Reconcile doc counts to disk (SW-1)

CHANGELOG.md

@@ -26,6 +26,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   Bumps command count 10 -> 11 and agent count 5 -> 6 across docs and the validators.
 
 ### Fixed
+- Reconcile documentation counts to disk (SW-1): corrected the `README.md` `/sd:feature` gate count
+  (`4` -> `3`) and the stale command/subagent tagline (`Ten`/`five` -> `Eleven`/`six`); designated
+  `docs/architecture.md` as the authoritative inventory source (asset + gate counts) with pointer
+  comments from `README.md`, and clarified that `/sd:bug` Gate 3a is the alternative-path form of Gate 3.
 - `/sd:setup` now migrates `.claude/*` drift instead of exiting blind on a `complete` project. A
   new Phase 1.5 (drift check & migrate) runs whenever `.claude/project-config.json` or
   `.claude/settings.json` exists (states `complete` and `partial`) and rule-based-compares them

README.md

@@ -1,7 +1,7 @@
 # specwright
 
 > **Spec-driven development workflows for Claude Code.**
-> Ten slash commands, five specialized subagents, three guard-rail hooks, nine templates, six reusable skills - all under the `sd:` namespace, stack-agnostic, cross-platform, and ready to drop into any project.
+> Eleven slash commands, six specialized subagents, three guard-rail hooks, nine templates, six reusable skills - all under the `sd:` namespace, stack-agnostic, cross-platform, and ready to drop into any project.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Claude Code](https://img.shields.io/badge/Claude%20Code-compatible-blue)](https://docs.claude.com/en/docs/claude-code)
@@ -24,6 +24,8 @@ The system is **stack-agnostic**. Agents read `CLAUDE.md` and `constitution.md`
 
 ## Features
 
+<!-- Counts/gates are authoritative in docs/architecture.md. Update there first, then mirror here. -->
+
 | Capability | What you get |
 |---|---|
 | **11 slash commands** | `/sd:feature`, `/sd:bug`, `/sd:rca`, `/sd:refactor`, `/sd:perf`, `/sd:spec`, `/sd:explore`, `/sd:review`, `/sd:setup`, `/sd:release`, `/sd:adr` |
@@ -86,9 +88,11 @@ Per-project artifacts (`.specs/`, `.claude/`, project `CLAUDE.md`) remain untouc
 
 ## Commands
 
-| Command | Type | Hard gates | Purpose |
+<!-- Counts/gates are authoritative in docs/architecture.md. Update there first, then mirror here. -->
+
+| Command | Type | Gates | Purpose |
 |---|---|---|---|
-| `/sd:feature <ID-or-slug>` | Workflow | 4 | Spec-driven feature: spec -> impact -> plan -> execute -> review -> close |
+| `/sd:feature <ID-or-slug>` | Workflow | 3 | Spec-driven feature: spec -> impact -> plan -> execute -> review -> close |
 | `/sd:bug <ID-or-slug>` | Workflow | 5 | Root-cause-first fix: capture -> reproduce -> investigate -> failing test -> minimal fix -> regression |
 | `/sd:rca <slug>` | Workflow | 3 | Incident analysis. **Output is the spec - no code change.** |
 | `/sd:refactor <slug>` | Workflow | 6 | Coverage-gated restructure: requires >=80% coverage before touching code |

commands/bug.md

@@ -117,6 +117,9 @@ If the user insists on proceeding without repro, log a constitution exception to
 Reached ONLY when the loop ends with no CONFIRMED hypothesis. STOP. Do NOT proceed to a fix - a fix on an
 unconfirmed root cause risks treating a symptom.
 
+> Gate 3a is the alternative-path form of Gate 3; the workflow reaches one or the other, never both, so
+> the gate count is 5.
+
 Append the exhausted tree (every hypothesis with its REJECTED / INCONCLUSIVE verdict and reasoning) to
 `.specs/BUG-<arg>/03-decisions.md` - this is the knowledge record for the next investigation.
 

docs/architecture.md

@@ -6,6 +6,8 @@ specwright is a thin layer on top of Claude Code that enforces spec-driven devel
 
 ## Three-layer architecture
 
+<!-- AUTHORITATIVE asset counts. Update here first; README derives from this. -->
+
 ```
 +--------------------------------------------------------------------+
 |  Layer 1 - USER scope  (~/.claude/, installed once)                |
@@ -69,6 +71,8 @@ A **gate** is a checkpoint where the workflow refuses to proceed without explici
 
 The 5 workflow commands have these gate counts:
 
+<!-- AUTHORITATIVE gate counts. Update here first; README derives from this. -->
+
 | Workflow | Gates | Why |
 |---|---|---|
 | `/sd:feature` | 3 | spec, plan, per-task review, integration |