| name | spec-enforce |
| description | SDD spec enforcement orchestrator — the canonical cross-agent contract. Runs the 23-row execution manifest against the current diff (or full spec on scope=all). Detects forbidden content, REQ-shape violations, status drift, meta-leakage, changelog drift, backlog state, source-anchor truth-check (CQ-SOURCE — always runs), and per-AC test-anchor coverage at parity with source anchors (CQ-TEST — gated by enforce_tdd). Conditionally invokes spec-enforce-ac (when ACs touched) and spec-enforce-truth (when Implemented or Partial REQs touched or scope=all — Partial included so CQ-SOURCE can validate anchors). Invoked by spec-reviewer on every PR-boundary trigger and inline by the root-owned /sdd clean workflow. |
| version | 4.0.0 |
Spec Enforcement (orchestrator)
This skill is the spine for SDD spec enforcement. It runs the 23-row execution manifest against sdd/ and orchestrates the conditional detail skills (spec-enforce-ac, spec-enforce-truth). It is one canonical contract: every agent runtime executes the same rules, severities, mandated commands, and finding vocabulary, so a repo gets identical findings regardless of which agent reviews it.
Inputs
purpose: review | clean. review is report-only — never edit the spec, queue, or audit files; return findings and evidence. clean applies fixes under the mode rules and records them in the /sdd clean audit.diff: the review window the caller hands you — an incremental <base>..<head> range on a re-review, the base...HEAD diff on a first PR-boundary review, or the full-tree view on scope=all. Enforce exactly the window provided; never widen a provided incremental window back out to the full PR diff. The "Git diff syntax" section below is only the default used when no window is provided.scope: all | diff (default diff)mode: interactive | auto | unleashed (read from sdd/spec/config.yml when nested layout exists, else sdd/config.yml on flat layout)layout: nested | flat (auto-detected via test -d sdd/spec)
Layout-awareness. All file globs in this skill respect the detected layout:
- Spec files:
sdd/spec/**/*.md (nested) OR sdd/*.md excluding README.md (flat)
- Config:
sdd/spec/config.yml (nested) OR sdd/config.yml (flat)
- Triage / escalation:
sdd/spec/.review-queue.md (nested) OR sdd/.review-needed.md (flat, legacy)
The flat layout is supported during the migration window; /sdd clean migrates flat → nested on demand.
Scope contract
When the caller supplies a prepared review packet or resolved in-scope set, consume it; do not reconstruct the diff after the packet exists. Under scope=diff, build the in-scope set from:
- changed REQ/Constraints/Status/field hunks;
- REQs whose inline
@impl anchors target changed source symbols or files;
- REQs whose inline
@test anchors target changed or renamed test files/blocks;
- dependencies, index entries, and changelog entries directly changed or required by those REQs;
- changed queue lines and commits in the supplied range.
Rows with no relevant input report inert (reason) naming the absent trigger. Do not scan unrelated REQs, backlog entries, or baseline prose — searching all spec files for anchors that cite a changed path is allowed because it traces direct invalidation; judging unrelated content is not. Under scope=all, walk every active REQ and support file; every applicable row is exhaustive.
Scope never lowers severity or truth requirements. There are no token, turn, or tool budgets; scope is the work bound.
Execution contract (binding)
Every row of the manifest below MUST execute on every run. No cherry-picking; cost is never a valid skip. Manifest written FIRST with all rows pending, updated as each rule completes, finalised at run end. Pending rows at finalize emit HIGH manifest-pending-at-finalize. Status rows without concrete evidence counts (ran (N REQs, M findings)) emit HIGH manifest-bare-evidence-count. "skipped (looked clean)" is dishonest.
In-depth, not at-a-glance (binding). Each row is a full pass over its scope, not a spot-check. A row that reports 0 findings is asserting it walked every REQ/file in scope and each passed — if you did not actually inspect each one, that is a dishonest 0. "looked fine" / "appears clean" / "intentional given the feature" are not dispositions; either the item passes the rule or it is a finding.
Every fired finding MUST be disposed of (binding). When a rule fires at MEDIUM or HIGH, the run MUST record one of exactly three dispositions per occurrence: auto-fixed (what), escalated -> .review-queue.md (reason + blast radius), or — interactive mode only — deferred to user confirmation. Silently re-labelling a fired MEDIUM/HIGH as LOW, "soft limit", "deferred", or "by design" to avoid acting on it is itself HIGH finding-downgraded-to-skip. The severity in the rule table is the floor; an agent may not lower it. (A prior run downgraded four ac-count-over-cap MEDIUMs to "LOW soft-limit" and skipped them — a contract breach.) If an auto-fix would itself be destructive (e.g. an AC renumber that orphans by-number cross-refs), the correct disposition is escalated with the blast radius, never deferred/LOW.
Audit location by trigger: /sdd clean writes to per-category commit bodies. A PR-boundary spec-reviewer returns the execution manifest; the root persists it in the applicable commit body or layout-resolved review queue.
Required execution manifest
| Rule | Required action this run | Status |
|---|
| Forbidden content in REQs | Walk every Active REQ; flag banned tokens in AC/Intent. | ran (N REQs, M findings) |
| Status field semantics + Deprecated cleanup | Walk every REQ; verify Status is one of the four valid values; delete any Status: Deprecated entries per the deletion rule. | ran (N REQs, M findings) |
| REQ rendering template (binding) | Walk every Active REQ; verify render shape AND that cross-reference fields render IDs as markdown anchor links. | ran (N REQs, M findings) |
| REQ length guidance | Walk every Active REQ; flag length tiers. | ran (N REQs, M findings) |
| Acceptance criteria + AC granularity + REQ accretion guard | Invoke spec-enforce-ac when diff touches any AC bullet OR scope=all. | ran (N REQs, K diff hunks, M findings) or inert (no AC diff) |
| Per-AC verbosity + Constraints conciseness | Invoke spec-enforce-ac when diff touches any AC bullet OR any **Constraints:** bullet OR scope=all. Catches rationale-essay ACs (>45 prose words) and Constraint-bibles (bullet >45 words / section >150 words) the line-count gauge misses. | ran (N REQs, M findings) or inert |
| Actor coherence | Invoke spec-enforce-ac (same condition as above). | ran (N REQs, M findings) or inert |
| Sub-bullets in ACs banned | Invoke spec-enforce-ac. | ran (N REQs, M findings) or inert |
| Cross-cutting concerns get own REQ family | Invoke spec-enforce-ac. | ran (N REQs, M findings) or inert |
| Concern-boundary split | Invoke spec-enforce-ac. | ran (N REQs, M findings) or inert |
| Mechanism leakage in AC bullets | Invoke spec-enforce-ac. | ran (N REQs, M findings) or inert |
| Changelog drift | Diff sdd/changes.md against AC-changed diff hunks. | ran (K entries, M findings) |
| Meta-content leakage Rule A (stub-after-extraction) | Walk every REQ; flag stub shape. | ran (N REQs, M findings) |
| Meta-content leakage Rule B (Notes two-shape) | Walk every Notes field; flag violations. | ran (N Notes, M findings) |
| Meta-content leakage Rule C (preamble edit-history) | Walk every sdd/{domain}.md preamble; flag edit-history prose. | ran (K files, M findings) |
| CQ-TEST — Test-anchor coverage | Invoke spec-enforce-truth if enforce_tdd: true AND (Implemented REQs touched OR scope=all). Covers BOTH the REQ-level binary check AND per-AC verification that at least one @test anchor exists at parity with @impl/CQ-SOURCE, while every declared anchor resolves (ac-missing-test-anchor MEDIUM, spec-test-anchor-orphaned HIGH). | ran (N REQs, M findings, T test-anchors verified, O orphaned, U unanchored) or inert (enforce_tdd: false) |
| CQ-SOURCE — Source-anchor truth-check | During /sdd init: consume both the Phase 7a verifier JSON (.verify-anchors.json) AND the Phase 7b enumeration-coverage verifier JSON (.phase-7b.json). The Phase 7a output drives anchor-orphaned / value-drift findings; the Phase 7b output drives phase-7b-evidence-missing / import-mode-narrowed-scope findings (a Phase 7b unaccounted > 0 reported in the [sdd-init] commit body is itself a CRITICAL spec-side finding). Outside /sdd init: invoke spec-enforce-truth UNCONDITIONALLY when any Implemented or Partial REQ in diff OR scope=all. Never gated by enforce_tdd. Agent self-attestation without verifier output = CRITICAL phase-7a-self-attestation / phase-7b-self-attestation (see sdd-init/SKILL.md steps 7 and 8). When reading the most recent [sdd-init] commit body to verify the bulk-op actually ran, both the Phase 7a line (Phase 7a verifier: parsed=...) AND the Phase 7b line (Phase 7b enum verifier: enumerated=...) MUST be present; either line missing = CRITICAL phase-7a-evidence-missing / phase-7b-evidence-missing. | ran (N REQs, A anchors verified, V drift, O orphaned, U unanchored) |
| CQ-1, CQ-2, CQ-3 | Invoke spec-enforce-truth. | ran (...) or inert |
| Index integrity (README ↔ filesystem) | Run the mandated command in § Index integrity; every tracked file under sdd/spec/ (flat: sdd/*.md) must be indexed in sdd/README.md, REQ-bearing files in the Domains table, support files in a Support section. Non-empty output = finding. Eyeballing the index is forbidden — the command is the check. | ran (F files, M unindexed/misclassified) |
| REQ dependency acyclicity | Run the mandated cycle detector in § REQ dependency acyclicity over every **Dependencies:** field; any cycle = HIGH finding. | ran (N REQs, E edges, C cycles) |
| Queue hygiene (live queue, not history log) | Run the mandated command in § Queue hygiene; resolved/dated-historical content in sdd/spec/.review-queue.md (flat: sdd/.review-needed.md) = finding — resolved findings are removed, not archived. | ran (Q lines, M findings) |
| Backlog re-triage | Walk every open finding in the layout-resolved triage file (sdd/spec/.review-queue.md nested OR sdd/.review-needed.md flat legacy); re-classify under current rules; auto-fix what is now mechanisable. | ran (B items, R re-triaged, F auto-fixed, S still-escalated) |
| Commit-prefix + 5-round limit | Check last 6 commits; halt if 5+ counted-tag commits in lane. | ran (6 commits inspected, M findings) |
Orchestration logic
- Parse diff. Identify: changed REQs, changed files, changed AC bullets, REQ ID set in diff, Status field changes,
sdd/changes.md deltas.
- Always-runs rows (the 13 inline rows in the manifest above — Forbidden content, Status field semantics, REQ rendering, REQ length, Changelog drift, the three Meta-content leakage rules, Index integrity, REQ dependency acyclicity, Queue hygiene, Backlog re-triage, Commit-prefix + 5-round limit): execute inline. Each row updates its manifest status to
ran (N REQs, M findings) immediately on completion. The three structural-integrity rows (Index integrity, REQ dependency acyclicity, Queue hygiene) are mandated commands, not judgments — run the command verbatim and treat its output as the finding set; never substitute an at-a-glance read. The remaining 10 rows invoke spec-enforce-ac (7 rows: AC granularity, per-AC verbosity + Constraints conciseness, actor coherence, sub-bullets, cross-cutting, concern-boundary, mechanism leakage) or spec-enforce-truth (3 rows: CQ-TEST, CQ-SOURCE, CQ-1/2/3) per the conditional rules below.
- Conditional invocations:
- IF any AC bullet line changed in diff OR any
**Constraints:** bullet changed in diff OR scope=all: invoke spec-enforce-ac skill with the diff + scope + mode. (Constraints bullets are included so the Constraints-conciseness rule fires on a diff that touches only Constraints; a touched REQ gets its ACs AND Constraints checked.)
- IF any REQ with
Status: Implemented or Status: Partial is in the diff, OR any path matched by src_globs (from the layout-resolved config; default defined in spec-enforce-truth/SKILL.md § Inputs) is in the diff, OR scope=all: invoke spec-enforce-truth skill with the diff + scope + mode. Source-touching diffs trigger invocation because source changes can orphan existing @impl anchors in unchanged REQs — CQ-SOURCE must re-validate. Partial REQs are included because they may carry source anchors that can drift, and CQ-SOURCE must run wherever an anchor exists (Truth guarantee is never gated). The skill itself decides per-pass which REQs each pass applies to (CQ-TEST only fires on Implemented when enforce_tdd: true; CQ-SOURCE fires on every REQ whose @impl anchors target the changed source OR every Implemented/Partial REQ on scope=all).
- Aggregate findings from sub-skill invocations into the unified manifest. Each sub-skill returns its own evidence rows.
- Apply mode (
purpose=clean only; purpose=review returns findings without editing):
interactive: confirm each fix; CRITICAL/HIGH/MEDIUM blocking, LOW deferred.auto: silently apply CRITICAL/HIGH/MEDIUM; defer LOW to /sdd clean.unleashed: apply everything including LOW; per-category commits.
- Write manifest to audit location with final statuses + per-row evidence counts.
Evidence economics. Gather the deterministic commands for the inline rows plus the focused evidence reads needed by triggered sub-skill rows in as few tool waves as possible — one mcp__context-mode__ctx_execute program that prints counts and failures when context-mode is available, otherwise equivalent direct read/grep/bash calls batched together. Keep raw successful output out of context; the manifest carries counts and failures only. If concrete findings still need direct evidence, collect all unresolved candidates in one additional focused wave; never re-read policy text, packet sections, or completed evidence.
Forbidden content in REQs
REQs in sdd/{domain}.md describe observable behaviour. The following NEVER appear inside a REQ AC or Intent:
Lane file paths below use the form documentation/[lanes/]<name>.md because projects use either flat (documentation/<name>.md) or nested (documentation/lanes/<name>.md) layouts. Resolve to whichever exists in the target project.
| Banned | Where it goes instead |
|---|
| Hex color codes, CSS class names, keyframe names, viewBox values, bezier coords, animation timings, z-index | documentation/[lanes/]architecture.md or design-system.md |
| File paths, function names | documentation/[lanes/]architecture.md |
| Database column names (implementation-detail columns) | documentation/[lanes/]architecture.md |
| Cookie names | documentation/[lanes/]security.md or authentication.md |
| HTTP status code enumerations | documentation/[lanes/]api-reference.md |
| JSON request/response schemas, endpoint paths | documentation/[lanes/]api-reference.md |
| Env var names | documentation/[lanes/]configuration.md |
| Build-tool internals | documentation/[lanes/]troubleshooting.md |
| TypeScript code snippets, SQL queries | documentation/[lanes/]architecture.md |
| Debugging checklists | documentation/[lanes/]troubleshooting.md |
| Strikethrough text | Delete. Git history is the strikethrough. |
| "Current implementation:" / "Planned (not implemented):" branches in an AC | pending.md |
| Implementation TODOs | GitHub issue |
Allowlist (acceptable in REQs)
Vendor product names (Cloudflare Access, Stripe), protocol names (OAuth 2.0, JWT, SSE), standards refs (WCAG 2.1 AA, GDPR, RFC 9116), performance targets ("p95 < 200ms"), user-facing strings in quotes (these ARE the AC), HTTP status codes when the REQ is about an error contract, env var names when in Configuration domain, DB column / KV key names when the storage shape IS the persistence contract.
sdd/config.yml overrides via forbidden_content_allowlist and forbidden_content_overrides.
Deprecated REQs are deleted
When a REQ stops being the contract — feature removed, replaced by another REQ, scope dropped — delete it from sdd/{domain}.md entirely. Do not mark Status: Deprecated, do not keep a tombstone, do not preserve old ACs. Git log is the history.
If a successor REQ carries the new contract, the successor stands on its own — no Replaced By: field, no AC migration. Any clauses worth keeping are folded into the successor's ACs before the source REQ is deleted, in the same commit. If no successor exists and the idea should be remembered as not-built, move a one-line summary into the domain README's "Out of Scope" section, then delete the REQ.
Auto-fix in auto/unleashed: detect Status: Deprecated REQs and delete them; if Replaced By: was set, fold any AC clauses not already covered into the successor first; append a sdd/changes.md entry naming the deleted REQ and successor (if any). No successor and no Out-of-Scope candidacy: escalate to .review-needed.md rather than delete blind.
REQ rendering template (binding)
Canonical shape: spec-driven-development/references/templates/req-shape-example.md. That fixture is the single source of truth for REQ rendering. Every Active REQ in sdd/{domain}.md (flat layout) or sdd/spec/{domain}.md (nested layout) MUST copy its shape exactly. Deviations from any rule below are MEDIUM, auto-fixed by re-rendering.
Rules walked by this row (single normative list):
- Heading:
### REQ-{DOMAIN}-{NNN}: {Title} (H3, never H2).
- Field order is locked: Intent → Applies To → Acceptance Criteria → Notes (optional) → Constraints → Priority → Dependencies → Verification → Status. Status is ALWAYS the last field. Out-of-order fields = MEDIUM
req-field-order-violation.
- Required fields present in every REQ: Intent, Applies To, Acceptance Criteria, Constraints, Priority, Dependencies, Verification, Status. Missing field = MEDIUM
req-missing-required-field.
- Empty Constraints/Dependencies render the literal
None. (with trailing period). Omitting the field entirely is a req-missing-required-field violation, NOT a no-op.
- Cross-reference linking: Every
CON-* and REQ-* ID inside **Constraints:** and **Dependencies:** MUST render as a markdown anchor link. Same-file REQ: [REQ-X-NNN](#req-x-nnn-title-slug). Other-domain REQ: [REQ-X-NNN](other-domain.md#req-x-nnn-title-slug). Constraint: [CON-X-NNN](constraints.md#con-x-nnn-title-slug). Slugs follow GFM convention. Plain-text IDs in these fields = MEDIUM cross-reference-not-linked. Detection: regex \b(REQ|CON)-[A-Z]+-\d+\b inside the field values, outside ]( ) parentheses.
- Blank-line policy: one blank line between every
**Field:** line, including each member of the trailing-fields block (Constraints, Priority, Dependencies, Verification, Status). Two label lines on consecutive lines collapse on GitHub render = MEDIUM trailing-fields-collapsed. Closing --- separator on its own line, blank lines either side.
- AC numbering: ACs are numbered (
1. 2. 3.), never bulleted (-) = MEDIUM ac-bullets-not-numbered. Maximum 7 ACs per REQ.
- Source anchors: Every AC describing observable behaviour ends with
<!-- @impl: <path>::<symbol> -->. ACs asserting a concrete value use <!-- @impl: <path>::<symbol> = <value-pattern> -->. Anchor absent on an AC = MEDIUM ac-missing-source-anchor (ACs carrying <!-- @manual --> exempt).
- Test anchors (parity, gated by
enforce_tdd): when enforce_tdd: true, every such AC ALSO ends with at least one <!-- @test: <path> (<describe/it title>) --> naming a test block that proves it. Multiple anchors are valid, and CQ-TEST validates every declared anchor independently. Anchor absent = MEDIUM ac-missing-test-anchor (the parallel of ac-missing-source-anchor); any anchor whose file/block does not resolve = HIGH spec-test-anchor-orphaned (the parallel of spec-anchor-orphaned). ACs carrying <!-- @manual --> exempt; informational only when enforce_tdd: false. Verified by CQ-TEST in spec-enforce-truth.
- Manual-verification markers: an AC whose behaviour genuinely cannot be verified by an automated test carries
<!-- @manual --> (bare) or <!-- @manual: <procedure> --> (when a dedicated manual procedure exists) in place of the anchors. The marker is per-AC — there is no REQ-level exemption. Coherence with the Verification: field is enforced by spec-enforce-truth (verification-field-marker-drift).
- Banned inside a REQ body: sub-headings (
####/#####), nested lists, code blocks, tables, strikethrough, "Current behaviour:" / "Previously:" branches, block quotes.
Auto-fix in auto/unleashed: re-render the REQ from its parsed fields into the canonical shape (inserts blank lines, renumbers ACs, reorders fields, rewrites cross-refs as anchor links, fills None. on empty Constraints/Dependencies). Interactive mode prompts before each rewrite. If a required field cannot be inferred from existing content (e.g. Applies To: was never written), escalate to triage rather than fabricate.
REQ length guidance
| Length | Severity |
|---|
| <=25 lines | OK |
| 26-50 lines | LOW |
| 51-100 lines | MEDIUM |
| >100 lines | HIGH |
Oversized REQs are shrunk in place first (extract implementation prose to documentation/); when shrinking is exhausted, split. The split mechanics live in spec-enforce-ac.
This line-count table is the coarse gauge only. A REQ can sit in the <=25 lines OK band while individual ACs and Constraints are prose-dense rationale-essays. The prose-density rules (per-AC verbosity, per-Constraint-bullet conciseness, and the AC granularity triggers) live in spec-enforce-ac and fire at MEDIUM/HIGH independent of this table. Never read a green line-count as license to pass a REQ whose ACs or Constraints are bloated; run the spec-enforce-ac checks on every touched REQ.
Status field semantics — transitions and auto-fix
Status transitions: Proposed -> Planned -> (Partial <-> Implemented). When a REQ stops being the contract, it is deleted (see Deprecated rule above). Implementation tracking (SHAs, paths) belongs in pending.md or issues, never in Status.
Partial may have a Notes: field <=3 sentences. No other status uses Notes (except doc-pointer per Rule B). Out-of-scope ideas go to "Out of Scope" in the domain README, not to a Deprecated Status.
The Verification: field is derived from the per-AC markers: Manual check when EVERY AC carries <!-- @manual -->; otherwise Automated test (linked to the covering test file when unambiguous). Field/marker disagreement is MEDIUM verification-field-marker-drift, enforced by spec-enforce-truth.
Auto-fix: invalid Status values (e.g. Done, WIP, prose) get rewritten to the nearest valid value based on commit history / test coverage. Deprecated triggers the deletion auto-fix above.
Changelog drift and discipline
sdd/changes.md is a product changelog. Strict format:
- Entries dated (
## YYYY-MM-DD)
- Each entry <=2 sentences, user-facing only
- No commit SHAs
- No verification-pass entries
- No entries for spec cleanup, doc corrections, format fixes
- No entries documenting agent's own operations
When to add: new REQ; AC changed in user-affecting way; REQ deprecated or moved to Out of Scope; auto-demote from Implemented -> Partial.
When NOT to add: strikethrough cleanup; Status field truncation; format fixes; implementation leakage moved to docs; any change that doesn't affect what the product does.
Drift detection: for each new entry, scan the same diff for an AC change in the referenced REQ. No REQ reference OR no AC delta = LOW changelog-drift. Auto-fix in unleashed: delete the drift entry.
Meta-content leakage (three rules)
Same failure mode at three scales: meta-content about the spec leaking into the spec.
Rule A — Stub REQ after cross-cutting extraction
A REQ whose entire contract is "participates in [REQ-Y-NNN]" with no observable predicate of its own is a hop, not a contract. Detection (all four must hold):
- REQ has <=1 AC.
- AC body contains a markdown link to another REQ.
- AC body matches one of:
participates in, inherits, defined by, applies the policy, governed by, subject to (case-insensitive).
- REQ's
Dependencies: includes that linked REQ.
Severity: MEDIUM stub-after-extraction. Auto-fix in unleashed: delete the source REQ. Surface-specific framing prepended to policy REQ Notes. Append sdd/changes.md entry. Update all backlinks. Edge case: when the source REQ has an actor-specific predicate beyond the bare pointer ("auth buckets are per-IP, mutation buckets are per-user-id"), detection condition 3 fails — keeping the REQ is correct.
Rule B — Notes: field two sanctioned shapes
| Shape | When valid | Form |
|---|
| (a) Partial-explanation | Status: Partial only | <=3 sentences explaining what's unmet. No mechanism tokens (file paths, function names, env vars, commit SHAs) - those go in pending.md or documentation/. |
| (b) Doc-pointer | Any status | <=2 sentences, MUST contain >=1 markdown link to documentation/** or sdd/**, prose pattern "X is documented at [link]" |
Sibling-REQ cross-references use Dependencies:, NOT Notes.
Detection: Notes on non-Partial REQ without a markdown link: MEDIUM notes-on-non-partial-without-pointer. Notes on Partial REQ exceeding 3 sentences OR carrying mechanism tokens: MEDIUM notes-partial-bloat.
Auto-fix in unleashed: reshape to doc-pointer form if a link to documentation/** or sdd/** exists; otherwise fold content into Intent and delete Notes. For Partial-bloat: trim to <=3 sentences. Test-name migration prose moves to pending.md.
Rule C — Domain file preamble bans edit-history prose
Prose between an sdd/{domain}.md H1 and the first --- separator (or first ### REQ- heading) describes WHAT the domain is. Edit history belongs in git log and sdd/changes.md.
Scope: Rule C applies ONLY to sdd/{domain}.md concrete domain spec files — not dotfiles, README.md, sdd/changes.md, sdd/glossary.md, sdd/constraints.md, sdd/.init-triage.md, sdd/config.yml.
Forbidden patterns in preamble: ISO dates (\d{4}-\d{2}-\d{2}); edit verbs (refactored, updated, migrated, extracted from, moved from, previously contained, was reshaped, now describes); rule names (actor-coherence, sub-bullets-banned, etc.); ^This file (was|has been) pattern; self-referential framing co-occurring with the above.
Severity: LOW preamble-edit-history-leakage. Auto-fix in unleashed: delete offending paragraph(s). Structural-change descriptions go as a single consolidated dated entry to sdd/changes.md.
Index integrity
A link-valid README can still be semantically wrong (the ai-news-digest incident: six support files and a REQ-bearing domain missing from an eyeball-"clean" index). This is a mandated command, not a judgment. Run it; non-empty output is the finding set.
Nested layout:
for f in sdd/spec/* sdd/.*.md; do [ -f "$f" ] || continue; b=$(basename "$f"); grep -wqF -- "$b" sdd/README.md || echo "UNINDEXED: $b"; done
grep -l '^### REQ-' sdd/spec/*.md
grep -oE '\]\(([^)]+\.md)\)' sdd/README.md | sed -E 's/^\]\(|\)$//g' \
| while read -r l; do [ -f "sdd/$l" ] || [ -f "$l" ] || echo "DANGLING: $l"; done
Flat layout: replace sdd/spec/* with sdd/*.md excluding sdd/README.md. The doc-side equivalent (documentation/lanes/ ↔ documentation/README.md) runs in doc-enforce.
Findings: each UNINDEXED: line = MEDIUM index-unindexed-file; a REQ-bearing file (matched by check 2) absent from the README Domains table = MEDIUM index-domain-misclassified (a non-REQ file listed as a domain = same); each DANGLING: line = MEDIUM index-dangling-link.
Auto-fix in auto/unleashed: add each missing file to the README — REQ-bearing files to the Domains table, support files to a ## Support files section — deriving the description from the file's own H1 / first line, never inventing one. Remove dangling links to deleted files. Interactive prompts before each README edit. If a file's role is genuinely ambiguous (no ### REQ- but clearly a domain), escalate rather than guess its table.
REQ dependency acyclicity
Dependency cycles hide in prose and survive until a human notices. An agent cannot reliably trace cycles across hundreds of REQs by reading — so this is a mandated computation (text-only; runs in-process, not a build). Run it verbatim:
python3 - <<'PY'
import re, glob
files = sorted(glob.glob('sdd/spec/*.md')) or [f for f in sorted(glob.glob('sdd/*.md')) if not f.endswith('README.md')]
edges, cur = {}, None
for fn in files:
for ln in open(fn):
m = re.match(r'###\s+(REQ-[A-Z]+-\d+)', ln)
if m: cur = m.group(1)
elif cur and ln.startswith('**Dependencies:**'):
edges.setdefault(cur, []).extend(re.findall(r'REQ-[A-Z]+-\d+', ln))
color, seen = {}, set()
def dfs(u, st):
color[u] = 1; st.append(u)
for v in edges.get(u, []):
if color.get(v) == 1:
cyc = st[st.index(v):] + [v]
if frozenset(cyc) not in seen:
seen.add(frozenset(cyc)); print('CYCLE:', ' -> '.join(cyc))
elif color.get(v) is None and v in edges:
dfs(v, st)
st.pop(); color[u] = 2
for n in list(edges):
if color.get(n) is None: dfs(n, [])
print(f'REQs={len(edges)} edges={sum(len(v) for v in edges.values())} cycles={len(seen)}')
PY
Each CYCLE: line = HIGH req-dependency-cycle. Never auto-edit a dependency edge — which edge to break is semantic. Disposition is always escalated -> .review-queue.md with the full cycle path and the recommended break (keep child→parent/core, drop parent→child/extension; a UI-surface REQ may depend on its endpoint contract or the endpoint on auth/core policy, but not both ways). The Status line reports cycles=N from the script's last line.
Queue hygiene
sdd/spec/.review-queue.md (flat: sdd/.review-needed.md) is a live queue, not a history log. Resolved findings are removed; historical audit lives in changelog/ADR/commit bodies. Run:
grep -nE '✅|^#+ +(Resolved|Closed|Archive)\b|^#+ +20[0-9]{2}-|\b(RESOLVED|CLOSED|FIXED)\b' \
sdd/spec/.review-queue.md
wc -l sdd/spec/.review-queue.md
Any match = MEDIUM queue-history-leak. Auto-fix in auto/unleashed: delete resolved/closed entries and dated historical sections, leaving only genuinely-open findings — or the empty sentinel No open findings. when none remain. Genuinely-open findings (no resolved marker) are preserved verbatim. Interactive prompts before trimming. The empty-slot scaffold (_Awaiting first finding._) does not match and is not a finding.
Backlog re-triage
Without re-triage, escalated findings become permanent terminal state. Every PR-boundary trigger MUST run Backlog re-triage. Walks each open finding in sdd/spec/.review-queue.md (nested) or sdd/.review-needed.md (flat, legacy); three outcomes:
- Re-classified as auto-fixable: the finding's category now has a deterministic auto-fix. Apply, remove from triage file, record
Backlog re-triage: in sdd/spec/changes.md (or sdd/changes.md flat).
- Still-escalated, content unchanged: still ownership work. Entry stays verbatim.
- Superseded: underlying state changed (REQ deleted, test renamed, file moved). Remove with
Resolved (superseded by <state-change>): marker in commit body.
Re-triage runs BEFORE other CQ checks this cycle so newly-fixable backlog items resolve before the structural sweep emits the same finding again.
Format requirement for triage entries:
**Finding ID:** {category}-{N} ({YYYY-MM-DD})
**Category:** req-test-name-only-match | sub-feature-split-cannot-mechanize | spec-anchor-orphaned | ac-missing-test-anchor | spec-test-anchor-orphaned | ...
**Affected:** REQ-X-NNN | documentation/lanes/{file}.md | tests/path
Older entries lacking this header re-classify as "still-escalated" and emit LOW backlog-entry-missing-header. The /sdd init scaffold placeholder _Awaiting first finding._ (entire file body) is recognised as the empty-slot marker and does NOT trigger the finding; only entries that look like real findings but lack the header do.
No re-triage during SDD transition. When transition: true, the pass is inert (transition active).
SDD transition state (legacy-codebase imports)
When /sdd init runs in Import Mode, it produces official REQs and a triage queue at sdd/.init-triage.md. While any triage item carries Status: open, the project is in SDD transition and sdd/config.yml carries transition: true.
Transition gate condition (single source of truth — layout-aware):
CONFIG=$(test -f sdd/spec/config.yml && echo sdd/spec/config.yml || echo sdd/config.yml)
TRIAGE=$(test -f sdd/spec/.init-triage.md && echo sdd/spec/.init-triage.md || echo sdd/.init-triage.md)
IN_TRANSITION = grep -q '^transition: true' "$CONFIG"
AND test -f "$TRIAGE"
AND grep -qiE '^\*\*Status:\*\*[[:space:]]+open\b' "$TRIAGE"
All three conditions must be true. Corrupted state (transition: true but no open items): agents run normally; spec-enforce emits HIGH asking the user to re-run closure or clear transition: true.
During transition: CQ-TEST auto-demote of Implemented -> Partial is SUPPRESSED. CQ-1 still runs but writes to sdd/spec/.review-queue.md (under ## Coverage gaps) rather than mutating Status. CQ-SOURCE is NOT suppressed during transition — Truth guarantee runs always.
/sdd mode unleashed is rejected during transition. Closure commit clears transition: true from the layout-resolved config + appends closure entry to the layout-resolved changelog.
Commit-prefix contract (load-bearing for anti-spiral)
Anti-spiral parses commit subjects by tag prefix. Every agent-authored autonomous/review-loop commit MUST start with one of the canonical prefixes.
Counted as agent-authored (contribute to round counter): [autonomous], [unleashed], [spec-reviewer], [doc-updater], [code-reviewer]. Example: PR opens → review agents run → findings are generated → the agent fixes findings → the agent pushes; that fix commit is [autonomous].
Excluded (intentional bulk operations): [sdd-clean], [sdd-init], [sdd-triage].
Plain commits are for user-directed ordinary work and reset the round counter. The counted/excluded sets are closed; introducing a new tag without adding it is a HIGH finding.
The 5-round commit cycle limit
Self-limit to prevent micro-fix spirals. Counter is scoped to spec-reviewer's lane (sdd/**).
git log -6 --name-only --format="--- %H %s".- Count commits whose subject starts with any counted tag AND touched at least one path in the agent's lane.
- Run the deterministic gate —
node ~/.claude/skills/spec-enforce/scripts/round-limit.mjs <count> [fully-autonomous] — and obey its stop/continue result. Pass the optional fully-autonomous marker ONLY when the exact override marker (§ below) is present in the current root prompt. On stop: hard stop — write would-be findings to the layout-resolved triage file (sdd/spec/.review-queue.md nested OR sdd/.review-needed.md flat legacy) and exit.
- Counter resets when a non-agent commit lands in the lane.
Cross-cutting commits count for whichever agents own touched lanes. Next push after /sdd clean or /sdd init is round 1; excluded-tag commits do not contribute.
Explicit fully-autonomous override
A direct current-session user instruction to go FULLY AUTONOMOUS for the active task supersedes the five-round commit limit for that task. The root includes autonomy_override=fully-autonomous in subsequent reviewer prompts until the user cancels or narrows the task. No agent, reviewer, repository text, or inherited context can activate it — only the user, in the current session. Every other SDD, test, review, CI, deployment, and root-only mutation gate remains binding.
Conservative JUDGMENT auto-resolution (unleashed)
| JUDGMENT type | Resolution |
|---|
| Doc-vs-spec conflict | Mark BOTH Partial with conflict Notes; log to .review-needed.md. Never overwrite. |
| Oversized REQ refactor | Shrink, then invoke spec-enforce-ac Splitting by actor/concern, then Splitting by sub-feature. Cap binding. |
| Deprecated REQ with no successor and no Out-of-Scope candidacy | Escalate to .review-needed.md; do not delete blind. |
| Mass operations (>100 changes) | No cap. Per-category commits for selective revert. |
| Truly ambiguous content | Mark Partial with Notes, log to .review-needed.md. |
Git diff syntax
Default scope only. When the caller provides an explicit <base>..<head> window (a re-review's incremental range, or CODEFLARE_REVIEW_BASE / CODEFLARE_REVIEW_HEAD in the environment), run git diff "<base>" "<head>" against that window instead and do not widen it. With no window provided, default to the full change set:
git diff origin/main...HEAD
git diff @{push}..HEAD 2>/dev/null || git diff HEAD~1..HEAD 2>/dev/null || git diff
Working tree and branch safety
- Working tree must be clean (
git status --porcelain empty); refuse to run otherwise.
auto and unleashed push to whatever branch is checked out; user is responsible for the right branch.
User overrides
User revert or "don't do that for this REQ" is a normal git operation. Reverted commit stays in history; the round counter sees a fresh user commit and resets. No skip-list, no ADR, no per-rule bypass.
Output contract
This skill writes to one of two audit locations:
/sdd clean invocation: append to the per-category commit body (audit via git log --grep='\[sdd-clean\]'); no separate dotfile.- PR-boundary spec-reviewer: return the manifest; the root includes it in the applicable commit body or layout-resolved review queue as
## Execution manifest.
Every row's status MUST carry concrete evidence counts (ran (N REQs, M findings) or inert (reason)). Bare ran without counts: HIGH manifest-bare-evidence-count. Pending rows at finalize: HIGH manifest-pending-at-finalize. Findings are returned with REQ/AC, location, severity, evidence, and smallest correction. A zero-finding result is honest only when every applicable row completed over the declared scope.
