@kirill.konshin/lint 0.5.5 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (91) 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 +262 -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 +22 -8
  44. package/rules/agent.md +2 -0
  45. package/rules/openspec.md +1 -1
  46. package/skills/spec-steward/SKILL.md +4 -12
  47. package/skills/spec-steward/references/audit.md +18 -43
  48. package/skills/spec-steward/references/contract.md +9 -9
  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/sweeps.json +49 -0
  54. package/skills/spec-tools/SKILL.md +48 -0
  55. package/skills/spec-tools/references/contract.md +111 -0
  56. package/skills/spec-tools/references/gitlab.md +120 -0
  57. package/skills/spec-tools/scripts/cli.js +8129 -0
  58. package/skills/spec-verify/SKILL.md +153 -0
  59. package/dist/configs/base.d.ts.map +0 -1
  60. package/dist/configs/imports.d.ts.map +0 -1
  61. package/dist/configs/nx.d.ts.map +0 -1
  62. package/dist/configs/prettier.d.ts.map +0 -1
  63. package/dist/configs/promise.d.ts.map +0 -1
  64. package/dist/configs/react.d.ts.map +0 -1
  65. package/dist/configs/storybook.d.ts.map +0 -1
  66. package/dist/configs/tailwind.d.ts.map +0 -1
  67. package/dist/configs/testing.d.ts.map +0 -1
  68. package/dist/configs/turbo.d.ts.map +0 -1
  69. package/dist/configs/typescriptTypeAware.d.ts.map +0 -1
  70. package/dist/configs/unicorn.d.ts.map +0 -1
  71. package/dist/exts.d.ts.map +0 -1
  72. package/dist/index.d.ts.map +0 -1
  73. package/dist/lib.d.ts.map +0 -1
  74. package/dist/lintPrepare.d.ts.map +0 -1
  75. package/dist/lintStaged.d.ts.map +0 -1
  76. package/dist/prettier.d.ts.map +0 -1
  77. package/dist/restrictions.d.ts.map +0 -1
  78. package/dist/yarn.d.cts.map +0 -1
  79. package/skills/spec-steward/scripts/lib/align.mjs +0 -127
  80. package/skills/spec-steward/scripts/lib/checks.mjs +0 -589
  81. package/skills/spec-steward/scripts/lib/citations.mjs +0 -156
  82. package/skills/spec-steward/scripts/lib/corpus.mjs +0 -256
  83. package/skills/spec-steward/scripts/lib/coverage.mjs +0 -123
  84. package/skills/spec-steward/scripts/lib/evidence.mjs +0 -334
  85. package/skills/spec-steward/scripts/lib/git.mjs +0 -138
  86. package/skills/spec-steward/scripts/lib/review.mjs +0 -347
  87. package/skills/spec-steward/scripts/lib/scan.mjs +0 -364
  88. package/skills/spec-steward/scripts/lib/util.mjs +0 -161
  89. package/skills/spec-steward/scripts/lib/wire.mjs +0 -331
  90. package/skills/spec-steward/scripts/steward.mjs +0 -350
  91. 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 `--binds <glob>` the repository passes (a check script, a Dockerfile, a CI configuration), anywhere | yes |
39
+ | In a file matching a `binds` glob the repository declares — `"spec-steward": { "binds": [...] }` in its root `package.json`, or `--binds <glob>` — (a check script, a Dockerfile, a CI configuration), anywhere | yes |
40
40
  | Anywhere else in a test file: its header, a fixture, a helper | no — it binds nothing and fails nothing |
41
41
  | Code, configuration, YAML, a Dockerfile or a document that no `--binds` glob matches | no — it is a pointer |
42
42
 
@@ -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 (`EVAA-34696`), a tickets-page id, or an open `openspec/changes/<name>` folder. Steward checks only that it is present: any non-empty text inside the parentheses counts and is not validated, so a placeholder counts until it is replaced. In the statement, the line records the gap and exempts nothing, unless it names scenarios of its requirement by title after `exempts`, each in quotes (`exempts scenario 'A'`, `exempts scenarios 'A' and 'B'`; double quotes, curly quotes, `_…_` and `*…*` are read too). Exactly the named scenarios are then exempt from the scenario ratchet. Coverage lists every gap with its tracker. |
59
+ | `**⚠️ Known gap (<tracker>):** <what is missing>` | Behaviour the requirement describes is knowingly absent or incomplete, or a REQUIRED rule lacks the evidence that would catch its failure. `<tracker>` is required text: a ticket key (`PROJ-123`), a tickets-page id, or an open `openspec/changes/<name>` folder. Steward checks only that it is present: any non-empty text inside the parentheses counts and is not validated, so a placeholder counts until it is replaced. In the statement, the line records the gap and exempts nothing, unless it names scenarios of its requirement by title after `exempts`, each in quotes (`exempts scenario 'A'`, `exempts scenarios 'A' and 'B'`; double quotes, curly quotes, `_…_` and `*…*` are read too). Exactly the named scenarios are then exempt from the scenario ratchet. Coverage lists every gap with its tracker. |
60
60
 
61
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
 
@@ -131,12 +131,12 @@ An explicit `--base <ref>` compares with the merge base of `<ref>` and `HEAD`. W
131
131
 
132
132
  | Command | Purpose | Output |
133
133
  | --- | --- | --- |
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
- | `spec-steward coverage [--out <file>] [--binds <glob>]…` | The [coverage report](#coverage-report) | Markdown, to the file or to stdout |
136
- | `spec-steward evidence --json [--binds <glob>]…` | The audit's [evidence model](#evidence-json) | JSON on stdout |
137
- | `spec-steward evidence --out <dir>`, `partition`, `index`, `review`, `align`, `wire`, `hook` | Audit bundles and partitions, the corpus index, review files, cross-repository drift, wiring, the edit hook | As each command documents |
134
+ | `spec-tools 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
+ | `spec-tools steward coverage [--out <file>] [--binds <glob>]…` | The [coverage report](#coverage-report) | Markdown, to the file or to stdout |
136
+ | `spec-tools 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-tools steward review`, `align`, `wire`, `hook` | Review files, cross-repository drift, wiring, the edit hook | As each command documents |
138
138
 
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.
139
+ `spec-tools steward` runs through the package's one `bin`, `spec-tools`. 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
 
141
141
  ### Findings
142
142
 
@@ -155,7 +155,7 @@ Exit 2 on an empty listing keeps a broken checkout from passing a scan that read
155
155
 
156
156
  ## Coverage report
157
157
 
158
- `spec-steward coverage` writes a Markdown report that is MDX-safe: `<`, `>`, `{`, `}` and `|` are escaped. It gates nothing: it exits 0, or 2 on an environment error. Statuses come from [bindings](#binding) and [markers](#markers) only. A pointer never changes a status.
158
+ `spec-tools steward coverage` writes a Markdown report that is MDX-safe: `<`, `>`, `{`, `}` and `|` are escaped. It gates nothing: it exits 0, or 2 on an environment error. Statuses come from [bindings](#binding) and [markers](#markers) only. A pointer never changes a status.
159
159
 
160
160
  - **Headline.** Requirements and capabilities; Advisory requirements; Known gaps; REQUIRED requirements no test binds; REQUIRED scenarios no test binds; retired markers.
161
161
  - **Per capability.** One table: `| Requirement / Scenario | Spec | Bound by | Pointers | Status |`.
@@ -166,7 +166,7 @@ Exit 2 on an empty listing keeps a broken checkout from passing a scan that read
166
166
 
167
167
  ## Evidence JSON
168
168
 
169
- `spec-steward evidence --json` writes the evidence an audit reads, one entry per requirement:
169
+ `spec-tools steward evidence --json` writes the evidence an audit reads, one entry per requirement:
170
170
 
171
171
  ```
172
172
  { version: 1, root, requirements: [{ id, capability, file, line, end, block, class: 'required'|'advisory',
@@ -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 · CXAD apps/mastra · 1, 6
10
+ ### R-007 · SPEC-ADVISORY · SHOP checkout · 1, 6
11
11
 
12
- - Rule: “The A2A endpoint and Agent Card are the ONLY surface a consumer may target”
13
- - Location: `CXAD openspec/specs/apps/mastra/spec.md:20`
14
- - What’s wrong: <the concrete problem>. Evidence: `apps/mastra/src/main.ts:59`.
12
+ - Rule: “The public HTTP API is the ONLY surface a client may target”
13
+ - Location: `SHOP openspec/specs/checkout/spec.md:20`
14
+ - What’s wrong: <the concrete problem>. Evidence: `src/checkout/server.ts:59`.
15
15
  - Proposed: Reclassify → OpenSpec ⚠️ ADVISORY — <exactly what to do>
16
16
  - My response: ⬜
17
17
  ```
@@ -29,8 +29,8 @@ When several rules share one problem and one solution, they become a single them
29
29
  ### R-012 · DELETE · Theme: Scenarios that restate their requirement · 19, 20
30
30
 
31
31
  - Rule: “Scenarios that restate their requirement” — 3 rules:
32
- - “WHEN the module is evaluated THEN no instance exists until the factory runs” — `CXAD openspec/specs/apps/mastra/spec.md:31`
33
- - “…” — `APC openspec/specs/client/spec.md:88` — member-specific note
32
+ - “WHEN the module is evaluated THEN no instance exists until the factory runs” — `SHOP openspec/specs/checkout/spec.md:31`
33
+ - “…” — `BILLING openspec/specs/invoices/spec.md:88` — member-specific note
34
34
  - Location: each member above
35
35
  - What’s wrong: …
36
36
  - Proposed: …
@@ -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 repository's own audit. | You, beside the specification-driven convention; `wire --fix` prints the line. |
10
+ | Routing line in `AGENTS.md` | Tells every agent, Codex included, where the guard lives, and that corpus-quality audits use this skill while code conformance is the `spec-verify` audit. | You, beside the specification-driven convention; `wire --fix` prints the line. |
11
11
  | OPSX operation guidance in `openspec/config.yaml` | One narrow line each for `apply` and `archive`: run the repository's spec gate (AGENTS.md → Checks); a `weakened` finding stops the flow. | `steward wire --fix`, when the file has OpenSpec's standard shape |
12
12
 
13
13
  These five points keep to the placement rules:
@@ -16,4 +16,4 @@ These five points keep to the placement rules:
16
16
  - The OPSX `context` stays untouched: it already carries `AGENTS.md`.
17
17
  - The hook is a no-op where the skill is not installed, so teammates without it are not blocked.
18
18
 
19
- **The gate.** A repository's spec gate (`spec:gates` and its CI job, listed in `AGENTS.md` → Checks) runs `steward check --base auto`, passing the repository's `--binds` globs, and then whatever change gates the repository keeps. Error findings fail it; warnings and prompts never do ([contract](contract.md#kinds-and-severities)). Steward is the one spec engine, so it never runs as a second job beside an existing gate, and the repository keeps no copy of a check steward implements. Whether a repository puts the gate in CI is its owner's decision.
19
+ **The gate.** A repository's spec gate (`spec-tools gates` and its CI job, listed in `AGENTS.md` → Checks) runs `steward check --base auto` with the repository's binds — `"spec-steward": { "binds": [...] }` in its root `package.json` — and then the change gates. Error findings fail it; warnings and prompts never do ([contract](contract.md#kinds-and-severities)). Steward is the one spec engine, so it never runs as a second job beside an existing gate, and the repository keeps no copy of a check steward implements. Whether a repository puts the gate in CI is its owner's decision.
@@ -0,0 +1,67 @@
1
+ # Audit worker
2
+
3
+ What one worker of the corpus-quality audit does. `spec-tools workers --audit spec-steward` starts one per unit of the scope and names, in its brief, the unit, the files to read and the findings file to write. The audit's procedure around the workers is [audit.md](audit.md).
4
+
5
+ ## The standard
6
+
7
+ Read these first, in full — they are what you judge by: [model.md](model.md), [criteria.md](criteria.md), and the placement guide, `rules/agent.md` of this package.
8
+
9
+ - Specification quality first. An ordinary implementation bug is out of scope unless it reveals the rule is unrealistic, unclear, outdated, ambiguous, or contradicted by what the tests actually assert. Whether code conforms is the `spec-verify` audit's.
10
+ - Comments, descriptions, prompt text and citations are never evidence that code complies, and never a violation by themselves. Judge executable behaviour and structure.
11
+ - For every rule you would keep REQUIRED, ask what meaningful failure its verification catches. Never propose a test merely because a rule lacks one, and never a test of incidental text or structure.
12
+ - Internal component and API contracts are legitimate specification. The line is contract versus implementation or process, not product versus engineering.
13
+ - Do not decide intent silently: when the meaning is ambiguous, describe the readings, propose options and set `needsHumanIntent`.
14
+ - No style preferences: every finding states a concrete problem.
15
+ - A proposal that reverses an earlier owner decision says so, in `reversesPastDecision`.
16
+ - Quote the original text verbatim, from the line you name; open the file to confirm before writing it.
17
+
18
+ The audit is read-only: you write your findings file and nothing else. Your tools are Read, Glob, Grep, Write and the read-only git commands; anything else is denied and only costs a turn.
19
+
20
+ ## Your unit
21
+
22
+ - **A part** is a set of capabilities, each as its evidence file under `audit-parts/` quotes it: every requirement verbatim with its line, the tests bound to it, where its terms occur, and its related requirements elsewhere. Read the evidence files and the specifications they name in full, then trace into code and tests wherever a verdict depends on them. Every requirement of the part is either in a finding (on it or one of its scenarios) or in `sound`, and every one you judged is in `judged`.
23
+ - **A sweep** looks across the corpus from one angle — its focus names the criteria. Read the files the brief lists; `judged` and `sound` may stay empty.
24
+
25
+ ## The findings file
26
+
27
+ One finding per rule and problem. A rule may be a requirement, a scenario, a sentence, or — outside the specifications — a section or line of `AGENTS.md`, a skill, a configuration, a script or a CI job. Write the file once with the Write tool, plain JSON:
28
+
29
+ ```json
30
+ {
31
+ "part": 3,
32
+ "reader": 1,
33
+ "findings": [
34
+ {
35
+ "file": "openspec/specs/billing/refunds/spec.md",
36
+ "line": 12,
37
+ "quote": "The service SHALL apply a refund at most once per request id",
38
+ "level": "requirement",
39
+ "ruleName": "Refunds are idempotent",
40
+ "criteria": [6, 7],
41
+ "layer": "SPEC-ADVISORY",
42
+ "whatsWrong": "<the concrete problem, one or two sentences>",
43
+ "proposed": "Reclassify → OpenSpec ⚠️ ADVISORY — <exactly what to do>",
44
+ "evidence": ["src/refunds.ts:40"],
45
+ "crossRefs": [],
46
+ "themeKey": "unverifiable-absolute",
47
+ "needsHumanIntent": false,
48
+ "reversesPastDecision": "",
49
+ "confidence": "high"
50
+ }
51
+ ],
52
+ "sound": ["billing/refunds#requirement-a-refund-names-its-order"],
53
+ "judged": [
54
+ "billing/refunds#requirement-refunds-are-idempotent",
55
+ "billing/refunds#requirement-a-refund-names-its-order"
56
+ ],
57
+ "notes": []
58
+ }
59
+ ```
60
+
61
+ - `file` is repository-relative; `line` is where the quoted text is; `quote` is verbatim, at most 300 characters, `…` eliding. The merge looks the quote up at its line and drops a finding whose quote is not there.
62
+ - `criteria` are numbers from [criteria.md](criteria.md). `proposed` starts with the target notation (`Keep →`, `Reclassify →`, `Move →`, `Replace →`, `Merge →`, `Rewrite →`, `Delete →`) and says exactly what to do: a rewrite gives the new text, a move names the target file.
63
+ - `layer` is the owning layer you propose: `SPEC-REQUIRED`, `SPEC-ADVISORY`, `DESIGN`, `AGENTS`, `RULE`, `SKILL`, `COMMAND`, `OPSX-CONFIG`, `README`, `TOOLING`, `TEST`, `CI`, `MERGE`, `REWRITE` or `DELETE`.
64
+ - `themeKey` names the underlying problem — one of `restating-scenario`, `single-scenario-padding`, `bdd-verbosity`, `impl-detail-in-spec`, `coding-convention-in-spec`, `process-rule-in-spec`, `agent-steering-as-spec`, `tooling-should-enforce`, `textual-test`, `comment-as-evidence`, `citation-upkeep`, `unverifiable-absolute`, `vague-obligation`, `advisory-not-required`, `duplicate-rule`, `cross-repo-drift`, `contradiction`, `stale-rule`, `scope-unclear`, `repo-wide-reasoning`, `placement-duplication`, `agents-md-bloat`, `ci-cost`, `missing-invariant`, `gap-marker` — or a new kebab-case key only when none fits. The merge groups findings that share one into a theme.
65
+ - `sound` lists the requirements you judged correct, well placed and adequately evidenced, as `capability#requirement-slug`; `judged` lists every requirement you judged, finding or not. A requirement of your part missing from `judged` is judged again by a completion worker.
66
+
67
+ Be aggressive about questionable specification design and conservative about deciding intent. Then return one line: the path and your count of findings.
@@ -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
+ ]
@@ -0,0 +1,48 @@
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
+ spec-steward's commands run as `spec-tools steward <command>` — the `spec-steward` skill documents them.
32
+
33
+ Run them through the package manager (`yarn spec-tools gates`), the bin (`node_modules/.bin/spec-tools`), or the file itself, `node <this skill's folder>/scripts/cli.js`, which needs no install; they act on the repository of the current directory.
34
+
35
+ ## Setting a repository up
36
+
37
+ 1. Pin `@kirill.konshin/lint`; `lint-prepare` links the `spec-steward`, `spec-tools` and `spec-verify` skills.
38
+ 2. Declare what binds beyond spec-steward's defaults once, in the root `package.json`: `"spec-steward": { "binds": ["scripts/checks/**", "**/*.Dockerfile", ".gitlab-ci.yml"] }`.
39
+ 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`.
40
+ 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`.
41
+ 5. Wire the pipeline: [GitLab](references/gitlab.md). Other CI providers are not supported yet — `spec-tools` reads GitLab's pipeline variables.
42
+
43
+ ## Reading a failure
44
+
45
+ - `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.
46
+ - `evidence` — an open change carries deltas, or is synced but not archived: archive it before the branch merges.
47
+ - `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.
48
+ - `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-tools 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,120 @@
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 AI job's image carries `claude` and Node but no workspace install. The job that computes the scope runs with the workspace installed and hands the package's `skills/` on as an artifact: the self-contained CLI, `skills/spec-tools/scripts/cli.js`, and the skills its workers read. The AI jobs `needs:` that job and call the file with `node`; they run no setup.
20
+
21
+ `spec-tools scope` and `changed` load `typescript`, so they run in a job with the workspace installed.
22
+
23
+ ## Jobs
24
+
25
+ ```yaml
26
+ openspec:
27
+ stage: review
28
+ script: [yarn openspec validate --strict --all]
29
+
30
+ spec-gates:
31
+ stage: review
32
+ script: [yarn spec-tools gates]
33
+
34
+ workflow-evidence:
35
+ stage: review
36
+ rules:
37
+ - if: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $CI_DEFAULT_BRANCH
38
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $SPEC_AUDIT_NIGHTLY != "true"
39
+ script: [yarn spec-tools evidence]
40
+
41
+ spec-diff:
42
+ stage: review
43
+ rules: [if: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $CI_DEFAULT_BRANCH]
44
+ script: [yarn spec-tools diff]
45
+ artifacts: { when: always, paths: [spec-diff.md] }
46
+
47
+ # The run class, the coverage report and the audit's inputs, handed on as artifacts — with the package's skills/,
48
+ # which hold the CLI the AI jobs run.
49
+ spec-coverage:
50
+ stage: review
51
+ script:
52
+ - yarn spec-tools tier | tee audit-tier.env
53
+ - set -a && . ./audit-tier.env && set +a
54
+ - yarn spec-tools steward coverage --out spec-coverage.md
55
+ - yarn spec-tools scope
56
+ artifacts:
57
+ when: always
58
+ reports: { dotenv: audit-tier.env }
59
+ paths:
60
+ [
61
+ audit-tier.env,
62
+ spec-coverage.md,
63
+ audit-scope.json,
64
+ audit-parts/,
65
+ node_modules/@kirill.konshin/lint/skills/,
66
+ ]
67
+
68
+ # The reading, shared out: each job reads the parts dealt to it.
69
+ spec-verify:read:
70
+ stage: review
71
+ image: <an image with claude and node>
72
+ needs: [spec-coverage]
73
+ parallel: 2 # 8 on the nightly
74
+ allow_failure: true
75
+ script:
76
+ - node node_modules/@kirill.konshin/lint/skills/spec-tools/scripts/cli.js 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
+ - node node_modules/@kirill.konshin/lint/skills/spec-tools/scripts/cli.js report
87
+ - node node_modules/@kirill.konshin/lint/skills/spec-tools/scripts/cli.js workers --complete
88
+ - node node_modules/@kirill.konshin/lint/skills/spec-tools/scripts/cli.js report
89
+ - node node_modules/@kirill.konshin/lint/skills/spec-tools/scripts/cli.js workers --verify
90
+ - node node_modules/@kirill.konshin/lint/skills/spec-tools/scripts/cli.js report
91
+ - node node_modules/@kirill.konshin/lint/skills/spec-tools/scripts/cli.js verdict spec-verify.json
92
+ artifacts: { when: always, paths: [spec-verify.md, spec-verify.json, audit-parts/findings/] }
93
+
94
+ # Any other skill-driven review: headless, then its verdict.
95
+ some-review:
96
+ stage: review
97
+ image: <an image with claude and node>
98
+ needs: [spec-coverage]
99
+ allow_failure: { exit_codes: [3, 77] }
100
+ script:
101
+ - node node_modules/@kirill.konshin/lint/skills/spec-tools/scripts/cli.js run some-review --verdict some-review.md --advisory
102
+ artifacts: { when: always, paths: [some-review.md, claude.jsonl, 'job-log-*.md'] }
103
+
104
+ render-reviews:
105
+ stage: deploy
106
+ dependencies: [spec-verify, some-review, spec-coverage, spec-diff]
107
+ rules:
108
+ - if: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $CI_DEFAULT_BRANCH
109
+ when: always
110
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
111
+ when: always
112
+ script:
113
+ - yarn spec-tools html spec-verify.md some-review.md spec-coverage.md spec-diff.md
114
+ - yarn spec-tools comment spec-verify=spec-verify.md some-review=some-review.md
115
+ # Posting needs a token that may write notes; CI_JOB_TOKEN cannot.
116
+ - '[ -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)"'
117
+ artifacts: { when: always, paths: ['*.md', '*.html'] }
118
+ ```
119
+
120
+ A release job that must wait for the audit `needs:` the judge (`spec-verify`), so a gating `FAIL` on the default branch holds it.