@kirill.konshin/lint 0.5.4 → 0.6.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 (114) hide show
  1. package/README.md +47 -7
  2. package/commands/spec-author.md +39 -0
  3. package/dist/configs/base.d.ts +4 -3
  4. package/dist/configs/base.js +61 -74
  5. package/dist/configs/imports.d.ts +3 -2
  6. package/dist/configs/imports.js +95 -146
  7. package/dist/configs/nx.d.ts +4 -3
  8. package/dist/configs/nx.js +31 -41
  9. package/dist/configs/prettier.d.ts +3 -2
  10. package/dist/configs/prettier.js +19 -16
  11. package/dist/configs/promise.d.ts +3 -2
  12. package/dist/configs/promise.js +16 -16
  13. package/dist/configs/react.d.ts +4 -3
  14. package/dist/configs/react.js +178 -217
  15. package/dist/configs/storybook.d.ts +4 -3
  16. package/dist/configs/storybook.js +22 -22
  17. package/dist/configs/tailwind.d.ts +4 -3
  18. package/dist/configs/tailwind.js +67 -91
  19. package/dist/configs/testing.d.ts +7 -6
  20. package/dist/configs/testing.js +112 -136
  21. package/dist/configs/turbo.d.ts +4 -3
  22. package/dist/configs/turbo.js +19 -27
  23. package/dist/configs/typescriptTypeAware.d.ts +4 -3
  24. package/dist/configs/typescriptTypeAware.js +99 -95
  25. package/dist/configs/unicorn.d.ts +3 -2
  26. package/dist/configs/unicorn.js +34 -41
  27. package/dist/exts.d.ts +2 -1
  28. package/dist/exts.js +10 -11
  29. package/dist/index.d.ts +44 -41
  30. package/dist/index.js +53 -84
  31. package/dist/lib.d.ts +21 -21
  32. package/dist/lib.js +261 -301
  33. package/dist/lintPrepare.d.ts +33 -28
  34. package/dist/lintPrepare.js +347 -376
  35. package/dist/lintStaged.d.ts +4 -3
  36. package/dist/lintStaged.js +25 -22
  37. package/dist/prettier.d.ts +4 -3
  38. package/dist/prettier.js +16 -17
  39. package/dist/restrictions.d.ts +24 -0
  40. package/dist/restrictions.js +20 -0
  41. package/dist/yarn.cjs +79 -98
  42. package/dist/yarn.d.cts +3 -2
  43. package/package.json +24 -8
  44. package/rules/agent.md +7 -4
  45. package/rules/openspec.md +1 -1
  46. package/skills/spec-steward/SKILL.md +4 -12
  47. package/skills/spec-steward/references/audit.md +18 -43
  48. package/skills/spec-steward/references/contract.md +7 -7
  49. package/skills/spec-steward/references/criteria.md +4 -4
  50. package/skills/spec-steward/references/model.md +1 -1
  51. package/skills/spec-steward/references/review-format.md +6 -6
  52. package/skills/spec-steward/references/wiring.md +4 -4
  53. package/skills/spec-steward/references/worker.md +67 -0
  54. package/skills/spec-steward/scripts/lib/align.mjs +7 -6
  55. package/skills/spec-steward/scripts/lib/checks.mjs +6 -1
  56. package/skills/spec-steward/scripts/lib/corpus.mjs +5 -8
  57. package/skills/spec-steward/scripts/lib/coverage.mjs +2 -3
  58. package/skills/spec-steward/scripts/lib/evidence.mjs +2 -148
  59. package/skills/spec-steward/scripts/lib/wire.mjs +6 -4
  60. package/skills/spec-steward/scripts/steward.mjs +30 -91
  61. package/skills/spec-steward/sweeps.json +49 -0
  62. package/skills/spec-tools/SKILL.md +46 -0
  63. package/skills/spec-tools/references/contract.md +111 -0
  64. package/skills/spec-tools/references/gitlab.md +122 -0
  65. package/skills/spec-verify/SKILL.md +153 -0
  66. package/spec-tools/dist/audit-DkZZulq6.mjs +130 -0
  67. package/spec-tools/dist/auditChanged-CNGjlake.mjs +1 -0
  68. package/spec-tools/dist/auditChanged-CZCvMgyZ.mjs +618 -0
  69. package/spec-tools/dist/auditReport-xgq4wK2i.mjs +458 -0
  70. package/spec-tools/dist/auditScope-CBuBtfPG.mjs +104 -0
  71. package/spec-tools/dist/changeGates-DdeQKfle.mjs +333 -0
  72. package/spec-tools/dist/changeGates-uy4Ti8rK.mjs +1 -0
  73. package/spec-tools/dist/ci-BUewHJS3.mjs +143 -0
  74. package/spec-tools/dist/ci-CFBzn8Of.mjs +1 -0
  75. package/spec-tools/dist/cli.mjs +93 -0
  76. package/spec-tools/dist/comment-szasMMg2.mjs +57 -0
  77. package/spec-tools/dist/files-Bppsb34B.mjs +1 -0
  78. package/spec-tools/dist/files-QlzY687_.mjs +38 -0
  79. package/spec-tools/dist/html-BMTkpbUN.mjs +1766 -0
  80. package/spec-tools/dist/jsonrepair-Dlm5dEen.mjs +742 -0
  81. package/spec-tools/dist/repo-CjIoUPYl.mjs +16 -0
  82. package/spec-tools/dist/repo-DUcnJw3c.mjs +1 -0
  83. package/spec-tools/dist/run-BElA9du3.mjs +67 -0
  84. package/spec-tools/dist/specDiff-8G56jMYn.mjs +123 -0
  85. package/spec-tools/dist/steward-DeieyOcj.mjs +34 -0
  86. package/spec-tools/dist/stewardAudit-BRMM0lrD.mjs +1 -0
  87. package/spec-tools/dist/stewardAudit-v0vOMfLN.mjs +271 -0
  88. package/spec-tools/dist/tier-Cn0P7juM.mjs +1 -0
  89. package/spec-tools/dist/tier-c3s_mA_I.mjs +65 -0
  90. package/spec-tools/dist/util-wnxhsnWO.mjs +49 -0
  91. package/spec-tools/dist/verdict-BFfN9PO8.mjs +58 -0
  92. package/spec-tools/dist/workers-BcIgckeq.mjs +417 -0
  93. package/spec-tools/dist/workflowEvidence-DyBj8EdG.mjs +1 -0
  94. package/spec-tools/dist/workflowEvidence-oui6ghPI.mjs +78 -0
  95. package/dist/configs/base.d.ts.map +0 -1
  96. package/dist/configs/imports.d.ts.map +0 -1
  97. package/dist/configs/nx.d.ts.map +0 -1
  98. package/dist/configs/prettier.d.ts.map +0 -1
  99. package/dist/configs/promise.d.ts.map +0 -1
  100. package/dist/configs/react.d.ts.map +0 -1
  101. package/dist/configs/storybook.d.ts.map +0 -1
  102. package/dist/configs/tailwind.d.ts.map +0 -1
  103. package/dist/configs/testing.d.ts.map +0 -1
  104. package/dist/configs/turbo.d.ts.map +0 -1
  105. package/dist/configs/typescriptTypeAware.d.ts.map +0 -1
  106. package/dist/configs/unicorn.d.ts.map +0 -1
  107. package/dist/exts.d.ts.map +0 -1
  108. package/dist/index.d.ts.map +0 -1
  109. package/dist/lib.d.ts.map +0 -1
  110. package/dist/lintPrepare.d.ts.map +0 -1
  111. package/dist/lintStaged.d.ts.map +0 -1
  112. package/dist/prettier.d.ts.map +0 -1
  113. package/dist/yarn.d.cts.map +0 -1
  114. package/skills/spec-steward/workflows/audit.js +0 -539
@@ -1,57 +1,32 @@
1
1
  # Audit procedure
2
2
 
3
- An audit asks whether the corpus holds the **right** rules with the **right** evidence. It judges by [model.md](model.md) and [criteria.md](criteria.md), places guidance by `rules/agent.md`, and produces a review file ([review-format.md](review-format.md)). Nothing in the specifications or the code changes during an audit. Whether the code conforms to the specifications is not its question; that is the repository's own conformance audit.
3
+ An audit asks whether the corpus holds the **right** rules with the **right** evidence. It judges by [model.md](model.md) and [criteria.md](criteria.md), places guidance by `rules/agent.md`, and produces a review file ([review-format.md](review-format.md)). Nothing in the specifications or the code changes during an audit. Whether the code conforms to the specifications is not its question; that is the `spec-verify` audit, and the principles both judge are worded once, in [criteria.md](criteria.md).
4
4
 
5
- ## 1. Mechanical inputs
5
+ ## 1. Run the engine
6
6
 
7
- Run these for every repository in scope. With several repositories, pass `--root NAME=path` for each.
7
+ Both audits run on one engine, `spec-tools` (the `spec-tools` skill), one repository per run; cross-repository wording drift is [align](../SKILL.md#align). The whole sequence, from a detached tree of `HEAD` (`--here` for uncommitted edits):
8
8
 
9
- - `steward check` (add `--base auto` or `--base <ref>` for a change): heuristic candidates. They are leads, not verdicts.
10
- - `steward index`: counts (capabilities, requirements, Advisory requirements, Known gaps, scenarios), and the citation inventory split into bindings and pointers, with how many of them dangle.
11
- - `steward evidence --out <dir>`: one bundle per capability. A bundle holds each requirement verbatim with line numbers, the tests bound to its scenarios ([contract.md](contract.md#binding)), code citations as pointers, where its terms occur, and related requirements across capabilities and repositories.
12
- - `steward coverage --out <file>`: bindings, Advisory requirements and Known gaps per capability.
13
- - The repository's own gates and reports, when it has them.
9
+ ```bash
10
+ spec-tools audit --audit spec-steward --context <decisions file>
11
+ ```
14
12
 
15
- ## 2. Fan out
13
+ It runs locally, on the owner's request; no pipeline runs it. `--context` passes a file of facts already established and the owner's earlier decisions — earlier review answers, the decision log — into every worker's and verifier's brief, so no finding reverses one without saying so.
16
14
 
17
- One reader cannot hold a corpus, so partition it.
15
+ It runs these passes, each also a command of its own:
18
16
 
19
- - **Parts.** Group a handful of related capabilities per part, and keep same-named capabilities from different repositories together so drift is judged in place. `steward partition --parts N` balances by size. Hand-made parts are fine when the architecture suggests better groups.
20
- - **Sweeps.** Each sweep looks across the corpus from one angle:
21
- - tooling and CI
22
- - tests citing the corpus (compliance theatre)
23
- - comments and citations
24
- - a whole-corpus reader for duplicates, contradictions and cross-repository wording
25
- - missing invariants
26
- - the CI run classes
27
- - placement against `rules/agent.md` (duplicated concerns, AGENTS.md hierarchy, scoped rules, skills)
28
- - **Maps first.** An architecture map, an enforcement map and the owner's decision history go to every reader, so no one re-derives them.
17
+ 1. `spec-tools scope --audit spec-steward` — spec-steward's evidence model, cut into parts one reader holds (each capability's requirements verbatim, the tests bound to them, where their terms occur, their related requirements), plus one unit per [sweep](../sweeps.json): tooling and CI, tests citing the corpus, comments and citations, missing invariants, placement.
18
+ 2. `spec-tools workers --audit spec-steward` — one headless worker per unit under [worker.md](worker.md), judging every criterion and writing its findings file, with the requirements it judged and those it found sound.
19
+ 3. `spec-tools report --audit spec-steward` — the merge: every quote looked up at its line (a finding whose quote is not there is dropped, saying so); the requirements no worker judged listed as short.
20
+ 4. `spec-tools workers --complete --audit spec-steward` — what the reading left short, judged once more; then the merge again.
21
+ 5. `spec-tools workers --verify --audit spec-steward` — one skeptic per finding: it keeps, revises or drops for silent intent, a non-spec problem, compliance theatre, a misplaced contract, the wrong layer, an unstated reversal of an owner decision, or a false claim about code. Then the last merge folds duplicates (one rule, one problem), offers findings sharing a theme key as a theme, and renders `spec-review.md`.
29
22
 
30
- With Claude Code's Workflow tool, run [`workflows/audit.js`](../workflows/audit.js). It takes the arguments documented at its top and returns verified, consolidated findings and themes. Without it, start one subagent per part and per sweep in waves, give each this procedure and its files, and run the verification below yourself.
23
+ The run's data, kept for the next step, is `audit-parts/steward/review.json`: the themes and findings, the dropped findings with who dropped them and why, the requirements judged sound, the short list and the workers' notes.
31
24
 
32
- ## 3. Verify every finding twice
25
+ ## 2. Consolidate and hand back
33
26
 
34
- 1. **Facts.** Is the quote verbatim at its line? Are the evidence references real, and does the code or test do what the finding claims?
35
- 2. **Judgement.** The verifier acts as a skeptic and looks for these failures:
36
- - **silent intent**: the finding decides an ambiguous intent without saying so. Revise it to offer options.
37
- - **not a spec problem**: style, an ordinary bug, or speculation. Drop it.
38
- - **compliance theatre**: the proposed verification catches no real failure. Revise or drop.
39
- - **misplaced contract**: an internal contract moved out of the spec only because it is not user-facing. Revise.
40
- - **wrong layer**. Revise.
41
- - **unstated reversal** of a past owner decision. Revise to state it.
42
- - **duplicate**. Drop the weaker one.
43
-
44
- ## 4. Completeness
45
-
46
- A critic looks for capabilities with neither findings nor a sound list, criteria that yielded nothing where the corpus plainly has cases, unread sources, and shared capabilities not compared. Its gaps become targeted follow-up units. Loop until a round finds nothing new; two rounds is usually enough.
47
-
48
- ## 5. Consolidate and render
49
-
50
- - **Merge duplicates per area.** The same rule with the same problem becomes one finding.
51
- - **Form themes.** Several rules with one solution become one item with members.
52
- - **Render** with `steward review render <result.json> --out <review.md> [--sections layout.json]`.
53
- - **Check** with `steward review lint` and `steward review verify --root NAME=path …`.
54
- - **Read every item yourself**: sharpen the wording, fix what the readers got wrong, and order the sections so decisions that others depend on come first.
27
+ - **Read every item yourself**: sharpen the wording, fix what the readers got wrong, and decide each offered theme — keep it as one item when its members share one solution, split it when they do not.
28
+ - **Order the sections** so decisions that others depend on come first.
55
29
  - **Close with an appendix** listing the requirements judged sound, so coverage is visible.
30
+ - **Check** with `steward review lint` and `steward review verify --root NAME=path …`.
56
31
 
57
32
  Hand the file to the owner and stop.
@@ -36,7 +36,7 @@ A citation of a scenario's anchor binds the scenario only where it sits in one o
36
36
  | In a test file, in the comment run directly above such a call or function (in Python, its decorators too), with no blank line between | yes |
37
37
  | In a test file, on a type assertion — an `Expect<…>` type alias, or an `expectTypeOf(…)` or `assertType(…)` call — at the top level or inside a block | yes |
38
38
  | In a lint configuration — `eslint.config.{js,mjs,cjs,ts,mts,cts}` or `yarn.config.cjs` — anywhere | yes |
39
- | In a file matching a `--binds <glob>` the repository passes (a check script, a Dockerfile, a CI configuration), anywhere | yes |
39
+ | In a file matching a `binds` glob the repository declares — `"spec-steward": { "binds": [...] }` in its root `package.json`, or `--binds <glob>` — (a check script, a Dockerfile, a CI configuration), anywhere | yes |
40
40
  | Anywhere else in a test file: its header, a fixture, a helper | no — it binds nothing and fails nothing |
41
41
  | Code, configuration, YAML, a Dockerfile or a document that no `--binds` glob matches | no — it is a pointer |
42
42
 
@@ -51,14 +51,14 @@ Cases:
51
51
 
52
52
  ## Markers
53
53
 
54
- There are exactly two markers. Each stands on a line of its own: the Advisory line in the requirement's statement, directly under its heading, and a Known gap line in the statement or inside the block of the scenario it qualifies.
54
+ There are exactly two markers. Each stands on a line of its own: the Advisory line in the requirement's statement, directly under its heading, and a Known gap line in the statement.
55
55
 
56
56
  | Marker | Meaning |
57
57
  | --- | --- |
58
58
  | `**⚠️ Advisory:** <why review is its evidence>` | The requirement is ADVISORY. It keeps its RFC 2119 keywords and is exempt from the scenario ratchet and from `absolute-unproven`. Coverage reports it as `advisory`, and the evidence JSON classes it `advisory`. Marking an existing requirement Advisory is reported as `weakened` ("newly marked advisory"). It qualifies the whole requirement, so a requirement that mixes a contract with guidance is split. |
59
- | `**⚠️ Known gap (<tracker>):** <what is missing>` | Behaviour the requirement describes is knowingly absent or incomplete, or a REQUIRED rule lacks the evidence that would catch its failure. `<tracker>` is required text: a ticket key (`EVAA-34696`), a tickets-page id, or an open `openspec/changes/<name>` folder. Steward checks only that it is present: any non-empty text inside the parentheses counts and is not validated, so a placeholder counts until it is replaced. In the statement, the line records the gap and exempts nothing, unless it names scenarios of its requirement by title after `exempts`, each in quotes (`exempts scenario 'A'`, `exempts scenarios 'A' and 'B'`; double quotes, curly quotes, `_…_` and `*…*` are read too). Exactly the named scenarios are then exempt from the scenario ratchet. Inside a scenario's block, the line exempts that scenario. Coverage lists every gap with its tracker. |
59
+ | `**⚠️ Known gap (<tracker>):** <what is missing>` | Behaviour the requirement describes is knowingly absent or incomplete, or a REQUIRED rule lacks the evidence that would catch its failure. `<tracker>` is required text: a ticket key (`PROJ-123`), a tickets-page id, or an open `openspec/changes/<name>` folder. Steward checks only that it is present: any non-empty text inside the parentheses counts and is not validated, so a placeholder counts until it is replaced. In the statement, the line records the gap and exempts nothing, unless it names scenarios of its requirement by title after `exempts`, each in quotes (`exempts scenario 'A'`, `exempts scenarios 'A' and 'B'`; double quotes, curly quotes, `_…_` and `*…*` are read too). Exactly the named scenarios are then exempt from the scenario ratchet. Coverage lists every gap with its tracker. |
60
60
 
61
- Retired spellings are `**⚠️ Unenforced:**` and `**⚠️ Known gap:**` without a tracker. Each is reported as `marker-hygiene` and grants no exemption. So is a marker inside a line rather than on a line of its own, and an Advisory line inside a scenario. A misspelt marker (wrong case, missing emoji or bold) is reported as `marker-hygiene`, and `--fix` normalises it.
61
+ Retired spellings are `**⚠️ Unenforced:**` and `**⚠️ Known gap:**` without a tracker. Each is reported as `marker-hygiene` and grants no exemption. So is a marker inside a line rather than on a line of its own, and an Advisory or Known gap line inside a scenario. A misspelt marker (wrong case, missing emoji or bold) is reported as `marker-hygiene`, and `--fix` normalises it.
62
62
 
63
63
  Cases:
64
64
 
@@ -133,8 +133,8 @@ An explicit `--base <ref>` compares with the merge base of `<ref>` and `HEAD`. W
133
133
  | --- | --- | --- |
134
134
  | `spec-steward check [--base auto\|<ref>] [--binds <glob>]… [--file <f>] [--fix] [--strict] [--json]` | The corpus gate, run locally, in CI and by the hook | Findings ([below](#findings)) |
135
135
  | `spec-steward coverage [--out <file>] [--binds <glob>]…` | The [coverage report](#coverage-report) | Markdown, to the file or to stdout |
136
- | `spec-steward evidence --json [--binds <glob>]…` | The audit's [evidence model](#evidence-json) | JSON on stdout |
137
- | `spec-steward evidence --out <dir>`, `partition`, `index`, `review`, `align`, `wire`, `hook` | Audit bundles and partitions, the corpus index, review files, cross-repository drift, wiring, the edit hook | As each command documents |
136
+ | `spec-steward evidence --json [--binds <glob>]…` | The audits' [evidence model](#evidence-json), which `spec-tools scope` assembles each audit's evidence files from | JSON on stdout |
137
+ | `spec-steward review`, `align`, `wire`, `hook` | Review files, cross-repository drift, wiring, the edit hook | As each command documents |
138
138
 
139
139
  `spec-steward` is the package's `bin`. A repository calls it from its root scripts and never imports steward's modules: the package's `exports` map does not expose them, so the CLI and its JSON are the interface.
140
140
 
@@ -179,7 +179,7 @@ Exit 2 on an empty listing keeps a broken checkout from passing a scan that read
179
179
  ```
180
180
 
181
181
  - `class` is `advisory` when the requirement carries the Advisory marker, else `required`.
182
- - `gaps` lists each Known gap line that carries a tracker. `scenario` is the slug of the scenario whose block holds the line, or `null` for a line under the requirement; `exempts` lists the slugs of the scenarios it exempts, empty when it exempts none.
182
+ - `gaps` lists each Known gap line under the requirement that carries a tracker; `exempts` lists the slugs of the scenarios it names, empty when it names none.
183
183
  - `bindings` are the citations that [bind](#binding) a scenario or the requirement. `kind` is `test` for a test-file binding, and `file` for a lint configuration or a `--binds` file. `title` is the bound test's title, or `null`; `window` is the line range of the bound block.
184
184
  - `pointers` are every other citation of the requirement or its scenarios.
185
185
  - `terms` are the requirement's own distinctive terms, with every hit in non-test sources after comments are stripped. Line numbers are kept.
@@ -10,13 +10,13 @@ Every rule, requirement or scenario that matches one of these, numbered so findi
10
10
  2. A rule that belongs in `AGENTS.md`, a scoped rule, a skill, a command, the OPSX config or a README rather than the specification (place it per `rules/agent.md`).
11
11
  3. A rule better enforced by deterministic tooling than by an AI audit.
12
12
  4. A rule that produces low-value or artificial tests.
13
- 5. A rule whose tests satisfy the wording while failing to protect the intent.
13
+ 5. A rule whose tests satisfy the wording while failing to protect the intent. (`spec-verify` check 5 judges it against the code.)
14
14
  6. A rule that cannot reasonably be verified.
15
15
  7. A rule whose wording allows materially different interpretations. An undefined evaluative term in a REQUIRED statement (_thin_, _safe_, _lean_, _at parity_, _needed_) is a finding: replace it with the criterion it stands for, drop the sentence where a precise rule already carries the obligation, or, when nothing checkable remains, make it ⚠️ ADVISORY.
16
16
  8. A rule that describes implementation detail instead of an externally meaningful invariant.
17
- 9. A rule redundant with, or substantially overlapping, another.
18
- 10. Contradictory rules.
19
- 11. A rule that no longer matches the implementation or architecture.
17
+ 9. A rule redundant with, or substantially overlapping, another. (`spec-verify` check 3.)
18
+ 10. Contradictory rules. (`spec-verify` check 2.)
19
+ 11. A rule that no longer matches the implementation or architecture. (`spec-verify` check 4 judges it against the code.)
20
20
  12. Implementation suggesting the specification itself is wrong or outdated.
21
21
  13. A missing high-value invariant the architecture clearly relies on.
22
22
  14. A rule whose scope is unclear.
@@ -30,7 +30,7 @@ A REQUIRED requirement stating an absolute names its exceptions, or has none; on
30
30
  A requirement is REQUIRED unless a marker says otherwise. The exact spellings, and what each exempts, are in [contract.md](contract.md#markers).
31
31
 
32
32
  - **⚠️ Advisory** — permanent guidance whose only evidence is review, such as a design direction. Its line says why review is its evidence, and its RFC 2119 keywords stay. The marker qualifies the whole requirement, so a requirement that mixes a contract with guidance is split, and the contract half stays REQUIRED. Marking an existing requirement Advisory weakens it, so the owner confirms it.
33
- - **⚠️ Known gap (<tracker>)** — behaviour the requirement describes is knowingly absent or incomplete, or a REQUIRED rule lacks the evidence that would catch its failure. The line says what is missing (for missing evidence, the missing rung) and names what tracks it: a ticket, a tickets-page entry or an open change. Under the requirement, it names by title the scenarios it exempts; inside a scenario's block, it exempts that scenario. A gap is never restated as a scenario, and a scenario that a gap conditions states that condition.
33
+ - **⚠️ Known gap (<tracker>)** — behaviour the requirement describes is knowingly absent or incomplete, or a REQUIRED rule lacks the evidence that would catch its failure. The line says what is missing (for missing evidence, the missing rung) and names what tracks it: a ticket, a tickets-page entry or an open change. It sits under the requirement statement and names by title the scenarios it exempts; inside a scenario's block it grants nothing. A gap is never restated as a scenario, and a scenario that a gap conditions states that condition.
34
34
  - **Neither** — a test (an end-to-end test included), a type assertion, a lint entry or a deterministic check that CI runs proves the rule. It stays REQUIRED and unmarked.
35
35
 
36
36
  ## The evidence ladder — cheapest first
@@ -7,11 +7,11 @@ An audit's findings go to the owner as one Markdown review file. The owner answe
7
7
  Each item has a scan line and five bullets. The bullet labels are fixed — the parser reads them.
8
8
 
9
9
  ```md
10
- ### R-007 · SPEC-ADVISORY · CXAD apps/mastra · 1, 6
10
+ ### R-007 · SPEC-ADVISORY · SHOP checkout · 1, 6
11
11
 
12
- - Rule: “The A2A endpoint and Agent Card are the ONLY surface a consumer may target”
13
- - Location: `CXAD openspec/specs/apps/mastra/spec.md:20`
14
- - What’s wrong: <the concrete problem>. Evidence: `apps/mastra/src/main.ts:59`.
12
+ - Rule: “The public HTTP API is the ONLY surface a client may target”
13
+ - Location: `SHOP openspec/specs/checkout/spec.md:20`
14
+ - What’s wrong: <the concrete problem>. Evidence: `src/checkout/server.ts:59`.
15
15
  - Proposed: Reclassify → OpenSpec ⚠️ ADVISORY — <exactly what to do>
16
16
  - My response: ⬜
17
17
  ```
@@ -29,8 +29,8 @@ When several rules share one problem and one solution, they become a single them
29
29
  ### R-012 · DELETE · Theme: Scenarios that restate their requirement · 19, 20
30
30
 
31
31
  - Rule: “Scenarios that restate their requirement” — 3 rules:
32
- - “WHEN the module is evaluated THEN no instance exists until the factory runs” — `CXAD openspec/specs/apps/mastra/spec.md:31`
33
- - “…” — `APC openspec/specs/client/spec.md:88` — member-specific note
32
+ - “WHEN the module is evaluated THEN no instance exists until the factory runs” — `SHOP openspec/specs/checkout/spec.md:31`
33
+ - “…” — `BILLING openspec/specs/invoices/spec.md:88` — member-specific note
34
34
  - Location: each member above
35
35
  - What’s wrong: …
36
36
  - Proposed: …
@@ -4,10 +4,10 @@ A skill is discovered at the agent's discretion, so it cannot be the only thing
4
4
 
5
5
  | Point | What it does | Placed by |
6
6
  | --- | --- | --- |
7
- | Scoped rule `.agents/rules/openspec.md` (+ `.claude/rules`, `.codex/rules`) | Hard constraints, loaded when the agent touches `openspec/**`. | `lint-prepare` (`@kirill.konshin/lint`) |
8
- | Skill `.agents/skills/spec-steward` (+ `.claude/skills`, `.codex/skills`) | The procedures, the model, the contract and the scripts. | `lint-prepare` |
7
+ | Scoped rule `.agents/rules/openspec.md` (+ `.claude/rules`) | Hard constraints, loaded when the agent touches `openspec/**`. | `lint-prepare` (`@kirill.konshin/lint`) |
8
+ | Skill `.agents/skills/spec-steward` (+ `.claude/skills`) | The procedures, the model, the contract and the scripts. | `lint-prepare` |
9
9
  | Edit hook in `.claude/settings.json` | Runs `steward hook` after every Edit/Write/MultiEdit and feeds findings back to the agent at once — only for what the edit changed, with no ratchet. | `steward wire --fix` |
10
- | Routing line in `AGENTS.md` | Tells every agent, Codex included, where the guard lives, and that corpus-quality audits use this skill while code conformance is the repository's own audit. | You, beside the specification-driven convention; `wire --fix` prints the line. |
10
+ | Routing line in `AGENTS.md` | Tells every agent, Codex included, where the guard lives, and that corpus-quality audits use this skill while code conformance is the `spec-verify` audit. | You, beside the specification-driven convention; `wire --fix` prints the line. |
11
11
  | OPSX operation guidance in `openspec/config.yaml` | One narrow line each for `apply` and `archive`: run the repository's spec gate (AGENTS.md → Checks); a `weakened` finding stops the flow. | `steward wire --fix`, when the file has OpenSpec's standard shape |
12
12
 
13
13
  These five points keep to the placement rules:
@@ -16,4 +16,4 @@ These five points keep to the placement rules:
16
16
  - The OPSX `context` stays untouched: it already carries `AGENTS.md`.
17
17
  - The hook is a no-op where the skill is not installed, so teammates without it are not blocked.
18
18
 
19
- **The gate.** A repository's spec gate (`spec:gates` and its CI job, listed in `AGENTS.md` → Checks) runs `steward check --base auto`, passing the repository's `--binds` globs, and then whatever change gates the repository keeps. Error findings fail it; warnings and prompts never do ([contract](contract.md#kinds-and-severities)). Steward is the one spec engine, so it never runs as a second job beside an existing gate, and the repository keeps no copy of a check steward implements. Whether a repository puts the gate in CI is its owner's decision.
19
+ **The gate.** A repository's spec gate (`spec-tools gates` and its CI job, listed in `AGENTS.md` → Checks) runs `steward check --base auto` with the repository's binds — `"spec-steward": { "binds": [...] }` in its root `package.json` — and then the change gates. Error findings fail it; warnings and prompts never do ([contract](contract.md#kinds-and-severities)). Steward is the one spec engine, so it never runs as a second job beside an existing gate, and the repository keeps no copy of a check steward implements. Whether a repository puts the gate in CI is its owner's decision.
@@ -0,0 +1,67 @@
1
+ # Audit worker
2
+
3
+ What one worker of the corpus-quality audit does. `spec-tools workers --audit spec-steward` starts one per unit of the scope and names, in its brief, the unit, the files to read and the findings file to write. The audit's procedure around the workers is [audit.md](audit.md).
4
+
5
+ ## The standard
6
+
7
+ Read these first, in full — they are what you judge by: [model.md](model.md), [criteria.md](criteria.md), and the placement guide, `rules/agent.md` of this package.
8
+
9
+ - Specification quality first. An ordinary implementation bug is out of scope unless it reveals the rule is unrealistic, unclear, outdated, ambiguous, or contradicted by what the tests actually assert. Whether code conforms is the `spec-verify` audit's.
10
+ - Comments, descriptions, prompt text and citations are never evidence that code complies, and never a violation by themselves. Judge executable behaviour and structure.
11
+ - For every rule you would keep REQUIRED, ask what meaningful failure its verification catches. Never propose a test merely because a rule lacks one, and never a test of incidental text or structure.
12
+ - Internal component and API contracts are legitimate specification. The line is contract versus implementation or process, not product versus engineering.
13
+ - Do not decide intent silently: when the meaning is ambiguous, describe the readings, propose options and set `needsHumanIntent`.
14
+ - No style preferences: every finding states a concrete problem.
15
+ - A proposal that reverses an earlier owner decision says so, in `reversesPastDecision`.
16
+ - Quote the original text verbatim, from the line you name; open the file to confirm before writing it.
17
+
18
+ The audit is read-only: you write your findings file and nothing else. Your tools are Read, Glob, Grep, Write and the read-only git commands; anything else is denied and only costs a turn.
19
+
20
+ ## Your unit
21
+
22
+ - **A part** is a set of capabilities, each as its evidence file under `audit-parts/` quotes it: every requirement verbatim with its line, the tests bound to it, where its terms occur, and its related requirements elsewhere. Read the evidence files and the specifications they name in full, then trace into code and tests wherever a verdict depends on them. Every requirement of the part is either in a finding (on it or one of its scenarios) or in `sound`, and every one you judged is in `judged`.
23
+ - **A sweep** looks across the corpus from one angle — its focus names the criteria. Read the files the brief lists; `judged` and `sound` may stay empty.
24
+
25
+ ## The findings file
26
+
27
+ One finding per rule and problem. A rule may be a requirement, a scenario, a sentence, or — outside the specifications — a section or line of `AGENTS.md`, a skill, a configuration, a script or a CI job. Write the file once with the Write tool, plain JSON:
28
+
29
+ ```json
30
+ {
31
+ "part": 3,
32
+ "reader": 1,
33
+ "findings": [
34
+ {
35
+ "file": "openspec/specs/billing/refunds/spec.md",
36
+ "line": 12,
37
+ "quote": "The service SHALL apply a refund at most once per request id",
38
+ "level": "requirement",
39
+ "ruleName": "Refunds are idempotent",
40
+ "criteria": [6, 7],
41
+ "layer": "SPEC-ADVISORY",
42
+ "whatsWrong": "<the concrete problem, one or two sentences>",
43
+ "proposed": "Reclassify → OpenSpec ⚠️ ADVISORY — <exactly what to do>",
44
+ "evidence": ["src/refunds.ts:40"],
45
+ "crossRefs": [],
46
+ "themeKey": "unverifiable-absolute",
47
+ "needsHumanIntent": false,
48
+ "reversesPastDecision": "",
49
+ "confidence": "high"
50
+ }
51
+ ],
52
+ "sound": ["billing/refunds#requirement-a-refund-names-its-order"],
53
+ "judged": [
54
+ "billing/refunds#requirement-refunds-are-idempotent",
55
+ "billing/refunds#requirement-a-refund-names-its-order"
56
+ ],
57
+ "notes": []
58
+ }
59
+ ```
60
+
61
+ - `file` is repository-relative; `line` is where the quoted text is; `quote` is verbatim, at most 300 characters, `…` eliding. The merge looks the quote up at its line and drops a finding whose quote is not there.
62
+ - `criteria` are numbers from [criteria.md](criteria.md). `proposed` starts with the target notation (`Keep →`, `Reclassify →`, `Move →`, `Replace →`, `Merge →`, `Rewrite →`, `Delete →`) and says exactly what to do: a rewrite gives the new text, a move names the target file.
63
+ - `layer` is the owning layer you propose: `SPEC-REQUIRED`, `SPEC-ADVISORY`, `DESIGN`, `AGENTS`, `RULE`, `SKILL`, `COMMAND`, `OPSX-CONFIG`, `README`, `TOOLING`, `TEST`, `CI`, `MERGE`, `REWRITE` or `DELETE`.
64
+ - `themeKey` names the underlying problem — one of `restating-scenario`, `single-scenario-padding`, `bdd-verbosity`, `impl-detail-in-spec`, `coding-convention-in-spec`, `process-rule-in-spec`, `agent-steering-as-spec`, `tooling-should-enforce`, `textual-test`, `comment-as-evidence`, `citation-upkeep`, `unverifiable-absolute`, `vague-obligation`, `advisory-not-required`, `duplicate-rule`, `cross-repo-drift`, `contradiction`, `stale-rule`, `scope-unclear`, `repo-wide-reasoning`, `placement-duplication`, `agents-md-bloat`, `ci-cost`, `missing-invariant`, `gap-marker` — or a new kebab-case key only when none fits. The merge groups findings that share one into a theme.
65
+ - `sound` lists the requirements you judged correct, well placed and adequately evidenced, as `capability#requirement-slug`; `judged` lists every requirement you judged, finding or not. A requirement of your part missing from `judged` is judged again by a completion worker.
66
+
67
+ Be aggressive about questionable specification design and conservative about deciding intent. Then return one line: the path and your count of findings.
@@ -1,7 +1,8 @@
1
1
  // @ts-check
2
2
  /**
3
3
  * Rules shared by several repositories, compared: capabilities pair by path or by leaf name, requirements by anchor or
4
- * by text. Reports identical, drifted and one-sided rules; choosing the wording stays with the owner.
4
+ * by statement. A rule is its name and statement; its scenarios are each repository's own, so a scenario only one
5
+ * repository has is not drift. Reports identical, drifted and one-sided rules; choosing the wording stays with the owner.
5
6
  */
6
7
  import { loadCorpus } from './corpus.mjs';
7
8
  import { jaccard, normalize, words } from './util.mjs';
@@ -11,8 +12,8 @@ import { jaccard, normalize, words } from './util.mjs';
11
12
  * @typedef {import('./corpus.mjs').Requirement} Requirement
12
13
  */
13
14
 
14
- /** Body without heading, normalized. @param {Requirement} r */
15
- const body = (r) => normalize(r.block.split('\n').slice(1).join('\n'));
15
+ /** The rule's own words: its statement, without its markers and scenarios, normalized. @param {Requirement} r */
16
+ const statement = (r) => normalize(r.statement);
16
17
 
17
18
  /**
18
19
  * Word-level difference of two texts: the words only one side has, in order.
@@ -46,7 +47,7 @@ export function align(a, b) {
46
47
  if (!rb) {
47
48
  const best = cb.requirements
48
49
  .filter((x) => !used.has(x.slug))
49
- .map((x) => ({ x, s: jaccard(words(ra.block), words(x.block)) }))
50
+ .map((x) => ({ x, s: jaccard(words(ra.statement), words(x.statement)) }))
50
51
  .sort((p, q) => q.s - p.s)[0];
51
52
  if (best && best.s >= 0.5) rb = best.x;
52
53
  }
@@ -55,12 +56,12 @@ export function align(a, b) {
55
56
  continue;
56
57
  }
57
58
  used.add(rb.slug);
58
- const same = body(ra) === body(rb) && ra.name === rb.name;
59
+ const same = statement(ra) === statement(rb) && ra.name === rb.name;
59
60
  reqs.push({
60
61
  kind: same ? 'identical' : 'drift',
61
62
  a: ra,
62
63
  b: rb,
63
- ...(same ? {} : wordDiff(ra.block, rb.block)),
64
+ ...(same ? {} : wordDiff(ra.statement, rb.statement)),
64
65
  });
65
66
  }
66
67
  for (const rb of cb.requirements) if (!used.has(rb.slug)) reqs.push({ kind: 'only-b', b: rb });
@@ -203,6 +203,11 @@ function markerFindings(r) {
203
203
  m.line,
204
204
  "Advisory is the requirement's class — put it directly under the requirement heading; in a scenario it grants nothing",
205
205
  );
206
+ else if (m.label === KNOWN_GAP && m.scenario)
207
+ warn(
208
+ m.line,
209
+ 'a Known gap goes under the requirement statement and names the scenarios it exempts by title; inside a scenario it grants nothing',
210
+ );
206
211
  else {
207
212
  const canon = m.label === ADVISORY ? DEFAULT_MARKERS[0] : `**⚠️ Known gap (${m.tracker}):**`;
208
213
  if (!m.text.startsWith(canon)) {
@@ -212,7 +217,7 @@ function markerFindings(r) {
212
217
  }
213
218
  }
214
219
  for (const g of r.gaps)
215
- if (g.named && !g.exempts.some((s) => s !== g.scenario))
220
+ if (g.named && !g.exempts.length)
216
221
  warn(
217
222
  g.line,
218
223
  'names no scenario of this requirement by its title — a Known gap exempts only the scenarios it names',
@@ -2,7 +2,7 @@
2
2
  /**
3
3
  * The OpenSpec corpus as data: capabilities, requirements, scenarios, each with its line and anchor, and the two
4
4
  * markers a requirement can carry — `**⚠️ Advisory:**` (its class) and `**⚠️ Known gap (<tracker>):**` (a gap,
5
- * exempting the scenarios it names or whose block it sits in).
5
+ * exempting the scenarios it names by title).
6
6
  */
7
7
  import fs from 'node:fs';
8
8
  import path from 'node:path';
@@ -14,8 +14,7 @@ import { slugify, stripCode, strongCount, weakCount } from './util.mjs';
14
14
  * @typedef {{ kw: string, text: string, line: number }} Step
15
15
  * @typedef {{ label: string, tracker: string | null, line: number, text: string, scenario: string | null,
16
16
  * inline: boolean }} Marker
17
- * @typedef {{ tracker: string, text: string, line: number, scenario: string | null, exempts: string[],
18
- * named: boolean }} Gap
17
+ * @typedef {{ tracker: string, text: string, line: number, exempts: string[], named: boolean }} Gap
19
18
  * @typedef {{ name: string, slug: string, line: number, end: number, block: string, steps: Step[],
20
19
  * markers: Marker[] }} Scenario
21
20
  * @typedef {{
@@ -114,16 +113,14 @@ export function parseSpec(text, file, capability) {
114
113
  const own = r.markers.filter((m) => !m.inline);
115
114
  r.advisory = own.some((m) => m.label === ADVISORY && !m.scenario);
116
115
  r.gaps = own
117
- .filter((m) => m.label === KNOWN_GAP && m.tracker)
116
+ .filter((m) => m.label === KNOWN_GAP && m.tracker && !m.scenario)
118
117
  .map((m) => {
119
118
  const named = namedIn(m.text, r.scenarios);
120
- const exempts = [...new Set([...(m.scenario ? [m.scenario] : []), ...(named ?? [])])];
121
119
  return {
122
120
  tracker: /** @type {string} */ (m.tracker),
123
121
  text: m.text,
124
122
  line: m.line,
125
- scenario: m.scenario,
126
- exempts,
123
+ exempts: named ?? [],
127
124
  named: named !== null,
128
125
  };
129
126
  });
@@ -215,7 +212,7 @@ function walkSpecs(dir) {
215
212
  return out.sort();
216
213
  }
217
214
 
218
- /** `openspec/specs/apps/mastra/spec.md` → `apps/mastra`. @param {string} specsDir @param {string} file */
215
+ /** `openspec/specs/billing/refunds/spec.md` → `billing/refunds`. @param {string} specsDir @param {string} file */
219
216
  export const capabilityOf = (specsDir, file) => path.relative(specsDir, path.dirname(file)).split(path.sep).join('/');
220
217
 
221
218
  /**
@@ -60,14 +60,13 @@ export function coverageReport(corpus, citations) {
60
60
  const scenarioBound = (/** @type {import('./corpus.mjs').Scenario} */ s) =>
61
61
  bound.has(`${r.file}#${s.slug}`) || (r.scenarios.length === 1 && bound.has(reqKey));
62
62
  const anyBound = bound.has(reqKey) || r.scenarios.some(scenarioBound);
63
- const requirementGaps = r.gaps.filter((g) => !g.scenario);
64
63
  if (r.advisory) totals.advisory++;
65
64
  totals.gaps += r.gaps.length;
66
65
  if (!r.advisory && !anyBound) totals.unboundRequirements++;
67
66
  const status = r.advisory
68
67
  ? 'advisory'
69
- : requirementGaps.length
70
- ? `known gap (${requirementGaps.map((g) => mdx(g.tracker)).join(', ')})`
68
+ : r.gaps.length
69
+ ? `known gap (${r.gaps.map((g) => mdx(g.tracker)).join(', ')})`
71
70
  : anyBound
72
71
  ? 'tested'
73
72
  : 'no test';
@@ -3,7 +3,7 @@
3
3
  * Evidence for an audit, assembled mechanically so a reader judges instead of searching. For every requirement: the
4
4
  * tests bound to it and its scenarios, and where its own terms occur in the sources with comments stripped. Code
5
5
  * citations are optional pointers, listed when present and never evidence. Every excerpt keeps its file's own line
6
- * numbers. Two shapes: per-capability Markdown bundles (`evidence --out`) and one JSON model (`evidence --json`).
6
+ * numbers, as one JSON model (`evidence --json`) — what spec-tools assembles each audit's evidence files from.
7
7
  */
8
8
  import fs from 'node:fs';
9
9
  import path from 'node:path';
@@ -12,7 +12,7 @@ import { isTestFile } from './citations.mjs';
12
12
  import { allRequirements } from './corpus.mjs';
13
13
  import { listFiles } from './git.mjs';
14
14
  import { stripComments } from './scan.mjs';
15
- import { codeTokens, jaccard, sentences, words } from './util.mjs';
15
+ import { codeTokens, jaccard, words } from './util.mjs';
16
16
 
17
17
  /**
18
18
  * @typedef {import('./corpus.mjs').Corpus} Corpus
@@ -38,17 +38,6 @@ const COMMON = new Set([
38
38
  'type',
39
39
  ]);
40
40
 
41
- /** Lines `[from, to]` of a file with their numbers. @param {string[]} lines @param {number} from @param {number} to */
42
- const numbered = (lines, from, to) =>
43
- lines
44
- .slice(from - 1, to)
45
- .map((l, i) => `${String(from + i).padStart(5)}│ ${l}`)
46
- .join('\n');
47
-
48
- /** @param {string} file */
49
- const fence = (file) =>
50
- /\.(?:[cm]?[jt]sx?)$/.test(file) ? 'ts' : /\.ya?ml$/.test(file) ? 'yaml' : /\.json$/.test(file) ? 'json' : '';
51
-
52
41
  /**
53
42
  * The non-test source files of a repository, read once, comments blanked for searching.
54
43
  * @param {string} root
@@ -165,7 +154,6 @@ export function evidenceModel(corpus, citations, sources) {
165
154
  tracker: g.tracker,
166
155
  text: g.text,
167
156
  line: g.line,
168
- scenario: g.scenario,
169
157
  exempts: g.exempts,
170
158
  })),
171
159
  scenarios: r.scenarios.map((s) => ({
@@ -199,137 +187,3 @@ export function evidenceModel(corpus, citations, sources) {
199
187
  }),
200
188
  };
201
189
  }
202
-
203
- /**
204
- * One capability's evidence, as markdown.
205
- * @param {Corpus} corpus
206
- * @param {import('./corpus.mjs').Capability} cap
207
- * @param {Citation[]} citations
208
- * @param {Source[]} sources
209
- * @param {{ corpus: Corpus, requirement: Requirement }[]} everywhere every requirement of every corpus in the run
210
- */
211
- export function capabilityEvidence(corpus, cap, citations, sources, everywhere) {
212
- const specLines = fs.readFileSync(path.join(corpus.path, cap.file), 'utf8').split('\n');
213
- const fileLines = new Map();
214
- const linesOf = (/** @type {string} */ f) => {
215
- if (!fileLines.has(f)) fileLines.set(f, fs.readFileSync(path.join(corpus.path, f), 'utf8').split('\n'));
216
- return fileLines.get(f);
217
- };
218
- const out = [
219
- `# ${corpus.name} \`${cap.capability}\` — evidence`,
220
- '',
221
- `Spec \`${cap.file}\` in ${corpus.name} (\`${corpus.path}\`). Generated by spec-steward; every excerpt keeps its file's own line numbers. Bound tests come first: a test block, type assertion or lint entry citing a scenario is the binding that matters. Code citations are optional pointers, never evidence; "where its terms occur" is a search of comment-stripped sources, a lead to read, not a verdict.`,
222
- '',
223
- '## Purpose',
224
- '',
225
- cap.purpose || '_(none)_',
226
- '',
227
- ];
228
- for (const r of cap.requirements) {
229
- const cites = citationsOf(r, citations);
230
- const tests = cites.filter((c) => c.binding);
231
- const code = cites.filter((c) => !c.binding);
232
- out.push(
233
- '---',
234
- '',
235
- `## \`${r.id}\` — \`${r.file}:${r.line}\`${r.advisory ? ' — ⚠️ Advisory' : ''}`,
236
- '',
237
- '```md',
238
- numbered(specLines, r.line, r.end),
239
- '```',
240
- '',
241
- );
242
-
243
- out.push(`### Bound tests (${tests.length})`, '');
244
- if (!tests.length) out.push('_Nothing binds this requirement or its scenarios._', '');
245
- for (const t of tests) {
246
- const lines = linesOf(t.file);
247
- const [from, to] = [Math.max(1, t.window[0]), Math.min(lines.length, t.window[1], t.window[0] + 70)];
248
- out.push(
249
- `\`${t.file}:${t.line}\` → \`#${t.anchor}\`${t.testTitle ? ` — "${t.testTitle}"` : ''}${to < t.window[1] ? ' (window cut)' : ''}`,
250
- '',
251
- '```' + fence(t.file),
252
- numbered(lines, from, to),
253
- '```',
254
- '',
255
- );
256
- }
257
- if (code.length) {
258
- out.push(`### Pointers (${code.length}) — code citations, not evidence`, '');
259
- for (const c of code) {
260
- const lines = linesOf(c.file);
261
- out.push(
262
- `\`${c.file}:${c.line}\``,
263
- '',
264
- '```' + fence(c.file),
265
- numbered(lines, Math.max(1, c.line - 2), Math.min(lines.length, c.line + 20)),
266
- '```',
267
- '',
268
- );
269
- }
270
- }
271
- const terms = searchTerms(r);
272
- const hits = [];
273
- for (const term of terms.slice(0, 8)) {
274
- const found = termHits(term, sources).slice(0, 3);
275
- for (const h of found) {
276
- const src = sources.find((s) => s.file === h.file);
277
- const text = (src?.lines[h.line - 1] ?? '').trim().slice(0, 160).replace(/`/g, "'");
278
- hits.push(`- \`${term}\` — \`${h.file}:${h.line}\`: \`${text}\``);
279
- }
280
- if (!found.length) hits.push(`- \`${term}\` — no source contains it`);
281
- }
282
- out.push('### Where its terms occur', '', hits.length ? hits.join('\n') : '_It names no code terms._', '');
283
-
284
- const related = relatedOf(r, everywhere, corpus);
285
- if (related.length) {
286
- out.push('### Related requirements', '');
287
- for (const { x, shared } of related)
288
- out.push(
289
- `- ${x.corpus.name} \`${x.requirement.id}\` (\`${x.requirement.file}:${x.requirement.line}\`)${
290
- shared.length
291
- ? ` — shares ${shared
292
- .slice(0, 4)
293
- .map((t) => `\`${t}\``)
294
- .join(', ')}`
295
- : ''
296
- }: ${(sentences(x.requirement.statement)[0] ?? '').slice(0, 220)}`,
297
- );
298
- out.push('');
299
- }
300
- }
301
- return out.join('\n');
302
- }
303
-
304
- /**
305
- * Balanced parts for parallel readers; same-named capabilities across repositories stay in one part.
306
- * @param {{ corpus: string, capability: string, file: string, bytes: number, requirementIds: string[] }[]} bundles
307
- * @param {number} parts
308
- */
309
- export function partition(bundles, parts) {
310
- const groups = new Map();
311
- for (const b of bundles) {
312
- const key = b.capability.split('/').pop();
313
- groups.set(key, [...(groups.get(key) ?? []), b]);
314
- }
315
- const bins = Array.from({ length: Math.max(1, parts) }, (_, i) => ({
316
- part: i + 1,
317
- bytes: 0,
318
- files: /** @type {string[]} */ ([]),
319
- capabilities: /** @type {string[]} */ ([]),
320
- requirementIds: /** @type {string[]} */ ([]),
321
- }));
322
- const sorted = [...groups.values()].sort(
323
- (a, b) => b.reduce((s, x) => s + x.bytes, 0) - a.reduce((s, x) => s + x.bytes, 0),
324
- );
325
- for (const group of sorted) {
326
- const bin = bins.reduce((min, x) => (x.bytes < min.bytes ? x : min));
327
- for (const b of group) {
328
- bin.bytes += b.bytes;
329
- bin.files.push(b.file);
330
- bin.capabilities.push(`${b.corpus}:${b.capability}`);
331
- bin.requirementIds.push(...b.requirementIds.map((id) => `${b.corpus}:${id}`));
332
- }
333
- }
334
- return bins.filter((b) => b.files.length);
335
- }