maestro-flow 0.3.11 → 0.3.13

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

@@ -1,62 +1,69 @@
----
-name: maestro-merge
-description: Two-phase merge of milestone worktree branch back — git merge first, artifact sync only on success. Registry health check, pre-merge rebase, atomic state reconciliation.
-argument-hint: "-m <milestone-number> [--force] [--dry-run] [--no-cleanup] [--continue]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
----
-
-<purpose>
-Merge a completed milestone worktree branch back into main, sync workflow artifacts,
-and reconcile project state. Two-phase approach: git merge first (source code),
-artifact sync second (only after git succeeds). Prevents partial state corruption
-when merge conflicts occur.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/merge.md
-</required_reading>
-
-<context>
-$ARGUMENTS — milestone number and optional flags.
-
-**Flags:**
-- `-m <N>` or bare `<N>`: Milestone number
-- `--force`: Merge even if not all phases completed
-- `--dry-run`: Show what would be merged
-- `--no-cleanup`: Keep worktree and branch after merge
-- `--continue`: Resume merge paused due to git conflict
-
-**Merge sequence:**
-1. Registry health check → 2. Phase readiness validation → 3. Pre-merge rebase →
-4. Git merge (source) → 5. Artifact sync (.workflow/) → 6. State reconciliation → 7. Cleanup
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/merge.md' completely.
-
-**Next steps:**
-- View dashboard → `$manage-status`
-- Audit milestone → `$maestro-milestone-audit`
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Running inside a worktree | Run from main worktree |
-| E002 | error | No worktree registry found | Nothing to merge |
-| E003 | error | --continue but no merge state | Start fresh merge |
-| E004 | error | No milestone number | Provide `-m <N>` |
-| W001 | warning | Stale registry entries | Auto-cleaned |
-| W002 | warning | Incomplete phases without --force | Confirm or use --force |
-| W003 | warning | Conflict pulling main into worktree | Resolve first |
-</error_codes>
-
-<success_criteria>
-- [ ] Registry health check passed
-- [ ] Pre-merge rebase successful
-- [ ] Git merge completed (or conflicts resolved via --continue)
-- [ ] Phase artifacts synced to main `.workflow/`
-- [ ] `state.json` reconciled
-- [ ] Worktree removed and branch deleted (unless --no-cleanup)
-- [ ] Registry updated
-</success_criteria>
+---
+name: maestro-merge
+description: Two-phase merge of milestone worktree branch back — git merge first, scratch artifact sync and registry reconciliation only on success.
+argument-hint: "-m <milestone-number> [--force] [--dry-run] [--no-cleanup] [--continue]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Merge a completed milestone worktree branch back into main, sync scratch artifacts,
+and reconcile artifact registry. Two-phase approach: git merge first (source code),
+artifact sync second (only after git succeeds). Prevents partial state corruption
+when merge conflicts occur.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/merge.md
+</required_reading>
+
+<context>
+$ARGUMENTS — milestone number and optional flags.
+
+**Flags:**
+- `-m <N>` or bare `<N>`: Milestone number
+- `--force`: Merge even if milestone has incomplete artifacts
+- `--dry-run`: Show what would be merged
+- `--no-cleanup`: Keep worktree and branch after merge
+- `--continue`: Resume merge paused due to git conflict
+
+**Merge sequence:**
+1. Registry health check → 2. Milestone artifact completeness validation →
+3. Pre-merge rebase → 4. Git merge (source) → 5. Scratch artifact sync →
+6. Artifact registry reconciliation → 7. Cleanup
+
+**Phase 2 detail:**
+- Copy worktree `scratch/*` to main `.workflow/scratch/`
+- Merge `state.json.artifacts[]` entries (worktree wins for same id)
+- Remove milestone `"forked"` flag in main state.json
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/merge.md' completely.
+
+**Next steps:**
+- View dashboard → `$manage-status`
+- Audit milestone → `$maestro-milestone-audit`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Running inside a worktree | Run from main worktree |
+| E002 | error | No worktree registry found | Nothing to merge |
+| E003 | error | --continue but no merge state | Start fresh merge |
+| E004 | error | No milestone number | Provide `-m <N>` |
+| W001 | warning | Stale registry entries | Auto-cleaned |
+| W002 | warning | Incomplete artifacts without --force | Confirm or use --force |
+| W003 | warning | Conflict pulling main into worktree | Resolve first |
+</error_codes>
+
+<success_criteria>
+- [ ] Registry health check passed
+- [ ] Pre-merge rebase successful
+- [ ] Git merge completed (or conflicts resolved via --continue)
+- [ ] Scratch artifacts synced to main `.workflow/scratch/`
+- [ ] `state.json.artifacts[]` reconciled (worktree entries merged)
+- [ ] Milestone `"forked"` flag removed
+- [ ] Worktree removed and branch deleted (unless --no-cleanup)
+- [ ] Registry updated
+</success_criteria>

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 `.workflow/phases/{NN}-*/` directory
+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**:
@@ -83,15 +83,15 @@ When `--yes` or `-y`: Auto-confirm check decomposition, skip interactive validat
 
 ```csv
 id,title,description,layer,phase_dir,check_type,deps,context_from,wave,status,findings,gaps_found,fix_plan,error
-"1","Truth: User can see existing messages","Verify observable behavior: user can see existing messages by checking supporting artifacts, API calls, and render logic.","truth",".workflow/phases/03-chat/","observable_behavior","","","1","","","","",""
-"2","Truth: User can send new messages","Verify observable behavior: user can send new messages by checking form submission, API POST, and state update.","truth",".workflow/phases/03-chat/","observable_behavior","","","1","","","","",""
-"3","Artifact Exists: src/components/Chat.tsx","Check L1 existence: verify file src/components/Chat.tsx exists on disk.","artifact",".workflow/phases/03-chat/","exists","","","1","","","","",""
-"4","Artifact Exists: src/api/chat.ts","Check L1 existence: verify file src/api/chat.ts exists on disk.","artifact",".workflow/phases/03-chat/","exists","","","1","","","","",""
-"5","Artifact Substance: src/components/Chat.tsx","Check L2 substance: verify src/components/Chat.tsx has real implementation (not stub/placeholder). Minimum logic threshold, no placeholder markers.","artifact",".workflow/phases/03-chat/","substance","3","3","2","","","","",""
-"6","Artifact Substance: src/api/chat.ts","Check L2 substance: verify src/api/chat.ts has real implementation (not stub/placeholder).","artifact",".workflow/phases/03-chat/","substance","4","4","2","","","","",""
-"7","Wiring: Chat.tsx -> /api/chat","Check L3 wiring: verify Chat.tsx imports and calls /api/chat endpoints. Check import statements and actual usage beyond imports.","wiring",".workflow/phases/03-chat/","import_usage","3;4","3;4","2","","","","",""
-"8","Anti-Pattern Scan","Scan all modified files for TODO/FIXME/XXX/HACK, placeholder content, empty returns, log-only functions, hardcoded test data, disabled tests. Categorize as Blocker/Warning/Info.","antipattern",".workflow/phases/03-chat/","pattern_scan","1;2;5;6;7","1;2;5;6;7","3","","","","",""
-"9","Nyquist Test Coverage Audit","Map requirements to test files. Classify each as COVERED/PARTIAL/MISSING. Detect test framework, run coverage if available.","nyquist",".workflow/phases/03-chat/","test_coverage","1;2;5;6;7","1;2;5;6;7","3","","","","",""
+"1","Truth: User can see existing messages","Verify observable behavior: user can see existing messages by checking supporting artifacts, API calls, and render logic.","truth",".workflow/scratch/plan-chat-2026/","observable_behavior","","","1","","","","",""
+"2","Truth: User can send new messages","Verify observable behavior: user can send new messages by checking form submission, API POST, and state update.","truth",".workflow/scratch/plan-chat-2026/","observable_behavior","","","1","","","","",""
+"3","Artifact Exists: src/components/Chat.tsx","Check L1 existence: verify file src/components/Chat.tsx exists on disk.","artifact",".workflow/scratch/plan-chat-2026/","exists","","","1","","","","",""
+"4","Artifact Exists: src/api/chat.ts","Check L1 existence: verify file src/api/chat.ts exists on disk.","artifact",".workflow/scratch/plan-chat-2026/","exists","","","1","","","","",""
+"5","Artifact Substance: src/components/Chat.tsx","Check L2 substance: verify src/components/Chat.tsx has real implementation (not stub/placeholder). Minimum logic threshold, no placeholder markers.","artifact",".workflow/scratch/plan-chat-2026/","substance","3","3","2","","","","",""
+"6","Artifact Substance: src/api/chat.ts","Check L2 substance: verify src/api/chat.ts has real implementation (not stub/placeholder).","artifact",".workflow/scratch/plan-chat-2026/","substance","4","4","2","","","","",""
+"7","Wiring: Chat.tsx -> /api/chat","Check L3 wiring: verify Chat.tsx imports and calls /api/chat endpoints. Check import statements and actual usage beyond imports.","wiring",".workflow/scratch/plan-chat-2026/","import_usage","3;4","3;4","2","","","","",""
+"8","Anti-Pattern Scan","Scan all modified files for TODO/FIXME/XXX/HACK, placeholder content, empty returns, log-only functions, hardcoded test data, disabled tests. Categorize as Blocker/Warning/Info.","antipattern",".workflow/scratch/plan-chat-2026/","pattern_scan","1;2;5;6;7","1;2;5;6;7","3","","","","",""
+"9","Nyquist Test Coverage Audit","Map requirements to test files. Classify each as COVERED/PARTIAL/MISSING. Detect test framework, run coverage if available.","nyquist",".workflow/scratch/plan-chat-2026/","test_coverage","1;2;5;6;7","1;2;5;6;7","3","","","","",""
 ```
 
 **Columns**:
@@ -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 | Phase directory path (e.g., `.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}` 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 | Abort with error: "Phase {N} not 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 from `.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/phases/*/index.json` — per-phase metadata and progress
-- `.workflow/phases/*/.task/TASK-*.json` — individual task statuses
+- `.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/phases/*/index.json` -- per-phase metadata and progress
-- `.workflow/phases/*/.task/TASK-*.json` -- individual task statuses
+- `.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}
 ```