@kirill.konshin/lint 0.6.0 → 0.6.2

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 (51) hide show
  1. package/README.md +8 -8
  2. package/dist/lib.js +2 -1
  3. package/package.json +4 -6
  4. package/skills/spec-steward/SKILL.md +2 -2
  5. package/skills/spec-steward/references/contract.md +7 -7
  6. package/skills/spec-tools/SKILL.md +3 -1
  7. package/skills/spec-tools/references/contract.md +5 -5
  8. package/skills/spec-tools/references/gitlab.md +26 -35
  9. package/skills/spec-tools/scripts/cli.js +8155 -0
  10. package/skills/spec-verify/SKILL.md +6 -6
  11. package/skills/spec-steward/scripts/lib/align.mjs +0 -127
  12. package/skills/spec-steward/scripts/lib/checks.mjs +0 -589
  13. package/skills/spec-steward/scripts/lib/citations.mjs +0 -156
  14. package/skills/spec-steward/scripts/lib/corpus.mjs +0 -256
  15. package/skills/spec-steward/scripts/lib/coverage.mjs +0 -123
  16. package/skills/spec-steward/scripts/lib/evidence.mjs +0 -189
  17. package/skills/spec-steward/scripts/lib/git.mjs +0 -138
  18. package/skills/spec-steward/scripts/lib/review.mjs +0 -347
  19. package/skills/spec-steward/scripts/lib/scan.mjs +0 -364
  20. package/skills/spec-steward/scripts/lib/util.mjs +0 -161
  21. package/skills/spec-steward/scripts/lib/wire.mjs +0 -333
  22. package/skills/spec-steward/scripts/steward.mjs +0 -289
  23. package/spec-tools/dist/audit-DkZZulq6.mjs +0 -130
  24. package/spec-tools/dist/auditChanged-CNGjlake.mjs +0 -1
  25. package/spec-tools/dist/auditChanged-CZCvMgyZ.mjs +0 -618
  26. package/spec-tools/dist/auditReport-xgq4wK2i.mjs +0 -458
  27. package/spec-tools/dist/auditScope-CBuBtfPG.mjs +0 -104
  28. package/spec-tools/dist/changeGates-DdeQKfle.mjs +0 -333
  29. package/spec-tools/dist/changeGates-uy4Ti8rK.mjs +0 -1
  30. package/spec-tools/dist/ci-BUewHJS3.mjs +0 -143
  31. package/spec-tools/dist/ci-CFBzn8Of.mjs +0 -1
  32. package/spec-tools/dist/cli.mjs +0 -93
  33. package/spec-tools/dist/comment-szasMMg2.mjs +0 -57
  34. package/spec-tools/dist/files-Bppsb34B.mjs +0 -1
  35. package/spec-tools/dist/files-QlzY687_.mjs +0 -38
  36. package/spec-tools/dist/html-BMTkpbUN.mjs +0 -1766
  37. package/spec-tools/dist/jsonrepair-Dlm5dEen.mjs +0 -742
  38. package/spec-tools/dist/repo-CjIoUPYl.mjs +0 -16
  39. package/spec-tools/dist/repo-DUcnJw3c.mjs +0 -1
  40. package/spec-tools/dist/run-BElA9du3.mjs +0 -67
  41. package/spec-tools/dist/specDiff-8G56jMYn.mjs +0 -123
  42. package/spec-tools/dist/steward-DeieyOcj.mjs +0 -34
  43. package/spec-tools/dist/stewardAudit-BRMM0lrD.mjs +0 -1
  44. package/spec-tools/dist/stewardAudit-v0vOMfLN.mjs +0 -271
  45. package/spec-tools/dist/tier-Cn0P7juM.mjs +0 -1
  46. package/spec-tools/dist/tier-c3s_mA_I.mjs +0 -65
  47. package/spec-tools/dist/util-wnxhsnWO.mjs +0 -49
  48. package/spec-tools/dist/verdict-BFfN9PO8.mjs +0 -58
  49. package/spec-tools/dist/workers-BcIgckeq.mjs +0 -417
  50. package/spec-tools/dist/workflowEvidence-DyBj8EdG.mjs +0 -1
  51. package/spec-tools/dist/workflowEvidence-oui6ghPI.mjs +0 -78
package/README.md CHANGED
@@ -342,9 +342,9 @@ In the project root, `lint-prepare`:
342
342
 
343
343
  ### OpenSpec
344
344
 
345
- For a repository specified with [OpenSpec](https://github.com/Fission-AI/OpenSpec) the package ships two bins, three skills and a command:
345
+ For a repository specified with [OpenSpec](https://github.com/Fission-AI/OpenSpec) the package ships one bin, `spec-tools` — a single self-contained file, `skills/spec-tools/scripts/cli.js` — three skills and a command:
346
346
 
347
- - `spec-steward` and its skill — the corpus gate (citations, binding, the scenario ratchet), the edit hook, corpus-quality audits and review rounds.
347
+ - `spec-tools steward` and the `spec-steward` skill — the corpus gate (citations, binding, the scenario ratchet), the edit hook, corpus-quality audits and review rounds.
348
348
  - `spec-tools` and its skill — the change gates, the workflow-evidence gate, the requirement-level specification diff, the code-conformance audit, and the glue a CI pipeline runs around a headless AI review (verdict gate, merge-request comment, HTML reports).
349
349
  - `spec-verify` — the skill every audit worker loads.
350
350
  - `/spec-author` — the command that writes or edits a specification in place, the default direct-edit path.
@@ -354,7 +354,7 @@ Which to reach for:
354
354
  | Question | Tool | Outcome |
355
355
  | --- | --- | --- |
356
356
  | How do I write or change a rule? | `/spec-author` | The specification edited in place, with the code and tests that prove it |
357
- | Do citations resolve, is every new scenario bound, did a rule weaken? | `spec-steward check` (the gate, the edit hook) | Fails the merge request on an error |
357
+ | Do citations resolve, is every new scenario bound, did a rule weaken? | `spec-tools steward check` (the gate, the edit hook) | Fails the merge request on an error |
358
358
  | Are these the right rules — placement, REQUIRED or ⚠️ ADVISORY, wording, evidence, duplicates, drift across repositories? | the `spec-steward` skill (audit on the `spec-tools` engine, review rounds, align) | A review file of proposals; the owner decides, steward applies; never a build failure |
359
359
  | Does the code do exactly what the rules say, and do the bound tests assert them? | the `spec-verify` skill, run by `spec-tools` | Graded, quote-proved findings; PASS / FAIL / INCOMPLETE gates CI |
360
360
  | Is the change finished, what did it change, how does CI run the audit? | `spec-tools` (gates, evidence, diff, tier, workers, verdict, comment, html) | Gates and reports for the pipeline |
@@ -363,13 +363,13 @@ Where each runs:
363
363
 
364
364
  | What | In CI | Locally |
365
365
  | --- | --- | --- |
366
- | `spec-steward check` | `spec-tools gates`, every merge request: an error fails it | the edit hook on every edit Claude makes, and `spec-tools gates` before handing back |
367
- | `spec-steward coverage`, `spec-steward evidence --json` | the coverage report, and the evidence `spec-tools scope` builds the spec-verify audit from | on demand |
366
+ | `spec-tools steward check` | `spec-tools gates`, every merge request: an error fails it | the edit hook on every edit Claude makes, and `spec-tools gates` before handing back |
367
+ | `spec-tools steward coverage`, `spec-tools steward evidence --json` | the coverage report, and the evidence `spec-tools scope` builds the spec-verify audit from | on demand |
368
368
  | spec-steward's corpus audit, review rounds, `align` | never — it is heavy and its outcome is the owner's | on the owner's request: `spec-tools audit --audit spec-steward [--context <decisions file>]`, then the review rounds, where the accepted answers are applied |
369
- | `spec-verify` | the reading jobs and the judge job: its verdict gates merge requests and the release | `spec-tools audit`, and `/spec-verify changed` before handing back a spec edit |
369
+ | `spec-verify` | one audit job — the reading, then the judging: its verdict gates merge requests and the release | `spec-tools audit`, and `/spec-verify changed` before handing back a spec edit |
370
370
  | `spec-tools gates`, `evidence`, `diff` | their own jobs | before handing back |
371
371
 
372
- Specifications change only by hand, or when the steward skill applies the owner's accepted review answers; `spec-steward check --fix` makes the only mechanical repairs. No audit edits code or specifications.
372
+ Specifications change only by hand, or when the steward skill applies the owner's accepted review answers; `spec-tools steward check --fix` makes the only mechanical repairs. No audit edits code or specifications.
373
373
 
374
374
  The audits share their principles: `spec-verify`'s checks 2–5 are spec-steward's criteria 10, 9, 11 and 5, worded identically — steward asks whether the rule should change, `spec-verify` whether the code or the rule has diverged.
375
375
 
@@ -437,7 +437,7 @@ Everything else — `prettier`, `listStaged`, extension lists (`tsExts`, …), `
437
437
 
438
438
  ### Build
439
439
 
440
- `tsdown` builds two things (`tsdown.config.ts`): the library — ESM and declarations from `src/*.ts`, one file per module, plus the CommonJS Yarn entry from `src/yarn.cts` — into `dist`, and the `spec-tools` CLI into one self-contained bundle in `spec-tools/dist`. `yarn typecheck` (`tsc --noEmit`) checks types; the build does not. Consumers load `dist`, and this monorepo builds lint first in its root `postinstall` before running `lint-prepare`.
440
+ `tsdown` builds two things (`tsdown.config.ts`): the library — ESM and declarations from `src/*.ts`, one file per module, plus the CommonJS Yarn entry from `src/yarn.cts` — into `dist`, and the `spec-tools` CLI — spec-steward included — into one self-contained file, `skills/spec-tools/scripts/cli.js`, which the skills and CI jobs name. `yarn typecheck` (`tsc --noEmit`) checks types; the build does not. Consumers load `dist`, and this monorepo builds lint first in its root `postinstall` before running `lint-prepare`.
441
441
 
442
442
  ### Eslint
443
443
 
package/dist/lib.js CHANGED
@@ -14,7 +14,8 @@ const GLOBAL_IGNORES = [
14
14
  "**/.cache",
15
15
  "**/.nx",
16
16
  "**/.turbo",
17
- "**/.yarn"
17
+ "**/.yarn",
18
+ "**/skills/spec-tools/scripts/cli.js"
18
19
  ];
19
20
  const LINT_DEBUG = Boolean(process.env.LINT_DEBUG);
20
21
  /**
package/package.json CHANGED
@@ -1,13 +1,12 @@
1
1
  {
2
2
  "name": "@kirill.konshin/lint",
3
3
  "description": "ESLint + Prettier + lint-staged config and AI agent rules/skills for monorepos",
4
- "version": "0.6.0",
4
+ "version": "0.6.2",
5
5
  "type": "module",
6
6
  "skipGenerate": true,
7
7
  "bin": {
8
8
  "lint-prepare": "./dist/lintPrepare.js",
9
- "spec-steward": "./skills/spec-steward/scripts/steward.mjs",
10
- "spec-tools": "./spec-tools/dist/cli.mjs"
9
+ "spec-tools": "./skills/spec-tools/scripts/cli.js"
11
10
  },
12
11
  "main": "./dist/index.js",
13
12
  "module": "./dist/index.js",
@@ -34,7 +33,7 @@
34
33
  },
35
34
  "scripts": {
36
35
  "----- BUILD -----": "",
37
- "clean": "rm -rf dist spec-tools/dist",
36
+ "clean": "rm -rf dist skills/spec-tools/scripts",
38
37
  "build": "tsdown",
39
38
  "start": "tsdown --watch",
40
39
  "----- TEST -----": "",
@@ -46,7 +45,6 @@
46
45
  "commands",
47
46
  "rules",
48
47
  "skills",
49
- "spec-tools/dist",
50
48
  "!**/*.test.*"
51
49
  ],
52
50
  "dependencies": {
@@ -142,7 +140,7 @@
142
140
  "build": {
143
141
  "outputs": [
144
142
  "{projectRoot}/dist",
145
- "{projectRoot}/spec-tools/dist"
143
+ "{projectRoot}/skills/spec-tools/scripts"
146
144
  ]
147
145
  }
148
146
  }
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: spec-steward
3
- description: Guard, audit and repair an OpenSpec specification corpus — whether these are the right rules, in the right place, with the right evidence; it proposes spec changes and never fails a build. Use when auditing specs for corpus quality (the whole corpus, a change, or one capability), producing or processing a spec review file (review rounds where the owner answers items with ⬜ / ✅ / ❌), aligning rules shared by several repositories, wiring the spec guard (edit hook, AGENTS.md routing, OPSX config) into a repository, or when the repository's spec gate, `spec-steward check` or the edit hook reports a finding. Deterministic scripts do the mechanical work; the skill supplies the procedure. It does not audit code conformance; the `spec-verify` skill does. Writing a rule is the `/spec-author` command.
3
+ description: Guard, audit and repair an OpenSpec specification corpus — whether these are the right rules, in the right place, with the right evidence; it proposes spec changes and never fails a build. Use when auditing specs for corpus quality (the whole corpus, a change, or one capability), producing or processing a spec review file (review rounds where the owner answers items with ⬜ / ✅ / ❌), aligning rules shared by several repositories, wiring the spec guard (edit hook, AGENTS.md routing, OPSX config) into a repository, or when the repository's spec gate, `spec-tools steward check` or the edit hook reports a finding. Deterministic scripts do the mechanical work; the skill supplies the procedure. It does not audit code conformance; the `spec-verify` skill does. Writing a rule is the `/spec-author` command.
4
4
  ---
5
5
 
6
6
  # Spec steward
@@ -12,7 +12,7 @@ Procedures for an OpenSpec corpus. Four things live elsewhere and are not repeat
12
12
  - the specification model (REQUIRED versus ⚠️ ADVISORY, Known gaps, the evidence ladder, what is not evidence, how requirements and scenarios are written) — [references/model.md](references/model.md)
13
13
  - what the gate checks and emits (citations, binding, markers, size lines, the scenario ratchet, base resolution, exit codes, the coverage report, the evidence JSON) — [references/contract.md](references/contract.md)
14
14
 
15
- `steward` below means the `spec-steward` bin that `@kirill.konshin/lint` installs (`node_modules/.bin/spec-steward`); where the bin is absent, `node <this skill's folder>/scripts/steward.mjs`. Inside a Yarn script the bin resolves only once the installed release carries it (a yalc link adds `node_modules/.bin/spec-steward`, which Yarn's script PATH does not include); until then call it by path. It has no dependencies and needs Node ≥ 20 and git. Every command takes `--root NAME=path` (repeatable, for several repositories) and `--specs <dir>` (default `openspec/specs`).
15
+ `steward` below means `spec-tools steward`, through the `spec-tools` bin `@kirill.konshin/lint` installs; where the bin is absent, `node <the spec-tools skill's folder>/scripts/cli.js steward`. The file is self-contained and needs Node ≥ 20 and git. Every command takes `--root NAME=path` (repeatable, for several repositories) and `--specs <dir>` (default `openspec/specs`).
16
16
 
17
17
  ## Pick the procedure
18
18
 
@@ -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 audits' [evidence model](#evidence-json), which `spec-tools scope` assembles each audit's evidence files from | JSON on stdout |
137
- | `spec-steward review`, `align`, `wire`, `hook` | Review files, cross-repository drift, wiring, the edit hook | As each command documents |
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',
@@ -28,7 +28,9 @@ One CLI, `spec-tools`, installed with `@kirill.konshin/lint` beside `spec-stewar
28
28
 
29
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
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.
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.
32
34
 
33
35
  ## Setting a repository up
34
36
 
@@ -47,7 +47,7 @@ The author's pre-hand-back check: every requirement a hunk of the diff overlaps
47
47
 
48
48
  ### Run class — `spec-tools tier`
49
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.
50
+ Decided once, printed as dotenv lines (`AUDIT_RUN`, `AUDIT_SCOPE`, `AUDIT_GATING`, `AUDIT_MODEL`, `AUDIT_EFFORT`, `AUDIT_MODEL_VERIFY`, `AUDIT_EFFORT_VERIFY`, `AUDIT_SLOTS`); every audit job reads the answer.
51
51
 
52
52
  | run | decided by | scope | verifier | gating |
53
53
  | -------------- | --------------------------------------- | -------- | --------- | -------- |
@@ -57,11 +57,11 @@ Decided once, printed as dotenv lines (`AUDIT_RUN`, `AUDIT_SCOPE`, `AUDIT_GATING
57
57
  | merge-request | a merge request touching none | affected | cheap | gating |
58
58
  | default-branch | anything else | affected | expensive | gating |
59
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.
60
+ Every run reads on the cheap model. `AUDIT_MODEL_CHEAP`, `AUDIT_EFFORT_CHEAP`, `AUDIT_MODEL_EXPENSIVE` and `AUDIT_EFFORT_EXPENSIVE` override the defaults. `AUDIT_SLOTS` is how many workers a reading job runs at once: as many as `AUDIT_JOB_MEMORY` (default 2 GiB) holds at 600 MB a worker, never more than `AUDIT_WORKERS` (default 2). A merge request whose open changes cannot be classified fails the command rather than reading as one that touches nothing.
61
61
 
62
62
  ### Scope — `spec-tools scope`
63
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/`.
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 `AUDIT_JOBS` × `AUDIT_SLOTS` parts — one round of workers across the pipeline's reading jobs (`AUDIT_JOBS`, its own count, default 1) — balanced by load, none larger than one cheap reader holds, a capability larger than that cut between its requirements; only a scope larger than a round holds opens more parts. The cut is a function of the evidence and those two numbers. Written to `audit-scope.json` and `audit-parts/`.
65
65
 
66
66
  Cases:
67
67
 
@@ -70,7 +70,7 @@ Cases:
70
70
 
71
71
  ### Workers — `spec-tools workers [--complete|--verify]`
72
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.
73
+ One headless `claude --print` worker per part loads the `spec-verify` skill and writes its own findings file. In a parallel job (`CI_NODE_INDEX` of `CI_NODE_TOTAL`) it 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), never more than `AUDIT_WORKERS` (default 2), and each pass logs the job's memory peak against its limit; 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
74
 
75
75
  ### Merge — `spec-tools report [--gate] [--worktree]`
76
76
 
@@ -90,7 +90,7 @@ The same sequence — scope, reading, merge, completion, merge, verification, ga
90
90
 
91
91
  ### spec-steward's corpus-quality audit — `--audit spec-steward`
92
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.
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
94
 
95
95
  Cases:
96
96
 
@@ -11,19 +11,13 @@ The jobs a GitLab repository runs around `spec-steward` and `spec-tools`. Names
11
11
  - Report jobs depend on the audits with `dependencies:` and `when: always`, never `needs:` — a failed audit is exactly when its report matters.
12
12
  - The default-branch pipeline publishes the reports on Pages, a failing one included; a report a run did not produce is omitted.
13
13
  - The scheduled nightly sets `SPEC_AUDIT_NIGHTLY=true`, so `spec-tools tier` audits the corpus there.
14
+ - Reading jobs × workers is the pipeline's choice: `AUDIT_JOBS` reading jobs (default 1; a `parallel:` job sets the same number), each running `AUDIT_SLOTS` workers at once — as many as `AUDIT_JOB_MEMORY` holds, never more than `AUDIT_WORKERS` — and the scope is cut for one round across them. The reading and the judging hand off through files, so they run in one job (below) or as parallel reading jobs and a judge job that `needs:` them; `spec-tools workers` reads only its share in a parallel job. Set `AUDIT_JOB_MEMORY` once and give the AI jobs the same `KUBERNETES_MEMORY_LIMIT` (a YAML anchor keeps them one value; the runner must allow the overwrite); each pass logs the memory it used, which is what `AUDIT_WORKERS` is tuned from. Parallel reading jobs pay when one job cannot hold the round — a runner's default 2 GiB holds three workers; with the memory raised one job holds it, and the job that judges is the job that read: one pod, no artifact hop.
14
15
  - 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
16
  - Declare what binds beyond spec-steward's defaults once, in `package.json`: `"spec-steward": { "binds": ["scripts/checks/**", "**/*.Dockerfile", ".gitlab-ci.yml"] }`.
16
17
 
17
18
  ## Getting the tools into an AI job
18
19
 
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
- ```
20
+ 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.
27
21
 
28
22
  `spec-tools scope` and `changed` load `typescript`, so they run in a job with the workspace installed.
29
23
 
@@ -51,45 +45,43 @@ spec-diff:
51
45
  script: [yarn spec-tools diff]
52
46
  artifacts: { when: always, paths: [spec-diff.md] }
53
47
 
54
- # The run class, the coverage report and the audit's inputs, handed on as artifacts.
48
+ # The run class, the coverage report and the audit's inputs, handed on as artifacts — with the package's skills/,
49
+ # which hold the CLI the AI jobs run.
55
50
  spec-coverage:
56
51
  stage: review
57
52
  script:
58
53
  - yarn spec-tools tier | tee audit-tier.env
59
54
  - set -a && . ./audit-tier.env && set +a
60
- - yarn spec-steward coverage --out spec-coverage.md
55
+ - yarn spec-tools steward coverage --out spec-coverage.md
61
56
  - yarn spec-tools scope
62
57
  artifacts:
63
58
  when: always
64
59
  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.
60
+ paths:
61
+ [
62
+ audit-tier.env,
63
+ spec-coverage.md,
64
+ audit-scope.json,
65
+ audit-parts/,
66
+ node_modules/@kirill.konshin/lint/skills/,
67
+ ]
68
+
69
+ # The audit, in one job: read (a failed reading leaves its parts to the completion pass), merge, complete what the
70
+ # reading left short, verify every ERROR, gate.
80
71
  spec-verify:
81
72
  stage: review
82
73
  image: <an image with claude and node>
83
- needs: [spec-coverage, { job: 'spec-verify:read', optional: true }]
74
+ needs: [spec-coverage]
75
+ variables: { KUBERNETES_MEMORY_LIMIT: 8Gi, KUBERNETES_CPU_LIMIT: '4' } # AUDIT_JOB_MEMORY says the same
84
76
  allow_failure: { exit_codes: [3, 77] }
85
77
  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
78
+ - node node_modules/@kirill.konshin/lint/skills/spec-tools/scripts/cli.js workers || echo "the completion pass reads what the reading left short"
79
+ - node node_modules/@kirill.konshin/lint/skills/spec-tools/scripts/cli.js report
80
+ - node node_modules/@kirill.konshin/lint/skills/spec-tools/scripts/cli.js workers --complete
81
+ - node node_modules/@kirill.konshin/lint/skills/spec-tools/scripts/cli.js report
82
+ - node node_modules/@kirill.konshin/lint/skills/spec-tools/scripts/cli.js workers --verify
83
+ - node node_modules/@kirill.konshin/lint/skills/spec-tools/scripts/cli.js report
84
+ - node node_modules/@kirill.konshin/lint/skills/spec-tools/scripts/cli.js verdict spec-verify.json
93
85
  artifacts: { when: always, paths: [spec-verify.md, spec-verify.json, audit-parts/findings/] }
94
86
 
95
87
  # Any other skill-driven review: headless, then its verdict.
@@ -99,8 +91,7 @@ some-review:
99
91
  needs: [spec-coverage]
100
92
  allow_failure: { exit_codes: [3, 77] }
101
93
  script:
102
- - *spec-tools-setup
103
- - node_modules/.bin/spec-tools run some-review --verdict some-review.md --advisory
94
+ - node node_modules/@kirill.konshin/lint/skills/spec-tools/scripts/cli.js run some-review --verdict some-review.md --advisory
104
95
  artifacts: { when: always, paths: [some-review.md, claude.jsonl, 'job-log-*.md'] }
105
96
 
106
97
  render-reviews: