pi-maestro-flow 0.2.0 → 0.3.0

package/workflows/odyssey-base-codex.md

@@ -0,0 +1,305 @@
+# Odyssey Shared Base (Codex)
+
+Shared by all Odyssey commands (debug, improve, planex, review-test-fix, ui).
+
+<execution_discipline>
+
+1. **Phase auto-commit** — auto `git commit` after each phase
+   - Code changes + understanding.md → `git add` → `git commit -m "{command}({slug}): {phase} — {summary}"`
+   - session.json / evidence.ndjson are runtime state, excluded from commits
+
+2. **Confident edits only, but must attempt** — edit when confident; record decision only when human judgment truly needed
+   - Confident → edit + commit
+   - Needs decision → `evidence.ndjson {"phase":"decision","status":"pending"}`, no code change
+   - **Decision gate** — only these qualify: cross-module architecture tradeoffs needing human direction | business semantics ambiguity where fix may change intent | new dependency or breaking API required
+   - "Unsure how to fix", "Too large scope", "Pre-existing issue" are NOT valid decision reasons
+
+3. **Multi-CLI assist** — `maestro delegate` for cross-angle verification
+   - Different `--role` per phase (analyze / review / explore)
+   - **`--role` fallback:** when `cli-tools.json` `roles` is empty, `--role` auto-falls back to first enabled tool. Equivalent to `--to <first-enabled>` but preserves semantic annotation for log tracking
+   - All delegate calls `run_in_background: true`, wait for callback
+
+4. **Never abort for context exhaustion** — harness auto-compresses context; aborting due to "insufficient context" or "already ran N phases" is a discipline violation. Must complete through S_RECORD → END.
+
+**Zero-residual:** Every finding must have an action (fix / issue / decision). "Report only" and "pre-existing skip" are forbidden.
+</execution_discipline>
+
+<flag_semantics>
+
+### `--auto` vs `-y`
+
+| Flag | Scope | Effect |
+|------|-------|--------|
+| `--auto` | **CLI delegate calls** | Skip delegate launch confirmation, execute `run_in_background` directly |
+| `-y` | **Human decision points** | All `request_user_input` calls auto-select default, record as `deferred` |
+
+- `--auto` does not affect human decision points (ambiguity, triage, goal audit still need confirmation or `-y`)
+- `-y` does not affect delegate calls (delegates always auto-execute, `--auto` only controls pre-launch confirmation)
+- Combine: `--auto -y` = fully automatic mode
+- `session.json.flags` mapping: `auto` ↔ `--auto`, `auto_confirm` ↔ `-y`
+</flag_semantics>
+
+<shared_schemas>
+
+### session.json standard fields
+
+```json
+{
+  "session_id": "{type}-odyssey-{YYYYMMDD-HHmmss}",
+  "current_state": "S_INTAKE",
+  "flags": { "skip_fix": false, "skip_generalize": false, "auto": false, "auto_confirm": false },
+  "phase_goals": [], "phase_goals_all_done": false,
+  "self_iteration_log": [],
+  "cross_phase_loops": 0, "max_loops": 5,
+  "created_at": "", "updated_at": ""
+}
+```
+
+Each command adds its own fields (e.g. `issue`, `target`, `requirement`).
+Note: `cross_phase_loops` and `max_loops` are shared fields — commands should not redeclare them.
+
+### evidence.ndjson base schema
+
+```json
+{"ts":"","phase":"","type":"","source":"","content":"","note":""}
+```
+
+Each command defines phase-specific extension fields (e.g. `hypothesis`, `severity`, `dimension`).
+
+### patterns[] schema (A_GENERALIZE output)
+
+```json
+{
+  "id": "P1",
+  "source": "<value>",
+  "layer": "syntax|semantic|structural",
+  "signature": "regex or description",
+  "description": "human-readable",
+  "risk": "high|medium|low",
+  "fix_template": "code pattern or instruction",
+  "confidence": "high|medium|low"
+}
+```
+
+`source` field value per command:
+
+| Command | source value | Meaning |
+|---------|-------------|---------|
+| debug | root_cause | Root cause fix |
+| improve | diagnosis | Diagnosed finding |
+| review-test-fix | finding | Review finding |
+| ui | finding | Audit/diverge finding |
+| planex | implementation | Implementation pattern |
+
+### generalization_stats schema
+
+```json
+{
+  "patterns_extracted": 0, "total_hits": 0,
+  "cross_layer_confirmed": 0, "regression_risks": 0,
+  "by_layer": {"syntax": 0, "semantic": 0, "structural": 0},
+  "deepening_triggered": false
+}
+```
+
+</shared_schemas>
+
+<anti_stall>
+
+### progress_metrics fields
+
+```json
+{
+  "progress_metrics": {
+    "phase_stats": {},
+    "stale_count": 0,
+    "last_productive_phase": "",
+    "convergence_trend": "unknown"
+  },
+  "directions_tried": []
+}
+```
+
+### Progress Tracking
+
+After each analytical phase:
+1. Count `new_findings` (deduplicated) and `repeated` (matching existing evidence)
+2. Write to `progress_metrics.phase_stats[state_name]`
+3. `new == 0` → `stale_count++`, `convergence_trend = "stalling"`
+4. `new > 0` → `stale_count = 0`, update `last_productive_phase`
+5. 2 consecutive phases with declining new → `convergence_trend = "diminishing"`
+
+### Direction Diversity
+
+```json
+{
+  "phase": "S_DIAGNOSE", "round": 1,
+  "strategy_type": "scope_widen|perspective_shift|tool_switch|structural_pivot",
+  "strategy_desc": "expand search to utils/", "result": "2 new findings"
+}
+```
+
+**Dedup rule:** Check same-phase history before self-iteration → new strategy must differ in `strategy_type` or `strategy_desc` → all 4 types tried → force stale_count upgrade
+
+### Stall Escalation Ladder
+
+| stale_count | Strategy |
+|-------------|----------|
+| 0 | Normal advance |
+| 1 | **Shift perspective** — different CLI tool, reverse trace, manual read. Must differ from directions_tried |
+| 2 | **Structural pivot** — redefine search dimensions, switch analysis framework, decompose sub-problems. Not parameter tuning |
+| 3 | **Human escalation** — request_user_input / `-y` auto INCONCLUSIVE and advance |
+
+### /loop Heartbeat (optional, `--heartbeat`)
+
+Suggest `/loop 270s`. Each phase updates `session.json.updated_at`. >15 min without update → alert + stale_count. 2 consecutive no-update → suggest `-c` resume.
+</anti_stall>
+
+<self_iteration>
+
+### Quality Gate
+
+| Dimension | Sufficient | Insufficient |
+|-----------|-----------|-------------|
+| Coverage | All known related files/modules analyzed | Missed targets discoverable via grep/git log |
+| Depth | ≥80% findings have file:line evidence | Most findings lack specifics |
+| Actionability | Each conclusion has concrete next action | "Consider reviewing" without action |
+
+**Progress-aware iteration:**
+- Phase complete → evaluate 3 dimensions + check `progress_metrics`
+- Any insufficient AND `stale_count < 3` → re-enter with expansion strategy (must pass directions_tried dedup)
+- Follow Stall Escalation Ladder for strategy selection
+
+**Expansion strategies:**
+- `scope_widen`: more directories, git log depth ×2, additional delegate angles
+- `perspective_shift`: different CLI tool, reverse trace, manual reading
+- `tool_switch`: switch to unused analysis tool
+- `structural_pivot`: redefine problem framework, decompose sub-problems
+
+**Exit:** all sufficient → advance | `stale_count >= 3` → log gaps, advance
+
+**Log:** `evidence.ndjson {"phase":"self-iteration"}` + `session.json.self_iteration_log[]` + `directions_tried[]`
+</self_iteration>
+
+<shared_actions>
+
+### A_GENERALIZE
+
+3-layer pattern extraction → 4-agent concurrent scan → cross-layer dedup → iterative deepening.
+
+**Pattern source:** specified by each command (root cause / audit findings / implementation patterns).
+
+**3-layer extraction:**
+
+| Layer | Method | Example |
+|-------|--------|---------|
+| Syntax | Regex → Grep | `eval(`, missing `await`, inline styles |
+| Semantic | Agent understands anti-pattern → scan | Unhandled async errors, missing validation |
+| Structural | File/module structure similarity | Same import structure, missing override |
+
+Write `session.json.patterns[]` — schema in `<shared_schemas>` patterns[] definition.
+
+**4-agent concurrent scan (spawn_agents_on_csv, wave number specified by each command):**
+
+| Agent | Strategy | Scope |
+|-------|----------|-------|
+| Syntax grep | Grep regex | Full project |
+| Semantic scan | Anti-pattern check | Related modules |
+| Structural match | Structurally similar files | Full project |
+| Historical grep | `git log -S` | Git history |
+
+**Cross-layer dedup:** multi-layer hit → boost confidence | single-layer → `needs_review` | historically fixed → `regression_risk`
+
+**Iterative deepening:** module ≥3 hits → targeted deep scan (max 1 round)
+
+**Persist:** understanding.md generalization section + `session.json.generalization_stats`
+
+Commit: `"...({slug}): GENERALIZE — generalization scan complete"`
+
+### A_DISCOVER
+
+1. **Triage** each hit ±10 lines context → classify `bug` / `risk` / `safe`
+2. **Route:**
+   - bug + fix_template applicable → immediate fix → back to S_FIX
+   - bug + needs cross-module decision or no fix_template → create issue (with fix suggestion + impact analysis)
+   - risk → assess if guard can be added directly; yes → fix; no → create issue
+   - safe → skip
+   Normal: request_user_input | `-y`: auto-fix bugs with fix_template, create issue for rest
+3. **Cross-phase loops:** `cross_phase_loops++`. `loops >= max_loops` → must log per-item reasons (blanket "pre-existing" forbidden)
+4. Append evidence + update understanding.md
+
+Commit: `"...({slug}): DISCOVER — discovery triage complete"`
+
+### A_RECORD
+
+1. Finalize understanding.md final section — learnings structured by each command's category table
+2. Mark record goal done. Pending decisions: Normal → request_user_input | `-y` → skip (show deferred count)
+3. **Goal audit:** all `completion_confirmed` → `phase_goals_all_done = true`. Incomplete: Normal → request_user_input | `-y` → auto accept
+4. `current_state = "COMPLETED"`, emit completion summary (format defined by each command)
+
+Commit: `"...({slug}): RECORD — summary and knowledge persistence"`
+
+</shared_actions>
+
+<shared_appendix>
+
+### Goal Prompt
+
+**Timing guard: display ONCE after INTAKE completes. Never re-display at RECORD.**
+
+```
+{Command} Odyssey session created. Copy the /goal below to set termination criteria:
+
+/goal Complete these goals:
+{for each G in phase_goals where status != "skipped":}
+- {G.id}: {G.goal} — done when: {G.done_when}
+{end for}
+{command-specific convergence rules}
+Pending phase=decision items must use request_user_input, never self-resolve.
+```
+
+Continue execution after output, do not block.
+
+### `-y` generic rules
+
+- Decision pending → best-effort continue, record `deferred`
+- 3-strike escalation → auto INCONCLUSIVE
+- Discovery routing → auto-fix bugs with fix_template, create issue for rest
+- Record pending → skip, show deferred count
+- Record goal audit → auto accept
+
+`deferred` items shown in completion summary; recoverable via `-c`. Each command lists its own specific decision points.
+
+### Phase Goal Lifecycle
+
+`pending → done (confirmed=true)` | `pending → skipped (confirmed=true)` | `pending → failed (confirmed=false)`
+
+`phase_goals_all_done = true` only when ALL goals have `completion_confirmed == true`.
+
+### Session Resume (`-c`)
+
+1. `Glob(".workflow/scratch/*-{type}-odyssey-*")` scan all matching session directories
+2. **Multiple sessions: sort by `session.json.updated_at` descending, select most recent**
+3. Read `session.json` → display summary (issue/target, current_state, phase_goals status)
+4. Jump to `current_state` and continue
+
+### Pre-load (optional, missing does not block)
+
+| Layer | Command |
+|-------|---------|
+| Codebase docs | Read `.workflow/codebase/ARCHITECTURE.md` |
+| Wiki search | `maestro search "<keywords>" --json` (top 5) |
+| Specs | `maestro load --type spec --category <cat>` |
+| Role knowledge | `maestro search --category <cat>` → `maestro load --type knowhow --id <id>` |
+| Prior sessions | `Glob(".workflow/scratch/*-{type}-odyssey-*")` |
+
+### Common Error Codes
+
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E003 | error | Resume but no session found | Start new |
+| E004 | error | Delegate failed | Retry or proceed without |
+| W003 | warning | Generalization 0 hits | Skip discovery |
+| W004 | warning | Delegate parse failed | Use raw output |
+
+</shared_appendix>

package/workflows/odyssey-base.md

@@ -0,0 +1,256 @@
+# Odyssey Shared Base
+
+Shared by all Odyssey commands (debug, improve, planex, review-test-fix, ui).
+
+<execution_discipline>
+
+1. **Phase auto-commit** — auto `git commit` after each phase
+   - Code changes + understanding.md → `git add` → `git commit -m "{command}({slug}): {phase} — {summary}"`
+   - session.json / evidence.ndjson are runtime state, excluded from commits
+
+2. **Confident edits only, but must attempt** — edit when confident; record decision only when human judgment truly needed
+   - Confident → edit + commit
+   - Needs decision → `evidence.ndjson {"phase":"decision","status":"pending"}`, no code change
+   - **Decision gate** — only these qualify: cross-module architecture tradeoffs needing human direction | business semantics ambiguity where fix may change intent | new dependency or breaking API required
+   - "Unsure how to fix", "Too large scope", "Pre-existing issue" are NOT valid decision reasons
+
+3. **Multi-CLI assist** — `maestro delegate` for cross-angle verification
+   - Different `--role` per phase (analyze / review / explore)
+   - All delegate calls `run_in_background: true`, wait for callback
+
+4. **Never abort for context exhaustion** — harness auto-compresses context; aborting due to "insufficient context" or "already ran N phases" is a discipline violation. Must complete through S_RECORD → END.
+
+**Zero-residual:** Every finding must have an action (fix / issue / decision). "Report only" and "pre-existing skip" are forbidden.
+</execution_discipline>
+
+<shared_schemas>
+
+### session.json standard fields
+
+```json
+{
+  "session_id": "{type}-odyssey-{YYYYMMDD-HHmmss}",
+  "current_state": "S_INTAKE",
+  "flags": { "skip_fix": false, "skip_generalize": false, "auto": false, "auto_confirm": false },
+  "phase_goals": [], "phase_goals_all_done": false,
+  "self_iteration_log": [],
+  "cross_phase_loops": 0, "max_loops": 5,
+  "created_at": "", "updated_at": ""
+}
+```
+
+Each command adds its own fields (e.g. `issue`, `target`, `requirement`).
+
+### evidence.ndjson base schema
+
+```json
+{"ts":"","phase":"","type":"","source":"","content":"","note":""}
+```
+
+Each command defines phase-specific extension fields (e.g. `hypothesis`, `severity`, `dimension`).
+
+### generalization_stats schema
+
+```json
+{
+  "patterns_extracted": 0, "total_hits": 0,
+  "cross_layer_confirmed": 0, "regression_risks": 0,
+  "by_layer": {"syntax": 0, "semantic": 0, "structural": 0},
+  "deepening_triggered": false
+}
+```
+
+</shared_schemas>
+
+<anti_stall>
+
+### progress_metrics fields
+
+```json
+{
+  "progress_metrics": {
+    "phase_stats": {},
+    "stale_count": 0,
+    "last_productive_phase": "",
+    "convergence_trend": "unknown"
+  },
+  "directions_tried": []
+}
+```
+
+### Progress Tracking
+
+After each analytical phase:
+1. Count `new_findings` (deduplicated) and `repeated` (matching existing evidence)
+2. Write to `progress_metrics.phase_stats[state_name]`
+3. `new == 0` → `stale_count++`, `convergence_trend = "stalling"`
+4. `new > 0` → `stale_count = 0`, update `last_productive_phase`
+5. 2 consecutive phases with declining new → `convergence_trend = "diminishing"`
+
+### Direction Diversity
+
+```json
+{
+  "phase": "S_DIAGNOSE", "round": 1,
+  "strategy_type": "scope_widen|perspective_shift|tool_switch|structural_pivot",
+  "strategy_desc": "expand search to utils/", "result": "2 new findings"
+}
+```
+
+**Dedup rule:** Check same-phase history before self-iteration → new strategy must differ in `strategy_type` or `strategy_desc` → all 4 types tried → force stale_count upgrade
+
+### Stall Escalation Ladder
+
+| stale_count | Strategy |
+|-------------|----------|
+| 0 | Normal advance |
+| 1 | **Shift perspective** — different CLI tool, reverse trace, manual read. Must differ from directions_tried |
+| 2 | **Structural pivot** — redefine search dimensions, switch analysis framework, decompose sub-problems. Not parameter tuning |
+| 3 | **Human escalation** — AskUserQuestion / `-y` auto INCONCLUSIVE and advance |
+
+### /loop Heartbeat (optional, `--heartbeat`)
+
+Suggest `/loop 270s`. Each phase updates `session.json.updated_at`. >15 min without update → alert + stale_count. 2 consecutive no-update → suggest `-c` resume.
+</anti_stall>
+
+<self_iteration>
+
+### Quality Gate
+
+| Dimension | Sufficient | Insufficient |
+|-----------|-----------|-------------|
+| Coverage | All known related files/modules analyzed | Missed targets discoverable via grep/git log |
+| Depth | ≥80% findings have file:line evidence | Most findings lack specifics |
+| Actionability | Each conclusion has concrete next action | "Consider reviewing" without action |
+
+**Progress-aware iteration:**
+- Phase complete → evaluate 3 dimensions + check `progress_metrics`
+- Any insufficient AND `stale_count < 3` → re-enter with expansion strategy (must pass directions_tried dedup)
+- Follow Stall Escalation Ladder for strategy selection
+
+**Expansion strategies:**
+- `scope_widen`: more directories, git log depth ×2, additional delegate angles
+- `perspective_shift`: different CLI tool, reverse trace, manual reading
+- `tool_switch`: switch to unused analysis tool
+- `structural_pivot`: redefine problem framework, decompose sub-problems
+
+**Exit:** all sufficient → advance | `stale_count >= 3` → log gaps, advance
+
+**Log:** `evidence.ndjson {"phase":"self-iteration"}` + `session.json.self_iteration_log[]` + `directions_tried[]`
+</self_iteration>
+
+<shared_actions>
+
+### A_GENERALIZE
+
+3-layer pattern extraction → 4-agent concurrent scan → cross-layer dedup → iterative deepening.
+
+**Pattern source:** specified by each command (root cause / audit findings / implementation patterns).
+
+**3-layer extraction:**
+
+| Layer | Method | Example |
+|-------|--------|---------|
+| Syntax | Regex → Grep | `eval(`, missing `await`, inline styles |
+| Semantic | Agent understands anti-pattern → scan | Unhandled async errors, missing validation |
+| Structural | File/module structure similarity | Same import structure, missing override |
+
+Write `session.json.patterns[]`: `[{id, source, layer, signature, description, risk, fix_template, confidence}]`
+
+**4-agent concurrent scan (single message):**
+
+| Agent | Strategy | Scope |
+|-------|----------|-------|
+| Syntax grep | Grep regex | Full project |
+| Semantic scan | Anti-pattern check | Related modules |
+| Structural match | Structurally similar files | Full project |
+| Historical grep | `git log -S` | Git history |
+
+**Cross-layer dedup:** multi-layer hit → boost | single-layer → `needs_review` | historically fixed → `regression_risk`
+
+**Iterative deepening:** module ≥3 hits → targeted deep scan (max 1 round)
+
+**Persist:** understanding.md generalization section + `session.json.generalization_stats`
+
+Commit: `"...({slug}): GENERALIZE — generalization scan complete"`
+
+### A_DISCOVER
+
+1. **Triage** each hit ±10 lines context → classify `bug` / `risk` / `safe`
+2. **Route:**
+   - bug + fix_template applicable → immediate fix → back to S_FIX
+   - bug + needs cross-module decision or no fix_template → create issue (with fix suggestion + impact analysis)
+   - risk → assess if guard can be added directly; yes → fix; no → create issue
+   - safe → skip
+   Normal: AskUserQuestion | `-y`: auto-fix bugs with fix_template, create issue for rest
+3. **Cross-phase loops:** `cross_phase_loops++`. `loops >= max_loops` → must log per-item reasons (blanket "pre-existing" forbidden)
+4. Append evidence + update understanding.md
+
+Commit: `"...({slug}): DISCOVER — discovery triage complete"`
+
+### A_RECORD
+
+1. Finalize understanding.md final section — learnings structured by each command's category table
+2. Mark record goal done. Pending decisions: Normal → AskUserQuestion | `-y` → skip (show deferred count)
+3. **Goal audit:** all `completion_confirmed` → `phase_goals_all_done = true`. Incomplete: Normal → AskUserQuestion | `-y` → auto accept
+4. `current_state = "COMPLETED"`, emit completion summary (format defined by each command)
+
+Commit: `"...({slug}): RECORD — summary and knowledge persistence"`
+
+</shared_actions>
+
+<shared_appendix>
+
+### Goal Prompt
+
+**Timing guard: display ONCE after INTAKE completes. Never re-display at RECORD.**
+
+```
+{Command} Odyssey session created. Copy the /goal below to set termination criteria:
+
+/goal Complete these goals:
+{for each G in phase_goals where status != "skipped":}
+- {G.id}: {G.goal} — done when: {G.done_when}
+{end for}
+{command-specific convergence rules}
+Pending phase=decision items must use AskUserQuestion, never self-resolve.
+```
+
+Continue execution after output, do not block.
+
+### `-y` generic rules
+
+- Decision pending → best-effort continue, record `deferred`
+- 3-strike escalation → auto INCONCLUSIVE
+- Discovery routing → auto-fix bugs with fix_template, create issue for rest
+- Record pending → skip, show deferred count
+- Record goal audit → auto accept
+
+`deferred` items shown in completion summary; recoverable via `-c`. Each command lists its own specific decision points.
+
+### Phase Goal Lifecycle
+
+`pending → done (confirmed=true)` | `pending → skipped (confirmed=true)` | `pending → failed (confirmed=false)`
+
+`phase_goals_all_done = true` only when ALL goals have `completion_confirmed == true`.
+
+### Pre-load (optional, missing does not block)
+
+| Layer | Command |
+|-------|---------|
+| Codebase docs | Read `.workflow/codebase/ARCHITECTURE.md` |
+| Wiki search | `maestro search "<keywords>" --json` (top 5) |
+| Specs | `maestro load --type spec --category <cat>` |
+| Role knowledge | `maestro search --category <cat>` → `maestro load --type knowhow --id <id>` |
+| Prior sessions | `Glob(".workflow/scratch/*-{type}-odyssey-*")` |
+
+### Common Error Codes
+
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E003 | error | Resume but no session found | Start new |
+| E004 | error | Delegate failed | Retry or proceed without |
+| W003 | warning | Generalization 0 hits | Skip discovery |
+| W004 | warning | Delegate parse failed | Use raw output |
+
+</shared_appendix>

package/workflows/overlays.md

@@ -0,0 +1,109 @@
+# Command Overlays — Format & Contract
+
+## File format
+
+Each overlay is a JSON file at `~/.maestro/overlays/<name>.json`:
+
+```json
+{
+  "name": "cli-verify-after-execute",
+  "description": "Run ccw cli quality review after /maestro-execute",
+  "targets": ["maestro-execute"],
+  "priority": 50,
+  "enabled": true,
+  "scope": "any",
+  "docs": ["docs/verify-protocol.md"],
+  "patches": [
+    {
+      "section": "execution",
+      "mode": "append",
+      "content": "## CLI Verification (overlay)\n\nAfter execution, run:\n\n```\nccw cli -p \"PURPOSE: Review just-executed changes for quality regressions\" --mode analysis --rule analysis-review-code-quality\n```\n"
+    },
+    {
+      "section": "required_reading",
+      "mode": "append",
+      "content": "@~/.maestro/overlays/docs/verify-protocol.md"
+    }
+  ]
+}
+```
+
+### Top-level fields
+
+| Field | Required | Notes |
+|---|---|---|
+| `name` | yes | Slug, matches `^[a-z0-9][a-z0-9-_]*$`. Filesystem-safe and unique across overlays. |
+| `description` | no | Short human summary shown in `maestro overlay list`. |
+| `targets` | yes | Array of command names without `.md` (e.g., `maestro-execute`). Missing/disabled targets are skipped with a log entry. |
+| `priority` | no | Default 50. Lower runs earlier. Alphabetical tiebreak. |
+| `enabled` | no | Default true. Set `false` to keep on disk but exclude from apply. |
+| `scope` | no | `global` / `project` / `any`. v1 is effectively global-only. |
+| `docs` | no | Relative paths under `~/.maestro/overlays/docs/` that this overlay references. Informational only. |
+| `patches` | yes | Non-empty array of patch objects. |
+
+### Patch fields
+
+| Field | Required | Notes |
+|---|---|---|
+| `section` | yes | One of `purpose`, `required_reading`, `deferred_reading`, `context`, `execution`, `error_codes`, `success_criteria`. For `new-section`, any slug. |
+| `mode` | yes | `append` / `prepend` / `replace` / `new-section`. |
+| `content` | yes | Raw markdown. Escaped `\n` inside JSON strings. No HTML-comment markers — the patcher adds its own. |
+| `afterSection` | no | For `new-section` only. Section slug after which the new block is inserted. Omit to append at end of file. |
+
+## Apply semantics
+
+On apply, each patch's `content` is wrapped in hashed markers:
+
+```
+<!-- maestro-overlay:<name>#<idx> hash=<short> -->
+...content...
+<!-- /maestro-overlay:<name>#<idx> -->
+```
+
+- **Idempotent**: Re-applying with the same content produces byte-identical output — no mtime churn.
+- **Drift-aware**: If the overlay's content changes, the marker block is replaced on next apply.
+- **Surgical removal**: `maestro overlay remove <name>` strips only the marker blocks for that overlay; text outside markers is preserved.
+
+### Mode behavior
+
+| Mode | Insertion point | Notes |
+|---|---|---|
+| `append` | Immediately before `</section>` | Most common. Adds a new step at the end of the section. |
+| `prepend` | Immediately after `<section>` | Adds a gate/precondition. |
+| `replace` | Between `<section>` and `</section>` | Destructive — overwrites the entire section body. Use sparingly. |
+| `new-section` | After `afterSection`'s `</...>` (or end of file) | Creates a brand-new tagged section. |
+
+## Install integration
+
+`maestro install` runs the following sequence:
+
+1. Copy pristine files (`.claude/commands/*` etc.) from the package to the target
+2. Restore `.md.disabled` state from the prior install
+3. **Apply overlays** — reads `~/.maestro/overlays/*.json`, applies each enabled one to the just-installed commands, writes `~/.maestro/manifests/overlays-<scope>.json`
+
+## CLI reference
+
+```bash
+maestro overlay list                        # show overlays and applied state
+maestro overlay apply                       # reapply to all known install scopes
+maestro overlay add <file.json>             # validate, install, apply
+maestro overlay remove <name>               # strip markers, delete overlay file
+```
+
+## Edge cases
+
+- **Disabled targets** (`.md.disabled`) are skipped silently.
+- **Missing targets** are skipped with a log entry — not an error.
+- **Multiple overlays on the same section** are sorted by `priority` (asc), alphabetical tiebreak. Each gets its own marker block, stacked inside the section.
+- **User edits outside markers** are preserved across reapply (inside-marker edits are overwritten — that's the contract).
+- **Invalid overlay JSON** never applies — errors surface in `maestro overlay list` and `maestro overlay add`.
+- **CRLF vs LF** is detected per-target and preserved on write.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `overlay load error` in `list` | Invalid JSON or schema | Fix the file at the reported path |
+| Marker start found but no matching end | File was hand-edited mid-marker | Delete the stale block manually; re-run `maestro overlay apply` |
+| Changes not visible in Claude Code | Claude Code caches loaded commands | Restart Claude Code after applying |
+| Overlay reapplied endlessly | Hash drift because content contains a dynamic value | Make the `content` deterministic — no timestamps |