maestro-flow 0.3.12 → 0.3.14

package/.codex/skills/maestro-milestone-complete/SKILL.md

@@ -65,9 +65,24 @@ cp .workflow/roadmap.md .workflow/milestones/{milestone}/roadmap-snapshot.md
 - Read `.summaries/` from each execute artifact's plan dir
 - Read `reflection-log.md` if exists
 - Extract patterns, pitfalls, strategy adjustments
-- Append to `.workflow/specs/learnings.md`
+- Check existing entries via `maestro spec load --category learning` (dedup)
+- Append to `.workflow/specs/learnings.md` using `<spec-entry>` closed-tag format (category=`learning`, auto-extract keywords, date=today, source=`milestone-complete`)
 - Avoid duplicates (check existing entries)
 
+### Step 3b: Knowledge Promotion Inquiry
+
+After learning extraction, scan `learnings.md` for promotion candidates:
+
+1. **High-frequency pattern detection**: Scan all `<spec-entry category="learning">` entries for keyword overlap (≥2 entries sharing keywords):
+   → Ask: "Keyword '{keyword}' appears in {N} learning entries. Should this be promoted to a formal coding convention? (`/spec-add coding`)"
+
+2. **Convention drift detection**: Compare executed task summaries against `coding-conventions.md` and `architecture-constraints.md`:
+   → Ask: "Were any established conventions bypassed during this milestone? Should conventions be updated?"
+
+3. **Wiki island check**: Auto-trigger `wiki-connect --fix` to link newly extracted knowledge.
+
+If user confirms, append promoted `<spec-entry>` to target category file, preserving original date and source traceability.
+
 ### Step 4: Archive Artifact Entries
 
 Move artifact entries from `state.json.artifacts[]` to `milestone_history`:
@@ -130,6 +145,8 @@ Next steps:
   $maestro-milestone-release  -- Cut release
   $maestro-analyze            -- Start next milestone
   $manage-status              -- View state
+  $manage-wiki health         -- Check wiki graph health
+  $wiki-digest                -- Generate knowledge digest
 ```
 
 </execution>

package/.codex/skills/maestro-plan/SKILL.md

@@ -55,7 +55,7 @@ $maestro-plan -y "3 --auto"
 $maestro-plan -c 4 "3 --spec SPEC-001"
 $maestro-plan "3 --gaps"
 $maestro-plan "3 --dir .workflow/scratch/quick-nav-fix"
-$maestro-plan --continue "plan-phase3-20260318"
+$maestro-plan --continue "20260318-plan-P3-auth"
 ```
 
 **Flags**:
@@ -116,7 +116,7 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column.
 ### Session Structure
 
 ```
-.workflow/.csv-wave/plan-{phase}-{date}/
+.workflow/.csv-wave/{YYYYMMDD}-plan-P{N}-{slug}/
 +-- tasks.csv
 +-- results.csv
 +-- discoveries.ndjson
@@ -197,9 +197,9 @@ if (dirMatch) {
 }
 
 const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
-const sessionId = `plan-${phaseSlug}-${dateStr}`
+const sessionId = `${dateStr}-plan-P${phaseArg}-${phaseSlug}`
 const sessionFolder = `.workflow/.csv-wave/${sessionId}`
-const scratchDir = `.workflow/scratch/plan-${phaseSlug}-${dateStr}`
+const scratchDir = `.workflow/scratch/${dateStr}-plan-P${phaseArg}-${phaseSlug}`
 
 Bash(`mkdir -p ${sessionFolder}`)
 Bash(`mkdir -p ${scratchDir}/.task/`)
@@ -413,8 +413,8 @@ spawn_agents_on_csv({
    Tasks: {task_count} tasks in {wave_count} waves
    Check: {checker_status}
 
-   Plan: {phase_dir}/plan.json
-   Tasks: {phase_dir}/.task/TASK-*.json
+   Plan: {scratch_dir}/plan.json
+   Tasks: {scratch_dir}/.task/TASK-*.json
 
    Next steps:
      Skill({ skill: "maestro-execute", args: "{phase}" })  -- Execute the plan

package/.codex/skills/maestro-roadmap/SKILL.md

@@ -135,7 +135,7 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column.
 ### Session Structure
 
 ```
-.workflow/.csv-wave/roadmap-{slug}-{date}/
+.workflow/.csv-wave/{YYYYMMDD}-roadmap-{slug}/
 +-- tasks.csv
 +-- results.csv
 +-- discoveries.ndjson
@@ -164,7 +164,7 @@ const slug = requirementArg.toLowerCase()
   .replace(/[^a-z0-9]+/g, '-')
   .substring(0, 40)
 const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
-const sessionId = `roadmap-${slug}-${dateStr}`
+const sessionId = `${dateStr}-roadmap-${slug}`
 const sessionFolder = `.workflow/.csv-wave/${sessionId}`
 
 Bash(`mkdir -p ${sessionFolder}`)
@@ -301,7 +301,6 @@ spawn_agents_on_csv({
    - Write `.workflow/roadmap.md` using standard roadmap template structure
    - Ensure `.workflow/scratch/` directory exists (phases are labels, not directories)
    - Update `state.json` milestones array and set `current_milestone`
-   - Update `.workflow/state.json` (if exists): set `current_phase: 1`
 
 6. Display summary:
 
@@ -372,7 +371,7 @@ echo '{"ts":"<ISO>","worker":"{id}","type":"risk_factor","data":{"name":"OAuth p
 - [ ] Wave 2 assembly agent produced roadmap.md
 - [ ] Interactive refinement offered (or skipped with -y)
 - [ ] .workflow/roadmap.md written with phases, milestones, success criteria
-- [ ] state.json updated with milestones and current_phase
+- [ ] state.json updated with milestones
 - [ ] context.md generated with analysis summary
 - [ ] Completion report displayed with next steps
 </success_criteria>

package/.codex/skills/maestro-spec-generate/SKILL.md

@@ -139,7 +139,7 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column.
 ### Session Structure
 
 ```
-.workflow/.csv-wave/spec-generate-{slug}-{date}/
+.workflow/.csv-wave/{YYYYMMDD}-spec-generate-{slug}/
 +-- tasks.csv
 +-- results.csv
 +-- discoveries.ndjson
@@ -189,7 +189,7 @@ const slug = topicArg.toLowerCase()
   .replace(/[^a-z0-9]+/g, '-')
   .substring(0, 40)
 const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
-const sessionId = `spec-generate-${slug}-${dateStr}`
+const sessionId = `${dateStr}-spec-generate-${slug}`
 const sessionFolder = `.workflow/.csv-wave/${sessionId}`
 
 Bash(`mkdir -p ${sessionFolder}`)

package/.codex/skills/maestro-ui-design/SKILL.md

@@ -37,7 +37,7 @@ $maestro-ui-design "3 --style-skill PKG --stack react"
 
 When `--yes` or `-y`: Skip interactive selection, auto-pick top-scored variant, skip brief review.
 
-**Output**: `{phase_dir}/design-ref/` with MASTER.md, design-tokens.json, animation-tokens.json, selection.json, prototypes/
+**Output**: `{scratch_dir}/design-ref/` with MASTER.md, design-tokens.json, animation-tokens.json, selection.json, prototypes/
 </context>
 
 <invariants>
@@ -54,7 +54,7 @@ When `--yes` or `-y`: Skip interactive selection, auto-pick top-scored variant,
 ### Step 1: Parse Input and Resolve Target
 
 1. Parse flags from `$ARGUMENTS`: `--styles N`, `--stack`, `--targets`, `--persist`, `--full`, `-y`
-2. **Phase mode** (number): resolve via state.json artifact registry to `.workflow/scratch/{type}-{slug}-{date}/`; legacy fallback to `.workflow/phases/{NN}-*/`
+2. **Phase mode** (number): resolve via state.json artifact registry to `.workflow/scratch/{YYYYMMDD}-{type}-{slug}/`
 3. **Scratch mode** (text): create `.workflow/scratch/ui-design-{slug}-{date}/` with minimal index.json
 4. Create output directories:
    ```bash
@@ -148,10 +148,10 @@ Agent({
    Targets: {target_list}
 
    Design System:
-     MASTER.md:  {phase_dir}/design-ref/MASTER.md
-     Tokens:     {phase_dir}/design-ref/design-tokens.json
-     Animation:  {phase_dir}/design-ref/animation-tokens.json
-     Prototypes: {phase_dir}/design-ref/prototypes/
+     MASTER.md:  {scratch_dir}/design-ref/MASTER.md
+     Tokens:     {scratch_dir}/design-ref/design-tokens.json
+     Animation:  {scratch_dir}/design-ref/animation-tokens.json
+     Prototypes: {scratch_dir}/design-ref/prototypes/
 
    Next steps:
      Skill({ skill: "maestro-plan", args: "{phase}" })

package/.codex/skills/maestro-verify/SKILL.md

@@ -63,7 +63,7 @@ Wave-based 3-layer Goal-Backward verification using `spawn_agents_on_csv`. Decom
 $maestro-verify "3"
 $maestro-verify -c 4 "3 --skip-tests"
 $maestro-verify -y "3 --skip-antipattern"
-$maestro-verify --continue "verify-phase3-20260318"
+$maestro-verify --continue "20260318-verify-P3-auth"
 ```
 
 **Flags**:
@@ -102,7 +102,7 @@ id,title,description,layer,phase_dir,check_type,deps,context_from,wave,status,fi
 | `title` | Input | Short check title |
 | `description` | Input | Detailed verification instructions for this check |
 | `layer` | Input | Verification layer: truth/artifact/wiring/antipattern/nyquist |
-| `phase_dir` | Input | Target directory path (e.g., `.workflow/scratch/plan-chat-2026/`; legacy: `.workflow/phases/03-chat/`) |
+| `phase_dir` | Input | Target directory path (e.g., `.workflow/scratch/plan-chat-2026/`) |
 | `check_type` | Input | Specific check type: observable_behavior/exists/substance/import_usage/pattern_scan/test_coverage |
 | `deps` | Input | Semicolon-separated dependency task IDs |
 | `context_from` | Input | Semicolon-separated task IDs whose findings this task needs |
@@ -132,7 +132,7 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column.
 ### Session Structure
 
 ```
-.workflow/.csv-wave/verify-{phase}-{date}/
+.workflow/.csv-wave/{YYYYMMDD}-verify-P{N}-{slug}/
 +-- tasks.csv
 +-- results.csv
 +-- discoveries.ndjson
@@ -179,7 +179,7 @@ const phaseArg = $ARGUMENTS
   .trim()
 
 const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
-const sessionId = `verify-phase${phaseArg}-${dateStr}`
+const sessionId = `${dateStr}-verify-P${phaseArg}-${phaseSlug}`
 const sessionFolder = `.workflow/.csv-wave/${sessionId}`
 
 Bash(`mkdir -p ${sessionFolder}`)
@@ -191,7 +191,7 @@ Bash(`mkdir -p ${sessionFolder}`)
 
 **Decomposition Rules**:
 
-1. **Phase resolution**: Resolve `{phaseArg}` via artifact registry in `state.json` to `.workflow/scratch/{type}-{slug}-{date}/`; legacy fallback to `.workflow/phases/{NN}-{slug}/`
+1. **Phase resolution**: Resolve `{phaseArg}` via artifact registry in `state.json` to `.workflow/scratch/{YYYYMMDD}-{type}-{slug}/`
 2. **Artifact loading**: Read from phase directory:
    - `index.json` -- success_criteria (ground truth for verification)
    - `plan.json` -- original plan with task_ids
@@ -445,8 +445,8 @@ Issue Refs: {issue_ids}
     - If `verification.json` or `validation.json` exists in phase dir, move to `.history/`
 
 12. **Copy output files** to phase directory:
-    - `verification.json` -> `{phase_dir}/verification.json`
-    - `validation.json` -> `{phase_dir}/validation.json` (if generated)
+    - `verification.json` -> `{artifact_dir}/verification.json`
+    - `validation.json` -> `{artifact_dir}/validation.json` (if generated)
 
 13. **Update phase index.json** with verification status and timestamps.
 
@@ -475,11 +475,20 @@ Human Verification: {human_items} items
 Files:
   {session_folder}/verification.json
   {session_folder}/validation.json (if generated)
-  {phase_dir}/verification.json
-  {phase_dir}/validation.json (if generated)
+  {artifact_dir}/verification.json
+  {artifact_dir}/validation.json (if generated)
 ```
 
-15. **Next step routing**:
+15. **Post-verify Knowledge Inquiry** (before next step routing):
+   - **Anti-pattern detection**: If anti-pattern scan found blockers:
+     → Ask: "Verification found {N} anti-patterns. Should `quality-rules.md` be updated to enforce these checks? (`/spec-add quality`)"
+   - **Constraint violation**: If Goal-Backward check found constraint violations or missing wiring:
+     → Ask: "Verification found architecture constraint violations. Should `architecture-constraints.md` be updated? (`/spec-add arch`)"
+   - **Test coverage gaps**: If Nyquist gaps found with recurring pattern:
+     → Ask: "Persistent test coverage gap detected in {module}. Should it be added to `test-conventions.md` as a required test area? (`/spec-add test`)"
+   - If user confirms, append `<spec-entry>` to matching category file via `spec-add` mechanism
+
+16. **Next step routing**:
 
 | Result | Suggestion |
 |--------|------------|
@@ -528,7 +537,7 @@ echo '{"ts":"<ISO>","worker":"{id}","type":"verification_gap","data":{"gap_id":"
 
 | Error | Resolution |
 |-------|------------|
-| Phase directory not found | Resolve via state.json artifact registry; legacy fallback to `.workflow/phases/`; abort if neither found |
+| Phase directory not found | Resolve via state.json artifact registry; abort if not found |
 | No execution results found | Abort with error: "No completed tasks found -- run execute first" |
 | No summaries found | Warn, proceed with task file analysis only |
 | No success_criteria in index.json | Derive must-haves from phase goal (fallback) |

package/.codex/skills/manage-codebase-rebuild/SKILL.md

@@ -55,7 +55,7 @@ $ARGUMENTS -- optional flags for rebuild control.
 $manage-codebase-rebuild ""
 $manage-codebase-rebuild -y "--force"
 $manage-codebase-rebuild -c 5 "--force --skip-commit"
-$manage-codebase-rebuild --continue "rebuild-full-20260318"
+$manage-codebase-rebuild --continue "20260318-rebuild-full"
 ```
 
 **Flags**:
@@ -145,7 +145,7 @@ Single wave generates `wave-1.csv`. No `prev_context` needed (all tasks independ
 ### Session Structure
 
 ```
-.workflow/.csv-wave/rebuild-{scope}-{date}/
+.workflow/.csv-wave/{YYYYMMDD}-rebuild-{scope}/
 +-- tasks.csv
 +-- results.csv
 +-- discoveries.ndjson
@@ -171,7 +171,7 @@ const forceMode = $ARGUMENTS.includes('--force') || AUTO_YES
 const skipCommit = $ARGUMENTS.includes('--skip-commit')
 
 const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
-const sessionId = `rebuild-full-${dateStr}`
+const sessionId = `${dateStr}-rebuild-full`
 const sessionFolder = `.workflow/.csv-wave/${sessionId}`
 
 Bash(`mkdir -p ${sessionFolder}`)
@@ -204,7 +204,7 @@ Bash(`mkdir -p ${sessionFolder}`)
 
 4. **Detect source directories**:
    - Check for: `src/`, `lib/`, `app/`, `packages/`
-   - Read `project-tech.json` if available for `source_dirs`
+   - Read `project.md` Tech Stack section if available for context
    - If no source directories found: abort with "No source files in project"
 
 5. **Load project specs** (if available):

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

@@ -54,8 +54,17 @@ Follow '~/.maestro/workflows/harvest.md' Stages 1–8.
 3. **Stable fragment IDs** — `HRV-{8 hex}` from `hash(source_id + content_hash)`
 4. **Never modify source artifacts** — purely extractive
 5. **Confidence filtering** — below threshold logged but not routed
+6. **Spec format enforcement** — all spec routing must use `<spec-entry>` closed-tag format with `category`, `keywords`, `date`, `source="harvest"` attributes
 
-**Next steps:** `maestro wiki list --type note`, `/wiki-connect --fix`, `/manage-issue list --source harvest`
+**Routing rules:**
+- Universal design patterns → `coding` or `arch` category
+- Component-level pitfalls → `learning` category
+- Quality enforcement rules → `quality` category
+- Wiki: `maestro wiki create --type <type> --slug harvest-<source_type>-<short_id>`
+- Spec: `maestro wiki append spec-<file> --category <category> --body "<content>" --keywords "<kws>"` (unified write path) or `Skill({ skill: "spec-add", args: "<category> <content>" })`
+- Issue: append to `issues.jsonl` matching canonical schema
+
+**Next steps:** `/manage-wiki health`, `maestro wiki list --type note`, `/wiki-connect --fix`, `/wiki-digest`, `/manage-issue list --source harvest`
 </execution>
 
 <error_codes>

package/.codex/skills/manage-issue-discover/SKILL.md

@@ -60,7 +60,7 @@ Wave-based multi-perspective issue discovery using `spawn_agents_on_csv`. In def
 $manage-issue-discover
 $manage-issue-discover -c 8 ""
 $manage-issue-discover -y "by-prompt 'error handling gaps in auth module'"
-$manage-issue-discover --continue "discover-multi-20260318"
+$manage-issue-discover --continue "20260318-discover-multi"
 ```
 
 **Flags**:
@@ -127,7 +127,7 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column.
 ### Session Structure
 
 ```
-.workflow/.csv-wave/discover-{mode}-{date}/
+.workflow/.csv-wave/{YYYYMMDD}-discover-{mode}/
 +-- tasks.csv
 +-- results.csv
 +-- discoveries.ndjson
@@ -185,7 +185,7 @@ const mode = isByPrompt ? 'by-prompt' : 'multi'
 const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
 const timeStr = getUtc8ISOString().substring(11, 19).replace(/:/g, '')
 const sessionId = `DBP-${dateStr}-${timeStr}`
-const csvSessionId = `discover-${mode}-${dateStr}`
+const csvSessionId = `${dateStr}-discover-${mode}`
 const sessionFolder = `.workflow/.csv-wave/${csvSessionId}`
 const discoveryDir = `.workflow/issues/discoveries/${sessionId}`
 

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

@@ -98,7 +98,7 @@ Verify `.workflow/` exists (E001 if not).
 | gotcha, surprising, unexpected, watch out | gotcha |
 | technique, approach, method, pattern for | technique |
 
-2. **Auto-link phase**: Read `.workflow/state.json` for `current_phase`. Resolve matching directory slug via artifact registry in `state.json` to `.workflow/scratch/{type}-{slug}-{date}/`; legacy fallback to `.workflow/phases/`. `--phase 0` forces null.
+2. **Auto-link phase**: Read `.workflow/state.json` for current phase (derived from artifact registry). Resolve matching directory slug via artifact registry in `state.json` to `.workflow/scratch/{YYYYMMDD}-{type}-{slug}/`. `--phase 0` forces null.
 
 3. **Generate stable INS-id**: `INS-{8 lowercase hex}` from `hash(insightText + timestamp)`.
 
@@ -164,6 +164,7 @@ Confidence: medium
 Tags:       manual, zod, typescript
 
 Next: $manage-learn "list"  or  $manage-learn "search zod"
+Wiki: maestro wiki list --type lesson  (lessons auto-indexed in wiki graph)
 ```
 </execution>
 
@@ -174,7 +175,7 @@ Next: $manage-learn "list"  or  $manage-learn "search zod"
 | E002 | error | Unknown `--category` value | parse_input |
 | E003 | error | `show` mode requires INS-id argument | show |
 | E004 | error | INS-id not found in lessons.jsonl | show |
-| W001 | warning | Auto-phase detection: current_phase found but no matching directory; phase set to null | capture |
+| W001 | warning | Auto-phase detection: no matching artifact directory found; phase set to null | capture |
 | W002 | warning | `learning-index.json` row count differs from `lessons.jsonl`; offer to rebuild index | list/search |
 </error_codes>
 

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

@@ -37,7 +37,7 @@ $manage-memory "prune --before 2026-01-01 --type tip --dry-run"
 
 ### Step 1: Resolve Store Paths
 
-- **Workflow store**: `.workflow/memory/` (entries: `MEM-*.md`, `TIP-*.md`, index: `memory-index.json`)
+- **Workflow store**: `.workflow/memory/` (entries: `MEM-*.md`, `TIP-*.md`, indexed in unified `.workflow/wiki-index.json`)
 - **System store**: `~/.claude/projects/{project}/memory/` (files: `MEMORY.md` + topic `.md` files)
 
 Derive system path from project root (replace path separators with `--`, prefix drive letter).
@@ -49,7 +49,7 @@ Default to `list` if no arguments. Parse first token as subcommand.
 ### Step 3: Execute Subcommand
 
 **list**: Show entries from both stores (or filtered by `--store`, `--tag`, `--type`).
-- Workflow: read `memory-index.json`, display ID, type, date, tags, title
+- Workflow: use `maestro wiki list --type memory --json` or read `.workflow/wiki-index.json`, display ID, type, date, tags, title
 - System: list `.md` files in system memory directory
 
 **search `<query>`**: Full-text grep across both stores. Rank by match count.
@@ -58,7 +58,7 @@ Default to `list` if no arguments. Parse first token as subcommand.
 
 **edit `<file>`**: Edit a system memory file. Read current content, apply changes. Warn if MEMORY.md exceeds 200 lines (W003).
 
-**delete `<id|file>`**: Require confirmation (or `--confirm` flag). MEMORY.md cannot be deleted (E004). Remove entry file and update `memory-index.json`.
+**delete `<id|file>`**: Require confirmation (or `--confirm` flag). MEMORY.md cannot be deleted (E004). Remove entry file (WikiIndexer auto-updates `.workflow/wiki-index.json` on next access).
 
 **prune**: Requires at least one filter (`--tag`, `--type`, `--before`, `--after`). Workflow store only. `--dry-run` previews without deleting.
 

package/.codex/skills/manage-memory-capture/SKILL.md

@@ -54,20 +54,14 @@ If absent or ambiguous, ask user via AskUserQuestion.
 2. Generate entry ID: `TIP-{YYYYMMDD}-{NNN}`
 3. Write `.workflow/memory/TIP-{id}.md` with: content, tags, timestamp, context
 
-### Step 4: Update Index
-
-Read or create `.workflow/memory/memory-index.json`.
-Append new entry metadata:
-
-```json
-{
-  "id": "{entry_id}",
-  "type": "compact|tip",
-  "date": "{ISO}",
-  "title": "{short title}",
-  "tags": ["tag1", "tag2"],
-  "file": "{filename}"
-}
+### Step 4: Wiki Index Invalidation
+
+Memory files are automatically indexed by WikiIndexer. No manual index update needed — the persistent `wiki-index.json` at `.workflow/` root is regenerated on next `maestro wiki` access.
+
+For immediate visibility, use:
+```bash
+maestro wiki get memory-{slug}         # verify entry exists in wiki
+maestro wiki list --type memory        # list all memory entries
 ```
 
 ### Step 5: Confirm

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

@@ -19,8 +19,9 @@ $manage-status
 Reads from:
 - `.workflow/state.json` — project-level state machine
 - `.workflow/roadmap.md` — milestone and phase structure
-- `.workflow/scratch/*/index.json` — per-phase metadata and progress (resolved via state.json artifact registry; legacy fallback: `.workflow/phases/*/index.json`)
-- `.workflow/scratch/*/.task/TASK-*.json` — individual task statuses (legacy fallback: `.workflow/phases/*/.task/TASK-*.json`)
+- `.workflow/scratch/*/index.json` — per-phase metadata and progress (resolved via state.json artifact registry)
+- `.workflow/scratch/*/.task/TASK-*.json` — individual task statuses (resolved via state.json artifact registry)
+- `.workflow/wiki-index.json` — unified wiki graph index (entry counts, health)
 </context>
 
 <execution>
@@ -38,8 +39,8 @@ test -f .workflow/state.json || exit 1  # E002: state missing
 Read all state sources:
 - `.workflow/state.json` -- project-level state machine
 - `.workflow/roadmap.md` -- milestone and phase structure
-- `.workflow/scratch/*/index.json` -- per-phase metadata and progress (resolved via state.json artifact registry; legacy fallback: `.workflow/phases/*/index.json`)
-- `.workflow/scratch/*/.task/TASK-*.json` -- individual task statuses (legacy fallback: `.workflow/phases/*/.task/TASK-*.json`)
+- `.workflow/scratch/*/index.json` -- per-phase metadata and progress (resolved via state.json artifact registry)
+- `.workflow/scratch/*/.task/TASK-*.json` -- individual task statuses (resolved via state.json artifact registry)
 
 ### Step 3: Calculate Progress
 
@@ -67,6 +68,10 @@ Phase {N}: {title}
   In-progress: {list}
   Blocked: {list}
 
+--- Knowledge Graph ---
+Wiki entries: {total} (spec: {N}, memory: {N}, note: {N}, lesson: {N}, issue: {N})
+Health: {score}/100 | Orphans: {N}
+
 --- Next Steps ---
 Based on current state: {suggestion with Skill() reference}
 ```

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. Resolve `PHASE_DIR` via artifact registry in `state.json` to `.workflow/scratch/{type}-{slug}-{date}/`; legacy fallback to `.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 | Resolve via state.json artifact registry; legacy fallback to `.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