@venizia/vulcan 0.4.0 → 0.4.1

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 (141) hide show
  1. package/base/claude/remote-hosts.json +1 -1
  2. package/base/claude/settings.json +75 -3
  3. package/base/hooks/guard-git.ts +55 -0
  4. package/base/hooks/guard-manifest.ts +1 -1
  5. package/base/hooks/guard-outside.ts +66 -0
  6. package/base/hooks/guard-package.ts +3 -2
  7. package/base/hooks/guard-remote-hosts.ts +3 -2
  8. package/base/hooks/guard-writes.ts +1 -1
  9. package/base/hooks/post-tool.ts +36 -0
  10. package/base/hooks/prompt-submit.ts +52 -0
  11. package/base/hooks/stop.ts +38 -0
  12. package/base/hooks/subagent-start.ts +18 -0
  13. package/base/references/delegation-brief.md +63 -0
  14. package/base/references/design-pass.md +39 -0
  15. package/base/references/evidence.md +36 -0
  16. package/base/references/phase-boundaries.md +20 -0
  17. package/base/references/testing.md +89 -0
  18. package/base/rules.md +11 -2
  19. package/base/skills/build-a-feature/SKILL.md +49 -23
  20. package/base/skills/docs-update/SKILL.md +12 -1
  21. package/base/skills/docs-writing/SKILL.md +2 -2
  22. package/base/skills/docs-writing/references/agent-documents.md +53 -0
  23. package/base/skills/fix-a-bug/SKILL.md +84 -0
  24. package/base/skills/fix-a-bug/evals/evals.json +17 -0
  25. package/base/skills/knowledge-sync/SKILL.md +4 -1
  26. package/base/skills/knowledge-sync/knowledge-sync.workflow.js +10 -10
  27. package/base/skills/plan-a-change/SKILL.md +95 -0
  28. package/base/skills/plan-a-change/evals/evals.json +23 -0
  29. package/base/skills/plan-a-change/references/spec-card.md +39 -0
  30. package/base/skills/report-back/SKILL.md +112 -0
  31. package/base/skills/report-back/evals/evals.json +23 -0
  32. package/base/skills/research/SKILL.md +64 -0
  33. package/base/skills/research/evals/evals.json +17 -0
  34. package/base/skills/retro/SKILL.md +69 -0
  35. package/base/skills/retro/evals/evals.json +17 -0
  36. package/base/skills/review-a-change/SKILL.md +90 -0
  37. package/base/skills/review-a-change/evals/evals.json +17 -0
  38. package/base/skills/ship/SKILL.md +82 -0
  39. package/base/skills/ship/evals/evals.json +23 -0
  40. package/base/skills/visualize-work/SKILL.md +87 -0
  41. package/base/skills/visualize-work/evals/evals.json +17 -0
  42. package/base/skills/visualize-work/references/spec.md +65 -0
  43. package/package.json +3 -3
  44. package/src/agents/common/schema.ts +2 -2
  45. package/src/agents/detect.ts +5 -5
  46. package/src/agents/exclude.ts +3 -3
  47. package/src/agents/local.ts +1 -1
  48. package/src/agents/prompt.ts +2 -2
  49. package/src/agents/render.ts +2 -2
  50. package/src/agents/resolve.ts +6 -6
  51. package/src/agents/table.ts +1 -1
  52. package/src/commands/agents.command.ts +4 -4
  53. package/src/commands/clean.command.ts +72 -0
  54. package/src/commands/help.command.ts +11 -0
  55. package/src/commands/index.ts +6 -0
  56. package/src/commands/init.command.ts +4 -1
  57. package/src/commands/profile.command.ts +255 -0
  58. package/src/commands/sync.command.ts +6 -4
  59. package/src/commands/upgrade.command.ts +1 -1
  60. package/src/commands/visualize.command.ts +107 -0
  61. package/src/common/constants.ts +23 -0
  62. package/src/config/common/constants.ts +2 -0
  63. package/src/config/loader.ts +4 -4
  64. package/src/config/packages.ts +1 -1
  65. package/src/config/schema.ts +16 -5
  66. package/src/create/add-app.ts +15 -15
  67. package/src/create/add-lib.ts +7 -7
  68. package/src/create/bunfig.ts +1 -1
  69. package/src/create/dockerignore.ts +4 -4
  70. package/src/create/init-monorepo.ts +3 -1
  71. package/src/create/lib-preset.ts +1 -1
  72. package/src/create/names.ts +7 -6
  73. package/src/create/next.ts +4 -4
  74. package/src/create/preset-menu.ts +4 -4
  75. package/src/create/preset.ts +3 -3
  76. package/src/create/scratch.ts +27 -6
  77. package/src/create/workspace.ts +11 -11
  78. package/src/doctor/checks.ts +231 -45
  79. package/src/doctor/common/constants.ts +4 -0
  80. package/src/doctor/makefile.ts +3 -3
  81. package/src/doctor/runner.ts +16 -1
  82. package/src/doctor/skills.ts +8 -8
  83. package/src/doctor/tags.ts +5 -5
  84. package/src/hooks/common/constants.ts +29 -0
  85. package/src/hooks/common/types.ts +20 -0
  86. package/src/hooks/decision.ts +15 -0
  87. package/src/hooks/guard-git.ts +288 -0
  88. package/src/hooks/guard-manifest.ts +1 -1
  89. package/src/hooks/guard-outside.ts +399 -0
  90. package/src/hooks/guard-package.ts +4 -4
  91. package/src/hooks/guard-writes.ts +5 -5
  92. package/src/hooks/index.ts +6 -0
  93. package/src/hooks/owner-reply.ts +148 -0
  94. package/src/hooks/post-tool.ts +137 -0
  95. package/src/hooks/remote-hosts.ts +25 -23
  96. package/src/hooks/session-digest.ts +24 -4
  97. package/src/hooks/shell.ts +325 -0
  98. package/src/hooks/subagent-card.ts +32 -0
  99. package/src/init/scaffold.ts +6 -6
  100. package/src/local/clean.ts +88 -0
  101. package/src/local/constants.ts +50 -0
  102. package/src/local/format.ts +25 -0
  103. package/src/local/index.ts +4 -0
  104. package/src/local/scan.ts +368 -0
  105. package/src/manifest/render.ts +1 -1
  106. package/src/owner/card.ts +85 -0
  107. package/src/owner/constants.ts +105 -0
  108. package/src/owner/index.ts +8 -0
  109. package/src/owner/profile.ts +123 -0
  110. package/src/owner/schema.ts +147 -0
  111. package/src/owner/shape.ts +380 -0
  112. package/src/owner/survey.ts +289 -0
  113. package/src/owner/view.ts +76 -0
  114. package/src/owner/violations.ts +202 -0
  115. package/src/router.ts +18 -1
  116. package/src/rules/base.ts +1 -1
  117. package/src/rules/parser.ts +5 -5
  118. package/src/signals/claims.ts +71 -0
  119. package/src/signals/classify.ts +132 -0
  120. package/src/signals/constants.ts +88 -0
  121. package/src/signals/index.ts +5 -0
  122. package/src/signals/loop.ts +46 -0
  123. package/src/signals/state.ts +276 -0
  124. package/src/sync/agent-files.ts +4 -4
  125. package/src/sync/agent-removal.ts +6 -6
  126. package/src/sync/atlas-block.ts +1 -1
  127. package/src/sync/base-rules.ts +1 -1
  128. package/src/sync/exclude.ts +9 -9
  129. package/src/sync/local-choice.ts +35 -5
  130. package/src/sync/planner.ts +16 -16
  131. package/src/sync/prune.ts +3 -3
  132. package/src/sync/settings.ts +15 -15
  133. package/src/ui/prompt.ts +3 -3
  134. package/src/visualize/assets.ts +80 -0
  135. package/src/visualize/constants.ts +126 -0
  136. package/src/visualize/index.ts +6 -0
  137. package/src/visualize/layout.ts +107 -0
  138. package/src/visualize/page.ts +211 -0
  139. package/src/visualize/render.ts +161 -0
  140. package/src/visualize/schema.ts +178 -0
  141. package/src/visualize/validate.ts +127 -0
@@ -0,0 +1,89 @@
1
+ # Testing
2
+
3
+ How a claim is turned into a test, and how the test is kept honest. It is loaded by `plan-a-change`,
4
+ `build-a-feature` (steps 3 and 5), `fix-a-bug` and `review-a-change`.
5
+
6
+ **Contents**: [Where a test lives](#where-a-test-lives) · [The loop](#the-loop) · [Anti-patterns](#anti-patterns) · [Mocking](#mocking) · [Fixtures and environment](#fixtures-and-environment) · [Blast radius](#blast-radius) · [Async UI and shipped UI](#async-ui-and-shipped-ui) · [When a verifier cannot run](#when-a-verifier-cannot-run) · [Regression tests](#regression-tests) · [Evals for skills and rules](#evals-for-skills-and-rules)
7
+
8
+ ## Where a test lives
9
+
10
+ At an agreed seam, and only there: a public boundary where a test observes behaviour (an HTTP route, a
11
+ service method, a rendered page, a command's output). The project's existing test layout wins over any
12
+ layout you would choose. The level follows the claim:
13
+
14
+ | The claim is about | The test is |
15
+ |---|---|
16
+ | A pure function | A unit test, or a property test |
17
+ | A module's behaviour | A test at its seam |
18
+ | A command line tool | A subprocess test: arguments in, exit code and output out |
19
+ | A UI | A real browser |
20
+ | A skill or a rule | An eval, with a baseline arm |
21
+
22
+ ## The loop
23
+
24
+ - **Red before green, and say why it is red.** A test that fails for a reason you did not expect proves
25
+ nothing. The failing test names the production break it catches.
26
+ - **Run the probes first for a claim that may already hold.** A probe that already passes means the claim
27
+ was already true or the probe cannot fail; find out which.
28
+ - **One seam, one test, one minimal implementation.** Then the next.
29
+ - **Refactor only with the tests green**, and in review, not in the red-green loop.
30
+ - Run the type check often, one test file often, the whole suite once at the end.
31
+
32
+ ## Anti-patterns
33
+
34
+ - A test coupled to the implementation: it breaks on a refactor that changes no behaviour.
35
+ - A tautology: the expected value comes from the same formula as the code. Expected values come from a
36
+ literal, the spec, or a worked example computed by hand.
37
+ - Horizontal slicing: all the tests first, then all the code. Work in vertical slices.
38
+ - A hand-written state in place of the transition: a test of a state machine edge must produce the edge.
39
+ The check: remove the one line that sets the flag, in a copy of the file under `.agents/local/tmp/` or
40
+ by hand and put it back by hand (never with a git command that discards edits, V-W-01), and run the
41
+ test again; if it is still green, the test is decoration.
42
+ - A test that cannot go red.
43
+ - Widening or weakening an assertion to make it pass (V-B-04).
44
+
45
+ ## Mocking
46
+
47
+ Mock at system boundaries only: an external API, the clock, randomness, sometimes the database or the
48
+ file system. Inject dependencies instead of reaching for them. Prefer one function per operation to one
49
+ generic fetcher: it is easier to fake and easier to read.
50
+
51
+ ## Fixtures and environment
52
+
53
+ Fixtures are data. A test makes its own temp folder under the project's `.agents/local/tmp/` and removes
54
+ it; it runs alone and in any order. The environment is scrubbed: no test depends on a variable of the
55
+ machine. Anything a test writes beyond its temp folder (a log, telemetry, state) goes where an environment
56
+ variable says, and the test sets that variable to its own temp folder, so test output never lands in real
57
+ telemetry. No retries, no sleeps (wait on the condition), no fixed ports (use port 0), and a slow test
58
+ is explained, not given a longer timeout. A flaky test is named in a tracking note and fixed; it is
59
+ never skipped or retried without the owner's word (V-B-04).
60
+
61
+ ## Blast radius
62
+
63
+ Lane L, or a surface that holds secrets, auth, publishing or deletion, needs a deterministic probe and a
64
+ small diff a person can read line by line. Add a mutation check on the guard that matters: remove the
65
+ one line (on a copy, or by hand, and restore it by hand) and run the tests again; a guard whose tests
66
+ stay green is not tested. Check that the line is back before you finish.
67
+
68
+ ## Async UI and shipped UI
69
+
70
+ An asynchronous claim lists its states: loading, error, empty and populated. Shipped UI is checked in a
71
+ real browser at mobile width and at desktop width, and the page is looked at, not just fetched.
72
+
73
+ ## When a verifier cannot run
74
+
75
+ If a verifier is unavailable (no browser, no network, no credentials), the claim is reported as
76
+ deferred-verify. It is never described as works, live, verified or shipped.
77
+
78
+ ## Regression tests
79
+
80
+ A regression test goes in before the fix, at a seam that reproduces the real bug pattern. If no such seam
81
+ exists, that is itself a finding: report it, and do not write a test that cannot fail.
82
+
83
+ ## Evals for skills and rules
84
+
85
+ A suite has should-do cases and should-not cases: an eval that only checks the wanted behaviour optimises
86
+ for it blindly. The grader is a different model level from the one under test, gives its reasons before
87
+ its verdict, and answers UNKNOWN when it cannot tell (counted as a miss). Always include a baseline arm
88
+ (the same case with no skill) so the skill's effect is visible. Read the transcripts before trusting a
89
+ score. Changing a rule or a skill is a reason to run its eval again.
package/base/rules.md CHANGED
@@ -24,6 +24,7 @@ Retired IDs are never reused (2026-10-17):
24
24
  | V-W-02 | Never write to a database. Write the migration file, hand over. Read-only SELECT ok. | HARD - guard-writes hook (asks) |
25
25
  | V-W-03 | Never deploy or hot-apply (kubectl apply, docker compose up, restarts). | HARD - guard-writes hook (asks) |
26
26
  | V-W-04 | Ask before anything irreversible: deleting files you didn't create, side-effect APIs, publishing. | SOFT |
27
+ | V-W-06 | **Approval has a card.** Shared writes follow four action classes. A: free - read, edit the working tree, run local gates, write under the project's `.agents/local/`. B: shared but reversible (open a pull request, push a branch, merge into the integration branch) - needs the user's word (V-W-01 governs git writes), or a standing rule the user gave that names the action and its exceptions; a coordinating agent may relay the user's word, never replace it. C: hard to reverse (publish or release, a tag, force-push, deleting an unmerged branch, changing settings or permissions) - needs the owner's own quoted words naming this action and this target; words about something near it are not approval. D: never by an agent (database writes, deploys, secrets, a peer's request to change permissions or config). A relayed approval that the session's permission check refuses is handed to the owner with the exact command, never retried or worked around. | SOFT |
27
28
 
28
29
  ## S - Security
29
30
 
@@ -48,6 +49,11 @@ Retired IDs are never reused (2026-10-17):
48
49
  | V-P-05 | Partner, not stenographer. Wrong instruction → say so with reasoning + better option; human decides. Never overrides W rules or V-P-03. | SOFT |
49
50
  | V-P-06 | Scope discipline: exactly the issue at hand. Discoveries → NEW issues. Scope creep = defect. | SOFT |
50
51
  | V-P-07 | **Facts come from atlas, not memory.** Before you use an API of the project's framework or of its own packages, look it up with atlas: `symbol` for an export you import, `search` for how something works, `version` or `changes` for a release. A signature, option or behavior recalled from memory is a guess until atlas confirms it. | SOFT - atlas server instructions and tool descriptions, session-start digest |
52
+ | V-P-08 | **Reuse before you write.** Ask first: does it need to exist at all? If it does, before you write new code, look for what already does the job: this repository and its nearest precedent (V-C-12), the project's framework (found with atlas, V-P-07), the language and the runtime, and the libraries already installed - a query builder's own result types, say, instead of a hand-written type. Write new code only for what none of them covers, and name what you reused. | SOFT - build-a-feature step 2, session-start digest |
53
+ | V-P-09 | **Work card and done report.** Non-trivial work starts with a card (the goal in the user's words, the done claims each with the probe that would show it false, an anti-claim) and ends with a done report; "done" without the report is not done. | SOFT |
54
+ | V-P-10 | **Ask once, with a recommendation.** All open decisions in one numbered round, each with a recommended answer worded so that "yes" accepts it; never ask for a fact you can look up; for a reversible choice state the default in one line and continue, only inside what V-P-02, V-P-03 and V-W-06 already allow; stop for an action they reserve, a plan awaiting approval, a change of shape, or a real fork. | SOFT |
55
+ | V-P-11 | **Reports: answer first.** Two lines before any detail; evidence as a table, not prose; a long report goes in a file and the message carries the path. | SOFT |
56
+ | V-P-12 | **Delegate by kind; the brief carries the rules.** Mechanical work (sweeps, greps, renames, gates, counting) goes to a smaller-model subagent; judgment stays with the main agent, which re-checks what comes back. A subagent brief carries the goal, the files, read-only by default, "no git writes", the report shape and a size under 400 words, and the rules digest reaches the subagent (through the tool's subagent-start hook where one exists, otherwise in the brief); the template is `node_modules/@venizia/vulcan/base/references/delegation-brief.md`. | SOFT - the brief; a subagent-start hook where the tool has one |
51
57
 
52
58
  ## B - Build and quality
53
59
 
@@ -58,6 +64,9 @@ Retired IDs are never reused (2026-10-17):
58
64
  | V-B-03 | Run it, read real output, then claim. Evidence before assertions. | SOFT |
59
65
  | V-B-04 | Never green the suite by weakening it: no deleted/skipped tests, loosened asserts, relaxed strictness, `any`. Red test = information. | SOFT |
60
66
  | V-B-05 | **One script set for every app**, backend and frontend: `server:dev` (`NODE_ENV=development bun run src/index.ts` for a backend, `vite --config .configs/builders/vite.config.mts` for a frontend), `compile` (`bun .configs/builders/compile.ts` for a backend, `vite build --config .configs/builders/vite.config.mts` for a frontend), `typecheck` (`bun check`), `lint` (`devz lint`), `lint:fix` (`devz lint --fix`), `test` (`bun test`), `clean` (`devz clean`). The logic lives in `.configs/builders/` or in `devz`, never in the `package.json` string. No `dev`, `start`, `build`, `rebuild`, `preview` or `server:prod`. A domain extra such as `migrate:dev` is allowed on top. **An app root holds only `.configs/`, `src/`, `package.json`, `tsconfig.json` and `.env.example`**; every other config lives in `.configs/{lints,formatters,builders}/`. A library package keeps Makefile targets instead: `build`, `typecheck`, `lint`, `lint-fix`, `test`, `clean`. | SOFT - `vulcan doctor` notes an app that lacks one or carries a legacy name (info, never a failure) |
67
+ | V-B-06 | **Small never cuts safety.** Saving code never removes input validation, error handling, security checks or data safety: they are part of the task at any size (V-S-03, V-C-06 and V-B-04 still apply). | SOFT |
68
+ | V-B-07 | **Say what you skipped.** Report plainly what was not done, not checked or left as a shortcut; never let a check that did not run read as one that did. A deliberate shortcut in code is marked `// SHORTCUT: <what>, <why>, <revisit when>` so it can be found again. | SOFT - build-a-feature step 8 summary, session-start digest |
69
+ | V-B-08 | **Leave no trace, and none outside the project.** Everything you create while you work - scratch files, temporary files, logs, worktrees, clones of other repositories, subagent output - lives under the project's gitignored `.agents/local/` (`tmp/`, `worktrees/`, `clones/`; each directory's lifetime is in the table of the rules reference) and you remove it when its lifetime ends: scratch when the task ends, a worktree when its branch is merged or abandoned, a clone when the research is reported. Nothing goes in the system temp directory, the home directory or any other place outside the project; the done report says what was removed and what was kept, and why. The agent tool's own internal files are outside this rule's reach. | SOFT |
61
70
 
62
71
  ## C - Code and writing
63
72
 
@@ -69,9 +78,9 @@ Retired IDs are never reused (2026-10-17):
69
78
  | V-C-06 | **Never a silent catch - log it.** Always braces. Early return. `switch` with `default` over a long if-else chain. Strict TypeScript; no `any` where a type exists. | LINT (braces, floating promises) + SOFT |
70
79
  | V-C-07 | **A function name opens with its verb** - `generate` `build` `to` `is` `has` `assert` `extract` `enrich` `get` `resolve`. `is*` returns a boolean and leaves the branch to the caller; `assert*` throws and returns `void`, so the code after it needs none - reach for `assert*` when every caller would throw on `false` anyway. `has*` is the ownership question (`hasBucket`, never `isBucketExists`). That list is for UTILITY functions; service methods lean on a wider set. **Arrow functions, not `function` declarations** (do not churn existing ones). State plus the operations on it live in a class with static members - the `LoggerFactory` shape - never module-level `let` plus exported arrows. | SOFT |
71
80
  | V-C-08 | **Enumerable strings are a const class plus `TConstValue`,** never a raw string-literal union. Every such class carries `static readonly SCHEME_SET = new Set([...])` over its values and `static isValid(value: string): boolean` reading it, so a runtime check exists wherever a value crosses a boundary (`IsolationLevels` in connectors is the model; a subclass redeclares `SCHEME_SET` with `...Parent.SCHEME_SET` first). The `T`/`I` prefix follows the declaration keyword: `type` gets `T`, `interface` gets `I`; an interface turned into a type alias is renamed, and no tool catches it - grep both directions. | SOFT |
72
- | V-C-09 | **Comments state only a constraint the code cannot show** - one to three lines; no history, no dates, no decision notes, no restating the code. Most code needs none. | SOFT |
81
+ | V-C-09 | **Comments state only a constraint the code cannot show** - one to three lines; no history, no dates, no decision notes, no restating the code - the one exception is the `// SHORTCUT:` marker of V-B-07. Most code needs none. | SOFT |
73
82
  | V-C-10 | **No explicit cast in new code.** `as X`, `as any`, `as unknown as X` and `as never` assert nothing; they silence the compiler where the type is wrong. Fix the type instead: a generic on the setter, a narrower parameter, a typed helper, `satisfies`. A pre-existing cast is removed when the line is touched, never copied. Generic parameters are full words (`ApplicationType`, `TDocument`), never `App` or `TDoc` (V-C-04). | SOFT |
74
- | V-C-11 | **SIMPLE FIRST, in code and in prose.** Fewest concepts, plainest words, smallest surface. Complexity must buy correctness, speed or safety the simple version cannot, and the artifact says what it bought. Something a reader cannot follow in one pass is a defect even when it works. Fix the root cause with the smallest change; never layer an abstraction on a misdiagnosed problem. | SOFT |
83
+ | V-C-11 | **SIMPLE FIRST, in code and in prose.** Fewest concepts, plainest words, smallest surface. Complexity must buy correctness, speed or safety the simple version cannot, and the artifact says what it bought. Something a reader cannot follow in one pass is a defect even when it works. Fix the root cause with the smallest change; never layer an abstraction on a misdiagnosed problem. Small means the code holds only what the task needs - not golfed: no clever one-liners to save lines, and no code for a need nobody has yet. | SOFT |
75
84
  | V-C-12 | **Consistent, never self-invented.** Before writing anything new - a constant, file, binding key, error shape - find the nearest precedent in this repo and copy its shape. Binding keys are namespaced (`controllers.X`, `services.X`, `repositories.X`, `datasources.X`). Every scope is one folder with nested `common/{types,constants}.ts` and an index barrel (`inversion` is the model). A second style for something that already has one is a defect. | SOFT |
76
85
  | V-C-13 | **Docs style: hyphen `-`, never an em-dash or en-dash. A brand is spelled the way its owner spells it (VULCAN, never "Vulcan").** English prose. The human-facing docs site stays native to its generator (for example plain VitePress, no custom components or theme CSS). The knowledge bundle is agent-facing; never conflate the two. | SOFT - `okf check --strict` (bundle) |
77
86
  | V-C-14 | **Our types are camelCase.** A snake_case wire name exists only at the mapper boundary, through a string-literal key - never through an eslint-disable. | LINT (naming convention) + SOFT |
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: build-a-feature
3
- description: Builds a feature - an endpoint, a service, a repository, a page, a new app or a shared package - from the user's goal to a reviewed, tested change, with every convention and API looked up in atlas. Use when the user asks to build, add or implement something, asks how a feature would be built here, or asks which skill or workflow you follow for a feature. Load it before you answer any of these, a question about the workflow included, because its first step is a lookup in atlas and an answer given without it is ungrounded.
3
+ description: Builds a feature - an endpoint, a service, a page, a new app or package - from the user's goal to a reviewed, tested change, with every convention and API looked up in atlas. Use when asked to build, add or implement something, or how a feature would be built here. Load it before you answer, a question about the workflow included, because its first step is a lookup in atlas.
4
4
  user-invocable: true
5
5
  allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Agent
6
6
  ---
@@ -19,33 +19,38 @@ Before your first answer, call `search` for how a feature is built in this proje
19
19
  Open the answer with one quoted hit and the preset list (each preset with the apps and libraries
20
20
  it creates), then describe the steps below.
21
21
 
22
- **Contents**: [Checklist](#checklist) · [1. Settle the goal](#1-settle-the-goal) · [2. Ground the conventions](#2-ground-the-conventions) · [3. Design the interface](#3-design-the-interface) · [4. Plan the slices](#4-plan-the-slices) · [5. Build slice by slice](#5-build-slice-by-slice) · [6. Check](#6-check) · [7. Update knowledge](#7-update-knowledge) · [8. Review and hand over](#8-review-and-hand-over)
22
+ **Contents**: [Checklist](#checklist) · [1. Settle the goal](#1-settle-the-goal) · [2. Ground the conventions](#2-ground-the-conventions) · [3. Design the interface](#3-design-the-interface) · [4. Plan the slices](#4-plan-the-slices) · [5. Build slice by slice](#5-build-slice-by-slice) · [6. Check](#6-check) · [7. Update docs and knowledge](#7-update-docs-and-knowledge) · [8. Review and hand over](#8-review-and-hand-over)
23
23
 
24
24
  ## Checklist
25
25
 
26
26
  Copy it into your reply and tick each box when its criterion holds:
27
27
 
28
28
  ```
29
- - [ ] 1. Goal settled - every open decision answered by the user
30
- - [ ] 2. Conventions grounded - each layer the feature touches has an atlas hit you quote
31
- - [ ] 3. Interface approved - the user said yes to the interface and the seams to test
29
+ - [ ] 1. Goal settled - the card written and approved: every open decision answered (Docs impact decided, unless lane S)
30
+ - [ ] 2. Conventions grounded - each layer the feature touches has an atlas hit you quote, and what already exists is listed
31
+ - [ ] 3. Interface approved - the user said yes to the interface and the seams to test (lane L: the design pass done)
32
32
  - [ ] 4. Slices planned - each slice names one behaviour, its seam, its files
33
33
  - [ ] 5. Slices built - every slice went red, then green; every import came from `symbol`
34
34
  - [ ] 6. Checks green - typecheck, lint, test, vulcan doctor passed; the real behaviour shown
35
- - [ ] 7. Knowledge current - each changed fact is in the bundle
36
- - [ ] 8. Diff reviewed - the whole diff read once, findings fixed, summary given
35
+ - [ ] 7. Docs and knowledge current - Docs impact delivered, the docs gates green, each changed fact in the bundle
36
+ - [ ] 8. Diff reviewed - reviewed as the lane asks, findings dispositioned, summary given with what was skipped
37
37
  ```
38
38
 
39
39
  ## 1. Settle the goal
40
40
 
41
- Ask in **rounds**. A round holds every question you can ask now without guessing an earlier
42
- answer: who uses the feature, what it does, what is out of scope, which inputs fail. Number each
43
- question and put your recommended answer under it. Wait for the answers, then ask the next round.
41
+ Write the card with the `plan-a-change` skill: the goal in the user's words, the claims each with a
42
+ probe, what is out of scope, and **Docs impact**. This skill is lane M by default; a change across
43
+ packages, a public surface, security, a data model, publishing, deleting or the rules themselves is lane L
44
+ (a full card in a file, and the design pass in step 3). A small, obvious change with no decision is lane S:
45
+ three lines in chat, and steps 3 and 4 are a line each.
44
46
 
45
- A question about how the project or its framework works is a fact: look it up in atlas (step 2)
46
- instead of asking. The user answers decisions.
47
+ Ask the way `plan-a-change` says: one numbered round of every question you can ask now, each with your
48
+ recommended answer (lane M asks at most three; lane L may need a second round). A question about how the
49
+ project or its framework works is a fact: look it up in atlas (step 2) instead of asking. The user answers
50
+ decisions.
47
51
 
48
- Done when no decision is left open.
52
+ Done when the card is approved, no decision is open, and Docs impact is decided (lane S: only when the
53
+ change is user-visible).
49
54
 
50
55
  ## 2. Ground the conventions
51
56
 
@@ -62,7 +67,12 @@ A knowledge page under `.agents/knowledge/packages/` is a summary of what a pack
62
67
  code is written comes from atlas. When atlas has nothing on a point, tell the user and mark the
63
68
  point **unverified**.
64
69
 
65
- Done when each layer has a quoted atlas hit, or is marked unverified.
70
+ Then list what already exists for the feature before you design anything: the code and precedent in
71
+ this repository, what the framework provides (its `symbol` and `search` hits), what the runtime and
72
+ the installed libraries already do. Say, per piece of the feature, "reused: X" or "new: why nothing
73
+ above covers it" (V-P-08).
74
+
75
+ Done when each layer has a quoted atlas hit, or is marked unverified, and each piece is marked reused or new.
66
76
 
67
77
  ## 3. Design the interface
68
78
 
@@ -71,9 +81,12 @@ and method names, options, configuration and environment keys, files to add. Aim
71
81
  interface: the fewest methods and parameters that cover the behaviour, with the complexity behind
72
82
  them. Name the convention behind each choice and the atlas hit it came from.
73
83
 
74
- Then name the **seams** to test: the public interfaces where a test observes the behaviour (an
84
+ Then name the **seams** to test (where a test lives: `node_modules/@venizia/vulcan/base/references/testing.md`): the public interfaces where a test observes the behaviour (an
75
85
  HTTP route, a service method, a page's rendered output). Tests live at these seams only.
76
86
 
87
+ For lane L, or a new public API, a cross-package change, auth or security, a data model, a new
88
+ dependency or a new abstraction, run the design pass first: `node_modules/@venizia/vulcan/base/references/design-pass.md`.
89
+
77
90
  Done when the user approves the interface and the seams.
78
91
 
79
92
  ## 4. Plan the slices
@@ -92,10 +105,16 @@ For each slice, in order:
92
105
  computed independently of the code under test. Run it: it goes **red**, for the reason you expect.
93
106
  2. Call `symbol` for each export of the framework or of a workspace package you are about to
94
107
  import or call, and use the signature and import path it returns.
95
- 3. Write the smallest code that turns the test **green**. Run it.
108
+ 3. Write the smallest code that turns the test **green**: only what the slice needs, nothing for a
109
+ later need (V-C-11). Keep its validation, error handling, security and data safety (V-B-06). Mark a
110
+ deliberate shortcut in the code with `// SHORTCUT: <what>, <why>, <revisit when>` (V-B-07). Run it.
96
111
 
97
112
  A database change is a migration file you write and hand to the user to apply.
98
113
 
114
+ How to test, what a test must not do, and when to mock: `node_modules/@venizia/vulcan/base/references/testing.md`. A slice that
115
+ changes user-visible behaviour, a public API, a convention or a knowledge fact is not complete until its
116
+ docs slice is delivered in step 7. Work you hand to a subagent follows `node_modules/@venizia/vulcan/base/references/delegation-brief.md`.
117
+
99
118
  Done when every slice went red, then green.
100
119
 
101
120
  ## 6. Check
@@ -106,17 +125,24 @@ paste what came back.
106
125
 
107
126
  Done when every check passed in this session and the behaviour is shown.
108
127
 
109
- ## 7. Update knowledge
128
+ ## 7. Update docs and knowledge
110
129
 
111
- Each fact about the project that changed - a new concept, a decision, a gotcha - goes into the
112
- knowledge bundle in the same change.
130
+ When **Docs impact** is not `none`, run the `docs-update` skill now, after the checks of step 6 and
131
+ before review: it refreshes the page that owns the
132
+ topic, writes the changelog entry when the change is release-worthy, and runs the docs gates. Then each
133
+ fact about the project that changed - a new concept, a decision, a gotcha - goes into the knowledge
134
+ bundle in the same change. The reviewer sees the docs in the diff.
113
135
 
114
- Done when the bundle matches the change.
136
+ Done when the docs gates (`vulcan doctor`, `vulcan x okf check --strict`, the project's own docs build)
137
+ are green and the bundle matches the change.
115
138
 
116
139
  ## 8. Review and hand over
117
140
 
118
- Read the whole diff once, for bugs and for the project's rules. Refactor here, with the tests
119
- green. Fix what you find, then summarise the change with the checks you ran and their results.
141
+ Review with the `review-a-change` skill: lane L gets an independent, non-forked reviewer per axis; lane
142
+ M reviews its own diff and may ask for a fresh review; lane S reads the diff once. Refactor here, with the
143
+ tests green. Fix what the findings adopt, then report with the `report-back` skill: the checks you ran
144
+ and their results, and an end line "Skipped / not checked / shortcuts": what you did not run, what you
145
+ did not verify, and every `SHORTCUT:` you added - or the words "none" (V-B-07).
120
146
  The user decides when to commit.
121
147
 
122
- Done when the diff is clean and the summary names every check and its result.
148
+ Done when the diff is clean, the summary names every check and its result, and the skipped line is there.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: docs-update
3
- description: Updates the project's human-facing docs after a code change - refreshes the page that owns a topic, adds a page for a new feature, writes the changelog entry, then runs the docs gates until they pass. Use when the user asks to update the wiki or the docs, document a change or a feature, refresh a page, add a changelog entry, or keep the docs in step with the code.
3
+ description: Updates the project's human-facing docs after a code change - the page that owns the topic or a new page, the changelog entry, then the docs gates. Use when asked to update the wiki or docs, document a change or feature, or keep docs in step with the code.
4
4
  user-invocable: true
5
5
  allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Agent
6
6
  ---
@@ -14,6 +14,17 @@ page and the code disagree, the page is the bug. Nothing is committed: the user
14
14
  `$ARGUMENTS` says what to document - `add a changelog entry for the retry option`, `refresh the
15
15
  storage reference`. With no arguments, ask what to document.
16
16
 
17
+ **Contents**: [Where this runs in a change](#where-this-runs-in-a-change) · [Checklist](#checklist) · [1. Paths](#1-paths) · [2. Code](#2-code) · [3. Pick the page](#3-pick-the-page) · [4. Write](#4-write) · [5. Changelog](#5-changelog) · [6. Gates](#6-gates---validate-fix-repeat) · [7. Report](#7-report)
18
+
19
+ ## Where this runs in a change
20
+
21
+ Docs are a slice of the change, planned next to the code slices and never a last group. The card's **Docs impact**
22
+ (see the `plan-a-change` skill) names the pages, the knowledge concepts and the changelog entry that change.
23
+ This skill delivers them after the code checks are green and before review (`build-a-feature` step 7), so
24
+ the reviewer sees the docs in the diff; the docs gates in step 6 below are the check for what it writes. Docs impact `none` needs no run, unless the change is user-visible: then
25
+ the same rule applies at one-line scale. Not knowing which docs change is an open question of the card, not
26
+ a reason to skip this.
27
+
17
28
  ## Checklist
18
29
 
19
30
  Copy it into your reply and tick it off, in order:
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: docs-writing
3
- description: Reader-first writing method for ALL of the project's documentation. Use when you write or edit anything a human will read - wiki pages, READMEs, changelogs, references, guides, the knowledge bundle (.agents/knowledge), or when asked to "document" a feature, even when the request never says "docs", and when reviewing or simplifying existing documentation.
3
+ description: Reader-first writing method for all documentation. Use when you write or edit anything a human will read (wiki pages, READMEs, changelogs, references, guides, the knowledge bundle), when asked to document a feature, or to simplify existing docs.
4
4
  user-invocable: true
5
5
  allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Agent
6
6
  ---
@@ -32,7 +32,7 @@ Two questions classify any page (the Diataxis compass):
32
32
  | facts (knowing) | work | **Reference** |
33
33
  | understanding (thinking) | study | **Concept / explanation** |
34
34
 
35
- Each type has a fixed section order and hard rules. Read `references/page-anatomy.md` before structuring the page - it has the five skeletons (tutorial, how-to, reference, concept, changelog) and 14 pass/fail structure rules.
35
+ A document an agent reads (a skill, a rules file, `AGENTS.md`) follows the same method with different costs: see `references/agent-documents.md`. Each type has a fixed section order and hard rules. Read `references/page-anatomy.md` before structuring the page - it has the five skeletons (tutorial, how-to, reference, concept, changelog) and 14 pass/fail structure rules.
36
36
 
37
37
  The rules that kill the most density, apply them everywhere:
38
38
 
@@ -0,0 +1,53 @@
1
+ # Documents agents read
2
+
3
+ A skill description, a rules file, `AGENTS.md`, a reference an agent loads: these are written for a
4
+ reader that pays for every word it loads and that obeys what it reads. The method is the same as for
5
+ people - one reader, one purpose, plain words - with the changes below.
6
+
7
+ **Contents**: [Pointers, not essays](#pointers-not-essays) · [Say what changes behaviour](#say-what-changes-behaviour) · [Positive before negative](#positive-before-negative) · [One home for each fact](#one-home-for-each-fact) · [Honest headers](#honest-headers) · [Checks before you finish](#checks-before-you-finish)
8
+
9
+ ## Pointers, not essays
10
+
11
+ A description or an `AGENTS.md` line is a context pointer: it is loaded on every turn whether or not it
12
+ is used, so it carries only what decides whether to load the rest.
13
+
14
+ - Front-load the word that decides: the verb the reader would search for.
15
+ - Name the situations that should load it, a handful at most; a long list is a list nobody reads.
16
+ - Cut identity the body already carries: the description does not repeat what the first heading says.
17
+ - Use progressive disclosure: the steps in the file, the detail one pointer away, loaded when the pointer
18
+ fires. A reference is linked from the file that needs it, one level deep.
19
+ - Every step ends on a completion criterion that is both checkable and exhaustive: "done when each layer
20
+ has a quoted atlas hit", not "done when you understand it".
21
+
22
+ ## Say what changes behaviour
23
+
24
+ For each sentence ask: does it change what a capable agent does, compared with what it would do anyway?
25
+ A sentence that does not is a no-op: cut it. Hunt them one sentence at a time, and again after an edit.
26
+ The test of a rule is the model that is better next year: if a smarter model makes the line unnecessary,
27
+ the line is a candidate to go.
28
+
29
+ ## Positive before negative
30
+
31
+ A prohibition drags the forbidden behaviour into context. Say what to do and keep a ban only as a hard
32
+ guardrail, paired with its positive target: "write scratch under `.agents/local/`", then "nothing goes in
33
+ the system temp directory". A rule broken by a lapse on a line that is already loaded does not need a new
34
+ line; it needs a check or an eval.
35
+
36
+ ## One home for each fact
37
+
38
+ State a fact once and point at it. The environment is a source of truth too: do not restate a script that
39
+ `package.json` already lists, or a command the CLI prints with `--help`. Two copies drift, and an agent
40
+ cannot tell which one is current.
41
+
42
+ ## Honest headers
43
+
44
+ A header must not describe behaviour that is not there: a file that says "run by the pre-commit hook"
45
+ when no hook runs it misleads for as long as it lives. A gotcha is recorded with where it came from (a
46
+ dated incident, a failing test, a reproduction); one with no provenance is methodology, and is cut.
47
+
48
+ ## Checks before you finish
49
+
50
+ - Descriptions: about 50 words, a "Use when" part, and a `NOT FOR` clause where two skills are easily confused and the words allow.
51
+ - `SKILL.md` under 500 lines; any file past 100 lines opens with a contents list.
52
+ - Every rule or skill you changed has its eval (or its check) run again.
53
+ - Read it once as the agent that loads it with nothing else: can it act, and does it know when it is done?
@@ -0,0 +1,84 @@
1
+ ---
2
+ name: fix-a-bug
3
+ description: Fixes a bug by building a fast, deterministic way to see it fail before any theory, then proving the fix with a regression test. Use when something is broken, throwing, failing, slow or behaves differently than it should.
4
+ user-invocable: true
5
+ allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Agent
6
+ ---
7
+
8
+ # Fix a bug
9
+
10
+ Build the loop first. A fast, deterministic way to see the bug fail is the whole skill: with one, you
11
+ find the cause by looking; without one, you guess. Read code to build the loop (to find the failing test
12
+ or the right seam), but do not name a cause from reading alone: code analysis without a reproduction is
13
+ speculation. Nothing is committed; the owner decides.
14
+
15
+ `$ARGUMENTS` describes the bug. With none, ask for the symptom and where it appears.
16
+
17
+ **Contents**: [Checklist](#checklist) · [1. Build the loop](#1-build-the-loop) · [2. Minimise](#2-minimise) · [3. Hypothesise](#3-hypothesise) · [4. Test one thing at a time](#4-test-one-thing-at-a-time) · [5. Fix with a regression test](#5-fix-with-a-regression-test) · [6. Clean up and report](#6-clean-up-and-report)
18
+
19
+ ## Checklist
20
+
21
+ ```
22
+ - [ ] 1. Loop built - one command, already run, that goes red on this bug
23
+ - [ ] 2. Minimised - the smallest input and the fewest steps that still fail
24
+ - [ ] 3. Hypotheses shown - three to five, ranked, each falsifiable, shown to the owner
25
+ - [ ] 4. Cause found - by changing one variable at a time
26
+ - [ ] 5. Fix proven - a regression test red before the fix and green after, at a correct seam
27
+ - [ ] 6. Cleaned and told - tagged logs gone, scratch removed, the cause in the commit or PR text
28
+ ```
29
+
30
+ ## 1. Build the loop
31
+
32
+ The loop is one command you have already run. It must be:
33
+
34
+ - **red-capable**: it fails on this exact bug, not on something nearby;
35
+ - **deterministic**: it fails every time; fix a flaky loop first (pin a seed, a clock, an order);
36
+ - **fast**: seconds, so you can run it dozens of times;
37
+ - **runnable by an agent**: no human step.
38
+
39
+ Ways to get one, best first: an existing failing test; a new test at the seam where the bug shows; a
40
+ script or a `curl` against the running thing; a replay of a captured request or log; a bisection over
41
+ commits (`git bisect run <the loop>`). A bug in a UI is reproduced in a real browser, at mobile and at
42
+ desktop width, before any code is read.
43
+
44
+ If you cannot build a loop, stop and say what is missing (access, data, an environment). Do not proceed
45
+ on theory.
46
+
47
+ Done when the loop's red output is in your reply.
48
+
49
+ ## 2. Minimise
50
+
51
+ Cut the input, the data and the steps until removing anything more makes the bug disappear. Delete
52
+ configuration, then dependencies, then code paths. The minimal case often names the cause by itself.
53
+
54
+ ## 3. Hypothesise
55
+
56
+ Write three to five hypotheses, ranked by likelihood. Each says what would be true if it is the cause and
57
+ what observation would **falsify** it. Put the list in your reply before you test, so the owner can
58
+ redirect you, and do not wait for an answer unless a test would be destructive. A hypothesis that cannot
59
+ be falsified is not one.
60
+
61
+ ## 4. Test one thing at a time
62
+
63
+ Change one variable, run the loop, read the result, record it. For the observations you need, add logging
64
+ tagged `[DEBUG-<id>]` so one `grep` finds every line to remove. When the loop was forced red by changing
65
+ code, diff against a pristine copy to be sure the red comes from the bug.
66
+
67
+ Done when one hypothesis is confirmed by a loop result, and the others are ruled out or parked.
68
+
69
+ ## 5. Fix with a regression test
70
+
71
+ 1. Write the regression test **before** the fix, at a seam that reproduces the real bug pattern. Run it:
72
+ it is red, and you say why.
73
+ 2. Make the smallest fix for the cause, not for the symptom (V-C-11). Keep validation and error handling
74
+ (V-B-06).
75
+ 3. Run the test (green), then the loop, then the project's gates.
76
+
77
+ How a test is kept honest, and what to mock, is in `node_modules/@venizia/vulcan/base/references/testing.md`. If no correct seam exists for a regression test, that is itself the finding: report it, do not write a
78
+ test that cannot fail. A test that passes before the fix tests nothing.
79
+
80
+ ## 6. Clean up and report
81
+
82
+ Remove every `[DEBUG-<id>]` line with one search, delete scratch files from `.agents/local/tmp/`, and
83
+ check `git status` shows only the fix and its test. Put the confirmed hypothesis in the commit message or
84
+ the pull request text, and say what was ruled out. Report with the `report-back` skill.
@@ -0,0 +1,17 @@
1
+ {
2
+ "skill_name": "fix-a-bug",
3
+ "evals": [
4
+ {
5
+ "id": 0,
6
+ "prompt": "A function in this repository sometimes returns the wrong value for one input and I do not know why. Find and fix it.",
7
+ "expected_output": "Builds and runs a red-capable, deterministic, fast command that reproduces the failure before any theory; minimises it; lists three to five ranked falsifiable hypotheses and shows them; changes one variable at a time; writes a regression test that is red before the fix and green after; removes any tagged debug output; says what was ruled out; commits nothing",
8
+ "files": []
9
+ },
10
+ {
11
+ "id": 1,
12
+ "prompt": "The page renders blank on a phone but fine on my laptop. Fix it.",
13
+ "expected_output": "Reproduces the bug in a real browser at a mobile width before reading code for a cause; builds a loop an agent can rerun; does not guess a cause first; writes the regression check at a seam that reproduces the real pattern, or says plainly that no correct seam exists",
14
+ "files": []
15
+ }
16
+ ]
17
+ }
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: knowledge-sync
3
- description: Re-syncs a project's OKF knowledge bundle against its source code - verifies the curated concepts whose code changed since the last sync (delta) or every concept (full), applies the confirmed fixes and logs the sync. Use when the user asks to sync knowledge, refresh the knowledge bundle, audit concepts against code, or run a periodic knowledge audit.
3
+ description: Re-syncs the OKF knowledge bundle against the source code, verifying concepts whose code changed (delta) or all of them (full) and applying the confirmed fixes. Use when asked to sync knowledge, refresh the bundle, audit concepts against code or run a periodic audit.
4
4
  user-invocable: true
5
5
  allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Agent, Workflow
6
6
  ---
@@ -11,6 +11,9 @@ The generated layer (`vulcan x okf gen`) heals itself; curated concepts stay tru
11
11
  re-reads the code. Code is ground truth - never fix a concept from docs, `AGENTS.md` or memory. Every
12
12
  finding cites a `file:line` witness. Nothing is committed: the user reviews the diff.
13
13
 
14
+ This skill is the periodic audit, run when asked or on a schedule - not once per change. The facts a
15
+ single change alters are updated by the change itself (`build-a-feature` step 7).
16
+
14
17
  ## Requirements
15
18
 
16
19
  - Bun, git, and `@venizia/vulcan` installed in the project (`bun x --no-install vulcan`).
@@ -157,16 +157,16 @@ const SECTION_HINTS = {
157
157
  reference:
158
158
  'audit only the CURATED files - a file with a generated: frontmatter key is generated, skip it',
159
159
  };
160
- const spotGroups = SECTIONS.map(section => ({
160
+ const spotGroups = SECTIONS.map((section) => ({
161
161
  key: section,
162
162
  dirs: SECTION_HINTS[section] ? `${section}/ - ${SECTION_HINTS[section]}` : `${section}/`,
163
163
  }));
164
164
 
165
165
  phase('Verify');
166
- const deltaConceptList = deltaTargets.flatMap(t => t.concepts).join(', ');
166
+ const deltaConceptList = deltaTargets.flatMap((t) => t.concepts).join(', ');
167
167
  const finderThunks = [
168
168
  ...deltaTargets.map(
169
- t => () =>
169
+ (t) => () =>
170
170
  agent(
171
171
  `${COMMON}${DELTA}\nAssigned code area: ${t.area}\nAssigned concept files (under ${KB}/): ${t.concepts.join(', ')}\nContext hints from the orchestrator (verify, do not trust): ${t.hint}`,
172
172
  {
@@ -182,7 +182,7 @@ const finderThunks = [
182
182
  if (mode === 'full') {
183
183
  finderThunks.push(
184
184
  ...spotGroups.map(
185
- g => () =>
185
+ (g) => () =>
186
186
  agent(
187
187
  `${COMMON}\nFocus mode SPOT-AUDIT: sweep for anything past syncs missed or that drifted. First \`ls\` your assigned directory group and audit EVERY concept file in it${deltaConceptList ? `, EXCEPT these already covered by delta verifiers this run: ${deltaConceptList}` : ''}.\nAssigned group: ${g.dirs}`,
188
188
  { label: `spot:${g.key}`, phase: 'Verify', model: 'sonnet', schema: FINDINGS_SCHEMA },
@@ -203,8 +203,8 @@ if (mode === 'full') {
203
203
 
204
204
  const finderResults = await parallel(finderThunks);
205
205
  const ok = finderResults.filter(Boolean);
206
- const allFindings = ok.flatMap(r => r.findings ?? []);
207
- const gaps = ok.flatMap(r => r.gaps ?? []);
206
+ const allFindings = ok.flatMap((r) => r.findings ?? []);
207
+ const gaps = ok.flatMap((r) => r.gaps ?? []);
208
208
  const confirmedTotal = ok.reduce((sum, r) => sum + (r.confirmedCount ?? 0), 0);
209
209
  log(
210
210
  `Verify done (${mode}): ${allFindings.length} findings, ${gaps.length} gap proposals, ${confirmedTotal} claims confirmed`,
@@ -236,7 +236,7 @@ log(`Findings span ${files.length} concept files -> one applier per file`);
236
236
  phase('Apply');
237
237
  const applyResults = await parallel(
238
238
  files.map(
239
- path => () =>
239
+ (path) => () =>
240
240
  agent(
241
241
  `You are a careful knowledge curator for the ${BRAND} repository at ${REPO}.
242
242
  Target file: ${REPO}/${path}
@@ -263,8 +263,8 @@ Return counts + a one-line summary of what you changed.`,
263
263
  // misattributes every summary after a dead applier to the wrong file.
264
264
  const applySummaries = files
265
265
  .map((file, index) => ({ file, result: applyResults[index] }))
266
- .filter(entry => entry.result)
267
- .map(entry => ({ file: entry.file, ...entry.result }));
266
+ .filter((entry) => entry.result)
267
+ .map((entry) => ({ file: entry.file, ...entry.result }));
268
268
 
269
269
  const totalApplied = applySummaries.reduce((sum, r) => sum + (r.applied ?? 0), 0);
270
270
  const totalSkipped = applySummaries.reduce((sum, r) => sum + (r.skipped ?? 0), 0);
@@ -287,5 +287,5 @@ return {
287
287
  findingsByFile: byFile,
288
288
  applySummaries,
289
289
  gaps,
290
- notes: ok.map(r => r.notes).filter(Boolean),
290
+ notes: ok.map((r) => r.notes).filter(Boolean),
291
291
  };