maestro-flow 0.5.42 → 0.5.43

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

@@ -21,7 +21,7 @@ Wave-based hypothesis-driven debugging using `spawn_agents_on_csv`. Wave 1 explo
 All mean: **return to evidence gathering**.
 
 ## Escalation Rule
-After **3 failed hypotheses**, STOP. Summarize failures, question architecture, present to user.
+After wave 1, if **0 hypotheses confirmed** (all refuted/inconclusive/failed) AND total hypotheses >= 3: STOP. Skip wave 2. Summarize failures, question architecture assumptions, present to user via `request_user_input` for guidance before proceeding.
 
 ## Backward Tracing
 Find where incorrect value appears → trace backward through call chain → fix at source, not symptom.
@@ -160,7 +160,7 @@ Each wave generates `wave-{N}.csv` with Input columns + `prev_context` only. Out
 5. **Discovery Board is Append-Only**: Never clear, modify, or recreate discoveries.ndjson
 6. **Skip on Refuted**: Wave 2 fix tasks skip if their hypothesis was refuted or inconclusive
 7. **Cleanup Temp Files**: Remove wave-{N}.csv AND wave-{N}-results.csv after results are merged into master tasks.csv
-8. **DO NOT STOP**: Continuous execution until all waves complete
+8. **Escalation gate**: After wave 1 merge, if 0 hypotheses confirmed AND total >= 3, STOP and present to user (overrides continuous execution). Otherwise, continuous execution until all waves complete
 </invariants>
 
 <execution>
@@ -254,7 +254,7 @@ spawn_agents_on_csv({
     properties: {
       id:                  { type: "string" },
       result_status:       { type: "string", enum: ["completed", "failed"] },
-      hypothesis_verdict:  { type: "string", enum: ["confirmed", "refuted", "inconclusive"], description: "Investigation outcome" },
+      hypothesis_verdict:  { type: "string", enum: ["confirmed", "refuted", "inconclusive"], description: "Investigation outcome. Use 'inconclusive' as fallback when result_status=failed." },
       findings:            { type: "string", maxLength: 500 },
       evidence_for:        { type: "string" },
       evidence_against:    { type: "string" },
@@ -294,7 +294,7 @@ REQUIRED STEPS:
 TERMINATION CONTRACT (mandatory — NO worker may end without calling report_agent_job_result):
   - Success path  → result_status=completed, hypothesis_verdict = confirmed | refuted, with evidence
   - Timeout path  → if approaching {max_runtime_seconds}, STOP investigation and report result_status=completed, hypothesis_verdict=inconclusive
-  - Failure path  → on any unrecoverable error, result_status=failed with error message
+  - Failure path  → on any unrecoverable error, result_status=failed, hypothesis_verdict=inconclusive, with error message
   - NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
 
 OUTPUT (return via report_agent_job_result; must match output_schema):
@@ -333,10 +333,10 @@ spawn_agents_on_csv({
     properties: {
       id:            { type: "string" },
       result_status: { type: "string", enum: ["completed", "failed"] },
-      fix_result:    { type: "string", enum: ["fixed", "fix_failed"], description: "Fix attempt outcome" },
+      fix_result:    { type: "string", enum: ["fixed", "fix_failed"], description: "Fix attempt outcome. Use 'fix_failed' as fallback when result_status=failed." },
       findings:      { type: "string", maxLength: 500 },
       fix_applied:   { type: "string" },
-      verified:      { type: "string", enum: ["true", "false"] },
+      verified:      { type: "string", enum: ["true", "false"], description: "Use 'false' as fallback when result_status=failed." },
       error:         { type: "string" }
     },
     required: ["id", "result_status", "fix_result", "findings", "verified"]
@@ -366,8 +366,8 @@ REQUIRED STEPS:
 TERMINATION CONTRACT (mandatory):
   - Success path → fix applied AND verified → result_status=completed, fix_result=fixed, verified="true"
   - Partial path → fix applied but verification failed → result_status=completed, fix_result=fix_failed, verified="false"
-  - Timeout path → approaching {max_runtime_seconds} with no fix applied → result_status=completed, fix_result=fix_failed with error="timeout"
-  - Failure path → cannot apply fix (file missing, parse error, etc.) → result_status=failed
+  - Timeout path → approaching {max_runtime_seconds} with no fix applied → result_status=completed, fix_result=fix_failed, verified="false", error="timeout"
+  - Failure path → cannot apply fix (file missing, parse error, etc.) → result_status=failed, fix_result=fix_failed, verified="false", with error message
   - NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
 
 OUTPUT (return via report_agent_job_result; must match output_schema):
@@ -399,11 +399,18 @@ CONSTRAINTS:
 
    Dimensions (4): hypothesis_quality, evidence_completeness, root_cause_isolation, fix_confidence. Factors (weights): evidence_depth(.30), evidence_strength(.25), coverage_breadth(.20), reproduction(.15), consistency(.10). Map to legacy: <40% = low, 40-70% = medium, >70% = high. Append confidence assessment to understanding.md.
 
-3. **UAT update** (if --from-uat): Update `uat.md` gaps with `root_cause`, `fix_direction`, `affected_files` for confirmed hypotheses.
+2c. **Side-effect confirmation gate** (skip when `-y/--yes`):
+   Before writing to external stores, present a summary to the user via `request_user_input`:
+   - UAT gaps to update (count + hypothesis titles) if --from-uat
+   - Issues to update (count + issue IDs)
+   - Artifact registration in state.json
+   The user can approve all, selectively exclude, or skip entirely.
 
-4. **Issue update**: If `issues.jsonl` exists, update matching issues with status `diagnosed`, add `context.suggested_fix` and `context.notes`.
+3. **UAT update** (approved items only; if --from-uat): Update `uat.md` gaps with `root_cause`, `fix_direction`, `affected_files` for confirmed hypotheses.
 
-5. **Register artifact** (phase-scoped only): Append to `state.json.artifacts[]` with `type: "debug"`, `id: DBG-NNN`, `depends_on: triggering_review_id || exec_art.id`.
+4. **Issue update** (approved items only): If `issues.jsonl` exists, update matching issues with status `diagnosed`, add `context.suggested_fix` and `context.notes`.
+
+5. **Register artifact** (approved items only; phase-scoped): Append to `state.json.artifacts[]` with `type: "debug"`, `id: DBG-NNN`, `depends_on: triggering_review_id || exec_art.id`.
 
 6. **Post-debug Knowledge Inquiry**: Prompt user to capture knowledge when:
    - Recurring root cause pattern detected -> `$spec-add debug`

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

@@ -95,12 +95,12 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column populated fr
 
 <invariants>
 1. **Test after every change** -- zero regressions tolerated
-2. **Revert on failure** -- never leave broken state
+2. **Revert on failure** -- never leave broken state; revert ONLY files listed in the task's `files_modified` output (tracked per worker), never `git checkout .` or `git reset --hard` which may discard unrelated user changes
 3. **Max 2 retries per task** with strategy adjustment
 4. **Reflection-driven** -- every round records strategy, outcome, adjustment
 5. **User approval required** before execution (Step 4)
 6. **Quick wins first** -- order by risk (low first) and dependency
-7. **CSV waves execute synchronously** — each refactoring task dispatched as single-row wave, wait for completion before next
+7. **Single-row waves** — each refactoring task dispatched as its own single-row wave (one task per wave, sequential execution). Wave numbers are assigned 1:1 per task in dependency-safe order (low-risk first, deps respected). No multi-row shared waves.
 8. **Incremental safety** -- each task is independently safe to apply or revert
 </invariants>
 
@@ -157,7 +157,7 @@ Initialize session folder `.workflow/.csv-wave/{dateStr}-refactor-{slug}/`.
 Initialize `reflection-log.md` and `discoveries.ndjson` in session folder.
 Build `tasks.csv` from plan.json tasks using csv_schema columns.
 
-**Wave computation**: Group independent same-risk tasks into shared waves. Dependent tasks go to later waves. Low-risk tasks wave first, high-risk last.
+**Wave computation**: Each task gets its own wave number (single-row per wave). Order: low-risk first, high-risk last, dependencies respected.
 
 For each wave N in ascending order:
 
@@ -210,7 +210,7 @@ REQUIRED STEPS:
   2. Apply refactoring per description, modifying only files in scope
   3. Verify EVERY convergence_criterion via grep (ALL must pass; ANY miss → failure)
   4. Run verification_cmd via Bash; capture pass/fail
-  5. If tests fail OR convergence fails → revert ALL changes for this task using git (or Edit reverse), set files_modified=""
+  5. If tests fail OR convergence fails → revert ONLY files this task modified (track touched files; use `git checkout -- <file>` per file, NOT `git checkout .` or `git reset --hard`), set files_modified=""
   6. Append discoveries (type=implementation_note / pattern) to {sessionFolder}/discoveries.ndjson
   7. Call report_agent_job_result EXACTLY ONCE
 

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

@@ -2,7 +2,7 @@
 name: quality-retrospective
 description: Use after completing a phase to extract lessons, patterns, and improvement opportunities
 argument-hint: "[phase|N..M] [--lens technical|process|quality|decision] [--all] [--no-route] [--compare N] [-y]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, spawn_agent, wait_agent, close_agent, request_user_input
 ---
 
 <purpose>
@@ -130,7 +130,7 @@ Each artifact's type determines its outputs at `.workflow/{a.path}/`:
 5. **Synthesizer is isolated**: `fork_turns: "none"` -- receives lens results only via message, not full conversation history
 6. **Stable INS-ids**: `INS-{8hex}` from `hash(phase_num + lens + title)` -- re-runs do not create duplicates
 7. **Archive before overwrite**: Move existing retrospective.{md,json} to `.history/` with timestamp before writing new ones
-8. **Spec learnings.md backward-compat**: Append to it only if it already exists -- never create it
+8. **Spec learnings.md**: Create `.workflow/specs/learnings.md` if it does not exist, then append insights
 9. **Route confirmation**: Unless `-y`, present routing table and ask per-group before writing spec/issue/knowhow
 10. **Lessons always written**: Append to `.workflow/specs/learnings.md` regardless of `--no-route` -- routing only controls spec/issue/knowhow creation
 </invariants>
@@ -166,9 +166,6 @@ Update plan: Stages 1-3 → completed; Stage 4 → in_progress.
 
 ### Stage 4: Context-Agent Fork + Parallel Lens Analysis
 
-**Archive if overwriting**:
-If existing `retrospective.{md,json}` present, move to `{artifact_dir}/.history/` with timestamp suffix before spawning.
-
 **Step 4a: Spawn context agent**
 ```javascript
 spawn_agent({
@@ -253,13 +250,15 @@ If `!AUTO_YES`: present routing table and ask confirmation before routing each g
 
 ### Stage 7: Write Artifacts
 
+**Archive if overwriting**: If existing `retrospective.{md,json}` present, move to `{artifact_dir}/.history/` with timestamp suffix before writing new ones.
+
 Write two files to `{target_dir}/`:
 - **retrospective.json**: phase, slug, timestamp, lenses_run, metrics, findings_by_lens, distilled_insights, routing_summary
 - **retrospective.md**: Header with phase/slug/timestamp, metrics table (tasks completed, test pass rate, review issues, UAT scenarios), findings by lens, distilled insights, routing summary
 
 Append each insight to `.workflow/specs/learnings.md`.
 
-If `.workflow/specs/learnings.md` already exists, append each insight as `<spec-entry>` (category=`learning`, auto-extract keywords, date=today, source=`retrospective`). Never create the file -- only append if it exists.
+If `.workflow/specs/learnings.md` does not exist, create it with a `# Learnings` header. Append each insight as `<spec-entry>` (category=`learning`, auto-extract keywords, date=today, source=`retrospective`).
 
 Update plan: Stages 1-7 → completed; Stage 8 → in_progress.
 

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

@@ -65,7 +65,7 @@ $quality-review --continue "20260318-review-P3-auth"
 **Flags**:
 - `-y, --yes`: Skip all confirmations (auto mode)
 - `-c, --concurrency N`: Max concurrent agents within each wave (default: 6)
-- `--continue`: Resume existing session
+- `--continue [session-id]`: Resume existing session. If session-id provided, load that session directly. If omitted, list available sessions in `.workflow/.csv-wave/` matching `*-review-*` and prompt user to select. Resume reads master `tasks.csv`, skips completed waves, and continues from the next pending wave.
 - `--level quick|standard|deep`: Explicit review level (default: auto-detect from file count)
 - `--dimensions <list>`: Comma-separated subset of dimensions to review (overrides level defaults)
 - `--skip-specs`: Skip loading project specs as review context
@@ -81,14 +81,14 @@ When `--yes` or `-y`: Auto-confirm dimension selection, skip interactive validat
 ### tasks.csv (Master State)
 
 ```csv
-id,title,description,dimension,changed_files,project_specs,review_level,deps,context_from,wave
-"1","Correctness Review","Review all changed files for correctness: logic errors, missing edge cases, incorrect return values, null/undefined handling, off-by-one errors. Classify each finding as critical/high/medium/low with file:line references.","correctness","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","Existing patterns use Result type for error handling","standard","","","1"
-"2","Security Review","Review all changed files for security vulnerabilities: injection flaws, XSS, CSRF, auth bypass, sensitive data exposure, insecure crypto. Reference OWASP Top 10. Classify each finding.","security","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","Auth uses bcrypt + JWT","standard","","","1"
-"3","Performance Review","Review all changed files for performance issues: N+1 queries, unnecessary re-renders, memory leaks, blocking operations, unoptimized algorithms.","performance","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","","standard","","","1"
-"4","Architecture Review","Review all changed files for architecture issues: layer violations, circular dependencies, inappropriate coupling, missing abstractions, SRP violations.","architecture","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","ESM modules, strict TypeScript","standard","","","1"
-"5","Maintainability Review","Review all changed files for maintainability: code duplication, overly complex functions, poor naming, missing types, unclear control flow.","maintainability","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","","standard","","","1"
-"6","Best Practices Review","Review all changed files for best-practice violations: error handling gaps, missing validation, hardcoded values, deprecated API usage, inconsistent patterns.","best-practices","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","","standard","","","1"
-"7","Aggregate + Deep-Dive","Aggregate all dimension findings. Calculate severity distribution. Determine verdict (PASS/WARN/BLOCK). If critical findings exist, perform deep-dive with cross-file impact analysis.","aggregation","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","","standard","1;2;3;4;5;6","1;2;3;4;5;6","2"
+id,title,description,dimension,changed_files,project_specs,review_level,deps,context_from,wave,status
+"1","Correctness Review","Review all changed files for correctness: logic errors, missing edge cases, incorrect return values, null/undefined handling, off-by-one errors. Classify each finding as critical/high/medium/low with file:line references.","correctness","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","Existing patterns use Result type for error handling","standard","","","1","pending"
+"2","Security Review","Review all changed files for security vulnerabilities: injection flaws, XSS, CSRF, auth bypass, sensitive data exposure, insecure crypto. Reference OWASP Top 10. Classify each finding.","security","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","Auth uses bcrypt + JWT","standard","","","1","pending"
+"3","Performance Review","Review all changed files for performance issues: N+1 queries, unnecessary re-renders, memory leaks, blocking operations, unoptimized algorithms.","performance","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","","standard","","","1","pending"
+"4","Architecture Review","Review all changed files for architecture issues: layer violations, circular dependencies, inappropriate coupling, missing abstractions, SRP violations.","architecture","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","ESM modules, strict TypeScript","standard","","","1","pending"
+"5","Maintainability Review","Review all changed files for maintainability: code duplication, overly complex functions, poor naming, missing types, unclear control flow.","maintainability","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","","standard","","","1","pending"
+"6","Best Practices Review","Review all changed files for best-practice violations: error handling gaps, missing validation, hardcoded values, deprecated API usage, inconsistent patterns.","best-practices","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","","standard","","","1","pending"
+"7","Aggregate + Deep-Dive","Aggregate all dimension findings. Calculate severity distribution. Determine verdict (PASS/WARN/BLOCK). If critical findings exist, perform deep-dive with cross-file impact analysis.","aggregation","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","","standard","1;2;3;4;5;6","1;2;3;4;5;6","2","pending"
 ```
 
 **Columns**:
@@ -105,6 +105,7 @@ id,title,description,dimension,changed_files,project_specs,review_level,deps,con
 | `deps` | Input | Semicolon-separated dependency task IDs |
 | `context_from` | Input | Semicolon-separated task IDs whose findings this task needs |
 | `wave` | Computed | Wave number (1 = dimension review, 2 = aggregation) |
+| `status` | Lifecycle | Task lifecycle state in master CSV: `pending` / `completed` / `failed` / `skipped` (initialized to `pending`; updated during merge from `result_status`) |
 | `result_status` | Output | `completed` / `failed` (returned via output_schema) |
 | `findings` | Output | Key review findings summary (max 500 chars) |
 | `severity_counts` | Output | JSON: `{"critical":N,"high":N,"medium":N,"low":N}` |
@@ -166,6 +167,12 @@ Parse `$ARGUMENTS` to extract:
 - `dimsMatch` from `--dimensions <list>`
 - `phaseArg` = remaining text after stripping all flags
 
+**Resume flow** (when `--continue`):
+1. If session-id argument provided: load `.workflow/.csv-wave/{session-id}/tasks.csv` directly
+2. If no session-id: scan `.workflow/.csv-wave/*-review-*` directories, list sessions with their status (pending wave counts), prompt user to select
+3. Read master `tasks.csv`, identify next pending wave (lowest wave number with `status == "pending"` rows), skip to Phase 2 for that wave
+4. If no pending rows remain, skip to Phase 3 (results aggregation)
+
 Session ID: `{YYYYMMDD}-review-P{phaseArg}-{phaseSlug}` (phaseSlug from index.json or roadmap)
 Session folder: `.workflow/.csv-wave/{sessionId}/` — create via `mkdir -p`
 
@@ -210,7 +217,7 @@ If `--dimensions` flag provided, override with explicit list.
 
 #### Wave 1: Dimension Reviews (Parallel)
 
-Filter master `tasks.csv` for `wave == 1 AND status == pending` → write `wave-1.csv` (no prev_context needed).
+Filter master `tasks.csv` for `wave == 1 AND status == "pending"` → write `wave-1.csv` (no prev_context needed).
 
 ```javascript
 spawn_agents_on_csv({
@@ -275,7 +282,7 @@ CONSTRAINTS:
 
 #### Wave 2: Aggregation + Deep-Dive
 
-Filter master `tasks.csv` for `wave == 2 AND status == pending`. If all wave 1 tasks failed, skip aggregation (invariant 6).
+Filter master `tasks.csv` for `wave == 2 AND status == "pending"`. If all wave 1 tasks failed, skip aggregation (invariant 6).
 
 Build `prev_context` from wave 1 findings (format: `[Task N: Title] summary...` per task). **Failed-dependency handling**: exclude failed task IDs from prev_context. If SOME wave 1 tasks failed, append gap_note listing missing dimensions so the aggregation agent knows its coverage is incomplete.
 Write `wave-2.csv` with `prev_context` column → execute `spawn_agents_on_csv` with `REVIEW_AGGREGATION_INSTRUCTION` (same termination contract; output_schema returns `result_status` enum [completed|failed], findings, plus `verdict` enum [PASS|WARN|BLOCK]) → merge results into master `tasks.csv` (map `result_status` → master `status` column) → delete both `wave-2.csv` and `wave-2-results.csv`.

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

@@ -37,8 +37,8 @@ Verify `.workflow/` directory exists — if missing, raise E001.
 If `--full`: skip diff, mark all tracked files as changed.
 
 Otherwise:
-1. Read last sync timestamp from `state.json` field `last_synced`
-2. If `--since` provided, use that as baseline
+1. Read last sync commit from `state.json` field `last_synced_commit` (a git commit hash). If `last_synced_commit` is missing, fall back to `git log --reverse --format=%H | head -1` (first commit) as baseline.
+2. If `--since` provided, use that as baseline (overrides `last_synced_commit`)
 3. Run `git diff --name-only {baseline} HEAD` to get changed files
 
 If no changes and not `--full`, report clean state (W001) and exit.

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

@@ -39,7 +39,7 @@ id,test_id,cluster,test_name,expected,reported,severity,target_files,issue_id,so
 ```
 
 Input: id, test_id, cluster, test_name, expected, reported, severity, target_files, issue_id, source_context.
-Output: root_cause, fix_direction, affected_files, evidence, error.
+Output (via output_schema): root_cause, fix_direction, affected_files, evidence, findings, error.
 </csv_schema>
 
 <invariants>
@@ -49,7 +49,7 @@ Output: root_cause, fix_direction, affected_files, evidence, error.
 4. **Batched writes** -- on issue, every 5 passes, or completion
 5. **Gap-fix loop max 2 iterations** -- prevent infinite loops
 6. **CSV parallel diagnosis** -- spawn_agents_on_csv for gap clusters, not sequential
-7. **Auto-create issues** -- every failed test -> issues.jsonl entry
+7. **Confirmed issue creation** -- every failed test -> issues.jsonl entry, but only after user confirmation (skip confirmation if `-y`); present batch summary (count + severity + titles) before writing
 8. **Issue lifecycle sync** -- registered -> planning -> executing -> completed/failed
 </invariants>
 
@@ -125,7 +125,7 @@ S_PRESENT:
   -> S_COMPLETE     WHEN: all tests done
 
 S_COMPLETE:
-  -> S_DIAGNOSE    WHEN: issues found      DO: write output files, register artifact in state.json
+  -> S_DIAGNOSE    WHEN: issues found      DO: write output files (test-results.json, coverage-report.json); artifact registration deferred to A_REPORT
   -> S_REPORT      WHEN: no issues
 
   **test-results.json**: `{ target, completed_at, results: [...], summary: { total, passed, issues, skipped } }`
@@ -172,7 +172,7 @@ Response processing:
 - color/spacing/alignment/looks off/typo -> cosmetic
 - Default: major
 
-On issue: auto-create in `.workflow/issues/issues.jsonl`:
+On issue: queue issue for creation (do NOT write yet). After all tests are presented (or on batched write triggers), present issue summary to user via `request_user_input` (skip if `-y`): show count, severity, and titles. User can approve all, selectively exclude, or skip. Then write approved issues to `.workflow/issues/issues.jsonl`:
 ```json
 { "id": "ISS-{YYYYMMDD}-{NNN}", "title": "UAT: {test.name} - {response truncated 100}",
   "status": "registered", "priority": "{from severity}", "severity": "{inferred}",
@@ -199,6 +199,7 @@ On issue: auto-create in `.workflow/issues/issues.jsonl`:
     "root_cause":      { "type": "string", "maxLength": 500 },
     "fix_direction":   { "type": "string" },
     "affected_files":  { "type": "string", "description": "Semicolon-separated file:line refs" },
+    "evidence":        { "type": "string", "description": "File:line references supporting the diagnosis" },
     "findings":        { "type": "string", "maxLength": 500 },
     "error":           { "type": "string" }
   },
@@ -233,6 +234,7 @@ OUTPUT (must match output_schema):
     "root_cause": "<concrete root cause with file:line, max 500 chars>",
     "fix_direction": "<high-level fix strategy, NOT code>",
     "affected_files": "<semicolon-separated file:line refs>",
+    "evidence": "<file:line references supporting the diagnosis>",
     "findings": "<one-sentence summary>",
     "error": "<message if not completed>"
   }
@@ -253,7 +255,7 @@ Max 2 iterations:
 
 1. UAT confidence scoring (4 dims: scenario_coverage, diagnostic_depth, observation_quality, closure_completeness). Readiness gate: block if scenario_coverage < 40% or blocker without diagnosis.
 2. Display summary: smoke results, pass/fail/skip counts, diagnosis stats, auto-fix results
-3. Register artifact in state.json (type: test)
+3. Register artifact in state.json (type: test) -- this is the ONLY registration point; S_COMPLETE defers registration here to avoid duplicates
 4. Route: all passed -> milestone-audit; auto-fix succeeded -> maestro-execute; gaps remain -> quality-debug; low coverage -> quality-auto-test
 
 </actions>

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

@@ -2,7 +2,7 @@
 name: security-audit
 description: OWASP Top 10 and STRIDE security auditing with supply chain analysis
 argument-hint: "[quick|standard|deep] [--scope <path>]"
-allowed-tools: spawn_agents_on_csv, Read, Bash, Glob, Grep, request_user_input
+allowed-tools: spawn_agents_on_csv, Read, Write, Bash, Glob, Grep, request_user_input
 ---
 <purpose>
 Systematic security audit covering OWASP Top 10, dependency supply chain, secrets detection,
@@ -57,7 +57,9 @@ Use `Grep` for pattern matching (e.g., `eval(`, `exec(`, `innerHTML`, `dangerous
 `sql.*\+.*req\.`, `process\.env` without validation).
 
 For `standard` and `deep` tiers, use `spawn_agents_on_csv` to parallelize OWASP category scans
-across multiple agents, one agent per 2-3 categories.
+across multiple agents, one agent per 2-3 categories. Unless `-y/--yes`, use `request_user_input` to confirm scope and category assignments before spawning.
+
+**Wave state transitions**: After spawn, merge results. 1+ completed → proceed to next phase. All failed + retry available → retry wave once. All failed + retry exhausted → mark phase `degraded`, continue with available results, log `evidence_incomplete`.
 
 **spawn_agents_on_csv contract** (OWASP scan):
 - CSV columns: `id, title, owasp_categories, scope_glob, deps, wave, status` (initial `status="pending"`); filter `wave==1 AND status=="pending"` before writing wave-1.csv.
@@ -74,11 +76,11 @@ across multiple agents, one agent per 2-3 categories.
     "top_issues":      { "type": "string", "description": "JSON array: [{title, severity, file:line, cwe}]" },
     "error":           { "type": "string" }
   },
-  "required": ["id", "result_status", "findings"]
+  "required": ["id", "result_status", "findings", "severity_counts"]
 }
 ```
 
-- Merge: `result_status` → master `status`; copy `findings`, `severity_counts`, `top_issues`, `error`.
+- Merge: `result_status` → master `status`; copy `findings`, `severity_counts`, `top_issues`, `error`. Clean results with no issues MUST return `severity_counts: "{\"critical\":0,\"high\":0,\"medium\":0,\"low\":0}"`.
 - **Termination contract** (embed in instruction):
   ```
   You MUST call report_agent_job_result EXACTLY ONCE before exiting.
@@ -201,7 +203,7 @@ NEXT: $quality-review
 --- END STATUS ---
 ```
 
-**Register artifact on completion** (so retrospective/harvest can trace this audit):
+**Register artifact on completion** (gated: unless `-y`, use `request_user_input` to confirm artifact registration and report writing before proceeding):
 ```
 Append to state.json.artifacts[]:
 {

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

@@ -1,7 +1,7 @@
 ---
 name: spec-add
 description: Add spec entry by category with role tagging
-argument-hint: "<category> <content>"
+argument-hint: "<category> <title> <content>"
 allowed-tools: Read, Write, Bash, Glob, Grep
 ---
 
@@ -17,11 +17,13 @@ $spec-add "quality All API endpoints must return structured error objects"
 
 **Valid categories**: coding, arch, quality, debug, test, review, learning, tools, bug, pattern, decision, rule, validation.
 
+**Input format**: `<category> <title> <content>` — category is the first token, title is a short identifier (quoted if multi-word), content is the remainder.
+
 **CLI alternative**: `maestro spec add <category> "<title>" "<content>" --keywords kw1,kw2 --description "<desc>" --source <src>`. Used by workflow agents (analyze, plan, execute) for programmatic spec enrichment.
 </purpose>
 
 <context>
-$ARGUMENTS — `<category> <content>` where category selects the target file.
+$ARGUMENTS — `<category> <title> <content>` where category selects the target file, title is a short identifier, and content is the spec body.
 
 **Category-to-file mapping (1:1, same as spec-load):**
 | Category | Target file |
@@ -49,9 +51,9 @@ Category is determined by the first positional argument.
 
 ### Step 1: Parse Input
 
-Extract category (first token) and content (remainder) from arguments.
-- Validate category is one of: coding, arch, quality, debug, test, review, learning, bug, pattern, decision, rule, validation (E003 if invalid)
-- Validate content is non-empty (E001 if missing)
+Extract category (first token), title (second token or quoted string), and content (remainder) from arguments.
+- Validate category is one of: coding, arch, quality, debug, test, review, learning, tools, bug, pattern, decision, rule, validation (E003 if invalid)
+- Validate title and content are non-empty (E001 if missing)
 
 ### Step 2: Validate Specs Directory
 
@@ -92,9 +94,9 @@ Display: category, target file, extracted keywords, and commands for verify (`$s
 <error_codes>
 | Code | Severity | Description |
 |------|----------|-------------|
-| E001 | fatal | Category and content are both required |
+| E001 | fatal | Category, title, and content are all required |
 | E002 | fatal | `.workflow/specs/` not initialized -- run `$spec-setup` first |
-| E003 | fatal | Invalid category -- must be one of: coding, arch, quality, debug, test, review, learning, ui, bug, pattern, decision, rule, validation |
+| E003 | fatal | Invalid category -- must be one of: coding, arch, quality, debug, test, review, learning, tools, bug, pattern, decision, rule, validation |
 </error_codes>
 
 <success_criteria>

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

@@ -29,8 +29,9 @@ $spec-load "--category review"
 | `test-conventions.md` | test |
 | `review-standards.md` | review |
 | `debug-notes.md` | debug |
-| `quality-rules.md` | review |
-| `learnings.md` | coding |
+| `quality-rules.md` | quality |
+| `learnings.md` | learning |
+| `tools.md` | tools |
 
 **--category loading**: Loads category's primary doc in full + matching entries from other files.
 

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

@@ -88,7 +88,7 @@ id,title,description,focus_area,output_file,deps,context_from,wave,status,findin
 </csv_schema>
 
 <invariants>
-1. **Start Immediately**: Initialize session, generate CSV, execute
+1. **Confirm Before Execute**: After session init and CSV generation, present mapper assignment summary to user via `request_user_input` for confirmation before spawning agents. Skip confirmation only if `-y` flag is set.
 2. **CSV is Source of Truth**: tasks.csv holds all mapper state
 3. **Discovery Board is Append-Only**: Mappers share findings
 4. **Partial Results OK**: If 3/4 mappers succeed, still write available docs
@@ -102,6 +102,8 @@ id,title,description,focus_area,output_file,deps,context_from,wave,status,findin
 
 Parse flags from `$ARGUMENTS` (`-y`, `-c N`, `--continue`). Extract focus area (default: "full"). Generate session ID: `{YYYYMMDD}-map-{focusArea}`. Create session folder at `.workflow/.csv-wave/{sessionId}/` and `.workflow/codebase/`.
 
+**Confirmation gate**: Present mapper assignment summary (4 tasks, focus area, concurrency) to user via `request_user_input`. Skip if `-y` flag is set.
+
 ### Phase 1: Generate tasks.csv
 
 Generate 4 mapper rows. If focus area specified, scope descriptions to that area.
@@ -133,6 +135,11 @@ spawn_agents_on_csv({
 
 Merge: write `master.status = result_status`, copy `findings` and `error`. Delete `wave-1.csv` and `wave-1-results.csv`.
 
+**Retry / degraded paths:**
+- If `spawn_agents_on_csv` call fails entirely: retry once. If second attempt fails, abort with E003.
+- If individual mapper fails (`result_status == "failed"`): mark that mapper as failed, continue with remaining mappers. Phase 3 writes partial output from completed mappers only.
+- If all 4 mappers fail: transition to degraded state — write empty output files with headers only, report E004, and exit gracefully.
+
 #### Mapper Worker Contract (MAPPER_INSTRUCTION)
 
 ```
@@ -192,6 +199,8 @@ Mappers share discoveries so other mappers can skip redundant exploration (e.g.,
 | Mapper agent timeout | Mark failed, continue with other mappers |
 | Mapper agent failed | Mark failed, output partial results |
 | .workflow/codebase/ exists | Prompt: refresh/skip/merge (auto-refresh with -y) |
+| E003: spawn_agents_on_csv failed twice | Abort with error message |
+| E004: All 4 mappers failed | Write empty output files with headers, exit gracefully |
 
 </error_codes>
 

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

@@ -1,7 +1,7 @@
 ---
 name: spec-remove
 description: Remove spec entry by ID
-argument-hint: "<entry-id> [--cascade]"
+argument-hint: "<entry-id> [--cascade] [-y]"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
@@ -25,7 +25,8 @@ $ARGUMENTS — entry ID to remove (e.g., `spec-learnings-003`)
 - `maestro search "<query>"` — BM25 search
 
 **Flags:**
-- `--cascade` — When the target spec is a ref-type entry (created via `spec-add --ref` and linked to a knowhow document), also delete the referenced knowhow file. Without this flag, ref-type removal leaves an orphan knowhow file.
+- `--cascade` — When the target spec has a `ref` attribute linking to a knowhow document, also delete the referenced knowhow file. Without this flag, removal leaves an orphan knowhow file. Cascade checks the entry's `ref` attribute in the `<spec-entry>` tag.
+- `-y` — Skip confirmation prompt and proceed with removal immediately.
 </context>
 
 <execution>

package/.codex/skills/team-coordinate/SKILL.md

@@ -182,6 +182,7 @@ S_EVAL_W3    — Evaluate Wave 3 participation                      PERSIST: ski
 S_WAVE_3     — Execute Wave 3 (Implementation)                    PERSIST: findings in master CSV
 S_EVAL_W4    — Evaluate Wave 4 participation                      PERSIST: skipped tasks if any
 S_WAVE_4     — Execute Wave 4 (Validation/Testing)                PERSIST: findings in master CSV
+S_DEGRADED_AGG — Degraded aggregation after all-failed retry      PERSIST: partial results
 S_AGGREGATE  — Generate report, export results                    PERSIST: context.md, results.csv
 </states>
 
@@ -193,10 +194,13 @@ S_CSV_GEN → S_EVAL_W1
 
 S_EVAL_W{N} → S_WAVE_{N}      WHEN: tasks qualify after evaluation
 S_EVAL_W{N} → S_EVAL_W{N+1}   WHEN: all tasks skipped or no tasks in wave
-S_WAVE_{N} → S_EVAL_W{N+1}    WHEN: wave complete, N < 4
+S_WAVE_{N} → S_EVAL_W{N+1}    WHEN: wave complete (some tasks succeeded), N < 4
+S_WAVE_{N} → S_WAVE_{N}       WHEN: all tasks in wave failed AND retry_count < 1 (retry once)
+S_WAVE_{N} → S_DEGRADED_AGG   WHEN: all tasks in wave failed AND retry_count >= 1
 
 S_EVAL_W4 → S_AGGREGATE       WHEN: after Wave 4 eval (regardless of skip)
 S_WAVE_4 → S_AGGREGATE        WHEN: Wave 4 complete
+S_DEGRADED_AGG → S_AGGREGATE  WHEN: degraded aggregation (partial results only)
 </transitions>
 
 <actions>
@@ -232,10 +236,11 @@ When `--continue`:
 
 1. **Parse task description**
 
-2. **Clarify if ambiguous** (skip if `-y`):
+2. **Confirm scope and deliverables** (skip if `-y`):
    - Scope? (specific files, module, project-wide)
    - Deliverables? (documents, code, reports)
    - Constraints? (technology, style)
+   - Always confirm via `request_user_input` unless `-y` is set
 
 3. **Signal detection** — scan keywords against `specs/role-catalog.md` §1 Signal Detection Table:
    - Match keywords → capabilities → roles
@@ -259,7 +264,7 @@ When `--continue`:
 
 8. **Dependency + context_from** — tasks in wave N depend on relevant tasks in wave N-1
 
-9. **Write `tasks.csv`** with all rows (Input columns only, no status/findings)
+9. **Write `tasks.csv`** with all rows (Input columns + lifecycle columns initialized: `status=pending`, `findings=""`, `files_modified=""`, `error=""`)
 
 10. **Write empty `discoveries.ndjson`**
 
@@ -454,7 +459,8 @@ Protocol: read before work, append-only, dedup by type+key.
 |-----------|----------|
 | No capabilities detected | Default to single `general` role in wave 1 |
 | All wave 1 tasks failed | Abort pipeline (downstream has no context) |
-| All tasks in wave N failed | Skip subsequent waves, proceed to aggregation |
+| All tasks in wave N failed (first attempt) | Retry wave once with same tasks |
+| All tasks in wave N failed (after retry) | Enter S_DEGRADED_AGG: aggregate partial results from prior waves, mark remaining waves skipped |
 | Evaluation skipped all tasks in wave | Normal — skip wave, continue to next |
 | Task timeout | Mark failed, cascade skip dependents |
 | Session not found (--continue) | Error with available session list |