maestro-flow 0.4.12 → 0.4.13

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

@@ -34,14 +34,15 @@ $ARGUMENTS -- requirement/idea text or @file reference, plus optional flags.
 <interview_protocol>
 Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `-y/--yes`, `--revise`, `--review`, `-c`, or input is already specific (clear requirement + mode).
 
-- One decision per turn via request_user_input with 2–4 options + a (Recommended) default; every question must include a `Proceed now` option.
-- Never ask what code can verify — resolve via `state.json`, existing `roadmap.md`, `project.md`, or `maestro spec load`.
+- One decision per turn via request_user_input with 2–4 options + a (Recommended) default. The user controls termination — keep interviewing until convergence; they can interrupt naturally at any time.
+- Search-first when uncertain: before asking, resolve via `state.json`, existing `roadmap.md`, `project.md`, `maestro spec load`, `maestro wiki search`, Glob/Grep/Read, or — for open-ended multi-file scans — `maestro delegate ... --role explore`. Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
+- Writeback cadence: each settled decision is immediately appended/updated in the `Roadmap Decisions` section at the top of `.workflow/roadmap.md` (create the section if absent). Do NOT batch writeback to the end — partial decisions must already be on disk before the next question.
 - Walk the decision dependency tree strictly: mode → requirement scope → decomposition strategy → phase dependencies/order. Do not open the next branch until the current one is settled.
 - Scope guard: only decide the shape of the roadmap. Do not pre-resolve intra-phase task breakdown — that belongs to `plan`.
 
 Decision points: scope (MVP / complete / phased) → strategy (progressive / direct / auto) → milestone boundaries → phase dependencies and order.
 
-Exit: on consensus or `Proceed now`, append the table below to a `Roadmap Decisions` section at the top of `.workflow/roadmap.md`:
+Exit: on consensus or explicit user signal to proceed, finalize the `Roadmap Decisions` section (rows already populated incrementally). Schema:
 `| # | Decision | Choice | Source (user / code / default) |`
 </interview_protocol>
 

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

@@ -81,13 +81,15 @@ When `--yes` or `-y`: Auto-confirm rebuild (implies --force), skip all prompts.
 
 ```csv
 id,title,description,doc_dimension,output_path,deps,context_from,wave
-"1","Component Scanner","Scan all source directories for components: models, services, controllers, utils, types, config, middleware, core modules. For each component extract exported symbols, determine type, record code locations. Output JSON array of component entries with id (TC-NNN), name, type, code_locations, symbols.","components",".workflow/codebase/doc-index.json#components","","","1"
-"2","Feature Mapper","Group discovered components by domain/functional area using directory proximity, naming patterns, and import relationships. Map features to requirements if .workflow/blueprint/ exists. Output JSON array of feature entries with id (FT-NNN), name, status, component_ids, requirement_ids, phase.","features",".workflow/codebase/doc-index.json#features","","","1"
-"3","Requirement Linker","If .workflow/blueprint/ exists, scan BLP-*/requirements/REQ-*.md files. Parse requirement metadata (title, priority, acceptance_criteria). Match requirements to features by keyword analysis. Also scan for ADR-*.md architecture decisions. Output JSON arrays for requirements and architecture_decisions.","requirements",".workflow/codebase/doc-index.json#requirements","","","1"
-"4","Tech Registry Writer","For each component discovered, generate a markdown documentation file in .workflow/codebase/tech-registry/{slug}.md with: ID, type, features, code locations, exported symbols, dependencies. Generate _index.md with component table. Output file count and paths.","tech-registry",".workflow/codebase/tech-registry/","","","1"
-"5","Feature Map Writer","For each feature discovered, generate a markdown documentation file in .workflow/codebase/feature-maps/{slug}.md with: ID, status, phase, requirements, component table. Generate _index.md with feature table. Output file count and paths.","feature-maps",".workflow/codebase/feature-maps/","","","1"
+"1","Component Scanner","Scan all source directories for components: models, services, controllers, utils, types, config, middleware, core modules. For each component extract exported symbols, determine type, record code locations. Return JSON array of component entries with id (TC-NNN), name, type, code_locations, symbols via output_schema. Do NOT write files — orchestrator assembles doc-index.json in Phase 3.","components","<ABS_WORKFLOW>/codebase/doc-index.json#components","","","1"
+"2","Feature Mapper","Group discovered components by domain/functional area using directory proximity, naming patterns, and import relationships. Map features to requirements if <ABS_WORKFLOW>/blueprint/ exists. Return JSON array of feature entries with id (FT-NNN), name, status, component_ids, requirement_ids, phase via output_schema. Do NOT write files.","features","<ABS_WORKFLOW>/codebase/doc-index.json#features","","","1"
+"3","Requirement Linker","If <ABS_WORKFLOW>/blueprint/ exists, scan BLP-*/requirements/REQ-*.md files. Parse requirement metadata (title, priority, acceptance_criteria). Match requirements to features by keyword analysis. Also scan for ADR-*.md architecture decisions. Return JSON arrays for requirements and architecture_decisions via output_schema. Do NOT write files.","requirements","<ABS_WORKFLOW>/codebase/doc-index.json#requirements","","","1"
+"4","Tech Registry Writer","For each component discovered, use the Write tool to create a markdown documentation file at <ABS_WORKFLOW>/codebase/tech-registry/{slug}.md with: ID, type, features, code locations, exported symbols, dependencies. Also write <ABS_WORKFLOW>/codebase/tech-registry/_index.md with the component table. After all writes, verify every intended file exists with Glob and return file count + absolute paths via output_schema. MUST use the Write tool — files on disk are the deliverable, do NOT return file content as text.","tech-registry","<ABS_WORKFLOW>/codebase/tech-registry/","","","1"
+"5","Feature Map Writer","For each feature discovered, use the Write tool to create a markdown documentation file at <ABS_WORKFLOW>/codebase/feature-maps/{slug}.md with: ID, status, phase, requirements, component table. Also write <ABS_WORKFLOW>/codebase/feature-maps/_index.md with the feature table. After all writes, verify every intended file exists with Glob and return file count + absolute paths via output_schema. MUST use the Write tool — files on disk are the deliverable, do NOT return file content as text.","feature-maps","<ABS_WORKFLOW>/codebase/feature-maps/","","","1"
 ```
 
+**Path resolution (orchestrator MUST do BEFORE writing tasks.csv)**: substitute `<ABS_WORKFLOW>` with the absolute path to the project's `.workflow/` directory (e.g. `D:/maestro2/.workflow`). Agent Write tool requires absolute paths — passing relative `.workflow/...` literals will fail.
+
 **Columns**:
 
 | Column | Phase | Description |
@@ -125,6 +127,8 @@ Single wave generates `wave-1.csv`. No `prev_context` needed (all tasks independ
 6. **Single Wave**: All generators are independent, no wave ordering needed
 7. **Cleanup Temp Files**: Remove wave-1.csv after results are merged
 8. **DO NOT STOP**: Execute until all generators complete or fail
+9. **Absolute Paths Only**: All paths in `description` and `output_path` MUST be absolute before tasks.csv is written. Orchestrator substitutes `<ABS_WORKFLOW>` placeholder; never let it leak into a spawned agent's prompt.
+10. **Writer vs Returner Split**: Tasks 1-3 return data via `output_schema` (no file writes). Tasks 4-5 MUST write files via Write tool + verify with Glob. Mixing the two contracts (e.g., returning markdown content as text from tasks 4-5) is a contract violation.
 </invariants>
 
 <execution>

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

@@ -64,7 +64,7 @@ Follow '~/.maestro/workflows/harvest.md' Stages 1–8 (standard mode) or Stage 9
 - Quality enforcement rules → `quality` category
 - Wiki: `maestro wiki create --type <type> --slug harvest-<source_type>-<short_id>`
 - Spec: `maestro wiki append spec-<file> --body "<content>" --keywords "<kws>"` (unified write path) or `Skill({ skill: "spec-add", args: "<category> <content>" })`
-- Issue: append to `issues.jsonl` matching canonical schema
+- Issue: append to `issues.jsonl` matching canonical schema, with `source: "harvest"` field (distinguishes from `manage-issue-discover`, which uses `source: "discover"` — required for cross-skill dedup when both write concurrently)
 
 **Next steps:** `/manage-wiki health`, `maestro wiki list --type note`, `/wiki-connect --fix`, `/wiki-digest`, `/manage-issue list --source harvest`
 

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

@@ -155,7 +155,7 @@ Also writes to:
 5. **Discovery Board is Append-Only**: Never clear, modify, or recreate discoveries.ndjson
 6. **Skip on Failure**: If all perspective agents failed, skip dedup
 7. **Evidence Required**: Every finding must have file:line reference -- no speculative issues
-8. **Dedup Before Create**: Never append to issues.jsonl without deduplication
+8. **Dedup Before Create**: Never append to issues.jsonl without deduplication. Every appended record MUST include `source: "discover"` so concurrent writers (e.g. `manage-harvest` uses `source: "harvest"`) can be safely distinguished and deduplicated cross-skill.
 9. **Cleanup Temp Files**: Remove wave-{N}.csv after results are merged
 10. **DO NOT STOP**: Continuous execution until all waves complete
 </invariants>

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

@@ -73,7 +73,7 @@ After write operations, verify:
 <error_codes>
 | Code | Severity | Description |
 |------|----------|-------------|
-| E001 | error | No stores found — run `Skill({ skill: "manage-knowhow-capture" })` or create MEMORY.md |
+| E001 | error | No stores found — for workflow store run `Skill({ skill: "manage-knowhow-capture" })`; for system store run `Skill({ skill: "manage-memory-capture" })` or create MEMORY.md |
 | E002 | error | Entry ID or filename not found |
 | E003 | error | Prune requires at least one filter flag |
 | E004 | error | Cannot delete MEMORY.md — use `edit` subcommand instead |

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

@@ -6,7 +6,7 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 ---
 
 <purpose>
-Pure file-operation CRUD skill for the workflow knowhow library. No agent spawning, no CLI calls, no LLM inference — just parse-infer-append-confirm. Complements `quality-retrospective`: where retrospective extracts insights in bulk from completed phases, `manage-learn` captures one timeless insight at a time during active work. Both write to the same `specs/learnings.md` store, disambiguated by `source` and `lens` fields.
+Pure file-operation CRUD skill for the workflow knowhow library. No agent spawning, no CLI calls, no LLM inference — just parse-infer-append-confirm. Complements `quality-retrospective`: where retrospective extracts insights in bulk from completed phases, `manage-learn` captures one timeless insight at a time during active work. Both write to the same `.workflow/specs/learnings.md` store, disambiguated by `source` and `lens` fields.
 
 ```
 Parse Mode  →  Bootstrap Store  →  Execute Mode  →  Confirm
@@ -94,7 +94,7 @@ Verify `.workflow/` exists (E001 if not). If `.workflow/specs/learnings.md` miss
 2. **Auto-link phase** from `state.json` artifact registry. `--phase 0` forces null.
 3. **Generate INS-id**: `INS-{8 hex}` from `hash(insightText + timestamp)`.
 4. **Build row** with fields: id, title (first 80 chars), summary, source="manual", lens=null, category, tags (includes "manual"), phase, phase_slug, confidence, routed_to=null, created_at.
-5. **Append** entry to `specs/learnings.md` (append-only, never rewrite).
+5. **Append** entry to `.workflow/specs/learnings.md` (append-only, never rewrite).
 6. WikiIndexer auto-indexes the new entry (no manual index update needed).
 
 #### List Mode
@@ -129,7 +129,7 @@ Capture mode: display ID, category, phase, confidence, tags, and next-step comma
 - [ ] Mode parsed correctly (capture, list, search, show)
 - [ ] Learning store bootstrapped on first use
 - [ ] Capture: category inferred from keywords, phase auto-linked, INS-id generated
-- [ ] Capture: entry appended to specs/learnings.md (append-only)
+- [ ] Capture: entry appended to .workflow/specs/learnings.md (append-only)
 - [ ] List: filters applied, newest-first, respects --limit
 - [ ] Search: grep with weighted ranking across title/tags/summary
 - [ ] Show: full record displayed for valid INS-id

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

@@ -223,9 +223,9 @@ Display report: scope, tasks completed/blocked, reflection rounds, strategy adju
 | Result | Next Step |
 |--------|-----------|
 | All tests pass, refactoring complete | `$quality-sync` (update codebase docs) |
-| Test failures remain after refactor | `$quality-debug "{scope}"` |
+| Test failures remain after refactor | `$quality-debug "test failures in {scope} after refactor"` (debug expects bug description, not raw scope) |
 | No test suite available for scope | `$quality-auto-test "{phase}"` |
-| Partial completion (some blocked) | `$quality-debug "{scope}"` for blocked tasks |
+| Partial completion (some blocked) | `$quality-debug "blocked refactor tasks in {scope}: <task titles>"` |
 </execution>
 
 <error_codes>

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

@@ -8,7 +8,7 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 <purpose>
 Multi-lens retrospective for completed phases. Context-Agent Fork loads phase artifacts once;
 four parallel lens agents (technical, process, quality, decision) analyze independently;
-synthesizer distills insights; outputs are routed to spec stubs, knowhow tips, issues, and specs/learnings.md.
+synthesizer distills insights; outputs are routed to spec stubs, knowhow tips, issues, and .workflow/specs/learnings.md.
 
 ```
 +------------------------------------------------------------------+
@@ -132,7 +132,7 @@ Each artifact's type determines its outputs at `.workflow/{a.path}/`:
 7. **Archive before overwrite**: Move existing retrospective.{md,json} to `.history/` with timestamp before writing new ones
 8. **Spec learnings.md backward-compat**: Append to it only if it already exists -- never create it
 9. **Route confirmation**: Unless `-y`, present routing table and ask per-group before writing spec/issue/knowhow
-10. **Lessons always written**: Append to `specs/learnings.md` regardless of `--no-route` -- routing only controls spec/issue/knowhow creation
+10. **Lessons always written**: Append to `.workflow/specs/learnings.md` regardless of `--no-route` -- routing only controls spec/issue/knowhow creation
 </invariants>
 
 <execution>
@@ -294,6 +294,6 @@ Next steps: `$manage-status`, `$manage-issue "list --source retrospective"`, `$m
 - [ ] Synthesizer produces deduplicated insights with stable INS-ids
 - [ ] Routing applied per insight (spec/issue/knowhow/none) with confirmation
 - [ ] retrospective.{md,json} written to phase directory
-- [ ] Lessons appended to specs/learnings.md regardless of --no-route flag
+- [ ] Lessons appended to .workflow/specs/learnings.md regardless of --no-route flag
 - [ ] Existing retrospective archived before overwrite
 </success_criteria>

package/.codex/skills/security-audit/SKILL.md

@@ -9,6 +9,10 @@ Systematic security audit covering OWASP Top 10, dependency supply chain, secret
 CI/CD pipeline review, and optional STRIDE threat modeling. Three tiers control depth vs speed.
 </purpose>
 
+<required_reading>
+@~/.maestro/workflows/review.md
+</required_reading>
+
 <context>
 $ARGUMENTS -- Parse tier and scope:
 - Tier: `quick` (default) | `standard` | `deep`
@@ -142,6 +146,26 @@ CONCERNS: {count} critical findings require immediate action
 NEXT: $quality-review
 --- END STATUS ---
 ```
+
+**Register artifact on completion** (so retrospective/harvest can trace this audit):
+```
+Append to state.json.artifacts[]:
+{
+  id: nextArtifactId(artifacts, "review"),  // RVW-NNN (security-audit reuses review type)
+  type: "review",
+  subtype: "security-audit",
+  milestone: current_milestone || null,
+  phase: target_phase || null,
+  scope: target_phase ? "phase" : "standalone",
+  path: "scratch/{YYYYMMDD}-security-audit-{tier}-{slug}",
+  status: critical_count == 0 ? "completed" : "completed_with_concerns",
+  tier: tier,                              // quick|standard|deep
+  harvested: false,
+  created_at: start_time,
+  completed_at: now()
+}
+```
+Write findings report to the same `path` (severity matrix, file:line refs, remediation).
 </execution>
 
 <success_criteria>

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

@@ -1,7 +1,7 @@
 ---
 name: spec-remove
 description: Remove spec entry by ID
-argument-hint: "<entry-id>"
+argument-hint: "<entry-id> [--cascade]"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 ---
 
@@ -23,6 +23,9 @@ $ARGUMENTS — entry ID to remove (e.g., `spec-learnings-003`)
 - `maestro wiki list --type spec --json` — list all spec entries
 - `/spec-load --keyword <term>` — find by keyword
 - `maestro wiki search "<query>"` — BM25 search
+
+**Flags:**
+- `--cascade` — When the target spec is a ref-type entry (created via `spec-add --ref` and linked to a knowhow document), also delete the referenced knowhow file. Without this flag, ref-type removal leaves an orphan knowhow file.
 </context>
 
 <execution>
@@ -45,6 +48,8 @@ Display entry details. Ask user to confirm unless `-y` flag present.
 
 Run `maestro wiki remove-entry <entry-id>`. WikiIndexer auto-updates `wiki-index.json`.
 
+If `--cascade` is set and the entry has a `ref` attribute pointing to a knowhow file, also delete that file to avoid leaving an orphan.
+
 ### Step 5: Verify & Report
 
 Confirm removal via `maestro wiki get <entry-id>` (should return not-found). Display removed ID, source file, and commands for verify/re-add.
@@ -65,5 +70,6 @@ Confirm removal via `maestro wiki get <entry-id>` (should return not-found). Dis
 - [ ] User confirmed removal
 - [ ] Entry removed via `maestro wiki remove-entry`
 - [ ] Wiki index auto-updated
-- [ ] Confirmation displayed
+- [ ] If `--cascade` and entry has a `ref` attribute: referenced knowhow file deleted, orphan avoided
+- [ ] Confirmation displayed (and cascaded knowhow path if applicable)
 </success_criteria>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-flow",
-  "version": "0.4.12",
+  "version": "0.4.13",
   "description": "Workflow orchestration CLI with MCP endpoint support and extensible architecture",
   "type": "module",
   "imports": {

package/workflows/agy-instructions.md

@@ -108,6 +108,8 @@ For point-to-point delivery, use `send_message` directly.
 
 ### Search — Query Before Acting
 
+**Before planning or implementing any task, search wiki and spec first** — the knowledge base contains reusable methods, tools, and hard-won experience. Load the right knowledge at the right time: search before you plan, load relevant entries before you implement, and revisit when you hit unfamiliar territory mid-task.
+
 When tackling unfamiliar domains or cross-cutting concerns, search existing knowledge first:
 - `maestro spec load --category <cat>` — load rules by category (coding/arch/debug/test/review/learning)
 - `maestro spec load --keyword <kw>` — cross-category keyword match

package/workflows/auto-test.md

@@ -36,7 +36,7 @@ specs_arch = maestro spec load --category arch
 
 ### Step 1: Read State & Route
 
-Read project state signals and auto-select scenario source. This is the **sole branch point** in the pipeline.
+Read project state signals and auto-select scenario source. This is the **primary branch point, with Route-specific extraction in Step 2** (after Step 2 normalization, the downstream pipeline is identical).
 
 ```
 Priority: Resume > Re-run > Spec > Gap > Code
@@ -54,6 +54,11 @@ Priority: Resume > Re-run > Spec > Gap > Code
    Action: load failed/blocked scenarios with status reset to pending
    Skip to Step 4 (scenarios pre-loaded, plan confirmation)
 
+# Note: `integration/state.json` and `business/business-test-report.json` are
+# legacy compat paths read for backward compatibility only. The new pipeline
+# writes exclusively to `.tests/auto-test/state.json` and `.tests/auto-test/report.json`
+# (these legacy paths are superseded; see migration table at end of file).
+
 3. SPEC:
    Check: .workflow/blueprint/BLP-*/requirements/REQ-*.md exists
    Resolve: SPEC_DIR from index.json.blueprint_ref or most recent BLP-*/

package/workflows/brainstorm.md

@@ -329,23 +329,37 @@ When `ui-designer` is among the selected roles, establish the project's visual d
 
 For EACH selected role, spawn a `role-design-author` agent in parallel. Each agent produces a multi-file analysis under `{output_dir}/{role}/`.
 
+**Path resolution (orchestrator responsibility, BEFORE invocation)**:
+- Resolve `{output_dir}` to an **absolute path** (e.g., `D:/proj/.workflow/scratch/brainstorm-foo-20260521`). Do NOT pass the literal `.workflow/...` relative form — agent Write tool requires absolute paths.
+- Expand `~/` in `role_template_path` to the user home absolute path.
+- For absent optional fields (e.g., `style_skill` when role ≠ ui-designer, `design_research` when Step 1.7 was skipped), pass the literal string `null` — never a conditional placeholder like `{x if y}`.
+
 ```
 Agent({
   subagent_type: "role-design-author",
   prompt: """
     role_name: {role}
-    role_template_path: ~/.maestro/templates/planning-roles/{role}.md
-    guidance_path: {output_dir}/guidance-specification.md
-    output_dir: {output_dir}/{role}/
+    role_template_path: <ABSOLUTE path to planning-roles/{role}.md>
+    guidance_path: <ABSOLUTE {output_dir}>/guidance-specification.md
+    output_dir: <ABSOLUTE {output_dir}>/{role}/
     feature_list: <F-id + slug + title rows from guidance §10>
-    design_research: {output_dir}/design-research.md if exists, else null
-    project_specs: {specs_content or null}
-    user_context: {session.role_decisions[role] if any}
-    style_skill: {style_skill_path if role == ui-designer and provided}
+    design_research: <ABSOLUTE path>/design-research.md  OR  null
+    project_specs: <specs_content text>  OR  null
+    user_context: <session.role_decisions[role] text>  OR  null
+    style_skill: <ABSOLUTE style-skill SKILL.md path>  OR  null
+
+    Follow the Output Contract in `.claude/agents/role-design-author.md` (§1 Role Mandate,
+    §2 Decision Digest with 4 tables, §3 Cross-Cutting Foundations, §4 File Index, §5 TODOs)
+    — this is authoritative. The role template's "Brainstorming Analysis Structure" section
+    is legacy single-file scaffolding; ignore it for file layout. Use the role template ONLY
+    for §3 subsection headings (via the "MUST-Have Sections (Brainstorming)" block when present).
 
-    Write the analysis files per the role template's "Brainstorming Analysis Structure".
     Reference guidance decisions by ID (e.g., SA-03) — do NOT copy decision text.
     All behavioural statements MUST use RFC 2119 keywords.
+
+    MUST use the Write tool to persist every file under output_dir/. After all writes, verify
+    with Glob that `analysis.md` and each `analysis-F-*.md` exist on disk, then emit the
+    `TASK COMPLETE` return protocol. Returning analysis as text without files is failure.
   """,
   run_in_background: false
 })

package/workflows/claude-instructions.md

@@ -21,6 +21,8 @@ Available CLI endpoints are dynamically defined by the config file
 
 ### Search — Query Before Acting
 
+**Before planning or implementing any task, search wiki and spec first** — the knowledge base contains reusable methods, tools, and hard-won experience. Load the right knowledge at the right time: search before you plan, load relevant entries before you implement, and revisit when you hit unfamiliar territory mid-task.
+
 When tackling unfamiliar domains or cross-cutting concerns, search existing knowledge first:
 - `maestro spec load --category <cat>` — load rules by category (coding/arch/debug/test/review/learning)
 - `maestro spec load --keyword <kw>` — cross-category keyword match

package/workflows/codex-instructions.md

@@ -1,5 +1,12 @@
 # Codex Code Guidelines
+## Delegate & CLI
 
+- **Delegate Usage**: @~/.maestro/workflows/delegate-usage.md
+- **CLI Endpoints Config**: @~/.maestro/cli-tools.json
+
+**Strictly follow the cli-tools.json configuration**
+
+Available CLI endpoints are dynamically defined by the config file
 
 ## Code Quality Standards
 
@@ -55,96 +62,22 @@
 - Treat all pre-existing uncommitted changes as intentional work-in-progress by other tools
 
 
-## System Optimization
-
-**Direct Binary Calls**: Always call binaries directly in `functions.shell`, set `workdir`, avoid shell wrappers (`bash -lc`, `cmd /c`, etc.)
-
-**Text Editing Priority**:
-1. Use `apply_patch` tool for all routine text edits
-2. Fall back to `sed` for single-line substitutions if unavailable
-3. Avoid Python editing scripts unless both fail
-
-**apply_patch invocation**:
-```json
-{
-  "command": ["apply_patch", "*** Begin Patch\n*** Update File: path/to/file\n@@\n- old\n+ new\n*** End Patch\n"],
-  "workdir": "<workdir>",
-  "justification": "Brief reason"
-}
-```
-
-**Windows UTF-8 Encoding** (before commands):
-```powershell
-[Console]::InputEncoding  = [Text.UTF8Encoding]::new($false)
-[Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)
-chcp 65001 > $null
-```
-
-## Context Acquisition (MCP Tools Priority)
-
-**For task context gathering and analysis, ALWAYS prefer MCP tools**:
+## Knowledge System
 
-1. **mcp__ace-tool__search_context** - HIGHEST PRIORITY for code discovery
-   - Semantic search with real-time codebase index
-   - Use for: finding implementations, understanding architecture, locating patterns
-   - Example: `mcp__ace-tool__search_context(project_root_path="/path", query="authentication logic")`
+### Search — Query Before Acting
 
-2. **smart_search** - Fallback for structured search
-   - Use `smart_search(query="...")` for keyword/regex search
-   - Use `smart_search(action="find_files", pattern="*.ts")` for file discovery
-   - Supports modes: `auto`, `hybrid`, `exact`, `ripgrep`
+**Before planning or implementing any task, search wiki and spec first** — the knowledge base contains reusable methods, tools, and hard-won experience. Load the right knowledge at the right time: search before you plan, load relevant entries before you implement, and revisit when you hit unfamiliar territory mid-task.
 
-3. **read_file** - Batch file reading
-   - Read multiple files in parallel: `read_file(path="file1.ts")`, `read_file(path="file2.ts")`
-   - Supports glob patterns: `read_file(path="src/**/*.config.ts")`
+- `maestro spec load --category <cat>` — load rules by category (coding/arch/debug/test/review/learning)
+- `maestro spec load --keyword <kw>` — cross-category keyword match
+- `maestro wiki search "<query>"` — full-text search across all knowhow
+- `maestro wiki list --category <cat>` → `maestro wiki load <id>` — browse then load full detail
 
-**Priority Order**:
-```
-ACE search_context (semantic) → smart_search (structured) → read_file (batch read) → shell commands (fallback)
-```
-
-**NEVER** use shell commands (`cat`, `find`, `grep`) when MCP tools are available.
-
-## Workflow Session Awareness
-
-| Workflow | Directory | Summary File |
-|----------|-----------|-------------|
-| `workflow-plan` | `.workflow/active/WFS-*/` | `workflow-session.json` |
-| `workflow-lite-plan` | `.workflow/.lite-plan/{date}-{slug}/` | `plan.json` |
-| `analyze-with-file` | `.workflow/.analysis/ANL-*/` | `conclusions.json` |
-| `multi-cli-plan` | `.workflow/.multi-cli-plan/*/` | `session-state.json` |
-| `lite-fix` | `.workflow/.lite-fix/*/` | `fix-plan.json` |
-| Other | `.workflow/.debug/`, `.workflow/.scratchpad/`, `.workflow/archives/` | — |
-
-Before starting work, scan recent sessions (7 days) to avoid conflicts and reuse prior work:
-- Overlapping file scope → warn, suggest referencing prior session
-- Complementary findings → feed into current task context
-
-
-## Knowledge Capture
+### Knowledge Capture
 
 - **Spec writes** → always `<spec-entry>` closed-tag format with `category`, `keywords`, `date`, `source`. Never raw Markdown. Route through `spec-add` when possible.
 - **Capture signal** → when execution surfaces non-obvious knowledge (plan deviation, retry pattern, root cause, constraint violation), ask user once whether to persist it. Match category to content: decisions→`arch`, pitfalls→`debug`/`learning`, patterns→`coding`, rules→`quality`.
 - **Promotion** → at milestone close, scan learnings for repeated keywords (≥2 entries) and offer to graduate them into formal conventions.
 - **Traceability** → every entry needs a source anchor: `file:line`, `INS-{id}`, commit, or phase path.
 
-## Execution Checklist
-
-**Before**:
-- [ ] Understand PURPOSE and TASK clearly
-- [ ] Use ACE search_context first, fallback to smart_search for discovery
-- [ ] Use read_file to batch read context files, find 3+ patterns
-- [ ] Check RULES templates and constraints
-
-**During**:
-- [ ] Follow existing patterns exactly
-- [ ] Write tests alongside code
-- [ ] Run tests after every change
-- [ ] Commit working code incrementally
-
-**After**:
-- [ ] All tests pass
-- [ ] Coverage meets target
-- [ ] Build succeeds
-- [ ] All EXPECTED deliverables met
-- [ ] Non-obvious knowledge surfaced? → offer `spec-add`
+

package/workflows/debug.md

@@ -3,7 +3,7 @@
 Debug issues using scientific method with subagent isolation. Supports three modes:
 
 1. **Standalone**: User describes issue, gather symptoms via 5 questions
-2. **From UAT**: --from-uat reads uat.md gaps as pre-filled symptoms (skip gathering)
+2. **From UAT**: --from-uat reads uat.md gaps as pre-filled symptoms (skip gathering). Input-only: does not write back to uat.md/test artifacts (test workflow is the sole caller and owns uat.md writes).
 3. **Parallel**: --parallel spawns one debug agent per gap cluster concurrently
 
 Output: understanding.md + evidence.ndjson per investigation.

package/workflows/harvest.md

@@ -40,7 +40,7 @@ Unlike `retrospective.md` which is phase-scoped and post-execution, harvest oper
 | `--dry-run` | Preview extracted items without writing to any store |
 | `-y` / `--yes` | Skip confirmation prompts, accept all routing |
 | `--min-confidence N` | Minimum extraction confidence 0.0-1.0 (default: 0.5) |
-| `--prune` | State hygiene mode: classify artifacts, graduate harvested ones to knowhow, archive from state.json, prune accumulated_context |
+| `--prune` | State hygiene mode: classify artifacts, graduate harvested ones to knowhow, archive from state.json, prune accumulated_context. **Note:** `harvest --prune` *promotes* artifacts to knowhow (and trims state.json); this differs from `knowhow.md`'s `prune` operation which *deletes* knowhow entries. The two `--prune` flags share a name but operate on different stores in opposite directions. |
 | `--age N` | Graduation age threshold in days (default: 14). Only artifacts older than N days are prune candidates. Used with `--prune` |
 
 ---

package/workflows/impeccable.md

@@ -1,5 +1,7 @@
 # Impeccable Harvest Workflow
 
+> **Note**: Post-harvest hook, distinct from `/maestro-impeccable` command. This file is the harvest workflow invoked AFTER an impeccable run; it is not the impeccable command entry itself (see `chainMap['impeccable_*']` in `maestro.md`).
+
 Post-execution knowledge capture for maestro-impeccable commands. Extracts design decisions and persists to `.workflow/knowhow/` + `specs/`.
 
 ---

package/workflows/issue-analyze.md

@@ -3,109 +3,23 @@
 > **DEPRECATED**: Superseded by `issue-gaps-analyze.md` which adds batch support and context.md output.
 > Use `maestro-analyze --gaps [ISS-ID]` instead.
 
-Root cause analysis for a specific issue using CLI exploration and codebase context gathering.
+This workflow's executable steps have been removed to prevent divergent implementations.
 
-## Input
+## Migration
 
-- `$ARGUMENTS`: `<ISS-ID> [--tool gemini|qwen] [--depth standard|deep]`
-- Operates on `.workflow/issues/`
+| Old usage | New usage |
+|-----------|-----------|
+| `manage-issue-analyze ISS-ID` | `/maestro-analyze --gaps ISS-ID` |
+| `manage-issue-analyze` (batch) | `/maestro-analyze --gaps` |
+| `manage-issue-plan ISS-ID` (follow-up) | `/maestro-plan --gaps ISS-ID` |
 
----
+## See Also
 
-### Step 1: Parse Arguments
+- `issue-gaps-analyze.md` — current implementation (single + batch, classification, parallel exploration, context.md)
+- `issue-gaps-analyze.codex.md` — codex variant using `spawn_agents_on_csv` waves
+- `issue-execute.md` — downstream execution after planning
 
-```
-Extract ISS-ID (required, pattern ISS-\d{8}-\d{3}).
-Flags: --tool gemini|qwen (default: gemini), --depth standard|deep (default: standard)
-```
+## Notes
 
----
-
-### Step 2: Load Issue and Validate
-
-```
-Load ISS-ID from .workflow/issues/issues.jsonl → fatal if file missing or ID not found.
-Status check: open/registered → proceed; other → warn but continue (non-destructive).
-```
-
----
-
-### Step 3: Gather Codebase Context
-
-```
-Extract keywords from issue title, description, location, affected_components.
-
-Standard depth: grep keywords in source files → top 20 paths, read 10 lines around
-  top 5 matches.
-Deep depth: standard grep + semantic Agent search (error handling, data flow, deps),
-  merge results.
-
-Build CODEBASE_CONTEXT: related files, key snippets (max 50 lines), dependency chain.
-```
-
----
-
-### Step 4: Run CLI Analysis
-
-```
-Delegate root cause analysis with issue details + CODEBASE_CONTEXT:
-
-  maestro delegate "Root cause analysis for {ISS-ID}: {ISSUE.title}
-  ISSUE: title, description, severity, location, fix_direction
-  CODEBASE CONTEXT: {CODEBASE_CONTEXT}
-  TASK: Identify root cause (file:line) → assess impact → list related files → rate confidence → suggest fix
-  EXPECTED: JSON { root_cause, impact, related_files[], confidence, suggested_approach }
-  CONSTRAINTS: Evidence-only, no speculation
-  " --to {TOOL} --mode analysis
-
-Validate response: all required fields present.
-Parse failure → save raw output to issue feedback for review.
-```
-
----
-
-### Step 5: Build Analysis Record
-
-```
-Construct IssueAnalysis:
-  { root_cause, impact, related_files, confidence, suggested_approach, analyzed_at: NOW_ISO, analyzed_by: TOOL }
-```
-
----
-
-### Step 6: Update Issue in JSONL
-
-```
-Read-modify-write issues.jsonl:
-  Set issue.analysis = ANALYSIS, updated_at = NOW_ISO
-  Append issue_history: actor "analysis-agent", note "confidence: {confidence}"
-  Status unchanged (analysis is metadata enrichment).
-Verify: re-read file, confirm analysis field present.
-```
-
----
-
-### Step 7: Display Summary and Next Steps
-
-```
-Display: root cause, impact, confidence, related files, suggested approach.
-
-Next steps:
-  - manage-issue-plan {ISS-ID} (generate solution | --tool {TOOL})
-  - manage-issue status {ISS-ID}
-```
-
----
-
-## Output
-
-- **Updated**: `.workflow/issues/issues.jsonl` -- issue record enriched with `analysis` field
-- **Analysis fields**: root_cause, impact, related_files, confidence, suggested_approach, analyzed_at, analyzed_by
-
-## Quality Criteria
-
-- Analysis grounded in actual codebase evidence (file:line references)
-- JSON result validated before writing to JSONL
-- Issue status unchanged (analysis is non-destructive enrichment)
-- Read-modify-write pattern preserves other issues in JSONL
-- Next-step routing guides user to solution planning
+- Issue records analyzed by the new pipeline still write to `.workflow/issues/issues.jsonl` with `analysis` field (root_cause, impact, related_files, confidence, suggested_approach, analyzed_at, analyzed_by).
+- Status is unchanged by analysis (non-destructive enrichment).

package/workflows/issue-discover.md

@@ -148,7 +148,7 @@ Display summary: session ID, mode, raw/unique counts, per-perspective breakdown,
 Next steps:
   - manage-issue list --severity critical
   - manage-issue list
-  - manage-issue-discover by-prompt "..."
+  - see also: /manage-issue-discover usage docs (by-prompt mode for focused scans)
 ```
 
 ---
@@ -211,8 +211,7 @@ Display summary: session, prompt, rounds, raw/unique counts, per-dimension + sev
 
 Next steps:
   - manage-issue list --source discovery
-  - manage-issue-discover (full 8-perspective scan)
-  - manage-issue-discover by-prompt "..." (explore another area)
+  - see also: /manage-issue-discover usage docs (full 8-perspective scan and by-prompt mode)
 ```
 
 ---

package/workflows/issue-execute.md

@@ -25,7 +25,7 @@ Flags: --executor claude-code|codex|gemini (default: claude-code), --dry-run (de
 
 ```
 Load ISS-ID from .workflow/issues/issues.jsonl → fatal if file missing or ID not found.
-Require issue.solution with non-empty steps[] → error if missing (run manage-issue-plan first).
+Require issue.solution with non-empty steps[] → error if missing (run `maestro-plan --gaps {ISS-ID}` first).
 Resolve EXECUTOR → CLI tool (claude-code→claude, codex→codex, gemini→gemini), all with --mode write.
 ```