docs: establish spec governance and restructure 28 specs

.claude/commands/converge.md

@@ -28,11 +28,12 @@ Cycle | Gate | Review Critical | Review Important | Regressions | Verdict
 ### Step 2: Run Cycle
 
 **A. Clear Stale State**
-Before running gates, clear the previous gate result in `.workflow/state.json`:
-1. Read the file (create `{}` if missing)
-2. Set `gates.passed` to `null`
-3. Set `gates.commit_ref` to `null`
-4. Write the file back
+Before running gates, clear the previous gate result:
+
+```bash
+python scripts/workflow-state.py set-null gates.passed
+python scripts/workflow-state.py set-null gates.commit_ref
+```
 
 This ensures that a fix cycle cannot accidentally rely on a stale gate pass.
 

.claude/commands/gates.md

@@ -118,7 +118,7 @@ Fail: snapshot mismatch — report which snapshots differ
 
 **Gate 6: AC Verification** (if specs with ACs are relevant)
 
-Read `specs/README.md` to map changed files to specs. For each relevant spec with ACs:
+To find governing specs: grep all `specs/*.md` files for `**Code:**` lines. Match changed file paths against the code path prefixes in each spec's frontmatter. For each relevant spec with ACs:
 - Extract test method names from the AC table
 - For .NET tests: `dotnet test --filter "FullyQualifiedName~{method}" -v q --no-build`
 - For TypeScript tests: `npx vitest run -t "{method}" --prefix src/PPDS.Extension`
@@ -158,11 +158,12 @@ Gates are necessary but NOT sufficient. After gates pass:
 
 ## Workflow State
 
-After all gates pass (verdict is PASS), update `.workflow/state.json`:
-1. Read the file (create `{}` if missing)
-2. Set `gates.passed` to the current ISO 8601 timestamp
-3. Set `gates.commit_ref` to current HEAD SHA (from `git rev-parse HEAD`)
-4. Write the file back
+After all gates pass (verdict is PASS), run:
+
+```bash
+python scripts/workflow-state.py set gates.passed now
+python scripts/workflow-state.py set gates.commit_ref "$(git rev-parse HEAD)"
+```
 
 ## Rules
 

.claude/commands/implement.md

@@ -29,20 +29,10 @@ Before dispatching any agents, load the specification context that will be injec
 
 **A. Read Foundation**
 - Read `specs/CONSTITUTION.md` — full content will be injected into every subagent prompt
-- Read `specs/README.md` — maps code paths to specs
 
 **B. Identify Relevant Specs**
 - From the plan, identify which source directories/files will be touched
-- Map each to its spec using the README.md code column:
-  - `src/PPDS.Dataverse/Pooling/` → `specs/connection-pooling.md`
-  - `src/PPDS.Dataverse/Query/` → `specs/query.md`
-  - `src/PPDS.Cli/Tui/` → `specs/tui.md` + `specs/tui-foundation.md`
-  - `src/PPDS.Cli/Commands/` → `specs/cli.md`
-  - `src/PPDS.Mcp/` → `specs/mcp.md`
-  - `src/PPDS.Migration/` → `specs/migration.md`
-  - `src/PPDS.Auth/` → `specs/authentication.md`
-  - `src/PPDS.Extension/src/panels/` → `specs/per-panel-environment-scoping.md` (if panels) or relevant spec
-  - `src/PPDS.Extension/` → check `specs/README.md` for extension-related specs
+- Grep all `specs/*.md` files for `**Code:**` frontmatter lines. Match each touched source directory against code path prefixes to find governing specs. This replaces hardcoded mappings and the README index.
 - Always include `specs/architecture.md`
 - Read each relevant spec and extract the `## Acceptance Criteria` section
 
@@ -62,6 +52,8 @@ with a spec or constitution principle, STOP and report the conflict
 to the orchestrator — do not silently deviate.
 ```
 
+**Note:** When creating new code paths for a spec (new directories, new files in new locations), update the spec’s `**Code:**` frontmatter to include the new paths. This ensures frontmatter grep continues to discover the correct specs.
+
 ### Step 3: Assess Current State
 - Check git status and current branch
 - Search for any existing work (worktrees, branches) related to this plan
@@ -71,13 +63,14 @@ to the orchestrator — do not silently deviate.
 
 ### Step 3.5: Initialize Workflow State
 
-Update `.workflow/state.json` to record that implementation has started:
-1. Read the file (create `{}` if missing)
-2. Set `branch` to the current branch name
-3. Set `spec` to the path of the primary spec associated with the plan
-4. Set `plan` to the plan file path ($ARGUMENTS)
-5. Set `started` to the current ISO 8601 timestamp
-6. Write the file back
+Record that implementation has started:
+
+```bash
+python scripts/workflow-state.py set branch "$(git rev-parse --abbrev-ref HEAD)"
+python scripts/workflow-state.py set spec "{spec-path}"
+python scripts/workflow-state.py set plan "$ARGUMENTS"
+python scripts/workflow-state.py set started now
+```
 
 ### Step 4: Create Task Tracking
 - Use TaskCreate to build a task list from the plan phases
@@ -198,7 +191,7 @@ If `/review` finds critical or important issues, invoke `/converge` to run the f
 3. **Parallel by default** - if tasks don't depend on each other, run them simultaneously
 4. **Sequential when required** - respect phase gates and dependency chains
 5. **One commit per phase** - each phase gate produces exactly one commit with a clear message
-6. **Review before commit** - always use code-reviewer agent before committing phase work
+6. **Review before commit** - invoke `/review` before committing phase work
 7. **Fix before advancing** - if build fails, tests fail, or review finds issues, fix them BEFORE committing. Dispatch fix agents rather than debugging yourself.
 8. **Never skip verification** - always build + test + review before declaring a phase complete
 9. **Continue until done** - execute ALL phases in the plan, don't stop early and ask permission

.claude/commands/qa.md

@@ -418,13 +418,13 @@ Present the final merged report to the user.
 
 ## Workflow State
 
-After QA passes for a surface (verdict is PASS — all checks green), update `.workflow/state.json`:
-1. Read the file (create `{}` if missing)
-2. Set `qa.{surface}` to the current ISO 8601 timestamp
-3. Surface key matches mode: `ext`, `tui`, `mcp`, `cli`
-4. Write the file back
+After QA passes for a surface (verdict is PASS — all checks green), run:
 
-Example: after `/qa extension` passes, set `qa.ext` to the timestamp.
+```bash
+python scripts/workflow-state.py set qa.{surface} now
+```
+
+Surface key matches mode: `ext`, `tui`, `mcp`, `cli`. Example: `/qa extension` → `qa.ext`.
 
 ## Rules
 

.claude/commands/reset.md

@@ -4,14 +4,13 @@ Clear workflow state for the current branch.
 
 ## Usage
 
-`/reset` — Delete `.workflow/state.json` and start fresh.
+`/reset` — Delete workflow state and start fresh.
 
 ## Process
 
-1. Check if `.workflow/state.json` exists
-2. If it exists, delete it
-3. Print confirmation: "Workflow state cleared. Run /gates to begin tracking."
-4. If it doesn't exist, print: "No workflow state to clear."
+```bash
+python scripts/workflow-state.py delete
+```
 
 ## When to Use
 

.claude/commands/review.md

@@ -28,7 +28,7 @@ If $ARGUMENTS specifies a scope, filter the diff to those paths only.
 ### Step 2: Load Spec Context (NO implementation context)
 
 - Read `specs/CONSTITUTION.md`
-- Map changed files to specs via `specs/README.md`
+- Map changed files to specs by grepping all `specs/*.md` files for `**Code:**` frontmatter lines. Match changed file paths against code path prefixes to find governing specs.
 - Read each relevant spec — extract ONLY the `## Acceptance Criteria` section
 - Do NOT read any plan files, task descriptions, or implementation notes
 
@@ -106,11 +106,14 @@ Include total counts and a clear verdict:
 
 ## Workflow State
 
-After review completes (all findings evaluated and verdict rendered), update `.workflow/state.json`:
-1. Read the file (create `{}` if missing)
-2. Set `review.passed` to the current ISO 8601 timestamp
-3. Set `review.findings` to the total count of findings (critical + important + suggestion)
-4. Write the file back
+After review completes (all findings evaluated and verdict rendered), run:
+
+```bash
+python scripts/workflow-state.py set review.passed now
+python scripts/workflow-state.py set review.findings {count}
+```
+
+Where `{count}` is the total findings (critical + important + suggestion).
 
 ## Rules
 

.claude/commands/spec-audit.md

@@ -12,7 +12,6 @@ $ARGUMENTS = spec name for single audit (e.g., `connection-pooling`), or empty f
 
 Read these files:
 - `specs/CONSTITUTION.md` — principles to check against
-- `specs/README.md` — index of all specs and their code mappings
 
 ### Step 2: Determine Scope
 
@@ -21,7 +20,7 @@ Read these files:
 - Proceed to Step 3 with this one spec
 
 **Full audit** (`$ARGUMENTS` empty):
-- Read `specs/README.md` to get list of all specs
+- Glob `specs/*.md` (excluding CONSTITUTION.md, SPEC-TEMPLATE.md, README.md) to get the list of all specs
 - For each spec, dispatch a parallel subagent (use `Agent` tool with `subagent_type: "general-purpose"`) with the audit prompt below
 - Collect all results and produce a summary
 

.claude/commands/spec.md

@@ -1,6 +1,6 @@
 # Spec
 
-Create or update a specification following PPDS conventions. Ensures consistency, cross-references related specs, and enforces numbered acceptance criteria.
+Create, update, or reconcile a specification following PPDS conventions. Three modes: forward (create new), update (modify existing), reconcile (align spec with code). Ensures consistency, cross-references related specs, and enforces numbered acceptance criteria.
 
 ## Input
 
@@ -11,34 +11,42 @@ $ARGUMENTS = spec name (e.g., `connection-pooling` for existing, `new-feature` f
 ### Step 1: Load Foundation
 
 Read these files before doing anything else:
-- `specs/CONSTITUTION.md` — non-negotiable principles
+- `specs/CONSTITUTION.md` — non-negotiable principles (includes Spec Laws SL1–SL5)
 - `specs/SPEC-TEMPLATE.md` — structural template
-- `specs/README.md` — index of all specs and their code mappings
+- Glob `specs/*.md` and grep each for `**Code:**` lines to build a code-path-to-spec map. This replaces the README index.
 
 ### Step 2: Determine Mode
 
-**If spec exists** (`specs/$ARGUMENTS.md` found):
+**Forward mode** — spec does not exist (`specs/$ARGUMENTS.md` not found):
+- Search existing specs for overlapping scope — check that this isn't already covered
+- If overlap found, ask user: update existing spec or create new one?
+- Proceed to authoring (Step 4)
+
+**Update mode** — spec exists, user requests specific changes:
 - Read the existing spec
 - Read the code files referenced in the spec's `Code:` header line
 - Identify drift: does the code match what the spec describes?
 - Identify missing ACs: does the spec have numbered acceptance criteria?
 - Present findings to user before making changes
-
-**If spec is new** (`specs/$ARGUMENTS.md` not found):
-- Search existing specs for overlapping scope — check that this isn't already covered
-- If overlap found, ask user: update existing spec or create new one?
-- Proceed to authoring
+- Proceed to authoring (Step 4)
+
+**Reconcile mode** — spec exists, user wants to align spec with code (`/spec <name> --reconcile` or when significant code divergence is detected):
+- Read the existing spec and extract all ACs, Code paths, and type descriptions
+- Read the code at the spec's `Code:` paths
+- Enumerate public types, methods, and behaviors in the code
+- Compare against existing ACs:
+  - **Missing ACs:** Code behavior with no corresponding AC → propose new ACs
+  - **Stale ACs:** AC describes behavior the code no longer has → flag for removal
+  - **Status drift:** AC references a test that now passes/fails differently → flag for update
+- **Member-count verification:** Count public types/methods in code, count ACs. Report the delta. If ACs cover less than 90% of public surface area, warn explicitly. This prevents the known LLM summarization problem (capturing ~70-80% and missing the rest).
+- Compare spec prose (Architecture, Core Requirements) against actual code structure
+- Present all proposed changes to user for approval before writing
+- After writing: regenerate README, append to Changelog
+- Skip to Step 6 (reconcile does not go through the authoring flow)
 
 ### Step 3: Cross-Reference Related Specs
 
-Based on the spec's domain, read related specs:
-- Touches `src/PPDS.Dataverse/` → read `specs/connection-pooling.md`, `specs/architecture.md`
-- Touches `src/PPDS.Cli/Tui/` → read `specs/tui.md`, `specs/tui-foundation.md`
-- Touches `src/PPDS.Cli/Commands/` → read `specs/cli.md`
-- Touches `src/PPDS.Mcp/` → read `specs/mcp.md`
-- Touches `src/PPDS.Migration/` → read `specs/migration.md`
-- Touches `src/PPDS.Auth/` → read `specs/authentication.md`
-- Always read `specs/architecture.md` for cross-cutting patterns
+Use the code-path-to-spec map from Step 1 to find related specs. Match the spec's Code: paths against the directories being touched. Always include `specs/architecture.md` and `specs/CONSTITUTION.md`.
 
 ### Step 4: Author/Update Spec
 
@@ -64,7 +72,7 @@ If the user tries to skip ACs, remind them: Constitution I3 requires numbered ac
 ### Step 6: Finalize
 
 1. Write/update the spec file at `specs/$ARGUMENTS.md`
-2. Update `specs/README.md` if this is a new spec (add to appropriate table)
+2. Regenerate `specs/README.md` by running `python scripts/generate-spec-readme.py` (or manually scraping frontmatter from all specs if the script doesn't exist yet)
 3. Commit:
    ```
    docs(specs): add/update {spec-name} specification
@@ -74,7 +82,7 @@ If the user tries to skip ACs, remind them: Constitution I3 requires numbered ac
 
 ## Rules
 
-1. **Always read foundation first** — constitution, template, README. No exceptions.
+1. **Always read foundation first** — constitution and spec template. No exceptions.
 2. **Always cross-reference** — no spec exists in isolation.
 3. **ACs are mandatory** — the spec is incomplete without them.
 4. **One section at a time** — don't dump the entire spec at once.

.claude/commands/verify.md

@@ -178,13 +178,13 @@ Present structured results:
 
 ## Workflow State
 
-After verification passes for a surface (verdict is PASS), update `.workflow/state.json`:
-1. Read the file (create `{}` if missing)
-2. Set `verify.{surface}` to the current ISO 8601 timestamp
-3. Surface key matches mode: `ext`, `tui`, `mcp`, `cli`
-4. Write the file back
+After verification passes for a surface (verdict is PASS), run:
 
-Example: after `/verify extension` passes, set `verify.ext` to the timestamp.
+```bash
+python scripts/workflow-state.py set verify.{surface} now
+```
+
+Surface key matches mode: `ext`, `tui`, `mcp`, `cli`. Example: `/verify extension` → `verify.ext`.
 
 ## Rules
 

.claude/skills/ext-panels/SKILL.md

@@ -453,7 +453,7 @@ When designing a new panel or feature, design across all four PPDS surfaces: Dae
 Read before doing anything:
 - `specs/CONSTITUTION.md` — A1, A2 govern multi-surface design (services are single code path, UI is thin wrapper)
 - `specs/architecture.md` — cross-cutting patterns
-- Domain-relevant specs via `specs/README.md`
+- Domain-relevant specs via frontmatter grep — search `specs/*.md` for `**Code:**` lines matching `src/PPDS.Extension/`
 
 ### Inventory Existing Infrastructure
 

.claude/skills/pr/SKILL.md

@@ -130,24 +130,16 @@ Awaiting your review.
 ### 6. Write Workflow State
 
 After PR is created:
-```json
-{
-  "pr": {
-    "url": "https://github.com/...",
-    "created": "2026-03-16T17:00:00Z"
-  }
-}
+
+```bash
+python scripts/workflow-state.py set pr.url "{pr-url}"
+python scripts/workflow-state.py set pr.created now
 ```
 
-After Gemini comments are triaged (step 4 complete), update workflow state:
-```json
-{
-  "pr": {
-    "url": "https://github.com/...",
-    "created": "2026-03-16T17:00:00Z",
-    "gemini_triaged": true
-  }
-}
+After Gemini comments are triaged (step 4 complete):
+
+```bash
+python scripts/workflow-state.py set pr.gemini_triaged true
 ```
 
 The stop hook will BLOCK the session from ending if `gemini_triaged` is not set after PR creation. Do not skip step 4.

.claude/skills/start/SKILL.md

@@ -52,13 +52,10 @@ git branch --list "feature/<name>"
 
 ### 5. Initialize Workflow State
 
-Write `.workflow/state.json` in the worktree:
+Initialize workflow state in the worktree:
 
-```json
-{
-  "branch": "feature/<name>",
-  "started": "<ISO 8601 timestamp>"
-}
+```bash
+python scripts/workflow-state.py init "feature/<name>"
 ```
 
 ### 6. Transfer Session Context