@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.
Files changed (111) hide show
  1. package/README.md +38 -3
  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 -146
  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 -42
  30. package/dist/index.js +53 -85
  31. package/dist/lib.d.ts +21 -21
  32. package/dist/lib.js +261 -301
  33. package/dist/lintPrepare.d.ts +20 -17
  34. package/dist/lintPrepare.js +341 -371
  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 +11 -10
  40. package/dist/restrictions.js +18 -22
  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 +2 -0
  45. package/rules/openspec.md +1 -1
  46. package/skills/spec-steward/SKILL.md +3 -11
  47. package/skills/spec-steward/references/audit.md +18 -43
  48. package/skills/spec-steward/references/contract.md +4 -4
  49. package/skills/spec-steward/references/criteria.md +4 -4
  50. package/skills/spec-steward/references/review-format.md +6 -6
  51. package/skills/spec-steward/references/wiring.md +2 -2
  52. package/skills/spec-steward/references/worker.md +67 -0
  53. package/skills/spec-steward/scripts/lib/corpus.mjs +1 -1
  54. package/skills/spec-steward/scripts/lib/evidence.mjs +2 -147
  55. package/skills/spec-steward/scripts/lib/wire.mjs +6 -4
  56. package/skills/spec-steward/scripts/steward.mjs +30 -91
  57. package/skills/spec-steward/sweeps.json +49 -0
  58. package/skills/spec-tools/SKILL.md +46 -0
  59. package/skills/spec-tools/references/contract.md +111 -0
  60. package/skills/spec-tools/references/gitlab.md +122 -0
  61. package/skills/spec-verify/SKILL.md +153 -0
  62. package/spec-tools/dist/audit-DkZZulq6.mjs +130 -0
  63. package/spec-tools/dist/auditChanged-CNGjlake.mjs +1 -0
  64. package/spec-tools/dist/auditChanged-CZCvMgyZ.mjs +618 -0
  65. package/spec-tools/dist/auditReport-xgq4wK2i.mjs +458 -0
  66. package/spec-tools/dist/auditScope-CBuBtfPG.mjs +104 -0
  67. package/spec-tools/dist/changeGates-DdeQKfle.mjs +333 -0
  68. package/spec-tools/dist/changeGates-uy4Ti8rK.mjs +1 -0
  69. package/spec-tools/dist/ci-BUewHJS3.mjs +143 -0
  70. package/spec-tools/dist/ci-CFBzn8Of.mjs +1 -0
  71. package/spec-tools/dist/cli.mjs +93 -0
  72. package/spec-tools/dist/comment-szasMMg2.mjs +57 -0
  73. package/spec-tools/dist/files-Bppsb34B.mjs +1 -0
  74. package/spec-tools/dist/files-QlzY687_.mjs +38 -0
  75. package/spec-tools/dist/html-BMTkpbUN.mjs +1766 -0
  76. package/spec-tools/dist/jsonrepair-Dlm5dEen.mjs +742 -0
  77. package/spec-tools/dist/repo-CjIoUPYl.mjs +16 -0
  78. package/spec-tools/dist/repo-DUcnJw3c.mjs +1 -0
  79. package/spec-tools/dist/run-BElA9du3.mjs +67 -0
  80. package/spec-tools/dist/specDiff-8G56jMYn.mjs +123 -0
  81. package/spec-tools/dist/steward-DeieyOcj.mjs +34 -0
  82. package/spec-tools/dist/stewardAudit-BRMM0lrD.mjs +1 -0
  83. package/spec-tools/dist/stewardAudit-v0vOMfLN.mjs +271 -0
  84. package/spec-tools/dist/tier-Cn0P7juM.mjs +1 -0
  85. package/spec-tools/dist/tier-c3s_mA_I.mjs +65 -0
  86. package/spec-tools/dist/util-wnxhsnWO.mjs +49 -0
  87. package/spec-tools/dist/verdict-BFfN9PO8.mjs +58 -0
  88. package/spec-tools/dist/workers-BcIgckeq.mjs +417 -0
  89. package/spec-tools/dist/workflowEvidence-DyBj8EdG.mjs +1 -0
  90. package/spec-tools/dist/workflowEvidence-oui6ghPI.mjs +78 -0
  91. package/dist/configs/base.d.ts.map +0 -1
  92. package/dist/configs/imports.d.ts.map +0 -1
  93. package/dist/configs/nx.d.ts.map +0 -1
  94. package/dist/configs/prettier.d.ts.map +0 -1
  95. package/dist/configs/promise.d.ts.map +0 -1
  96. package/dist/configs/react.d.ts.map +0 -1
  97. package/dist/configs/storybook.d.ts.map +0 -1
  98. package/dist/configs/tailwind.d.ts.map +0 -1
  99. package/dist/configs/testing.d.ts.map +0 -1
  100. package/dist/configs/turbo.d.ts.map +0 -1
  101. package/dist/configs/typescriptTypeAware.d.ts.map +0 -1
  102. package/dist/configs/unicorn.d.ts.map +0 -1
  103. package/dist/exts.d.ts.map +0 -1
  104. package/dist/index.d.ts.map +0 -1
  105. package/dist/lib.d.ts.map +0 -1
  106. package/dist/lintPrepare.d.ts.map +0 -1
  107. package/dist/lintStaged.d.ts.map +0 -1
  108. package/dist/prettier.d.ts.map +0 -1
  109. package/dist/restrictions.d.ts.map +0 -1
  110. package/dist/yarn.d.cts.map +0 -1
  111. package/skills/spec-steward/workflows/audit.js +0 -539
@@ -0,0 +1,46 @@
1
+ ---
2
+ name: spec-tools
3
+ description: The machinery around both audits — set up and run the `spec-tools` CLI of `@kirill.konshin/lint` in an OpenSpec repository — the change gates and workflow-evidence gate beside spec-steward's corpus gate, the requirement-level specification diff, the `spec-verify` code-conformance audit (run class, scope, workers, merge, verdict), and the glue a CI pipeline runs around a headless AI review (verdict gate, merge-request comment, HTML reports). Use when wiring these into a repository or its pipeline, when a `spec-tools` command fails or its output needs reading, or when deciding which run class an audit is.
4
+ ---
5
+
6
+ # spec-tools
7
+
8
+ One CLI, `spec-tools`, installed with `@kirill.konshin/lint` beside `spec-steward`. What each command does, reads and writes, and its exit codes are [references/contract.md](references/contract.md); a GitLab pipeline is [references/gitlab.md](references/gitlab.md). Three things live elsewhere:
9
+
10
+ - the corpus gate — citations, binding, markers, the scenario ratchet — is the `spec-steward` skill;
11
+ - how an audit worker judges — the five checks, the tiers, the finding kinds, the findings file — is the `spec-verify` skill, which `spec-tools workers` hands every worker;
12
+ - how the repository makes a change is its own `AGENTS.md`.
13
+
14
+ ## Commands
15
+
16
+ | Need | Command |
17
+ | --- | --- |
18
+ | The gate a merge request runs | `spec-tools gates` (spec-steward's check, then the change gates) |
19
+ | Is this branch's change finished? | `spec-tools evidence` |
20
+ | What changed in the specifications, by requirement | `spec-tools diff [<base>]` |
21
+ | Check a spec edit before handing it back | `spec-tools changed`, then `/spec-verify changed` |
22
+ | The full code-conformance audit, locally | `spec-tools audit` (`--here` for uncommitted edits, `--dry` to stop after the scope) |
23
+ | spec-steward's corpus-quality audit, on the same engine | `spec-tools audit --audit spec-steward`, then consolidate `spec-review.md` as the `spec-steward` skill says |
24
+ | One pass of a CI audit | `spec-tools tier`, `scope`, `workers [--complete\|--verify]`, `report [--gate]` |
25
+ | A headless skill review in CI | `spec-tools run <skill> --verdict <report>` |
26
+ | Gate a review's report | `spec-tools verdict <report>` |
27
+ | The merge-request comment and HTML reports | `spec-tools comment <name>=<report.md>...`, `spec-tools html <file.md>...` |
28
+
29
+ In CI: `gates`, `evidence`, `diff`, `tier`, `scope`, `workers`, `report`, `verdict`, `comment`, `html`, for spec-verify. Locally: any of them, plus `audit --audit spec-steward`, which never runs in CI.
30
+
31
+ Run them through the package manager (`yarn spec-tools gates`) or the bin (`node_modules/.bin/spec-tools`); they act on the repository of the current directory.
32
+
33
+ ## Setting a repository up
34
+
35
+ 1. Pin `@kirill.konshin/lint`; `lint-prepare` links the `spec-steward`, `spec-tools` and `spec-verify` skills.
36
+ 2. Declare what binds beyond spec-steward's defaults once, in the root `package.json`: `"spec-steward": { "binds": ["scripts/checks/**", "**/*.Dockerfile", ".gitlab-ci.yml"] }`.
37
+ 3. List the gates in the repository's `AGENTS.md` checks: `openspec validate --strict --all`, `spec-tools gates`, and after a requirement changes `spec-tools changed` with `/spec-verify changed` and `spec-tools diff`.
38
+ 4. Ignore the generated files: `spec-evidence.json`, `spec-coverage.md`, `spec-diff.md`, `audit-scope.json`, `audit-parts/`, `audit-tier.env`, `spec-verify.*`, `mr-comment.md`, `claude.jsonl`, `job-log-*.md` and the rendered `*.html`.
39
+ 5. Wire the pipeline: [GitLab](references/gitlab.md). Other CI providers are not supported yet — `spec-tools` reads GitLab's pipeline variables.
40
+
41
+ ## Reading a failure
42
+
43
+ - `gates` — spec-steward's findings come first (the `spec-steward` skill says what each kind asks), then one line per change gate with what violates it and a hint.
44
+ - `evidence` — an open change carries deltas, or is synced but not archived: archive it before the branch merges.
45
+ - `report --gate` / `verdict` — exit 1 is a confirmed ERROR on a gating run, 77 the same on an advisory run, 3 `INCOMPLETE` (the report names the check that fell short). Summarize `spec-verify.md` as the `spec-verify` skill's _Interactive use_ says.
46
+ - `workers` exit 1 — a worker changed a file outside the audit's outputs; the paths are listed.
@@ -0,0 +1,111 @@
1
+ # spec-tools contract
2
+
3
+ What `spec-tools` does in every repository that runs it. It ships with `@kirill.konshin/lint`, so a repository is held to the version it pins. The tests beside the source (`spec-tools/src/*.test.ts`) prove the cases below. The corpus gate's own contract — citations, binding, markers, size lines, the scenario ratchet — is spec-steward's [`contract.md`](../../spec-steward/references/contract.md); how a pipeline wires the commands is [`gitlab.md`](gitlab.md).
4
+
5
+ ## Bases
6
+
7
+ Every pipeline variable is read in one module (`ci.ts`); GitLab CI's today. The **gate base** is spec-steward's: a merge request's diff base, none in any other pipeline, locally the merge base with `origin/HEAD` (or `origin/main`). The **diff base** of the diff, the focused check and the audit's affected set is a merge request's diff base, else the merge base with its target branch, else a push's tip before it (`HEAD^` on a branch's first push), else `HEAD`.
8
+
9
+ ## Gates — `spec-tools gates`
10
+
11
+ spec-steward's `check --base auto`, then the change gates; exit 1 when either fails, 2 on a usage error. The change gates are statements about the tree, never unit tests:
12
+
13
+ - every archived change carries `.openspec.yaml` and `proposal.md`, and a `specs/` directory it carries holds at least one delta file;
14
+ - no change, open or archived, sets `skip_specs: true` while carrying a delta file;
15
+ - every `MODIFIED` and `REMOVED` heading and every `RENAMED` FROM of an unsynced change the branch touches names a standing requirement. A stale delta in a change the branch does not touch is a warning.
16
+
17
+ Cases:
18
+
19
+ - **WHEN** an archived change has no proposal or no schema marker **THEN** the gate fails, naming it
20
+ - **WHEN** a `skip_specs` change carries a delta **THEN** the gate fails, naming it
21
+ - **WHEN** a touched change's `MODIFIED` heading names a requirement since renamed **THEN** the gate fails, naming the change and the heading
22
+
23
+ ## Workflow evidence — `spec-tools evidence`
24
+
25
+ A change with deltas is finished inside its merge request. The gate fails while an open change carries delta files, or its deltas are already live in `openspec/specs/` but the change is not archived (an ADDED heading present, a REMOVED one gone, a MODIFIED block already equal). `--classify` instead prints which open changes the branch touches against the gate base, and as its last line `deltas`, `skip-specs` or `none`.
26
+
27
+ Cases:
28
+
29
+ - **WHEN** a branch's deltas were synced and the change not archived **THEN** the gate fails
30
+ - **WHEN** a branch carries an open change whose deltas were never synced **THEN** the gate fails
31
+
32
+ ## Diff — `spec-tools diff [<base>]`
33
+
34
+ The specification change against the diff base (or the given ref), by `### Requirement:` heading, each block in full: a heading only the head has is ADDED, only the base has is REMOVED, a block that differs beyond whitespace is MODIFIED, a removed and an added heading with the same body in one file are one RENAMED; a capability whose file moved verbatim is MOVED and counts as no change. Written to `spec-diff.md` and printed; it always exits 0.
35
+
36
+ Cases:
37
+
38
+ - **WHEN** the head adds a heading, drops one and edits a block **THEN** they render as ADDED, REMOVED and MODIFIED
39
+ - **WHEN** a removed and an added heading carry the same body **THEN** they render as one RENAMED; a rename that also edits the body stays REMOVED and ADDED
40
+ - **WHEN** a capability's file moves verbatim **THEN** it is listed as moved and nothing counts as changed
41
+
42
+ ## Changed — `spec-tools changed`
43
+
44
+ The author's pre-hand-back check: every requirement a hunk of the diff overlaps (a deletion at its line included), once, plus the requirements an unsynced touched delta names, what the changed files bind or cite, and their related requirements — each with its bound tests, where its own terms occur in the comment-stripped sources, and its related requirements, quoted in full. Written to `audit-parts/changed.md` from spec-steward's evidence model (`spec-evidence.json`, written first).
45
+
46
+ ## The audit
47
+
48
+ ### Run class — `spec-tools tier`
49
+
50
+ Decided once, printed as dotenv lines (`AUDIT_RUN`, `AUDIT_SCOPE`, `AUDIT_GATING`, `AUDIT_MODEL`, `AUDIT_EFFORT`, `AUDIT_MODEL_VERIFY`, `AUDIT_EFFORT_VERIFY`); every audit job reads the answer.
51
+
52
+ | run | decided by | scope | verifier | gating |
53
+ | -------------- | --------------------------------------- | -------- | --------- | -------- |
54
+ | nightly | `SPEC_AUDIT_NIGHTLY=true` | corpus | expensive | advisory |
55
+ | draft | a draft merge request | affected | cheap | advisory |
56
+ | open-change | a merge request touching an open change | affected | cheap | advisory |
57
+ | merge-request | a merge request touching none | affected | cheap | gating |
58
+ | default-branch | anything else | affected | expensive | gating |
59
+
60
+ Every run reads on the cheap model. `AUDIT_MODEL_CHEAP`, `AUDIT_EFFORT_CHEAP`, `AUDIT_MODEL_EXPENSIVE` and `AUDIT_EFFORT_EXPENSIVE` override the defaults. A merge request whose open changes cannot be classified fails the command rather than reading as one that touches nothing.
61
+
62
+ ### Scope — `spec-tools scope`
63
+
64
+ The corpus on the nightly, or wherever there is no merge-request target; otherwise the affected set — what `changed` names — judged with cross-capability checks against the corpus its evidence quotes. The evidence is assembled mechanically first: per capability, every requirement verbatim, its bound tests at their real lines, where its terms occur, its related requirements; citations are not evidence and are left out. The scope is cut into parts no larger than one cheap reader holds, a capability larger than that cut between its requirements; the cut is a function of the evidence alone. Written to `audit-scope.json` and `audit-parts/`.
65
+
66
+ Cases:
67
+
68
+ - **WHEN** one capability's evidence exceeds one reader **THEN** it is cut between its requirements, each in exactly one piece
69
+ - **WHEN** a request changes a source file that cites no requirement **THEN** the requirements whose own terms that file contains are in its affected set
70
+
71
+ ### Workers — `spec-tools workers [--complete|--verify]`
72
+
73
+ One headless `claude --print` worker per part loads the `spec-verify` skill and writes its own findings file. A parallel job reads only its share: part p goes to job ((p − 1) mod total) + 1. `--complete` judges, as each part's next reader, exactly what the merge listed short; `--verify` puts every standing ERROR to one verifier that confirms it only when the divergence is real and critical. How many run at once follows the container's memory (600 MB a worker), capped by `AUDIT_WORKERS`; a worker past `AUDIT_WORKER_TIMEOUT` (20m) is killed and its part judged by the completion pass. A pass that changed any file outside the audit's outputs exits 1, naming the paths; a missing input exits 2.
74
+
75
+ ### Merge — `spec-tools report [--gate] [--worktree]`
76
+
77
+ Nothing is judged twice. Every ERROR's quotes are looked up at their `file:line` in the audited commit (`HEAD`, or the working tree with `--worktree`); a quote not found, or a verifier's `warn`, makes it WARN with the reason; one the verifier never reached stands on its quotes and says so. Kinds are tiered by the fixed list in the `spec-verify` skill, an unknown kind is INFO, and a finding against an ⚠️ Advisory requirement is at most WARN. A requirement of a part that no reader's judged list names was not judged, whatever coverage the reader claimed. Written to `spec-verify.md` (its first line the verdict) and `spec-verify.json`.
78
+
79
+ The verdict: `PASS` when every requirement in scope was judged, every check ran in full and no ERROR stands; `FAIL` when an ERROR stands; `INCOMPLETE` when none stands but a check was sampled or skipped — the report names it. `--gate` exits 0, 1 or 3.
80
+
81
+ Cases:
82
+
83
+ - **WHEN** an ERROR's quote is not at the `file:line` it names **THEN** the report carries it as WARN, naming the quote
84
+ - **WHEN** a check was sampled and no ERROR stands **THEN** the verdict is `INCOMPLETE` and `--gate` exits 3
85
+ - **WHEN** every check ran in full and no ERROR stands **THEN** the verdict is `PASS`
86
+
87
+ ### Local — `spec-tools audit [--here] [--dry]`
88
+
89
+ The same sequence — scope, reading, merge, completion, merge, verification, gating merge — in a detached worktree of `HEAD`, the outputs copied back; `--here` runs on the working tree, `--dry` stops after the scope.
90
+
91
+ ### spec-steward's corpus-quality audit — `--audit spec-steward`
92
+
93
+ `scope`, `workers`, `report` and `audit` take `--audit spec-steward` to run spec-steward's audit on the same engine, one repository per run, locally — no pipeline runs it. `workers` and `audit` take `--context <file>`: its text — facts established and the owner's earlier decisions — goes into every worker's and verifier's brief, and a finding or verdict that would reverse one says so. Its scope is the same parts plus one unit per sweep of `skills/spec-steward/sweeps.json`, each reading the files its globs match or the evidence's tests or citations; its workers follow `skills/spec-steward/references/worker.md`; its verification puts every finding, not only ERRORs, to a skeptic that keeps, revises or drops it. Its merge drops a finding whose quote is not at its line, folds duplicates (one file, line and theme key), offers three or more findings sharing a theme key as a theme, lists the requirements no worker judged as short, writes `audit-parts/steward/review.json` and renders `spec-review.md` with `spec-steward review render`. It never gates: the review file is the owner's to answer.
94
+
95
+ Cases:
96
+
97
+ - **WHEN** a steward finding's quote is not in the block at its line **THEN** the merge drops it, naming the reason
98
+ - **WHEN** a verifier answers `drop` **THEN** the finding leaves the review and is kept among the dropped with the verifier's reason
99
+ - **WHEN** a part's workers judged one of its requirements nowhere **THEN** it is listed short and the completion pass judges it
100
+
101
+ ## Review glue
102
+
103
+ - `spec-tools run <skill> [--verdict <file>] [--advisory]` — one skill-driven review, headless, on `AUDIT_MODEL`; the stream kept as `claude.jsonl`, the final result as the job log (`job-log-<job>.md`); exits with Claude's status, then gates `--verdict` if given.
104
+ - `spec-tools verdict <file> [--log <file>] [--advisory]` — the report's verdict (a Markdown first line, or `.verdict` of a JSON report) as an exit code: 0 `PASS`, 1 `FAIL`, 77 `FAIL` on an advisory run (`--advisory` or `AUDIT_GATING=advisory`), 3 `INCOMPLETE`, 1 no verdict. A report the skill printed but did not write is recovered from the job log when it carries a verdict line.
105
+ - `spec-tools comment <name>=<report.md>...` — the merge-request comment: one row per review from its verdict line, links into the job's artifacts, the coverage report and the diff beneath; written to `mr-comment.md`.
106
+ - `spec-tools html <file.md>...` — each report as self-contained HTML beside it.
107
+
108
+ Cases:
109
+
110
+ - **WHEN** a review's report says `FAIL` on an advisory run **THEN** `verdict` exits 77
111
+ - **WHEN** the report is missing and the job log carries `PASS (0 errors, 2 warnings)` **THEN** the report is written from the log and `verdict` exits 0
@@ -0,0 +1,122 @@
1
+ # GitLab pipeline
2
+
3
+ The jobs a GitLab repository runs around `spec-steward` and `spec-tools`. Names are suggestions; the order, the rules and the exit codes are the contract ([contract.md](contract.md)).
4
+
5
+ ## Rules
6
+
7
+ - `openspec validate` and `spec-tools gates` are gates over repository state, not unit tests: each runs as a job of its own, never inside a unit suite. An error fails its job; a warning never does.
8
+ - The diff, the coverage report and the merge-request comment are reports: they never fail a pipeline.
9
+ - `workflow-evidence` runs on merge requests to the default branch, and on default-branch pushes, where a red holds the release.
10
+ - The audit jobs accept exit 3 (`INCOMPLETE`) and 77 (an advisory `FAIL`) as allowed failures; a gating `FAIL` (exit 1) blocks.
11
+ - Report jobs depend on the audits with `dependencies:` and `when: always`, never `needs:` — a failed audit is exactly when its report matters.
12
+ - The default-branch pipeline publishes the reports on Pages, a failing one included; a report a run did not produce is omitted.
13
+ - The scheduled nightly sets `SPEC_AUDIT_NIGHTLY=true`, so `spec-tools tier` audits the corpus there.
14
+ - spec-steward's corpus audit (`--audit spec-steward`) has no job: it is heavy, and its review file is the owner's to answer, locally.
15
+ - Declare what binds beyond spec-steward's defaults once, in `package.json`: `"spec-steward": { "binds": ["scripts/checks/**", "**/*.Dockerfile", ".gitlab-ci.yml"] }`.
16
+
17
+ ## Getting the tools into an AI job
18
+
19
+ An image that carries `claude` and Node but no workspace install unpacks the pinned package; the bundle needs no install, and the skills the repository links resolve through it:
20
+
21
+ ```yaml
22
+ .spec-tools-setup: &spec-tools-setup
23
+ - mkdir -p node_modules/@kirill.konshin/lint
24
+ - npm pack "@kirill.konshin/lint@$(node -p "require('./package.json').devDependencies['@kirill.konshin/lint']")" --silent
25
+ - tar -xzf kirill.konshin-lint-*.tgz --strip-components 1 -C node_modules/@kirill.konshin/lint
26
+ ```
27
+
28
+ `spec-tools scope` and `changed` load `typescript`, so they run in a job with the workspace installed.
29
+
30
+ ## Jobs
31
+
32
+ ```yaml
33
+ openspec:
34
+ stage: review
35
+ script: [yarn openspec validate --strict --all]
36
+
37
+ spec-gates:
38
+ stage: review
39
+ script: [yarn spec-tools gates]
40
+
41
+ workflow-evidence:
42
+ stage: review
43
+ rules:
44
+ - if: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $CI_DEFAULT_BRANCH
45
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $SPEC_AUDIT_NIGHTLY != "true"
46
+ script: [yarn spec-tools evidence]
47
+
48
+ spec-diff:
49
+ stage: review
50
+ rules: [if: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $CI_DEFAULT_BRANCH]
51
+ script: [yarn spec-tools diff]
52
+ artifacts: { when: always, paths: [spec-diff.md] }
53
+
54
+ # The run class, the coverage report and the audit's inputs, handed on as artifacts.
55
+ spec-coverage:
56
+ stage: review
57
+ script:
58
+ - yarn spec-tools tier | tee audit-tier.env
59
+ - set -a && . ./audit-tier.env && set +a
60
+ - yarn spec-steward coverage --out spec-coverage.md
61
+ - yarn spec-tools scope
62
+ artifacts:
63
+ when: always
64
+ reports: { dotenv: audit-tier.env }
65
+ paths: [audit-tier.env, spec-coverage.md, audit-scope.json, audit-parts/]
66
+
67
+ # The reading, shared out: each job reads the parts dealt to it.
68
+ spec-verify:read:
69
+ stage: review
70
+ image: <an image with claude and node>
71
+ needs: [spec-coverage]
72
+ parallel: 2 # 8 on the nightly
73
+ allow_failure: true
74
+ script:
75
+ - *spec-tools-setup
76
+ - node_modules/.bin/spec-tools workers
77
+ artifacts: { when: always, paths: [audit-parts/findings/] }
78
+
79
+ # The judge: merge, complete what the reading left short, verify every ERROR, gate.
80
+ spec-verify:
81
+ stage: review
82
+ image: <an image with claude and node>
83
+ needs: [spec-coverage, { job: 'spec-verify:read', optional: true }]
84
+ allow_failure: { exit_codes: [3, 77] }
85
+ script:
86
+ - *spec-tools-setup
87
+ - node_modules/.bin/spec-tools report
88
+ - node_modules/.bin/spec-tools workers --complete
89
+ - node_modules/.bin/spec-tools report
90
+ - node_modules/.bin/spec-tools workers --verify
91
+ - node_modules/.bin/spec-tools report
92
+ - node_modules/.bin/spec-tools verdict spec-verify.json
93
+ artifacts: { when: always, paths: [spec-verify.md, spec-verify.json, audit-parts/findings/] }
94
+
95
+ # Any other skill-driven review: headless, then its verdict.
96
+ some-review:
97
+ stage: review
98
+ image: <an image with claude and node>
99
+ needs: [spec-coverage]
100
+ allow_failure: { exit_codes: [3, 77] }
101
+ script:
102
+ - *spec-tools-setup
103
+ - node_modules/.bin/spec-tools run some-review --verdict some-review.md --advisory
104
+ artifacts: { when: always, paths: [some-review.md, claude.jsonl, 'job-log-*.md'] }
105
+
106
+ render-reviews:
107
+ stage: deploy
108
+ dependencies: [spec-verify, some-review, spec-coverage, spec-diff]
109
+ rules:
110
+ - if: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $CI_DEFAULT_BRANCH
111
+ when: always
112
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
113
+ when: always
114
+ script:
115
+ - yarn spec-tools html spec-verify.md some-review.md spec-coverage.md spec-diff.md
116
+ - yarn spec-tools comment spec-verify=spec-verify.md some-review=some-review.md
117
+ # Posting needs a token that may write notes; CI_JOB_TOKEN cannot.
118
+ - '[ -z "$CI_MERGE_REQUEST_IID" ] || glab api --method POST "projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes" -f "body=$(cat mr-comment.md)"'
119
+ artifacts: { when: always, paths: ['*.md', '*.html'] }
120
+ ```
121
+
122
+ A release job that must wait for the audit `needs:` the judge (`spec-verify`), so a gating `FAIL` on the default branch holds it.
@@ -0,0 +1,153 @@
1
+ ---
2
+ name: spec-verify
3
+ description: Audit whether the code does exactly what the OpenSpec specifications say, as written; its verdict gates CI. Checks what no tool can - cross-capability contradiction, EXACT code conformance, whether a bound test asserts its rule, and gaps nobody recorded. It audits code conformance only; corpus quality — placement, REQUIRED versus ⚠️ ADVISORY, evidence — is the spec-steward skill's audit. Workers only judge; each writes audit-parts/findings/part-<n>-<reader>.json and `spec-tools report` renders spec-verify.md at the repo root. Interactively, run `spec-tools audit`, then summarize spec-verify.md and ask the operator what to do. After changing a capability, `/spec-verify changed` judges what changed; the full audit runs when the operator asks.
4
+ model: claude-haiku-4-5-20251001
5
+ effort: high
6
+ ---
7
+
8
+ # Verify spec adherence
9
+
10
+ The capability specifications under `openspec/specs/` are the single source of truth. The tooling's contract — this audit's scope, partition, merge and verdict — is the `spec-tools` skill's `references/contract.md`; the grading and the finding kinds are below; how a specification is written is the `spec-steward` model (its `references/model.md`); how a change is made is the repository's `AGENTS.md`. A code citation is an optional pointer to a requirement, never evidence that code complies.
11
+
12
+ **Where it runs:** in CI as the gating audit (the reading jobs and the judge job), and locally as `spec-tools audit` and `/spec-verify changed`. spec-steward's corpus audit is the local, owner-requested counterpart; it never runs in CI.
13
+
14
+ **Invariant this skill enforces: CODE 100% follows the SPEC.** A requirement and its code must match exactly; a mismatch is always a finding (the owner decides which side is fixed — never leave them divergent).
15
+
16
+ The audit itself is **read-only**: no worker changes code or specs, and neither do you while it runs; a worker writes its own findings file and nothing else. Fixes come afterwards, only when the operator chooses them — see _Interactive use_.
17
+
18
+ There are three ways in. A worker — its brief names a part and a findings file — follows _The worker contract_. `/spec-verify changed` is _Focused mode_. `/spec-verify` from an operator is _Interactive use_.
19
+
20
+ ## What this skill does NOT check
21
+
22
+ These run deterministically in CI. Do not re-derive them, and do not report what they own — a finding they cover is noise, not signal:
23
+
24
+ - `openspec validate` and `spec-tools gates` — the corpus gates: OpenSpec's structure check, then spec-steward's check and the change gates. What a citation is, how a test binds to a scenario, the markers, the size lines and the scenario ratchet are the `spec-steward` contract.
25
+ - `spec-tools scope` — **this run's scope, its partition, and the evidence each part is judged from.** Nothing here is searched for; it is read.
26
+ - `spec-tools report` — **the merge.** It looks every ERROR's quotes up at their `file:line` in the audited commit, tiers by the kinds below, takes the weakest part's coverage, computes the verdict and renders `spec-verify.md`. No reader judges twice.
27
+ - `spec-steward coverage` — the coverage report: which requirements and scenarios a test binds, the ⚠️ Advisory requirements and the recorded known gaps. The audit does not read it.
28
+ - Corpus quality — whether a rule sits in the right place, whether it is REQUIRED or ⚠️ Advisory, whether its evidence is the right kind — is the `spec-steward` skill's audit.
29
+
30
+ **Why the split matters.** This skill is an LLM audit: one reader over the whole corpus samples, and two such runs over the same commit can reach different verdicts. Everything mechanically decidable was moved out of it and into code — including finding the evidence. What remains needs judgment — read in full, one worker per part, and graded so that only what you can demonstrate stops a pipeline.
31
+
32
+ ## Scope
33
+
34
+ In CI, `spec-tools tier` chooses each pass's scope, model and effort — the run classes are the `spec-tools` contract's — and this frontmatter applies to an in-chat run only. The scope is partitioned before any worker starts, in `audit-scope.json`: its `parts` list the parts, one worker each, with the evidence files each part judges. Ignore build output (any `dist/`, `node_modules`, and whatever else the repository's `AGENTS.md` names as generated).
35
+
36
+ ## Focused mode — `/spec-verify changed`
37
+
38
+ Invoked with the argument `changed`, this skill is an author's pre-hand-back check, not the gate. `spec-tools changed` has already written `audit-parts/changed.md` — you do not run it —: the requirements the working tree changed, each with the tests bound to it, where its own terms occur, and its related requirements quoted in full. You are the one reader: Read that file, run checks 2, 3 and 4 over exactly those requirements against what is quoted, and print the findings in the conversation — no workers, no findings file, no report. Say plainly when a changed sentence contradicts a related requirement, when it duplicates one, and when the code does not do what the new text says.
39
+
40
+ ## The material — read, never produced
41
+
42
+ Two inputs, both written by `spec-tools scope` and, in CI, handed to the audit jobs as artifacts:
43
+
44
+ - `audit-scope.json` — the scope and its `parts`: for each, its number, the `files` its worker reads and the `requirementIds` it judges.
45
+ - `audit-parts/<capability>.md`, one per capability in scope — **the evidence.** Each carries every requirement verbatim with its id and `file:line`, and under each: **Bound tests** — the tests bound to the requirement or to one of its scenarios, quoted with the files' own line numbers (the enclosing test, or a window marked as such); **Where its terms occur** — the lines of the sources, comments stripped, where the requirement's own terms occur, or the note that it names none; and the related requirements elsewhere that share its terms, each with its statement.
46
+
47
+ You NEVER produce or regenerate these — no `spec-tools scope`, no `spec-steward coverage`, no `spec-tools report`: a worker's shell is `git` and nothing else. If a file is absent, say so in the coverage, grade every check that depends on it as not run, and — locally — tell the user to run `spec-tools scope` first.
48
+
49
+ **Read everything with Read / Glob / Grep — do not shell out.** A worker runs under `claude --print`, which cannot be prompted for permission: a command outside the job's `--allowedTools` stalls the run and no report is written. An evidence file longer than one Read returns is read in full with `offset`/`limit` — never sampled.
50
+
51
+ A **requirement** is one `### Requirement:` heading and everything under it. Address it as `<capability>#<slug>` (e.g. `billing/refunds#requirement-a-refund-is-applied-once`) — the slug is stable, so never invent positional ids.
52
+
53
+ ## The worker contract
54
+
55
+ One reader cannot hold the whole corpus and every symbol it governs; a run that tries samples, and a sample cannot support a `PASS`. So the evidence is assembled mechanically before the audit starts, and `spec-tools workers` starts one headless worker per part. The passes run in order — the reading, shared out among parallel reading jobs, the completion pass over what the reading left short, and the verification pass over every ERROR still standing. Each later brief names exactly what it judges, and the tool runs every pass, never a worker.
56
+
57
+ A worker's brief gives its part number, its reader number, the findings file it alone writes, its part's evidence files and its `requirementIds`. It judges all five checks over its evidence in one pass: the specification against itself (checks 2 and 3, from the requirement blocks and related lists the evidence carries) and the code against the specification (1, 4 and 5) — every requirement, every bound test and every listed related pair. It opens a source only where an excerpt is marked as a window, where a term hit must be confirmed, where the behaviour continues outside the excerpt, or where a related requirement's statement line is not enough to decide. Its tools are Skill, Read, Glob, Grep, Write, Edit (to repair its own findings file) and the git commands; anything else is denied and only costs a turn. It writes its findings file and returns one line: the path and its counts per tier.
58
+
59
+ ## The checks
60
+
61
+ Checks 2–5 are spec-steward's audit criteria 10, 9, 11 and 5 (its `references/criteria.md`), worded identically: the same principle, judged here against the code and the specification as written, where spec-steward judges whether the rule itself should change.
62
+
63
+ 1. **Gap honesty** — for each requirement no test binds, decide whether the behaviour exists at all, starting from where its terms occur; the absence of a citation is never itself a reason to suspect a gap. A requirement describing behaviour nothing implements, with no `**⚠️ Known gap (<tracker>):**` line recorded, is an undeclared gap. One that names no term is judged first for whether it describes code behaviour at all — a process or documentation rule has nothing to implement and is not a gap. Kind: `undeclared-gap`. Do not report which requirements no test binds: that is in `spec-coverage.md`, mechanically; only the judgment — gap or not — is yours.
64
+ 2. **Contradictory rules.** (spec-steward criterion 10) — no requirement contradicts another, in the same capability or a different one. `openspec validate` compares a delta against the spec it replaces; nothing compares capability A with capability B. Each requirement's evidence lists the related requirements sharing its terms (e.g. an ordering two capabilities both state, who owns a piece of state, which layer may hold a credential); judge every listed pair, and note in prose any overlap the terms could not pair. Report each conflicting pair. Kind: `conflict`.
65
+ 3. **A rule redundant with, or substantially overlapping, another.** (spec-steward criterion 9) — two requirements asserting the same rule; one should own it and the other cross-reference. Judged over the same related lists. Kind: `spec-dup`.
66
+ 4. **A rule that no longer matches the implementation or architecture.** (spec-steward criterion 11) — judged from the code side, EXACT: the code does exactly what the requirement says, no more and no less. Compare the quoted code with the requirement word-for-word: missing or extra behaviour, different ordering or condition, a looser type than required. When a requirement mandates a concrete class or pattern, the code MUST use it; when it states only a requirement, any implementation satisfying it passes. Open the source only where the excerpt is a window or the behaviour continues outside it. A `code-mismatch` quotes code that does something DIFFERENT from the requirement; code that conforms is not a defect whether or not anything cites it, and a pointer naming another requirement is not a finding. Kind: `code-mismatch`.
67
+ 5. **A rule whose tests satisfy the wording while failing to protect the intent.** (spec-steward criterion 5) — for each test bound to a requirement or to one of its scenarios, read the quoted test and confirm it asserts that rule. Do not trust the name: a citation, comment, description or prompt text is never evidence that code complies. A structural requirement may be proven by a schema assertion or a compile-time `Equal<>` pin. Kind: `untested` — a test bound to a scenario that does not assert it. A requirement no test binds is already in `spec-coverage.md`, mechanically; do not spend a row restating it.
68
+
69
+ **Every path you name must exist.** Every `file:line` in the evidence files exists by construction. Any other code or test path a finding names MUST exist — confirm each with Read or Glob before writing the row. Bare basenames are forbidden: two files can share one. A row whose path does not resolve is invalid: correct the path, or drop the row.
70
+
71
+ ## Grading — this decides whether the build fails
72
+
73
+ Every finding is in exactly one of three tiers:
74
+
75
+ - **ERROR** — a defect you demonstrated: you opened both sides and quote each at `file:line`. It fails the build once its verifier confirms it real and critical.
76
+ - **WARN** — a defect of the same class, suspected but not demonstrated: suspected from a sample, or not read on both sides. Published, never a failure.
77
+ - **INFO** — inventory and state recorded for a reader. Never a failure.
78
+
79
+ The kinds are fixed — never invent another. ERROR-class, graded ERROR when demonstrated and WARN when only suspected: `code-mismatch` (the code does not do what a requirement says), `conflict` (two requirements contradict), `undeclared-gap` (a requirement describes behaviour that does not exist, with no Known gap recorded). INFO-class, however certain: `spec-dup` (one rule asserted by two requirements), `untested` (a test cites a scenario but does not assert it). The merge records any other kind as INFO. A finding against a requirement marked `**⚠️ Advisory:**` is at most WARN.
80
+
81
+ The one line worth repeating here, because it is the whole contract: **you may write ERROR only if you opened both sides and can quote each at `file:line`.** Anything you inferred, sampled, or could not read both halves of is WARN. Marking a suspicion ERROR costs the team a red pipeline on a guess; marking a real defect WARN costs one triage cycle. The asymmetry is deliberate. And a worker's ERROR is not yet the gate's: the verification pass puts each to one more reader over that finding alone, which confirms it only when the divergence is real and critical and lowers it to WARN with its reason otherwise — so a worker grades what it demonstrated, and never softens a real divergence because it seems minor; the verifier decides that.
82
+
83
+ **State your coverage honestly.** Each worker records, for each of the five checks, whether it ran it in full, sampled, or not at all — and what it skipped. _In full_ means every requirement, bound test, term-hit list or related pair of the part was judged — and every requirement id appears in your `judged` list, which is what the merge believes rather than the word; judging from a complete quoted excerpt and the term hits without opening the source IS in full — that is what the evidence is for. An excerpt marked as a window or an outline is NOT complete: Read the file at those lines before grading, every time — the evidence tells you which files, so this is a handful of Reads, never a search — and only then is the check in full. A check with nothing to judge in your part is `full`, not `not-run`. _Sampled_ means some items were not judged at all. Two things are NOT sampling and must not be reported as such: judging a requirement that names no term from its text and its term hits (that is the whole of check 1 for it), and judging the related pairs the evidence lists without opening the other capability's specification (the listed pairs ARE checks 2 and 3's scope; open the other side only when a statement line is not enough to decide). The merge takes the weakest part: a check sampled or not run anywhere makes the verdict `INCOMPLETE`, never `PASS`.
84
+
85
+ An uncertain conclusion is a WARN finding, not a reason to mark a check sampled. Before writing, resolve every window by reading its named source and complete every requirement in the assigned list. Use `sampled` only when an assigned source is genuinely unavailable after those reads; never use it because code lives elsewhere, a requirement has no bound test, or the evidence makes a conclusion difficult. And never use it for what a test fails to prove: once you have read a bound test and can say what it does not assert, check 5 ran in full for that requirement and what you found is a finding of kind `untested`. A `sampled` note names what you did not read — a file, a window — never what a test did not cover; a note that restates a finding turns a complete part into a spurious `INCOMPLETE`.
86
+
87
+ ## The findings file — what a worker writes
88
+
89
+ Each reader writes its own findings file with the **Write tool** — `audit-parts/findings/part-<n>-<reader>.json` — overwrite, and nothing else. The file is what `spec-tools report` reads; findings that exist only in a worker's reply are lost. Its shape is fixed:
90
+
91
+ ```json
92
+ {
93
+ "part": 1,
94
+ "reader": 1,
95
+ "capabilities": ["<capability>", "<another>"],
96
+ "findings": [
97
+ {
98
+ "kind": "code-mismatch",
99
+ "tier": "ERROR",
100
+ "where": "<capability>#requirement-<slug> / <package>/src/<file>.ts:6",
101
+ "quotes": [
102
+ {
103
+ "file": "openspec/specs/<capability>/spec.md",
104
+ "line": 101,
105
+ "text": "SHALL mark the in-flight assistant message as errored and render the failure text inside its bubble"
106
+ },
107
+ {
108
+ "file": "<package>/src/<file>.ts",
109
+ "line": 6,
110
+ "text": "if (event.type === 'RUN_ERROR') return;"
111
+ }
112
+ ],
113
+ "detail": "The handler returns on RUN_ERROR, so the in-flight assistant message is never marked errored and no failure text renders in its bubble."
114
+ }
115
+ ],
116
+ "coverage": {
117
+ "1": "full",
118
+ "2": "full",
119
+ "3": "full",
120
+ "4": "sampled: <capability>#requirement-<slug> — the excerpt was a window and the source was not opened",
121
+ "5": "full"
122
+ },
123
+ "judged": ["<capability>#requirement-<slug>", "<capability>#requirement-<other-slug>"],
124
+ "notes": [
125
+ "<capability>#requirement-<slug> and <capability>#requirement-<other-slug> overlap in prose on one rule; no shared term paired them"
126
+ ]
127
+ }
128
+ ```
129
+
130
+ - `kind` is one of the kinds above, `tier` is `ERROR`, `WARN` or `INFO`, `where` names the requirement id(s) and the `file:line`, `detail` says what diverges and which rule it breaks in one or two sentences — the developer's report shows its first sentence alone.
131
+ - Keep the JSON plain: double quotes, no trailing commas, no comments; a `detail` or `note` is one string with no line breaks. A file that does not parse is a part that ran nothing.
132
+ - Write the file once and stop. Do not validate it with a shell — no `python3 -c`, `node -e`, `wc`: Bash is denied to workers, every attempt is a wasted turn, and the merge reads the file back.
133
+ - `quotes` carry the proof. An ERROR needs at least two — both sides, each from a specification or a source file, never from `audit-parts/` — each a **verbatim fragment of one line** (or of consecutive lines) copied from the evidence excerpt without its line-number prefix, at most ~200 characters. `spec-tools report` looks each up at its `file:line`; a quote that is not there turns the finding into WARN, so copy, never paraphrase. WARN and INFO findings carry no `quotes`: their `where` and `detail` are what the report shows.
134
+ - `coverage` has one string per check — `"1"` to `"5"`: `"full"`, or `"sampled: <what was skipped>"` / `"not-run: <why>"`. Strings, not objects — every bracket is a chance to break the file. The note after `sampled:` names the source you could not read; a judgment about a test — it covers the happy path only, it asserts less than the rule — is a finding of kind `untested`, and a check whose only shortfall is such a judgment is `"full"`.
135
+ - `judged` is the judged list: every requirement id in your evidence files, added as you finish judging it for checks 1–5, whether or not it yielded a finding. The merge compares this list with the part's requirements: an id missing from it was not judged, the check is sampled for the whole audit and the verdict is `INCOMPLETE`, whatever `coverage` says. So walk the requirements one by one and write each id down when it is done; a `"full"` with a short list is a contradiction the merge resolves against you. Before you write the file, set the list against your part's `requirementIds` in `audit-scope.json`: an id you judged but forgot goes in now; an id you did not judge stays out and is reported as such — never added to look complete.
136
+ - `notes` are prose-only overlaps the term lists could not pair — suspicions for the reader, published as such.
137
+
138
+ ## Interactive use — `/spec-verify`
139
+
140
+ An operator's `/spec-verify` runs the audit CI runs: `spec-tools audit` (`--here` to judge the working tree's uncommitted edits instead of `HEAD`), then summarizes `spec-verify.md` in the conversation, **one line per finding, most severe first**:
141
+
142
+ `⟨ERROR|WARN|INFO⟩ <capability>#requirement-<slug> <file>:<line> — <kind> — <one-sentence verdict, actionable>`
143
+
144
+ No quotes, no paragraphs: the proof lives in the findings files and the report. End with the counts per tier. Nothing found → say so and stop. With no operator — the AskUserQuestion tool is not among your tools, as under `claude --print` — the summary is the end of your job.
145
+
146
+ Otherwise **ask once**, with the AskUserQuestion tool — _rerun_ / _fix the errors_ / _fix errors and warnings_ / _go one by one_ / _stop_ — and **do nothing until answered**.
147
+
148
+ - **Rerun** — run `spec-tools audit` again and summarize again. Two runs over one tree differ only in what the workers noticed, so a rerun is for a run you distrust, not a way to make a finding disappear.
149
+ - **Fix the errors / fix errors and warnings** — you, never a worker, apply the whole batch at once. Per finding, propose the side — code or specification — with a one-line reason, show the list, and edit nothing until the operator has confirmed or changed each side. A specification fix is a direct edit of the standing specification unless the user asked for the delta flow. Before touching a requirement, read the requirements it names and that name it — they are in its evidence file — so the fix does not contradict a sibling; after the batch, run `spec-tools changed` and judge `audit-parts/changed.md` as _Focused mode_ describes, then the checks the repository's `AGENTS.md` lists. Report the diff of everything changed and stop; the operator decides whether to run the audit again.
150
+ - **Go one by one** — per finding, in the summary's order: _fix in code_ / _fix in spec_ / _skip_ / _instructions_. Show the exact edit before making it; apply the confirmed ones as one batch and finish as above.
151
+ - **Stop** — leave the findings files and say so.
152
+
153
+ `spec-verify.md` is rendered by `spec-tools report`, whose first line is the verdict CI reads (`PASS|FAIL|INCOMPLETE (<n> errors, <m> warnings)`); you never write it.
@@ -0,0 +1,130 @@
1
+ import { a as PARTS_DIR, r as EVIDENCE_FILE, t as AUDIT_FILES } from "./files-QlzY687_.mjs";
2
+ import { n as root, t as git } from "./repo-CjIoUPYl.mjs";
3
+ import { spawnSync } from "node:child_process";
4
+ import * as fs from "node:fs";
5
+ import * as os from "node:os";
6
+ import * as path from "node:path";
7
+ //#region spec-tools/src/audit.ts
8
+ /**
9
+ * `spec-tools audit`: the CI sequence — the evidence model, scope, then the passes and merges in the order `workers.ts`
10
+ * describes — run by default from a DETACHED worktree of HEAD, so what is judged is exactly the commit CI judges: an
11
+ * uncommitted edit, or a stale `audit-parts/findings/` in the working tree, cannot leak into the run, and every ERROR's
12
+ * quotes are re-proved against HEAD. The install is the working tree's (`node_modules` is linked in), and the run's
13
+ * outputs — evidence model, scope, evidence, findings, the merged report — come back to the working tree.
14
+ * `--here` runs on the working tree instead, uncommitted edits included, and re-proves quotes against it.
15
+ * `--dry` exercises the tree and runs no worker.
16
+ */
17
+ /** What a run produces and brings back to the working tree. */
18
+ const outputs = (audit) => [.../* @__PURE__ */ new Set([
19
+ EVIDENCE_FILE,
20
+ PARTS_DIR,
21
+ AUDIT_FILES[audit].scope,
22
+ AUDIT_FILES[audit].report,
23
+ AUDIT_FILES[audit].data
24
+ ])];
25
+ /** This CLI as it was started — the build or the source under a loader alike — run in `cwd`; its exit code. */
26
+ const self = (args, cwd) => spawnSync(process.execPath, [
27
+ ...process.execArgv,
28
+ process.argv[1],
29
+ ...args
30
+ ], {
31
+ cwd,
32
+ stdio: "inherit"
33
+ }).status ?? 1;
34
+ /**
35
+ * The sequence in one tree. The intermediate merges only render; spec-verify's last one gates (exit 0 / 1 / 3), and
36
+ * spec-steward's renders the review file for the owner.
37
+ */
38
+ function sequence(tree, here, dry, audit, context) {
39
+ const named = audit === "spec-verify" ? [] : ["--audit", audit];
40
+ const worker = context ? [
41
+ ...named,
42
+ "--context",
43
+ context
44
+ ] : named;
45
+ const report = [...here ? ["report", "--worktree"] : ["report"], ...named];
46
+ const steps = dry ? [["scope", ...named]] : [
47
+ ["scope", ...named],
48
+ ["workers", ...worker],
49
+ report,
50
+ [
51
+ "workers",
52
+ "--complete",
53
+ ...worker
54
+ ],
55
+ report,
56
+ [
57
+ "workers",
58
+ "--verify",
59
+ ...worker
60
+ ],
61
+ audit === "spec-verify" ? [...report, "--gate"] : report
62
+ ];
63
+ for (const step of steps) {
64
+ const code = self(step, tree);
65
+ if (code !== 0) return code;
66
+ }
67
+ if (dry) console.log("spec-tools audit: dry run — scope written, no worker started");
68
+ return 0;
69
+ }
70
+ function audit(argv, audit = "spec-verify") {
71
+ const valued = ["--audit", "--context"];
72
+ const unknown = argv.filter((a, i) => a !== "--here" && a !== "--dry" && !valued.includes(a) && !valued.includes(argv[i - 1] ?? ""));
73
+ if (unknown.length) {
74
+ console.error(`spec-tools audit: unknown argument ${unknown[0]} (accepted: --here, --dry, --audit <name>, --context <file>)`);
75
+ return 2;
76
+ }
77
+ const given = argv.includes("--context") ? argv[argv.indexOf("--context") + 1] : void 0;
78
+ const context = given ? path.resolve(given) : void 0;
79
+ const here = argv.includes("--here");
80
+ const dry = argv.includes("--dry");
81
+ const top = root();
82
+ const head = git([
83
+ "rev-parse",
84
+ "--short",
85
+ "HEAD"
86
+ ]).trim();
87
+ if (here) {
88
+ console.log(`spec-tools audit: working tree (${head}, uncommitted edits included)`);
89
+ return sequence(top, true, dry, audit, context);
90
+ }
91
+ const tree = path.join(fs.mkdtempSync(path.join(os.tmpdir(), `${path.basename(top)}-audit-`)), "tree");
92
+ git([
93
+ "worktree",
94
+ "add",
95
+ "--detach",
96
+ "--quiet",
97
+ tree,
98
+ "HEAD"
99
+ ]);
100
+ try {
101
+ fs.symlinkSync(path.join(top, "node_modules"), path.join(tree, "node_modules"));
102
+ console.log(`spec-tools audit: detached tree of ${head} at ${tree}`);
103
+ const code = sequence(tree, false, dry, audit, context);
104
+ if (!dry) for (const out of outputs(audit)) {
105
+ if (!fs.existsSync(path.join(tree, out))) continue;
106
+ fs.rmSync(path.join(top, out), {
107
+ recursive: true,
108
+ force: true
109
+ });
110
+ fs.cpSync(path.join(tree, out), path.join(top, out), { recursive: true });
111
+ }
112
+ return code;
113
+ } finally {
114
+ try {
115
+ git([
116
+ "worktree",
117
+ "remove",
118
+ "--force",
119
+ tree
120
+ ]);
121
+ } catch {
122
+ fs.rmSync(tree, {
123
+ recursive: true,
124
+ force: true
125
+ });
126
+ }
127
+ }
128
+ }
129
+ //#endregion
130
+ export { audit };
@@ -0,0 +1 @@
1
+ export { o as main } from "./auditChanged-CZCvMgyZ.mjs";