@vaubaan/harness 2.4.0 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/README.md +207 -83
  2. package/dist/cli/index.js +4165 -843
  3. package/dist/cli/index.js.map +1 -1
  4. package/dist/commands/harn-canvas.cmd.md +23 -0
  5. package/dist/commands/{decision.cmd.md → harn-decision.cmd.md} +6 -6
  6. package/dist/commands/{doc-audit.cmd.md → harn-doc-audit.cmd.md} +7 -7
  7. package/dist/commands/{drift.cmd.md → harn-drift.cmd.md} +6 -6
  8. package/dist/commands/{handbook.cmd.md → harn-handbook.cmd.md} +6 -6
  9. package/dist/commands/harn-improve.cmd.md +20 -0
  10. package/dist/commands/{intent.cmd.md → harn-intent.cmd.md} +9 -9
  11. package/dist/commands/{readme.cmd.md → harn-readme.cmd.md} +6 -6
  12. package/dist/commands/{spec.cmd.md → harn-spec.cmd.md} +6 -6
  13. package/dist/commands/{test-plan.cmd.md → harn-test-plan.cmd.md} +6 -6
  14. package/dist/commands/harn-upgrade.cmd.md +22 -0
  15. package/dist/commands/{workflow.cmd.md → harn-workflow.cmd.md} +6 -6
  16. package/dist/index.d.ts +32 -3
  17. package/dist/index.js +533 -96
  18. package/dist/index.js.map +1 -1
  19. package/dist/init.d.ts +1 -1
  20. package/dist/init.js +468 -93
  21. package/dist/init.js.map +1 -1
  22. package/dist/linters/index.d.ts +3 -34
  23. package/dist/linters/index.js +996 -554
  24. package/dist/linters/index.js.map +1 -1
  25. package/dist/parser/index.d.ts +96 -6
  26. package/dist/parser/index.js +220 -10
  27. package/dist/parser/index.js.map +1 -1
  28. package/dist/render-BhUar2gf.d.ts +81 -0
  29. package/dist/render.d.ts +1 -1
  30. package/dist/render.js +233 -22
  31. package/dist/render.js.map +1 -1
  32. package/dist/skills/harn-canvas-review.skill.md +87 -0
  33. package/dist/skills/{decision-record-writer.skill.md → harn-decision-record-writer.skill.md} +2 -1
  34. package/dist/skills/{doc-audit.skill.md → harn-doc-audit.skill.md} +75 -26
  35. package/dist/skills/{drift-detector.skill.md → harn-drift-detector.skill.md} +15 -14
  36. package/dist/skills/harn-guide.skill.md +137 -0
  37. package/dist/skills/{handbook-writer.skill.md → harn-handbook-writer.skill.md} +2 -1
  38. package/dist/skills/{intent-writer.skill.md → harn-intent-writer.skill.md} +83 -16
  39. package/dist/skills/{readme-writer.skill.md → harn-readme-writer.skill.md} +4 -4
  40. package/dist/skills/harn-self-improve.skill.md +84 -0
  41. package/dist/skills/{spec-writer.skill.md → harn-spec-writer.skill.md} +8 -8
  42. package/dist/skills/{test-plan-writer.skill.md → harn-test-plan-writer.skill.md} +6 -5
  43. package/dist/skills/harn-upgrade.skill.md +171 -0
  44. package/dist/skills/{workflow-writer.skill.md → harn-workflow-writer.skill.md} +6 -5
  45. package/dist/templates/decisions-index.md.tmpl +11 -0
  46. package/dist/templates/handbook-index.md.tmpl +8 -0
  47. package/dist/templates/profile.md.tmpl +30 -0
  48. package/dist/types-CfUByAIr.d.ts +35 -0
  49. package/dist/view/index.d.ts +117 -0
  50. package/dist/view/index.js +3987 -0
  51. package/dist/view/index.js.map +1 -0
  52. package/package.json +5 -1
  53. package/dist/render-CTx7VNOK.d.ts +0 -45
@@ -0,0 +1,171 @@
1
+ ---
2
+ id: harn-upgrade
3
+ description: |
4
+ Moves a project to a newer version of @vaubaan/harness: pins the
5
+ package, previews and applies `update`, resolves the conflicts it
6
+ lists, then applies the migration notes of every version crossed
7
+ (kept in this skill, one entry per release). Use it when the human
8
+ asks to update or upgrade the harness, or when `lint:generated-fresh`
9
+ fails after the package version changed.
10
+ engines: [claude-code, codex-cli, opencode]
11
+ tags: [harness, upgrade]
12
+ ---
13
+
14
+ # Harness Upgrade
15
+
16
+ You move this project from the harness version that rendered it to a
17
+ newer one. `update` re-renders the generated files; it does not choose a
18
+ version, and it cannot do what a version asks of the project's own
19
+ files. That part is yours, and it is written below, version by version.
20
+
21
+ This file is rendered by the version *currently installed*: its notes
22
+ stop at that version. The notes of the target version arrive with it,
23
+ which is why step 3 comes before step 5.
24
+
25
+ ## Procedure
26
+
27
+ 1. **Read where the project is.** `harnessVersion` in
28
+ `.harness-manifest.json` is the version that rendered it (absent
29
+ before 1.1). Read how the project runs the harness: a dev dependency
30
+ in the package manifest, a pinned `npx @vaubaan/harness@<version>` in
31
+ CI or in the pre-commit hook, or the unpinned `npx`.
32
+ 2. **Choose the target with the human.** The latest version, unless
33
+ they name one. Read its changelog entries between the two versions
34
+ (`npm view @vaubaan/harness versions`, then the `CHANGELOG.md` of the
35
+ package). Crossing a major version: say so, and what it removes,
36
+ before touching anything.
37
+ 3. **Start from a clean tree**, on a branch named as the project's
38
+ workflow says, so the upgrade is one reviewable change. Then pin the
39
+ target wherever the project pins the harness: the dev dependency
40
+ (`npm install --save-dev @vaubaan/harness@<target>`), the CI file,
41
+ the hook. All of them, to the same version.
42
+ 4. **Preview.** `npx @vaubaan/harness update . --dry-run`. It writes
43
+ nothing. Read the writes, the removals and every warning.
44
+ 5. **Re-read this skill once the preview is clean**: after step 6 the
45
+ file on disk is the target version's, with the notes you need.
46
+ Until then, read them from the package:
47
+ `node_modules/@vaubaan/harness/dist/skills/harn-upgrade.skill.md`.
48
+ 6. **Resolve conflicts, then apply.** `update` stops before any write
49
+ when a generated path holds a file it did not write, or a generated
50
+ file edited by hand. For each one: move the content to its source
51
+ (`docs/`, `docs/skills/`, `.harness-overrides/`), or keep the file as
52
+ the project's with `--preserve <path>` and tell the human it will no
53
+ longer be refreshed. Never delete a file to get past the check. Then
54
+ `npx @vaubaan/harness update .`.
55
+ 7. **Apply the migration notes** below, for every version after the one
56
+ the project was on, up to the target, in order.
57
+ 8. **Lint.** `npx @vaubaan/harness lint`. A new version may bring new
58
+ checks: fix each with the skill its message names, never by disabling
59
+ the linter. A check you cannot satisfy in this change is a finding
60
+ for the human, not a reason to pin back silently.
61
+ 9. **Report**, then commit as the project's workflow says: from which
62
+ version to which, what was removed, what the notes made you change,
63
+ which files are preserved and therefore not refreshed, what is left.
64
+
65
+ ## Guardrails
66
+
67
+ - **Never skip a major.** From 1.x, go to the last 2.x first, lint
68
+ green, commit, then to 3.x.
69
+ - **Never edit a generated file** to make it match: change its source
70
+ and run `update .`.
71
+ - **A backup exists.** `update` prints the folder where it kept the
72
+ previous content of every file it touched. On a failed apply it rolls
73
+ back by itself; mention the folder in your report.
74
+ - **Rollback** is pinning the previous version and running `update .`
75
+ again; a version's notes say when that is not enough.
76
+ - **Do not adopt new pillars during an upgrade.** A new version may
77
+ offer some; that is a separate decision (`harn-guide`).
78
+
79
+ ## Migration notes
80
+
81
+ One entry per release that asks something of a project, newest first.
82
+ "Nothing to do" means `update .` is the whole migration.
83
+
84
+ ### 3.0
85
+
86
+ Breaking: pillars are active by presence, and only the README is
87
+ required; every shipped skill and command is prefixed with `harn-`.
88
+
89
+ - **Commands and skills are renamed**: `/spec` is `/harn-spec`, `/intent`
90
+ is `/harn-intent`, `/harness-upgrade` is `/harn-upgrade`, and so on;
91
+ `spec-writer` is `harn-spec-writer`, `harness-guide` is `harn-guide`.
92
+ `update` removes the old files and writes the new ones by itself.
93
+ Then search the project's own docs, scripts and CI for the old command
94
+ names and replace them. `update` warns on every project skill
95
+ (`docs/skills/`), override (`.harness-overrides/skills/`) or
96
+ `disable.yaml` entry that still names an old id: rename it, or it
97
+ becomes an extra skill instead of replacing the shipped one.
98
+
99
+ - **Nothing breaks for a project that has the six former pillars**:
100
+ their folders exist, so they are active and their skills stay.
101
+ - **A pillar folder you had only because the lint demanded it** (test
102
+ plans that say nothing, a workflow nobody follows): ask the human
103
+ whether to keep it. Deleting the folder, then `update .`, removes its
104
+ skill, its command and its checks.
105
+ - **`AGENTS.md` changes**: its map and rules now hold a line only for an
106
+ active pillar, and one line names the others. If the project preserved
107
+ `AGENTS.md`, tell the human it no longer reflects the pillars.
108
+ - **`lint:doc-layout`** no longer requires any folder; it now fails on a
109
+ pillar folder that holds no file. Fill it or remove it.
110
+ - **`check`** no longer requires `docs/`: only the README and the
111
+ `.gitignore` entries.
112
+ - **The `stop-hook` command is gone.** 2.x kept it as a silent no-op for
113
+ hook entries written by 1.x. Search `.claude/settings.json` and
114
+ `.codex/hooks.json` for `@vaubaan/harness stop-hook` and remove the
115
+ entry: it now fails on every turn. `update` warns when it finds one.
116
+ - **Custom skills** in `docs/skills/` or `.harness-overrides/` keep
117
+ working; they may now declare `pillars: [...]` to be rendered only
118
+ while one of those pillars is active.
119
+ - **Programmatic callers of `render()`**: `hasQualityDoc` is replaced by
120
+ `activePillars`.
121
+ - New, nothing to do unless wanted: the `add <pillar>` command, the
122
+ `profiles` pillar, the `harn-guide` and `harn-upgrade` skills; the
123
+ view of the context (`vaubaan-harness view`) and review sessions
124
+ (`/harn-canvas`); lessons from reviews (`/harn-improve`), which read
125
+ agent conversations only if the project lists them under
126
+ `lessons.sources` in `.harnessrc`. All of them write only under
127
+ `.vaubaan/`, already gitignored.
128
+
129
+ ### 2.4, 2.3.1
130
+
131
+ Nothing to do.
132
+
133
+ ### 2.3
134
+
135
+ The journeys pillar became the intents pillar. Only for a project that
136
+ has `docs/journeys/`:
137
+
138
+ 1. `git mv docs/journeys docs/intents`, then `update .`.
139
+ 2. Replace `/story` and `/journey` by `/harn-intent` in the project's own
140
+ docs, and `lint:journey-*` by `lint:intent-*` in a lint configuration.
141
+
142
+ ### 2.2, 2.1
143
+
144
+ Nothing to do.
145
+
146
+ ### 2.0
147
+
148
+ Breaking: generated files are committed, and the Stop hook is replaced
149
+ by the lint in CI and in the pre-commit hook.
150
+
151
+ 1. After `update .`: stale agent files and the OpenCode plugin are
152
+ removed; files 1.x wrote into engine settings (`.mcp.json`,
153
+ `.claude/settings.json`, `.codex/hooks.json`, `.codex/config.toml`,
154
+ `.opencode/opencode.json`) are left in place and are now the
155
+ project's.
156
+ 2. Remove the `npx -y @vaubaan/harness stop-hook` entry from
157
+ `.claude/settings.json` or `.codex/hooks.json`.
158
+ 3. Remove `AGENTS.md`, `CLAUDE.md`, `.claude/`, `.codex/`, `.agents/`,
159
+ `.opencode/`, `.harness-manifest.json`, `.harness/` and `.mcp.json`
160
+ from `.gitignore`; keep `.harness-overrides/` and `.vaubaan/`. Commit
161
+ the generated files.
162
+ 4. Run `npx @vaubaan/harness lint` in CI and add it to the pre-commit
163
+ hook.
164
+
165
+ ### 1.x
166
+
167
+ - From `@sbw-vaubaan/harness` (before 1.3): `uninstall .` with the old
168
+ package, then `init . --engines=<list>` with the new one.
169
+ - From 0.x or 1.0: re-run `init . --engines=<list>`; a manifest older
170
+ than version 4 is migrated by `update`, never by `init`.
171
+ - Within 1.x otherwise: `update --dry-run`, then `update`.
@@ -1,5 +1,5 @@
1
1
  ---
2
- id: workflow-writer
2
+ id: harn-workflow-writer
3
3
  description: |
4
4
  Updates `docs/workflow/coding-workflow.md`. Reads `.github/workflows/`,
5
5
  `vercel.json`, the `package.json` scripts, the repo's branch/PR
@@ -7,6 +7,7 @@ description: |
7
7
  PR process / branches / release).
8
8
  engines: [claude-code, codex-cli, opencode]
9
9
  requires: [multi-step]
10
+ pillars: [workflow]
10
11
  tags: [workflow, doc, writer, ci]
11
12
  ---
12
13
 
@@ -38,8 +39,8 @@ short.
38
39
 
39
40
  - The agent modifies a CI workflow, a deployment config, or a
40
41
  `package.json` script → update the workflow doc.
41
- - `doc-audit` flags `coding-workflow.md` as missing or stale.
42
- - `/workflow` invoked by the human.
42
+ - `harn-doc-audit` flags `coding-workflow.md` as missing or stale.
43
+ - `/harn-workflow` invoked by the human.
43
44
  - Onboarding: a new contributor needs a recap of the process.
44
45
 
45
46
  ## Procedure
@@ -94,7 +95,7 @@ short.
94
95
  ## Criteria
95
96
 
96
97
  - **5 sections present**. The `lint:cardinal-files` linter checks the
97
- file's presence; `doc-audit` checks the presence of the 5 required
98
+ file's presence; `harn-doc-audit` checks the presence of the 5 required
98
99
  sections by their header (regex). All 5 are mandatory; the
99
100
  Languages section is optional.
100
101
  - **Concrete and actionable**. Mention the exact commands
@@ -194,7 +195,7 @@ Finish by:
194
195
  command, read `package.json` or ask the human. A workflow doc with a
195
196
  wrong command is worse than no doc.
196
197
  - **No "because it's better" reasoning**. Justifications live in the
197
- ADRs (`decision-record-writer`). The workflow doc describes *what is
198
+ ADRs (`harn-decision-record-writer`). The workflow doc describes *what is
198
199
  in place*.
199
200
  - **Cross-link, do not duplicate**. The content of `ci.yml` is not
200
201
  copied here — we link to the file. The workflow doc *summarizes* and
@@ -0,0 +1,11 @@
1
+ # Decisions
2
+
3
+ The structural decisions in force in this project, one file per
4
+ decision, `<slug>.md`, no numbering. Each has four sections: Context,
5
+ Decision, Consequences, Rejected alternatives. A decision that changes
6
+ is rewritten as a new file; the old one is deleted and its option moves
7
+ to the Rejected alternatives of the new one.
8
+
9
+ ## Decisions in force
10
+
11
+ <!-- One bullet per decision, newest first: its title as a link to its file, then the rule in one sentence. -->
@@ -0,0 +1,8 @@
1
+ # Handbook
2
+
3
+ What the code of this project does not say: entry points, invariants
4
+ across files, traps, settings outside the repo, manual procedures. One
5
+ `<slug>.md` per feature, no numbering; each declares the code it depends
6
+ on in `tracks:`.
7
+
8
+ <!-- One bullet per handbook: its title as a link to its file, then what it covers. -->
@@ -0,0 +1,30 @@
1
+ ---
2
+ title: <WHO THEY ARE, IN A FEW WORDS>
3
+ status: hypothesis
4
+ last_reviewed: <DATE>
5
+ ---
6
+
7
+ # <WHO THEY ARE>
8
+
9
+ <!--
10
+ One file per kind of user the project serves; the file name is the name
11
+ the intents use in `actors:`. A profile is a `hypothesis` until research
12
+ backs it: then set `status: validated` and add `evidence:`, a relative
13
+ path to a file of the repo or a URL. Never copy interview notes here.
14
+
15
+ A pain is what the user lives, not a missing feature. The most severe
16
+ first: the order is the rank. Each bullet opens with its name in bold;
17
+ `**Context rot**` is referred to as `context-rot` in an intent's
18
+ `relieves:`. No jobs section: the profile's jobs are the intents that
19
+ name it. Target 20-40 lines.
20
+ -->
21
+
22
+ <One paragraph: who they are and in what situation.>
23
+
24
+ ## Pains
25
+
26
+ - **<Name of the pain>** — <what hurts or blocks them today>
27
+
28
+ ## Gains
29
+
30
+ - **<Name of the gain>** — <the outcome they hope for>
@@ -0,0 +1,35 @@
1
+ interface HarnessLintConfig {
2
+ ignore: ReadonlyArray<string>;
3
+ }
4
+ declare function loadLintConfig(repoRoot: string): HarnessLintConfig;
5
+
6
+ type Severity = "error" | "warning";
7
+ interface LintIssue {
8
+ linter: string;
9
+ severity: Severity;
10
+ file: string;
11
+ line?: number;
12
+ message: string;
13
+ }
14
+ interface LintContext {
15
+ repoRoot: string;
16
+ config: HarnessLintConfig;
17
+ }
18
+ interface Linter {
19
+ id: string;
20
+ pillars: ReadonlyArray<string>;
21
+ defaultSeverity: Severity;
22
+ suggestedSkills?: ReadonlyArray<string>;
23
+ run(repoRoot: string, ctx?: LintContext): LintIssue[];
24
+ }
25
+ interface LintReport {
26
+ version: 1;
27
+ summary: {
28
+ errors: number;
29
+ warnings: number;
30
+ pass: boolean;
31
+ };
32
+ issues: LintIssue[];
33
+ }
34
+
35
+ export { type HarnessLintConfig as H, type LintContext as L, type Severity as S, type LintIssue as a, type LintReport as b, type Linter as c, loadLintConfig as l };
@@ -0,0 +1,117 @@
1
+ import { b as LintReport, a as LintIssue } from '../types-CfUByAIr.js';
2
+
3
+ type Domain = "harness" | "project" | "local";
4
+ declare const NODE_TYPES: readonly ["readme", "spec", "section", "term", "decision", "alternative", "handbook", "test-plan", "known-gap", "workflow", "quality", "doc", "intent-file", "intent", "linter", "skill", "command", "rendered-file", "path", "glob", "lesson"];
5
+ type NodeType = (typeof NODE_TYPES)[number];
6
+ type EdgeType = "contains" | "tracks" | "anchors" | "requires" | "creates" | "spec" | "links-to" | "gap-of" | "checks" | "suggests" | "invokes" | "renders-to";
7
+ type AttrValue = string | number | boolean | null | string[] | {
8
+ [k: string]: AttrValue;
9
+ };
10
+ interface GraphNode {
11
+ id: string;
12
+ type: NodeType;
13
+ domain: Domain;
14
+ title: string;
15
+ /** Path from the repo root, or the package name for a harness node. */
16
+ sourcePath: string;
17
+ /** 1-based; 0 when the node has no line of its own. */
18
+ line: number;
19
+ parent?: string;
20
+ attrs: Record<string, AttrValue>;
21
+ issues: LintIssue[];
22
+ }
23
+ interface GraphEdge {
24
+ from: string;
25
+ to: string;
26
+ type: EdgeType;
27
+ line: number;
28
+ }
29
+ interface ContextGraph {
30
+ version: 1;
31
+ harness: string;
32
+ nodes: GraphNode[];
33
+ edges: GraphEdge[];
34
+ lint: {
35
+ ran: boolean;
36
+ errors: number;
37
+ warnings: number;
38
+ unattached: LintIssue[];
39
+ };
40
+ }
41
+ interface BuildOptions {
42
+ /** Run the linters and attach their issues (default true). */
43
+ lint?: boolean;
44
+ /** A report already computed; skips running the linters. */
45
+ report?: LintReport;
46
+ /** Directory holding the shipped `skills/` and `commands/`. */
47
+ packageDir?: string;
48
+ }
49
+ declare function buildGraph(repoRoot: string, opts?: BuildOptions): ContextGraph;
50
+ /** The graph as written to `.vaubaan/graph.json`. */
51
+ declare function serializeGraph(graph: ContextGraph): string;
52
+ declare const GRAPH_PATH: string;
53
+
54
+ interface ThreadMessage {
55
+ author: "human" | "agent";
56
+ body: string;
57
+ at: string;
58
+ changes?: Array<{
59
+ path: string;
60
+ line: number;
61
+ }>;
62
+ }
63
+ interface Thread {
64
+ id: string;
65
+ anchor: {
66
+ nodeId: string;
67
+ sourcePath: string;
68
+ line: number;
69
+ };
70
+ status: "open" | "submitted" | "answered" | "resolved";
71
+ batch?: number;
72
+ messages: ThreadMessage[];
73
+ }
74
+ interface JournalEntry {
75
+ at: string;
76
+ files: string[];
77
+ errors: number;
78
+ warnings: number;
79
+ note?: string;
80
+ }
81
+ /** What a review session adds to the view; absent for the static page. */
82
+ interface SessionView {
83
+ id: string;
84
+ /** The graph at the session start, for the differences. */
85
+ base: ContextGraph;
86
+ threads: Thread[];
87
+ journal: JournalEntry[];
88
+ /** Graph revision, bumped on each rebuild. */
89
+ revision: number;
90
+ }
91
+ interface RenderOptions {
92
+ session?: SessionView;
93
+ /** Prefix of source links; the static page sits two levels under the repo root. */
94
+ sourcePrefix?: string;
95
+ }
96
+ /** A stable HTML id for a node id. */
97
+ declare function htmlId(nodeId: string): string;
98
+ declare function renderView(graph: ContextGraph, opts?: RenderOptions): string;
99
+
100
+ interface ViewArgs {
101
+ targetDir: string;
102
+ /** Directory receiving `graph.json` and `view/index.html`; default `<target>/.vaubaan`. */
103
+ outDir?: string;
104
+ /** Skip the linters (faster; no issue attached). */
105
+ lint?: boolean;
106
+ packageDir?: string;
107
+ }
108
+ interface ViewResult {
109
+ graph: ContextGraph;
110
+ graphPath: string;
111
+ htmlPath: string;
112
+ }
113
+ declare const VIEW_PATH = ".vaubaan/view/index.html";
114
+ /** Builds the context graph and renders the view (docs/spec/coding-agent-harness.md §10.4). */
115
+ declare function viewCommand(args: ViewArgs): ViewResult;
116
+
117
+ export { type AttrValue, type BuildOptions, type ContextGraph, type Domain, type EdgeType, GRAPH_PATH, type GraphEdge, type GraphNode, type JournalEntry, NODE_TYPES, type NodeType, type RenderOptions, type SessionView, type Thread, type ThreadMessage, VIEW_PATH, type ViewArgs, type ViewResult, buildGraph, htmlId, renderView, serializeGraph, viewCommand };