@vaubaan/harness 2.1.0 → 2.3.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 +537 -67
- package/dist/cli/index.js +582 -83
- package/dist/cli/index.js.map +1 -1
- package/dist/commands/doc-audit.cmd.md +1 -1
- package/dist/commands/intent.cmd.md +33 -0
- package/dist/index.d.ts +2 -2
- package/dist/index.js +343 -63
- package/dist/index.js.map +1 -1
- package/dist/init.d.ts +1 -1
- package/dist/init.js +340 -60
- package/dist/init.js.map +1 -1
- package/dist/linters/index.js +536 -62
- package/dist/linters/index.js.map +1 -1
- package/dist/parser/index.d.ts +143 -1
- package/dist/parser/index.js +235 -4
- package/dist/parser/index.js.map +1 -1
- package/dist/{render-C-FWmUfX.d.ts → render-CTx7VNOK.d.ts} +3 -1
- package/dist/render.d.ts +1 -1
- package/dist/render.js +98 -14
- package/dist/render.js.map +1 -1
- package/dist/skills/doc-audit.skill.md +35 -4
- package/dist/skills/drift-detector.skill.md +36 -5
- package/dist/skills/handbook-writer.skill.md +3 -0
- package/dist/skills/intent-writer.skill.md +174 -0
- package/dist/templates/e2e-tests.md.tmpl +1 -1
- package/dist/templates/integration-tests.md.tmpl +1 -1
- package/dist/templates/intent.md.tmpl +46 -0
- package/package.json +3 -7
package/dist/render.js
CHANGED
|
@@ -1,7 +1,14 @@
|
|
|
1
|
-
// src/
|
|
2
|
-
import {
|
|
1
|
+
// src/parser/intent.ts
|
|
2
|
+
import { existsSync, readFileSync, readdirSync, statSync } from "fs";
|
|
3
|
+
import { basename, join } from "path";
|
|
4
|
+
import matter from "gray-matter";
|
|
5
|
+
|
|
6
|
+
// src/parser/schemas.ts
|
|
7
|
+
import { z } from "zod";
|
|
3
8
|
|
|
4
9
|
// src/types.ts
|
|
10
|
+
var ENGINES = ["claude-code", "codex-cli", "opencode"];
|
|
11
|
+
var CAPABILITIES = ["multi-step", "slash-command", "inline-exec"];
|
|
5
12
|
var CAPABILITIES_MATRIX = {
|
|
6
13
|
"claude-code": ["multi-step", "slash-command", "inline-exec"],
|
|
7
14
|
"codex-cli": ["multi-step", "slash-command", "inline-exec"],
|
|
@@ -11,7 +18,53 @@ var DEGRADED_CAPABILITIES = {
|
|
|
11
18
|
"codex-cli": ["multi-step"]
|
|
12
19
|
};
|
|
13
20
|
|
|
21
|
+
// src/parser/schemas.ts
|
|
22
|
+
var IdSchema = z.string().min(1).regex(/^[a-z][a-z0-9-]*$/, "id must be kebab-case (lowercase + digits + hyphens)");
|
|
23
|
+
var SkillFrontmatterSchema = z.object({
|
|
24
|
+
id: IdSchema,
|
|
25
|
+
description: z.string().min(1),
|
|
26
|
+
engines: z.array(z.enum(ENGINES)).min(1).optional(),
|
|
27
|
+
requires: z.array(z.enum(CAPABILITIES)).optional(),
|
|
28
|
+
tags: z.array(z.string()).optional()
|
|
29
|
+
}).strict();
|
|
30
|
+
var CmdArgEnumSchema = z.object({
|
|
31
|
+
name: z.string().min(1),
|
|
32
|
+
type: z.literal("enum"),
|
|
33
|
+
values: z.array(z.string()).min(1),
|
|
34
|
+
default: z.string().optional(),
|
|
35
|
+
/** False when the command runs without the argument. Defaults to true. */
|
|
36
|
+
required: z.boolean().optional()
|
|
37
|
+
}).strict();
|
|
38
|
+
var CmdArgStringSchema = z.object({
|
|
39
|
+
name: z.string().min(1),
|
|
40
|
+
type: z.literal("string"),
|
|
41
|
+
default: z.string().optional(),
|
|
42
|
+
/** False when the command runs without the argument. Defaults to true. */
|
|
43
|
+
required: z.boolean().optional()
|
|
44
|
+
}).strict();
|
|
45
|
+
var CmdArgSchema = z.discriminatedUnion("type", [CmdArgEnumSchema, CmdArgStringSchema]);
|
|
46
|
+
var CmdFrontmatterSchema = z.object({
|
|
47
|
+
id: IdSchema,
|
|
48
|
+
trigger: z.string().regex(/^\/[a-z][a-z0-9-]*$/, "trigger must be /kebab-case"),
|
|
49
|
+
invokes_skill: IdSchema,
|
|
50
|
+
args: z.array(CmdArgSchema).optional(),
|
|
51
|
+
description: z.string().min(1)
|
|
52
|
+
}).strict();
|
|
53
|
+
var INTENT_STATUSES = ["proposed", "implemented", "deprecated"];
|
|
54
|
+
var IntentFrontmatterSchema = z.object({
|
|
55
|
+
title: z.string().min(1),
|
|
56
|
+
status: z.enum(INTENT_STATUSES),
|
|
57
|
+
actors: z.array(z.string().min(1)).min(1),
|
|
58
|
+
spec: z.union([z.string().min(1), z.array(z.string().min(1)).min(1)]),
|
|
59
|
+
last_reviewed: z.union([z.date(), z.string().min(1)])
|
|
60
|
+
}).strict();
|
|
61
|
+
|
|
62
|
+
// src/parser/intent.ts
|
|
63
|
+
var INTENTS_DIR = "docs/intents";
|
|
64
|
+
var INTENTS_INDEX_PATH = `${INTENTS_DIR}/README.md`;
|
|
65
|
+
|
|
14
66
|
// src/renderers/common.ts
|
|
67
|
+
import { stringify as yamlStringify } from "yaml";
|
|
15
68
|
function checkSkillCapabilities(skill, engine) {
|
|
16
69
|
const blockingWarnings = [];
|
|
17
70
|
const degradedWarnings = [];
|
|
@@ -57,22 +110,26 @@ function frontmatterDataForCmd(cmd) {
|
|
|
57
110
|
description: cmd.meta.description
|
|
58
111
|
};
|
|
59
112
|
if (cmd.meta.args && cmd.meta.args.length > 0) {
|
|
60
|
-
data.args = cmd.meta.args.map((a) => {
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
}
|
|
64
|
-
|
|
65
|
-
|
|
113
|
+
data.args = cmd.meta.args.map((a) => ({
|
|
114
|
+
name: a.name,
|
|
115
|
+
type: a.type,
|
|
116
|
+
...a.type === "enum" ? { values: a.values } : {},
|
|
117
|
+
...a.default !== void 0 ? { default: a.default } : {},
|
|
118
|
+
...a.required === false ? { required: false } : {}
|
|
119
|
+
}));
|
|
66
120
|
}
|
|
67
121
|
return data;
|
|
68
122
|
}
|
|
69
123
|
function buildUmbrellaBody(extras) {
|
|
70
|
-
const
|
|
71
|
-
|
|
72
|
-
|
|
124
|
+
const triggersBySkill = /* @__PURE__ */ new Map();
|
|
125
|
+
for (const c of extras.availableCommands) {
|
|
126
|
+
const triggers = triggersBySkill.get(c.meta.invokes_skill) ?? [];
|
|
127
|
+
triggers.push(c.meta.trigger);
|
|
128
|
+
triggersBySkill.set(c.meta.invokes_skill, triggers);
|
|
129
|
+
}
|
|
73
130
|
const skillLines = extras.availableSkills.map((s) => {
|
|
74
|
-
const
|
|
75
|
-
const label =
|
|
131
|
+
const triggers = triggersBySkill.get(s.meta.id) ?? [];
|
|
132
|
+
const label = triggers.length > 0 ? `\`${s.meta.id}\` (${triggers.map((t) => `\`${t}\``).join(", ")})` : `\`${s.meta.id}\``;
|
|
76
133
|
return `- ${label} \u2014 ${s.meta.description.split("\n")[0]}`;
|
|
77
134
|
});
|
|
78
135
|
const sections = [
|
|
@@ -92,11 +149,17 @@ function buildUmbrellaBody(extras) {
|
|
|
92
149
|
...extras.hasQualityDoc ? [
|
|
93
150
|
"- `docs/quality/code-quality.md` \u2014 the project's code-quality rules: mechanical checks, judgment rules, accepted deviations. Read it before writing or auditing code."
|
|
94
151
|
] : [],
|
|
152
|
+
...extras.hasIntents ? [
|
|
153
|
+
"- `docs/intents/<intent>.md` \u2014 user intents, one tree per level-1 intent, anchored to the code. `docs/intents/README.md` is the generated index."
|
|
154
|
+
] : [],
|
|
95
155
|
"",
|
|
96
156
|
"## Doc-first",
|
|
97
157
|
"",
|
|
98
158
|
"The order is: **understand the docs \u2192 fill the gaps \u2192 code \u2192 update the docs \u2192 commit**. If the docs are silent or stale on something you change, fill the gap upfront with the doc-skill writers \u2014 not downstream, not after the fact.",
|
|
99
159
|
"",
|
|
160
|
+
...extras.hasIntents ? [
|
|
161
|
+
"- Visible change of behavior \u2192 a `proposed` intent first (`/intent <verb + object>`), never the code first."
|
|
162
|
+
] : [],
|
|
100
163
|
"- Missing spec for a subsystem you touch \u2192 **do not code**, report the gap.",
|
|
101
164
|
"- Implicit structural decision in your changes \u2192 an ADR (`/decision`).",
|
|
102
165
|
"- Changed feature behavior \u2192 update the matching handbook (`/handbook`).",
|
|
@@ -225,6 +288,23 @@ function getRenderer(engine) {
|
|
|
225
288
|
return RENDERERS[engine];
|
|
226
289
|
}
|
|
227
290
|
|
|
291
|
+
// src/renderers/intents-index.ts
|
|
292
|
+
var INTRO = "User intents of this project, anchored to the code. Generated by `@vaubaan/harness` from `docs/intents/*.md`: edit the intents, not this file, then run `npx @vaubaan/harness update .`.";
|
|
293
|
+
function buildIntentsIndex(intentFiles) {
|
|
294
|
+
const lines = ["# Intents", "", INTRO, ""];
|
|
295
|
+
const sorted = [...intentFiles].sort((a, b) => a.file < b.file ? -1 : a.file > b.file ? 1 : 0);
|
|
296
|
+
for (const intentFile of sorted) {
|
|
297
|
+
const status = intentFile.meta?.status ?? "proposed";
|
|
298
|
+
const actors = intentFile.meta?.actors.join(", ") ?? "";
|
|
299
|
+
lines.push(`- [${intentFile.title}](./${intentFile.file}) \u2014 ${status} \xB7 ${actors}`);
|
|
300
|
+
for (const node of intentFile.nodes) {
|
|
301
|
+
lines.push(`${" ".repeat(node.level)}- ${node.title} \u2014 ${node.effectiveStatus ?? status}`);
|
|
302
|
+
}
|
|
303
|
+
}
|
|
304
|
+
return `${lines.join("\n")}
|
|
305
|
+
`;
|
|
306
|
+
}
|
|
307
|
+
|
|
228
308
|
// src/render.ts
|
|
229
309
|
var RenderError = class extends Error {
|
|
230
310
|
constructor(message) {
|
|
@@ -294,12 +374,16 @@ function render(input) {
|
|
|
294
374
|
availableSkills: Array.from(exposedSkills.values()),
|
|
295
375
|
availableCommands: Array.from(exposedCmds.values()),
|
|
296
376
|
hasProjectSkills: (input.projectSkills?.length ?? 0) > 0,
|
|
297
|
-
hasQualityDoc: input.hasQualityDoc === true
|
|
377
|
+
hasQualityDoc: input.hasQualityDoc === true,
|
|
378
|
+
hasIntents: (input.intentFiles?.length ?? 0) > 0
|
|
298
379
|
});
|
|
299
380
|
files.push({ path: "AGENTS.md", content: umbrellaContent });
|
|
300
381
|
if (engines.includes("claude-code")) {
|
|
301
382
|
files.push({ path: "CLAUDE.md", content: CLAUDE_MD_STUB });
|
|
302
383
|
}
|
|
384
|
+
if (input.intentFiles && input.intentFiles.length > 0) {
|
|
385
|
+
files.push({ path: INTENTS_INDEX_PATH, content: buildIntentsIndex(input.intentFiles) });
|
|
386
|
+
}
|
|
303
387
|
return { files, warnings };
|
|
304
388
|
}
|
|
305
389
|
export {
|
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/intent.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/intents-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 { INTENT_STATUSES, type IntentFrontmatter, type IntentStatus, Schemas } from \"./schemas.js\";\n\n/** The optional intents pillar (docs/spec/coding-agent-harness.md §9.1.3). */\nexport const INTENTS_DIR = \"docs/intents\";\n/** The generated index of the pillar; never an intent file. */\nexport const INTENTS_INDEX_PATH = `${INTENTS_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 terminal intent (a node with no sub-intent) may carry. */\nexport const TERMINAL_FIELDS: ReadonlyArray<NodeField> = [\n \"anchors\",\n \"acceptance\",\n \"requires\",\n \"creates\",\n];\n\nexport interface IntentError {\n line?: number;\n message: string;\n}\n\nexport interface IntentNode {\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 /** True when the node has no sub-intent: a terminal intent. */\n isTerminal: boolean;\n /** Line of each known field the node declares. */\n fieldLines: Partial<Record<NodeField, number>>;\n status?: IntentStatus;\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?: IntentStatus;\n}\n\nexport interface IntentFile {\n meta?: IntentFrontmatter;\n title: string;\n statement?: string;\n nodes: IntentNode[];\n errors: IntentError[];\n}\n\nexport interface ParsedIntentFile extends IntentFile {\n /** Path from the repo root, e.g. `docs/intents/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: IntentError[]): IntentFrontmatter | 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.Intent.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): IntentNode {\n return {\n title,\n level,\n line,\n isTerminal: 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: IntentNode,\n lines: ReadonlyArray<string>,\n from: number,\n to: number,\n errors: IntentError[],\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 ((INTENT_STATUSES as ReadonlyArray<string>).includes(value)) {\n node.status = value as IntentStatus;\n } else {\n errors.push({\n line: lineNo,\n message: `invalid status \\`${value}\\` (expected ${INTENT_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 intent file (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 parseIntentFile(relPath: string, text: string): IntentFile {\n const errors: IntentError[] = [];\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 statement: 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) statement = paragraph.join(\" \");\n }\n\n const nodes: IntentNode[] = [];\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.isTerminal = 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, ...(statement ? { statement } : {}), nodes, errors };\n}\n\n/** Intent files: `docs/intents/*.md` minus the generated index, sorted by file name. */\nexport function listIntentFiles(targetDir: string): string[] {\n const dir = join(targetDir, INTENTS_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 intent file without throwing; linters read their `errors`. */\nexport function readIntentFiles(targetDir: string): ParsedIntentFile[] {\n return listIntentFiles(targetDir).map((file) => {\n const path = `${INTENTS_DIR}/${file}`;\n const text = readFileSync(join(targetDir, path), \"utf8\");\n return { path, file, ...parseIntentFile(path, text) };\n });\n}\n\n/**\n * The intent files the render needs. One 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 loadIntentFiles(targetDir: string): ParsedIntentFile[] {\n const intentFiles = readIntentFiles(targetDir);\n const problems = intentFiles.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 intents (run \\`npx @vaubaan/harness lint --pillar intents\\`):\\n${problems.join(\"\\n\")}`,\n );\n }\n return intentFiles;\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 /** False when the command runs without the argument. Defaults to true. */\n required: z.boolean().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 /** False when the command runs without the argument. Defaults to true. */\n required: z.boolean().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 INTENT_STATUSES = [\"proposed\", \"implemented\", \"deprecated\"] as const;\nexport type IntentStatus = (typeof INTENT_STATUSES)[number];\n\n// gray-matter parses a bare YAML date (`2026-11-09`) into a Date object.\nconst IntentFrontmatterSchema = z\n .object({\n title: z.string().min(1),\n status: z.enum(INTENT_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 IntentFrontmatter = z.infer<typeof IntentFrontmatterSchema>;\n\nexport const Schemas = {\n Skill: SkillFrontmatterSchema,\n Cmd: CmdFrontmatterSchema,\n Intent: IntentFrontmatterSchema,\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 hasIntents?: 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 // `required` is rendered only when false: an argument is required by default.\n data.args = cmd.meta.args.map((a) => ({\n name: a.name,\n type: a.type,\n ...(a.type === \"enum\" ? { values: a.values } : {}),\n ...(a.default !== undefined ? { default: a.default } : {}),\n ...(a.required === false ? { required: false } : {}),\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: list every trigger, in\n // 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.hasIntents\n ? [\n \"- `docs/intents/<intent>.md` — user intents, one tree per level-1 intent, anchored to the code. `docs/intents/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.hasIntents\n ? [\n \"- Visible change of behavior → a `proposed` intent first (`/intent <verb + object>`), 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 { ParsedIntentFile } from \"../parser/intent.js\";\n\nconst INTRO =\n \"User intents of this project, anchored to the code. Generated by `@vaubaan/harness` from `docs/intents/*.md`: edit the intents, not this file, then run `npx @vaubaan/harness update .`.\";\n\n/**\n * `docs/intents/README.md`: every intent file (sorted by file name) and its\n * whole tree, one line per node with its effective status, the actors on\n * the level-1 intent line (docs/spec/coding-agent-harness.md §9.1.3).\n */\nexport function buildIntentsIndex(intentFiles: ReadonlyArray<ParsedIntentFile>): string {\n const lines = [\"# Intents\", \"\", INTRO, \"\"];\n const sorted = [...intentFiles].sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));\n for (const intentFile of sorted) {\n const status = intentFile.meta?.status ?? \"proposed\";\n const actors = intentFile.meta?.actors.join(\", \") ?? \"\";\n lines.push(`- [${intentFile.title}](./${intentFile.file}) — ${status} · ${actors}`);\n for (const node of intentFile.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 { INTENTS_INDEX_PATH, type ParsedIntentFile } from \"./parser/intent.js\";\nimport type { Skill } from \"./parser/skill.js\";\nimport { buildUmbrellaBody } from \"./renderers/common.js\";\nimport { getRenderer } from \"./renderers/index.js\";\nimport { buildIntentsIndex } from \"./renderers/intents-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/intents/*.md` (optional pillar); renders their index. */\n intentFiles?: ReadonlyArray<ParsedIntentFile>;\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 hasIntents: (input.intentFiles?.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 intents index is a generated file too, rendered only while an intent file exists.\n if (input.intentFiles && input.intentFiles.length > 0) {\n files.push({ path: INTENTS_INDEX_PATH, content: buildIntentsIndex(input.intentFiles) });\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`, `intents`, 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
|
+
- **intents** — `docs/intents/*.md`: what the user does and wants,
|
|
49
|
+
at every scale, one tree of intents anchored to the code (`README.md` there is generated).
|
|
48
50
|
|
|
49
51
|
## Procedure
|
|
50
52
|
|
|
@@ -142,6 +144,27 @@ 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
|
+
### Intents (optional pillar)
|
|
148
|
+
Audit **only if `docs/intents/` holds an intent file**. The linters
|
|
149
|
+
(`lint:intent-*`) already check the grammar, the anchors and the
|
|
150
|
+
vocabulary; you judge what they cannot.
|
|
151
|
+
- ⚠️ **Spec without intents**: a `docs/spec/*.md` file that no intent
|
|
152
|
+
file links in its `spec:` frontmatter. The subsystem has rules but no
|
|
153
|
+
documented user activity.
|
|
154
|
+
- ⚠️ **Terminal intent without a test**: an `implemented` terminal
|
|
155
|
+
intent none of whose
|
|
156
|
+
`anchors:` is a test file (by the project's test conventions, see
|
|
157
|
+
`docs/tests/`).
|
|
158
|
+
- ⚠️ **Pending increment**: a `proposed` intent whose intent file has not
|
|
159
|
+
changed for more than N commits (default 10). List them: they are the
|
|
160
|
+
backlog nobody delivered.
|
|
161
|
+
- ⚠️ **Criteria lost at delivery**: the tests anchored by an intent
|
|
162
|
+
delivered in the recent history (`git log` on the intent file) do not
|
|
163
|
+
restate its former `acceptance:` items in their titles.
|
|
164
|
+
- ❌ **Pillar drift**: a terminal intent carrying prose that states a business rule
|
|
165
|
+
(→ `spec/`) or how the code works (→ `handbook/`); a field the linter
|
|
166
|
+
does not know is already an error.
|
|
167
|
+
|
|
145
168
|
### Cross-link consistency
|
|
146
169
|
- ⚠️ Orphan spec: no decision, handbook or test references it.
|
|
147
170
|
- ⚠️ Orphan decision: not referenced by any other doc file.
|
|
@@ -159,6 +182,8 @@ This is *the* critical point where docs drift. Heuristics:
|
|
|
159
182
|
paraphrases generic principles (SOLID, Clean Code), what lengthily
|
|
160
183
|
justifies a structural decision (→ ADR) or describes the
|
|
161
184
|
implementation (→ handbook).
|
|
185
|
+
- intents/ (if present) must stay intents + pointers → flag an
|
|
186
|
+
intent that explains a rule or an implementation.
|
|
162
187
|
- Any architectural choice mentioned in a commit without an ADR → flag
|
|
163
188
|
(see "Implicit decisions").
|
|
164
189
|
|
|
@@ -217,6 +242,12 @@ invent empty sections):
|
|
|
217
242
|
- ❌ section "<section>" missing
|
|
218
243
|
- ⚠️ <cited tool or config file> not found in the repo
|
|
219
244
|
|
|
245
|
+
## Intents (optional — section omitted if docs/intents/ is absent)
|
|
246
|
+
|
|
247
|
+
- ⚠️ docs/spec/<name>.md — no intent file links it
|
|
248
|
+
- ⚠️ docs/intents/<slug>.md › <intent title> — implemented, no test anchor
|
|
249
|
+
- ⚠️ docs/intents/<slug>.md › <intent title> — proposed for N commits
|
|
250
|
+
|
|
220
251
|
## Cross-link consistency
|
|
221
252
|
|
|
222
253
|
- Orphan spec: <path>
|
|
@@ -239,8 +270,8 @@ invent empty sections):
|
|
|
239
270
|
|
|
240
271
|
- **Fix nothing**. You audit, you list, you recommend. The writers
|
|
241
272
|
(`spec-writer`, `decision-record-writer`, `handbook-writer`,
|
|
242
|
-
`test-plan-writer`, `workflow-writer`, `readme-writer
|
|
243
|
-
fix — not you.
|
|
273
|
+
`test-plan-writer`, `workflow-writer`, `readme-writer`,
|
|
274
|
+
`intent-writer`) are there to fix — not you.
|
|
244
275
|
- **Do not re-implement the mechanical linters**. If a check is already
|
|
245
276
|
covered by `vaubaan harness lint` (file presence, frontmatter schema,
|
|
246
277
|
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/intents/` 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
|
+
- An intent anchors a file that no longer exists, or
|
|
69
|
+
`requires:` an entity the spec vocabulary no longer defines →
|
|
70
|
+
hard drift.
|
|
71
|
+
- An intent 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` intent 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
|
+
intent (`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
|
+
- Intent 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 an intent node; `proposed` intent 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/intents/<slug>.md
|
|
143
|
+
|
|
144
|
+
- ❌ Intent "<title>" anchors `src/legacy/old.ts` — file deleted.
|
|
145
|
+
- ❌ Intent "<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/intents/<slug>.md
|
|
163
|
+
|
|
164
|
+
- ⚠️ Intent "<title>": its anchored `src/foo.ts:88` gained a guard the
|
|
165
|
+
user sees, no node for it.
|
|
166
|
+
- ⚠️ Intent "<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 intent anchors them. Suggested:
|
|
173
|
+
`/handbook new-feature` for the how, `/intent` to map 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. `/intent` to add the missing node or re-anchor the intent.
|
|
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
|
+
`intent-writer` via `/intent`) 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 an intent anchors the feature (`docs/intents/`), link its file
|
|
55
|
+
too: the intent says what the user does and where, the handbook says
|
|
56
|
+
how. Never restate the intent.
|
|
54
57
|
|
|
55
58
|
```markdown
|
|
56
59
|
---
|