@kirill.konshin/lint 0.5.2 → 0.5.3

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.
@@ -5,7 +5,8 @@
5
5
  * This script makes `rules`, `commands` and `skills` real directories in the consuming project's
6
6
  * `.agents` (canonical, cross-tool), `.claude` (Claude Code) and `.codex`, and fills them with
7
7
  * file symlinks only: package rules and skills (SKILL.md plus the package README.md alongside it,
8
- * so a skill can reference `@README.md`) go into all three, pointing straight at the installed
8
+ * so a skill can reference `@README.md`; a folder skill with every file it ships) go into all three, pointing straight
9
+ * at the installed
9
10
  * package; the user's own files in `.agents` are mirrored into `.claude` and `.codex`. It also
10
11
  * generates an `AGENTS.md` file for other tools, with `CLAUDE.md` symlinked to `AGENTS.md`.
11
12
  *
@@ -26,6 +27,7 @@ type Rule = {
26
27
  type Skill = {
27
28
  file: string;
28
29
  name: string;
30
+ folder?: boolean;
29
31
  };
30
32
  type ExistingFile = {
31
33
  exists: boolean;
@@ -37,13 +39,15 @@ type ExistingFile = {
37
39
  */
38
40
  export declare function readRules(): Rule[];
39
41
  /**
40
- * Read all markdown files from the package skills directory. Each file becomes its own skill, named after the file
41
- * (without extension) - e.g. `lint-repo.md` becomes the `lint-repo` skill.
42
+ * Read the package skills directory. A markdown file becomes its own skill, named after the file (without extension)
43
+ * - e.g. `lint-repo.md` becomes the `lint-repo` skill; a directory holding a `SKILL.md` is a folder skill named after
44
+ * the directory, shipped with its scripts and references.
42
45
  */
43
46
  export declare function readSkills(): Skill[];
44
47
  /**
45
- * Package files to link, keyed by their path inside an agent dir: `rules/<file>`, and `skills/<name>/SKILL.md` plus
46
- * the package README.md next to it, so a skill can reference `@README.md`.
48
+ * Package files to link, keyed by their path inside an agent dir: `rules/<file>`, `skills/<name>/SKILL.md` plus the
49
+ * package README.md next to it, so a skill can reference `@README.md`, and every file of a folder skill at its own
50
+ * relative path.
47
51
  */
48
52
  export declare function packageFiles(rules: Rule[], skills: Skill[]): Map<string, string>;
49
53
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"lintPrepare.d.ts","sourceRoot":"","sources":["../src/lintPrepare.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;GAiBG;AAUH,KAAK,IAAI,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAClF,KAAK,KAAK,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAC5C,KAAK,YAAY,GAAG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AA8M1F;;GAEG;AACH,wBAAgB,SAAS,IAAI,IAAI,EAAE,CAmBlC;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,KAAK,EAAE,CAQpC;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAchF;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAc9D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAkClH;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,EAAE,CAYpF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAc9D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAKjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAsBtF;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,CAW9D;AAED;;GAEG;AACH,wBAAgB,IAAI,IAAI,IAAI,CAmD3B"}
1
+ {"version":3,"file":"lintPrepare.d.ts","sourceRoot":"","sources":["../src/lintPrepare.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAUH,KAAK,IAAI,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAClF,KAAK,KAAK,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAC9D,KAAK,YAAY,GAAG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AA8M1F;;GAEG;AACH,wBAAgB,SAAS,IAAI,IAAI,EAAE,CAmBlC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,KAAK,EAAE,CAcpC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAqBhF;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAc9D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAkClH;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,EAAE,CAYpF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAc9D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAKjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAsBtF;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,CAW9D;AAED;;GAEG;AACH,wBAAgB,IAAI,IAAI,IAAI,CAmD3B"}
@@ -5,7 +5,8 @@
5
5
  * This script makes `rules`, `commands` and `skills` real directories in the consuming project's
6
6
  * `.agents` (canonical, cross-tool), `.claude` (Claude Code) and `.codex`, and fills them with
7
7
  * file symlinks only: package rules and skills (SKILL.md plus the package README.md alongside it,
8
- * so a skill can reference `@README.md`) go into all three, pointing straight at the installed
8
+ * so a skill can reference `@README.md`; a folder skill with every file it ships) go into all three, pointing straight
9
+ * at the installed
9
10
  * package; the user's own files in `.agents` are mirrored into `.claude` and `.codex`. It also
10
11
  * generates an `AGENTS.md` file for other tools, with `CLAUDE.md` symlinked to `AGENTS.md`.
11
12
  *
@@ -218,21 +219,29 @@ export function readRules() {
218
219
  return rules;
219
220
  }
220
221
  /**
221
- * Read all markdown files from the package skills directory. Each file becomes its own skill, named after the file
222
- * (without extension) - e.g. `lint-repo.md` becomes the `lint-repo` skill.
222
+ * Read the package skills directory. A markdown file becomes its own skill, named after the file (without extension)
223
+ * - e.g. `lint-repo.md` becomes the `lint-repo` skill; a directory holding a `SKILL.md` is a folder skill named after
224
+ * the directory, shipped with its scripts and references.
223
225
  */
224
226
  export function readSkills() {
225
227
  if (!fs.existsSync(SKILLS_DIR))
226
228
  return [];
227
229
  return fs
228
- .readdirSync(SKILLS_DIR)
229
- .filter((f) => f.endsWith('.md'))
230
- .sort()
231
- .map((file) => ({ file, name: file.replace('.md', '') }));
230
+ .readdirSync(SKILLS_DIR, { withFileTypes: true })
231
+ .flatMap((entry) => {
232
+ if (entry.isDirectory() && fs.existsSync(path.join(SKILLS_DIR, entry.name, 'SKILL.md'))) {
233
+ return [{ file: entry.name, name: entry.name, folder: true }];
234
+ }
235
+ return entry.isFile() && entry.name.endsWith('.md')
236
+ ? [{ file: entry.name, name: entry.name.replace('.md', '') }]
237
+ : [];
238
+ })
239
+ .sort((a, b) => a.name.localeCompare(b.name));
232
240
  }
233
241
  /**
234
- * Package files to link, keyed by their path inside an agent dir: `rules/<file>`, and `skills/<name>/SKILL.md` plus
235
- * the package README.md next to it, so a skill can reference `@README.md`.
242
+ * Package files to link, keyed by their path inside an agent dir: `rules/<file>`, `skills/<name>/SKILL.md` plus the
243
+ * package README.md next to it, so a skill can reference `@README.md`, and every file of a folder skill at its own
244
+ * relative path.
236
245
  */
237
246
  export function packageFiles(rules, skills) {
238
247
  const files = new Map();
@@ -241,6 +250,13 @@ export function packageFiles(rules, skills) {
241
250
  files.set(path.join('rules', rule.file), path.join(RULES_DIR, rule.file));
242
251
  }
243
252
  for (const skill of skills) {
253
+ if (skill.folder) {
254
+ const root = path.join(SKILLS_DIR, skill.file);
255
+ for (const file of listRealFiles(root)) {
256
+ files.set(path.join('skills', skill.name, file), path.join(root, file));
257
+ }
258
+ continue;
259
+ }
244
260
  files.set(path.join('skills', skill.name, 'SKILL.md'), path.join(SKILLS_DIR, skill.file));
245
261
  if (hasReadme)
246
262
  files.set(path.join('skills', skill.name, 'README.md'), README_FILE);
package/package.json CHANGED
@@ -1,11 +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.5.2",
4
+ "version": "0.5.3",
5
5
  "type": "module",
6
6
  "skipGenerate": true,
7
7
  "bin": {
8
- "lint-prepare": "./dist/lintPrepare.js"
8
+ "lint-prepare": "./dist/lintPrepare.js",
9
+ "spec-steward": "./skills/spec-steward/scripts/steward.mjs"
9
10
  },
10
11
  "main": "./dist/index.js",
11
12
  "module": "./dist/index.js",
@@ -41,7 +42,8 @@
41
42
  "files": [
42
43
  "dist",
43
44
  "rules",
44
- "skills"
45
+ "skills",
46
+ "!skills/**/*.test.mjs"
45
47
  ],
46
48
  "dependencies": {
47
49
  "@eslint/config-helpers": "^0.7.0",
@@ -0,0 +1,12 @@
1
+ ---
2
+ type: always_apply
3
+ description: Hard constraints while editing an OpenSpec corpus
4
+ paths:
5
+ - 'openspec/**'
6
+ ---
7
+
8
+ - NEVER weaken, narrow, delete or reclassify a rule to make code pass — a divergence is the owner's call, ask
9
+ - A scenario adds one concrete case beyond its requirement, or it is not written
10
+ - A rule shared by several repositories is worded identically in each
11
+ - Before handing back a spec change run the repository's spec gate (AGENTS.md → Checks) and surface every `weakened` finding to the owner
12
+ - Corpus-quality audits, review rounds and cross-repository alignment follow the `spec-steward` skill; a code-conformance audit is the repository's own, named in its AGENTS.md
package/rules/testing.md CHANGED
@@ -24,3 +24,4 @@ paths:
24
24
  - Mock class methods/values or wrap originals in mocks for visibility
25
25
  - Create helper/factory functions for repeated setup, keep tests DRY
26
26
  - Prefer tests to be logic-free
27
+ - Write a test because it catches a regression, NEVER so that spec text counts as covered
@@ -0,0 +1,76 @@
1
+ ---
2
+ name: spec-steward
3
+ description: Guard, audit and repair an OpenSpec specification corpus. 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 repository's own conformance audit does — the `verify-spec` skill where the repository has one.
4
+ ---
5
+
6
+ # Spec steward
7
+
8
+ Procedures for an OpenSpec corpus. Four things live elsewhere and are not repeated here:
9
+
10
+ - the hard constraints for editing specs — the scoped rule `.agents/rules/openspec.md`
11
+ - where any guidance belongs — `.agents/rules/agent.md`
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
+ - 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
+
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`).
16
+
17
+ ## Pick the procedure
18
+
19
+ | The situation | Do |
20
+ | --------------------------------------------------------------- | ---------------------------- |
21
+ | You edited a spec, a proposal, or a test or code that cites one | [Check](#check) |
22
+ | The spec gate, the edit hook or `steward check` reported one | [Check](#check) |
23
+ | Audit the corpus, a change, or a capability | [Audit](references/audit.md) |
24
+ | The owner has answered a review file | [Apply](references/apply.md) |
25
+ | A rule lives in several repositories | [Align](#align) |
26
+ | Set up or repair the guard in a repository | [Wire](references/wiring.md) |
27
+
28
+ ## Check
29
+
30
+ Where the repository's `AGENTS.md` names a spec gate in its Checks list, such as `yarn spec:gates`, run that gate: it runs `steward check --base auto` with the repository's `--binds`. Elsewhere run `steward check --base auto` yourself. It compares the working tree with the branch point and checks the corpus and the files citing it. Add `--file <path>` to scope it, `--json` for machines, `--strict` to fail on warnings, and `--fix` for the safe mechanical repairs. A kind marked _base only_ runs only when a base is set, and under a base the prompts cover only what the diff added or edited.
31
+
32
+ | Kind | Severity | What to do |
33
+ | --- | --- | --- |
34
+ | `dangling-citation` | error | Fix the path or anchor, or remove the citation. A citation is an optional pointer; the one rule is that it resolves. |
35
+ | `renamed-anchor` | error, base only | `--fix` rewrites every citation of an anchor the diff renamed. |
36
+ | `duplicate-anchor` | error | Two headings in one spec render the same slug. Rename one. |
37
+ | `duplicate-requirement` | error | One requirement name in two capabilities, or one body twice. Keep it in the capability that owns the behaviour and reference it from the other. |
38
+ | `size` | error past 500 words or 8 obligations, info past 300 or 5 | Split the requirement into coherent areas, never into one requirement per sentence ([model](references/model.md#tests-and-scenarios)). |
39
+ | `scenario-unproven` | error, base only | A scenario you added or edited in a REQUIRED requirement has no binding. Cite it where its test, type assertion, lint entry or check proves it ([binding](references/contract.md#binding)); a test you add must catch a regression of that case. If no evidence can, the requirement takes a Known gap naming the scenario, or becomes ⚠️ ADVISORY — the owner's call. |
40
+ | `weakened` | warn, base only | A rule was removed, lowered (MUST → SHOULD), lost an absolute, gained an exception or became advisory. **Stop and ask the owner** — unless they asked for exactly this. |
41
+ | `textual-test` | warn | The test asserts on source, spec or doc text. Prefer a behavioural test, or a deterministic tool for structure. |
42
+ | `marker-hygiene` | warn | `--fix` normalises a misspelt marker. A retired `**⚠️ Unenforced:**`, or a Known gap without a tracker, exempts nothing: replace it with Advisory, a tracked Known gap, or nothing, as the [model](references/model.md#advisory-known-gap-or-neither) says, and ask the owner, because each is a reclassification. |
43
+ | `new-requirement` | info, base only | Say, in your reply, which observable failure it prevents and what cheapest evidence catches it. If there is none, it is advisory or belongs elsewhere. |
44
+ | `absolute-unproven` | info | Name the absolute's exceptions, or confirm it has none. Advisory requirements are not reported. |
45
+ | `impl-detail`, `vague-obligation`, `restating-scenario`, `duplicate-scenario`, `unbound-test` | info | Prompts for judgement, not orders. Answer them in the spec or in your reply. Never write a test just to silence one. |
46
+ | `non-ears`, `non-bdd` | info, base only | Added or edited text only: write the statement in EARS and the scenario in Given/When/Then ([model](references/model.md#tests-and-scenarios)). Never fails. |
47
+
48
+ The exact rule behind each kind is in [contract.md](references/contract.md#kinds-and-severities). The edit hook runs the per-file checks on each file you touch, with no ratchet, and feeds them back at once. Treat its message as you would this table.
49
+
50
+ ## Audit
51
+
52
+ Corpus-wide or affected-set, for corpus quality: placement, REQUIRED versus ⚠️ ADVISORY, evidence. The procedure, its parts and its verification are in [references/audit.md](references/audit.md). The output is a review file in the format of [references/review-format.md](references/review-format.md), and nothing in the specs or the code changes until the owner answers it.
53
+
54
+ Mechanical inputs:
55
+
56
+ - `steward check` (heuristic candidates)
57
+ - `steward evidence --out <dir>`: per-capability bundles, starting from the tests bound to each scenario
58
+ - `steward coverage --out <file>`: bindings, Advisory requirements and Known gaps per capability
59
+ - `steward partition --out <dir> --parts N`
60
+ - `steward index`: counts, and the citation inventory as bindings and pointers, with how many of them dangle
61
+
62
+ ## Apply
63
+
64
+ The owner answers each item in the review file. [references/apply.md](references/apply.md) processes the answers round by round:
65
+
66
+ - apply ✅
67
+ - respect ❌
68
+ - investigate a bare comment
69
+ - re-audit what changed
70
+ - append new items
71
+
72
+ `steward review status` shows what is open.
73
+
74
+ ## Align
75
+
76
+ `steward align --root A=<path> --root B=<path>` pairs the capabilities and requirements of several repositories and reports wording drift and one-sided rules. Choosing the wording is the owner's call. Once it is chosen, write it identically in every repository.
@@ -0,0 +1,18 @@
1
+ # Apply a review round
2
+
3
+ The owner has answered a review file ([review-format.md](review-format.md)). Process every item. Leave nothing half-done, and decide nothing on the owner's behalf.
4
+
5
+ 1. **Read the whole file again.** Then run `steward review status <review.md>`, which lists the open items, the comments, the accepted-but-not-applied items and the member comments of themes.
6
+ 2. **Accepted (`✅`, `✅ <comment>`).** Apply the proposal, adjusted by the comment.
7
+ - Before you touch a requirement, read the requirements that name it and that it names, and the code and tests involved. A fix must not break a sibling.
8
+ - A rule shared by several repositories changes identically in each; `steward align` shows the drift.
9
+ - When a change moves guidance to a new place, put it in the place `rules/agent.md` assigns, remove every copy, and reference it from where it used to live.
10
+ - Add `Applied: R<n> — <what changed>` under the item.
11
+ 3. **Rejected (`❌`, `❌ <comment>`).** Keep the rule as it is, or follow the owner's alternative instruction, and record what was done.
12
+ 4. **Comment only.** Investigate further and revise the proposal or the explanation in place. Move the owner's comment into `Previous response (R<n>): …` and reset the response to `⬜`. Never read a comment as acceptance.
13
+ 5. **Theme with member comments.** Apply the theme's verdict to the members without comments. Handle each commented member by its comment, as above.
14
+ 6. **Re-audit what changed.** Run the audit ([audit.md](audit.md)) over the affected set: the capabilities you edited, those that name them, and the moved guidance. Then run the repository's spec gate (`AGENTS.md` → Checks), or `steward check --base auto` where it names none. Append new findings under `## Round <n> — new`.
15
+ 7. **Verify.** Run the repository's own checks, as its `AGENTS.md` lists them, plus `steward review lint` and `steward review verify`. Report what failed or was skipped, with the reason.
16
+ 8. **Stop** while any item is open or carries an unresolved comment. Report the file, the counts and the decisions still needed. The loop ends only when every item is resolved, the accepted changes are in place, the repositories agree on shared rules, and a focused re-audit finds nothing material.
17
+
18
+ Never commit unless the repository's instructions say you may.
@@ -0,0 +1,57 @@
1
+ # Audit procedure
2
+
3
+ An audit asks whether the corpus holds the **right** rules with the **right** evidence. It judges by [model.md](model.md) and [criteria.md](criteria.md), places guidance by `rules/agent.md`, and produces a review file ([review-format.md](review-format.md)). Nothing in the specifications or the code changes during an audit. Whether the code conforms to the specifications is not its question; that is the repository's own conformance audit.
4
+
5
+ ## 1. Mechanical inputs
6
+
7
+ Run these for every repository in scope. With several repositories, pass `--root NAME=path` for each.
8
+
9
+ - `steward check` (add `--base auto` or `--base <ref>` for a change): heuristic candidates. They are leads, not verdicts.
10
+ - `steward index`: counts (capabilities, requirements, Advisory requirements, Known gaps, scenarios), and the citation inventory split into bindings and pointers, with how many of them dangle.
11
+ - `steward evidence --out <dir>`: one bundle per capability. A bundle holds each requirement verbatim with line numbers, the tests bound to its scenarios ([contract.md](contract.md#binding)), code citations as pointers, where its terms occur, and related requirements across capabilities and repositories.
12
+ - `steward coverage --out <file>`: bindings, Advisory requirements and Known gaps per capability.
13
+ - The repository's own gates and reports, when it has them.
14
+
15
+ ## 2. Fan out
16
+
17
+ One reader cannot hold a corpus, so partition it.
18
+
19
+ - **Parts.** Group a handful of related capabilities per part, and keep same-named capabilities from different repositories together so drift is judged in place. `steward partition --parts N` balances by size. Hand-made parts are fine when the architecture suggests better groups.
20
+ - **Sweeps.** Each sweep looks across the corpus from one angle:
21
+ - tooling and CI
22
+ - tests citing the corpus (compliance theatre)
23
+ - comments and citations
24
+ - a whole-corpus reader for duplicates, contradictions and cross-repository wording
25
+ - missing invariants
26
+ - the CI run classes
27
+ - placement against `rules/agent.md` (duplicated concerns, AGENTS.md hierarchy, scoped rules, skills)
28
+ - **Maps first.** An architecture map, an enforcement map and the owner's decision history go to every reader, so no one re-derives them.
29
+
30
+ With Claude Code's Workflow tool, run [`workflows/audit.js`](../workflows/audit.js). It takes the arguments documented at its top and returns verified, consolidated findings and themes. Without it, start one subagent per part and per sweep in waves, give each this procedure and its files, and run the verification below yourself.
31
+
32
+ ## 3. Verify every finding twice
33
+
34
+ 1. **Facts.** Is the quote verbatim at its line? Are the evidence references real, and does the code or test do what the finding claims?
35
+ 2. **Judgement.** The verifier acts as a skeptic and looks for these failures:
36
+ - **silent intent**: the finding decides an ambiguous intent without saying so. Revise it to offer options.
37
+ - **not a spec problem**: style, an ordinary bug, or speculation. Drop it.
38
+ - **compliance theatre**: the proposed verification catches no real failure. Revise or drop.
39
+ - **misplaced contract**: an internal contract moved out of the spec only because it is not user-facing. Revise.
40
+ - **wrong layer**. Revise.
41
+ - **unstated reversal** of a past owner decision. Revise to state it.
42
+ - **duplicate**. Drop the weaker one.
43
+
44
+ ## 4. Completeness
45
+
46
+ A critic looks for capabilities with neither findings nor a sound list, criteria that yielded nothing where the corpus plainly has cases, unread sources, and shared capabilities not compared. Its gaps become targeted follow-up units. Loop until a round finds nothing new; two rounds is usually enough.
47
+
48
+ ## 5. Consolidate and render
49
+
50
+ - **Merge duplicates per area.** The same rule with the same problem becomes one finding.
51
+ - **Form themes.** Several rules with one solution become one item with members.
52
+ - **Render** with `steward review render <result.json> --out <review.md> [--sections layout.json]`.
53
+ - **Check** with `steward review lint` and `steward review verify --root NAME=path …`.
54
+ - **Read every item yourself**: sharpen the wording, fix what the readers got wrong, and order the sections so decisions that others depend on come first.
55
+ - **Close with an appendix** listing the requirements judged sound, so coverage is visible.
56
+
57
+ Hand the file to the owner and stop.
@@ -0,0 +1,186 @@
1
+ # The spec-steward contract
2
+
3
+ What `spec-steward` checks and reports in every repository that runs it. It ships with `@kirill.konshin/lint`, so a repository is held to the version it pins. A repository's constitution states only its own choices — the `--binds` globs it passes, the jobs that run the gate, the audits it runs and where it publishes — and points here for the rest. How a specification is written is [model.md](model.md); this file is what the tool does with it. `steward.test.mjs` proves the cases below.
4
+
5
+ Terms used throughout:
6
+
7
+ - **The corpus** is every `spec.md` under the specs directory (`--specs`, default `openspec/specs`).
8
+ - **A requirement's statement** is the text between its `### Requirement:` heading and its first `#### Scenario:`. **Its block** runs from the heading to the next requirement heading.
9
+ - **A base** is the git ref the working tree is compared with ([Base resolution](#base-resolution)). A kind marked _base only_ runs only when a base is set.
10
+
11
+ ## Citation and scanning
12
+
13
+ A citation is an optional pointer to a capability specification: a mention of `openspec/specs/<capability>/spec.md`, with or without `#<anchor>`, in a `{@link}` tag, a code comment, or a document outside `openspec/changes/`. Every citation present SHALL resolve — its file exists, and its anchor, when given, is a heading that file renders; one that does not fails the build. A code citation is neither evidence that code complies nor required, and its placement and applicability are not checked.
14
+
15
+ - **Files scanned.** Every tracked file, and every untracked file git does not ignore, that is text; a file holding a NUL byte is binary and skipped. Dockerfiles, Helm templates, `.env*` and `.dockerignore` are scanned like any other text file.
16
+ - **Files skipped.** Dependency and build output directories, every `spec.md`, and all of `openspec/changes/**`, open changes included. Change folders quote other repositories and paths being removed, so they are history and plans, not pointers.
17
+ - **Where a mention counts.** Anywhere in a Markdown or MDX document. Elsewhere, only inside a `{@link …}` or `@see` tag, or inside a comment: `//`, `/* */`, a JSDoc line, `<!-- -->`, and `#` in every file that is not JavaScript, TypeScript or Markdown. A path inside a string literal is data, not a citation.
18
+ - **Resolution.** A path that starts with `openspec/` resolves from the repository root. Any other path resolves from the citing file's directory.
19
+ - **Anchors.** An anchor resolves when the cited file renders a heading with that slug. Slugs follow github-slugger: lowercase, punctuation and symbols dropped, each space a hyphen with runs kept, and a repeated heading suffixed `-1`, `-2`. `### Requirement: <name>` renders `#requirement-<slug>`; `#### Scenario: <name>` renders `#scenario-<slug>`.
20
+ - **Renames.** Under a base, a citation of an anchor that the diff renamed is reported as `renamed-anchor`, not as `dangling-citation`. `--fix` rewrites every such citation.
21
+
22
+ Cases:
23
+
24
+ - **WHEN** a cited capability, requirement, or scenario is renamed or removed **THEN** the citation stops resolving and the build fails, rather than rotting silently
25
+ - **WHEN** a file under `openspec/changes/` names a path that does not exist **THEN** nothing is reported
26
+ - **WHEN** a `#` comment in a Dockerfile cites a scenario **THEN** that citation is resolved like any other
27
+ - **WHEN** a test fixture holds a specification path inside a string **THEN** it is not a citation
28
+
29
+ ## Binding
30
+
31
+ A citation of a scenario's anchor binds the scenario only where it sits in one of the places below. A bound scenario has evidence for the [scenario ratchet](#scenario-ratchet) and the [coverage report](#coverage-report).
32
+
33
+ | Where the citation sits | Binds |
34
+ | --- | --- |
35
+ | In a test file (a JavaScript or TypeScript `*.test.*`, `*.spec.*` or `*.test-d.*` file, a file under `__tests__/` or `e2e/`, or a Python or Go test file), inside a `describe`, `it`, `test`, `suite` or `bench` call, with any `.only`, `.skip`, `.concurrent`, `.sequential`, `.todo`, `.each(…)`, `.for(…)`, `.runIf(…)`, `.skipIf(…)` or `.fails` chain, and Playwright's `test.describe`, `test.step`, `.serial`, `.parallel`, `.fixme` and `.fail`; in a Python test file, inside a `test_…` function or a `Test…` class; in a Go test file, inside a `Test…` function | yes |
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
+ | 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
+ | 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 |
40
+ | Anywhere else in a test file: its header, a fixture, a helper | no — it binds nothing and fails nothing |
41
+ | Code, configuration, YAML, a Dockerfile or a document that no `--binds` glob matches | no — it is a pointer |
42
+
43
+ A requirement's anchor binds its scenario only when the requirement has exactly one. A call's or a Go function's extent is found by balanced brackets, skipping strings, template literals and comments; a Python function's or class's, by indentation.
44
+
45
+ Cases:
46
+
47
+ - **WHEN** a citation sits in a test file's header comment **THEN** it binds no scenario, and no finding is reported for it
48
+ - **WHEN** a citation sits in the comment directly above an `it(…)` call **THEN** it binds that scenario
49
+ - **WHEN** a requirement constrains a shape, an interface or a structure **THEN** a citation on the type assertion, lint entry or `--binds` check that proves it binds its scenario, as a test's would
50
+ - **WHEN** a test cites the requirement anchor of a requirement with two scenarios **THEN** neither scenario is bound
51
+
52
+ ## Markers
53
+
54
+ There are exactly two markers. Each stands on a line of its own: the Advisory line in the requirement's statement, directly under its heading, and a Known gap line in the statement or inside the block of the scenario it qualifies.
55
+
56
+ | Marker | Meaning |
57
+ | --- | --- |
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. Inside a scenario's block, the line exempts that scenario. Coverage lists every gap with its tracker. |
60
+
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 line inside a scenario. A misspelt marker (wrong case, missing emoji or bold) is reported as `marker-hygiene`, and `--fix` normalises it.
62
+
63
+ Cases:
64
+
65
+ - **WHEN** a Known gap line under the requirement names no scenario **THEN** coverage lists the gap, and no scenario is exempt
66
+ - **WHEN** a requirement carries `**⚠️ Unenforced:**` **THEN** `marker-hygiene` warns, and the requirement is REQUIRED with no exemption
67
+ - **WHEN** an existing requirement gains the Advisory marker **THEN** `weakened` reports it for the owner
68
+
69
+ ## Kinds and severities
70
+
71
+ An `error` finding fails the run. A `warn` finding fails it only under `--strict`. An `info` finding is a prompt for judgement and never fails. Under a base, info findings are limited to the requirements and scenarios the diff added or edited and to citations in changed files; errors and warnings stay corpus-wide.
72
+
73
+ | Kind | Severity | Rule |
74
+ | --- | --- | --- |
75
+ | `dangling-citation` | error | A citation's file or anchor does not exist ([Citation and scanning](#citation-and-scanning)) |
76
+ | `renamed-anchor` | error, base only | A citation names an anchor the diff renamed; `--fix` rewrites it |
77
+ | `duplicate-anchor` | error | Two headings in one spec render the same slug |
78
+ | `duplicate-requirement` | error | The same requirement name in two capabilities, or two requirements whose bodies are equal up to whitespace |
79
+ | `size` | error / info | Over the failing line, or over the warning line ([Size gate](#size-gate-with-obligation-counting)) |
80
+ | `scenario-unproven` | error, base only | A changed scenario of a REQUIRED requirement is neither bound nor exempt ([Scenario ratchet](#scenario-ratchet)) |
81
+ | `weakened` | warn, base only | A rule was removed or lowered (MUST → SHOULD), lost an absolute, gained an exception, or was newly marked Advisory |
82
+ | `textual-test` | warn | A test asserts on the text of a source, a spec or a document |
83
+ | `marker-hygiene` | warn | A misspelt marker, a retired marker, or a Known gap without a tracker ([Markers](#markers)) |
84
+ | `new-requirement` | info, base only | A requirement the diff added: name the failure it prevents and the cheapest evidence that catches it |
85
+ | `absolute-unproven` | info | A REQUIRED requirement with an absolute in an obligation sentence, no exception word and no binding; Advisory requirements are skipped |
86
+ | `impl-detail`, `vague-obligation`, `restating-scenario`, `duplicate-scenario`, `unbound-test` | info | Judgement prompts; `unbound-test` judges block-level bindings |
87
+ | `non-ears`, `non-bdd` | info, base only | Added or edited text only. `non-ears`: the statement's first obligation sentence matches none of the forms _When …_, _While …_, _If … then …_, _Where …_ or _`<subject>` SHALL …_. `non-bdd`: a scenario lacks WHEN or THEN. |
88
+
89
+ The edit hook (`steward hook`) checks only the file an edit touched. On a spec, it compares the file with its committed version and reports `weakened` and `new-requirement`, `duplicate-anchor`, and, for the requirements the edit changed, `size`, `marker-hygiene` and the judgement prompts. On any other file it reports `dangling-citation`, and in a test file also `textual-test` and `unbound-test`. It runs no ratchet, and it does not repeat a finding it already reported in the session.
90
+
91
+ ## Size gate with obligation counting
92
+
93
+ A requirement's block over 300 words, or a statement — the text before its first scenario — issuing more than five obligations, SHALL be reported as an `info` prompt; a block over 500 words, or a statement issuing more than eight obligations, SHALL fail the build. An obligation is an RFC 2119 keyword in the statement written outside backticks — `MUST`, `SHALL`, `SHOULD`, `MAY`, `REQUIRED`, `RECOMMENDED` or `OPTIONAL`, a `NOT` form counted once; a keyword inside backticks is mentioned as a term and is not counted.
94
+
95
+ Marker lines are not part of the statement for counting. `--max-words 300,500` and `--max-obligations 5,8` set the warning and failing lines as a pair.
96
+
97
+ Cases:
98
+
99
+ - **WHEN** a requirement's block exceeds 300 words or its statement issues more than five obligations **THEN** `size` reports it at `file:line` as a prompt, and the build proceeds
100
+ - **WHEN** a requirement's block exceeds 500 words or its statement issues more than eight obligations **THEN** the build fails until the requirement is brought under the line
101
+ - **WHEN** a statement names a keyword inside backticks **THEN** the obligation count does not include it
102
+ - **WHEN** a statement reads "The gate MUST run. It SHALL NOT skip `MUST`; it MAY warn, is NEVER silent and ALWAYS logs; logging is RECOMMENDED." **THEN** it issues four obligations
103
+
104
+ ## Scenario ratchet
105
+
106
+ A scenario a merge request adds or modifies in a REQUIRED requirement SHALL be bound before the request merges, or SHALL be exempted by a `**⚠️ Known gap (<tracker>):**` line ([Markers](#markers)). An ⚠️ ADVISORY requirement is exempt. The scenarios the request's base already carries unbound are listed in the coverage report and fail nothing.
107
+
108
+ `scenario-unproven` enforces this under a base. A scenario counts as changed when its block, with whitespace normalised, appears nowhere in the base corpus, so a scenario moved verbatim is unchanged. A changed scenario fails when no [binding](#binding) cites `#scenario-<slug>` and no Known gap line exempts it. Its requirement's anchor counts only when the requirement has exactly one scenario. Without a base, the ratchet does not run.
109
+
110
+ Cases:
111
+
112
+ - **WHEN** a merge request changes a scenario of a REQUIRED requirement that nothing binds and no Known gap line exempts **THEN** `scenario-unproven` fails the run, naming the scenario at `file:line`
113
+ - **WHEN** a requirement's Known gap line names one scenario **THEN** that scenario is exempt, and the requirement's other changed scenarios still need binding
114
+ - **WHEN** a scenario of an ⚠️ ADVISORY requirement changes **THEN** the gate asks nothing of it
115
+ - **WHEN** a scenario moves to another requirement or capability unchanged **THEN** the gate asks nothing of it
116
+ - **WHEN** the base already carries a scenario unbound and the request does not change it **THEN** coverage lists it, and the run does not fail
117
+
118
+ ## Base resolution
119
+
120
+ `--base auto` picks the base from where the run happens:
121
+
122
+ | Run | Base | Effect |
123
+ | --- | --- | --- |
124
+ | Merge-request pipeline (`CI_MERGE_REQUEST_DIFF_BASE_SHA` set) | That SHA, which is already the merge base. The run exits 2 if the object is missing. | Every kind runs |
125
+ | Any other CI pipeline (`CI` set: a default-branch push, a schedule, a manual run) | None | The base-only kinds are skipped: `weakened`, `new-requirement`, `renamed-anchor`, `scenario-unproven`, `non-ears`, `non-bdd`. The skip is stated on stderr, and info findings are not printed. |
126
+ | Local | The merge base of `origin/HEAD` and `HEAD`, else of `origin/main` and `HEAD`. With neither, the run exits 2 and asks for `git fetch origin`. | Every kind runs. The head is the working tree, tracked plus untracked files. |
127
+
128
+ An explicit `--base <ref>` compares with the merge base of `<ref>` and `HEAD`. With no `--base`, no base is set.
129
+
130
+ ## Exit codes and output
131
+
132
+ | Command | Purpose | Output |
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 |
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.
140
+
141
+ ### Findings
142
+
143
+ - **stdout.** One finding per line: `<file>:<line> <severity> <kind> <message>`, prefixed with `<root> ` when several `--root` are given. With `--json`, stdout is instead an array of `{ root, file, line, severity, kind, id?, message }`.
144
+ - **stderr.** First `base: …`, then `N finding(s): <kind> <n>, …`, then `PASS|FAIL — e error(s), w warning(s), i prompt(s)`.
145
+
146
+ ### Exit codes
147
+
148
+ | Code | When |
149
+ | --- | --- |
150
+ | 0 | No error finding |
151
+ | 1 | An error finding, or a warning under `--strict` |
152
+ | 2 | A usage or environment error: an unknown flag, a base ref that does not exist, a git file listing that failed or came back empty, a missing specs directory |
153
+
154
+ Exit 2 on an empty listing keeps a broken checkout from passing a scan that read nothing.
155
+
156
+ ## Coverage report
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.
159
+
160
+ - **Headline.** Requirements and capabilities; Advisory requirements; Known gaps; REQUIRED requirements no test binds; REQUIRED scenarios no test binds; retired markers.
161
+ - **Per capability.** One table: `| Requirement / Scenario | Spec | Bound by | Pointers | Status |`.
162
+ - **Requirement status.** `advisory`, `tested`, `known gap (<tracker>)` or `no test`.
163
+ - **Scenario status.** `bound`, `known gap (<tracker>)` or `no test`, and a dash under an Advisory requirement.
164
+ - **Pointers.** The code and document citations of the requirement and its scenarios.
165
+ - **Closing sections.** "Known gaps" (tracker, requirement, text) and "Retired markers".
166
+
167
+ ## Evidence JSON
168
+
169
+ `spec-steward evidence --json` writes the evidence an audit reads, one entry per requirement:
170
+
171
+ ```
172
+ { version: 1, root, requirements: [{ id, capability, file, line, end, block, class: 'required'|'advisory',
173
+ gaps: [{ tracker, text, line, scenario: null|'<slug>', exempts: ['<slug>'] }],
174
+ scenarios: [{ slug, line, end, block, bound }],
175
+ bindings: [{ file, line, anchor, kind: 'test'|'file', title, window: [a, b] }],
176
+ pointers: [{ file, line, anchor, kind: 'code'|'doc' }],
177
+ terms: [{ term, hits: [{ file, line }] }],
178
+ related: [{ id, shared: [term] }] }] }
179
+ ```
180
+
181
+ - `class` is `advisory` when the requirement carries the Advisory marker, else `required`.
182
+ - `gaps` lists each Known gap line that carries a tracker. `scenario` is the slug of the scenario whose block holds the line, or `null` for a line under the requirement; `exempts` lists the slugs of the scenarios it exempts, empty when it exempts none.
183
+ - `bindings` are the citations that [bind](#binding) a scenario or the requirement. `kind` is `test` for a test-file binding, and `file` for a lint configuration or a `--binds` file. `title` is the bound test's title, or `null`; `window` is the line range of the bound block.
184
+ - `pointers` are every other citation of the requirement or its scenarios.
185
+ - `terms` are the requirement's own distinctive terms, with every hit in non-test sources after comments are stripped. Line numbers are kept.
186
+ - `related` lists the requirements that share terms with it, across capabilities.
@@ -0,0 +1,59 @@
1
+ # Audit criteria
2
+
3
+ An audit judges whether the corpus holds the **right** rules with the **right** evidence — specification quality first, implementation compliance only where code reveals a problem with the rule. Read [model.md](model.md) first.
4
+
5
+ ## What deserves an item
6
+
7
+ Every rule, requirement or scenario that matches one of these, numbered so findings can name them:
8
+
9
+ 1. A REQUIRED rule that should be ⚠️ ADVISORY.
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
+ 3. A rule better enforced by deterministic tooling than by an AI audit.
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.
14
+ 6. A rule that cannot reasonably be verified.
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
+ 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.
20
+ 12. Implementation suggesting the specification itself is wrong or outdated.
21
+ 13. A missing high-value invariant the architecture clearly relies on.
22
+ 14. A rule whose scope is unclear.
23
+ 15. A rule that forces repository-wide reasoning where a subsystem scope would do.
24
+ 16. A rule that encourages agents to modify specifications merely to make an implementation pass.
25
+ 17. A rule whose verification relies on comments or superficial textual matching.
26
+ 18. A tiny rule whose maintenance and enforcement cost is disproportionate to the failure it prevents.
27
+ 19. Requirements or scenarios that repeat each other.
28
+ 20. Scenario/When/Then structure that adds verbosity without precision.
29
+
30
+ Organisational criteria, for the mechanisms around the corpus:
31
+
32
+ 21. The same concern held by two or more mechanisms (spec, design, `AGENTS.md`, scoped rule, skill, command, OPSX config, tooling, test, audit) — name the authoritative one and the copies to remove.
33
+ 22. A rule shared by several repositories but worded differently.
34
+ 23. A CI or audit configuration whose cost buys no signal, or whose classification of a run is wrong.
35
+ 24. Citation machinery whose upkeep exceeds its value.
36
+
37
+ ## How to judge
38
+
39
+ - **Ask what failure the verification would catch.** If the answer is trivial, artificial, coupled to implementation, or proves only textual or structural conformity, do not propose that verification.
40
+ - **Do not create compliance theatre.** Never propose a test merely because a rule lacks one.
41
+ - **Comments are never evidence and never a violation.** Judge executable behaviour and structure.
42
+ - **Two markers, nothing else.** A requirement is REQUIRED, or carries `**⚠️ Advisory:**`; absent behaviour or missing evidence is a `**⚠️ Known gap (<tracker>):**` line ([model.md](model.md#advisory-known-gap-or-neither), spellings in [contract.md](contract.md#markers)). A retired `**⚠️ Unenforced:**`, an untracked Known gap and an unmarked silence are findings, and a proposal never introduces one.
43
+ - **Ordinary bugs are out of scope** unless they show the rule is unrealistic, unclear, outdated, ambiguous, or contradicted by the tests' actual contract.
44
+ - **Do not decide intent silently.** Where the intent is ambiguous, say so and propose options; flag `needsHumanIntent`.
45
+ - **Do not flag style preference.** Every finding has a concrete reason.
46
+ - **Internal contracts are specification.** Do not move a rule out of the corpus because it is not user-facing.
47
+ - **Past owner decisions are stated.** A proposal that reverses one names it.
48
+
49
+ ## Proposals name their target
50
+
51
+ Start every proposal with one of:
52
+
53
+ - `Keep → OpenSpec REQUIRED invariant` (optionally with a rewrite, or with a `**⚠️ Known gap (<tracker>):**` line when its behaviour or its evidence is missing)
54
+ - `Reclassify → OpenSpec ⚠️ ADVISORY` (the requirement gains an `**⚠️ Advisory:**` line; one that mixes a contract with guidance is split, the contract staying REQUIRED)
55
+ - `Move → <target>` — the design narrative (the repository's design documents or a package README), `<dir>/AGENTS.md`, `scoped rule (<glob>)`, `skill <name>` (referenced from `AGENTS.md` when it holds material moved out of it), `command <name>`, `openspec/config.yaml#<key>`, `README.md`
56
+ - `Replace → <tool>` — ESLint rule, dependency rule, type assertion, schema, script
57
+ - `Merge → <other rule>`
58
+ - `Rewrite → "<new text>"`
59
+ - `Delete → <reason>`