Pipeline integrity + brownfield adoption system

Pipeline integrity (4 fixes for snapshot-vs-live-reference problem):
- NEW docs/architecture/tr-registry.yaml: persistent stable TR-IDs per GDD
  requirement; /architecture-review bootstraps and appends, never renumbers
- /create-control-manifest: added Manifest Version stamp to header
- /create-epics-stories: stories embed TR-ID reference (not quoted text),
  Manifest Version from manifest, ADR status gate (Proposed → Blocked)
- /story-done: TR-ID registry lookup at review time, manifest staleness check
- /story-readiness: ADR Accepted check, TR-ID validity, manifest version check
- /review-all-gdds + /architecture-review: fixed parenthetical status values
  ("Needs Revision" only, no parentheticals that break exact-match reads)

Workflow infrastructure:
- NEW /help skill: context-aware "what's next" using workflow-catalog.yaml
- NEW .claude/docs/workflow-catalog.yaml: YAML-driven phase/step sequence
- /sprint-plan + /sprint-status: sprint-status.yaml machine-written tracking

Brownfield adoption system (migrate, not replace):
- NEW /adopt skill: format compliance audit (not existence check); classifies
  gaps BLOCKING/HIGH/MEDIUM/LOW; produces docs/adoption-plan-[date].md with
  numbered migration plan; never regenerates existing artifacts
- /design-system retrofit [path]: fills only missing GDD sections, preserves
  all existing content
- /architecture-decision retrofit [path]: adds missing ADR sections (Status,
  ADR Dependencies, Engine Compatibility) without touching existing content
- /start option D: split into D1 (early-stage) and D2 (has GDDs/ADRs → adopt)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Donchitos
2026-03-11 18:46:07 +11:00
parent b1cad29b68
commit 0bbf25ec31
16 changed files with 1261 additions and 32 deletions

View File

@@ -51,6 +51,27 @@ Report a count: "Loaded [N] GDDs, [M] ADRs, engine: [name + version]."
## Phase 2: Extract Technical Requirements from Every GDD
### Pre-load the TR Registry
Before extracting any requirements, read `docs/architecture/tr-registry.yaml`
if it exists. Index existing entries by `id` and by normalized `requirement`
text (lowercase, trimmed). This prevents ID renumbering across review runs.
For each requirement you extract, the matching rule is:
1. **Exact/near match** to an existing registry entry for the same system →
reuse that entry's TR-ID unchanged. Update the `requirement` text in the
registry only if the GDD wording changed (same intent, clearer phrasing) —
add a `revised: [date]` field.
2. **No match** → assign a new ID: next available `TR-[system]-NNN` for that
system, starting from the highest existing sequence + 1.
3. **Ambiguous** (partial match, intent unclear) → ask the user:
> "Does '[new requirement text]' refer to the same requirement as
> `TR-[system]-NNN: [existing text]'`, or is it a new requirement?"
User answers: "Same requirement" (reuse ID) or "New requirement" (new ID).
For any requirement with `status: deprecated` in the registry — skip it.
It was removed from the GDD intentionally.
For each GDD, read it and extract all **technical requirements** — things the
architecture must provide for the system to work. A technical requirement is any
statement that implies a specific architectural decision.
@@ -251,8 +272,11 @@ If no revision flags are found, write: "No GDD revision flags — all GDD assump
are consistent with verified engine behaviour."
Ask: "Should I flag these GDDs for revision in the systems index?"
- If yes: update the relevant systems' Status field to "Needs Revision (Architecture Feedback)"
and note the specific conflict in a comment. Ask for approval before writing.
- If yes: update the relevant systems' Status field to "Needs Revision"
and add a short inline note in the adjacent Notes/Description column explaining the conflict.
Ask for approval before writing.
(Do NOT use parentheticals like "Needs Revision (Architecture Feedback)" — other skills
match the exact string "Needs Revision" and parentheticals break that match.)
---
@@ -334,6 +358,23 @@ Ask: "May I write this review to `docs/architecture/architecture-review-[date].m
Also ask: "May I update `docs/architecture/architecture-traceability.md` with the
current matrix? This is the living index that future reviews update incrementally."
### TR Registry Update
Also ask: "May I update `docs/architecture/tr-registry.yaml` with new requirement
IDs from this review?"
If yes:
- **Append** any new TR-IDs that weren't in the registry before this review
- **Update** `requirement` text and `revised` date for any entries whose GDD
wording changed (ID stays the same)
- **Mark** `status: deprecated` for any registry entries whose GDD requirement
no longer exists (confirm with user before marking deprecated)
- **Never** renumber or delete existing entries
- Update the `last_updated` and `version` fields at the top
This ensures all future story files can reference stable TR-IDs that persist
across every subsequent architecture review.
The traceability index format:
```markdown