@vaubaan/harness 2.0.0 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/README.md +25 -21
  2. package/dist/cli/index.js +543 -76
  3. package/dist/cli/index.js.map +1 -1
  4. package/dist/commands/doc-audit.cmd.md +1 -1
  5. package/dist/commands/handbook.cmd.md +4 -3
  6. package/dist/commands/journey.cmd.md +22 -0
  7. package/dist/commands/story.cmd.md +24 -0
  8. package/dist/commands/test-plan.cmd.md +4 -4
  9. package/dist/index.d.ts +2 -2
  10. package/dist/index.js +304 -56
  11. package/dist/index.js.map +1 -1
  12. package/dist/init.d.ts +2 -3
  13. package/dist/init.js +301 -53
  14. package/dist/init.js.map +1 -1
  15. package/dist/linters/index.js +523 -56
  16. package/dist/linters/index.js.map +1 -1
  17. package/dist/parser/index.d.ts +110 -1
  18. package/dist/parser/index.js +229 -2
  19. package/dist/parser/index.js.map +1 -1
  20. package/dist/{render-C-FWmUfX.d.ts → render-BzrBb_l4.d.ts} +3 -1
  21. package/dist/render.d.ts +1 -1
  22. package/dist/render.js +89 -10
  23. package/dist/render.js.map +1 -1
  24. package/dist/skills/decision-record-writer.skill.md +93 -130
  25. package/dist/skills/doc-audit.skill.md +37 -7
  26. package/dist/skills/drift-detector.skill.md +41 -11
  27. package/dist/skills/handbook-writer.skill.md +71 -159
  28. package/dist/skills/journey-writer.skill.md +159 -0
  29. package/dist/skills/spec-writer.skill.md +25 -3
  30. package/dist/skills/test-plan-writer.skill.md +46 -53
  31. package/dist/skills/workflow-writer.skill.md +20 -3
  32. package/dist/templates/decision.md.tmpl +20 -47
  33. package/dist/templates/e2e-tests.md.tmpl +16 -45
  34. package/dist/templates/handbook.md.tmpl +20 -38
  35. package/dist/templates/integration-tests.md.tmpl +16 -34
  36. package/dist/templates/journey.md.tmpl +45 -0
  37. package/package.json +1 -1
@@ -1 +1 @@
1
- {"version":3,"sources":["../src/renderers/common.ts","../src/types.ts","../src/renderers/claude-code.ts","../src/renderers/codex-cli.ts","../src/renderers/opencode.ts","../src/renderers/index.ts","../src/render.ts"],"sourcesContent":["import { stringify as yamlStringify } from \"yaml\";\nimport type { Cmd } from \"../parser/cmd.js\";\nimport type { Skill } from \"../parser/skill.js\";\nimport {\n CAPABILITIES_MATRIX,\n type Capability,\n DEGRADED_CAPABILITIES,\n type Engine,\n type RenderedFile,\n} from \"../types.js\";\n\nexport interface UmbrellaExtras {\n availableSkills: ReadonlyArray<Skill>;\n availableCommands: ReadonlyArray<Cmd>;\n hasProjectSkills?: boolean;\n hasQualityDoc?: boolean;\n}\n\nexport interface RenderResult {\n files: RenderedFile[];\n warnings: string[];\n}\n\nexport interface Renderer {\n readonly engine: Engine;\n renderSkill(skill: Skill): RenderResult;\n renderCmd(cmd: Cmd): RenderResult;\n}\n\nexport interface CapabilityCheck {\n blockingWarnings: string[];\n degradedWarnings: string[];\n}\n\nexport function checkSkillCapabilities(skill: Skill, engine: Engine): CapabilityCheck {\n const blockingWarnings: string[] = [];\n const degradedWarnings: string[] = [];\n const supported = CAPABILITIES_MATRIX[engine];\n const degraded = DEGRADED_CAPABILITIES[engine] ?? [];\n if (!skill.meta.requires) return { blockingWarnings, degradedWarnings };\n for (const cap of skill.meta.requires) {\n if (!supported.includes(cap as Capability)) {\n blockingWarnings.push(\n `skill \"${skill.meta.id}\" requires \"${cap}\" not supported by \"${engine}\" — skipped`,\n );\n } else if (degraded.includes(cap as Capability)) {\n degradedWarnings.push(\n `skill \"${skill.meta.id}\" requires \"${cap}\" — supported by \"${engine}\" with degradation`,\n );\n }\n }\n return { blockingWarnings, degradedWarnings };\n}\n\nexport function isSkillEngineAllowed(skill: Skill, engine: Engine): boolean {\n if (!skill.meta.engines) return true;\n return skill.meta.engines.includes(engine);\n}\n\nexport function yamlFrontmatter(data: Record<string, unknown>): string {\n const rendered = yamlStringify(data, { lineWidth: 0 }).trimEnd();\n return `---\\n${rendered}\\n---\\n`;\n}\n\nexport function frontmatterDataForSkill(skill: Skill): Record<string, unknown> {\n // Agent Skills spec (agentskills.io): `name` must match the directory name.\n const data: Record<string, unknown> = {\n name: skill.meta.id,\n description: skill.meta.description,\n };\n if (skill.meta.tags && skill.meta.tags.length > 0) data.tags = skill.meta.tags;\n return data;\n}\n\nexport function frontmatterDataForCmd(cmd: Cmd): Record<string, unknown> {\n const data: Record<string, unknown> = {\n id: cmd.meta.id,\n trigger: cmd.meta.trigger,\n description: cmd.meta.description,\n };\n if (cmd.meta.args && cmd.meta.args.length > 0) {\n data.args = cmd.meta.args.map((a) => {\n if (a.type === \"enum\") {\n return a.default !== undefined\n ? { name: a.name, type: a.type, values: a.values, default: a.default }\n : { name: a.name, type: a.type, values: a.values };\n }\n return a.default !== undefined\n ? { name: a.name, type: a.type, default: a.default }\n : { name: a.name, type: a.type };\n });\n }\n return data;\n}\n\n/**\n * The engine-neutral umbrella: the one working rule the harness imposes,\n * the project map, the checks, and the doc skills the engines expose.\n * Everything project-specific lives in `README.md` and `docs/`.\n */\nexport function buildUmbrellaBody(extras: UmbrellaExtras): string {\n const triggerBySkill = new Map(\n extras.availableCommands.map((c) => [c.meta.invokes_skill, c.meta.trigger]),\n );\n const skillLines = extras.availableSkills.map((s) => {\n const trigger = triggerBySkill.get(s.meta.id);\n const label = trigger ? `\\`${s.meta.id}\\` (\\`${trigger}\\`)` : `\\`${s.meta.id}\\``;\n return `- ${label} — ${s.meta.description.split(\"\\n\")[0]}`;\n });\n const sections: string[] = [\n \"# How we work\",\n \"\",\n \"This file describes **how to work in this project**. The **business context** (what the project does, how to run it, which subsystems it contains) lives in `README.md` and `docs/`. Read them first.\",\n \"\",\n \"## Project map\",\n \"\",\n \"- `README.md` — pitch, quick start, scripts. Entry point.\",\n \"- `docs/spec/<subsystem>.md` — *what* and *why* (tech-agnostic).\",\n \"- `docs/handbook/<feature>.md` — *how it actually works* today.\",\n \"- `docs/decisions/<slug>.md` — ADRs: structural choices and rejected alternatives.\",\n \"- `docs/tests/integration-tests.md` & `e2e-tests.md` — core scenarios.\",\n \"- `docs/workflow/coding-workflow.md` — CI, branches, PR, release. How this team works: follow it.\",\n ...(extras.hasProjectSkills\n ? [\"- `docs/skills/*.skill.md` — the project's domain skills.\"]\n : []),\n ...(extras.hasQualityDoc\n ? [\n \"- `docs/quality/code-quality.md` — the project's code-quality rules: mechanical checks, judgment rules, accepted deviations. Read it before writing or auditing code.\",\n ]\n : []),\n \"\",\n \"## Doc-first\",\n \"\",\n \"The order is: **understand the docs → fill the gaps → code → update the docs → commit**. If the docs are silent or stale on something you change, fill the gap upfront with the doc-skill writers — not downstream, not after the fact.\",\n \"\",\n \"- Missing spec for a subsystem you touch → **do not code**, report the gap.\",\n \"- Implicit structural decision in your changes → an ADR (`/decision`).\",\n \"- Changed feature behavior → update the matching handbook (`/handbook`).\",\n \"- Suspected code ↔ doc drift → `/drift` before moving on.\",\n \"\",\n \"## Checks\",\n \"\",\n \"Run `npx @vaubaan/harness lint` before you commit; CI runs the same linters on every pull request. Fix what it reports with the skill it suggests.\",\n \"\",\n \"The files the harness generates (`AGENTS.md`, `CLAUDE.md`, the `.claude/`, `.agents/` and `.opencode/` folders, `.harness-manifest.json`) are committed. Never edit them by hand: change their source in `docs/` or `.harness-overrides/`, run `npx @vaubaan/harness update .`, and commit the result. The linter fails when a generated file no longer matches its render.\",\n ];\n if (skillLines.length > 0) {\n sections.push(\"\", \"## Doc-skills\", \"\", skillLines.join(\"\\n\"));\n }\n return `${sections.join(\"\\n\")}\\n`;\n}\n","export const ENGINES = [\"claude-code\", \"codex-cli\", \"opencode\"] as const;\nexport type Engine = (typeof ENGINES)[number];\n\nexport const ENGINE_ROOT_DIR: Record<Engine, string> = {\n \"claude-code\": \".claude\",\n \"codex-cli\": \".codex\",\n opencode: \".opencode\",\n};\n\nexport const CAPABILITIES = [\"multi-step\", \"slash-command\", \"inline-exec\"] as const;\nexport type Capability = (typeof CAPABILITIES)[number];\n\nexport interface RenderedFile {\n path: string;\n content: string;\n}\n\nexport interface CapabilitiesMatrix {\n [engine: string]: ReadonlyArray<Capability>;\n}\n\nexport const CAPABILITIES_MATRIX: Record<Engine, ReadonlyArray<Capability>> = {\n \"claude-code\": [\"multi-step\", \"slash-command\", \"inline-exec\"],\n \"codex-cli\": [\"multi-step\", \"slash-command\", \"inline-exec\"],\n opencode: [\"multi-step\", \"slash-command\", \"inline-exec\"],\n};\n\nexport const DEGRADED_CAPABILITIES: Partial<Record<Engine, ReadonlyArray<Capability>>> = {\n \"codex-cli\": [\"multi-step\"],\n};\n\nexport function engineSupports(engine: Engine, capability: Capability): boolean {\n return CAPABILITIES_MATRIX[engine].includes(capability);\n}\n","import type { Cmd } from \"../parser/cmd.js\";\nimport type { Skill } from \"../parser/skill.js\";\nimport type { Engine } from \"../types.js\";\nimport {\n type RenderResult,\n type Renderer,\n checkSkillCapabilities,\n frontmatterDataForCmd,\n frontmatterDataForSkill,\n isSkillEngineAllowed,\n yamlFrontmatter,\n} from \"./common.js\";\n\nconst ENGINE: Engine = \"claude-code\";\nconst BASE = \".claude\";\n\nexport const claudeCodeRenderer: Renderer = {\n engine: ENGINE,\n renderSkill(skill: Skill): RenderResult {\n if (!isSkillEngineAllowed(skill, ENGINE)) {\n return {\n files: [],\n warnings: [`skill \"${skill.meta.id}\" excluded from engine \"${ENGINE}\"`],\n };\n }\n const check = checkSkillCapabilities(skill, ENGINE);\n if (check.blockingWarnings.length > 0) {\n return { files: [], warnings: check.blockingWarnings };\n }\n const content = `${yamlFrontmatter(frontmatterDataForSkill(skill))}\\n${skill.body}\\n`;\n return {\n files: [{ path: `${BASE}/skills/${skill.meta.id}/SKILL.md`, content }],\n warnings: check.degradedWarnings,\n };\n },\n renderCmd(cmd: Cmd): RenderResult {\n const content = `${yamlFrontmatter(frontmatterDataForCmd(cmd))}\\n${cmd.body}\\n`;\n return {\n files: [{ path: `${BASE}/commands/${cmd.meta.id}.md`, content }],\n warnings: [],\n };\n },\n};\n","import type { Cmd } from \"../parser/cmd.js\";\nimport type { Skill } from \"../parser/skill.js\";\nimport type { Engine } from \"../types.js\";\nimport {\n type RenderResult,\n type Renderer,\n checkSkillCapabilities,\n frontmatterDataForSkill,\n isSkillEngineAllowed,\n yamlFrontmatter,\n} from \"./common.js\";\n\nconst ENGINE: Engine = \"codex-cli\";\n// Codex discovers repo skills under `.agents/skills/` only — `.codex/skills/` is not scanned.\nconst SKILLS_BASE = \".agents/skills\";\n\nexport const codexCliRenderer: Renderer = {\n engine: ENGINE,\n renderSkill(skill: Skill): RenderResult {\n if (!isSkillEngineAllowed(skill, ENGINE)) {\n return {\n files: [],\n warnings: [`skill \"${skill.meta.id}\" excluded from engine \"${ENGINE}\"`],\n };\n }\n const check = checkSkillCapabilities(skill, ENGINE);\n if (check.blockingWarnings.length > 0) {\n return { files: [], warnings: check.blockingWarnings };\n }\n const content = `${yamlFrontmatter(frontmatterDataForSkill(skill))}\\n${skill.body}\\n`;\n return {\n files: [{ path: `${SKILLS_BASE}/${skill.meta.id}/SKILL.md`, content }],\n warnings: check.degradedWarnings,\n };\n },\n // Codex custom prompts are deprecated in favour of skills: nothing to render.\n renderCmd(_cmd: Cmd): RenderResult {\n return { files: [], warnings: [] };\n },\n};\n","import type { Cmd } from \"../parser/cmd.js\";\nimport type { Skill } from \"../parser/skill.js\";\nimport type { Engine } from \"../types.js\";\nimport {\n type RenderResult,\n type Renderer,\n checkSkillCapabilities,\n frontmatterDataForSkill,\n isSkillEngineAllowed,\n yamlFrontmatter,\n} from \"./common.js\";\n\nconst ENGINE: Engine = \"opencode\";\nconst BASE = \".opencode\";\n\nexport const opencodeRenderer: Renderer = {\n engine: ENGINE,\n renderSkill(skill: Skill): RenderResult {\n if (!isSkillEngineAllowed(skill, ENGINE)) {\n return {\n files: [],\n warnings: [`skill \"${skill.meta.id}\" excluded from engine \"${ENGINE}\"`],\n };\n }\n const check = checkSkillCapabilities(skill, ENGINE);\n if (check.blockingWarnings.length > 0) {\n return { files: [], warnings: check.blockingWarnings };\n }\n const content = `${yamlFrontmatter(frontmatterDataForSkill(skill))}\\n${skill.body}\\n`;\n return {\n files: [{ path: `${BASE}/skills/${skill.meta.id}/SKILL.md`, content }],\n warnings: check.degradedWarnings,\n };\n },\n renderCmd(cmd: Cmd): RenderResult {\n // OpenCode names the command after the file; only `description` is a known key.\n const content = `${yamlFrontmatter({ description: cmd.meta.description })}\\n${cmd.body}\\n`;\n return {\n files: [{ path: `${BASE}/commands/${cmd.meta.id}.md`, content }],\n warnings: [],\n };\n },\n};\n","import type { Engine } from \"../types.js\";\nimport { claudeCodeRenderer } from \"./claude-code.js\";\nimport { codexCliRenderer } from \"./codex-cli.js\";\nimport type { Renderer } from \"./common.js\";\nimport { opencodeRenderer } from \"./opencode.js\";\n\nexport const RENDERERS: Record<Engine, Renderer> = {\n \"claude-code\": claudeCodeRenderer,\n \"codex-cli\": codexCliRenderer,\n opencode: opencodeRenderer,\n};\n\nexport function getRenderer(engine: Engine): Renderer {\n return RENDERERS[engine];\n}\n\nexport type { Renderer, RenderResult } from \"./common.js\";\n","import type { Cmd } from \"./parser/cmd.js\";\nimport type { Skill } from \"./parser/skill.js\";\nimport { buildUmbrellaBody } from \"./renderers/common.js\";\nimport { getRenderer } from \"./renderers/index.js\";\nimport type { Engine, RenderedFile } from \"./types.js\";\n\nexport interface Harness {\n skills: ReadonlyArray<Skill>;\n cmds: ReadonlyArray<Cmd>;\n}\n\nexport interface HarnessOverrides {\n add?: Partial<Harness>;\n disable?: ReadonlyArray<string>;\n}\n\nexport interface RenderInput {\n harness: Harness;\n engines: ReadonlyArray<Engine>;\n overrides?: HarnessOverrides;\n projectSkills?: ReadonlyArray<Skill>;\n /** True when the target project ships `docs/quality/code-quality.md` (optional pillar). */\n hasQualityDoc?: boolean;\n}\n\nexport interface RenderOutput {\n files: RenderedFile[];\n warnings: string[];\n}\n\nexport class RenderError extends Error {\n constructor(message: string) {\n super(message);\n this.name = \"RenderError\";\n }\n}\n\nfunction mergeById<T extends { meta: { id: string } }>(\n stock: ReadonlyArray<T>,\n added: ReadonlyArray<T> | undefined,\n): T[] {\n const result = new Map<string, T>();\n for (const item of stock) result.set(item.meta.id, item);\n if (added) {\n for (const item of added) result.set(item.meta.id, item);\n }\n return Array.from(result.values());\n}\n\nfunction removeByIds<T extends { meta: { id: string } }>(\n items: ReadonlyArray<T>,\n disabled: ReadonlyArray<string>,\n): T[] {\n if (disabled.length === 0) return [...items];\n const disabledSet = new Set(disabled);\n return items.filter((item) => !disabledSet.has(item.meta.id));\n}\n\nexport function applyOverrides(harness: Harness, overrides: HarnessOverrides | undefined): Harness {\n const disabled = overrides?.disable ?? [];\n return {\n skills: removeByIds(mergeById(harness.skills, overrides?.add?.skills), disabled),\n cmds: removeByIds(mergeById(harness.cmds, overrides?.add?.cmds), disabled),\n };\n}\n\n// `@AGENTS.md` is Claude Code's import syntax: the umbrella is really loaded,\n// on every version and provider, and never read twice alongside native\n// AGENTS.md support (cf. ADR engine-native-layouts-1-0).\nconst CLAUDE_MD_STUB = \"@AGENTS.md\\n\";\n\n// OpenCode also scans `.claude/skills/` and `.agents/skills/`. It goes last so\n// its own copy of a skill is dropped when another rendered engine exposes it.\nfunction opencodeLast(engines: ReadonlyArray<Engine>): Engine[] {\n return [...engines].sort((a, b) => Number(a === \"opencode\") - Number(b === \"opencode\"));\n}\n\n/**\n * Pure transformation `(catalog, engines, overrides) → files`. The harness\n * ships no agent persona and no engine hook: only the doc skills, their\n * commands, and the engine-neutral umbrella\n * (docs/decisions/no-personas-no-code-judgment.md,\n * docs/decisions/lint-in-ci-and-pre-commit.md).\n */\nexport function render(input: RenderInput): RenderOutput {\n const { engines } = input;\n if (engines.length === 0) {\n throw new RenderError(\"at least one engine must be selected\");\n }\n const base: Harness = input.projectSkills?.length\n ? { ...input.harness, skills: mergeById(input.harness.skills, input.projectSkills) }\n : input.harness;\n const harness = applyOverrides(base, input.overrides);\n\n const files: RenderedFile[] = [];\n const warnings: string[] = [];\n\n // Track skills + commands successfully exposed on at least one engine,\n // for the engine-neutral umbrella's \"Doc-skills\" section.\n const exposedSkills = new Map<string, Skill>();\n const exposedCmds = new Map<string, Cmd>();\n\n for (const engine of opencodeLast(engines)) {\n const renderer = getRenderer(engine);\n\n const renderedSkillIds = new Set<string>();\n for (const skill of harness.skills) {\n const result = renderer.renderSkill(skill);\n warnings.push(...result.warnings);\n if (result.files.length > 0) {\n const alreadyVisible = engine === \"opencode\" && exposedSkills.has(skill.meta.id);\n if (!alreadyVisible) files.push(...result.files);\n renderedSkillIds.add(skill.meta.id);\n exposedSkills.set(skill.meta.id, skill);\n }\n }\n\n for (const cmd of harness.cmds) {\n if (!renderedSkillIds.has(cmd.meta.invokes_skill)) continue;\n const result = renderer.renderCmd(cmd);\n warnings.push(...result.warnings);\n if (result.files.length > 0) {\n files.push(...result.files);\n exposedCmds.set(cmd.meta.id, cmd);\n }\n }\n }\n\n // Engine-neutral umbrella at the root\n const umbrellaContent = buildUmbrellaBody({\n availableSkills: Array.from(exposedSkills.values()),\n availableCommands: Array.from(exposedCmds.values()),\n hasProjectSkills: (input.projectSkills?.length ?? 0) > 0,\n hasQualityDoc: input.hasQualityDoc === true,\n });\n files.push({ path: \"AGENTS.md\", content: umbrellaContent });\n\n // CLAUDE.md stub only if claude-code is enabled (Claude Code reads it historically)\n if (engines.includes(\"claude-code\")) {\n files.push({ path: \"CLAUDE.md\", content: CLAUDE_MD_STUB });\n }\n\n return { files, warnings };\n}\n"],"mappings":"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","names":["ENGINE","ENGINE","BASE"]}
1
+ {"version":3,"sources":["../src/parser/journey.ts","../src/parser/schemas.ts","../src/types.ts","../src/renderers/common.ts","../src/renderers/claude-code.ts","../src/renderers/codex-cli.ts","../src/renderers/opencode.ts","../src/renderers/index.ts","../src/renderers/journeys-index.ts","../src/render.ts"],"sourcesContent":["import { existsSync, readFileSync, readdirSync, statSync } from \"node:fs\";\nimport { basename, join } from \"node:path\";\nimport matter from \"gray-matter\";\nimport {\n JOURNEY_STATUSES,\n type JourneyFrontmatter,\n type JourneyStatus,\n Schemas,\n} from \"./schemas.js\";\n\n/** The optional journeys pillar (docs/spec/coding-agent-harness.md §9.1.3). */\nexport const JOURNEYS_DIR = \"docs/journeys\";\n/** The generated index of the pillar; never a journey. */\nexport const JOURNEYS_INDEX_PATH = `${JOURNEYS_DIR}/README.md`;\n\nexport const NODE_FIELDS = [\n \"status\",\n \"spec\",\n \"anchors\",\n \"acceptance\",\n \"requires\",\n \"creates\",\n] as const;\nexport type NodeField = (typeof NODE_FIELDS)[number];\n/** Fields only a leaf may carry. */\nexport const LEAF_FIELDS: ReadonlyArray<NodeField> = [\n \"anchors\",\n \"acceptance\",\n \"requires\",\n \"creates\",\n];\n\nexport interface JourneyError {\n line?: number;\n message: string;\n}\n\nexport interface JourneyNode {\n title: string;\n /** Heading depth minus one: `##` is level 1. */\n level: number;\n /** 1-based line of the heading in the file. */\n line: number;\n /** Index of the parent node in `nodes`, absent for a level-1 node. */\n parent?: number;\n isLeaf: boolean;\n /** Line of each known field the node declares. */\n fieldLines: Partial<Record<NodeField, number>>;\n status?: JourneyStatus;\n spec?: string;\n anchors: string[];\n acceptance: string[];\n requires: string[];\n creates: string[];\n unknownFields: Array<{ key: string; line: number }>;\n /** Nearest `status:` up the tree, else the file status. */\n effectiveStatus?: JourneyStatus;\n}\n\nexport interface JourneyParse {\n meta?: JourneyFrontmatter;\n title: string;\n story?: string;\n nodes: JourneyNode[];\n errors: JourneyError[];\n}\n\nexport interface ParsedJourney extends JourneyParse {\n /** Path from the repo root, e.g. `docs/journeys/harness-a-project.md`. */\n path: string;\n /** File name, e.g. `harness-a-project.md`. */\n file: string;\n}\n\n/** Stands for a line of fenced code: not blank, not a field, not a heading. */\nconst MASKED_LINE = \"\\u0000\";\nconst FENCE_RE = /^ {0,3}(`{3,}|~{3,})/;\nconst HEADING_RE = /^(#{1,6})[ \\t]+(.+?)(?:[ \\t]+#+)?[ \\t]*$/;\nconst FIELD_RE = /^([a-z][a-z-]*):\\s*(.*)$/;\nconst LIST_ITEM_RE = /^\\s*-\\s+(.*)$/;\n\n/** Replaces every line of fenced code (fences included), keeping line numbers. */\nexport function maskFencedCode(lines: ReadonlyArray<string>): string[] {\n let fence: string | undefined;\n return lines.map((line) => {\n const m = FENCE_RE.exec(line);\n if (fence !== undefined) {\n if (m?.[1] && m[1][0] === fence[0] && m[1].length >= fence.length) fence = undefined;\n return MASKED_LINE;\n }\n if (m?.[1]) {\n fence = m[1];\n return MASKED_LINE;\n }\n return line;\n });\n}\n\nexport function parseHeading(line: string): { depth: number; title: string } | undefined {\n const m = HEADING_RE.exec(line);\n if (!m?.[1] || !m[2]) return undefined;\n return { depth: m[1].length, title: m[2] };\n}\n\nfunction splitList(value: string): string[] {\n return value\n .split(\",\")\n .map((v) => v.trim())\n .filter(Boolean);\n}\n\n/** Index of the first body line, after the frontmatter block when there is one. */\nfunction bodyStart(lines: ReadonlyArray<string>): number {\n if (lines[0]?.trim() !== \"---\") return 0;\n for (let i = 1; i < lines.length; i++) {\n const l = lines[i]?.trim();\n if (l === \"---\" || l === \"...\") return i + 1;\n }\n return lines.length;\n}\n\nfunction parseFrontmatter(text: string, errors: JourneyError[]): JourneyFrontmatter | undefined {\n let data: Record<string, unknown>;\n try {\n data = matter(text).data;\n } catch (error) {\n const reason = error instanceof Error ? error.message.split(\"\\n\")[0] : String(error);\n errors.push({ line: 1, message: `invalid frontmatter YAML: ${reason}` });\n return undefined;\n }\n const result = Schemas.Journey.safeParse(data);\n if (result.success) return result.data;\n for (const issue of result.error.issues) {\n const where = issue.path.length ? ` \\`${issue.path.join(\".\")}\\`` : \"\";\n errors.push({ line: 1, message: `frontmatter${where}: ${issue.message}` });\n }\n return undefined;\n}\n\nfunction newNode(title: string, level: number, line: number): JourneyNode {\n return {\n title,\n level,\n line,\n isLeaf: true,\n fieldLines: {},\n anchors: [],\n acceptance: [],\n requires: [],\n creates: [],\n unknownFields: [],\n };\n}\n\n/** Reads the field block directly under a heading, up to its first non-field line. */\nfunction parseFields(\n node: JourneyNode,\n lines: ReadonlyArray<string>,\n from: number,\n to: number,\n errors: JourneyError[],\n): void {\n let lastKey: string | undefined;\n for (let i = from; i < to; i++) {\n const line = lines[i] ?? \"\";\n if (line.trim() === \"\") continue;\n const lineNo = i + 1;\n const field = FIELD_RE.exec(line.trimEnd());\n if (field?.[1] !== undefined) {\n const key = field[1];\n const value = (field[2] ?? \"\").trim();\n lastKey = key;\n if (!(NODE_FIELDS as ReadonlyArray<string>).includes(key)) {\n node.unknownFields.push({ key, line: lineNo });\n continue;\n }\n const known = key as NodeField;\n node.fieldLines[known] = lineNo;\n if (known === \"status\") {\n if ((JOURNEY_STATUSES as ReadonlyArray<string>).includes(value)) {\n node.status = value as JourneyStatus;\n } else {\n errors.push({\n line: lineNo,\n message: `invalid status \\`${value}\\` (expected ${JOURNEY_STATUSES.join(\" | \")})`,\n });\n }\n } else if (known === \"spec\") {\n node.spec = value;\n } else if (known === \"acceptance\") {\n if (value) node.acceptance.push(value);\n } else {\n node[known] = splitList(value);\n }\n continue;\n }\n const item = LIST_ITEM_RE.exec(line);\n if (lastKey === \"acceptance\" && item) {\n const text = (item[1] ?? \"\").trim();\n if (text) node.acceptance.push(text);\n continue;\n }\n return;\n }\n}\n\n/**\n * Parses one journey (docs/spec/coding-agent-harness.md §9.1.3). Never\n * throws: frontmatter and node problems are collected in `errors` and the\n * nodes are parsed regardless, so a linter reports everything at once.\n */\nexport function parseJourney(relPath: string, text: string): JourneyParse {\n const errors: JourneyError[] = [];\n const meta = parseFrontmatter(text, errors);\n const lines = maskFencedCode(text.split(/\\r?\\n/));\n const start = bodyStart(lines);\n\n const headings: Array<{ index: number; depth: number; title: string }> = [];\n for (let i = start; i < lines.length; i++) {\n const h = parseHeading(lines[i] ?? \"\");\n if (h) headings.push({ index: i, ...h });\n }\n\n const h1 = headings.find((h) => h.depth === 1);\n let story: string | undefined;\n if (h1) {\n const paragraph: string[] = [];\n for (let i = h1.index + 1; i < lines.length; i++) {\n const line = lines[i] ?? \"\";\n if (line.trim() === \"\") {\n if (paragraph.length) break;\n continue;\n }\n if (line === MASKED_LINE || parseHeading(line)) break;\n paragraph.push(line.trim());\n }\n if (paragraph.length) story = paragraph.join(\" \");\n }\n\n const nodes: JourneyNode[] = [];\n const stack: number[] = [];\n for (const [k, h] of headings.entries()) {\n if (h.depth < 2) continue;\n const node = newNode(h.title, h.depth - 1, h.index + 1);\n while (stack.length) {\n const top = nodes[stack[stack.length - 1] as number];\n if (top && top.level < node.level) break;\n stack.pop();\n }\n const parentIndex = stack[stack.length - 1];\n if (parentIndex !== undefined) {\n node.parent = parentIndex;\n const parent = nodes[parentIndex];\n if (parent) parent.isLeaf = false;\n }\n const next = headings[k + 1];\n parseFields(node, lines, h.index + 1, next ? next.index : lines.length, errors);\n const inherited =\n parentIndex !== undefined ? nodes[parentIndex]?.effectiveStatus : meta?.status;\n node.effectiveStatus = node.status ?? inherited;\n stack.push(nodes.length);\n nodes.push(node);\n }\n\n const title = meta?.title ?? h1?.title ?? basename(relPath, \".md\");\n return { ...(meta ? { meta } : {}), title, ...(story ? { story } : {}), nodes, errors };\n}\n\n/** Journey files: `docs/journeys/*.md` minus the generated index, sorted by file name. */\nexport function listJourneyFiles(targetDir: string): string[] {\n const dir = join(targetDir, JOURNEYS_DIR);\n if (!existsSync(dir) || !statSync(dir).isDirectory()) return [];\n return readdirSync(dir)\n .filter((f) => f.endsWith(\".md\") && f !== \"README.md\")\n .filter((f) => statSync(join(dir, f)).isFile())\n .sort();\n}\n\n/** Parses every journey without throwing; linters read their `errors`. */\nexport function readJourneys(targetDir: string): ParsedJourney[] {\n return listJourneyFiles(targetDir).map((file) => {\n const path = `${JOURNEYS_DIR}/${file}`;\n const text = readFileSync(join(targetDir, path), \"utf8\");\n return { path, file, ...parseJourney(path, text) };\n });\n}\n\n/**\n * The journeys the render needs. A journey that does not parse fails the\n * render, like an invalid project skill: `init`, `update` and\n * `lint:generated-fresh` report it.\n */\nexport function loadJourneys(targetDir: string): ParsedJourney[] {\n const journeys = readJourneys(targetDir);\n const problems = journeys.flatMap((j) =>\n j.errors.map((e) => ` - ${j.path}${e.line !== undefined ? `:${e.line}` : \"\"}: ${e.message}`),\n );\n if (problems.length) {\n throw new Error(\n `invalid journeys (run \\`npx @vaubaan/harness lint --pillar journeys\\`):\\n${problems.join(\"\\n\")}`,\n );\n }\n return journeys;\n}\n","import { z } from \"zod\";\nimport { CAPABILITIES, ENGINES } from \"../types.js\";\n\nconst IdSchema = z\n .string()\n .min(1)\n .regex(/^[a-z][a-z0-9-]*$/, \"id must be kebab-case (lowercase + digits + hyphens)\");\n\nconst SkillFrontmatterSchema = z\n .object({\n id: IdSchema,\n description: z.string().min(1),\n engines: z.array(z.enum(ENGINES)).min(1).optional(),\n requires: z.array(z.enum(CAPABILITIES)).optional(),\n tags: z.array(z.string()).optional(),\n })\n .strict();\n\nexport type SkillFrontmatter = z.infer<typeof SkillFrontmatterSchema>;\n\nconst CmdArgEnumSchema = z\n .object({\n name: z.string().min(1),\n type: z.literal(\"enum\"),\n values: z.array(z.string()).min(1),\n default: z.string().optional(),\n })\n .strict();\n\nconst CmdArgStringSchema = z\n .object({\n name: z.string().min(1),\n type: z.literal(\"string\"),\n default: z.string().optional(),\n })\n .strict();\n\nconst CmdArgSchema = z.discriminatedUnion(\"type\", [CmdArgEnumSchema, CmdArgStringSchema]);\n\nexport type CmdArg = z.infer<typeof CmdArgSchema>;\n\nconst CmdFrontmatterSchema = z\n .object({\n id: IdSchema,\n trigger: z.string().regex(/^\\/[a-z][a-z0-9-]*$/, \"trigger must be /kebab-case\"),\n invokes_skill: IdSchema,\n args: z.array(CmdArgSchema).optional(),\n description: z.string().min(1),\n })\n .strict();\n\nexport type CmdFrontmatter = z.infer<typeof CmdFrontmatterSchema>;\n\nexport const JOURNEY_STATUSES = [\"proposed\", \"implemented\", \"deprecated\"] as const;\nexport type JourneyStatus = (typeof JOURNEY_STATUSES)[number];\n\n// gray-matter parses a bare YAML date (`2026-11-09`) into a Date object.\nconst JourneyFrontmatterSchema = z\n .object({\n title: z.string().min(1),\n status: z.enum(JOURNEY_STATUSES),\n actors: z.array(z.string().min(1)).min(1),\n spec: z.union([z.string().min(1), z.array(z.string().min(1)).min(1)]),\n last_reviewed: z.union([z.date(), z.string().min(1)]),\n })\n .strict();\n\nexport type JourneyFrontmatter = z.infer<typeof JourneyFrontmatterSchema>;\n\nexport const Schemas = {\n Skill: SkillFrontmatterSchema,\n Cmd: CmdFrontmatterSchema,\n Journey: JourneyFrontmatterSchema,\n} as const;\n\nexport class ParseError extends Error {\n constructor(\n public readonly file: string,\n public readonly issues: z.ZodIssue[],\n ) {\n const messages = issues\n .map((i) => ` - ${i.path.join(\".\") || \"<root>\"}: ${i.message}`)\n .join(\"\\n\");\n super(`Frontmatter validation failed for ${file}:\\n${messages}`);\n this.name = \"ParseError\";\n }\n}\n","export const ENGINES = [\"claude-code\", \"codex-cli\", \"opencode\"] as const;\nexport type Engine = (typeof ENGINES)[number];\n\nexport const ENGINE_ROOT_DIR: Record<Engine, string> = {\n \"claude-code\": \".claude\",\n \"codex-cli\": \".codex\",\n opencode: \".opencode\",\n};\n\nexport const CAPABILITIES = [\"multi-step\", \"slash-command\", \"inline-exec\"] as const;\nexport type Capability = (typeof CAPABILITIES)[number];\n\nexport interface RenderedFile {\n path: string;\n content: string;\n}\n\nexport interface CapabilitiesMatrix {\n [engine: string]: ReadonlyArray<Capability>;\n}\n\nexport const CAPABILITIES_MATRIX: Record<Engine, ReadonlyArray<Capability>> = {\n \"claude-code\": [\"multi-step\", \"slash-command\", \"inline-exec\"],\n \"codex-cli\": [\"multi-step\", \"slash-command\", \"inline-exec\"],\n opencode: [\"multi-step\", \"slash-command\", \"inline-exec\"],\n};\n\nexport const DEGRADED_CAPABILITIES: Partial<Record<Engine, ReadonlyArray<Capability>>> = {\n \"codex-cli\": [\"multi-step\"],\n};\n\nexport function engineSupports(engine: Engine, capability: Capability): boolean {\n return CAPABILITIES_MATRIX[engine].includes(capability);\n}\n","import { stringify as yamlStringify } from \"yaml\";\nimport type { Cmd } from \"../parser/cmd.js\";\nimport type { Skill } from \"../parser/skill.js\";\nimport {\n CAPABILITIES_MATRIX,\n type Capability,\n DEGRADED_CAPABILITIES,\n type Engine,\n type RenderedFile,\n} from \"../types.js\";\n\nexport interface UmbrellaExtras {\n availableSkills: ReadonlyArray<Skill>;\n availableCommands: ReadonlyArray<Cmd>;\n hasProjectSkills?: boolean;\n hasQualityDoc?: boolean;\n hasJourneys?: boolean;\n}\n\nexport interface RenderResult {\n files: RenderedFile[];\n warnings: string[];\n}\n\nexport interface Renderer {\n readonly engine: Engine;\n renderSkill(skill: Skill): RenderResult;\n renderCmd(cmd: Cmd): RenderResult;\n}\n\nexport interface CapabilityCheck {\n blockingWarnings: string[];\n degradedWarnings: string[];\n}\n\nexport function checkSkillCapabilities(skill: Skill, engine: Engine): CapabilityCheck {\n const blockingWarnings: string[] = [];\n const degradedWarnings: string[] = [];\n const supported = CAPABILITIES_MATRIX[engine];\n const degraded = DEGRADED_CAPABILITIES[engine] ?? [];\n if (!skill.meta.requires) return { blockingWarnings, degradedWarnings };\n for (const cap of skill.meta.requires) {\n if (!supported.includes(cap as Capability)) {\n blockingWarnings.push(\n `skill \"${skill.meta.id}\" requires \"${cap}\" not supported by \"${engine}\" — skipped`,\n );\n } else if (degraded.includes(cap as Capability)) {\n degradedWarnings.push(\n `skill \"${skill.meta.id}\" requires \"${cap}\" — supported by \"${engine}\" with degradation`,\n );\n }\n }\n return { blockingWarnings, degradedWarnings };\n}\n\nexport function isSkillEngineAllowed(skill: Skill, engine: Engine): boolean {\n if (!skill.meta.engines) return true;\n return skill.meta.engines.includes(engine);\n}\n\nexport function yamlFrontmatter(data: Record<string, unknown>): string {\n const rendered = yamlStringify(data, { lineWidth: 0 }).trimEnd();\n return `---\\n${rendered}\\n---\\n`;\n}\n\nexport function frontmatterDataForSkill(skill: Skill): Record<string, unknown> {\n // Agent Skills spec (agentskills.io): `name` must match the directory name.\n const data: Record<string, unknown> = {\n name: skill.meta.id,\n description: skill.meta.description,\n };\n if (skill.meta.tags && skill.meta.tags.length > 0) data.tags = skill.meta.tags;\n return data;\n}\n\nexport function frontmatterDataForCmd(cmd: Cmd): Record<string, unknown> {\n const data: Record<string, unknown> = {\n id: cmd.meta.id,\n trigger: cmd.meta.trigger,\n description: cmd.meta.description,\n };\n if (cmd.meta.args && cmd.meta.args.length > 0) {\n data.args = cmd.meta.args.map((a) => {\n if (a.type === \"enum\") {\n return a.default !== undefined\n ? { name: a.name, type: a.type, values: a.values, default: a.default }\n : { name: a.name, type: a.type, values: a.values };\n }\n return a.default !== undefined\n ? { name: a.name, type: a.type, default: a.default }\n : { name: a.name, type: a.type };\n });\n }\n return data;\n}\n\n/**\n * The engine-neutral umbrella: the one working rule the harness imposes,\n * the project map, the checks, and the doc skills the engines expose.\n * Everything project-specific lives in `README.md` and `docs/`.\n */\nexport function buildUmbrellaBody(extras: UmbrellaExtras): string {\n // One skill may be invoked by several commands (`/journey`, `/story`):\n // list every trigger, in command order.\n const triggersBySkill = new Map<string, string[]>();\n for (const c of extras.availableCommands) {\n const triggers = triggersBySkill.get(c.meta.invokes_skill) ?? [];\n triggers.push(c.meta.trigger);\n triggersBySkill.set(c.meta.invokes_skill, triggers);\n }\n const skillLines = extras.availableSkills.map((s) => {\n const triggers = triggersBySkill.get(s.meta.id) ?? [];\n const label =\n triggers.length > 0\n ? `\\`${s.meta.id}\\` (${triggers.map((t) => `\\`${t}\\``).join(\", \")})`\n : `\\`${s.meta.id}\\``;\n return `- ${label} — ${s.meta.description.split(\"\\n\")[0]}`;\n });\n const sections: string[] = [\n \"# How we work\",\n \"\",\n \"This file describes **how to work in this project**. The **business context** (what the project does, how to run it, which subsystems it contains) lives in `README.md` and `docs/`. Read them first.\",\n \"\",\n \"## Project map\",\n \"\",\n \"- `README.md` — pitch, quick start, scripts. Entry point.\",\n \"- `docs/spec/<subsystem>.md` — *what* and *why* (tech-agnostic).\",\n \"- `docs/handbook/<feature>.md` — what the code does not say: entry points, traps, settings outside the repo, manual procedures.\",\n \"- `docs/decisions/<slug>.md` — ADRs: structural choices and rejected alternatives.\",\n \"- `docs/tests/integration-tests.md` & `e2e-tests.md` — test scope, stack, conventions, known gaps.\",\n \"- `docs/workflow/coding-workflow.md` — CI, branches, PR, release. How this team works: follow it.\",\n ...(extras.hasProjectSkills\n ? [\"- `docs/skills/*.skill.md` — the project's domain skills.\"]\n : []),\n ...(extras.hasQualityDoc\n ? [\n \"- `docs/quality/code-quality.md` — the project's code-quality rules: mechanical checks, judgment rules, accepted deviations. Read it before writing or auditing code.\",\n ]\n : []),\n ...(extras.hasJourneys\n ? [\n \"- `docs/journeys/<journey>.md` — user intentions and journeys, anchored to the code. `docs/journeys/README.md` is the generated index.\",\n ]\n : []),\n \"\",\n \"## Doc-first\",\n \"\",\n \"The order is: **understand the docs → fill the gaps → code → update the docs → commit**. If the docs are silent or stale on something you change, fill the gap upfront with the doc-skill writers — not downstream, not after the fact.\",\n \"\",\n ...(extras.hasJourneys\n ? [\n \"- Visible change of behavior → a `proposed` leaf first (`/story <intent>`), never the code first.\",\n ]\n : []),\n \"- Missing spec for a subsystem you touch → **do not code**, report the gap.\",\n \"- Implicit structural decision in your changes → an ADR (`/decision`).\",\n \"- Changed feature behavior → update the matching handbook (`/handbook`).\",\n \"- Suspected code ↔ doc drift → `/drift` before moving on.\",\n \"\",\n \"## Checks\",\n \"\",\n \"Run `npx @vaubaan/harness lint` before you commit; CI runs the same linters on every pull request. Fix what it reports with the skill it suggests.\",\n \"\",\n \"The files the harness generates (`AGENTS.md`, `CLAUDE.md`, the `.claude/`, `.agents/` and `.opencode/` folders, `.harness-manifest.json`) are committed. Never edit them by hand: change their source in `docs/` or `.harness-overrides/`, run `npx @vaubaan/harness update .`, and commit the result. The linter fails when a generated file no longer matches its render.\",\n ];\n if (skillLines.length > 0) {\n sections.push(\"\", \"## Doc-skills\", \"\", skillLines.join(\"\\n\"));\n }\n return `${sections.join(\"\\n\")}\\n`;\n}\n","import type { Cmd } from \"../parser/cmd.js\";\nimport type { Skill } from \"../parser/skill.js\";\nimport type { Engine } from \"../types.js\";\nimport {\n type RenderResult,\n type Renderer,\n checkSkillCapabilities,\n frontmatterDataForCmd,\n frontmatterDataForSkill,\n isSkillEngineAllowed,\n yamlFrontmatter,\n} from \"./common.js\";\n\nconst ENGINE: Engine = \"claude-code\";\nconst BASE = \".claude\";\n\nexport const claudeCodeRenderer: Renderer = {\n engine: ENGINE,\n renderSkill(skill: Skill): RenderResult {\n if (!isSkillEngineAllowed(skill, ENGINE)) {\n return {\n files: [],\n warnings: [`skill \"${skill.meta.id}\" excluded from engine \"${ENGINE}\"`],\n };\n }\n const check = checkSkillCapabilities(skill, ENGINE);\n if (check.blockingWarnings.length > 0) {\n return { files: [], warnings: check.blockingWarnings };\n }\n const content = `${yamlFrontmatter(frontmatterDataForSkill(skill))}\\n${skill.body}\\n`;\n return {\n files: [{ path: `${BASE}/skills/${skill.meta.id}/SKILL.md`, content }],\n warnings: check.degradedWarnings,\n };\n },\n renderCmd(cmd: Cmd): RenderResult {\n const content = `${yamlFrontmatter(frontmatterDataForCmd(cmd))}\\n${cmd.body}\\n`;\n return {\n files: [{ path: `${BASE}/commands/${cmd.meta.id}.md`, content }],\n warnings: [],\n };\n },\n};\n","import type { Cmd } from \"../parser/cmd.js\";\nimport type { Skill } from \"../parser/skill.js\";\nimport type { Engine } from \"../types.js\";\nimport {\n type RenderResult,\n type Renderer,\n checkSkillCapabilities,\n frontmatterDataForSkill,\n isSkillEngineAllowed,\n yamlFrontmatter,\n} from \"./common.js\";\n\nconst ENGINE: Engine = \"codex-cli\";\n// Codex discovers repo skills under `.agents/skills/` only — `.codex/skills/` is not scanned.\nconst SKILLS_BASE = \".agents/skills\";\n\nexport const codexCliRenderer: Renderer = {\n engine: ENGINE,\n renderSkill(skill: Skill): RenderResult {\n if (!isSkillEngineAllowed(skill, ENGINE)) {\n return {\n files: [],\n warnings: [`skill \"${skill.meta.id}\" excluded from engine \"${ENGINE}\"`],\n };\n }\n const check = checkSkillCapabilities(skill, ENGINE);\n if (check.blockingWarnings.length > 0) {\n return { files: [], warnings: check.blockingWarnings };\n }\n const content = `${yamlFrontmatter(frontmatterDataForSkill(skill))}\\n${skill.body}\\n`;\n return {\n files: [{ path: `${SKILLS_BASE}/${skill.meta.id}/SKILL.md`, content }],\n warnings: check.degradedWarnings,\n };\n },\n // Codex custom prompts are deprecated in favour of skills: nothing to render.\n renderCmd(_cmd: Cmd): RenderResult {\n return { files: [], warnings: [] };\n },\n};\n","import type { Cmd } from \"../parser/cmd.js\";\nimport type { Skill } from \"../parser/skill.js\";\nimport type { Engine } from \"../types.js\";\nimport {\n type RenderResult,\n type Renderer,\n checkSkillCapabilities,\n frontmatterDataForSkill,\n isSkillEngineAllowed,\n yamlFrontmatter,\n} from \"./common.js\";\n\nconst ENGINE: Engine = \"opencode\";\nconst BASE = \".opencode\";\n\nexport const opencodeRenderer: Renderer = {\n engine: ENGINE,\n renderSkill(skill: Skill): RenderResult {\n if (!isSkillEngineAllowed(skill, ENGINE)) {\n return {\n files: [],\n warnings: [`skill \"${skill.meta.id}\" excluded from engine \"${ENGINE}\"`],\n };\n }\n const check = checkSkillCapabilities(skill, ENGINE);\n if (check.blockingWarnings.length > 0) {\n return { files: [], warnings: check.blockingWarnings };\n }\n const content = `${yamlFrontmatter(frontmatterDataForSkill(skill))}\\n${skill.body}\\n`;\n return {\n files: [{ path: `${BASE}/skills/${skill.meta.id}/SKILL.md`, content }],\n warnings: check.degradedWarnings,\n };\n },\n renderCmd(cmd: Cmd): RenderResult {\n // OpenCode names the command after the file; only `description` is a known key.\n const content = `${yamlFrontmatter({ description: cmd.meta.description })}\\n${cmd.body}\\n`;\n return {\n files: [{ path: `${BASE}/commands/${cmd.meta.id}.md`, content }],\n warnings: [],\n };\n },\n};\n","import type { Engine } from \"../types.js\";\nimport { claudeCodeRenderer } from \"./claude-code.js\";\nimport { codexCliRenderer } from \"./codex-cli.js\";\nimport type { Renderer } from \"./common.js\";\nimport { opencodeRenderer } from \"./opencode.js\";\n\nexport const RENDERERS: Record<Engine, Renderer> = {\n \"claude-code\": claudeCodeRenderer,\n \"codex-cli\": codexCliRenderer,\n opencode: opencodeRenderer,\n};\n\nexport function getRenderer(engine: Engine): Renderer {\n return RENDERERS[engine];\n}\n\nexport type { Renderer, RenderResult } from \"./common.js\";\n","import type { ParsedJourney } from \"../parser/journey.js\";\n\nconst INTRO =\n \"User intentions and journeys of this project, anchored to the code. Generated by `@vaubaan/harness` from `docs/journeys/*.md`: edit the journeys, not this file, then run `npx @vaubaan/harness update .`.\";\n\n/**\n * `docs/journeys/README.md`: every journey (sorted by file name) and its\n * whole tree, one line per node with its effective status, the actors on\n * the journey line (docs/spec/coding-agent-harness.md §9.1.3).\n */\nexport function buildJourneysIndex(journeys: ReadonlyArray<ParsedJourney>): string {\n const lines = [\"# Journeys\", \"\", INTRO, \"\"];\n const sorted = [...journeys].sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));\n for (const journey of sorted) {\n const status = journey.meta?.status ?? \"proposed\";\n const actors = journey.meta?.actors.join(\", \") ?? \"\";\n lines.push(`- [${journey.title}](./${journey.file}) — ${status} · ${actors}`);\n for (const node of journey.nodes) {\n lines.push(`${\" \".repeat(node.level)}- ${node.title} — ${node.effectiveStatus ?? status}`);\n }\n }\n return `${lines.join(\"\\n\")}\\n`;\n}\n","import type { Cmd } from \"./parser/cmd.js\";\nimport { JOURNEYS_INDEX_PATH, type ParsedJourney } from \"./parser/journey.js\";\nimport type { Skill } from \"./parser/skill.js\";\nimport { buildUmbrellaBody } from \"./renderers/common.js\";\nimport { getRenderer } from \"./renderers/index.js\";\nimport { buildJourneysIndex } from \"./renderers/journeys-index.js\";\nimport type { Engine, RenderedFile } from \"./types.js\";\n\nexport interface Harness {\n skills: ReadonlyArray<Skill>;\n cmds: ReadonlyArray<Cmd>;\n}\n\nexport interface HarnessOverrides {\n add?: Partial<Harness>;\n disable?: ReadonlyArray<string>;\n}\n\nexport interface RenderInput {\n harness: Harness;\n engines: ReadonlyArray<Engine>;\n overrides?: HarnessOverrides;\n projectSkills?: ReadonlyArray<Skill>;\n /** True when the target project ships `docs/quality/code-quality.md` (optional pillar). */\n hasQualityDoc?: boolean;\n /** The project's parsed `docs/journeys/*.md` (optional pillar); renders their index. */\n journeys?: ReadonlyArray<ParsedJourney>;\n}\n\nexport interface RenderOutput {\n files: RenderedFile[];\n warnings: string[];\n}\n\nexport class RenderError extends Error {\n constructor(message: string) {\n super(message);\n this.name = \"RenderError\";\n }\n}\n\nfunction mergeById<T extends { meta: { id: string } }>(\n stock: ReadonlyArray<T>,\n added: ReadonlyArray<T> | undefined,\n): T[] {\n const result = new Map<string, T>();\n for (const item of stock) result.set(item.meta.id, item);\n if (added) {\n for (const item of added) result.set(item.meta.id, item);\n }\n return Array.from(result.values());\n}\n\nfunction removeByIds<T extends { meta: { id: string } }>(\n items: ReadonlyArray<T>,\n disabled: ReadonlyArray<string>,\n): T[] {\n if (disabled.length === 0) return [...items];\n const disabledSet = new Set(disabled);\n return items.filter((item) => !disabledSet.has(item.meta.id));\n}\n\nexport function applyOverrides(harness: Harness, overrides: HarnessOverrides | undefined): Harness {\n const disabled = overrides?.disable ?? [];\n return {\n skills: removeByIds(mergeById(harness.skills, overrides?.add?.skills), disabled),\n cmds: removeByIds(mergeById(harness.cmds, overrides?.add?.cmds), disabled),\n };\n}\n\n// `@AGENTS.md` is Claude Code's import syntax: the umbrella is really loaded,\n// on every version and provider, and never read twice alongside native\n// AGENTS.md support (cf. ADR engine-native-layouts-1-0).\nconst CLAUDE_MD_STUB = \"@AGENTS.md\\n\";\n\n// OpenCode also scans `.claude/skills/` and `.agents/skills/`. It goes last so\n// its own copy of a skill is dropped when another rendered engine exposes it.\nfunction opencodeLast(engines: ReadonlyArray<Engine>): Engine[] {\n return [...engines].sort((a, b) => Number(a === \"opencode\") - Number(b === \"opencode\"));\n}\n\n/**\n * Pure transformation `(catalog, engines, overrides) → files`. The harness\n * ships no agent persona and no engine hook: only the doc skills, their\n * commands, and the engine-neutral umbrella\n * (docs/decisions/no-personas-no-code-judgment.md,\n * docs/decisions/lint-in-ci-and-pre-commit.md).\n */\nexport function render(input: RenderInput): RenderOutput {\n const { engines } = input;\n if (engines.length === 0) {\n throw new RenderError(\"at least one engine must be selected\");\n }\n const base: Harness = input.projectSkills?.length\n ? { ...input.harness, skills: mergeById(input.harness.skills, input.projectSkills) }\n : input.harness;\n const harness = applyOverrides(base, input.overrides);\n\n const files: RenderedFile[] = [];\n const warnings: string[] = [];\n\n // Track skills + commands successfully exposed on at least one engine,\n // for the engine-neutral umbrella's \"Doc-skills\" section.\n const exposedSkills = new Map<string, Skill>();\n const exposedCmds = new Map<string, Cmd>();\n\n for (const engine of opencodeLast(engines)) {\n const renderer = getRenderer(engine);\n\n const renderedSkillIds = new Set<string>();\n for (const skill of harness.skills) {\n const result = renderer.renderSkill(skill);\n warnings.push(...result.warnings);\n if (result.files.length > 0) {\n const alreadyVisible = engine === \"opencode\" && exposedSkills.has(skill.meta.id);\n if (!alreadyVisible) files.push(...result.files);\n renderedSkillIds.add(skill.meta.id);\n exposedSkills.set(skill.meta.id, skill);\n }\n }\n\n for (const cmd of harness.cmds) {\n if (!renderedSkillIds.has(cmd.meta.invokes_skill)) continue;\n const result = renderer.renderCmd(cmd);\n warnings.push(...result.warnings);\n if (result.files.length > 0) {\n files.push(...result.files);\n exposedCmds.set(cmd.meta.id, cmd);\n }\n }\n }\n\n // Engine-neutral umbrella at the root\n const umbrellaContent = buildUmbrellaBody({\n availableSkills: Array.from(exposedSkills.values()),\n availableCommands: Array.from(exposedCmds.values()),\n hasProjectSkills: (input.projectSkills?.length ?? 0) > 0,\n hasQualityDoc: input.hasQualityDoc === true,\n hasJourneys: (input.journeys?.length ?? 0) > 0,\n });\n files.push({ path: \"AGENTS.md\", content: umbrellaContent });\n\n // CLAUDE.md stub only if claude-code is enabled (Claude Code reads it historically)\n if (engines.includes(\"claude-code\")) {\n files.push({ path: \"CLAUDE.md\", content: CLAUDE_MD_STUB });\n }\n\n // The journeys index is a generated file too, rendered only while a journey exists.\n if (input.journeys && input.journeys.length > 0) {\n files.push({ path: JOURNEYS_INDEX_PATH, content: buildJourneysIndex(input.journeys) });\n }\n\n return { files, warnings };\n}\n"],"mappings":"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","names":["ENGINE","ENGINE","BASE"]}
@@ -1,11 +1,10 @@
1
1
  ---
2
2
  id: decision-record-writer
3
3
  description: |
4
- Wizard to write an ADR under `docs/decisions/<slug>.md` (no
5
- numbering — see README). Detects the implicit decisions in the
6
- current diff (commits, code, configs) and offers to turn them into
7
- ADRs. Guarantees the 4 required sections: Context, Decision,
8
- Consequences, Rejected alternatives.
4
+ Writes an ADR under `docs/decisions/<slug>.md`, only for a structural
5
+ decision that passes the admission test below. Everything else goes to
6
+ the spec, the handbook, the test plans or the workflow. ADRs are short:
7
+ one decision, four sections, about 40 lines.
9
8
  engines: [claude-code, codex-cli, opencode]
10
9
  requires: [multi-step]
11
10
  tags: [decisions, doc, writer, adr]
@@ -13,153 +12,117 @@ tags: [decisions, doc, writer, adr]
13
12
 
14
13
  # Decision Record Writer
15
14
 
16
- You are the Vaubaan harness's ADR (Architecture Decision Record)
17
- writing wizard. An ADR captures *a settled choice* — why we decided X
18
- rather than Y, when, and in what context. Without ADRs, choices get
19
- lost and the same debates are revisited every 6 months.
20
-
21
- ## When to invoke you
22
-
23
- - A feature is finished that involves a non-trivial choice (lib,
24
- pattern, architecture, dependency) → write the ADR before commit.
25
- - A PR carrying a decision is about to be merged → confirm that an
26
- ADR exists (otherwise create a light "merge decision" one).
27
- - `/decision` invoked explicitly by the human.
28
- - `doc-audit` flagged an implicit decision in `git log` → write the
29
- ADR retrospectively.
30
-
31
- ## Procedure
32
-
33
- 1. **Detect implicit decisions** (if invoked without an explicit
34
- subject):
35
- - `git log --oneline -n 50` — spot messages containing hints:
36
- `decided`, `switched`, `migrated`, `removed`, `dropped`,
37
- `replaced`, `chose X over Y`, `no longer using`, `now using`.
38
- - `git diff <base>...HEAD` — spot changes to `package.json` (deps
39
- added/removed), to config (`vercel.json`, `.github/workflows/`,
40
- `tsconfig.json`), to structure (new `packages/<name>/`, or
41
- removal).
42
- - List the candidate decisions and ask the human which one to turn
43
- into an ADR (or several).
44
- 2. **Slug**: short kebab-case (3-6 words) summarizing the decision.
45
- **No numbering** — the slug is the durable identity; no implicit
46
- precedence logic is carried by the file name.
47
- E.g.: `supabase-zk`, `trunk-based-branching`, `multi-engine-pivot-format`.
48
- If you find an already existing file with this slug, pick a more
49
- precise one (do not overwrite).
50
- 3. **Load the template** `@vaubaan/harness/templates/decision.md.tmpl`.
51
- 4. **Core questions** to ask the human:
52
- - **Context**: what motivated the decision? What problem needed
53
- solving? At what point in the project?
54
- - **Decision**: *what was settled*, phrased as one declarative
55
- sentence ("We use X for Y").
56
- - **Consequences**: positive (what it unlocks) + negative (what it
57
- constrains, technical debt, lock-in).
58
- - **Rejected alternatives**: list the options that were considered
59
- and discarded, *with the reason* for rejection. This is the most
60
- valuable section — without it, the ADR is just a note.
61
- 5. **Metadata**: Date (today), Author (the human or the org), Status
62
- (`accepted` by default; `proposed` if still under debate;
63
- `superseded by <slug>` if a more recent ADR overrides it).
64
- 6. **Draft** the ADR. Submit it to the human. Iterate.
65
- 7. **Write** `docs/decisions/<slug>.md` via `Write`.
66
- 8. **Cross-link**: if the ADR concerns an existing spec or handbook,
67
- mention them. If the decision *supersedes* an earlier ADR, add
68
- `superseded_by: <slug>` in the old one (with human confirmation).
69
- 9. **Update the index**: if `docs/decisions/README.md` exists, add a
70
- line for the new ADR.
71
-
72
- ## Criteria
73
-
74
- - **4 mandatory required sections**: `## Context`, `## Decision`,
75
- `## Consequences`, `## Rejected alternatives` (the French headings
76
- `## Contexte` / `## Décision` / `## Conséquences` / `## Alternatives
77
- rejetées` are also accepted for backward compatibility). Without
78
- Rejected alternatives, the `lint:decision-schema` linter breaks CI.
79
- - **Concise but complete**. An ADR is typically 50-150 lines. Not an
80
- essay, not a sticky note.
81
- - **Dated**. The date in the frontmatter is the date the decision was
82
- *made*, not the date the ADR was written (often retrospective).
83
- - **Immutable**. An accepted ADR is no longer modified — if the
84
- decision changes, create a new ADR that *supersedes* the old one. No
85
- rewrite.
86
-
87
- ## Expected output
88
-
89
- A `docs/decisions/<slug>.md` file:
15
+ The decision log holds **only the structural decisions in force**: the few
16
+ choices a newcomer must know so they don't undo them, and that would cost a
17
+ lot to reverse. It is not a journal of the project, nor a place to justify
18
+ every choice. Most choices do not get an ADR.
19
+
20
+ ## Admission test
21
+
22
+ Write an ADR only if **all three** answers are yes. Otherwise, do not write
23
+ it: say which test fails and where the content goes instead.
24
+
25
+ 1. **Costly to reverse.** Changing it later takes more than one ordinary PR:
26
+ it touches the code structure, the data model, a module boundary, the
27
+ security model, or a vendor/platform the code depends on.
28
+ 2. **A real alternative was weighed.** Someone could reasonably propose the
29
+ other option again; the ADR exists to stop that debate from restarting.
30
+ No rejected alternative worth one sentence → no ADR.
31
+ 3. **It outlives the ticket.** It constrains future work across the
32
+ codebase, not just the feature that triggered it.
33
+
34
+ ## Not an ADR — where it goes
35
+
36
+ | Content | Goes to |
37
+ | --- | --- |
38
+ | Product rule (who can sign in, which channels, what is out of scope) | `docs/spec/` |
39
+ | Implementation detail: config values, file layout, env variables | the code (traps and settings outside the repo: `docs/handbook/`) |
40
+ | Test strategy and tooling (runner, target env, what is E2E) | `docs/tests/` |
41
+ | CI, branches, deploy, harness and tooling upgrades | `docs/workflow/` |
42
+ | Review rules and conventions | `docs/quality/code-quality.md` |
43
+ | Temporary choice with a planned end (stub, demo data until ticket X) | the ticket, plus a line in the handbook |
44
+ | Library choice that a single PR can swap | the PR description |
45
+ | Dependency upgrade | the commit message |
46
+
47
+ A one-sentence *why* may sit in the handbook or test plan next to the fact
48
+ it explains. Do not create an ADR just to hold it.
49
+
50
+ ## Format
51
+
52
+ Hard limits — an ADR that exceeds them is rewritten, not accepted:
53
+
54
+ - **One decision per ADR.** If the Decision section needs a bullet list of
55
+ unrelated points, split it or move the points to the handbook.
56
+ - **About 40 lines** including frontmatter, 60 at most.
57
+ - **Context**: 2-4 sentences. The forces that made the choice necessary. No
58
+ chronology (who said what on which date), no issue history.
59
+ - **Decision**: 1-3 sentences in the present tense, stated as a rule ("X is
60
+ Y; Z never does W"). No implementation detail unless it *is* the rule.
61
+ - **Consequences**: only what constrains future work — the rules a
62
+ developer must follow because of this decision. 2-4 bullets. No list of
63
+ benefits restating the decision; no operational to-dos (those go to the
64
+ handbook).
65
+ - **Rejected alternatives**: only the options seriously weighed, one or two
66
+ sentences each, with the reason it was rejected in this project's
67
+ context.
68
+ - No `References` section by default; link the spec or handbook inline when
69
+ the reader needs it.
90
70
 
91
71
  ```markdown
92
72
  ---
93
- title: <Short title — the decision in one sentence>
94
- status: accepted | proposed | superseded | deprecated
73
+ title: <The decision in one sentence>
74
+ status: accepted | proposed
95
75
  date: YYYY-MM-DD
96
- author: <name or org>
97
- supersedes: <slug> # optional
98
- superseded_by: <slug> # optional, added later
99
- # ⚠️ No `tracks:` field — see guardrail below.
76
+ author: <name>
100
77
  ---
101
78
 
102
79
  # <Title>
103
80
 
104
81
  ## Context
105
82
 
106
- <2-5 ¶. The problem, the constraints, the state of the project at that
107
- time. What someone needs to know to understand why the question
108
- arose.>
83
+ <2-4 sentences.>
109
84
 
110
85
  ## Decision
111
86
 
112
- <1-3 ¶. What was settled, phrased in the declarative present tense:
113
- "We use X. The main reason is Y.">
87
+ <1-3 sentences, a rule.>
114
88
 
115
89
  ## Consequences
116
90
 
117
- ### Positive
118
- - ...
119
-
120
- ### Negative / constraints
121
- - ...
91
+ - <constraint on future work>
122
92
 
123
93
  ## Rejected alternatives
124
94
 
125
- ### <Alternative A>
126
- <Short description, reason for rejection.>
95
+ ### <Alternative>
96
+ <1-2 sentences: what it is, why not here.>
97
+ ```
127
98
 
128
- ### <Alternative B>
129
- <...>
99
+ `date` is the day the decision was made. Never add a `tracks:` field: an
100
+ ADR is not refreshed when the code moves (`lint:adr-no-tracks`).
130
101
 
131
- ## References
132
- - <link to the relevant spec/handbook, threads, external RFCs>
133
- ```
102
+ ## Procedure
134
103
 
135
- Finish by:
136
- - Recalling the path of the written file.
137
- - Suggesting an update of the relevant spec or handbook if applicable.
138
- - Recommending a commit (but do not commit yourself).
104
+ 1. Find the candidate: the subject given by the human, or the structural
105
+ changes of the current diff (new package or module boundary, removed
106
+ layer, new vendor, data model, security model).
107
+ 2. Run the admission test on it, out loud. If it fails, stop and name the
108
+ doc that should receive the content.
109
+ 3. Check that no ADR in `docs/decisions/` already covers it. If one does and
110
+ the decision changed, write the new ADR and **delete the old file**
111
+ (git keeps the history); list the old option in the new ADR's Rejected
112
+ alternatives and update the links to it.
113
+ 4. Ask the human only what the code cannot tell: the alternatives weighed
114
+ and why they lost.
115
+ 5. Draft within the format limits, submit it, iterate, then write
116
+ `docs/decisions/<slug>.md` (short kebab-case slug, no number).
117
+ 6. Update the links to the ADR in the docs that rely on it. Do not commit.
139
118
 
140
119
  ## Guardrails
141
120
 
142
- - **Never a `tracks:` field in an ADR's frontmatter.** The `tracks:`
143
- field is a "refresh-this-doc-when-the-code-moves" sensor, reserved
144
- for handbooks / test plans / workflow that describe the *current*
145
- state of the system. An ADR documents a decision *frozen in time*:
146
- it is not refreshed — it is superseded or remains valid. Attaching a
147
- `tracks:` to it produces false drift (every dep bump or config tweak
148
- wakes the ADR up while the decision is intact). If you inherit an
149
- existing ADR carrying a `tracks:`, flag it; the `lint:adr-no-tracks`
150
- linter should flag it too.
151
- - **Decide nothing on the human's behalf**. You capture a decision
152
- *already made* (or about to be). If the human hesitates, propose a
153
- `proposed` status rather than settling it yourself.
154
- - **Do not rewrite existing ADRs**. An ADR is immutable. If the
155
- decision changed, create a new ADR with `supersedes: <slug>`.
156
- - **Do not skip the Rejected alternatives section**. If the human says
157
- "there was no alternative", insist: there always is one (status quo,
158
- do nothing, build vs. buy, lib A vs lib B). Force it to be made
159
- explicit.
160
- - **No tech-bashing**. A rejected alternative is justified by *fit
161
- with the project's context*, not by "X sucks". Neutral tone.
162
- - **No duplication**. Before writing, check that no ADR already covers
163
- the same decision (look at the index + grep by keyword). If one
164
- does, propose a `supersedes` or a status update instead.
165
- - **No auto-commit**. File write only.
121
+ - **Decide nothing for the human.** If the choice is still open, use
122
+ `proposed` or do not write the ADR yet.
123
+ - **Fewer, shorter ADRs.** When in doubt, no ADR. The log is read in full
124
+ by newcomers and agents; every extra ADR dilutes the ones that matter.
125
+ - **In force only.** The log holds decisions that apply today. A superseded
126
+ or expired ADR is deleted, not kept with a status.
127
+ - **Neutral tone** in rejected alternatives: fit with this project, not
128
+ judgement on a tool.
@@ -26,7 +26,7 @@ mechanized.
26
26
  - Before drafting a plan: we need to know whether the existing docs
27
27
  are sound.
28
28
  - On explicit request via `/doc-audit [scope]` (scope = `spec`,
29
- `decisions`, `handbook`, `tests`, `workflow`, `readme`, or `all`).
29
+ `decisions`, `handbook`, `tests`, `workflow`, `readme`, `journeys`, or `all`).
30
30
 
31
31
  ## Scope of the 6 pillars
32
32
 
@@ -39,12 +39,14 @@ mechanized.
39
39
  (required v1).
40
40
  - **workflow** — `docs/workflow/coding-workflow.md` (required v1).
41
41
 
42
- Two **optional** pillars are added. Their absence is never reported;
42
+ Three **optional** pillars are added. Their absence is never reported;
43
43
  you audit them only if they exist:
44
44
 
45
45
  - **skills** — `docs/skills/*.skill.md`: the project's domain skills.
46
46
  - **quality** — `docs/quality/code-quality.md`: project-specific
47
47
  quality rules.
48
+ - **journeys** — `docs/journeys/*.md`: what the user does and wants,
49
+ at every scale, anchored to the code (`README.md` there is generated).
48
50
 
49
51
  ## Procedure
50
52
 
@@ -111,8 +113,8 @@ you audit them only if they exist:
111
113
  ### Tests
112
114
  - ❌ `docs/tests/integration-tests.md` missing.
113
115
  - ❌ `docs/tests/e2e-tests.md` missing.
114
- - ⚠️ Spec without a test plan: no integration-tests or e2e-tests
115
- scenario mentions the spec (by name or by ID `[[spec-name]]`).
116
+ - ⚠️ Spec without tests: no integration or E2E test file exercises the
117
+ subsystem, and the spec is not listed in a "Known gaps" section.
116
118
  - ❌ Stale test plan: `tracks:` points to code that no longer exists.
117
119
  - ⚠️ Explicit gaps listed in the "Known gaps" section of the test plan
118
120
  (not an error, but to be reported).
@@ -142,6 +144,26 @@ Audit **only if `docs/quality/` exists**.
142
144
  longer exists in the repo.
143
145
  - ⚠️ An accepted deviation with no reason and no link to an ADR.
144
146
 
147
+ ### Journeys (optional pillar)
148
+ Audit **only if `docs/journeys/` holds a journey**. The linters
149
+ (`lint:journey-*`) already check the grammar, the anchors and the
150
+ vocabulary; you judge what they cannot.
151
+ - ⚠️ **Spec without journey**: a `docs/spec/*.md` file that no journey
152
+ links in its `spec:` frontmatter. The subsystem has rules but no
153
+ documented user activity.
154
+ - ⚠️ **Leaf without a test**: an `implemented` leaf none of whose
155
+ `anchors:` is a test file (by the project's test conventions, see
156
+ `docs/tests/`).
157
+ - ⚠️ **Pending increment**: a `proposed` leaf whose journey has not
158
+ changed for more than N commits (default 10). List them: they are the
159
+ backlog nobody delivered.
160
+ - ⚠️ **Criteria lost at delivery**: the tests anchored by a leaf
161
+ delivered in the recent history (`git log` on the journey) do not
162
+ restate its former `acceptance:` items in their titles.
163
+ - ❌ **Pillar drift**: a leaf carrying prose that states a business rule
164
+ (→ `spec/`) or how the code works (→ `handbook/`); a field the linter
165
+ does not know is already an error.
166
+
145
167
  ### Cross-link consistency
146
168
  - ⚠️ Orphan spec: no decision, handbook or test references it.
147
169
  - ⚠️ Orphan decision: not referenced by any other doc file.
@@ -159,6 +181,8 @@ This is *the* critical point where docs drift. Heuristics:
159
181
  paraphrases generic principles (SOLID, Clean Code), what lengthily
160
182
  justifies a structural decision (→ ADR) or describes the
161
183
  implementation (→ handbook).
184
+ - journeys/ (if present) must stay intention + pointers → flag a leaf
185
+ that explains a rule or an implementation.
162
186
  - Any architectural choice mentioned in a commit without an ADR → flag
163
187
  (see "Implicit decisions").
164
188
 
@@ -197,7 +221,7 @@ invent empty sections):
197
221
  - ✅/❌ docs/tests/integration-tests.md
198
222
  - ✅/❌ docs/tests/e2e-tests.md
199
223
  - Specs without a test plan:
200
- - ⚠️ <spec>.md (no scenario references it)
224
+ - ⚠️ <spec>.md (no test, not listed as a known gap)
201
225
 
202
226
  ## README (root)
203
227
 
@@ -217,6 +241,12 @@ invent empty sections):
217
241
  - ❌ section "<section>" missing
218
242
  - ⚠️ <cited tool or config file> not found in the repo
219
243
 
244
+ ## Journeys (optional — section omitted if docs/journeys/ is absent)
245
+
246
+ - ⚠️ docs/spec/<name>.md — no journey links it
247
+ - ⚠️ docs/journeys/<slug>.md › <leaf title> — implemented, no test anchor
248
+ - ⚠️ docs/journeys/<slug>.md › <leaf title> — proposed for N commits
249
+
220
250
  ## Cross-link consistency
221
251
 
222
252
  - Orphan spec: <path>
@@ -239,8 +269,8 @@ invent empty sections):
239
269
 
240
270
  - **Fix nothing**. You audit, you list, you recommend. The writers
241
271
  (`spec-writer`, `decision-record-writer`, `handbook-writer`,
242
- `test-plan-writer`, `workflow-writer`, `readme-writer`) are there to
243
- fix — not you.
272
+ `test-plan-writer`, `workflow-writer`, `readme-writer`,
273
+ `journey-writer`) are there to fix — not you.
244
274
  - **Do not re-implement the mechanical linters**. If a check is already
245
275
  covered by `vaubaan harness lint` (file presence, frontmatter schema,
246
276
  tech keyword regex, cross-links), you may mention it briefly but do