chore(checks): graduate twelve checks to block and correct stale records

.github/ISSUE_TEMPLATE/bug_report.md

@@ -25,19 +25,18 @@ What you thought would happen.
 - Plugin version: <!-- e.g. 0.1.0 -->
 - Claude Code surface: <!-- CLI / Desktop / VS Code extension -->
 - Python version (if `/compile` related): <!-- python3 --version -->
-- Node version (if MCP server related): <!-- node --version -->
 - OS:
 
 ## Component
 
-- [ ] Plugin command (`/idea`, `/problem`, `/spec`, `/compile`, `/summary`)
-- [ ] Skill (product-ideation, product-flow, tech-spec, status)
-- [ ] Tech-spec subagent
+- [ ] Plugin command (`/idea`, `/problem`, `/spec`, `/compile`, `/summary`, `/optimize`)
+- [ ] Skill (product-ideation, product-flow, tech-spec, ux-optimization, status)
+- [ ] Subagent (tech-spec-writer, ux-extractor)
 - [ ] Prompt content (specify file path)
-- [ ] Compilation pipeline (`scripts/compile_spec.py`)
-- [ ] Validation pipeline (`scripts/validate_spec.py`)
-- [ ] Handoff generator (`scripts/generate_handoff.py`)
-- [ ] MCP server (`mcp/prompt-server/`)
+- [ ] Compilation pipeline (`plugin/scripts/compile_spec.py`)
+- [ ] Validation pipeline (`plugin/scripts/validate_spec.py`)
+- [ ] Handoff generator (`plugin/scripts/generate_handoff.py`)
+- [ ] Enforcement checks or hooks (`checks/`)
 - [ ] Documentation (README, CLAUDE.md, ADRs, schema)
 
 ## Output / logs

.github/pull_request_template.md

@@ -2,8 +2,8 @@
 Thanks for contributing! A few things to check before you open this PR:
 - Conventional commit prefix on the title (feat:, fix:, docs:, refactor:, perf:, test:, chore:, style:)
 - If this changes a prompt, run scripts/test-chain.md against examples/tea-tracker in a fresh Claude Code session
-- If this changes the schema, validation, or compiler, ensure scripts/validate_spec.py still passes against examples/tea-tracker/spec-package
-- If this changes anything in mcp/prompt-server/, ensure npm run typecheck and npm run build pass
+- If this changes the schema, validation, or compiler, ensure plugin/scripts/validate_spec.py still passes against examples/tea-tracker/spec-package
+- If this changes a prompt, skill, command, agent, ADR, or check, run python checks/run_checks.py --ci (blockers fail CI) and python -m unittest discover -s checks/tests
 - If this introduces an architectural decision, add or update an ADR in docs/adrs/
 -->
 
@@ -23,29 +23,29 @@ Thanks for contributing! A few things to check before you open this PR:
 
 ## Affected components
 
-- [ ] Plugin (`plugin/`) — commands, skills, subagent
-- [ ] Prompts (`prompts/dev/`)
-- [ ] Compilation pipeline (`scripts/compile_spec.py`)
-- [ ] Validation pipeline (`scripts/validate_spec.py`)
-- [ ] Handoff generator (`scripts/generate_handoff.py`)
-- [ ] MCP server (`mcp/prompt-server/`)
+- [ ] Plugin (`plugin/`) — commands, skills, subagents
+- [ ] Prompts (`plugin/prompts/`)
+- [ ] Compilation pipeline (`plugin/scripts/compile_spec.py`)
+- [ ] Validation pipeline (`plugin/scripts/validate_spec.py`)
+- [ ] Handoff generator (`plugin/scripts/generate_handoff.py`)
+- [ ] Enforcement checks and hooks (`checks/`, `.claude/settings.json`)
 - [ ] Documentation (`docs/`, `README.md`, `CLAUDE.md`)
 - [ ] CI (`.github/workflows/`)
 
 ## Test plan
 
 <!-- Markdown checklist of how you verified this. Local commands, manual walkthroughs, fixture validation. -->
 
-- [ ] `python scripts/validate_spec.py examples/tea-tracker/spec-package` still passes
-- [ ] `cd mcp/prompt-server && npm ci && npm run typecheck && npm run build` (if MCP changed)
+- [ ] `python plugin/scripts/validate_spec.py examples/tea-tracker/spec-package` still passes
+- [ ] `python checks/run_checks.py --ci` reports no blockers
 - [ ] Manual runbook walkthrough (if prompts or skills changed)
 - [ ] CI green on this PR
 
 ## ADR impact
 
 - [ ] No ADR needed
 - [ ] New ADR added: <!-- link -->
-- [ ] Existing ADR updated: <!-- link -->
+- [ ] Existing ADR amended by an appended, dated section: <!-- link -->
 
 ## Notes for reviewers
 

CHANGELOG.md

@@ -15,11 +15,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `skills-claude-ai/` — Claude.ai Agent Skill ports of product-ideation and product-flow (issue #12): bundled prompts with skill-relative paths, conversation-scoped artifact ledger with `product-dev-artifacts.md` export replacing the `.product-dev/` registry
 
 ### Changed
+- Enforcement suite: first graduation (ADR 0012 amendment, 2026-10-12). Twelve checks moved warn → block after 7+ clean days: `frontmatter-v2`, `name-uniqueness`, `body-structure`, `placeholder-syntax`, `placeholder-resolvability`, `dependency-graph`, `component-census`, `no-legacy`, `spec-fixture`, `adr-status`, `filename-convention`, `objective-parity`. Findings from these now fail CI and bounce the Stop-gate. `manifest`, `word-limit`, and `self-containment` stay at warn, with reasons in the amendment
+- ADRs 0003, 0004, 0008, 0013: appended amendments recording what later ADRs changed (the 6-command / 5-skill / 2-subagent census, registry extensions, the reverse-pass checks that had landed)
+- PR and bug-report templates, README, `scripts/README.md`, CONTRIBUTING: removed references to the deleted MCP server and to script paths that moved into `plugin/scripts/`; corrected component counts
 - PreToolUse guard (ADR 0012 amendment, 2026-10-12): appending to the end of an existing ADR is now allowed, so amendments and graduation-log entries no longer need the kill-switch; the guard also covers MultiEdit and Bash writes; rejections name moves an agent can actually take. Tests in `checks/tests/`, run in CI
 - product-ideation: the escape hatch now respects the first explicit request to move on, recording the remaining unvalidated assumptions instead of requiring a second override
 - ADR 0002: Superseded — MCP server removed; plugin is the sole delivery mechanism
 
 ### Removed
+- `docs/skills/` — eight skill specs for the pre-ADR 0004 eight-skill design, referenced by nothing
 - `mcp/prompt-server/` — MCP server (issue #13 closed as superseded; revisit triggers never fired, and ADR 0011 left it pointing at a prompt directory that no longer holds the framework library)
 
 ## [0.1.0] - 2026-04-06

CONTRIBUTING.md

@@ -157,9 +157,13 @@ claude --plugin-dir ./plugin
 When making architectural decisions:
 
 1. Create `docs/adrs/NNNN-short-title.md` (next number = highest existing + 1; check `ls docs/adrs/`)
-2. Use the existing format: Status, Context, Decision, Consequences
+2. Use the existing format: Status, Context, Decision, Consequences, Enforcement (testable consequences, the checks that verify them, and what is not machine-checkable — ADR 0012)
 3. Set status to "Proposed"
-4. Update status to "Accepted" after review
+4. The repo owner updates status to "Accepted" after review
+
+Existing ADRs are append-only. To change one, append a dated `## Amendment (YYYY-MM-DD)` section at the end of the file, or write a new ADR that supersedes it. When a new ADR amends an older one, append a note to the older one saying so. In Claude Code sessions a hook (`checks/hooks/pretooluse_guard.py`) blocks rewrites and allows appends.
+
+Run `python checks/run_checks.py --ci` before pushing. Checks at `block` fail CI; see `checks/README.md`.
 
 ## Code Style
 

README.md

@@ -81,9 +81,9 @@ Default is **Tier 1** (quick exploration, ~60 min total). The framework escalate
 ```
 ├── plugin/                            # Claude Code plugin (self-contained, installable)
 │   ├── .claude-plugin/plugin.json     # Plugin manifest
-│   ├── commands/                      # 5 commands (/idea, /problem, /spec, /compile, /summary)
-│   ├── skills/                        # 4 skills (3 workflows + status)
-│   ├── agents/                        # 1 subagent (tech-spec-writer)
+│   ├── commands/                      # 6 commands (/idea, /problem, /spec, /compile, /summary, /optimize)
+│   ├── skills/                        # 5 skills (4 workflows + status)
+│   ├── agents/                        # 2 subagents (tech-spec-writer, ux-extractor)
 │   ├── prompts/                       # Bundled prompt library
 │   │   ├── 01_ux_research/            # Prompts: phases 00-06
 │   │   ├── 02_tech_requirements/      # Tech spec prompts: 4 areas + consolidation
@@ -116,7 +116,7 @@ Default is **Tier 1** (quick exploration, ~60 min total). The framework escalate
 │
 └── docs/
     ├── spec-package-schema.md         # Spec package YAML schema (v1.0.0)
-    ├── adrs/                          # 17 Architecture Decision Records
+    ├── adrs/                          # Architecture Decision Records
     └── updates/                       # PRD v3, refactor roadmap, enhancement guides
 ```
 
@@ -140,9 +140,9 @@ Key decisions are documented as ADRs in `docs/adrs/`:
 | ADR | Decision |
 |-----|----------|
 | [0001](docs/adrs/0001-prompt-frontmatter-schema.md) | YAML frontmatter as canonical prompt metadata |
-| [0002](docs/adrs/0002-mcp-prompt-packaging.md) | MCP prompt packaging (deferred in favor of plugin) |
+| [0002](docs/adrs/0002-mcp-prompt-packaging.md) | MCP prompt packaging (superseded by ADR 0008; server removed) |
 | [0003](docs/adrs/0003-context-registry-state-management.md) | File-based context registry at `.product-dev/` |
-| [0004](docs/adrs/0004-skill-subagent-decomposition.md) | 3 skills + 1 subagent decomposition |
+| [0004](docs/adrs/0004-skill-subagent-decomposition.md) | Skill / command / subagent decomposition (amended by ADR 0013) |
 | [0005](docs/adrs/0005-prompt-enhancement-schema.md) | Prompt enhancement schema |
 | [0006](docs/adrs/0006-progressive-disclosure-tiered-engagement.md) | Progressive disclosure and tiered engagement |
 | [0007](docs/adrs/0007-json-index-deprecation.md) | JSON index deprecation |
@@ -160,7 +160,7 @@ Key decisions are documented as ADRs in `docs/adrs/`:
 ## ADR Enforcement
 
 Every ADR declares its testable consequences in an appended `## Enforcement`
-section, verified by a warn-only check suite:
+section, verified by a check suite:
 
 ```bash
 python checks/run_checks.py

checks/README.md

@@ -1,7 +1,8 @@
 # ADR Enforcement Checks
 
-Warn-only check suite verifying the testable consequences declared in each
-ADR's `## Enforcement` section. Architecture: [ADR 0012](../docs/adrs/0012-adr-enforcement-architecture.md).
+Check suite verifying the testable consequences declared in each ADR's
+`## Enforcement` section. Each check is `warn` (reported) or `block` (fails CI
+and the Stop-gate); `python checks/run_checks.py --list` shows which. Architecture: [ADR 0012](../docs/adrs/0012-adr-enforcement-architecture.md).
 
 ## Run the checks
 
@@ -43,11 +44,12 @@ Demotion (block → warn) is always allowed; log it the same three ways.
 
 ## Scope and exclusions
 
-All 91 prompts are v2 — there is no legacy scoping (ADR 0012 §6). To exempt a
+All prompts are v2 — there is no legacy scoping (ADR 0012 §6). To exempt a
 file from prompt-content checks, add its repo-relative path to the `exclude`
 array in `enforcement.config.json`. Word limits live in `word_limits.json`,
-keyed by prompt `name`; prompts absent there are reported as uncovered, not
-checked.
+keyed by prompt `name`; a prompt absent there is reported as uncovered, not
+checked. Raising a limit is a decision recorded in the owning ADR, not a
+check tweak.
 
 ## Hooks (the only blocking layer)
 

checks/enforcement.config.json

@@ -2,20 +2,20 @@
   "$schema": "enforcement-config-v1",
   "exclude": [],
   "checks": [
-    { "id": "frontmatter-v2", "adr": "0001, 0003, 0006, 0009", "tc": "0001:TC-1; 0003:TC-1; 0006:TC-1,TC-2,TC-3; 0009:TC-1", "status": "warn", "added": "2026-07-12", "graduated": null },
-    { "id": "name-uniqueness", "adr": "0009", "tc": "0009:TC-6", "status": "warn", "added": "2026-07-12", "graduated": null },
-    { "id": "body-structure", "adr": "0009", "tc": "0009:TC-2,TC-3", "status": "warn", "added": "2026-07-12", "graduated": null },
-    { "id": "placeholder-syntax", "adr": "0003, 0009", "tc": "0003:TC-2; 0009:TC-4", "status": "warn", "added": "2026-07-12", "graduated": null },
-    { "id": "placeholder-resolvability", "adr": "0003", "tc": "0003:TC-3", "status": "warn", "added": "2026-07-12", "graduated": null },
-    { "id": "dependency-graph", "adr": "0003", "tc": "0003:TC-4", "status": "warn", "added": "2026-07-12", "graduated": null },
+    { "id": "frontmatter-v2", "adr": "0001, 0003, 0006, 0009", "tc": "0001:TC-1; 0003:TC-1; 0006:TC-1,TC-2,TC-3; 0009:TC-1", "status": "block", "added": "2026-07-12", "graduated": "2026-10-12" },
+    { "id": "name-uniqueness", "adr": "0009", "tc": "0009:TC-6", "status": "block", "added": "2026-07-12", "graduated": "2026-10-12" },
+    { "id": "body-structure", "adr": "0009", "tc": "0009:TC-2,TC-3", "status": "block", "added": "2026-07-12", "graduated": "2026-10-12" },
+    { "id": "placeholder-syntax", "adr": "0003, 0009", "tc": "0003:TC-2; 0009:TC-4", "status": "block", "added": "2026-07-12", "graduated": "2026-10-12" },
+    { "id": "placeholder-resolvability", "adr": "0003", "tc": "0003:TC-3", "status": "block", "added": "2026-07-12", "graduated": "2026-10-12" },
+    { "id": "dependency-graph", "adr": "0003", "tc": "0003:TC-4", "status": "block", "added": "2026-07-12", "graduated": "2026-10-12" },
     { "id": "word-limit", "adr": "0009", "tc": "0009:TC-5", "status": "warn", "added": "2026-07-12", "graduated": null },
     { "id": "manifest", "adr": "0008", "tc": "0008:TC-1,TC-3", "status": "warn", "added": "2026-07-12", "graduated": null },
-    { "id": "component-census", "adr": "0004, 0008", "tc": "0004:TC-1,TC-2,TC-3,TC-4; 0008:TC-2", "status": "warn", "added": "2026-07-12", "graduated": null },
-    { "id": "no-legacy", "adr": "0001, 0002, 0005, 0007", "tc": "0001:TC-2; 0002:TC-1; 0005:TC-1; 0007:TC-1,TC-2", "status": "warn", "added": "2026-07-12", "graduated": null },
+    { "id": "component-census", "adr": "0004, 0008", "tc": "0004:TC-1,TC-2,TC-3,TC-4; 0008:TC-2", "status": "block", "added": "2026-07-12", "graduated": "2026-10-12" },
+    { "id": "no-legacy", "adr": "0001, 0002, 0005, 0007", "tc": "0001:TC-2; 0002:TC-1; 0005:TC-1; 0007:TC-1,TC-2", "status": "block", "added": "2026-07-12", "graduated": "2026-10-12" },
     { "id": "self-containment", "adr": "0011", "tc": "0011:TC-1,TC-2", "status": "warn", "added": "2026-07-12", "graduated": null },
-    { "id": "spec-fixture", "adr": "0010", "tc": "0010:TC-1,TC-2", "status": "warn", "added": "2026-07-12", "graduated": null },
-    { "id": "adr-status", "adr": "0002, process", "tc": "0002:TC-2; process:adr-status", "status": "warn", "added": "2026-07-12", "graduated": null },
-    { "id": "filename-convention", "adr": "CONTRIBUTING", "tc": "CONTRIBUTING:naming-convention", "status": "warn", "added": "2026-07-12", "graduated": null },
-    { "id": "objective-parity", "adr": "0014", "tc": "0014:TC-parity", "status": "warn", "added": "2026-07-25", "graduated": null }
+    { "id": "spec-fixture", "adr": "0010", "tc": "0010:TC-1,TC-2", "status": "block", "added": "2026-07-12", "graduated": "2026-10-12" },
+    { "id": "adr-status", "adr": "0002, process", "tc": "0002:TC-2; process:adr-status", "status": "block", "added": "2026-07-12", "graduated": "2026-10-12" },
+    { "id": "filename-convention", "adr": "CONTRIBUTING", "tc": "CONTRIBUTING:naming-convention", "status": "block", "added": "2026-07-12", "graduated": "2026-10-12" },
+    { "id": "objective-parity", "adr": "0014", "tc": "0014:TC-parity", "status": "block", "added": "2026-07-25", "graduated": "2026-10-12" }
   ]
 }

docs/adrs/0001-prompt-frontmatter-schema.md

@@ -124,3 +124,13 @@ every prompt in the library uses ADR 0009's minimal 7-field format
 enforced by the `frontmatter-v2` check. The still-operative core of this ADR
 is unchanged: frontmatter is the canonical prompt metadata and the JSON
 indices stay dead (ADR 0007). For the plugin runtime schema, ADR 0009 governs.
+
+---
+
+## Graduation log entry (2026-10-12)
+
+`frontmatter-v2` (TC-1) and `no-legacy` (TC-2): **warn → block**. Basis
+(ADR 0012 §5): 7+ consecutive clean days — zero findings from either check in
+every CI run since 2026-07-27. `checks/enforcement.config.json` is
+authoritative for current status; the "warn" labels in the Enforcement section
+above record the status when it was written.

docs/adrs/0002-mcp-prompt-packaging.md

@@ -80,3 +80,13 @@ Separate CLI tools (not MCP):
   - TC-2 → `checks/run_checks.py :: adr-status` (status: **warn**)
 - **Not machine-checkable:** The revisit trigger in the supersession note (editor-agnostic prompt access becoming a real need) is a judgment call, not a repo state.
 - **Graduation log:** _(empty)_
+
+---
+
+## Graduation log entry (2026-10-12)
+
+`no-legacy` (TC-1) and `adr-status` (TC-2): **warn → block**. Basis
+(ADR 0012 §5): 7+ consecutive clean days — zero findings from either check in
+every CI run since 2026-07-27. `checks/enforcement.config.json` is
+authoritative for current status; the "warn" labels in the Enforcement section
+above record the status when it was written.

docs/adrs/0003-context-registry-state-management.md

@@ -140,3 +140,33 @@ against the set of artifacts some prompt produces (typo guard) and rejects
 placeholders that are simultaneously optional and required. Canonical
 resolution rules: `plugin/docs/registry-operations.md` § Template Variable
 Resolution. (Owner-directed, part of the issue-backlog cleanup wave.)
+
+---
+
+## Amendment (2026-10-12): Later ADRs that extended this registry
+
+Recorded here so the amended ADR points at its amenders (previously only the
+amending ADRs said so):
+
+- **ADR 0013 §4** added the optional top-level `"mode"` field to
+  `context.json` (`"forward"` default | `"reverse"`) and four frontmatter
+  fields on extracted artifacts (`mode`, `provenance`, `confidence`,
+  `validation_status`). This re-introduces a `mode` field with a different
+  meaning from the one the 2026-04-04 amendment removed.
+- **ADR 0016 §3** added the `inputs` map on artifact entries (each `requires`
+  artifact name → its `version` at generation time), which makes staleness a
+  registry computation.
+- **ADR 0017 §4** added `.product-dev/learnings.jsonl` beside the registry.
+- **ADR 0011 (amendment 2026-07-25)** moved the canonical operations reference
+  to `plugin/docs/registry-operations.md`. The schema and operations table in
+  the Decision above are the design at acceptance; that file is current.
+
+## Graduation log entry (2026-10-12)
+
+`frontmatter-v2` (TC-1), `placeholder-syntax` (TC-2),
+`placeholder-resolvability` (TC-3), and `dependency-graph` (TC-4):
+**warn → block**. Basis (ADR 0012 §5): 7+ consecutive clean days — zero
+findings from any of the four in every CI run since 2026-07-27.
+`checks/enforcement.config.json` is authoritative for current status; the
+"warn" labels in the Enforcement section above record the status when it was
+written.

docs/adrs/0004-skill-subagent-decomposition.md

@@ -124,3 +124,31 @@ User invokes command (e.g., /idea)
   - TC-1, TC-2, TC-3, TC-4 → `checks/run_checks.py :: component-census` (status: **warn**)
 - **Not machine-checkable:** The planning-in-chat principle, and whether future features land in the correct mechanism (skill vs command vs subagent vs MCP tool), are design judgments.
 - **Graduation log:** _(empty)_
+
+---
+
+## Amendment (2026-10-12): Census as amended by ADR 0013
+
+ADR 0013 (2026-07-18) added the reverse pass and amended this ADR's counts,
+but this file was never updated to say so; the `component-census` check has
+enforced the amended set since that day. The census of record is:
+
+- **6 commands**: `plugin/commands/{idea,problem,spec,compile,summary,optimize}.md`
+- **5 skills** — 4 workflows plus status:
+  `plugin/skills/{product-ideation,product-flow,tech-spec,ux-optimization,status}/SKILL.md`
+- **2 subagents**: `plugin/agents/{tech-spec-writer,ux-extractor}.md`
+
+This supersedes the counts in the Decision tables ("Skills (3 total)",
+"Commands (5 total)", "Subagents (1 total)"), in Consequences, and in
+Enforcement TC-1 through TC-3 above. Those counted workflow skills only and
+predate `/optimize`. TC-4 (the status skill stays read-only) is unchanged. The
+assignment principle and the planning-in-chat principle are unchanged, and
+ADR 0013 §3 explains why the extractor subagent is consistent with them.
+
+## Graduation log entry (2026-10-12)
+
+`component-census` (TC-1 to TC-4): **warn → block**. Basis (ADR 0012 §5): 7+
+consecutive clean days — zero findings in every CI run since 2026-07-27.
+`checks/enforcement.config.json` is authoritative for current status; the
+"warn" label in the Enforcement section above records the status when it was
+written.