maestro-flow 0.3.11 → 0.3.13

package/.codex/skills/manage-wiki/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: manage-wiki
+description: Wiki knowledge graph management — health dashboard, orphan cleanup, entry search, and graph statistics
+argument-hint: "[health|search|cleanup|stats] [options]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Unified wiki graph management. Health monitoring, interactive search, orphan cleanup, and graph statistics. Day-to-day operations to keep the knowledge graph healthy.
+
+Complements `wiki-connect` (link discovery) and `wiki-digest` (synthesis) with operational tooling.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/wiki-manage.md
+</required_reading>
+
+<context>
+$ARGUMENTS — subcommand and optional flags.
+
+**Subcommands:**
+| Subcommand | Description |
+|-----------|-------------|
+| `health` | Health dashboard — score, broken links, orphans, hubs (default) |
+| `search <query>` | Interactive BM25 search with follow-up actions |
+| `cleanup` | Find and resolve orphans, broken links, stale entries |
+| `stats` | Graph statistics — type distribution, tag frequency, growth |
+
+**Flags:**
+- `--type <type>` — Filter: spec, memory, note, lesson, issue
+- `--fix` — Auto-fix issues during cleanup
+- `--json` — JSON output
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/wiki-manage.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | fatal | `.workflow/` not initialized |
+| E002 | fatal | No wiki entries found |
+| E003 | error | Invalid subcommand |
+| W001 | warning | Health score below 50 |
+| W002 | warning | Cleanup had partial failures |
+</error_codes>
+
+<success_criteria>
+- [ ] Subcommand parsed (health/search/cleanup/stats)
+- [ ] Wiki data loaded via `maestro wiki` CLI
+- [ ] Results displayed in formatted output
+- [ ] If cleanup --fix: issues resolved and delta reported
+- [ ] Next-step suggestions provided
+</success_criteria>

package/.codex/skills/quality-business-test/SKILL.md

@@ -51,7 +51,7 @@ $quality-business-test "3 --auto"                   # skip plan confirmation
 
 `--auto` skips interactive confirmation of test plan. `--dry-run` extracts scenarios only without execution.
 
-**Output**: `{phase_dir}/.tests/business/business-test-plan.json` + `business-test-report.json` + `business-test-summary.md`
+**Output**: `{artifact_dir}/.tests/business/business-test-plan.json` + `business-test-report.json` + `business-test-summary.md`
 </context>
 
 <invariants>
@@ -71,8 +71,9 @@ $quality-business-test "3 --auto"                   # skip plan confirmation
 ### Step 1: Resolve Target & Load Spec Package
 
 1. Parse `$ARGUMENTS` for phase number and flags
-2. Set `PHASE_DIR = .workflow/phases/{NN}-{slug}/`
-3. Load `index.json` -> find `spec_ref` -> locate `.workflow/.spec/SPEC-xxx/`
+2. Resolve `PHASE_DIR` via artifact registry in `state.json` to `.workflow/scratch/{YYYYMMDD}-{type}-{slug}/`
+3. **Related session discovery**: Query `state.json.artifacts[]` for all artifacts matching `phase === target_phase && milestone === current_milestone`. Each artifact's type determines its outputs: review → review.json (findings inform which business rules need extra scrutiny), debug → understanding.md (root causes map to specific requirement failures), test → uat.md (prior UAT gaps identify untested business scenarios). Extract conclusions that may affect business test scenario priorities.
+4. Load `index.json` -> find `spec_ref` -> locate `.workflow/.spec/SPEC-xxx/`
 4. **Full mode**: Read `requirements/_index.md` + all `REQ-*.md` + `NFR-*.md` + `architecture/_index.md` + `epics/EPIC-*.md`
 5. **Degraded mode** (no spec package): Read `index.json.success_criteria` + `plan.json` convergence criteria + `.summaries/TASK-*.md`
 6. If `--re-run`: load previous `business-test-report.json`, filter to failed/blocked scenarios
@@ -129,7 +130,7 @@ Three tiers:
 
 ### Step 5: Generate Test Code (if --gen-code)
 
-Detect project tech stack from `.workflow/specs/project-tech.json` or codebase scan.
+Detect project tech stack from `.workflow/project.md` Tech Stack section or codebase scan.
 
 | Stack | L1 | L2 | L3 |
 |-------|----|----|-----|
@@ -190,7 +191,8 @@ FOR each REQ:
 
 1. Auto-create issues from failures in `.workflow/issues/issues.jsonl` (each with `req_ref`, `source: "business-test"`)
 2. Report results
-3. Route next step:
+3. **Register artifact**: Append to `state.json.artifacts[]` with `type: "test"`, `id: TST-NNN`, `path: "scratch/{YYYYMMDD}-business-test-P{N}-{slug}"`, `depends_on: exec_art.id`.
+4. Route next step:
 
 | Result | Suggestion |
 |--------|------------|
@@ -206,7 +208,7 @@ FOR each REQ:
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|
 | E001 | error | Phase number required | Prompt user for phase number |
-| E002 | error | Phase directory not found | Verify phase exists in .workflow/phases/ |
+| E002 | error | Phase directory not found | Resolve via state.json artifact registry |
 | E003 | error | No spec package AND no success_criteria | Run maestro-spec-generate or maestro-plan first |
 | E004 | error | L1 critical failures block L2/L3 | Fix blockers via quality-debug |
 | W001 | warning | Degraded mode (no spec package) | Consider running maestro-spec-generate |

package/.codex/skills/quality-debug/SKILL.md

@@ -52,7 +52,7 @@ Wave-based hypothesis-driven debugging using `spawn_agents_on_csv`. Wave 1 explo
 $quality-debug "Login button throws 500 error on click"
 $quality-debug -y "JWT token not refreshed --from-uat 3"
 $quality-debug -c 4 "Navigation crash --from-uat 3 --parallel"
-$quality-debug --continue "debug-jwt-expiry-20260318"
+$quality-debug --continue "20260318-debug-P3-jwt-expiry"
 ```
 
 **Flags**:
@@ -115,7 +115,7 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column.
 ### Session Structure
 
 ```
-.workflow/.csv-wave/debug-{slug}-{date}/
+.workflow/.csv-wave/{YYYYMMDD}-debug-P{N}-{slug}/
 +-- tasks.csv
 +-- results.csv
 +-- discoveries.ndjson
@@ -159,7 +159,7 @@ const bugDescription = $ARGUMENTS
 
 const slug = bugDescription.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40)
 const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
-const sessionId = `debug-${slug}-${dateStr}`
+const sessionId = fromUatMatch ? `${dateStr}-debug-P${fromUatMatch[1]}-${slug}` : `${dateStr}-debug-${slug}`
 const sessionFolder = `.workflow/.csv-wave/${sessionId}`
 
 Bash(`mkdir -p ${sessionFolder}`)
@@ -179,13 +179,15 @@ Bash(`mkdir -p ${sessionFolder}`)
 | `--parallel` flag present | parallel (implies from-uat, one agent per gap cluster) |
 | Neither flag | standalone (gather symptoms interactively) |
 
-2. **Symptom collection**:
+2. **Related session discovery**: Query `state.json.artifacts[]` for all artifacts matching `phase === target_phase && milestone === current_milestone`. Each artifact's type determines its outputs: execute → .summaries/.task/, review → review.json (findings guide hypothesis formation), debug → understanding.md (avoid re-investigation), test → uat.md. Extract conclusions that may affect this debug session.
+
+3. **Symptom collection**:
 
 | Mode | Source | Action |
 |------|--------|--------|
 | standalone | User input | Ask 5 questions: expected, actual, errors, timeline, reproduction |
-| from-uat | `{phase_dir}/uat.md` | Parse Gaps section, cluster by component |
-| parallel | `{phase_dir}/uat.md` | Same as from-uat, one investigation per cluster |
+| from-uat | test artifact's uat.md (via registry) | Parse Gaps section, cluster by component |
+| parallel | test artifact's uat.md (via registry) | Same as from-uat, one investigation per cluster |
 
 3. **Hypothesis generation**: For each symptom cluster or bug description:
    - Analyze code patterns around affected area
@@ -322,12 +324,23 @@ spawn_agents_on_csv({
 ```
 
 4. **UAT update** (if --from-uat): For each confirmed hypothesis with fix:
-   - Update `{phase_dir}/uat.md` gaps with `root_cause`, `fix_direction`, `affected_files`
+   - Update `{artifact_dir}/uat.md` gaps with `root_cause`, `fix_direction`, `affected_files`
 
 5. **Issue update**: If `.workflow/issues/issues.jsonl` exists:
    - Update matching issues with status `diagnosed`, add `context.suggested_fix` and `context.notes`
 
-6. **Next step routing**:
+6. **Register artifact** (phase-scoped only): Append to `state.json.artifacts[]` with `type: "debug"`, `id: DBG-NNN`, `path: "scratch/{YYYYMMDD}-debug-P{N}-{slug}"`, `depends_on: triggering_review_id || exec_art.id`. Output directory is independent scratch.
+
+7. **Post-debug Knowledge Inquiry** (after root causes confirmed):
+   - **Recurring pattern**: If root cause matches a recurring pattern (similar to prior debug sessions):
+     → Ask: "This root cause pattern has appeared before. Should it be documented in `debug-notes.md` to prevent recurrence? (`/spec-add debug`)"
+   - **Non-obvious fix**: If fix involved a non-obvious approach or workaround:
+     → Ask: "This fix used a non-obvious strategy. Should it be recorded as a learning? (`/spec-add learning`)"
+   - **Architectural gap**: If root cause traces to architectural boundary violation or missing constraint:
+     → Ask: "Root cause points to an architectural gap. Should `architecture-constraints.md` be updated? (`/spec-add arch`)"
+   - If user confirms, append `<spec-entry>` to matching category file via `spec-add` mechanism
+
+8. **Next step routing**:
 
 | Result | Suggestion |
 |--------|------------|
@@ -337,7 +350,7 @@ spawn_agents_on_csv({
 | All inconclusive | Resume with more context or manual investigation |
 | From UAT, all diagnosed | `Skill({ skill: "quality-test", args: "{phase} --auto-fix" })` |
 
-7. Display summary.
+9. Display summary.
 
 ### Shared Discovery Board Protocol
 

package/.codex/skills/quality-integration-test/SKILL.md

@@ -62,7 +62,7 @@ Linear pipeline test execution using `spawn_agents_on_csv`. Progressive L0 -> L1
 $quality-integration-test "3"
 $quality-integration-test -c 4 "3 --max-iterations 8"
 $quality-integration-test -y "3 --target-coverage 90"
-$quality-integration-test --continue "integration-test-phase3-20260318"
+$quality-integration-test --continue "20260318-integration-test-P3-auth"
 ```
 
 **Flags**:
@@ -129,7 +129,7 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column populated fr
 ### Session Structure
 
 ```
-.workflow/.csv-wave/integration-test-{phase}-{date}/
+.workflow/.csv-wave/{YYYYMMDD}-integration-test-P{N}-{slug}/
 +-- tasks.csv
 +-- results.csv
 +-- discoveries.ndjson
@@ -183,7 +183,7 @@ const phaseArg = $ARGUMENTS
   .trim()
 
 const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
-const sessionId = `integration-test-phase${phaseArg}-${dateStr}`
+const sessionId = `${dateStr}-integration-test-P${phaseArg}-${phaseSlug}`  // phaseSlug from index.json or roadmap
 const sessionFolder = `.workflow/.csv-wave/${sessionId}`
 
 Bash(`mkdir -p ${sessionFolder}`)
@@ -213,9 +213,11 @@ Write(`${sessionFolder}/reflection-log.md`,
 
 **Decomposition Rules**:
 
-1. **Phase resolution**: Resolve `{phaseArg}` to `.workflow/phases/{NN}-{slug}/`
+1. **Phase resolution**: Resolve `{phaseArg}` via artifact registry in `state.json` to `.workflow/scratch/{YYYYMMDD}-{type}-{slug}/`
 
-2. **Codebase exploration**:
+2. **Related session discovery**: Query `state.json.artifacts[]` for all artifacts matching `phase === target_phase && milestone === current_milestone`. Each artifact's type determines its outputs: review → review.json (critical findings inform integration test focus), debug → understanding.md (root causes guide regression test layers), test → uat.md/.tests/ (prior results inform layer priorities). Extract conclusions that may affect integration test strategy.
+
+3. **Codebase exploration**:
    - Cross-module imports and dependencies
    - API endpoints and route definitions
    - Database interactions and queries
@@ -228,7 +230,7 @@ Write(`${sessionFolder}/reflection-log.md`,
    - Identify test utilities, fixtures, DB seed scripts
 
 4. **Pre-generated test loading**:
-   Check `{phase_dir}/.tests/test-gen-report.json` for tests from `quality-test-gen`. Merge integration/e2e tests into plan (execute but don't re-generate).
+   Check `{artifact_dir}/.tests/test-gen-report.json` for tests from `quality-test-gen`. Merge integration/e2e tests into plan (execute but don't re-generate).
 
 5. **Layer design**:
 
@@ -455,7 +457,9 @@ Update `state.json` with new strategy and iteration count.
 
 6. Update `index.json` with integration test status.
 
-7. Display summary.
+7. **Register artifact**: Append to `state.json.artifacts[]` with `type: "test"`, `id: TST-NNN`, `path: "scratch/{YYYYMMDD}-integration-test-P{N}-{slug}"`, `depends_on: exec_art.id`. Output directory is independent scratch.
+
+8. Display summary.
 
 **Next step routing**:
 

package/.codex/skills/quality-retrospective/SKILL.md

@@ -66,18 +66,27 @@ $quality-retrospective "3 --compare 2 --auto-yes"
 When `--auto-yes`: Accept all routing recommendations without prompting. Route all insights automatically.
 
 **Storage written**:
-- `.workflow/phases/{NN}-{slug}/retrospective.md` -- human-readable record
-- `.workflow/phases/{NN}-{slug}/retrospective.json` -- structured record
-- `.workflow/specs/SPEC-retro-*.md` -- spec stubs (one per spec-routed insight)
+- `{target_dir}/retrospective.md` -- human-readable record (target_dir resolved via state.json artifact registry to `.workflow/scratch/{YYYYMMDD}-{type}-{slug}/`)
+- `{target_dir}/retrospective.json` -- structured record
+- `.workflow/specs/{category-file}.md` -- `<spec-entry>` entries appended to matching category files (one per spec-routed insight)
 - `.workflow/issues/issues.jsonl` -- appended issue rows (`source: "retrospective"`)
 - `.workflow/memory/TIP-*.md` -- memory tips (via `manage-memory-capture` skill)
 - `.workflow/learning/lessons.jsonl` -- append-only insight log
 - `.workflow/learning/learning-index.json` -- updated searchable index
 
-**Storage read (never modified)**:
-- `.workflow/phases/{NN}-{slug}/index.json`, `plan.json`, `verification.json`, `review.json`, `uat.md`
-- `.workflow/phases/{NN}-{slug}/.task/TASK-*.json`, `.summaries/TASK-*-summary.md`
-- `.workflow/issues/issues.jsonl`, `.workflow/state.json`
+**Storage read (never modified)** — all resolved via `state.json.artifacts[]`:
+```
+related = artifacts.filter(a =>
+  a.phase === target_phase && a.milestone === current_milestone
+).sort_by(completed_at asc)
+```
+Each artifact's type determines its outputs at `.workflow/{a.path}/`:
+- **execute** → index.json, plan.json, .task/TASK-*.json, .summaries/TASK-*-summary.md
+- **verify** → verification.json
+- **review** → review.json (findings, verdict, severity distribution)
+- **debug** → understanding.md, evidence.ndjson (root causes, fix directions)
+- **test** → uat.md, .tests/ (UAT results, gaps, coverage)
+- Also reads: `.workflow/issues/issues.jsonl`, `.workflow/state.json`
 
 ### Agent Registry
 
@@ -151,7 +160,7 @@ functions.update_plan({
 Validate `--lens` values. If `--compare <M>` present, require single mode.
 
 **Stage 2: Validate phase artifacts**. For each target phase:
-- Phase directory `.workflow/phases/{NN}-{slug}/` must exist
+- Phase directory must exist (resolved via state.json artifact registry to `.workflow/scratch/{YYYYMMDD}-{type}-{slug}/`)
 - `index.json` must show `status: "completed"`
 - `.task/` directory must exist with at least one `TASK-*.json`
 - If existing `retrospective.json` found and not `--all`: emit W002, prompt overwrite
@@ -175,7 +184,7 @@ functions.update_plan({
 ### Stage 4: Context-Agent Fork + Parallel Lens Analysis
 
 **Archive if overwriting**:
-If existing `retrospective.{md,json}` present, move to `{phase_dir}/.history/` with timestamp suffix before spawning.
+If existing `retrospective.{md,json}` present, move to `{artifact_dir}/.history/` with timestamp suffix before spawning.
 
 **Step 4a: Spawn context agent**
 ```javascript
@@ -190,13 +199,18 @@ spawn_agent({
 ---
 
 Goal: Load and summarize all phase artifacts for retrospective analysis.
-Phase: ${phaseDir}
+Phase: ${targetPhase}
 
 TASK:
-1. Read ${phaseDir}/index.json, plan.json, verification.json, review.json, uat.md
-2. Read all .task/TASK-*.json and .summaries/TASK-*-summary.md
+1. Read .workflow/state.json -- query artifacts[] for all entries matching phase === ${targetPhase} && milestone === current_milestone
+2. For each artifact, load outputs from .workflow/{artifact.path}/:
+   - execute artifacts → index.json, plan.json, .task/TASK-*.json, .summaries/TASK-*-summary.md
+   - verify artifacts → verification.json
+   - review artifacts → review.json (findings, verdict, severity distribution)
+   - debug artifacts → understanding.md, evidence.ndjson (root causes, fix directions)
+   - test artifacts → uat.md, .tests/ (UAT results, gaps, coverage)
 3. Read .workflow/issues/issues.jsonl -- filter rows with phase link to this phase
-4. Read .workflow/state.json for project context
+4. Read .workflow/state.json for project context (milestones, accumulated_context)
 
 EXPECTED: Comprehensive artifact summary covering:
 - Phase goals and outcomes (from plan.json vs verification.json)
@@ -357,18 +371,21 @@ If `--no-route`: skip this stage.
 For each insight in `synthResult.insights`, route based on `routing` field:
 
 **Spec routing** (`routing: "spec"`):
-```javascript
-functions.apply_patch:
-*** Begin Patch
-*** Add File: .workflow/specs/SPEC-retro-<INS-id>.md
-+---
-+id: <INS-id>
-+source: retrospective
-+phase: <N>
-+category: <category>
-+---
-+
-+# <title>
+
+Map insight type to spec category: pattern/convention → `coding`, architecture → `arch`, quality → `quality`.
+Append `<spec-entry>` to matching category file:
+
+```markdown
+<spec-entry category="{category}" keywords="{auto-extracted}" date="{YYYY-MM-DD}" source="retrospective">
+
+### <title>
+
+<summary>
+
+**Evidence:** <evidence_refs>
+**Phase:** <N> | **Lens:** <lens> | **Insight:** <INS-id>
+
+</spec-entry>
 +
 +<summary>
 +
@@ -404,7 +421,7 @@ If `!AUTO_YES`: present routing table and ask confirmation before routing each g
 ```javascript
 functions.apply_patch:
 *** Begin Patch
-*** Add File: .workflow/phases/<NN>-<slug>/retrospective.json
+*** Add File: <target_dir>/retrospective.json
 +{
 +  "phase": <N>,
 +  "phase_slug": "<slug>",
@@ -415,7 +432,7 @@ functions.apply_patch:
 +  "distilled_insights": <insights_array>,
 +  "routing_summary": <routing_summary>
 +}
-*** Add File: .workflow/phases/<NN>-<slug>/retrospective.md
+*** Add File: <target_dir>/retrospective.md
 +# Retrospective: Phase <N> -- <slug>
 +
 +> Generated: <ISO> | Lenses: technical, process, quality, decision
@@ -441,7 +458,7 @@ functions.apply_patch:
 
 Append each insight to `.workflow/learning/lessons.jsonl` and update `learning-index.json`.
 
-If `.workflow/specs/learnings.md` already exists, append a one-line summary per insight (never create it).
+If `.workflow/specs/learnings.md` already exists, append each insight using `<spec-entry>` closed-tag format (category=`learning`, auto-extract keywords, date=today, source=`retrospective`). Never create the file — only append if it exists.
 
 ```javascript
 functions.update_plan({
@@ -466,7 +483,7 @@ Lenses:   technical, process, quality, decision
 Insights: <total> (<N> new, <N> duplicates merged)
 
 ROUTING:
-  Spec stubs:   <N>  -> .workflow/specs/SPEC-retro-*.md
+  Spec entries:  <N>  -> .workflow/specs/{category-file}.md
   Issues:       <N>  -> .workflow/issues/issues.jsonl
   Memory tips:  <N>  -> .workflow/memory/TIP-*.md
   Lessons:      <N>  -> .workflow/learning/lessons.jsonl
@@ -480,6 +497,8 @@ Next:
   $manage-status
   $manage-issue "list --source retrospective"
   $manage-learn "list --phase <N>"
+  $manage-wiki health
+  $wiki-digest "<phase-topic>"
 ```
 </execution>
 

package/.codex/skills/quality-review/SKILL.md

@@ -52,7 +52,7 @@ Wave-based multi-dimensional code review using `spawn_agents_on_csv`. Decomposes
 $quality-review "3"
 $quality-review -c 6 "3 --level deep"
 $quality-review -y "3 --dimensions security,performance"
-$quality-review --continue "review-phase3-20260318"
+$quality-review --continue "20260318-review-P3-auth"
 ```
 
 **Flags**:
@@ -119,7 +119,7 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column.
 ### Session Structure
 
 ```
-.workflow/.csv-wave/review-{phase}-{date}/
+.workflow/.csv-wave/{YYYYMMDD}-review-P{N}-{slug}/
 +-- tasks.csv
 +-- results.csv
 +-- discoveries.ndjson
@@ -163,7 +163,7 @@ const phaseArg = $ARGUMENTS
   .trim()
 
 const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
-const sessionId = `review-phase${phaseArg}-${dateStr}`
+const sessionId = `${dateStr}-review-P${phaseArg}-${phaseSlug}`  // phaseSlug from index.json or roadmap
 const sessionFolder = `.workflow/.csv-wave/${sessionId}`
 
 Bash(`mkdir -p ${sessionFolder}`)
@@ -175,8 +175,9 @@ Bash(`mkdir -p ${sessionFolder}`)
 
 **Decomposition Rules**:
 
-1. **Phase resolution**: Resolve `{phaseArg}` to `.workflow/phases/{NN}-{slug}/`
-2. **File collection**: Read `.task/TASK-*.json` -> collect all `files[].path` where action != "read"
+1. **Phase resolution**: Resolve `{phaseArg}` via artifact registry in `state.json` to `.workflow/scratch/{YYYYMMDD}-{type}-{slug}/`
+2. **Related session discovery**: Query `state.json.artifacts[]` for all artifacts matching `phase === target_phase && milestone === current_milestone`. Each artifact's type determines its outputs: execute → .summaries/.task/, review → review.json, debug → understanding.md, test → uat.md. Extract conclusions that may affect this review (prior verdicts, root causes, UAT gaps) and pass as prior quality context to reviewer agents.
+3. **File collection**: Read `.task/TASK-*.json` -> collect all `files[].path` where action != "read"
 3. **Level detection**:
 
 | Condition | Level |
@@ -332,9 +333,11 @@ spawn_agents_on_csv({
 | standard | critical + high |
 | deep | critical + high + medium |
 
-7. **Phase index update**: Update `.workflow/phases/{phase}/index.json` with review status.
+7. **Phase index update**: Update `{artifact_dir}/index.json` with review status.
 
-8. Display summary.
+8. **Register artifact**: Append to `state.json.artifacts[]` with `type: "review"`, `id: REV-NNN`, `path: "scratch/{YYYYMMDD}-review-P{N}-{slug}"`, `depends_on: exec_art.id`. Output directory is independent scratch, not shared with plan.
+
+9. Display summary.
 
 ### Shared Discovery Board Protocol
 

package/.codex/skills/quality-test/SKILL.md

@@ -49,15 +49,15 @@ No auto mode -- UAT is inherently interactive. `--auto-fix` only automates gap c
 ### Step 1: Resolve Target
 
 1. Parse `$ARGUMENTS` for phase number, scratch task ID, or flags
-2. **Phase mode**: set `PHASE_DIR = .workflow/phases/{NN}-{slug}/`
+2. **Phase mode**: resolve `PHASE_DIR` via artifact registry in `state.json` to `.workflow/scratch/{YYYYMMDD}-{type}-{slug}/`
 3. **Scratch mode**: set `SCRATCH_DIR = .workflow/scratch/{id}/`
 4. Validate target exists and has `verification.json` -- if missing: **E002**
 
 ### Step 2: Check Active Sessions
 
 ```bash
-find .workflow/phases -name "uat.md" -type f 2>/dev/null | head -5
 find .workflow/scratch -name "uat.md" -type f 2>/dev/null | head -5
+find .workflow/phases -name "uat.md" -type f 2>/dev/null | head -5
 ```
 
 - If active sessions exist and no target specified: display session table, ask user to resume or start new
@@ -71,7 +71,11 @@ If any smoke fails: **E003** -- abort, suggest Skill({ skill: "quality-debug" })
 
 ### Step 4: Load Verification Context
 
-Read from target directory: verification.json, validation.json, index.json, plan.json, `.summaries/TASK-*.md`. Build testable list from user-observable outcomes.
+Read from target directory (resolved via artifact registry): verification.json, validation.json, index.json, plan.json, `.summaries/TASK-*.md`. Build testable list from user-observable outcomes.
+
+### Step 4.5: Load Quality Context
+
+Query `state.json.artifacts[]` for all artifacts matching `phase === target_phase && milestone === current_milestone`. Each artifact's type determines its outputs: review → review.json (findings become additional test scenarios), debug → understanding.md (confirmed root causes become regression tests). Extract conclusions that may affect test scenario design.
 
 ### Step 5: Design Test Scenarios
 
@@ -132,8 +136,9 @@ Read `uat.md`, find first `result: [pending]` test, announce progress, continue
 2. Archive previous result artifacts to `.history/`
 3. Write `.tests/test-results.json` and `.tests/coverage-report.json`
 4. Update `index.json` with UAT results
-5. If no issues: go to Step 13
-6. If issues found: go to Step 11
+5. **Register artifact**: Append to `state.json.artifacts[]` with `type: "test"`, `id: TST-NNN`, `path: "scratch/{YYYYMMDD}-test-P{N}-{slug}"`, `depends_on: exec_art.id`. Output directory is independent scratch.
+6. If no issues: go to Step 13
+7. If issues found: go to Step 11
 
 ### Step 11: Auto-Diagnose
 

package/.codex/skills/quality-test-gen/SKILL.md

@@ -49,7 +49,7 @@ Wave-based test generation using `spawn_agents_on_csv`. Each source file/module
 $quality-test-gen "3"
 $quality-test-gen -c 4 "3 --type unit"
 $quality-test-gen -y "3 --type e2e --framework vitest"
-$quality-test-gen --continue "test-gen-phase3-20260318"
+$quality-test-gen --continue "20260318-testgen-P3-auth"
 ```
 
 **Flags**:
@@ -113,7 +113,7 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column (empty for w
 ### Session Structure
 
 ```
-.workflow/.csv-wave/test-gen-{phase}-{date}/
+.workflow/.csv-wave/{YYYYMMDD}-testgen-P{N}-{slug}/
 +-- tasks.csv
 +-- results.csv
 +-- discoveries.ndjson
@@ -158,7 +158,7 @@ const phaseArg = $ARGUMENTS
   .trim()
 
 const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
-const sessionId = `test-gen-phase${phaseArg}-${dateStr}`
+const sessionId = `${dateStr}-testgen-P${phaseArg}-${phaseSlug}`  // phaseSlug from index.json or roadmap
 const sessionFolder = `.workflow/.csv-wave/${sessionId}`
 
 Bash(`mkdir -p ${sessionFolder}`)
@@ -170,9 +170,11 @@ Bash(`mkdir -p ${sessionFolder}`)
 
 **Decomposition Rules**:
 
-1. **Phase resolution**: Resolve `{phaseArg}` to `.workflow/phases/{NN}-{slug}/`
+1. **Phase resolution**: Resolve `{phaseArg}` via artifact registry in `state.json` to `.workflow/scratch/{YYYYMMDD}-{type}-{slug}/`
 
-2. **Test infrastructure discovery**:
+2. **Related session discovery**: Query `state.json.artifacts[]` for all artifacts matching `phase === target_phase && milestone === current_milestone`. Each artifact's type determines its outputs: review → review.json (critical findings become focused test targets), debug → understanding.md (confirmed root causes become regression test targets), test → uat.md (UAT gaps inform which behaviors need tests). Extract conclusions that may affect test generation priorities.
+
+3. **Test infrastructure discovery**:
    - Find config files: `jest.config.*`, `vitest.config.*`, `pytest.ini`, `.mocharc.*`
    - Find existing test files: `*.test.*`, `*.spec.*`, `test_*`
    - Find test utilities: `test-utils.*`, `testHelper*`, `conftest.py`
@@ -277,9 +279,9 @@ Each agent receives:
 
 4. **Archive previous artifacts** before writing:
    ```
-   IF file exists "{phase_dir}/.tests/test-gen-report.json":
-     mkdir -p "{phase_dir}/.history"
-     mv to "{phase_dir}/.history/test-gen-report-{TIMESTAMP}.json"
+   IF file exists "{artifact_dir}/.tests/test-gen-report.json":
+     mkdir -p "{artifact_dir}/.history"
+     mv to "{artifact_dir}/.history/test-gen-report-{TIMESTAMP}.json"
    ```
 
 5. Build `test-gen-report.json`:
@@ -362,7 +364,9 @@ Each agent receives:
 
 8. Copy `test-gen-report.json` to phase `.tests/` directory.
 
-9. Display summary.
+9. **Register artifact**: Append to `state.json.artifacts[]` with `type: "test"`, `id: TST-NNN`, `path: "scratch/{YYYYMMDD}-testgen-P{N}-{slug}"`, `depends_on: exec_art.id`. Output directory is independent scratch.
+
+10. Display summary.
 
 **Next step routing**:
 

package/.codex/skills/spec-add/SKILL.md

@@ -15,7 +15,7 @@ $spec-add "arch Use Zod for runtime validation over io-ts"
 $spec-add "quality All API endpoints must return structured error objects"
 ```
 
-**Valid categories**: coding, arch, quality, debug, test, review, learning.
+**Valid categories**: coding, arch, quality, debug, test, review, learning, bug, pattern, decision, rule, validation.
 </purpose>
 
 <context>
@@ -31,6 +31,13 @@ $ARGUMENTS — `<category> <content>` where category selects the target file.
 | `test` | `test-conventions.md` |
 | `review` | `review-standards.md` |
 | `learning` | `learnings.md` |
+| `bug` | `learnings.md` |
+| `pattern` | `coding-conventions.md` |
+| `decision` | `architecture-constraints.md` |
+| `rule` | `quality-rules.md` |
+| `validation` | `quality-rules.md` |
+
+Extended types (`bug`, `pattern`, `decision`, `rule`, `validation`) are stored in the file of their closest core category but retain their specific category in the `<spec-entry>` tag.
 </context>
 
 <execution>
@@ -38,7 +45,7 @@ $ARGUMENTS — `<category> <content>` where category selects the target file.
 ### Step 1: Parse Input
 
 Extract category (first token) and content (remainder) from arguments.
-- Validate category is one of: coding, arch, quality, debug, test, review, learning (E003 if invalid)
+- Validate category is one of: coding, arch, quality, debug, test, review, learning, bug, pattern, decision, rule, validation (E003 if invalid)
 - Validate content is non-empty (E001 if missing)
 
 ### Step 2: Validate Specs Directory
@@ -78,6 +85,7 @@ Append `<spec-entry>` closed-tag block to target file:
 Added [{category}] to {target_file}
 Keywords: {kw1}, {kw2}, {kw3}
 Verify: /spec-load --keyword {kw1}
+Remove: /spec-remove <entry-id>
 ```
 </execution>
 
@@ -86,7 +94,7 @@ Verify: /spec-load --keyword {kw1}
 |------|----------|-------------|
 | E001 | fatal | Category and content are both required |
 | E002 | fatal | `.workflow/specs/` not initialized -- run `Skill({ skill: "spec-setup" })` first |
-| E003 | fatal | Invalid category -- must be one of: coding, arch, quality, debug, test, review, learning |
+| E003 | fatal | Invalid category -- must be one of: coding, arch, quality, debug, test, review, learning, bug, pattern, decision, rule, validation |
 </error_codes>
 
 <success_criteria>

package/.codex/skills/spec-load/SKILL.md

@@ -30,8 +30,15 @@ $spec-load "--category coding --keyword naming"
 | `test` | `test-conventions.md` |
 | `review` | `review-standards.md` |
 | `learning` | `learnings.md` |
+| `bug` | `learnings.md` |
+| `pattern` | `coding-conventions.md` |
+| `decision` | `architecture-constraints.md` |
+| `rule` | `quality-rules.md` |
+| `validation` | `quality-rules.md` |
 | `all` (default) | All spec files |
 
+Extended types (`bug`, `pattern`, `decision`, `rule`, `validation`) are stored in their closest core category's file but retain their specific category in the `<spec-entry>` tag.
+
 **Keyword filtering**: When `--keyword` is provided, only entries with matching keyword in their `<spec-entry keywords="...">` attribute are returned. Legacy entries (heading format) are filtered by text grep.
 </context>
 

package/.codex/skills/spec-map/SKILL.md

@@ -43,7 +43,7 @@ Single-wave parallel execution — 4 independent mapper agents each analyze a di
 $spec-map ""
 $spec-map "auth"
 $spec-map -c 4 "api layer"
-$spec-map --continue "map-auth-20260318"
+$spec-map --continue "20260318-map-auth"
 ```
 
 **Flags**:
@@ -102,7 +102,7 @@ id,title,description,focus_area,output_file,deps,context_from,wave,status,findin
 const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
 const focusArea = $ARGUMENTS.replace(/--yes|-y|--continue|--concurrency\s+\d+|-c\s+\d+/g, '').trim() || 'full'
 const dateStr = new Date(Date.now() + 8*60*60*1000).toISOString().substring(0,10).replace(/-/g,'')
-const sessionId = `map-${focusArea.substring(0,20)}-${dateStr}`
+const sessionId = `${dateStr}-map-${focusArea.substring(0,20)}`
 const sessionFolder = `.workflow/.csv-wave/${sessionId}`
 
 Bash(`mkdir -p ${sessionFolder}`)