@kirill.konshin/lint 0.5.5 → 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.
- package/README.md +38 -3
- package/commands/spec-author.md +39 -0
- package/dist/configs/base.d.ts +4 -3
- package/dist/configs/base.js +61 -74
- package/dist/configs/imports.d.ts +3 -2
- package/dist/configs/imports.js +95 -146
- package/dist/configs/nx.d.ts +4 -3
- package/dist/configs/nx.js +31 -41
- package/dist/configs/prettier.d.ts +3 -2
- package/dist/configs/prettier.js +19 -16
- package/dist/configs/promise.d.ts +3 -2
- package/dist/configs/promise.js +16 -16
- package/dist/configs/react.d.ts +4 -3
- package/dist/configs/react.js +178 -217
- package/dist/configs/storybook.d.ts +4 -3
- package/dist/configs/storybook.js +22 -22
- package/dist/configs/tailwind.d.ts +4 -3
- package/dist/configs/tailwind.js +67 -91
- package/dist/configs/testing.d.ts +7 -6
- package/dist/configs/testing.js +112 -146
- package/dist/configs/turbo.d.ts +4 -3
- package/dist/configs/turbo.js +19 -27
- package/dist/configs/typescriptTypeAware.d.ts +4 -3
- package/dist/configs/typescriptTypeAware.js +99 -95
- package/dist/configs/unicorn.d.ts +3 -2
- package/dist/configs/unicorn.js +34 -41
- package/dist/exts.d.ts +2 -1
- package/dist/exts.js +10 -11
- package/dist/index.d.ts +44 -42
- package/dist/index.js +53 -85
- package/dist/lib.d.ts +21 -21
- package/dist/lib.js +261 -301
- package/dist/lintPrepare.d.ts +20 -17
- package/dist/lintPrepare.js +341 -371
- package/dist/lintStaged.d.ts +4 -3
- package/dist/lintStaged.js +25 -22
- package/dist/prettier.d.ts +4 -3
- package/dist/prettier.js +16 -17
- package/dist/restrictions.d.ts +11 -10
- package/dist/restrictions.js +18 -22
- package/dist/yarn.cjs +79 -98
- package/dist/yarn.d.cts +3 -2
- package/package.json +24 -8
- package/rules/agent.md +2 -0
- package/rules/openspec.md +1 -1
- package/skills/spec-steward/SKILL.md +3 -11
- package/skills/spec-steward/references/audit.md +18 -43
- package/skills/spec-steward/references/contract.md +4 -4
- package/skills/spec-steward/references/criteria.md +4 -4
- package/skills/spec-steward/references/review-format.md +6 -6
- package/skills/spec-steward/references/wiring.md +2 -2
- package/skills/spec-steward/references/worker.md +67 -0
- package/skills/spec-steward/scripts/lib/corpus.mjs +1 -1
- package/skills/spec-steward/scripts/lib/evidence.mjs +2 -147
- package/skills/spec-steward/scripts/lib/wire.mjs +6 -4
- package/skills/spec-steward/scripts/steward.mjs +30 -91
- package/skills/spec-steward/sweeps.json +49 -0
- package/skills/spec-tools/SKILL.md +46 -0
- package/skills/spec-tools/references/contract.md +111 -0
- package/skills/spec-tools/references/gitlab.md +122 -0
- package/skills/spec-verify/SKILL.md +153 -0
- package/spec-tools/dist/audit-DkZZulq6.mjs +130 -0
- package/spec-tools/dist/auditChanged-CNGjlake.mjs +1 -0
- package/spec-tools/dist/auditChanged-CZCvMgyZ.mjs +618 -0
- package/spec-tools/dist/auditReport-xgq4wK2i.mjs +458 -0
- package/spec-tools/dist/auditScope-CBuBtfPG.mjs +104 -0
- package/spec-tools/dist/changeGates-DdeQKfle.mjs +333 -0
- package/spec-tools/dist/changeGates-uy4Ti8rK.mjs +1 -0
- package/spec-tools/dist/ci-BUewHJS3.mjs +143 -0
- package/spec-tools/dist/ci-CFBzn8Of.mjs +1 -0
- package/spec-tools/dist/cli.mjs +93 -0
- package/spec-tools/dist/comment-szasMMg2.mjs +57 -0
- package/spec-tools/dist/files-Bppsb34B.mjs +1 -0
- package/spec-tools/dist/files-QlzY687_.mjs +38 -0
- package/spec-tools/dist/html-BMTkpbUN.mjs +1766 -0
- package/spec-tools/dist/jsonrepair-Dlm5dEen.mjs +742 -0
- package/spec-tools/dist/repo-CjIoUPYl.mjs +16 -0
- package/spec-tools/dist/repo-DUcnJw3c.mjs +1 -0
- package/spec-tools/dist/run-BElA9du3.mjs +67 -0
- package/spec-tools/dist/specDiff-8G56jMYn.mjs +123 -0
- package/spec-tools/dist/steward-DeieyOcj.mjs +34 -0
- package/spec-tools/dist/stewardAudit-BRMM0lrD.mjs +1 -0
- package/spec-tools/dist/stewardAudit-v0vOMfLN.mjs +271 -0
- package/spec-tools/dist/tier-Cn0P7juM.mjs +1 -0
- package/spec-tools/dist/tier-c3s_mA_I.mjs +65 -0
- package/spec-tools/dist/util-wnxhsnWO.mjs +49 -0
- package/spec-tools/dist/verdict-BFfN9PO8.mjs +58 -0
- package/spec-tools/dist/workers-BcIgckeq.mjs +417 -0
- package/spec-tools/dist/workflowEvidence-DyBj8EdG.mjs +1 -0
- package/spec-tools/dist/workflowEvidence-oui6ghPI.mjs +78 -0
- package/dist/configs/base.d.ts.map +0 -1
- package/dist/configs/imports.d.ts.map +0 -1
- package/dist/configs/nx.d.ts.map +0 -1
- package/dist/configs/prettier.d.ts.map +0 -1
- package/dist/configs/promise.d.ts.map +0 -1
- package/dist/configs/react.d.ts.map +0 -1
- package/dist/configs/storybook.d.ts.map +0 -1
- package/dist/configs/tailwind.d.ts.map +0 -1
- package/dist/configs/testing.d.ts.map +0 -1
- package/dist/configs/turbo.d.ts.map +0 -1
- package/dist/configs/typescriptTypeAware.d.ts.map +0 -1
- package/dist/configs/unicorn.d.ts.map +0 -1
- package/dist/exts.d.ts.map +0 -1
- package/dist/index.d.ts.map +0 -1
- package/dist/lib.d.ts.map +0 -1
- package/dist/lintPrepare.d.ts.map +0 -1
- package/dist/lintStaged.d.ts.map +0 -1
- package/dist/prettier.d.ts.map +0 -1
- package/dist/restrictions.d.ts.map +0 -1
- package/dist/yarn.d.cts.map +0 -1
- package/skills/spec-steward/workflows/audit.js +0 -539
|
@@ -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
|
|
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
|
|
|
@@ -56,7 +56,7 @@ There are exactly two markers. Each stands on a line of its own: the Advisory li
|
|
|
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 (`
|
|
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
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
|
|
|
@@ -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
|
|
137
|
-
| `spec-steward
|
|
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
|
|
|
@@ -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.
|
|
@@ -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 ·
|
|
10
|
+
### R-007 · SPEC-ADVISORY · SHOP checkout · 1, 6
|
|
11
11
|
|
|
12
|
-
- Rule: “The
|
|
13
|
-
- Location: `
|
|
14
|
-
- What’s wrong: <the concrete problem>. Evidence: `
|
|
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” — `
|
|
33
|
-
- “…” — `
|
|
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: …
|
|
@@ -7,7 +7,7 @@ A skill is discovered at the agent's discretion, so it cannot be the only thing
|
|
|
7
7
|
| Scoped rule `.agents/rules/openspec.md` (+ `.claude/rules`) | Hard constraints, loaded when the agent touches `openspec/**`. | `lint-prepare` (`@kirill.konshin/lint`) |
|
|
8
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
|
|
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
|
|
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.
|
|
@@ -212,7 +212,7 @@ function walkSpecs(dir) {
|
|
|
212
212
|
return out.sort();
|
|
213
213
|
}
|
|
214
214
|
|
|
215
|
-
/** `openspec/specs/
|
|
215
|
+
/** `openspec/specs/billing/refunds/spec.md` → `billing/refunds`. @param {string} specsDir @param {string} file */
|
|
216
216
|
export const capabilityOf = (specsDir, file) => path.relative(specsDir, path.dirname(file)).split(path.sep).join('/');
|
|
217
217
|
|
|
218
218
|
/**
|
|
@@ -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
|
|
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,
|
|
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
|
|
@@ -198,137 +187,3 @@ export function evidenceModel(corpus, citations, sources) {
|
|
|
198
187
|
}),
|
|
199
188
|
};
|
|
200
189
|
}
|
|
201
|
-
|
|
202
|
-
/**
|
|
203
|
-
* One capability's evidence, as markdown.
|
|
204
|
-
* @param {Corpus} corpus
|
|
205
|
-
* @param {import('./corpus.mjs').Capability} cap
|
|
206
|
-
* @param {Citation[]} citations
|
|
207
|
-
* @param {Source[]} sources
|
|
208
|
-
* @param {{ corpus: Corpus, requirement: Requirement }[]} everywhere every requirement of every corpus in the run
|
|
209
|
-
*/
|
|
210
|
-
export function capabilityEvidence(corpus, cap, citations, sources, everywhere) {
|
|
211
|
-
const specLines = fs.readFileSync(path.join(corpus.path, cap.file), 'utf8').split('\n');
|
|
212
|
-
const fileLines = new Map();
|
|
213
|
-
const linesOf = (/** @type {string} */ f) => {
|
|
214
|
-
if (!fileLines.has(f)) fileLines.set(f, fs.readFileSync(path.join(corpus.path, f), 'utf8').split('\n'));
|
|
215
|
-
return fileLines.get(f);
|
|
216
|
-
};
|
|
217
|
-
const out = [
|
|
218
|
-
`# ${corpus.name} \`${cap.capability}\` — evidence`,
|
|
219
|
-
'',
|
|
220
|
-
`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.`,
|
|
221
|
-
'',
|
|
222
|
-
'## Purpose',
|
|
223
|
-
'',
|
|
224
|
-
cap.purpose || '_(none)_',
|
|
225
|
-
'',
|
|
226
|
-
];
|
|
227
|
-
for (const r of cap.requirements) {
|
|
228
|
-
const cites = citationsOf(r, citations);
|
|
229
|
-
const tests = cites.filter((c) => c.binding);
|
|
230
|
-
const code = cites.filter((c) => !c.binding);
|
|
231
|
-
out.push(
|
|
232
|
-
'---',
|
|
233
|
-
'',
|
|
234
|
-
`## \`${r.id}\` — \`${r.file}:${r.line}\`${r.advisory ? ' — ⚠️ Advisory' : ''}`,
|
|
235
|
-
'',
|
|
236
|
-
'```md',
|
|
237
|
-
numbered(specLines, r.line, r.end),
|
|
238
|
-
'```',
|
|
239
|
-
'',
|
|
240
|
-
);
|
|
241
|
-
|
|
242
|
-
out.push(`### Bound tests (${tests.length})`, '');
|
|
243
|
-
if (!tests.length) out.push('_Nothing binds this requirement or its scenarios._', '');
|
|
244
|
-
for (const t of tests) {
|
|
245
|
-
const lines = linesOf(t.file);
|
|
246
|
-
const [from, to] = [Math.max(1, t.window[0]), Math.min(lines.length, t.window[1], t.window[0] + 70)];
|
|
247
|
-
out.push(
|
|
248
|
-
`\`${t.file}:${t.line}\` → \`#${t.anchor}\`${t.testTitle ? ` — "${t.testTitle}"` : ''}${to < t.window[1] ? ' (window cut)' : ''}`,
|
|
249
|
-
'',
|
|
250
|
-
'```' + fence(t.file),
|
|
251
|
-
numbered(lines, from, to),
|
|
252
|
-
'```',
|
|
253
|
-
'',
|
|
254
|
-
);
|
|
255
|
-
}
|
|
256
|
-
if (code.length) {
|
|
257
|
-
out.push(`### Pointers (${code.length}) — code citations, not evidence`, '');
|
|
258
|
-
for (const c of code) {
|
|
259
|
-
const lines = linesOf(c.file);
|
|
260
|
-
out.push(
|
|
261
|
-
`\`${c.file}:${c.line}\``,
|
|
262
|
-
'',
|
|
263
|
-
'```' + fence(c.file),
|
|
264
|
-
numbered(lines, Math.max(1, c.line - 2), Math.min(lines.length, c.line + 20)),
|
|
265
|
-
'```',
|
|
266
|
-
'',
|
|
267
|
-
);
|
|
268
|
-
}
|
|
269
|
-
}
|
|
270
|
-
const terms = searchTerms(r);
|
|
271
|
-
const hits = [];
|
|
272
|
-
for (const term of terms.slice(0, 8)) {
|
|
273
|
-
const found = termHits(term, sources).slice(0, 3);
|
|
274
|
-
for (const h of found) {
|
|
275
|
-
const src = sources.find((s) => s.file === h.file);
|
|
276
|
-
const text = (src?.lines[h.line - 1] ?? '').trim().slice(0, 160).replace(/`/g, "'");
|
|
277
|
-
hits.push(`- \`${term}\` — \`${h.file}:${h.line}\`: \`${text}\``);
|
|
278
|
-
}
|
|
279
|
-
if (!found.length) hits.push(`- \`${term}\` — no source contains it`);
|
|
280
|
-
}
|
|
281
|
-
out.push('### Where its terms occur', '', hits.length ? hits.join('\n') : '_It names no code terms._', '');
|
|
282
|
-
|
|
283
|
-
const related = relatedOf(r, everywhere, corpus);
|
|
284
|
-
if (related.length) {
|
|
285
|
-
out.push('### Related requirements', '');
|
|
286
|
-
for (const { x, shared } of related)
|
|
287
|
-
out.push(
|
|
288
|
-
`- ${x.corpus.name} \`${x.requirement.id}\` (\`${x.requirement.file}:${x.requirement.line}\`)${
|
|
289
|
-
shared.length
|
|
290
|
-
? ` — shares ${shared
|
|
291
|
-
.slice(0, 4)
|
|
292
|
-
.map((t) => `\`${t}\``)
|
|
293
|
-
.join(', ')}`
|
|
294
|
-
: ''
|
|
295
|
-
}: ${(sentences(x.requirement.statement)[0] ?? '').slice(0, 220)}`,
|
|
296
|
-
);
|
|
297
|
-
out.push('');
|
|
298
|
-
}
|
|
299
|
-
}
|
|
300
|
-
return out.join('\n');
|
|
301
|
-
}
|
|
302
|
-
|
|
303
|
-
/**
|
|
304
|
-
* Balanced parts for parallel readers; same-named capabilities across repositories stay in one part.
|
|
305
|
-
* @param {{ corpus: string, capability: string, file: string, bytes: number, requirementIds: string[] }[]} bundles
|
|
306
|
-
* @param {number} parts
|
|
307
|
-
*/
|
|
308
|
-
export function partition(bundles, parts) {
|
|
309
|
-
const groups = new Map();
|
|
310
|
-
for (const b of bundles) {
|
|
311
|
-
const key = b.capability.split('/').pop();
|
|
312
|
-
groups.set(key, [...(groups.get(key) ?? []), b]);
|
|
313
|
-
}
|
|
314
|
-
const bins = Array.from({ length: Math.max(1, parts) }, (_, i) => ({
|
|
315
|
-
part: i + 1,
|
|
316
|
-
bytes: 0,
|
|
317
|
-
files: /** @type {string[]} */ ([]),
|
|
318
|
-
capabilities: /** @type {string[]} */ ([]),
|
|
319
|
-
requirementIds: /** @type {string[]} */ ([]),
|
|
320
|
-
}));
|
|
321
|
-
const sorted = [...groups.values()].sort(
|
|
322
|
-
(a, b) => b.reduce((s, x) => s + x.bytes, 0) - a.reduce((s, x) => s + x.bytes, 0),
|
|
323
|
-
);
|
|
324
|
-
for (const group of sorted) {
|
|
325
|
-
const bin = bins.reduce((min, x) => (x.bytes < min.bytes ? x : min));
|
|
326
|
-
for (const b of group) {
|
|
327
|
-
bin.bytes += b.bytes;
|
|
328
|
-
bin.files.push(b.file);
|
|
329
|
-
bin.capabilities.push(`${b.corpus}:${b.capability}`);
|
|
330
|
-
bin.requirementIds.push(...b.requirementIds.map((id) => `${b.corpus}:${id}`));
|
|
331
|
-
}
|
|
332
|
-
}
|
|
333
|
-
return bins.filter((b) => b.files.length);
|
|
334
|
-
}
|
|
@@ -12,10 +12,11 @@ import { isTestFile, scanCitations } from './citations.mjs';
|
|
|
12
12
|
import { capabilityOf, DEFAULT_SPECS_DIR, parseSpec } from './corpus.mjs';
|
|
13
13
|
import { git, show, toplevel } from './git.mjs';
|
|
14
14
|
|
|
15
|
-
|
|
16
|
-
export const
|
|
15
|
+
/** The bin the package installs; the hook is a no-op until the repository's install provides it. */
|
|
16
|
+
export const BIN = 'node_modules/.bin/spec-steward';
|
|
17
|
+
export const HOOK_COMMAND = `f="$CLAUDE_PROJECT_DIR/${BIN}"; [ ! -x "$f" ] || "$f" hook`;
|
|
17
18
|
export const AGENTS_LINE =
|
|
18
|
-
|
|
19
|
+
'Specifications: edits under `openspec/` are guarded by the scoped rule `.agents/rules/openspec.md` and the `spec-steward` edit hook; corpus-quality audits, review rounds and cross-repository alignment use the `spec-steward` skill, and code conformance is the `spec-verify` audit (`spec-tools`).';
|
|
19
20
|
/** The OPSX guidance points at the repository's own spec gate; the gate runs spec-steward, so no second command. */
|
|
20
21
|
export const GATE_POINTER = 'AGENTS.md → Checks';
|
|
21
22
|
export const GUIDANCE = {
|
|
@@ -53,7 +54,8 @@ export function wireStatus(root) {
|
|
|
53
54
|
(e.hooks ?? []).some(
|
|
54
55
|
(/** @type {any} */ h) =>
|
|
55
56
|
typeof h.command === 'string' &&
|
|
56
|
-
|
|
57
|
+
// the bin, or the script by path as earlier versions wired it
|
|
58
|
+
/spec-steward|steward\.mjs/.test(h.command) &&
|
|
57
59
|
h.command.includes('hook'),
|
|
58
60
|
),
|
|
59
61
|
);
|
|
@@ -7,16 +7,14 @@
|
|
|
7
7
|
* spec-steward check [--base auto|<ref>] [--binds <glob>]... [--file f] [--fix] [--strict] [--json]
|
|
8
8
|
* [--max-words P,F] [--max-obligations P,F] the corpus gate (also local and the hook)
|
|
9
9
|
* spec-steward coverage [--out file] [--binds <glob>]... the coverage report, MDX-safe Markdown
|
|
10
|
-
* spec-steward evidence --json [--binds <glob>]... the
|
|
11
|
-
* spec-steward evidence --out dir [--root NAME=path]... per-capability evidence bundles
|
|
12
|
-
* spec-steward partition --out dir --parts N balanced parts over the bundles in --out
|
|
13
|
-
* spec-steward index [--full] [--binds <glob>]... corpus and citation summary as JSON
|
|
10
|
+
* spec-steward evidence --json [--binds <glob>]... the audits' evidence model on stdout
|
|
14
11
|
* spec-steward review render|status|verify|lint ... the review-file engine
|
|
15
12
|
* spec-steward align --root A=path --root B=path [--json] wording drift of shared rules across repos
|
|
16
13
|
* spec-steward wire [--check|--fix] the guard's steering points in a repository
|
|
17
14
|
* spec-steward hook Claude Code PostToolUse entry (stdin JSON)
|
|
18
15
|
*
|
|
19
|
-
* Common flags: --root NAME=path (repeatable), --specs <dir> (default openspec/specs).
|
|
16
|
+
* Common flags: --root NAME=path (repeatable), --specs <dir> (default openspec/specs). A repository's own binds live in its
|
|
17
|
+
* root package.json, `"spec-steward": { "binds": [...] }`, and add to every `--binds` given.
|
|
20
18
|
* Exit: 0 clean; 1 an error finding (or a warning under --strict); 2 a usage or environment error — an unknown flag,
|
|
21
19
|
* a base ref that does not exist, a git listing that fails or is empty, a missing specs directory.
|
|
22
20
|
*/
|
|
@@ -34,9 +32,9 @@ import {
|
|
|
34
32
|
SIZE,
|
|
35
33
|
} from './lib/checks.mjs';
|
|
36
34
|
import { scanCitations } from './lib/citations.mjs';
|
|
37
|
-
import {
|
|
35
|
+
import { DEFAULT_SPECS_DIR, loadCorpus, loadCorpusAt, parseSpec } from './lib/corpus.mjs';
|
|
38
36
|
import { coverageReport } from './lib/coverage.mjs';
|
|
39
|
-
import {
|
|
37
|
+
import { evidenceModel, sourceIndex } from './lib/evidence.mjs';
|
|
40
38
|
import { changedFiles, forget, listFiles, resolveBase, toplevel } from './lib/git.mjs';
|
|
41
39
|
import { parseArgs } from './lib/util.mjs';
|
|
42
40
|
|
|
@@ -46,12 +44,10 @@ const anchorsOf = (/** @type {string} */ text) => parseSpec(text, '', '').slugs;
|
|
|
46
44
|
const FLAGS = {
|
|
47
45
|
check: ['base', 'binds', 'file', 'fix', 'strict', 'json', 'max-words', 'max-obligations', 'all-citations'],
|
|
48
46
|
coverage: ['out', 'binds'],
|
|
49
|
-
evidence: ['
|
|
50
|
-
partition: ['out', 'parts'],
|
|
51
|
-
index: ['full', 'binds'],
|
|
47
|
+
evidence: ['json', 'binds'],
|
|
52
48
|
};
|
|
53
49
|
const COMMON = ['root', 'specs'];
|
|
54
|
-
const BOOLEANS = ['fix', 'strict', 'json', 'all-citations', '
|
|
50
|
+
const BOOLEANS = ['fix', 'strict', 'json', 'all-citations', 'check'];
|
|
55
51
|
|
|
56
52
|
/** A usage or environment error: reported on stderr, exit 2. */
|
|
57
53
|
class UsageError extends Error {}
|
|
@@ -91,8 +87,23 @@ function assertScannable(root) {
|
|
|
91
87
|
throw new UsageError(`${root.name}: git lists no files — is ${root.path} a repository?`);
|
|
92
88
|
}
|
|
93
89
|
|
|
94
|
-
/**
|
|
95
|
-
|
|
90
|
+
/**
|
|
91
|
+
* What binds beyond the defaults: the repository's own `binds` (`"spec-steward": { "binds": [...] }` in its root
|
|
92
|
+
* `package.json`), then every `--binds` given.
|
|
93
|
+
* @param {Record<string, any>} opts
|
|
94
|
+
* @param {string} root
|
|
95
|
+
*/
|
|
96
|
+
const bindsOf = (opts, root) => {
|
|
97
|
+
let configured = [];
|
|
98
|
+
try {
|
|
99
|
+
configured = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'))['spec-steward']?.binds ?? [];
|
|
100
|
+
} catch {
|
|
101
|
+
// no package.json, or not JSON: nothing configured
|
|
102
|
+
}
|
|
103
|
+
return /** @type {string[]} */ (
|
|
104
|
+
[...[].concat(configured), ...[].concat(opts.binds ?? [])].filter((b) => typeof b === 'string')
|
|
105
|
+
);
|
|
106
|
+
};
|
|
96
107
|
|
|
97
108
|
/**
|
|
98
109
|
* Every finding for one repository, and the base it was judged against.
|
|
@@ -111,7 +122,7 @@ export function runCheck(root, opts) {
|
|
|
111
122
|
how = resolved.how;
|
|
112
123
|
}
|
|
113
124
|
const corpus = loadCorpus(root.path, root);
|
|
114
|
-
const binds = bindsOf(opts);
|
|
125
|
+
const binds = bindsOf(opts, root.path);
|
|
115
126
|
if (opts.file && (typeof opts.file !== 'string' || !fs.existsSync(path.resolve(opts.file))))
|
|
116
127
|
throw new UsageError(`--file ${opts.file}: no such file`);
|
|
117
128
|
const relative = (/** @type {string} */ f) =>
|
|
@@ -168,34 +179,6 @@ async function main(argv) {
|
|
|
168
179
|
validateFlags(cmd, opts);
|
|
169
180
|
const roots = rootsOf(opts);
|
|
170
181
|
|
|
171
|
-
if (cmd === 'index') {
|
|
172
|
-
const out = roots.map((root) => {
|
|
173
|
-
assertScannable(root);
|
|
174
|
-
const corpus = loadCorpus(root.path, root);
|
|
175
|
-
const citations = scanCitations(root.path, anchorsOf, { binds: bindsOf(opts) });
|
|
176
|
-
const reqs = allRequirements(corpus);
|
|
177
|
-
const count = (/** @type {(c: import('./lib/citations.mjs').Citation) => boolean} */ p) =>
|
|
178
|
-
citations.filter(p).length;
|
|
179
|
-
return {
|
|
180
|
-
name: root.name,
|
|
181
|
-
path: root.path,
|
|
182
|
-
capabilities: corpus.capabilities.length,
|
|
183
|
-
requirements: reqs.length,
|
|
184
|
-
advisory: reqs.filter((r) => r.advisory).length,
|
|
185
|
-
gaps: reqs.reduce((n, r) => n + r.gaps.length, 0),
|
|
186
|
-
scenarios: reqs.reduce((n, r) => n + r.scenarios.length, 0),
|
|
187
|
-
citations: {
|
|
188
|
-
bindings: count((c) => !!c.binding),
|
|
189
|
-
pointers: count((c) => !c.binding),
|
|
190
|
-
dangling: count((c) => !c.resolves),
|
|
191
|
-
},
|
|
192
|
-
corpus: opts.full ? corpus.capabilities.map((c) => ({ ...c, slugs: undefined })) : undefined,
|
|
193
|
-
};
|
|
194
|
-
});
|
|
195
|
-
process.stdout.write(JSON.stringify(out, null, 2) + '\n');
|
|
196
|
-
return 0;
|
|
197
|
-
}
|
|
198
|
-
|
|
199
182
|
if (cmd === 'check') {
|
|
200
183
|
let failed = false;
|
|
201
184
|
const all = [];
|
|
@@ -251,7 +234,7 @@ async function main(argv) {
|
|
|
251
234
|
assertScannable(root);
|
|
252
235
|
const { markdown, totals } = coverageReport(
|
|
253
236
|
loadCorpus(root.path, root),
|
|
254
|
-
scanCitations(root.path, anchorsOf, { binds: bindsOf(opts) }),
|
|
237
|
+
scanCitations(root.path, anchorsOf, { binds: bindsOf(opts, root.path) }),
|
|
255
238
|
);
|
|
256
239
|
if (typeof opts.out === 'string') {
|
|
257
240
|
fs.writeFileSync(path.resolve(opts.out), markdown);
|
|
@@ -262,70 +245,26 @@ async function main(argv) {
|
|
|
262
245
|
return 0;
|
|
263
246
|
}
|
|
264
247
|
|
|
265
|
-
if (cmd === 'evidence'
|
|
248
|
+
if (cmd === 'evidence') {
|
|
249
|
+
if (!opts.json) throw new UsageError('evidence takes --json: the evidence model on stdout');
|
|
266
250
|
const root = oneRoot(roots, cmd);
|
|
267
251
|
assertScannable(root);
|
|
268
252
|
const model = evidenceModel(
|
|
269
253
|
loadCorpus(root.path, root),
|
|
270
|
-
scanCitations(root.path, anchorsOf, { binds: bindsOf(opts) }),
|
|
254
|
+
scanCitations(root.path, anchorsOf, { binds: bindsOf(opts, root.path) }),
|
|
271
255
|
sourceIndex(root.path),
|
|
272
256
|
);
|
|
273
257
|
process.stdout.write(JSON.stringify(model) + '\n');
|
|
274
258
|
return 0;
|
|
275
259
|
}
|
|
276
260
|
|
|
277
|
-
if (cmd === 'evidence') {
|
|
278
|
-
const out = path.resolve(opts.out ?? 'spec-evidence');
|
|
279
|
-
const corpora = roots.map((root) => {
|
|
280
|
-
assertScannable(root);
|
|
281
|
-
return {
|
|
282
|
-
root,
|
|
283
|
-
corpus: loadCorpus(root.path, root),
|
|
284
|
-
citations: scanCitations(root.path, anchorsOf, { binds: bindsOf(opts) }),
|
|
285
|
-
sources: sourceIndex(root.path),
|
|
286
|
-
};
|
|
287
|
-
});
|
|
288
|
-
const everywhere = corpora.flatMap(({ corpus }) =>
|
|
289
|
-
allRequirements(corpus).map((requirement) => ({ corpus, requirement })),
|
|
290
|
-
);
|
|
291
|
-
const bundles = [];
|
|
292
|
-
for (const { root, corpus, citations, sources } of corpora) {
|
|
293
|
-
for (const cap of corpus.capabilities) {
|
|
294
|
-
const file = path.join(out, root.name, `${cap.capability}.md`);
|
|
295
|
-
fs.mkdirSync(path.dirname(file), { recursive: true });
|
|
296
|
-
const md = capabilityEvidence(corpus, cap, citations, sources, everywhere);
|
|
297
|
-
fs.writeFileSync(file, md);
|
|
298
|
-
bundles.push({
|
|
299
|
-
corpus: root.name,
|
|
300
|
-
capability: cap.capability,
|
|
301
|
-
file,
|
|
302
|
-
bytes: Buffer.byteLength(md),
|
|
303
|
-
requirementIds: cap.requirements.map((r) => r.id),
|
|
304
|
-
});
|
|
305
|
-
}
|
|
306
|
-
}
|
|
307
|
-
fs.writeFileSync(path.join(out, 'bundles.json'), JSON.stringify(bundles, null, 2));
|
|
308
|
-
process.stderr.write(`${bundles.length} bundle(s) in ${out}\n`);
|
|
309
|
-
return 0;
|
|
310
|
-
}
|
|
311
|
-
|
|
312
|
-
if (cmd === 'partition') {
|
|
313
|
-
const out = path.resolve(opts.out ?? 'spec-evidence');
|
|
314
|
-
const bundles = JSON.parse(fs.readFileSync(path.join(out, 'bundles.json'), 'utf8'));
|
|
315
|
-
const parts = partition(bundles, Number(opts.parts ?? 16));
|
|
316
|
-
fs.writeFileSync(path.join(out, 'parts.json'), JSON.stringify(parts, null, 2));
|
|
317
|
-
for (const p of parts)
|
|
318
|
-
process.stdout.write(`part ${p.part}: ${Math.round(p.bytes / 1024)} KB — ${p.capabilities.join(', ')}\n`);
|
|
319
|
-
return 0;
|
|
320
|
-
}
|
|
321
|
-
|
|
322
261
|
if (cmd === 'review') return (await import('./lib/review.mjs')).reviewCli(rest, roots);
|
|
323
262
|
if (cmd === 'align') return (await import('./lib/align.mjs')).alignCli(opts, roots);
|
|
324
263
|
if (cmd === 'wire') return (await import('./lib/wire.mjs')).wireCli(opts, roots[0]);
|
|
325
264
|
if (cmd === 'hook') return (await import('./lib/wire.mjs')).hookCli(opts);
|
|
326
265
|
|
|
327
266
|
throw new UsageError(
|
|
328
|
-
'usage: spec-steward check|coverage|evidence|
|
|
267
|
+
'usage: spec-steward check|coverage|evidence|review|align|wire|hook — see the header of steward.mjs',
|
|
329
268
|
);
|
|
330
269
|
}
|
|
331
270
|
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
[
|
|
2
|
+
{
|
|
3
|
+
"key": "tooling-ci",
|
|
4
|
+
"title": "Tooling, CI and the run classes",
|
|
5
|
+
"focus": "Which rules a deterministic check, a lint rule or a type would enforce better than an audit (criterion 3); CI and audit configuration whose cost buys no signal, or whose classification of a run is wrong (23); the same concern held by a CI job and a specification or a skill (21).",
|
|
6
|
+
"files": [
|
|
7
|
+
".gitlab-ci.yml",
|
|
8
|
+
".gitlab/**/*.yml",
|
|
9
|
+
".github/workflows/*.yml",
|
|
10
|
+
".github/workflows/*.yaml",
|
|
11
|
+
"package.json",
|
|
12
|
+
"nx.json",
|
|
13
|
+
"turbo.json",
|
|
14
|
+
"scripts/checks/**"
|
|
15
|
+
]
|
|
16
|
+
},
|
|
17
|
+
{
|
|
18
|
+
"key": "compliance-theatre",
|
|
19
|
+
"title": "Tests citing the corpus",
|
|
20
|
+
"focus": "Tests bound to the specifications that satisfy the wording while failing to protect the intent (5), that are low-value or artificial (4), or whose verification relies on comments or textual matching (17).",
|
|
21
|
+
"from": "bindings"
|
|
22
|
+
},
|
|
23
|
+
{
|
|
24
|
+
"key": "comments-citations",
|
|
25
|
+
"title": "Comments and citations",
|
|
26
|
+
"focus": "Citation machinery whose upkeep exceeds its value (24), citations standing in for evidence (17), comments restating a rule the specification owns (21).",
|
|
27
|
+
"from": "pointers"
|
|
28
|
+
},
|
|
29
|
+
{
|
|
30
|
+
"key": "missing-invariants",
|
|
31
|
+
"title": "Missing invariants",
|
|
32
|
+
"focus": "High-value invariants the architecture clearly relies on that no requirement states (13), and implementation suggesting a specification is wrong or outdated (12).",
|
|
33
|
+
"files": ["README.md", "ARCHITECTURE.md", "docs/**/*.md"]
|
|
34
|
+
},
|
|
35
|
+
{
|
|
36
|
+
"key": "placement",
|
|
37
|
+
"title": "Placement",
|
|
38
|
+
"focus": "Rules that belong in AGENTS.md, a scoped rule, a skill, a command, the OPSX config or a README rather than the specification, and the reverse (2); the same concern held by two mechanisms (21); AGENTS.md hierarchy and scoped-rule scope. Judge by the placement guide, rules/agent.md.",
|
|
39
|
+
"files": [
|
|
40
|
+
"AGENTS.md",
|
|
41
|
+
"**/AGENTS.md",
|
|
42
|
+
".agents/rules/*.md",
|
|
43
|
+
".agents/skills/*/SKILL.md",
|
|
44
|
+
".agents/commands/**/*.md",
|
|
45
|
+
"openspec/config.yaml",
|
|
46
|
+
"openspec/config.yml"
|
|
47
|
+
]
|
|
48
|
+
}
|
|
49
|
+
]
|