maestro-flow-one 0.2.18 → 0.2.19

package/maestro-flow/agents/role-design-author.md

@@ -17,9 +17,9 @@ You produce a set of analysis files for one role in a brainstorm session, organi
 | Field | Required | Notes |
 |---|---|---|
 | `role_name` | yes | kebab-case slug, e.g. `system-architect` |
-| `role_template_path` | yes | `~/.maestro/templates/planning-roles/{role}.md` |
-| `guidance_path` | yes | path to `guidance-specification.md` |
-| `output_dir` | yes | absolute path to role folder — `{session_dir}/{role}/` |
+| `role_template_path` | yes | **absolute** path to `planning-roles/{role}.md` (orchestrator MUST expand `~/`) |
+| `guidance_path` | yes | **absolute** path to `guidance-specification.md` |
+| `output_dir` | yes | **absolute** path to role folder — `{session_dir}/{role}/`. If you receive a relative path or a literal `{output_dir}` placeholder, fail fast with `TASK BLOCKED: output_dir is not absolute`. |
 | `feature_list` | optional | F-id + slug + title rows; if missing, fall back to non-feature organization |
 | `design_research` | optional | external research markdown to integrate as evidence |
 | `project_specs` | optional | pre-loaded `maestro spec load` output |
@@ -28,7 +28,9 @@ You produce a set of analysis files for one role in a brainstorm session, organi
 
 ## Output Contract
 
-Write files to `output_dir/`. Do NOT write files anywhere else.
+Write files to `output_dir/` using the Write tool. Do NOT write files anywhere else. Do NOT return analysis as chat text — files on disk are the only valid deliverable. After writing, verify with Glob that `analysis.md` exists; if any Write call fails (e.g. relative path rejected), fail fast with `TASK BLOCKED`.
+
+**Authority note**: This Output Contract is authoritative for file layout. The role template at `role_template_path` may contain a legacy "## Brainstorming Analysis Structure" section describing a single-file layout — ignore it for file structure. Use the role template ONLY to source §3 subsection headings (via its "## MUST-Have Sections (Brainstorming)" block when present).
 
 ### File Structure
 

package/maestro-flow/commands/learn/decompose.md

@@ -25,8 +25,8 @@ $ARGUMENTS — target path/module and optional flags.
 - `--save-spec`: `Skill("spec-add")` for each new pattern
 - `--save-wiki`: create wiki note per dimension group
 
-**Storage read**: target files + `coding-conventions.md` + `specs/learnings.md` (dedup)
-**Storage write**: `.workflow/knowhow/KNW-decompose-{slug}-{date}.md` + append `specs/learnings.md`
+**Storage read**: target files + `coding-conventions.md` + `.workflow/specs/learnings.md` (dedup)
+**Storage write**: `.workflow/knowhow/KNW-decompose-{slug}-{date}.md` + append `.workflow/specs/learnings.md`
 </context>
 
 <state_machine>
@@ -47,7 +47,7 @@ S_RESOLVE:
   → S_RESOLVE     WHEN: unresolvable                     DO: AskUserQuestion
 
 S_DEDUP:
-  → S_ANALYZE     DO: read coding-conventions.md + specs/learnings.md → build known pattern set
+  → S_ANALYZE     DO: read coding-conventions.md + .workflow/specs/learnings.md → build known pattern set
 
 S_ANALYZE:
   → S_CROSSREF    DO: A_PARALLEL_DIMENSION_ANALYSIS
@@ -59,7 +59,7 @@ S_CATALOG:
   → S_PERSIST     DO: write KNW-decompose report (grouped by dimension: pattern table + details)
 
 S_PERSIST:
-  → END           DO: append specs/learnings.md [+ spec-add if --save-spec] [+ wiki note if --save-wiki]
+  → END           DO: append .workflow/specs/learnings.md [+ spec-add if --save-spec] [+ wiki note if --save-wiki]
 
 </transitions>
 
@@ -86,7 +86,7 @@ For each finding, match against known pattern set:
 | Status | Condition |
 |--------|-----------|
 | documented | Already in coding-conventions.md |
-| known | In specs/learnings.md |
+| known | In .workflow/specs/learnings.md |
 | new | Not seen before |
 
 Flag contradictions (finding conflicts with documented convention). Merge duplicates across agents (same pattern found by multiple dimensions).
@@ -106,7 +106,7 @@ Flag contradictions (finding conflicts with documented convention). Merge duplic
 <success_criteria>
 - [ ] 4 dimension agents spawned in parallel, findings with anchors
 - [ ] Cross-reference: documented/known/new status assigned
-- [ ] Pattern catalog written + specs/learnings.md appended
+- [ ] Pattern catalog written + .workflow/specs/learnings.md appended
 </success_criteria>
 
 <next_step_routing>

package/maestro-flow/commands/learn/follow.md

@@ -12,7 +12,7 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Guided reading: walk through content section-by-section using forcing questions to extract patterns, identify assumptions, and build an understanding map. Findings persist to `specs/learnings.md` as `<spec-entry>` blocks.
+Guided reading: walk through content section-by-section using forcing questions to extract patterns, identify assumptions, and build an understanding map. Findings persist to `.workflow/specs/learnings.md` as `<spec-entry>` blocks.
 </purpose>
 
 <context>
@@ -30,8 +30,8 @@ $ARGUMENTS — target and optional flags.
 - `--depth deep`: every function, every branch, every assumption
 - `--save-wiki`: create wiki note entry with reading notes
 
-**Storage read**: target file + wiki forward/backlinks + `coding-conventions.md` + `specs/learnings.md` (dedup)
-**Storage write**: `.workflow/knowhow/KNW-follow-{slug}-{date}.md` + append `specs/learnings.md`
+**Storage read**: target file + wiki forward/backlinks + `coding-conventions.md` + `.workflow/specs/learnings.md` (dedup)
+**Storage write**: `.workflow/knowhow/KNW-follow-{slug}-{date}.md` + append `.workflow/specs/learnings.md`
 </context>
 
 <state_machine>
@@ -64,7 +64,7 @@ S_EXTRACT:
   → S_PERSIST     DO: A_EXTRACT_PATTERNS
 
 S_PERSIST:
-  → END           DO: write KNW-follow + append specs/learnings.md [+ wiki note if --save-wiki]
+  → END           DO: write KNW-follow + append .workflow/specs/learnings.md [+ wiki note if --save-wiki]
 
 </transitions>
 

package/maestro-flow/commands/learn/investigate.md

@@ -28,9 +28,9 @@ $ARGUMENTS — question text and optional flags.
 - `.workflow/knowhow/KNW-investigate-{slug}/evidence.ndjson` — structured evidence (one JSON line per item)
 - `.workflow/knowhow/KNW-investigate-{slug}/understanding.md` — evolving understanding
 - `.workflow/knowhow/KNW-investigate-{slug}/report.md` — final report
-- `specs/learnings.md` — appended `<spec-entry>` blocks
+- `.workflow/specs/learnings.md` — appended `<spec-entry>` blocks
 
-**Storage read**: source files in scope + `maestro wiki search` + `specs/learnings.md` + `debug-notes.md` + `codebase/architecture.md`
+**Storage read**: source files in scope + `maestro wiki search` + `.workflow/specs/learnings.md` + `debug-notes.md` + `codebase/architecture.md`
 </context>
 
 <state_machine>
@@ -43,7 +43,7 @@ S_HYPOTHESIZE    — 生成假设列表                                PERSIST:
 S_CLI_EXPLORE    — CLI 辅助探索（可选）                         PERSIST: evidence.ndjson (append)
 S_TEST           — 逐假设测试                                  PERSIST: evidence.ndjson + understanding.md
 S_ESCALATE       — 3-strike 升级                               PERSIST: —
-S_REPORT         — 综合报告 + persist                          PERSIST: report.md + specs/learnings.md
+S_REPORT         — 综合报告 + persist                          PERSIST: report.md + .workflow/specs/learnings.md
 </states>
 
 <transitions>
@@ -55,7 +55,7 @@ S_EVIDENCE:
   → S_PATTERN     DO: A_COLLECT_EVIDENCE
 
 S_PATTERN:
-  → S_HYPOTHESIZE DO: match evidence against debug-notes.md + specs/learnings.md patterns
+  → S_HYPOTHESIZE DO: match evidence against debug-notes.md + .workflow/specs/learnings.md patterns
 
 S_HYPOTHESIZE:
   → S_CLI_EXPLORE WHEN: CLI tools enabled AND hypotheses non-trivial    DO: A_FORM_HYPOTHESES
@@ -83,7 +83,7 @@ S_REPORT:
 ### A_FRAME_QUESTION
 
 1. Parse question, generate slug, create KNW-investigate-{slug}/
-2. Search prior knowledge: `maestro wiki search "<question>"` + search specs/learnings.md + read debug-notes.md
+2. Search prior knowledge: `maestro wiki search "<question>"` + search .workflow/specs/learnings.md + read debug-notes.md
 3. Write initial understanding.md (question, prior knowledge summary, scope, timestamp)
 
 ### A_COLLECT_EVIDENCE
@@ -124,7 +124,7 @@ For each hypothesis (rank order):
 ### A_SYNTHESIZE_REPORT
 
 Write report.md: Answer (or INCONCLUSIVE), Evidence Trail table, Hypotheses Tested table, Key Learnings, Open Questions.
-Append to specs/learnings.md: confirmed → roles="implement", disproved → roles="analyze" (gotcha).
+Append to .workflow/specs/learnings.md: confirmed → roles="implement", disproved → roles="analyze" (gotcha).
 
 </actions>
 

package/maestro-flow/commands/learn/retro.md

@@ -14,7 +14,7 @@ allowed-tools:
 <purpose>
 Unified retrospective combining git activity analysis and decision quality evaluation. Works on raw git history and wiki/spec data. Two lenses (git, decision), usable independently or together.
 
-All insights persist to `specs/learnings.md` as `<spec-entry>` blocks.
+All insights persist to `.workflow/specs/learnings.md` as `<spec-entry>` blocks.
 </purpose>
 
 <context>
@@ -28,9 +28,9 @@ $ARGUMENTS — lens selection and scope flags.
 **Storage write**:
 - `.workflow/knowhow/KNW-retro-{date}.md` — unified report
 - `.workflow/knowhow/KNW-retro-{date}.json` — structured metrics
-- `specs/learnings.md` — appended `<spec-entry>` blocks (source: retro-git / retro-decision)
+- `.workflow/specs/learnings.md` — appended `<spec-entry>` blocks (source: retro-git / retro-decision)
 
-**Storage read**: git history, `.workflow/state.json`, prior `KNW-retro-*.json`, `specs/learnings.md`, wiki specs, `architecture-constraints.md`, phase context files
+**Storage read**: git history, `.workflow/state.json`, prior `KNW-retro-*.json`, `.workflow/specs/learnings.md`, wiki specs, `architecture-constraints.md`, phase context files
 </context>
 
 <state_machine>
@@ -40,7 +40,7 @@ S_PARSE       — 解析 lens + flags                           PERSIST: —
 S_GIT         — git 活动分析（lens=git/all 时）              PERSIST: metrics
 S_DECISION    — 决策质量评估（lens=decision/all 时）         PERSIST: evaluations
 S_REPORT      — 生成统一报告                                 PERSIST: .md + .json
-S_PERSIST     — 写 spec-entry 块                             PERSIST: specs/learnings.md
+S_PERSIST     — 写 spec-entry 块                             PERSIST: .workflow/specs/learnings.md
 </states>
 
 <transitions>
@@ -60,7 +60,7 @@ S_REPORT:
   → S_PERSIST     DO: write KNW-retro-{date}.md + .json
 
 S_PERSIST:
-  → END           DO: append insights to specs/learnings.md via `maestro spec add learning`
+  → END           DO: append insights to .workflow/specs/learnings.md via `maestro spec add learning`
   RULE: INS-id = hash(lens + metric_or_decision_id + date) for cross-session stability
 
 </transitions>
@@ -102,7 +102,7 @@ maestro wiki search "decision" --json
 maestro wiki list --type spec --json
 git log --oneline --all --grep="decision\|chose\|decided" -20
 ```
-Plus: architecture-constraints.md, phase context Locked/Deferred sections, specs/learnings.md.
+Plus: architecture-constraints.md, phase context Locked/Deferred sections, .workflow/specs/learnings.md.
 Apply --phase/--tag/--id filters.
 
 **Build registry** per decision: id, title, source, date, rationale, alternatives, phase, implementation_evidence [file paths].
@@ -146,7 +146,7 @@ Apply --phase/--tag/--id filters.
 - [ ] Git lens: metrics computed (commits, LOC, test ratio, churn, sessions), insights distilled
 - [ ] Decision lens: decisions collected, 3 agents evaluated in parallel, lifecycle classified
 - [ ] Unified report + structured JSON written
-- [ ] specs/learnings.md appended with stable INS-ids
+- [ ] .workflow/specs/learnings.md appended with stable INS-ids
 </success_criteria>
 
 <next_step_routing>

package/maestro-flow/commands/learn/second-opinion.md

@@ -17,7 +17,7 @@ Structured second-opinion on code, decisions, or plans. Three modes:
 - **challenge**: single adversarial agent — break assumptions, propose alternatives
 - **consult**: interactive Q&A — agent studies target, answers your questions
 
-Findings persist to `specs/learnings.md` as `<spec-entry>` blocks.
+Findings persist to `.workflow/specs/learnings.md` as `<spec-entry>` blocks.
 </purpose>
 
 <context>
@@ -45,7 +45,7 @@ S_RESOLVE    — 解析 target                          PERSIST: —
 S_CONTEXT    — 加载 specs/wiki 上下文                PERSIST: —
 S_EXECUTE    — 按 mode 执行分析                      PERSIST: —
 S_SYNTHESIZE — 综合观点、生成报告                     PERSIST: outputs
-S_PERSIST    — 写文件、append specs/learnings.md      PERSIST: knowhow files
+S_PERSIST    — 写文件、append .workflow/specs/learnings.md      PERSIST: knowhow files
 </states>
 
 <transitions>
@@ -66,7 +66,7 @@ S_SYNTHESIZE:
   → S_PERSIST     DO: merge perspectives → agreements, disagreements, verdict, top 3 recommendations
 
 S_PERSIST:
-  → END           DO: write KNW-opinion + append <spec-entry> blocks to specs/learnings.md
+  → END           DO: write KNW-opinion + append <spec-entry> blocks to .workflow/specs/learnings.md
 
 </transitions>
 
@@ -112,7 +112,7 @@ Interactive loop:
 <success_criteria>
 - [ ] Mode executed: review (3 parallel agents) / challenge (adversarial) / consult (interactive Q&A)
 - [ ] Synthesis with agreements, disagreements, verdict
-- [ ] Report written + findings appended to specs/learnings.md
+- [ ] Report written + findings appended to .workflow/specs/learnings.md
 </success_criteria>
 
 <next_step_routing>

package/maestro-flow/commands/lifecycle/amend.md

@@ -148,6 +148,7 @@ On validation failure: fix JSON, retry (max 2).
 | Code | Condition | Recovery |
 |------|-----------|----------|
 | E001 | No signals from any source | Verify artifact paths or provide description |
+| E002 | Signal source path invalid or unreadable | Check `--from-*` path; ensure artifact exists |
 | E003 | All signals are code bugs, not command gaps | Use /maestro-quick or /maestro-plan --gaps |
 | E004 | Overlay validation failed after 2 retries | Review JSON manually |
 | W001 | Some signals skipped (code bugs) | Route to appropriate fix command |

package/maestro-flow/commands/lifecycle/analyze.md

@@ -38,6 +38,12 @@ $ARGUMENTS -- phase number for micro mode, topic text for macro/adhoc mode, no a
 - **Macro mode** (text argument): Explore impact surface of a topic/requirement. Produces coarse-grained context with `scope_verdict` to route next step. Use before roadmap or for standalone analysis.
 - **Micro mode** (numeric argument): Phase-level deep analysis within an existing roadmap. Produces fine-grained context for plan consumption. `analyze 1` = Phase 1 of current milestone.
 
+**Disambiguation rule (mode selection):**
+- First positional arg matches `^\d+$` (pure digits, e.g. `1`, `42`) → **micro mode** (treat as phase number)
+- First positional arg is non-numeric text (e.g. `auth-refactor`, `improve search`) → **macro mode** (treat as topic)
+- No positional arg → milestone-wide micro mode (when roadmap present) else macro fallback
+- Mixed input like `"1 phase"` is treated as text → macro mode (only bare numerics trigger micro)
+
 **Flags:**
 - `-y` / `--yes`: Auto mode — skip interactive scoping, use recommended defaults, auto-deepen
 - `-c` / `--continue`: Resume from existing session (auto-detect session folder + discussion.md)
@@ -54,14 +60,15 @@ Scope routing, output directory format, artifact registration schema, and output
 <interview_protocol>
 Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `-y/--yes`, `-c/--continue`, or input is already specific (explicit phase number or unambiguous topic).
 
-- One decision per turn via AskUserQuestion with 2–4 options + a (Recommended) default; every question must include a `Proceed now` option so the user can end the interview at any time.
-- Never ask what code can verify — resolve via `state.json`, `roadmap.md`, `issues.jsonl`, `maestro spec load`, `maestro wiki search`, Grep, or Read.
+- One decision per turn via AskUserQuestion with 2–4 options + a (Recommended) default. The user controls termination — keep interviewing until convergence; they can interrupt naturally or via `Other` at any time.
+- Search-first when uncertain: before asking, resolve via `state.json`, `roadmap.md`, `issues.jsonl`, `maestro spec load`, `maestro wiki search`, Grep, Read, or — for open-ended multi-file scans — spawn `Agent(subagent_type: Explore)` / `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 `discussion.md` (top table) and mirrored into `context.md` "Interview Decisions". Do NOT batch writeback to the end — partial decisions must already be on disk before the next question.
 - Walk the decision dependency tree strictly: scope → depth → dimensions → Go/No-Go threshold. Do not open the next branch until the current one is settled.
 - Scope guard: only ask about decisions owned by `analyze`. Do not prejudge plan/execute concerns.
 
 Decision points: scope (phase / topic / milestone-wide / adhoc / --gaps) → depth (quick / standard / deep) → dimensions (which of the 6 to keep) → Go/No-Go threshold.
 
-Exit: on `Proceed now` or when all decision points are settled, write the table below to the top of `discussion.md` and mirror it into `context.md` under an `Interview Decisions` section:
+Exit: when all decision points are settled (or user explicitly signals to proceed), finalize session metadata. The decision table (populated incrementally during interview) uses this schema:
 `| # | Decision | Choice | Source (user / code / default) |`
 </interview_protocol>
 

package/maestro-flow/commands/lifecycle/blueprint.md

@@ -64,14 +64,15 @@ maestro-analyze → maestro-roadmap → maestro-plan
 <interview_protocol>
 Interview the user relentlessly about every aspect of the spec until shared understanding is reached. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one; if a question can be answered by exploring the codebase, explore the codebase instead. Active only in interactive mode; skip when `-y/--yes`, `-c/--continue`, or input is already specific (clear idea + scope).
 
-- Ask one question per turn via AskUserQuestion and wait for the user's feedback before continuing; every question must carry a recommended answer marked `(Recommended)`, 2–4 options total, and a `Proceed now` option.
-- Never ask what code can verify — resolve via `state.json`, existing artifacts, `maestro spec load`, or direct codebase exploration (Glob/Grep/Read) instead of prompting.
+- Ask one question per turn via AskUserQuestion and wait for the user's feedback before continuing; every question must carry a recommended answer marked `(Recommended)`, 2–4 options total. The user controls termination — keep interviewing until convergence; they can interrupt naturally or via `Other` at any time.
+- Search-first when uncertain: before asking, resolve via `state.json`, existing artifacts, `maestro spec load`, direct codebase exploration (Glob/Grep/Read), or — for open-ended multi-file scans — spawn `Agent(subagent_type: Explore)` / `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 persisted into `blueprint-config.json` before the next question. Do NOT batch writeback to the end — partial decisions must already be on disk.
 - Walk the decision dependency tree depth-first: scope → spec type → focus areas → requirement priorities. Do not open the next branch until the current one is settled.
 - Scope guard: only decide the shape of the specification. Do not pre-resolve roadmap phases or plan tasks — those belong to downstream commands.
 
 Decision points: scope (full product / feature set / single feature) → spec type (service / api / library / platform) → focus areas → whether to run codebase exploration.
 
-Exit: on consensus or `Proceed now`, persist decisions in blueprint-config.json and proceed to Phase 1.
+Exit: on consensus or explicit user signal to proceed, finalize blueprint-config.json (decisions already written incrementally) and proceed to Phase 1.
 </interview_protocol>
 
 <execution>

package/maestro-flow/commands/lifecycle/brainstorm.md

@@ -30,7 +30,7 @@ $ARGUMENTS -- topic text for auto mode, or role name for single role mode.
 
 **Auto mode**: topic text (e.g., "Build real-time collaboration platform") triggers full pipeline.
 **Single role mode**: valid role name (e.g., "system-architect") runs one role analysis.
-**All output** goes to `.workflow/scratch/{YYYYMMDD}-brainstorm-{slug}/`.
+**All output** goes to `.workflow/scratch/brainstorm-{slug}-{YYYYMMDD}/` (orchestrator MUST resolve this to an absolute path before passing to sub-agents).
 **Artifact registration**: On completion, registers artifact (type=brainstorm) in state.json.
 **Output boundary**: ALL file writes MUST target `{output_dir}/` or `.workflow/state.json` only. NEVER modify source code or files outside these paths.
 **Produced files**: `guidance-specification.md`, `design-research.md` (optional), `{role}/analysis.md` + `{role}/analysis-F-*.md` + `{role}/findings-*.md` (per selected role).
@@ -62,14 +62,15 @@ $ARGUMENTS -- topic text for auto mode, or role name for single role mode.
 <interview_protocol>
 Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `--yes/-y`, `--skip-questions`, `--session` (existing session), or input is already specific.
 
-- One decision per turn via AskUserQuestion 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`, the session directory, `maestro spec load`, or `maestro wiki search`.
+- One decision per turn via AskUserQuestion with 2–4 options + a (Recommended) default. The user controls termination — keep interviewing until convergence; they can interrupt naturally or via `Other` at any time.
+- Search-first when uncertain: before asking, resolve via `state.json`, the session directory, `maestro spec load`, `maestro wiki search`, Glob/Grep/Read, or — for open-ended multi-file scans — spawn `Agent(subagent_type: Explore)` / `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 time a decision settles, immediately append/update its row in `guidance-specification.md` §11 (create the section if absent). Do NOT batch writeback to the end — partial decisions must already be on disk before the next question.
 - Branch jumps allowed: the user may switch freely between mode / role / upstream / sub-pipeline branches; sequence is not enforced, but every decision point must end with a definite answer.
 - Scope guard: only ask about decisions owned by `brainstorm`. Do not pre-resolve roadmap/plan choices.
 
 Decision points: mode (auto / single-role / review-only) / role selection and `--count` / `--from` upstream source / whether to enable design-research and the DESIGN.md sub-pipeline.
 
-Exit: on consensus or `Proceed now`, write the table below into `guidance-specification.md` §11 and session metadata:
+Exit: on consensus or explicit user signal to proceed, finalize session metadata. The §11 table (already populated incrementally) uses this schema:
 `| # | Decision | Choice | Source (user / code / default) |`
 </interview_protocol>
 

package/maestro-flow/commands/lifecycle/fork.md

@@ -19,7 +19,7 @@ Since `.workflow/` is gitignored, this command explicitly copies project context
 
 Also supports `--sync` mode to pull latest main branch changes and shared artifacts into an active worktree (prevents source and artifact drift for long-lived worktrees).
 
-Produces `.workflow/worktrees.json` registry in the main worktree and `.workflow/worktree-scope.json` marker in the worktree.
+Produces `.workflow/worktrees.json` registry in the main worktree and `.workflow/worktree-scope.json` marker in the worktree, and writes a scoped `state.json` inside the worktree containing only the forked milestone's artifacts.
 </purpose>
 
 <required_reading>

package/maestro-flow/commands/lifecycle/guard.md

@@ -77,10 +77,11 @@ Read `.workflow/config.json`. If file missing, initialize with empty guard secti
 - Write config
 
 **`deny <path>`:**
-- Normalize path to forward slashes
+- Normalize path to forward slashes, ensure trailing slash for directories
+- If `guard.mode` is `allow`, switch to `deny` and clear paths with warning
 - Set `guard.mode = "deny"`
 - Add path to `guard.paths` (deduplicate)
-- Set `guard.enabled = true` if not already
+- Set `guard.enabled = true` if not already (symmetric with `allow`: adding a deny path auto-enables the guard)
 - Write config
 
 **Step 4: Confirm**

package/maestro-flow/commands/lifecycle/impeccable.md

@@ -74,6 +74,8 @@ responsive-design.md, spatial-design.md, typography.md, ux-writing.md
 
 ## Chains
 
+Chain step names below reuse Command Routing names but resolve through the chain runner. To avoid ambiguity with Direct command invocation, internal display, todo items, and session status records always tag chain steps with the `impeccable:` prefix (e.g. `impeccable:craft`, `impeccable:critique`). The bare names in this table refer to the workflow file at `~/.maestro/workflows/impeccable/{name}.md` that the chain step reads.
+
 | Chain | Steps | Scenario |
 |-------|-------|----------|
 | build | teach? → explore? → shape → craft → critique → [refine] → audit → polish | New from scratch |
@@ -181,17 +183,17 @@ Before reading any command workflow:
 ## Chain Execution
 
 1. Prerequisites ✓
-2. **Display chain preview**: parse chain definition, output full step preview:
+2. **Display chain preview**: parse chain definition, output full step preview (chain steps prefixed `impeccable:` to disambiguate from Direct commands):
    ```
    ── Chain: build ──────────────────────────
-    1. teach        (conditional: PRODUCT.md missing)
-    2. explore      (conditional: DESIGN.md missing)
-    3. shape
-    4. craft
-    5. critique     ◆ quality gate (threshold: 26/40)
-    6. [refine]     ↺ auto-fix loop (max: 3)
-    7. audit        ◆ quality gate (threshold: 14/20)
-    8. polish
+    1. impeccable:teach        (conditional: PRODUCT.md missing)
+    2. impeccable:explore      (conditional: DESIGN.md missing)
+    3. impeccable:shape
+    4. impeccable:craft
+    5. impeccable:critique     ◆ quality gate (threshold: 26/40)
+    6. impeccable:[refine]     ↺ auto-fix loop (max: 3)
+    7. impeccable:audit        ◆ quality gate (threshold: 14/20)
+    8. impeccable:polish
    ─────────────────────────────────────────
    Target: {target}
    ```
@@ -205,9 +207,9 @@ Before reading any command workflow:
      "gate_history": [], "loop_count": 0, "status": "running" }
    ```
 4. **TodoWrite init**: create todo items for all chain steps
-   - One item per step, format: `[chain] step N: {command} — {description}`
+   - One item per step, format: `[chain] step N: impeccable:{command} — {description}` (use `impeccable:` prefix to disambiguate from Direct command items)
    - If conditional step is skipped, immediately mark completed
-   - Quality gate steps include threshold: `[chain] step 5: critique ◆ gate ≥26/40`
+   - Quality gate steps include threshold: `[chain] step 5: impeccable:critique ◆ gate ≥26/40`
 5. For each step:
    - Read `~/.maestro/workflows/impeccable/{command}.md` → execute
    - **Step start**: TodoWrite marks current step in_progress

package/maestro-flow/commands/lifecycle/plan.md

@@ -54,7 +54,9 @@ Scope routing, base flags (`--collab`, `--spec`, `-y`, `--gaps`, `--dir`), outpu
 5. No args + roadmap → scope = "milestone" (unchanged)
 6. No args + no roadmap → search state.json for latest analyze artifact, fallback standalone
 
-**Ad-hoc milestone (D-008):** When scope resolves to "standalone" and `current_milestone == null`, plan auto-creates an adhoc milestone (`type: "adhoc"`) in state.json before proceeding. This ensures downstream milestone-audit/complete have a valid milestone context. See workflow plan.md § "Ad-hoc Milestone Auto-Creation".
+**Ad-hoc milestone (D-008):** When scope resolves to "standalone" via the standard standalone resolution (no `--from` source), and `current_milestone == null`, plan auto-creates an adhoc milestone (`type: "adhoc"`) in state.json before proceeding. This ensures downstream milestone-audit/complete have a valid milestone context. See workflow plan.md § "Ad-hoc Milestone Auto-Creation".
+
+**Exception (`--from analyze:ANL-xxx` / `blueprint:BLP-xxx`):** When scope is set to "standalone" by `--from`, skip adhoc milestone auto-creation — the upstream analyze/blueprint artifact already provides the milestone context (or is intentionally milestone-free). Adhoc creation in this path would conflict with the `--from` semantic of "this is a one-shot plan rooted in an existing artifact".
 
 ### Role Knowledge
 `maestro wiki list --category arch` → select relevant → `maestro wiki load`

package/maestro-flow/commands/lifecycle/roadmap.md

@@ -69,14 +69,15 @@ maestro-analyze {phase} → maestro-plan → maestro-execute → maestro-verify
 <interview_protocol>
 Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `-y/--yes`, `--revise`, `--review`, `-c/--continue`, or input is already specific (clear requirement + mode).
 
-- One decision per turn via AskUserQuestion 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 AskUserQuestion with 2–4 options + a (Recommended) default. The user controls termination — keep interviewing until convergence; they can interrupt naturally or via `Other` 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 — spawn `Agent(subagent_type: Explore)` / `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/maestro-flow/commands/manage/harvest.md

@@ -47,6 +47,7 @@ Follow '~/.maestro/workflows/harvest.md' Stages 1-8 in order.
 1. **Read-only until Stage 6** — extraction and classification happen in-memory.
 2. **Dedup before write** — check harvest-log.jsonl and existing stores before each write.
 3. **Never modify source artifacts** — harvest is purely extractive.
+4. **Dedup contract with parallel writers** — when appending to `issues.jsonl`, set `source: "harvest"` on each row so concurrent writers (e.g. `manage-issue-discover` with `source: "discover"`) can be distinguished and deduplicated.
 
 Extraction patterns, classification rules, routing infrastructure, and fragment ID scheme defined in workflow harvest.md.
 

package/maestro-flow/commands/manage/issue-discover.md

@@ -46,7 +46,7 @@ $ARGUMENTS -- optional. Parse first token to determine mode.
 - `--depth=standard|deep` -- exploration depth (by-prompt only, default: `standard`)
 
 **State files:**
-- `.workflow/issues/issues.jsonl` -- issues appended here
+- `.workflow/issues/issues.jsonl` -- issues appended here (set `source: "discover"` on each row so concurrent writers like `manage-harvest` with `source: "harvest"` can be distinguished and deduplicated)
 - `.workflow/issues/discoveries/{SESSION_ID}/` -- session artifacts
 
 ### Pre-load specs

package/maestro-flow/commands/manage/knowhow.md

@@ -53,7 +53,7 @@ Follow '~/.maestro/workflows/knowhow.md' Part A (KnowHow Management) completely.
 <error_codes>
 | Code | Severity | Description | Stage |
 |------|----------|-------------|-------|
-| E001 | error | No memory stores found — run `/manage-knowhow-capture` or create MEMORY.md | resolve_paths |
+| E001 | error | No memory stores found — for workflow store run `/manage-knowhow-capture`; for system store create `~/.claude/projects/{project}/memory/MEMORY.md` manually | resolve_paths |
 | E002 | error | Entry ID or filename not found | execute_view, execute_delete |
 | E003 | error | Prune requires at least one filter (--tag, --type, --before, --after) | execute_prune |
 | E004 | error | Cannot delete MEMORY.md — use `edit` subcommand instead | execute_delete |

package/maestro-flow/commands/manage/learn.md

@@ -30,7 +30,7 @@ Arguments: $ARGUMENTS
 - `"<insight text>"` (or any non-keyword text) → insight capture mode
 - `tip <text>` → tip capture mode (quick contextual note, auto-tagged `tip`)
 - `list` → list recent entries (default 20)
-- `search <query>` → `maestro spec load --category learning` or text search across `specs/learnings.md`
+- `search <query>` → `maestro spec load --category learning` or text search across `.workflow/specs/learnings.md`
 - `show <INS-id>` → full detail with phase context
 - empty → AskUserQuestion to prompt for text
 
@@ -47,19 +47,19 @@ Follow `~/.maestro/workflows/learn.md` Stages 1–5 in order.
 | E001 | error | `.workflow/` not initialized — run `/maestro-init` first | parse_input |
 | E002 | error | Unknown `--category` value (allowed: pattern, antipattern, decision, tool, gotcha, technique, tip) | parse_input |
 | E003 | error | `show` mode requires an INS-id argument | show |
-| E004 | error | Insight id not found in `specs/learnings.md` | show |
+| E004 | error | Insight id not found in `.workflow/specs/learnings.md` | show |
 | W001 | warning | Auto-phase detection found a current_phase but no matching artifact in registry; phase set to null | capture |
 </error_codes>
 
 <success_criteria>
 - [ ] Mode correctly routed (capture / list / search / show)
-- [ ] Capture: `<spec-entry>` block appended to `specs/learnings.md` with all required fields
+- [ ] Capture: `<spec-entry>` block appended to `.workflow/specs/learnings.md` with all required fields
 - [ ] Capture: phase auto-link resolves correctly via artifact registry when `state.json` has `current_phase`
 - [ ] Capture: category inference produces a sensible default when `--category` absent
 - [ ] List: filters apply, output sorted newest-first, default limit 20
 - [ ] Search: results ranked by title (3) > tags (2) > summary (1) match
 - [ ] Show: full insight displayed with phase context and routed-artifact link if any
-- [ ] No file modifications outside `.workflow/knowhow/`
+- [ ] No file modifications outside `.workflow/specs/learnings.md` and `.workflow/knowhow/`
 - [ ] Confirmation banner displayed with INS-id and next-step hints
 - [ ] Next step: `/manage-learn list` to browse, or `/manage-learn search <query>` to find related insights
 </success_criteria>

package/maestro-flow/commands/milestone/release.md

@@ -44,7 +44,7 @@ $ARGUMENTS -- optional explicit version string and flags.
 </context>
 
 <execution>
-Follow '~/.maestro/workflows/release.md' completely.
+Follow '~/.maestro/workflows/milestone-release.md' completely.
 
 **High-level flow:**
 1. Validate preconditions (milestone completed, clean tree, audit PASS)

package/maestro-flow/commands/quality/auto-test.md

@@ -40,13 +40,13 @@ Phase or task: $ARGUMENTS (required — phase number)
 
 **Intelligent routing** (auto-detected from project state):
 
-| Priority | Condition | Route | Equivalent to |
-|----------|-----------|-------|---------------|
+| Priority | Condition | Route | Reference skill |
+|----------|-----------|-------|-----------------|
 | 1 | Active session exists (state.json status=running) | Resume | — |
 | 2 | --re-run flag + previous failures | Re-run | — |
-| 3 | Spec package exists (REQ-*.md) | spec | quality-business-test |
-| 4 | Nyquist gaps exist (verification.json) | gap | quality-test-gen |
-| 5 | Default | code | quality-integration-test |
+| 3 | Spec package exists (REQ-*.md) | spec | quality-business-test (separate skill) |
+| 4 | Nyquist gaps exist (verification.json) | gap | quality-test-gen (separate skill) |
+| 5 | Default | code | quality-integration-test (separate skill) |
 
 Flags, artifact context resolution, and output formats defined in workflow auto-test.md.
 

package/maestro-flow/commands/quality/refactor.md

@@ -46,7 +46,7 @@ After successful refactoring, ask user once: "Record refactoring pattern as codi
 
 **Next-step routing on completion:**
 - All tests pass → `/quality-sync` (update codebase docs)
-- Test failures after refactor → `/quality-debug {scope}`
+- Test failures after refactor → `/quality-debug "test failures after refactor in {scope}"`
 - No test suite available → `/quality-auto-test {phase}`
 </execution>
 

package/maestro-flow/commands/quality/retrospective.md

@@ -13,7 +13,7 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Post-execution multi-perspective retrospective (复盘) for completed phases. Consumes existing execution artifacts (verification.json, review.json, issues.jsonl, plan.json, .summaries/, uat.md, state.json) and runs four parallel lenses — technical, process, quality, decision — to distill reusable insights. Routes each insight into the appropriate store: spec stub for reusable patterns, memory tip for process notes, issue for recurring gaps. Auto-scans for unreviewed completed phases and reports the backlog. Every insight is also persisted to `.workflow/knowhow/specs/learnings.md` as `<spec-entry>` blocks for cross-phase queryability.
+Post-execution multi-perspective retrospective (复盘) for completed phases. Consumes existing execution artifacts (verification.json, review.json, issues.jsonl, plan.json, .summaries/, uat.md, state.json) and runs four parallel lenses — technical, process, quality, decision — to distill reusable insights. Routes each insight into the appropriate store: spec stub for reusable patterns, memory tip for process notes, issue for recurring gaps. Auto-scans for unreviewed completed phases and reports the backlog. Every insight is also persisted to `.workflow/specs/learnings.md` as `<spec-entry>` blocks for cross-phase queryability.
 </purpose>
 
 <required_reading>
@@ -70,7 +70,7 @@ Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order. Key invari
 - [ ] Spec entries (if any) appended as `<spec-entry>` to matching `.workflow/specs/{category-file}.md`
 - [ ] Issue rows (if any) match canonical issues.jsonl schema (status "open", full issue_history, all required fields)
 - [ ] Note tips (if any) created via `Skill({ skill: "manage-learn", args: "tip ..." })`
-- [ ] `specs/learnings.md` appended with one `<spec-entry>` per insight regardless of routing target
+- [ ] `.workflow/specs/learnings.md` appended with one `<spec-entry>` per insight regardless of routing target
 - [ ] No existing phase artifacts modified (verification.json, review.json, plan.json untouched)
 - [ ] Confirmation banner displays routing counts and next-step suggestions
 - [ ] Next step: `/manage-status` to review state, or `/manage-issue list --source retrospective` to triage created issues, or `/manage-learn list` to browse the knowhow library

package/maestro-flow/commands/spec/remove.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
@@ -26,6 +26,9 @@ $ARGUMENTS -- expects `<entry-id>` (e.g., `spec-learnings-003`, `spec-coding-con
 **Entry ID format**: `spec-{file-stem}-{NNN}` — the sub-node ID assigned by WikiIndexer when indexing `<spec-entry>` blocks.
 
 **Discovery**: Use `maestro wiki list --type spec --json` or `/spec-load --keyword <term>` to find entry IDs.
+
+**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>
@@ -47,5 +50,6 @@ Follow '~/.maestro/workflows/specs-remove.md' completely.
 - [ ] User confirmed removal (unless -y flag)
 - [ ] Entry removed from container file via `maestro wiki remove-entry`
 - [ ] Wiki index auto-updated
-- [ ] Confirmation displayed with removed entry details
+- [ ] If `--cascade` and entry has a `ref` attribute: referenced knowhow file deleted, orphan avoided
+- [ ] Confirmation displayed with removed entry details (and cascaded knowhow path if applicable)
 </success_criteria>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-flow-one",
-  "version": "0.2.18",
+  "version": "0.2.19",
   "description": "All Maestro workflow commands as a single Claude Code skill — intent routing, decision gates, minimal closed-loop chains",
   "bin": {
     "maestro-flow": "bin/maestro-flow.js"