@kirill.konshin/lint 0.5.1 → 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.
Files changed (30) hide show
  1. package/README.md +6 -4
  2. package/dist/lintPrepare.d.ts +32 -31
  3. package/dist/lintPrepare.d.ts.map +1 -1
  4. package/dist/lintPrepare.js +261 -125
  5. package/package.json +5 -3
  6. package/rules/agent.md +42 -36
  7. package/rules/openspec.md +12 -0
  8. package/rules/testing.md +1 -0
  9. package/skills/lint-repo.md +2 -2
  10. package/skills/spec-steward/SKILL.md +76 -0
  11. package/skills/spec-steward/references/apply.md +18 -0
  12. package/skills/spec-steward/references/audit.md +57 -0
  13. package/skills/spec-steward/references/contract.md +186 -0
  14. package/skills/spec-steward/references/criteria.md +59 -0
  15. package/skills/spec-steward/references/model.md +71 -0
  16. package/skills/spec-steward/references/review-format.md +61 -0
  17. package/skills/spec-steward/references/wiring.md +19 -0
  18. package/skills/spec-steward/scripts/lib/align.mjs +126 -0
  19. package/skills/spec-steward/scripts/lib/checks.mjs +584 -0
  20. package/skills/spec-steward/scripts/lib/citations.mjs +156 -0
  21. package/skills/spec-steward/scripts/lib/corpus.mjs +259 -0
  22. package/skills/spec-steward/scripts/lib/coverage.mjs +124 -0
  23. package/skills/spec-steward/scripts/lib/evidence.mjs +335 -0
  24. package/skills/spec-steward/scripts/lib/git.mjs +138 -0
  25. package/skills/spec-steward/scripts/lib/review.mjs +347 -0
  26. package/skills/spec-steward/scripts/lib/scan.mjs +364 -0
  27. package/skills/spec-steward/scripts/lib/util.mjs +161 -0
  28. package/skills/spec-steward/scripts/lib/wire.mjs +331 -0
  29. package/skills/spec-steward/scripts/steward.mjs +350 -0
  30. package/skills/spec-steward/workflows/audit.js +539 -0
package/rules/agent.md CHANGED
@@ -15,12 +15,11 @@ Use this summarized guidance to consider where to place a set of instructions
15
15
  - `README.md` — human-readable instructions how to work with repo
16
16
  - Root `AGENTS.md` — default context for agents, always included
17
17
  - Subdirectory `AGENTS.md` — scoped to this particular directory, auto-injected
18
- - `.claude/rules` — forced rules (or automatic guardrails), that agent will read based on frontmatter, with paths scope; may pollute context if not scoped well; should NOT have detailed guidance, examples, etc.
19
- - `rules/` referred from `AGENTS.md` — simple decomposition to clear up default context from specific / scoped / rarely used instructions, no frontmatter
20
- - `.claude/skills` or `.codex/skills` — one-off flows, potentially complex; but also sets of rules that agent may or may not read/follow, good for progressive disclosure, examples, thorough guidance, and has to be well-defined in frontmatter to increase likelihood of success, example: https://www.skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
21
- - `.claude/commands` — one-off commands, usually simpler than skills
18
+ - `.agents/rules` — forced rules (or automatic guardrails), that agent will read based on frontmatter, with paths scope; may pollute context if not scoped well; should NOT have detailed guidance, examples, etc.
19
+ - `.agents/skills` — one-off flows, potentially complex; but also sets of rules & instructions that agent may or may not read/follow, good for progressive disclosure, examples, thorough guidance, and something you want to offload from `AGENTS.md` (and cite from it), and has to be well-defined in frontmatter to increase likelihood of success, example: https://www.skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
20
+ - `.agents/commands` — one-off commands, usually simpler than skills
22
21
  - `openspec/specs` - SDD specifications, should define user facing behavior or API contracts, not coding instructions / best practices / etc.
23
- - `openspec/config.yml#context` - should only have very narrow rules for OpenSpec specifically, when user entered flow
22
+ - `openspec/config.yml#context` - should only have very narrow instructions for OpenSpec specifically, when user entered flow
24
23
  - `openspec/config.yml#rules.[specs|proposal]` - very narrow sets of rules specifically for defined part of the flow when it's entered
25
24
  - `openspec/config.yml#operation.[apply|archive].guidance` - very narrow sets of rules specifically for defined part of the flow when it's entered
26
25
 
@@ -29,15 +28,15 @@ Use this summarized guidance to consider where to place a set of instructions
29
28
  When deciding where information belongs, use this order:
30
29
 
31
30
  1. Is it durable observable system/component behavior?
32
- - → **`openspec/specs`**
31
+ - **→ `openspec/specs`**
33
32
  2. Must the agent always know it when touching a deterministically identifiable set of files?
34
- - → **scoped `.claude/rules`**
33
+ - **→ scoped `.agents/rules`**
35
34
  3. Is it mandatory repo-wide or directory-wide context/routing?
36
- - → **`AGENTS.md`**
35
+ - **→ `AGENTS.md`**
37
36
  4. Is it detailed knowledge, guidance, examples, best practices, or a reusable procedure that should be progressively disclosed?
38
37
  - **→ skill**
39
38
  5. Is it merely supporting material extracted from `AGENTS.md` to reduce default context?
40
- - **→ `rules/`**, referenced explicitly from `AGENTS.md`
39
+ - **→ skill**, referenced explicitly from `AGENTS.md`
41
40
  6. Is it primarily documentation for humans?
42
41
  - **→ `README.md`**
43
42
 
@@ -50,27 +49,12 @@ Prefer one authoritative location for each concern. Reference it elsewhere inste
50
49
  - Should be targeted to be read by humans
51
50
  - First file that's visible to humans
52
51
 
53
- # `.claude/rules` and `.codex/rules`
54
-
55
- - Can itself be a link to rules from a package; or individual files inside can be symlinks
56
- - Must be accompanied by symlink `.codex/rules`
57
- - Files should be scoped to certain paths
58
- - Files should be small,
59
- - Examples not allowed in general
60
- - Should describe only coding conventions, recommendations, forced contextual instructions / automatic guardrails
61
- - As bullet points
62
- - Concise, terse and to the point
63
- - Hard constraints
64
- - That must appear in scope by `paths` glob
65
-
66
52
  # `AGENTS.md`
67
53
 
68
54
  - Root `AGENTS.md`
69
- - Should be minimalistic and should refer to `rules/xxx.md` in order not to pollute default context if
70
- - Can be decomposed as references to files in `rules/` folder also located at repo root
71
- - Folder has no semantics of its own; it is not a standard but merely a convention for progressive-disclosure documentation referenced by AGENTS.md.
72
- - Files in `rules/` should be referred conditionally, e.g. with minimal explanation what's inside so agent has better chances of reaching them
73
- - Frontmatter not supported
55
+ - Should be minimalistic
56
+ - Can be decomposed as `skills` & `rules` (with references to them)
57
+ - Such references to skills should be referred conditional, e.g. with minimal explanation when to use so agent has better chances of reaching them
74
58
  - Decomposition should be used when
75
59
  - Section is narrowly scoped (installation instructions / testing / particular framework or technology) and not always applicable
76
60
  - Section is large
@@ -78,12 +62,26 @@ Prefer one authoritative location for each concern. Reference it elsewhere inste
78
62
  - Repo-wide convention to use SDD should be defined here to be always visible
79
63
  - Focus on mandatory routing and instructions
80
64
  - Sub-directory `AGENTS.md`
81
- - Directory-specific rules should be in `AGENTS.md` of that folder
82
- - Lift rules up the tree to higher `AGENTS.md` if multiple dirs must adhere to rules, don't copy-paste them
65
+ - Directory-specific rules & instructions should be in `AGENTS.md` of that folder
66
+ - Lift rules & instructions up the tree to higher `AGENTS.md` if multiple dirs must adhere to them, don't copy-paste them
83
67
  - All `AGENTS.md` files should be accompanied by a symlink `CLAUDE.md`
84
68
 
85
- # `.claude/skills` and `.codex/skills`
69
+ # `.agents/rules`
86
70
 
71
+ - `.agents/rules` must be accompanied by symlinks in `.claude/rules` and `.codex/rules`
72
+ - Files should be scoped to certain paths
73
+ - Files should be small,
74
+ - Examples not allowed in general
75
+ - Should describe only coding conventions, recommendations, forced contextual instructions / automatic guardrails
76
+ - As bullet points
77
+ - Concise, terse and to the point
78
+ - Hard constraints
79
+ - That must appear in scope by `paths` glob
80
+ - Should be cited in `AGENTS.md` to ensure they're discoverable by harnesses that don't support `.xxx/rules` natively
81
+
82
+ # `.agents/skills`
83
+
84
+ - `.agents/skills` must be accompanied by symlinks in `.claude/skills` and `.codex/skills`
87
85
  - May define either
88
86
  - A workflow
89
87
  - A process
@@ -94,8 +92,9 @@ Prefer one authoritative location for each concern. Reference it elsewhere inste
94
92
  - Agent decides to discover it or not, use it or not, so no guarantee of honoring
95
93
  - A requirement/rule MUST NOT exist only in a skill if correctness depends on the agent always observing it
96
94
 
97
- # `.claude/commands`
95
+ # `.agents/commands`
98
96
 
97
+ - `.agents/commands` must be accompanied by symlinks in `.claude/commands` and `.codex/commands`
99
98
  - Smaller and simpler than skills
100
99
  - One-off commands, not flows
101
100
 
@@ -105,13 +104,20 @@ Prefer one authoritative location for each concern. Reference it elsewhere inste
105
104
  - User facing or externally observable behavior
106
105
  - Durable component/system/API contracts & invariants
107
106
  - Not general coding instructions
108
- - Openspec-specific instructions must assume that flow WAS ENTERED, thus `AGENTS.md` or `[.claude|.codex]/skills` must be used to define how to enter the flow, and how flow should look like from outside perspective (without details)
109
- - `openspec/config.yml#context` - should only have very narrow rules for OpenSpec specifically, when user entered flow
107
+ - Openspec-specific instructions must assume that flow WAS ENTERED, thus `AGENTS.md` or `[.agents|.claude|.codex]/skills` must be used to define how to enter the flow, and how flow should look like from outside perspective (without details)
108
+ - `openspec/config.yml#context` - should only have very narrow instructions for OpenSpec specifically, when user entered flow
110
109
  - Context will already contain root `AGENTS.md`, no duplication needed
111
110
  - `openspec/config.yml#rules.[specs|proposal]` - very narrow sets of rules specifically for defined part of the flow when it's entered
112
- - `openspec/config.yml#operation.[apply|archive].guidance` - very narrow sets of rules specifically for defined part of the flow when it's entered
111
+ - `openspec/config.yml#operation.[apply|archive].guidance` - very narrow sets of instructions specifically for defined part of the flow when it's entered
112
+ - The two litmus questions:
113
+ - Could the implementation be rewritten substantially and the statement still hold? Then it is SPEC.
114
+ - Could the detail change while the contract stays the same? Then it is not SPEC.
115
+ - Requirements and scenarios should (preferrably) be proven by tests, and may be cited in tests for stronger connection
116
+ - Tests should be validated that they do what spec says (optional, unless project mandates this in root `AGENTS.md`)
117
+ - Code citations must resolve, not checked for validity
113
118
 
114
- # Common rules for `.claude/rules`, `.codex/rules`, `AGENTS.md` and `rules/`
119
+ # Common for `AGENTS.md` `.agents/rules` `.agents/skills`
115
120
 
116
121
  - If project uses Spec Driven Development framework like OpenSpec, these files should be free from product specifications / external behavior, and only focused on general coding instructions
117
- - Preferred syntax rules to structure plain human language: `EARS` for requirements and `BDD` (Given/When/Then) for scenarios
122
+ - Preferred instructions/rules syntax how to structure plain human language: `EARS` for requirements and `BDD` (Given/When/Then) for scenarios
123
+ - Rules & instructions in these files can't be cited from tests or code, so their proof is tooling, never a citation
@@ -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
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: lint-repo
3
- description: Set up/update this repo's ESLint + Prettier + lint-staged + Husky tooling (@kirill.konshin/lint), and/or audit the codebase against the packaged agent rules. Rules are discovered from .claude/rules/*.md (created by `lint-prepare init`), falling back to node_modules/@kirill.konshin/lint/rules/*.md; project overrides in AGENTS.md Custom Rules / CLAUDE.md win on conflict. Use when asked to set up, configure, or upgrade lint/format/pre-commit tooling, OR to check, audit, verify, or lint the codebase against agent rules/conventions.
3
+ description: Set up/update this repo's ESLint + Prettier + lint-staged + Husky tooling (@kirill.konshin/lint), and/or audit the codebase against the packaged agent rules. Rules are discovered from .agents/rules/*.md (created by `lint-prepare init`), falling back to node_modules/@kirill.konshin/lint/rules/*.md; project overrides in AGENTS.md Custom Rules / CLAUDE.md win on conflict. Use when asked to set up, configure, or upgrade lint/format/pre-commit tooling, OR to check, audit, verify, or lint the codebase against agent rules/conventions.
4
4
  ---
5
5
 
6
6
  # Lint Repo
@@ -27,7 +27,7 @@ Check the README's "Issues" section before debugging a lint crash.
27
27
 
28
28
  ## B. Audit code against rules
29
29
 
30
- Rules: `.claude/rules/*.md` → else `node_modules/@kirill.konshin/lint/rules/*.md`; plus overrides in `AGENTS.md # Custom Rules` / `CLAUDE.md` (override wins on conflict). Treat rule files as normative — read them directly.
30
+ Rules: `.agents/rules/*.md` → else `node_modules/@kirill.konshin/lint/rules/*.md`; plus overrides in `AGENTS.md # Custom Rules` / `CLAUDE.md` (override wins on conflict). Treat rule files as normative — read them directly.
31
31
 
32
32
  ### 1. Mechanical pass first
33
33
 
@@ -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>`