maestro-flow 0.4.11 → 0.4.13

package/workflows/business-test.md

@@ -28,10 +28,10 @@ Generator-Critic loop: max 3 iterations per layer to distinguish test defects fr
 **Load spec package:**
 
 ```
-1. Read ${PHASE_DIR}/index.json -> extract spec_ref (if present)
-2. IF --spec provided: SPEC_DIR = .workflow/.spec/{spec_ref}/
-   ELSE IF index.json.spec_ref: SPEC_DIR = .workflow/.spec/{spec_ref}/
-   ELSE: try .workflow/.spec/SPEC-*/ (most recent)
+1. Read ${PHASE_DIR}/index.json -> extract blueprint_ref (if present)
+2. IF --spec provided: SPEC_DIR = .workflow/blueprint/{blueprint_ref}/
+   ELSE IF index.json.blueprint_ref: SPEC_DIR = .workflow/blueprint/{blueprint_ref}/
+   ELSE: try .workflow/blueprint/SPEC-*/ (most recent)
 
 3. IF SPEC_DIR found:
    - Read requirements/_index.md (requirement summary + traceability matrix)
@@ -189,7 +189,7 @@ Write `business-test-plan.json` to `.tests/business/`:
 ```json
 {
   "phase": "{phase}",
-  "spec_ref": "{SPEC_DIR name or 'degraded'}",
+  "blueprint_ref": "{SPEC_DIR name or 'degraded'}",
   "spec_mode": "full|degraded",
   "generated_at": "{ISO timestamp}",
   "layers": {
@@ -363,7 +363,7 @@ Write `.tests/business/business-test-report.json`:
 ```json
 {
   "phase": "{phase}",
-  "spec_ref": "{spec reference}",
+  "blueprint_ref": "{spec reference}",
   "spec_mode": "full|degraded",
   "completed_at": "{ISO timestamp}",
   "execution_mode": "gen-code|agent",
@@ -432,7 +432,7 @@ Write `.tests/business/business-test-summary.md`:
 ```markdown
 ---
 phase: {phase}
-spec_ref: {spec reference}
+blueprint_ref: {spec reference}
 completed_at: {ISO timestamp}
 verdict: passed|gaps_found
 ---

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/codebase-rebuild.md

@@ -72,7 +72,7 @@ Used in Step 2-4 to produce architecture-aware documentation.
 
 ```
 Group components into features by:
-  directory proximity, naming patterns, import relationships, .spec/ mapping.
+  directory proximity, naming patterns, import relationships, blueprint/ mapping.
 
 For each feature group: derive name, collect component IDs, map requirements and phase.
 Build feature entry:
@@ -91,7 +91,7 @@ Back-fill component.feature_ids with assigned feature IDs.
 ### Step 4: Map Requirements (if .spec exist)
 
 ```
-If .workflow/.spec/ exist: parse each SPEC-*/requirements/REQ-*.md,
+If .workflow/blueprint/ exist: parse each SPEC-*/requirements/REQ-*.md,
 match to features by keyword analysis. Build requirement entry:
   {
     "id": "REQ-{NNN}",
@@ -102,13 +102,13 @@ match to features by keyword analysis. Build requirement entry:
     "acceptance_criteria": ["{criteria}"]
   }
 
-If no .spec: requirements = [] (populated later by spec-generate).
+If no blueprint: requirements = [] (populated later by maestro-blueprint).
 ```
 
 ### Step 5: Record Architecture Decisions (if ADRs exist)
 
 ```
-If .workflow/.spec/*/architecture/ADR-*.md exist: parse each ADR,
+If .workflow/blueprint/*/architecture/ADR-*.md exist: parse each ADR,
 map to components by keyword analysis. Build ADR entry:
   {
     "id": "ADR-{NNN}",

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

@@ -9,7 +9,7 @@ Unlike `retrospective.md` which is phase-scoped and post-execution, harvest oper
 ## Prerequisites
 
 - `.workflow/` initialized (`.workflow/state.json` exists)
-- At least one artifact source present (analysis, brainstorm, debug, lite-plan, lite-fix, scratchpad, or active session)
+- At least one artifact source present (analysis, brainstorm, import, debug, lite-plan, lite-fix, scratchpad, or active session)
 - For wiki routing: `maestro wiki` CLI available
 
 ---
@@ -27,16 +27,21 @@ Unlike `retrospective.md` which is phase-scoped and post-execution, harvest oper
 /manage-harvest <target> --to issue                  → force all findings to issue
 /manage-harvest <target> --to auto                   → auto-classify routing (default)
 /manage-harvest <target> --dry-run                   → preview without writing
+/manage-harvest --prune                              → classify artifacts, graduate to knowhow, archive from state.json
+/manage-harvest --prune --age 14                     → only graduate artifacts older than 14 days
+/manage-harvest --prune --dry-run                    → preview prune plan without modifying state.json
 ```
 
 | Flag | Effect |
 |------|--------|
 | `--to <target>` | Force routing target: `wiki`, `spec`, `issue`, `auto` (default: auto) |
-| `--source <type>` | Filter by source type: `analysis`, `brainstorm`, `debug`, `lite-plan`, `lite-fix`, `scratchpad`, `session`, `all` |
+| `--source <type>` | Filter by source type: `analysis`, `brainstorm`, `import`, `debug`, `lite-plan`, `lite-fix`, `scratchpad`, `session`, `all` |
 | `--recent N` | Only scan artifacts updated within last N days (default: 30) |
 | `--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. **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` |
 
 ---
 
@@ -44,10 +49,11 @@ Unlike `retrospective.md` which is phase-scoped and post-execution, harvest oper
 
 ```
 Verify .workflow/ exists (else E001). Parse flags and first non-flag token:
-  mode: "scan" (no target) | "session" (ID match) | "path" (explicit path)
+  mode: "scan" (no target) | "session" (ID match) | "path" (explicit path) | "prune" (--prune flag)
   Defaults: target_filter=auto, source_filter=all, recent_days=30,
-            dry_run=false, auto_yes=false, min_confidence=0.5
+            dry_run=false, auto_yes=false, min_confidence=0.5, age_threshold=14
 Invalid --to → E002. Invalid --source → E003.
+If --prune: mode = "prune", jump to Stage 9 (skip Stages 2-8).
 ```
 
 ---
@@ -61,12 +67,13 @@ Scan `.workflow/` for harvestable artifacts. Each source type has a known struct
 | Source Type | Scan Path | Key Files | ID Pattern |
 |-------------|-----------|-----------|------------|
 | `analysis` | `.workflow/.analysis/ANL-*/` | `conclusions.json`, `*.md` | `ANL-*` |
-| `brainstorm` | `.workflow/scratch/brainstorm-*/` | `guidance-specification.md`, `brainstorm-*.md` | directory name |
+| `brainstorm` | `.workflow/scratch/brainstorm-*/` | `guidance-specification.md`, `*/analysis.md`, `design-research.md` | directory name |
 | `lite-plan` | `.workflow/.lite-plan/*/` | `plan.json`, `plan-overview.md` | directory name |
 | `lite-fix` | `.workflow/.lite-fix/*/` | `fix-plan.json` | directory name |
 | `debug` | `.workflow/.debug/*/` | `debug-log.md`, `hypothesis-*.md` | directory name |
 | `scratchpad` | `.workflow/.scratchpad/` | `*.md`, `*.json` | filename |
 | `session` | `.workflow/active/WFS-*/` | `workflow-session.json` | `WFS-*` |
+| `import` | `.workflow/scratch/*-import-*/` | `context-package.json`, `source.*` | directory name |
 | `knowhow` | `.workflow/knowhow/` | `*.md`, `digest-*.md` | filename |
 
 Scan each source type (filtered by `--source`). For each matching directory/file within `--recent` window, extract: `source_type`, `id`, `path`, `title` (from JSON or H1), `updated_at`, `summary`, `file_count`.
@@ -125,11 +132,17 @@ Parse content to identify discrete knowledge items. Each source type has specifi
 - `risks[]` → each risk is a fragment
 - Markdown sections with `## ` headings → section-level fragments
 
-**Brainstorm (`guidance-specification.md` + notes):**
-- `## Options` or `## Approaches` → each option is a fragment
-- `## Decision` or `## Recommendation` → decision fragment
-- `## Trade-offs` → trade-off fragments
-- Action items (lines starting with `- [ ]` or `TODO`) → task fragments
+**Brainstorm (`guidance-specification.md` + `{role}/analysis.md` + `design-research.md`):**
+- guidance §4-§N Role Decisions tables → each row is a decision fragment
+- guidance §10 Feature Decomposition rows → each feature is a fragment
+- guidance §12 Cross-Role Resolutions table → each resolution is a decision fragment
+- `{role}/analysis.md` §2 Decision Digest tables → decision / interface / position fragments by role
+- `{role}/analysis.md` §3 Cross-Cutting Foundations subsections → architectural / data-model / pitfall fragments by role
+- `{role}/analysis.md` §4 File Index → navigate to sub-files:
+  - `{role}/analysis-F-{id}-{slug}.md` → per-feature decision fragments (one file = one fragment)
+  - `{role}/findings-{slug}.md` → finding / discovery fragments
+- `{role}/analysis.md` §5 Outstanding TODOs → task fragments
+- `design-research.md` "Extractable Patterns" sections → pattern reference fragments
 
 **Lite-plan (`plan.json`):**
 - `tasks[]` → each with rationale → decision fragments
@@ -141,6 +154,14 @@ Parse content to identify discrete knowledge items. Each source type has specifi
 - `fix_strategy` → pattern fragment
 - `verification` → test/validation fragment
 
+**Import (`context-package.json` + `source.*`):**
+- `requirements[]` → each requirement is a feature fragment
+- `constraints[]` → each constraint is a decision fragment
+- `non_goals[]` → each non-goal is a scope fragment
+- `insights[]` → each insight is a knowledge fragment
+- `domain.terminology[]` → each term is a terminology fragment
+- `open_questions[]` → each question is a task/investigation fragment
+
 **Debug (`debug-log.md`, `hypothesis-*.md`):**
 - Final diagnosis → bug fragment
 - Verified hypothesis → pattern/knowhow fragment
@@ -174,6 +195,8 @@ fragment = {
 
 Filter by `--min-confidence`.
 
+**Context Package shortcut**: If any artifact has a `context-package.json` (check `state.json.artifacts[].context_package`), harvest can use it as a pre-extracted summary — skip detailed file parsing and directly convert context-package fields to fragments. The per-item `ref` field provides traceability to original sources.
+
 ---
 
 ## Stage 4: classify_routing
@@ -351,3 +374,154 @@ Next:
   → Connect wiki graph: Skill({ skill: "wiki-connect", args: "--fix" })
   → View specs: Skill({ skill: "spec-load", args: "--role implement" })
 ```
+
+---
+
+## Stage 9: state_hygiene (--prune)
+
+When `--prune` flag is present, skip Stages 2-8 and run state.json hygiene instead. Manages three concerns: **artifact graduation** (harvested → archived via knowhow), **accumulated_context pruning** (remove resolved/stale entries), and **integrity validation**.
+
+### 9a. Load state
+
+```
+Read .workflow/state.json → { artifacts[], accumulated_context{}, current_milestone, milestones[] }
+Read .workflow/harvest/harvest-log.jsonl → build harvested_map: { [source_id]: { fragment_count, routed_count, last_harvested } }
+Defaults: age_threshold = --age value (default 14 days), dry_run = --dry-run flag
+```
+
+### 9b. Classify artifacts
+
+For each artifact in `artifacts[]`, assign a classification:
+
+| Classification | Criteria | Action |
+|---|---|---|
+| `active` | milestone == current_milestone OR age < age_threshold OR referenced by active plan (type=plan, status=completed, linked execute not completed) | **Keep** in artifacts[] |
+| `graduated` | harvested == true AND not active | **Graduate** → knowhow → archive |
+| `stale` | harvested == false AND not active AND age > age_threshold | **Suggest** harvest first |
+| `protected` | type ∈ {plan, execute} AND linked downstream artifact is active | **Keep** regardless of age |
+
+Age = days since `completed_at` (or `created_at` if never completed).
+
+"Referenced by active plan": artifact X is protected if any plan artifact has `depends_on == X.id` or any execute artifact in same phase is active.
+
+### 9c. Classify accumulated_context
+
+Scan `accumulated_context` sub-arrays:
+
+| Field | Prune Criteria | Keep Criteria |
+|---|---|---|
+| `key_decisions[]` | Entry exists verbatim in `specs/architecture-constraints.md` (deduplicated to spec) | Not yet in specs |
+| `deferred[]` | status ∈ {"resolved", "cancelled", "superseded"} | status ∈ {"open", "deferred"} |
+| `blockers[]` | status == "resolved" | status ∈ {"open", "investigating"} |
+
+### 9d. Preview
+
+```
+=== STATE HYGIENE PLAN ===
+
+  Artifacts (23 total):
+    active:     8   (keep)
+    graduated:  11  (→ knowhow → archive)
+    stale:      3   (suggest harvest first)
+    protected:  1   (keep)
+
+  Accumulated Context:
+    key_decisions:  12 total → 4 prunable (already in specs)
+    deferred:        5 total → 2 prunable (resolved)
+    blockers:        3 total → 1 prunable (resolved)
+
+  Stale artifacts (not yet harvested):
+    ANL-003  analysis  2026-03-15  "Security audit P2"
+    BRN-002  brainstorm 2026-03-10  "Cache strategy"
+    WFS-005  session   2026-03-08  "Feature toggle impl"
+    → Run: /manage-harvest ANL-003 BRN-002 WFS-005  (harvest before graduating)
+
+  Estimated state.json reduction: 23 → 9 artifacts, 20 → 13 context entries
+```
+
+`--dry-run` → display and exit. Otherwise (unless `-y`), AskUserQuestion:
+- "Proceed" — apply all
+- "Graduate only" — archive graduated artifacts, skip accumulated_context prune
+- "Harvest stale first" — run harvest on stale artifacts, then re-classify
+- "Abort"
+
+### 9e. Graduate to knowhow
+
+For each `graduated` artifact:
+
+1. **Build compact summary** from harvest-log entries:
+   - Fragment count, routing breakdown (N wiki, N spec, N issue)
+   - Top 3 fragment titles as representative items
+   - Original path for disk reference
+
+2. **Create knowhow entry**:
+   ```bash
+   maestro wiki create --type knowhow \
+     --slug "graduated-{type}-{short_id}" \
+     --title "Graduated: {type} {id}" \
+     --tags "graduated,{type},{milestone}" \
+     --body "{compact_summary}"
+   ```
+
+3. **Archive in state.json**: Move from `artifacts[]` to `artifact_archive[]`:
+   ```json
+   {
+     "id": "ANL-001",
+     "type": "analyze",
+     "milestone": "M1",
+     "path": "scratch/20260315-analyze-P2-security",
+     "graduated_at": "ISO-8601",
+     "knowhow_ref": "graduated-analyze-ANL-001",
+     "summary": "Security audit P2 — 8 fragments → 3 wiki, 2 spec, 3 issue"
+   }
+   ```
+
+4. **Files on disk**: NOT deleted. The `.workflow/{path}/` directory remains for reference. Only the state.json entry moves.
+
+### 9f. Prune accumulated_context
+
+For each prunable entry identified in 9c:
+- `key_decisions[]`: remove entry, log `[PRUNE] key_decision: "{text}" (deduplicated to spec)`
+- `deferred[]`: remove entry, log `[PRUNE] deferred: "{title}" (status: {status})`
+- `blockers[]`: remove entry, log `[PRUNE] blocker: "{title}" (resolved)`
+
+### 9g. Apply
+
+1. **Backup**: Copy `state.json` → `state.json.backup-prune-{timestamp}`
+2. **Write**: Updated state.json with:
+   - `artifacts[]` = active + protected entries only
+   - `artifact_archive[]` = existing archive + newly graduated
+   - `accumulated_context` = pruned version
+   - `last_pruned`: ISO-8601 timestamp
+3. **Validate**: Re-read and confirm artifact count matches expected
+
+### 9h. Report
+
+Append prune results to harvest report:
+
+```
+=== PRUNE COMPLETE ===
+
+  Graduated:  11 artifacts → knowhow
+  Archived:   11 entries moved to artifact_archive[]
+  Pruned:     4 key_decisions + 2 deferred + 1 blocker = 7 context entries
+
+  State reduction: 23 → 9 artifacts, 20 → 13 context entries
+  Backup: .workflow/state.json.backup-prune-20260521T143022
+
+  Stale (not harvested, action needed):
+    → /manage-harvest ANL-003 BRN-002 WFS-005
+
+  Next:
+    → Review graduated knowhow: maestro wiki list --type knowhow --tags graduated
+    → Re-run prune after harvesting stale: /manage-harvest --prune
+```
+
+### Safety invariants
+
+1. **Never prune current milestone artifacts** — active classification takes precedence
+2. **Never delete files on disk** — only state.json entries move; files remain for reference/audit
+3. **Backup before write** — always create `state.json.backup-prune-{timestamp}`
+4. **Stale before graduate** — stale artifacts are flagged, not silently archived (knowledge would be lost)
+5. **Spec dedup is conservative** — key_decision pruned only if verbatim match found in specs
+6. **Idempotent** — re-running `--prune` with no changes produces empty plan

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/init.md

@@ -42,13 +42,14 @@ state.json exists → Path C (existing) | source files exist → Path B (brownfi
    - "Keep exploring" → continue questioning
 
    If `--auto` flag: skip interactive questioning, extract from @ referenced document.
-   If `--from-brainstorm SESSION-ID`:
-   - Locate brainstorm session directory (`.workflow/scratch/brainstorm-*/`)
-   - Read `guidance-specification.md`:
-     - Problem statement → project vision + core value
-     - Features → project goals (Active requirements)
-     - Non-goals → constraints + Out of Scope requirements
-     - Terminology → project glossary context
+   If `--from <source>` (alias: `--from-brainstorm`):
+   - Locate source directory (`.workflow/scratch/brainstorm-*/`, `.workflow/scratch/*-import-*/`, etc.)
+   - Load `context-package.json` (preferred) or fall back to `guidance-specification.md`:
+     - `domain` (name, description, problem_statement) → project vision + core value
+     - `requirements[]` → project goals (Active requirements)
+     - `constraints[locked]` → key decisions
+     - `non_goals[]` → constraints + Out of Scope requirements
+     - `domain.terminology[]` → project glossary context
    - Skip interactive questioning (context already gathered)
 
 2. **Workflow Preferences** -- Configure project workflow settings:
@@ -86,7 +87,7 @@ state.json exists → Path C (existing) | source files exist → Path B (brownfi
    - "Skip mapping" → proceed
 4. Run Workflow Preferences (same as Path A step 2) → `.workflow/config.json`
 5. Ask user for project vision, goals, constraints (same deep questioning as Path A step 1)
-   - If `--from-brainstorm SESSION-ID`: extract from guidance-specification.md (skip questioning)
+   - If `--from <source>` (alias: `--from-brainstorm`): load context-package.json (skip questioning)
    - For brownfield: infer Validated requirements from existing code (what does codebase already do?)
 6. Create `.workflow/project.md` (include inferred Validated requirements + new Active requirements)
 

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)
 ```
 
 ---