Spec Enforce

---
name: spec-enforce
description: SDD spec enforcement orchestrator — the canonical cross-agent contract. Runs the 24-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 24-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:

1. changed REQ/Constraints/Status/field hunks;
2. REQs whose inline `@impl` anchors target changed source symbols or files;
3. REQs whose inline `@test` anchors target changed or renamed test files/blocks;
4. dependencies, index entries, and changelog entries directly changed or required by those REQs;
5. 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)` |
| Import-triage substantive guidance | Run `node ~/.claude/skills/spec-enforce/scripts/validate-import-triage.mjs --repo <repo>` on every pass. Consume its complete JSON result and surface every finding at HIGH; a non-zero finding exit blocks an import commit. This row still runs when transition is active and when an open queue exists despite `transition: false`. | `ran (E open entries, M findings, transition=<true\|false>)` |
| Commit-prefix + 5-round limit | Mandated command, not a judgment — and an agent self-limit binding the autonomous PR-boundary loop only. Under `purpose=clean` the run is user-invoked: report `inert (purpose=clean: user-invoked)` and continue without running the gate. Otherwise run `node ~/.claude/skills/spec-enforce/scripts/round-limit.mjs --repo <repo> --lane <lane-prefix> [fully-autonomous]` — for this lane, `--lane sdd/`. It walks the last 6 commits itself, counts every subject starting with a counted tag (§ "Commit-prefix contract" — the whole closed set, NOT only this lane's own tag) that touched a lane path, closes the window at the most recent user-directed commit in the lane, and prints `counted=<n> gate=<stop\|continue>`. Report both figures verbatim and obey the verdict; never count the window or decide `stop`/`continue` yourself. | `ran (6 commits inspected, C counted, gate=<stop\|continue>, M findings)` or `inert (purpose=clean: user-invoked)` |

## Orchestration logic

1. **Parse diff.** Identify: changed REQs, changed files, changed AC bullets, REQ ID set in diff, Status field changes, `sdd/changes.md` deltas.
2. **Always-runs rows** (the 14 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, Import-triage substantive guidance, 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), Import-triage substantive guidance, and the Commit-prefix + 5-round limit row are mandated *commands*, not judgments — run the command verbatim and treat its output as the finding set; never substitute an at-a-glance read. For the round limit that means the printed `stop`/`continue` is the verdict, not a starting point for reasoning. 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.
3. **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`).
4. **Aggregate** findings from sub-skill invocations into the unified manifest. Each sub-skill returns its own evidence rows.
5. **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.
6. **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):

1. REQ has <=1 AC.
2. AC body contains a markdown link to another REQ.
3. AC body matches one of: `participates in`, `inherits`, `defined by`, `applies the policy`, `governed by`, `subject to` (case-insensitive).
4. 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:

```bash
# (1) every tracked file under sdd/spec/, plus root-level SDD support dotfiles
#     (e.g. sdd/.review-decisions.md, the /review triage-history contract),
#     must be named somewhere in sdd/README.md
for f in sdd/spec/* sdd/.*.md; do [ -f "$f" ] || continue; b=$(basename "$f"); grep -wqF -- "$b" sdd/README.md || echo "UNINDEXED: $b"; done
# (2) classification: a file carrying '### REQ-' is a domain (belongs in the Domains table);
#     a file without it is a support file (belongs in a Support section). List the domains:
grep -l '^### REQ-' sdd/spec/*.md
# (3) no dangling link: every *.md the README points at must exist
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:

```bash
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:

```bash
# case-SENSITIVE: rot markers are uppercase RESOLVED/CLOSED/FIXED, dated section
# headers, or a "## Resolved"/"## Archive" section — NOT the lowercase word "resolved"
# in an open finding's prose (a -i flag here false-positives on clean queues).
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:

1. **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).
2. **Still-escalated, content unchanged**: still ownership work. Entry stays verbatim.
3. **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)`.

## Import-triage substantive guidance

Run this executable row on every enforcement pass, independently of Backlog re-triage:

```bash
node ~/.claude/skills/spec-enforce/scripts/validate-import-triage.mjs --repo "$(git rev-parse --show-toplevel)"
```

The validator resolves flat/nested layout and transition state, then checks every open real entry in `.init-triage.md`. It runs while transition is active and also validates an open queue when configuration has drifted to `transition: false`; no queue is a successful zero-entry pass. Every entry MUST contain non-empty, substantive `Context:`, `Recommendation:`, and `Rationale:` fields. HIGH `import-triage-placeholder` fires when a normalized field is absent, only a placeholder (`TBD`, `TODO`, `unknown`, `none`, `N/A`, `later`), nonspecific boilerplate (`investigate`, `fix as needed`, `update later`), or lacks its required evidence: Context names a concrete locator, Recommendation names candidate behavior and its target, and Rationale explains why it follows from evidence. Any finding blocks the import commit until the entry is rewritten.

## 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

An **agent** self-limit to prevent micro-fix spirals. Counter is scoped to spec-reviewer's lane (`sdd/**`).

It binds the autonomous PR-boundary loop only. Under `purpose=clean` a user invoked the run, so the limit does not apply: skip this section, report `inert (purpose=clean: user-invoked)` and continue. Blocking `/sdd clean` on a spiral would withhold the remediation exactly when the spiral has happened — which is why `[sdd-clean]` is already an excluded tag.

1. Run the deterministic gate — `node ~/.claude/skills/spec-enforce/scripts/round-limit.mjs --repo <repo> --lane <lane-prefix> [fully-autonomous]`. It inspects the last 6 commits, counts every subject starting with a counted tag that touched the lane, and prints `counted=<n> gate=<stop|continue>`. Pass the optional `fully-autonomous` marker ONLY when the exact override marker (§ below) is present in the current root prompt.
2. Obey the printed verdict and report the printed count; both are the gate's output, not yours to derive. 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.
3. The window closes at the most recent non-agent commit that landed in the lane; commits older than it belong to a prior cycle. The gate applies this, so a reset needs no separate step.

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:

```bash
git diff origin/main...HEAD
# or
git diff @{push}..HEAD 2>/dev/null || git diff HEAD~1..HEAD 2>/dev/null || git diff
```

## Working tree and branch safety

1. Working tree must be clean (`git status --porcelain` empty); refuse to run otherwise.
2. `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.