@vaubaan/harness 2.1.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.
- package/README.md +12 -6
- package/dist/cli/index.js +541 -74
- package/dist/cli/index.js.map +1 -1
- package/dist/commands/doc-audit.cmd.md +1 -1
- package/dist/commands/journey.cmd.md +22 -0
- package/dist/commands/story.cmd.md +24 -0
- package/dist/index.d.ts +2 -2
- package/dist/index.js +302 -54
- package/dist/index.js.map +1 -1
- package/dist/init.d.ts +1 -1
- package/dist/init.js +299 -51
- package/dist/init.js.map +1 -1
- package/dist/linters/index.js +521 -54
- package/dist/linters/index.js.map +1 -1
- package/dist/parser/index.d.ts +110 -1
- package/dist/parser/index.js +229 -2
- package/dist/parser/index.js.map +1 -1
- package/dist/{render-C-FWmUfX.d.ts → render-BzrBb_l4.d.ts} +3 -1
- package/dist/render.d.ts +1 -1
- package/dist/render.js +87 -8
- package/dist/render.js.map +1 -1
- package/dist/skills/doc-audit.skill.md +34 -4
- package/dist/skills/drift-detector.skill.md +36 -5
- package/dist/skills/handbook-writer.skill.md +3 -0
- package/dist/skills/journey-writer.skill.md +159 -0
- package/dist/templates/journey.md.tmpl +45 -0
- package/package.json +1 -1
package/dist/render.js.map
CHANGED
|
@@ -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` — 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 \"\",\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"]}
|
|
@@ -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
|
-
|
|
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
|
|
|
@@ -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
|
|
|
@@ -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
|
|
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
|
|
@@ -37,7 +37,9 @@ the doc content still matches reality.
|
|
|
37
37
|
move on to the semantic analysis.
|
|
38
38
|
1. **Inventory of targets**: all files under `docs/handbook/`,
|
|
39
39
|
`docs/tests/`, `docs/workflow/` that declare a non-empty
|
|
40
|
-
`tracks: [...]` in their frontmatter
|
|
40
|
+
`tracks: [...]` in their frontmatter, and the files under
|
|
41
|
+
`docs/journeys/` whose nodes declare `anchors:` (`README.md` there is
|
|
42
|
+
generated: skip it).
|
|
41
43
|
- **Explicit skip**: `docs/decisions/` is *never* scanned. ADRs
|
|
42
44
|
document decisions frozen in time — their drift is semantically
|
|
43
45
|
different (is the decision still valid?), not a question of doc
|
|
@@ -63,11 +65,21 @@ the doc content still matches reality.
|
|
|
63
65
|
exists in the test infrastructure → drift.
|
|
64
66
|
- The workflow doc says "the `lint` job runs on PR", `ci.yml`
|
|
65
67
|
no longer contains this job → drift.
|
|
68
|
+
- A journey leaf anchors a file that no longer exists, or
|
|
69
|
+
`requires:` an entity the spec vocabulary no longer defines →
|
|
70
|
+
hard drift.
|
|
71
|
+
- A journey leaf whose anchored code gained a branch (a new
|
|
72
|
+
guard, a new step the user sees) with no node for it → soft
|
|
73
|
+
drift; a `proposed` leaf whose code already exists → soft
|
|
74
|
+
drift, suggest passing it `implemented`.
|
|
66
75
|
- **Syntactic consistency**: do the mentioned signatures /
|
|
67
76
|
types / commands match?
|
|
68
77
|
3. **Reverse cross-check**: for "important" code files (entry point,
|
|
69
78
|
public types, `package.json` scripts), check that they are tracked
|
|
70
|
-
by *at least one* doc
|
|
79
|
+
by *at least one* doc (`tracks:`) or anchored by *at least one*
|
|
80
|
+
journey leaf (`anchors:`). Otherwise → ⚠️ "undocumented code". This
|
|
81
|
+
is where unanchored entry points are reported: with judgment, no
|
|
82
|
+
configuration.
|
|
71
83
|
4. **Report**: structured Markdown in a
|
|
72
84
|
`.vaubaan/reports/drift-report.md` file (create the folder if missing).
|
|
73
85
|
|
|
@@ -81,12 +93,15 @@ the doc content still matches reality.
|
|
|
81
93
|
- ADR with a non-empty `tracks:` (see `lint:adr-no-tracks`).
|
|
82
94
|
- Mention in the doc of a function / API / command that is gone.
|
|
83
95
|
- Test plan that refers to a test that is gone.
|
|
96
|
+
- Journey anchor to a deleted file; entity removed from the spec
|
|
97
|
+
vocabulary.
|
|
84
98
|
- **Soft drift** (⚠️):
|
|
85
99
|
- Doc that describes an earlier state (80 % covered by the current
|
|
86
100
|
code — not wrong, but incomplete).
|
|
87
101
|
- New undocumented feature (the code evolved, the doc did not
|
|
88
102
|
follow).
|
|
89
103
|
- Changed conventions (e.g.: naming, tree structure) not reflected.
|
|
104
|
+
- Code branch without a journey node; `proposed` leaf already coded.
|
|
90
105
|
- **Not drift**:
|
|
91
106
|
- Stylistic difference (wording, section order).
|
|
92
107
|
- Minor implementation detail absent from the doc (by design: the
|
|
@@ -124,6 +139,12 @@ lie about their own scope._
|
|
|
124
139
|
- ❌ Describes a `resetDb()` fixture — `tests/fixtures/db.ts`
|
|
125
140
|
deleted.
|
|
126
141
|
|
|
142
|
+
### docs/journeys/<slug>.md
|
|
143
|
+
|
|
144
|
+
- ❌ Leaf "<title>" anchors `src/legacy/old.ts` — file deleted.
|
|
145
|
+
- ❌ Leaf "<title>" requires `<entity>` — no longer in the Vocabulary
|
|
146
|
+
of `docs/spec/<subsystem>.md`.
|
|
147
|
+
|
|
127
148
|
## Soft drift (M items)
|
|
128
149
|
|
|
129
150
|
### docs/handbook/<name>.md
|
|
@@ -138,10 +159,19 @@ lie about their own scope._
|
|
|
138
159
|
- ⚠️ Mentions the CI job `e2e` — the job was renamed `e2e-tests`
|
|
139
160
|
in `.github/workflows/ci.yml` (commit <sha>).
|
|
140
161
|
|
|
162
|
+
### docs/journeys/<slug>.md
|
|
163
|
+
|
|
164
|
+
- ⚠️ Leaf "<title>": its anchored `src/foo.ts:88` gained a guard the
|
|
165
|
+
user sees, no node for it.
|
|
166
|
+
- ⚠️ Leaf "<title>" is `proposed` but `src/bar.ts` already realizes it
|
|
167
|
+
— pass it `implemented`.
|
|
168
|
+
|
|
141
169
|
## Undocumented code (K items)
|
|
142
170
|
|
|
143
171
|
- ⚠️ `src/new-feature/` (introduced commit <sha>) — no handbook
|
|
144
|
-
tracks these files. Suggested:
|
|
172
|
+
tracks these files and no journey leaf anchors them. Suggested:
|
|
173
|
+
`/handbook new-feature` for the how, `/journey <slug>` for the user
|
|
174
|
+
activity.
|
|
145
175
|
- ⚠️ Script `package.json:deploy:preview` — not mentioned in
|
|
146
176
|
`coding-workflow.md`.
|
|
147
177
|
|
|
@@ -152,13 +182,14 @@ lie about their own scope._
|
|
|
152
182
|
3. `/workflow` to resync `coding-workflow.md` vs `ci.yml`.
|
|
153
183
|
4. Write an ADR for change <X> if it was a decision (see
|
|
154
184
|
`/decision`).
|
|
185
|
+
5. `/journey <slug>` to add the missing node or re-anchor the leaf.
|
|
155
186
|
```
|
|
156
187
|
|
|
157
188
|
## Guardrails
|
|
158
189
|
|
|
159
190
|
- **Fix nothing**. You detect, you list, you recommend. The writers
|
|
160
|
-
(`handbook-writer`, `test-plan-writer`, `workflow-writer
|
|
161
|
-
to fix.
|
|
191
|
+
(`handbook-writer`, `test-plan-writer`, `workflow-writer`,
|
|
192
|
+
`journey-writer` via `/journey`) are there to fix.
|
|
162
193
|
- **No false positives on details**. If the handbook says "the
|
|
163
194
|
function returns a Result<T, E>" and the code returns `Result<T, E>`
|
|
164
195
|
but with a slightly different T type, that is not hard drift — it
|
|
@@ -51,6 +51,9 @@ Keep a sentence only if **reading the code would not give it quickly**:
|
|
|
51
51
|
(`lint:cross-links`).
|
|
52
52
|
- First line after the title: one sentence on the scope, and a link to the
|
|
53
53
|
spec if it exists.
|
|
54
|
+
- When a journey leaf anchors the feature (`docs/journeys/`), link it
|
|
55
|
+
too: the journey says what the user does and where, the handbook says
|
|
56
|
+
how. Never restate the journey.
|
|
54
57
|
|
|
55
58
|
```markdown
|
|
56
59
|
---
|
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: journey-writer
|
|
3
|
+
description: |
|
|
4
|
+
Writes or updates `docs/journeys/<slug>.md`: the user intentions of
|
|
5
|
+
the project at every scale, anchored to the code. One node at a time.
|
|
6
|
+
Greenfield: three questions. Mature: reads the code's entry points and
|
|
7
|
+
proposes anchored leaves. `/story <intent>` adds a `proposed` leaf
|
|
8
|
+
with its acceptance criteria before any code is written.
|
|
9
|
+
engines: [claude-code, codex-cli, opencode]
|
|
10
|
+
requires: [multi-step]
|
|
11
|
+
tags: [journeys, doc, writer]
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
# Journey Writer
|
|
15
|
+
|
|
16
|
+
You are the Vaubaan harness's journey wizard. A journey says what the
|
|
17
|
+
user does and wants, from a level-1 intention down to the atomic activity
|
|
18
|
+
a piece of code realizes, and where that code is. It is the entry point
|
|
19
|
+
to a feature: a new behavior is a `proposed` leaf here before it is a
|
|
20
|
+
line of code. Contract: spec §9.1.3 of the harness; the rule of a leaf
|
|
21
|
+
lives in `docs/spec/`, the how in `docs/handbook/`, never here.
|
|
22
|
+
|
|
23
|
+
## Content test
|
|
24
|
+
|
|
25
|
+
A journey holds only what neither the code nor another pillar says:
|
|
26
|
+
|
|
27
|
+
- **Keep**: the intention (verb + object) at each level, the actors, what
|
|
28
|
+
a leaf needs and produces (`requires:` / `creates:`), where it is
|
|
29
|
+
realized (`anchors:`), what "done" means for a `proposed` leaf
|
|
30
|
+
(`acceptance:`), the spec section that holds the rule (`spec:`).
|
|
31
|
+
- **Drop**: business rules (→ spec), how the code works (→ handbook),
|
|
32
|
+
anything derivable from the code (which components a leaf uses, which
|
|
33
|
+
roles guard it, how deep it is), prose on a leaf (its title and fields
|
|
34
|
+
suffice), a node for every function (a leaf is a user activity, not a
|
|
35
|
+
code unit).
|
|
36
|
+
|
|
37
|
+
Targets: 2 to 9 children per node, 40 to 120 lines per file. Beyond,
|
|
38
|
+
split into two level-1 journeys; never nest a journey in another with a
|
|
39
|
+
`parent:` field, the format has none.
|
|
40
|
+
|
|
41
|
+
## When to invoke you
|
|
42
|
+
|
|
43
|
+
- `/story <intent>`: a visible change of behavior is about to be built.
|
|
44
|
+
This is the doc-first rule of `AGENTS.md`; nothing is coded before the
|
|
45
|
+
leaf exists.
|
|
46
|
+
- `/journey [name]`: a new journey, or a node to add to an existing one.
|
|
47
|
+
- `doc-audit` reports a spec without journey, or a pending increment.
|
|
48
|
+
- A pull request delivers a `proposed` leaf: pass it `implemented`.
|
|
49
|
+
|
|
50
|
+
## Format
|
|
51
|
+
|
|
52
|
+
```markdown
|
|
53
|
+
---
|
|
54
|
+
title: <Verb + object>
|
|
55
|
+
status: proposed | implemented | deprecated
|
|
56
|
+
actors: [<role>, <role>]
|
|
57
|
+
spec: ../spec/<subsystem>.md
|
|
58
|
+
last_reviewed: YYYY-MM-DD
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
# <Verb + object>
|
|
62
|
+
|
|
63
|
+
As a <actor>, I want <intention> so that <outcome>.
|
|
64
|
+
|
|
65
|
+
## <Verb + object> ← internal node: may carry one sentence
|
|
66
|
+
|
|
67
|
+
### <Verb + object> ← leaf: fields, no prose
|
|
68
|
+
|
|
69
|
+
requires: <entity>, <entity>
|
|
70
|
+
creates: <entity>
|
|
71
|
+
anchors: <path or glob>, <path or glob>
|
|
72
|
+
spec: ../spec/<subsystem>.md#<section>
|
|
73
|
+
|
|
74
|
+
### <Verb + object>
|
|
75
|
+
|
|
76
|
+
status: proposed
|
|
77
|
+
requires: <entity>
|
|
78
|
+
acceptance:
|
|
79
|
+
- <observable criterion>
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Rules the linters enforce (`lint:journey-*`), so apply them as you write:
|
|
83
|
+
|
|
84
|
+
- A leaf is a heading with no sub-heading. Fields sit on the lines right
|
|
85
|
+
under it, one per line, values comma-separated. Leaf fields on an
|
|
86
|
+
internal node, or an unknown field, fail the lint.
|
|
87
|
+
- An `implemented` leaf has `anchors:` that exist; a `proposed` leaf has
|
|
88
|
+
at least one `acceptance:` item.
|
|
89
|
+
- An entity is the kebab-case slug of a bold term opening a bullet in the
|
|
90
|
+
Vocabulary section of a linked spec (`**Generated file**` →
|
|
91
|
+
`generated-file`). Singular, no synonym. A missing word goes into the
|
|
92
|
+
spec first (`/spec`), never into the journey as an invention.
|
|
93
|
+
- `spec:` paths resolve. `docs/journeys/README.md` is generated: never
|
|
94
|
+
edit it; after any change run `npx @vaubaan/harness update .`.
|
|
95
|
+
|
|
96
|
+
## Procedure
|
|
97
|
+
|
|
98
|
+
1. **Locate.** `/story <intent>` or `/journey <name>`: find the journey
|
|
99
|
+
the intent belongs to by reading `docs/journeys/README.md` (the
|
|
100
|
+
generated index) and the journey titles. No journey fits → a new
|
|
101
|
+
level-1 file, slug from the verb + object. Ask when two fit.
|
|
102
|
+
2. **Detect the mode** on the scope of the node:
|
|
103
|
+
- **Greenfield**: no code and no handbook cover it. Ask three
|
|
104
|
+
questions, one at a time: who does it (actor), what they want and
|
|
105
|
+
why (the user story), what it does not cover. Write the file with
|
|
106
|
+
its first `proposed` leaf and stop. The rest comes one node at a
|
|
107
|
+
time, as the project learns.
|
|
108
|
+
- **Mature**: code exists. Do not question the human from a blank
|
|
109
|
+
page. Read the entry points of the code (routes, commands,
|
|
110
|
+
handlers, mutations), the spec and the handbooks. Propose a
|
|
111
|
+
hierarchy top-down from the navigation or the CLI, and a leaf at a
|
|
112
|
+
time with its anchors, `requires:` / `creates:` from the spec
|
|
113
|
+
vocabulary, and the spec section. The human corrects instead of
|
|
114
|
+
answering. One sub-domain first, to stabilize the vocabulary, then
|
|
115
|
+
extend. A code-graph tool (an MCP server the project configured)
|
|
116
|
+
helps if present; read the code if not. The harness installs none.
|
|
117
|
+
3. **`/story <intent>`** (the typed transaction): write the leaf as
|
|
118
|
+
`proposed`, at the right place in the tree, with 2 to 5 observable
|
|
119
|
+
acceptance criteria and its `requires:` / `creates:`. **Refuse** to
|
|
120
|
+
write an entity that is in no linked spec's Vocabulary: stop and
|
|
121
|
+
redirect to `/spec` so the word is defined first. No `anchors:` yet.
|
|
122
|
+
4. **Deliver** (`proposed` → `implemented`, in the pull request that
|
|
123
|
+
ships the code): add `anchors:` to the code and the tests, write
|
|
124
|
+
tests whose titles restate the acceptance criteria, remove
|
|
125
|
+
`acceptance:`, set `last_reviewed`. A delivered leaf changes only in
|
|
126
|
+
the PR that delivers the change: a later change of behavior is a
|
|
127
|
+
sibling `proposed` leaf, merged into the leaf when delivered.
|
|
128
|
+
5. **Withdraw** (`implemented` → `deprecated`): set the status, keep the
|
|
129
|
+
node one release, delete it at the next one. Never back to
|
|
130
|
+
`proposed`.
|
|
131
|
+
6. **Check**: run `npx @vaubaan/harness lint --pillar journeys`, then
|
|
132
|
+
`npx @vaubaan/harness update .` so the index follows. Submit the
|
|
133
|
+
draft, iterate, write. Do not commit.
|
|
134
|
+
|
|
135
|
+
## Criteria
|
|
136
|
+
|
|
137
|
+
- **Verb + object** at every level; a category ("Settings", "Admin") is
|
|
138
|
+
not an intention.
|
|
139
|
+
- **A leaf is a user activity** that one handler, route, command or
|
|
140
|
+
mutation realizes. A step the user does not perceive is not a leaf.
|
|
141
|
+
- **The tree reads top-down**: an agent that opens the journey learns in
|
|
142
|
+
one screen what the user does and where to look.
|
|
143
|
+
- **Entities are the spec's words**, in the spec's language.
|
|
144
|
+
- **Acceptance criteria are observable**: a command output, a visible
|
|
145
|
+
state, an exit code, never "works correctly".
|
|
146
|
+
|
|
147
|
+
## Guardrails
|
|
148
|
+
|
|
149
|
+
- **Decide nothing on the human's behalf.** Propose, let them validate
|
|
150
|
+
leaf by leaf. A doubt on where a node belongs is a question, not a
|
|
151
|
+
guess.
|
|
152
|
+
- **No business rule, no implementation.** If you explain *why* a rule
|
|
153
|
+
holds, redirect to `/spec`; if you explain *how* the code does it,
|
|
154
|
+
redirect to `/handbook`. A one-line `spec:` pointer replaces both.
|
|
155
|
+
- **Do not invent vocabulary.** The spec defines the words; `/story`
|
|
156
|
+
refuses an undefined entity rather than coining one.
|
|
157
|
+
- **Do not commit.** Write the files only; the commit follows the
|
|
158
|
+
project's workflow.
|
|
159
|
+
- **Never edit `docs/journeys/README.md`.** It is rendered.
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: <VERB + OBJECT>
|
|
3
|
+
status: proposed
|
|
4
|
+
actors: [<ACTOR>]
|
|
5
|
+
spec: ../spec/<SUBSYSTEM>.md
|
|
6
|
+
last_reviewed: <DATE>
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# <VERB + OBJECT>
|
|
10
|
+
|
|
11
|
+
As a <actor>, I want <intention> so that <outcome>.
|
|
12
|
+
|
|
13
|
+
<!--
|
|
14
|
+
One file per level-1 intention; the levels below are nested headings. A
|
|
15
|
+
leaf is a heading with no sub-heading: it carries its fields on the lines
|
|
16
|
+
right under the title, one field per line, values comma-separated, and no
|
|
17
|
+
prose. An internal node may carry one sentence of user story.
|
|
18
|
+
|
|
19
|
+
Fields of a leaf:
|
|
20
|
+
requires: / creates: entities of the linked spec's Vocabulary (kebab-case)
|
|
21
|
+
anchors: paths or globs of the code and tests (implemented)
|
|
22
|
+
acceptance: observable criteria as a list (proposed)
|
|
23
|
+
status: proposed | implemented | deprecated, when it differs
|
|
24
|
+
from the file's
|
|
25
|
+
spec: link to the spec section that holds the rule
|
|
26
|
+
|
|
27
|
+
Targets: 2-9 children per node, 40-120 lines per file. Longer: split into
|
|
28
|
+
two journeys. The rule lives in the spec, the how in the handbook.
|
|
29
|
+
-->
|
|
30
|
+
|
|
31
|
+
## <Verb + object>
|
|
32
|
+
|
|
33
|
+
requires: <entity>
|
|
34
|
+
creates: <entity>
|
|
35
|
+
anchors: <path or glob>, <path or glob>
|
|
36
|
+
|
|
37
|
+
## <Verb + object>
|
|
38
|
+
|
|
39
|
+
### <Verb + object>
|
|
40
|
+
|
|
41
|
+
status: proposed
|
|
42
|
+
requires: <entity>
|
|
43
|
+
acceptance:
|
|
44
|
+
- <observable criterion>
|
|
45
|
+
- <observable criterion>
|
package/package.json
CHANGED