@kirill.konshin/lint 0.5.4 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (114) hide show
  1. package/README.md +47 -7
  2. package/commands/spec-author.md +39 -0
  3. package/dist/configs/base.d.ts +4 -3
  4. package/dist/configs/base.js +61 -74
  5. package/dist/configs/imports.d.ts +3 -2
  6. package/dist/configs/imports.js +95 -146
  7. package/dist/configs/nx.d.ts +4 -3
  8. package/dist/configs/nx.js +31 -41
  9. package/dist/configs/prettier.d.ts +3 -2
  10. package/dist/configs/prettier.js +19 -16
  11. package/dist/configs/promise.d.ts +3 -2
  12. package/dist/configs/promise.js +16 -16
  13. package/dist/configs/react.d.ts +4 -3
  14. package/dist/configs/react.js +178 -217
  15. package/dist/configs/storybook.d.ts +4 -3
  16. package/dist/configs/storybook.js +22 -22
  17. package/dist/configs/tailwind.d.ts +4 -3
  18. package/dist/configs/tailwind.js +67 -91
  19. package/dist/configs/testing.d.ts +7 -6
  20. package/dist/configs/testing.js +112 -136
  21. package/dist/configs/turbo.d.ts +4 -3
  22. package/dist/configs/turbo.js +19 -27
  23. package/dist/configs/typescriptTypeAware.d.ts +4 -3
  24. package/dist/configs/typescriptTypeAware.js +99 -95
  25. package/dist/configs/unicorn.d.ts +3 -2
  26. package/dist/configs/unicorn.js +34 -41
  27. package/dist/exts.d.ts +2 -1
  28. package/dist/exts.js +10 -11
  29. package/dist/index.d.ts +44 -41
  30. package/dist/index.js +53 -84
  31. package/dist/lib.d.ts +21 -21
  32. package/dist/lib.js +261 -301
  33. package/dist/lintPrepare.d.ts +33 -28
  34. package/dist/lintPrepare.js +347 -376
  35. package/dist/lintStaged.d.ts +4 -3
  36. package/dist/lintStaged.js +25 -22
  37. package/dist/prettier.d.ts +4 -3
  38. package/dist/prettier.js +16 -17
  39. package/dist/restrictions.d.ts +24 -0
  40. package/dist/restrictions.js +20 -0
  41. package/dist/yarn.cjs +79 -98
  42. package/dist/yarn.d.cts +3 -2
  43. package/package.json +24 -8
  44. package/rules/agent.md +7 -4
  45. package/rules/openspec.md +1 -1
  46. package/skills/spec-steward/SKILL.md +4 -12
  47. package/skills/spec-steward/references/audit.md +18 -43
  48. package/skills/spec-steward/references/contract.md +7 -7
  49. package/skills/spec-steward/references/criteria.md +4 -4
  50. package/skills/spec-steward/references/model.md +1 -1
  51. package/skills/spec-steward/references/review-format.md +6 -6
  52. package/skills/spec-steward/references/wiring.md +4 -4
  53. package/skills/spec-steward/references/worker.md +67 -0
  54. package/skills/spec-steward/scripts/lib/align.mjs +7 -6
  55. package/skills/spec-steward/scripts/lib/checks.mjs +6 -1
  56. package/skills/spec-steward/scripts/lib/corpus.mjs +5 -8
  57. package/skills/spec-steward/scripts/lib/coverage.mjs +2 -3
  58. package/skills/spec-steward/scripts/lib/evidence.mjs +2 -148
  59. package/skills/spec-steward/scripts/lib/wire.mjs +6 -4
  60. package/skills/spec-steward/scripts/steward.mjs +30 -91
  61. package/skills/spec-steward/sweeps.json +49 -0
  62. package/skills/spec-tools/SKILL.md +46 -0
  63. package/skills/spec-tools/references/contract.md +111 -0
  64. package/skills/spec-tools/references/gitlab.md +122 -0
  65. package/skills/spec-verify/SKILL.md +153 -0
  66. package/spec-tools/dist/audit-DkZZulq6.mjs +130 -0
  67. package/spec-tools/dist/auditChanged-CNGjlake.mjs +1 -0
  68. package/spec-tools/dist/auditChanged-CZCvMgyZ.mjs +618 -0
  69. package/spec-tools/dist/auditReport-xgq4wK2i.mjs +458 -0
  70. package/spec-tools/dist/auditScope-CBuBtfPG.mjs +104 -0
  71. package/spec-tools/dist/changeGates-DdeQKfle.mjs +333 -0
  72. package/spec-tools/dist/changeGates-uy4Ti8rK.mjs +1 -0
  73. package/spec-tools/dist/ci-BUewHJS3.mjs +143 -0
  74. package/spec-tools/dist/ci-CFBzn8Of.mjs +1 -0
  75. package/spec-tools/dist/cli.mjs +93 -0
  76. package/spec-tools/dist/comment-szasMMg2.mjs +57 -0
  77. package/spec-tools/dist/files-Bppsb34B.mjs +1 -0
  78. package/spec-tools/dist/files-QlzY687_.mjs +38 -0
  79. package/spec-tools/dist/html-BMTkpbUN.mjs +1766 -0
  80. package/spec-tools/dist/jsonrepair-Dlm5dEen.mjs +742 -0
  81. package/spec-tools/dist/repo-CjIoUPYl.mjs +16 -0
  82. package/spec-tools/dist/repo-DUcnJw3c.mjs +1 -0
  83. package/spec-tools/dist/run-BElA9du3.mjs +67 -0
  84. package/spec-tools/dist/specDiff-8G56jMYn.mjs +123 -0
  85. package/spec-tools/dist/steward-DeieyOcj.mjs +34 -0
  86. package/spec-tools/dist/stewardAudit-BRMM0lrD.mjs +1 -0
  87. package/spec-tools/dist/stewardAudit-v0vOMfLN.mjs +271 -0
  88. package/spec-tools/dist/tier-Cn0P7juM.mjs +1 -0
  89. package/spec-tools/dist/tier-c3s_mA_I.mjs +65 -0
  90. package/spec-tools/dist/util-wnxhsnWO.mjs +49 -0
  91. package/spec-tools/dist/verdict-BFfN9PO8.mjs +58 -0
  92. package/spec-tools/dist/workers-BcIgckeq.mjs +417 -0
  93. package/spec-tools/dist/workflowEvidence-DyBj8EdG.mjs +1 -0
  94. package/spec-tools/dist/workflowEvidence-oui6ghPI.mjs +78 -0
  95. package/dist/configs/base.d.ts.map +0 -1
  96. package/dist/configs/imports.d.ts.map +0 -1
  97. package/dist/configs/nx.d.ts.map +0 -1
  98. package/dist/configs/prettier.d.ts.map +0 -1
  99. package/dist/configs/promise.d.ts.map +0 -1
  100. package/dist/configs/react.d.ts.map +0 -1
  101. package/dist/configs/storybook.d.ts.map +0 -1
  102. package/dist/configs/tailwind.d.ts.map +0 -1
  103. package/dist/configs/testing.d.ts.map +0 -1
  104. package/dist/configs/turbo.d.ts.map +0 -1
  105. package/dist/configs/typescriptTypeAware.d.ts.map +0 -1
  106. package/dist/configs/unicorn.d.ts.map +0 -1
  107. package/dist/exts.d.ts.map +0 -1
  108. package/dist/index.d.ts.map +0 -1
  109. package/dist/lib.d.ts.map +0 -1
  110. package/dist/lintPrepare.d.ts.map +0 -1
  111. package/dist/lintStaged.d.ts.map +0 -1
  112. package/dist/prettier.d.ts.map +0 -1
  113. package/dist/yarn.d.cts.map +0 -1
  114. package/skills/spec-steward/workflows/audit.js +0 -539
@@ -12,10 +12,11 @@ import { isTestFile, scanCitations } from './citations.mjs';
12
12
  import { capabilityOf, DEFAULT_SPECS_DIR, parseSpec } from './corpus.mjs';
13
13
  import { git, show, toplevel } from './git.mjs';
14
14
 
15
- export const SCRIPT = 'node_modules/@kirill.konshin/lint/skills/spec-steward/scripts/steward.mjs';
16
- export const HOOK_COMMAND = `f="$CLAUDE_PROJECT_DIR/${SCRIPT}"; [ ! -f "$f" ] || node "$f" hook`;
15
+ /** The bin the package installs; the hook is a no-op until the repository's install provides it. */
16
+ export const BIN = 'node_modules/.bin/spec-steward';
17
+ export const HOOK_COMMAND = `f="$CLAUDE_PROJECT_DIR/${BIN}"; [ ! -x "$f" ] || "$f" hook`;
17
18
  export const AGENTS_LINE =
18
- "Specifications: edits under `openspec/` are guarded by the scoped rule `.agents/rules/openspec.md` and the `spec-steward` edit hook; corpus-quality audits, review rounds and cross-repository alignment use the `spec-steward` skill, and code conformance is the repository's own audit.";
19
+ 'Specifications: edits under `openspec/` are guarded by the scoped rule `.agents/rules/openspec.md` and the `spec-steward` edit hook; corpus-quality audits, review rounds and cross-repository alignment use the `spec-steward` skill, and code conformance is the `spec-verify` audit (`spec-tools`).';
19
20
  /** The OPSX guidance points at the repository's own spec gate; the gate runs spec-steward, so no second command. */
20
21
  export const GATE_POINTER = 'AGENTS.md → Checks';
21
22
  export const GUIDANCE = {
@@ -53,7 +54,8 @@ export function wireStatus(root) {
53
54
  (e.hooks ?? []).some(
54
55
  (/** @type {any} */ h) =>
55
56
  typeof h.command === 'string' &&
56
- h.command.includes('steward.mjs') &&
57
+ // the bin, or the script by path as earlier versions wired it
58
+ /spec-steward|steward\.mjs/.test(h.command) &&
57
59
  h.command.includes('hook'),
58
60
  ),
59
61
  );
@@ -7,16 +7,14 @@
7
7
  * spec-steward check [--base auto|<ref>] [--binds <glob>]... [--file f] [--fix] [--strict] [--json]
8
8
  * [--max-words P,F] [--max-obligations P,F] the corpus gate (also local and the hook)
9
9
  * spec-steward coverage [--out file] [--binds <glob>]... the coverage report, MDX-safe Markdown
10
- * spec-steward evidence --json [--binds <glob>]... the audit's evidence model on stdout
11
- * spec-steward evidence --out dir [--root NAME=path]... per-capability evidence bundles
12
- * spec-steward partition --out dir --parts N balanced parts over the bundles in --out
13
- * spec-steward index [--full] [--binds <glob>]... corpus and citation summary as JSON
10
+ * spec-steward evidence --json [--binds <glob>]... the audits' evidence model on stdout
14
11
  * spec-steward review render|status|verify|lint ... the review-file engine
15
12
  * spec-steward align --root A=path --root B=path [--json] wording drift of shared rules across repos
16
13
  * spec-steward wire [--check|--fix] the guard's steering points in a repository
17
14
  * spec-steward hook Claude Code PostToolUse entry (stdin JSON)
18
15
  *
19
- * Common flags: --root NAME=path (repeatable), --specs <dir> (default openspec/specs).
16
+ * Common flags: --root NAME=path (repeatable), --specs <dir> (default openspec/specs). A repository's own binds live in its
17
+ * root package.json, `"spec-steward": { "binds": [...] }`, and add to every `--binds` given.
20
18
  * Exit: 0 clean; 1 an error finding (or a warning under --strict); 2 a usage or environment error — an unknown flag,
21
19
  * a base ref that does not exist, a git listing that fails or is empty, a missing specs directory.
22
20
  */
@@ -34,9 +32,9 @@ import {
34
32
  SIZE,
35
33
  } from './lib/checks.mjs';
36
34
  import { scanCitations } from './lib/citations.mjs';
37
- import { allRequirements, DEFAULT_SPECS_DIR, loadCorpus, loadCorpusAt, parseSpec } from './lib/corpus.mjs';
35
+ import { DEFAULT_SPECS_DIR, loadCorpus, loadCorpusAt, parseSpec } from './lib/corpus.mjs';
38
36
  import { coverageReport } from './lib/coverage.mjs';
39
- import { capabilityEvidence, evidenceModel, partition, sourceIndex } from './lib/evidence.mjs';
37
+ import { evidenceModel, sourceIndex } from './lib/evidence.mjs';
40
38
  import { changedFiles, forget, listFiles, resolveBase, toplevel } from './lib/git.mjs';
41
39
  import { parseArgs } from './lib/util.mjs';
42
40
 
@@ -46,12 +44,10 @@ const anchorsOf = (/** @type {string} */ text) => parseSpec(text, '', '').slugs;
46
44
  const FLAGS = {
47
45
  check: ['base', 'binds', 'file', 'fix', 'strict', 'json', 'max-words', 'max-obligations', 'all-citations'],
48
46
  coverage: ['out', 'binds'],
49
- evidence: ['out', 'json', 'binds'],
50
- partition: ['out', 'parts'],
51
- index: ['full', 'binds'],
47
+ evidence: ['json', 'binds'],
52
48
  };
53
49
  const COMMON = ['root', 'specs'];
54
- const BOOLEANS = ['fix', 'strict', 'json', 'all-citations', 'full', 'check'];
50
+ const BOOLEANS = ['fix', 'strict', 'json', 'all-citations', 'check'];
55
51
 
56
52
  /** A usage or environment error: reported on stderr, exit 2. */
57
53
  class UsageError extends Error {}
@@ -91,8 +87,23 @@ function assertScannable(root) {
91
87
  throw new UsageError(`${root.name}: git lists no files — is ${root.path} a repository?`);
92
88
  }
93
89
 
94
- /** @param {Record<string, any>} opts */
95
- const bindsOf = (opts) => /** @type {string[]} */ ([].concat(opts.binds ?? []).filter((b) => typeof b === 'string'));
90
+ /**
91
+ * What binds beyond the defaults: the repository's own `binds` (`"spec-steward": { "binds": [...] }` in its root
92
+ * `package.json`), then every `--binds` given.
93
+ * @param {Record<string, any>} opts
94
+ * @param {string} root
95
+ */
96
+ const bindsOf = (opts, root) => {
97
+ let configured = [];
98
+ try {
99
+ configured = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'))['spec-steward']?.binds ?? [];
100
+ } catch {
101
+ // no package.json, or not JSON: nothing configured
102
+ }
103
+ return /** @type {string[]} */ (
104
+ [...[].concat(configured), ...[].concat(opts.binds ?? [])].filter((b) => typeof b === 'string')
105
+ );
106
+ };
96
107
 
97
108
  /**
98
109
  * Every finding for one repository, and the base it was judged against.
@@ -111,7 +122,7 @@ export function runCheck(root, opts) {
111
122
  how = resolved.how;
112
123
  }
113
124
  const corpus = loadCorpus(root.path, root);
114
- const binds = bindsOf(opts);
125
+ const binds = bindsOf(opts, root.path);
115
126
  if (opts.file && (typeof opts.file !== 'string' || !fs.existsSync(path.resolve(opts.file))))
116
127
  throw new UsageError(`--file ${opts.file}: no such file`);
117
128
  const relative = (/** @type {string} */ f) =>
@@ -168,34 +179,6 @@ async function main(argv) {
168
179
  validateFlags(cmd, opts);
169
180
  const roots = rootsOf(opts);
170
181
 
171
- if (cmd === 'index') {
172
- const out = roots.map((root) => {
173
- assertScannable(root);
174
- const corpus = loadCorpus(root.path, root);
175
- const citations = scanCitations(root.path, anchorsOf, { binds: bindsOf(opts) });
176
- const reqs = allRequirements(corpus);
177
- const count = (/** @type {(c: import('./lib/citations.mjs').Citation) => boolean} */ p) =>
178
- citations.filter(p).length;
179
- return {
180
- name: root.name,
181
- path: root.path,
182
- capabilities: corpus.capabilities.length,
183
- requirements: reqs.length,
184
- advisory: reqs.filter((r) => r.advisory).length,
185
- gaps: reqs.reduce((n, r) => n + r.gaps.length, 0),
186
- scenarios: reqs.reduce((n, r) => n + r.scenarios.length, 0),
187
- citations: {
188
- bindings: count((c) => !!c.binding),
189
- pointers: count((c) => !c.binding),
190
- dangling: count((c) => !c.resolves),
191
- },
192
- corpus: opts.full ? corpus.capabilities.map((c) => ({ ...c, slugs: undefined })) : undefined,
193
- };
194
- });
195
- process.stdout.write(JSON.stringify(out, null, 2) + '\n');
196
- return 0;
197
- }
198
-
199
182
  if (cmd === 'check') {
200
183
  let failed = false;
201
184
  const all = [];
@@ -251,7 +234,7 @@ async function main(argv) {
251
234
  assertScannable(root);
252
235
  const { markdown, totals } = coverageReport(
253
236
  loadCorpus(root.path, root),
254
- scanCitations(root.path, anchorsOf, { binds: bindsOf(opts) }),
237
+ scanCitations(root.path, anchorsOf, { binds: bindsOf(opts, root.path) }),
255
238
  );
256
239
  if (typeof opts.out === 'string') {
257
240
  fs.writeFileSync(path.resolve(opts.out), markdown);
@@ -262,70 +245,26 @@ async function main(argv) {
262
245
  return 0;
263
246
  }
264
247
 
265
- if (cmd === 'evidence' && opts.json) {
248
+ if (cmd === 'evidence') {
249
+ if (!opts.json) throw new UsageError('evidence takes --json: the evidence model on stdout');
266
250
  const root = oneRoot(roots, cmd);
267
251
  assertScannable(root);
268
252
  const model = evidenceModel(
269
253
  loadCorpus(root.path, root),
270
- scanCitations(root.path, anchorsOf, { binds: bindsOf(opts) }),
254
+ scanCitations(root.path, anchorsOf, { binds: bindsOf(opts, root.path) }),
271
255
  sourceIndex(root.path),
272
256
  );
273
257
  process.stdout.write(JSON.stringify(model) + '\n');
274
258
  return 0;
275
259
  }
276
260
 
277
- if (cmd === 'evidence') {
278
- const out = path.resolve(opts.out ?? 'spec-evidence');
279
- const corpora = roots.map((root) => {
280
- assertScannable(root);
281
- return {
282
- root,
283
- corpus: loadCorpus(root.path, root),
284
- citations: scanCitations(root.path, anchorsOf, { binds: bindsOf(opts) }),
285
- sources: sourceIndex(root.path),
286
- };
287
- });
288
- const everywhere = corpora.flatMap(({ corpus }) =>
289
- allRequirements(corpus).map((requirement) => ({ corpus, requirement })),
290
- );
291
- const bundles = [];
292
- for (const { root, corpus, citations, sources } of corpora) {
293
- for (const cap of corpus.capabilities) {
294
- const file = path.join(out, root.name, `${cap.capability}.md`);
295
- fs.mkdirSync(path.dirname(file), { recursive: true });
296
- const md = capabilityEvidence(corpus, cap, citations, sources, everywhere);
297
- fs.writeFileSync(file, md);
298
- bundles.push({
299
- corpus: root.name,
300
- capability: cap.capability,
301
- file,
302
- bytes: Buffer.byteLength(md),
303
- requirementIds: cap.requirements.map((r) => r.id),
304
- });
305
- }
306
- }
307
- fs.writeFileSync(path.join(out, 'bundles.json'), JSON.stringify(bundles, null, 2));
308
- process.stderr.write(`${bundles.length} bundle(s) in ${out}\n`);
309
- return 0;
310
- }
311
-
312
- if (cmd === 'partition') {
313
- const out = path.resolve(opts.out ?? 'spec-evidence');
314
- const bundles = JSON.parse(fs.readFileSync(path.join(out, 'bundles.json'), 'utf8'));
315
- const parts = partition(bundles, Number(opts.parts ?? 16));
316
- fs.writeFileSync(path.join(out, 'parts.json'), JSON.stringify(parts, null, 2));
317
- for (const p of parts)
318
- process.stdout.write(`part ${p.part}: ${Math.round(p.bytes / 1024)} KB — ${p.capabilities.join(', ')}\n`);
319
- return 0;
320
- }
321
-
322
261
  if (cmd === 'review') return (await import('./lib/review.mjs')).reviewCli(rest, roots);
323
262
  if (cmd === 'align') return (await import('./lib/align.mjs')).alignCli(opts, roots);
324
263
  if (cmd === 'wire') return (await import('./lib/wire.mjs')).wireCli(opts, roots[0]);
325
264
  if (cmd === 'hook') return (await import('./lib/wire.mjs')).hookCli(opts);
326
265
 
327
266
  throw new UsageError(
328
- 'usage: spec-steward check|coverage|evidence|partition|index|review|align|wire|hook — see the header of steward.mjs',
267
+ 'usage: spec-steward check|coverage|evidence|review|align|wire|hook — see the header of steward.mjs',
329
268
  );
330
269
  }
331
270
 
@@ -0,0 +1,49 @@
1
+ [
2
+ {
3
+ "key": "tooling-ci",
4
+ "title": "Tooling, CI and the run classes",
5
+ "focus": "Which rules a deterministic check, a lint rule or a type would enforce better than an audit (criterion 3); CI and audit configuration whose cost buys no signal, or whose classification of a run is wrong (23); the same concern held by a CI job and a specification or a skill (21).",
6
+ "files": [
7
+ ".gitlab-ci.yml",
8
+ ".gitlab/**/*.yml",
9
+ ".github/workflows/*.yml",
10
+ ".github/workflows/*.yaml",
11
+ "package.json",
12
+ "nx.json",
13
+ "turbo.json",
14
+ "scripts/checks/**"
15
+ ]
16
+ },
17
+ {
18
+ "key": "compliance-theatre",
19
+ "title": "Tests citing the corpus",
20
+ "focus": "Tests bound to the specifications that satisfy the wording while failing to protect the intent (5), that are low-value or artificial (4), or whose verification relies on comments or textual matching (17).",
21
+ "from": "bindings"
22
+ },
23
+ {
24
+ "key": "comments-citations",
25
+ "title": "Comments and citations",
26
+ "focus": "Citation machinery whose upkeep exceeds its value (24), citations standing in for evidence (17), comments restating a rule the specification owns (21).",
27
+ "from": "pointers"
28
+ },
29
+ {
30
+ "key": "missing-invariants",
31
+ "title": "Missing invariants",
32
+ "focus": "High-value invariants the architecture clearly relies on that no requirement states (13), and implementation suggesting a specification is wrong or outdated (12).",
33
+ "files": ["README.md", "ARCHITECTURE.md", "docs/**/*.md"]
34
+ },
35
+ {
36
+ "key": "placement",
37
+ "title": "Placement",
38
+ "focus": "Rules that belong in AGENTS.md, a scoped rule, a skill, a command, the OPSX config or a README rather than the specification, and the reverse (2); the same concern held by two mechanisms (21); AGENTS.md hierarchy and scoped-rule scope. Judge by the placement guide, rules/agent.md.",
39
+ "files": [
40
+ "AGENTS.md",
41
+ "**/AGENTS.md",
42
+ ".agents/rules/*.md",
43
+ ".agents/skills/*/SKILL.md",
44
+ ".agents/commands/**/*.md",
45
+ "openspec/config.yaml",
46
+ "openspec/config.yml"
47
+ ]
48
+ }
49
+ ]
@@ -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.