{"record":{"id":"1fd0b1d9b79cc909","repo":"pbakaus/impeccable","slug":"surface-brief-requires-a-concrete-project-relative-1fd0b1","errorCode":null,"errorMessage":"surface brief requires a concrete project-relative primary target or URL","messagePattern":"surface brief requires a concrete project-relative primary target or URL","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"skill/scripts/lib/surface-briefs.mjs","lineNumber":134,"sourceCode":"  const exactPath = surfaceBriefPathForTarget(normalized, { projectRoot });\n  const exact = briefs.find((brief) => brief.path === exactPath && (!brief.targets.length || brief.targets.includes(normalized)));\n  if (exact) return { brief: exact, candidates: briefs, reason: 'slug' };\n  const mapped = briefs.filter((brief) => brief.targets.includes(normalized));\n  return {\n    brief: mapped.length === 1 ? mapped[0] : null,\n    candidates: mapped.length > 1 ? mapped : briefs,\n    reason: mapped.length === 1 ? 'mapping' : mapped.length > 1 ? 'ambiguous-target' : 'not-found',\n  };\n}\n\nexport function writeSurfaceBrief({\n  projectRoot = process.cwd(),\n  primaryTarget,\n  relatedTargets = [],\n  body,\n}) {\n  const normalizedPrimary = normalizeSurfaceTarget(primaryTarget, { projectRoot });\n  if (!normalizedPrimary) throw new Error('surface brief requires a concrete project-relative primary target or URL');\n  const normalizedRelated = [...new Set(relatedTargets\n    .map((target) => normalizeSurfaceTarget(target, { projectRoot }))\n    .filter((target) => target && target !== normalizedPrimary))];\n  const slug = slugFromTarget(normalizedPrimary, { cwd: projectRoot });\n  const filePath = surfaceBriefPathForTarget(normalizedPrimary, { projectRoot });\n  fs.mkdirSync(path.dirname(filePath), { recursive: true });\n  const frontmatter = [\n    '---',\n    `version: ${SURFACE_BRIEF_VERSION}`,\n    `slug: ${JSON.stringify(slug)}`,\n    `primary_target: ${JSON.stringify(normalizedPrimary)}`,\n    `related_targets: ${JSON.stringify(normalizedRelated)}`,\n    '---',\n  ].join('\\n');\n  fs.writeFileSync(filePath, `${frontmatter}\\n\\n${String(body || '').trim()}\\n`, 'utf-8');\n  return filePath;\n}\n","sourceCodeStart":116,"sourceCodeEnd":152,"githubUrl":"https://github.com/pbakaus/impeccable/blob/d14711ae3d1a1dd62dee61a358d27f107c51ccd0/skill/scripts/lib/surface-briefs.mjs#L116-L152","documentation":"Thrown by writeSurfaceBrief() in skill/scripts/lib/surface-briefs.mjs when normalizeSurfaceTarget() returns null for the primaryTarget. normalizeSurfaceTarget accepts an http(s) URL, a `route:/path`, a lone `/`, or a project-relative path that does not escape the project root (no `..`, stays inside projectRoot). Anything else — absolute path outside the project, a `..` traversal, an unparseable URL, or a non-string — yields null and this error.","triggerScenarios":"Calling writeSurfaceBrief({ primaryTarget }) with a value like `/etc/passwd` (absolute, outside project, existing file so not treated as a route), `../outside`, a malformed URL (`http://[broken`), an empty string, or a non-string. Also a bare string that resolves outside projectRoot.","commonSituations":"Passing an absolute filesystem path instead of a project-relative one; passing a URL with a typo; forgetting to set projectRoot so the relative-path check uses the wrong base; feeding user input unchecked.","solutions":["Pass a project-relative path (e.g. `src/pages/home.astro`), an `http(s)://` URL, or a `route:/path` for an in-app route.","If you meant a route, prefix it with `route:` or pass it starting with `/` that does not resolve to an existing outside file.","Confirm projectRoot is the repo root so the relative-path normalization does not misclassify the target."],"exampleFix":"// before\nwriteSurfaceBrief({ primaryTarget: '/Users/me/site/src/pages/home.astro' });\n// after\nwriteSurfaceBrief({ projectRoot, primaryTarget: 'src/pages/home.astro' });","handlingStrategy":"validation","validationCode":"import { normalizeSurfaceTarget } from './surface-briefs.mjs';\nconst normalized = normalizeSurfaceTarget(primaryTarget, { projectRoot });\nif (!normalized) {\n  throw new Error('primaryTarget must be a project-relative path, http(s) URL, or route:/path');\n}","typeGuard":"function isUsableSurfaceTarget(target, projectRoot) {\n  return normalizeSurfaceTarget(target, { projectRoot }) !== null;\n}","tryCatchPattern":null,"preventionTips":["Pass project-relative paths, not absolute filesystem paths.","Prefix in-app routes with route: or a leading /.","Always pass projectRoot explicitly."],"tags":["surface-brief","validation","paths","design-flow"],"backgroundTag":null,"analyzedSha":"d14711ae3d1a1dd62dee61a358d27f107c51ccd0","analyzedAt":"2026-08-13T00:52:25.771Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}