pi-maestro-flow 0.2.0

package/skills/quality-debug/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: quality-debug
+description: "Use when bugs, test failures, or unexpected behavior need systematic root cause investigation Arguments: [issue description] [-c] [--from-uat <phase>] [--parallel]"
+allowed-tools: Read Write Edit Bash Glob Grep Agent AskUserQuestion
+---
+
+<purpose>
+Debug issues using scientific method with subagent isolation and persistent debug state. Three entry modes (standalone, from-UAT, parallel) and structured root cause collection with UAT feedback loop. Full algorithm defined in workflow debug.md.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/debug.md
+</required_reading>
+
+<context>
+User's issue: $ARGUMENTS
+
+**Flags:**
+- `--from-uat <phase>` -- Read gaps from phase's uat.md as pre-filled symptoms
+- `--parallel` -- Spawn parallel debug agents (one per gap cluster)
+
+**All context via state.json.artifacts[]:**
+
+```
+related = artifacts.filter(a =>
+  a.phase === target_phase && a.milestone === current_milestone
+).sort_by(completed_at asc)
+```
+
+Each artifact's type determines its outputs at `.workflow/{a.path}/`:
+- **execute** → .summaries/, .task/ (source of code changes)
+- **review** → review.json (findings guide hypothesis formation)
+- **debug** → understanding.md, evidence.ndjson (prior investigations, avoid re-investigation)
+- **test** → uat.md (--from-uat gap source), .tests/
+
+### Pre-load (optional, proceed without)
+- Codebase docs: `.workflow/codebase/ARCHITECTURE.md` → module boundaries
+- Wiki: `maestro search "<symptom keywords>" --json` → prior investigations
+- Specs: `maestro load --type spec --category debug --keyword "<symptom>"` → known issues/workarounds
+- Role knowledge: `maestro search --category debug` → select relevant → `maestro load --type knowhow --id`
+
+**Output**: `DEBUG_DIR = .workflow/scratch/{YYYYMMDD}-debug-P{N}-{slug}/` (P{N} = phase number when phase-scoped; omit for standalone). Output directory rules defined in workflow debug.md Step 4.
+
+**Output boundary**: ALL file writes MUST target `DEBUG_DIR` or `.workflow/state.json` only. NEVER modify source code, test files, or other artifacts outside these paths during investigation.
+</context>
+
+<invariants>
+1. **Investigation is read-only on source** — debug MUST NOT modify source code, test files, or execution artifacts. Diagnosis produces understanding.md, evidence.ndjson, and reports only.
+2. **Root cause requires reproduction** — NEVER declare a root cause confirmed without evidence (code trace, log entry, or reproduction steps). Hypothesis without evidence stays "suspected".
+3. **Evidence is append-only** — evidence.ndjson entries MUST only be appended, NEVER modified or deleted. Each entry is an immutable observation.
+4. **Confidence is multi-factor** — root cause confidence MUST use the multi-factor scoring model (Step 7.0). NEVER use bare high/medium/low without dimensional breakdown.
+5. **Prior investigations are consulted** — when related debug artifacts exist, check understanding.md for prior root causes. NEVER re-investigate an already-confirmed root cause without new symptoms.
+6. **Fix direction is not fix execution** — debug produces `fix_direction` and `affected_files` but NEVER applies fixes. Fix execution belongs to plan→execute cycle.
+</invariants>
+
+<execution>
+Follow '~/.maestro/workflows/debug.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Input → Investigation**
+- REQUIRED: Symptoms gathered (interactive) or loaded from UAT (--from-uat).
+- REQUIRED: Debug output directory created.
+- BLOCKED if missing: cannot investigate without symptom baseline.
+
+**GATE 2: Investigation → Diagnosis**
+- REQUIRED: Debug agent(s) spawned with full symptom context.
+- REQUIRED: evidence.ndjson written with structured entries.
+- REQUIRED: understanding.md tracks evolving understanding.
+- BLOCKED if incomplete: continue investigation before declaring root cause.
+
+**GATE 3: Diagnosis → Completion**
+- REQUIRED: Root causes collected with fix_direction and affected_files.
+- REQUIRED: Multi-factor confidence scored per gap.
+- REQUIRED: Readiness gate checked and pressure pass completed.
+- BLOCKED if inconclusive: resume session or escalate.
+
+**Register artifact on completion (phase-scoped only):**
+
+Confirm before writing:
+```
+AskUserQuestion("Register debug artifact DBG-{NNN} in state.json? (yes/no)")
+→ yes: proceed with write
+→ no: skip registration, continue to knowledge inquiry
+```
+
+```
+Append to state.json.artifacts[]:
+{
+  id: nextArtifactId(artifacts, "debug"),  // DBG-001
+  type: "debug",
+  milestone: current_milestone,
+  phase: target_phase,
+  scope: "phase",
+  path: "scratch/{YYYYMMDD}-debug-P{N}-{slug}",
+  status: all_diagnosed ? "completed" : "failed",
+  depends_on: triggering_review_id || exec_art.id,
+  harvested: false,
+  created_at: start_time,
+  completed_at: now()
+}
+```
+
+### Post-debug Knowledge Inquiry
+
+For each matching condition, ask the user explicitly:
+
+| Condition | Ask | Route |
+|-----------|-----|-------|
+| Recurring root cause pattern (seen in prior debug) | "Document in debug-notes.md?" | spec-add debug |
+| Non-obvious fix / workaround | "Record as learning?" | spec-add learning |
+| Root cause = architectural boundary violation | "Update architecture-constraints.md?" | spec-add arch |
+
+```
+AskUserQuestion("<ask text> (yes/no)")
+→ yes: Skill("spec-add", "<category> <content> --description \"<summary>\"")
+→ no: skip this entry, proceed to next condition or completion
+```
+
+</execution>
+
+<completion>
+### Standalone report
+
+```
+--- COMPLETION STATUS ---
+STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_RETRY
+CONCERNS: {description if applicable}
+--- END STATUS ---
+```
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Root cause found, fix needed | `/maestro-plan {phase} --gaps` |
+| Root cause found (from UAT), auto-fix | `/quality-test {phase} --auto-fix` |
+| Inconclusive, need more info | `/quality-debug {issue} -c` (resume) |
+| Standalone fix already applied | `/maestro-execute {phase}` |
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Issue description required (no arguments, no active sessions) | Check arguments format, re-run with correct input |
+| E002 | error | UAT file not found for --from-uat phase | Verify UAT file exists for specified phase |
+| W001 | warning | Existing debug session found, offer resume | Review existing sessions, choose resume or new |
+| W002 | warning | Checkpoint reached, user input needed | Provide requested input to continue |
+| W003 | warning | Some gaps inconclusive, partial diagnosis | Review partial results, retry inconclusive gaps |
+</error_codes>
+
+<success_criteria>
+- [ ] Input parsed: standalone, --from-uat, or --parallel mode determined
+- [ ] Active sessions checked and resume offered if applicable
+- [ ] Symptoms gathered (interactive) or loaded from UAT (pre-filled)
+- [ ] Debug output directory created (phase .debug/ or scratch/)
+- [ ] Debug agent(s) spawned with full symptom context
+- [ ] If --parallel: one agent per gap cluster, all concurrent
+- [ ] evidence.ndjson written with structured NDJSON entries
+- [ ] understanding.md tracks evolving understanding per cluster
+- [ ] Root causes collected with fix_direction and affected_files
+- [ ] Multi-factor confidence scored per gap (Step 7.0) replacing simple high/medium/low
+- [ ] Readiness gate checked before ROOT CAUSE declaration
+- [ ] Pressure pass completed on confirmed hypothesis
+- [ ] Confidence table appended to understanding.md
+- [ ] If --from-uat: uat.md gaps updated with diagnosis artifacts
+- [ ] Results unified into diagnosis summary with confidence section
+- [ ] Next step routed (plan --gaps + execute if fix needed, verify if fix applied, resume if inconclusive)
+</success_criteria>

package/skills/quality-refactor/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: quality-refactor
+description: "Use when accumulated tech debt needs systematic identification and safe reduction Arguments: [<scope>]"
+allowed-tools: Read Write Edit Bash Glob Grep Agent AskUserQuestion
+---
+
+<purpose>
+Targeted refactoring with safety guarantees: plan → confirm → execute with test verification per change → reflection-log.md.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/refactor.md
+</required_reading>
+
+<context>
+Scope: $ARGUMENTS (required)
+- Module path: "src/auth" - specific directory
+- Feature area: "authentication" - conceptual scope
+- "all" - full codebase scan
+
+If not provided, prompt user for scope.
+
+### Pre-load context (before refactoring)
+
+1. **Coding specs**: Run `maestro load --type spec --category coding` to load coding conventions. Apply conventions to all refactored code.
+2. **Review specs**: Run `maestro load --type spec --category review` to load review standards. Use as quality gate for refactored code.
+3. **Role Knowledge**:
+   - Browse: `maestro search --category coding`
+   - Identify task-relevant entries, then load: `maestro load --type knowhow --id <id1> [id2...]`
+4. All are optional — proceed without if unavailable.
+
+**Output boundary**: Refactoring modifies source files within the declared scope only. Ancillary outputs (reflection-log.md) MUST target `.workflow/scratch/{YYYYMMDD}-refactor-{slug}/`. NEVER modify files outside the confirmed scope without re-confirmation.
+</context>
+
+<invariants>
+1. **Plan before change** — NEVER apply refactoring changes without a confirmed plan. Every modification traces to a plan item.
+2. **Behavioral equivalence** — refactoring MUST preserve existing behavior. All tests MUST pass after each individual change, not just at the end.
+3. **Scope is locked after confirmation** — once the user confirms the refactoring plan, do NOT expand scope to include additional files or changes without re-confirmation.
+4. **Incremental verification** — each discrete refactoring step MUST be verified (tests run) before proceeding to the next. NEVER batch multiple unrelated changes into a single verification.
+5. **No feature creep** — refactoring MUST NOT add new functionality, change APIs, or alter public interfaces. If a beneficial API change is discovered, log it as a recommendation, do NOT apply it.
+6. **Rollback safety** — if any test fails after a refactoring step, revert that specific change before attempting alternatives. NEVER proceed with failing tests.
+</invariants>
+
+<execution>
+Follow '~/.maestro/workflows/refactor.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Analysis → Plan**
+- REQUIRED: Affected files and dependencies identified.
+- REQUIRED: Refactoring plan created with specific changes.
+- BLOCKED if missing: cannot refactor without identified targets.
+
+**GATE 2: Plan → Execution**
+- REQUIRED: User confirmed refactoring plan.
+- BLOCKED if not confirmed: do not apply changes without approval.
+
+**GATE 3: Execution → Completion**
+- REQUIRED: All changes applied with test verification per modification.
+- REQUIRED: Zero regressions (all tests pass).
+- REQUIRED: reflection-log.md written with strategy and outcomes.
+- BLOCKED if tests fail: fix regressions before completing.
+
+**Knowledge inquiry on completion:**
+After successful refactoring, ask user once: "Record refactoring pattern as coding convention?" If yes → `Skill("spec-add", "coding \"<title>\" \"<pattern>\" --keywords <kw1>,<kw2> --description \"<summary>\"")`.
+</execution>
+
+<completion>
+### Standalone report
+
+```
+--- COMPLETION STATUS ---
+STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_RETRY
+CONCERNS: {description if applicable}
+--- END STATUS ---
+```
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| All tests pass | `/quality-sync` (update codebase docs) |
+| Test failures after refactor | `/quality-debug "test failures after refactor in {scope}"` |
+| No test suite available | `/quality-auto-test {phase}` |
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Refactoring scope/description required | Prompt user for module path, feature area, or "all" |
+| E002 | error | Test suite not available for affected area | Suggest creating tests first, or proceed with manual verification |
+| W001 | warning | Partial test coverage for affected area | Note uncovered areas, proceed with extra caution |
+</error_codes>
+
+<success_criteria>
+- [ ] Refactoring plan created and confirmed by user
+- [ ] Changes implemented according to plan
+- [ ] All tests pass after refactoring
+- [ ] No regressions introduced
+- [ ] reflection-log.md written with strategy and outcomes
+</success_criteria>

package/skills/quality-retrospective/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: quality-retrospective
+description: "Use after completing a phase to extract lessons, patterns, and improvement opportunities Arguments: [phase|N..M] [--lens technical|process|quality|decision] [--all] [--no-route] [--compare N] [-y]"
+allowed-tools: Read Write Edit Bash Glob Grep Agent AskUserQuestion
+---
+
+<purpose>
+Post-execution retrospective (复盘): four parallel lenses (technical/process/quality/decision) → distill insights → route to spec/knowhow/issue stores.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/retrospective.md
+</required_reading>
+
+<deferred_reading>
+- @~/.maestro/workflows/issue.md (issues.jsonl schema for auto-creation)
+- @~/.maestro/workflows/learn.md (tip routing via manage-knowhow-capture tip)
+- @~/.maestro/workflows/verify.md (verification.json schema for quality lens parsing)
+- @~/.maestro/workflows/review.md (review.json schema for quality lens parsing)
+</deferred_reading>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Flags:**
+- `-y` — Skip confirmation prompts for external writes (issues.jsonl, spec entries, knowhow capture)
+- `--no-route` — Skip routing stage (produce retrospective files only, no spec/issue/knowhow writes)
+- `--compare N` — Compare current phase retrospective against phase N (requires single phase argument)
+- `--all` — Run retrospective on all completed phases that lack retrospective.json
+- `--lens <name>` — Restrict to specific lens (technical|process|quality|decision); default: all four
+
+Modes (scan/single/range/all) and storage paths defined in workflow retrospective.md Argument Shape and Stages 1-7.
+
+**Output boundary**: ALL file writes MUST target the phase's retrospective directory (`.workflow/scratch/{YYYYMMDD}-retrospective-P{N}/`), `.workflow/state.json`, `.workflow/issues.jsonl`, or `.workflow/specs/` (append-only). NEVER modify source code, verification.json, review.json, plan.json, or other existing artifacts.
+</context>
+
+<invariants>
+1. **Source artifacts are read-only** — NEVER modify verification.json, review.json, plan.json, or any execution artifact. Retrospective reads these for analysis only.
+2. **Stable insight IDs** — `INS-{8hex}` MUST be deterministic from `hash(phase_num + lens + title)`. Re-runs MUST NOT create duplicate insights.
+3. **Routing requires confirmation** — unless `-y` flag is set, every external write (issues.jsonl, spec entry, knowhow capture) MUST be confirmed by user before execution.
+4. **Lens independence** — each lens agent (technical/process/quality/decision) operates independently. One lens's findings MUST NOT suppress or override another's.
+5. **Append-only for specs** — learnings.md entries are appended as `<spec-entry>` blocks. NEVER overwrite or restructure existing entries.
+6. **Archive before overwrite** — if retrospective.json already exists for a phase, the existing file MUST be archived before writing a new version.
+</invariants>
+
+<execution>
+Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Input → Lens Analysis** (Stages 1-3 → Stage 4)
+- REQUIRED: Mode resolved (scan/single/range/all) and phases validated.
+- REQUIRED: At least one phase selected with status=completed and existing artifacts.
+- REQUIRED: Read-only — no file writes in Stages 1-3.
+- BLOCKED if no valid phases: E004/E005.
+
+**GATE 2: Lens Analysis → Routing** (Stages 4-5 → Stage 6)
+- REQUIRED: All requested lens agents returned valid JSON (or W001 logged for partial).
+- REQUIRED: Insights distilled with stable `INS-{8hex}` IDs.
+- REQUIRED: Archive existing `retrospective.{md,json}` before overwrite.
+- BLOCKED if all lens agents failed: cannot synthesize without results.
+
+**GATE 3: Routing → Completion** (Stage 6 → Stages 7-8)
+- REQUIRED: `retrospective.json` written with metrics, findings, insights, routing.
+- REQUIRED: `retrospective.md` written (human-readable).
+- REQUIRED: Issue rows match canonical `issues.jsonl` schema (status "open", full fields).
+- REQUIRED: Note tips routed via `Skill({ skill: "manage-knowhow-capture", args: "tip ..." })`.
+- REQUIRED: Unless `-y` flag is set, confirm before each external write (issues.jsonl append, spec-entry append, knowhow-capture). With `-y`, skip all confirmation prompts.
+- BLOCKED if routing incomplete: finish all write operations before reporting.
+
+### Execution Constraints
+
+- **Parallel lens dispatch**: Stage 4 spawns one Agent per active lens in a single message.
+- **Stable IDs**: `INS-{8 hex}` from `hash(phase_num + lens + title)` — re-runs do not duplicate.
+- **No source modification**: Never modify verification.json, review.json, plan.json.
+- **Backward-compat**: Append to `.workflow/specs/learnings.md` only if file already exists.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | error | `.workflow/` not initialized — run `/maestro-init` first | parse_input |
+| E002 | error | Unknown `--lens` name (allowed: technical, process, quality, decision) | parse_input |
+| E003 | error | `--compare` requires a single phase argument | parse_input |
+| E004 | error | Phase has not executed yet — no `.task/` or `.summaries/` artifacts | load_artifacts |
+| E005 | error | Phase argument out of range / phase directory not found | scan_unreviewed |
+| W001 | warning | One or more lens agents failed — proceeding with partial coverage | multi_lens_analysis |
+| W002 | warning | Existing retrospective.json found and not `--all` — prompted user to overwrite | scan_unreviewed |
+| W003 | warning | `manage-knowhow-capture tip` did not return parseable INS id; fell back to direct write | route_outputs |
+| W004 | warning | `--compare` target phase has no retrospective.json; delta omitted | load_artifacts |
+</error_codes>
+
+<success_criteria>
+- [ ] Mode correctly resolved (scan / single / range / all)
+- [ ] At least one phase selected and validated (status == "completed", artifacts exist)
+- [ ] All requested lens agents returned valid JSON, or W001 logged for partial coverage
+- [ ] `retrospective.json` written with metrics, findings_by_lens, distilled_insights, routing_recommendations
+- [ ] `retrospective.md` written and human-readable (tweetable, metrics table, per-lens findings, insights, routing table)
+- [ ] Each insight has a stable `INS-{8hex}` id
+- [ ] If routing enabled (default): every recommendation either created an artifact or was explicitly skipped by user
+- [ ] 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-knowhow-capture", args: "tip ..." })`
+- [ ] `.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
+</success_criteria>
+
+<completion>
+### Standalone report
+
+```
+--- COMPLETION STATUS ---
+STATUS: DONE|DONE_WITH_CONCERNS
+CONCERNS: {description if applicable}
+--- END STATUS ---
+```
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Insights routed | `/manage-status` |
+| Issues created | `/manage-issue list --source retrospective` |
+| Knowhow captured | `/manage-knowhow list` |
+| More phases to review | `/quality-retrospective --all` |
+</completion>

package/skills/quality-review/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: quality-review
+description: "Use after execution to evaluate code quality across correctness, security, performance, and architecture Arguments: <phase> [--level quick|standard|deep] [--dimensions security,architecture,...] [--skip-specs]"
+allowed-tools: Read Write Edit Bash Glob Grep Agent AskUserQuestion
+---
+
+<purpose>
+Multi-dimensional code review on a phase's changed files. Three levels (quick/standard/deep), auto-detected from file count. Level and dimension details in workflow review.md.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/review.md
+</required_reading>
+
+<deferred_reading>
+- [index.json](~/.maestro/templates/index.json) — read when updating phase index after review
+</deferred_reading>
+
+<context>
+Phase: $ARGUMENTS (required — phase number or slug)
+
+**Flags:**
+- `--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
+
+**All context via state.json.artifacts[]:**
+
+```
+related = artifacts.filter(a =>
+  a.phase === target_phase && a.milestone === current_milestone
+).sort_by(completed_at asc)
+```
+
+Each artifact's type determines its outputs at `.workflow/{a.path}/`:
+- **execute** → .summaries/, .task/, verification.json, plan.json (source of files to review)
+- **review** → review.json (prior verdict, findings — for delta comparison)
+- **debug** → understanding.md, evidence.ndjson (confirmed root causes)
+- **test** → uat.md, .tests/ (user-observable gaps)
+
+### Pre-load (optional, proceed without)
+- Codebase docs: `.workflow/codebase/ARCHITECTURE.md` → component boundaries, layer rules
+- Wiki constraints: `maestro search "architecture constraint" --json` → documented decisions
+- Specs: `maestro load --type spec --category review` → review standards, checklists, knowhow tools
+- Conflict state: `maestro spec conflict list` → 当前已标记冲突的 spec 条目（review 时优先关注）
+- Role knowledge: `maestro search --category review` → select relevant → `maestro load --type knowhow --id`
+
+**Output**: `REVIEW_DIR = .workflow/scratch/{YYYYMMDD}-review-P{N}-{slug}/` (P{N} = phase number, enables directory-level identification as state.json fallback)
+
+**Output boundary**: ALL file writes MUST target `REVIEW_DIR` or `.workflow/state.json` only. NEVER modify source code, execution artifacts, or files outside these paths.
+</context>
+
+<invariants>
+1. **Review is read-only on source** — NEVER modify source code, test files, or execution artifacts. Review produces reports only.
+2. **Findings require evidence** — every finding MUST reference file:line and include a code snippet or concrete description. No vague or unanchored findings.
+3. **Verdict is data-driven** — NEVER change verdict severity to accommodate user preference without new evidence. Verdicts flow from findings, not negotiation.
+4. **Dimension independence** — each review dimension produces findings independently. One dimension's results MUST NOT suppress or override another's.
+5. **Prior review delta** — when a prior review.json exists for the same phase, findings MUST be compared. Do NOT re-report already-resolved findings as new.
+6. **Spec conflict integrity** — if code contradicts a spec entry: if the code is the evolved practice (spec outdated), suggest `maestro spec supersede`; if genuinely disputed, flag via `maestro spec conflict mark`. NEVER silently accept the contradiction or edit the spec inline.
+</invariants>
+
+<execution>
+Follow '~/.maestro/workflows/review.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Setup → Review**
+- REQUIRED: Phase resolved and changed files collected from task summaries. E001/E002 if missing.
+- REQUIRED: Review level determined (explicit flag or auto-detected from file count).
+- BLOCKED if no changed files: E004.
+
+**GATE 2: Review → Aggregation**
+- REQUIRED: All dimension reviews executed (inline for quick, parallel agents for standard/deep).
+- REQUIRED: Deep-dive completed if triggered (standard: auto, deep: forced).
+
+**GATE 3: Aggregation → Completion**
+- REQUIRED: review.json written with findings, severity distribution, and verdict.
+- REQUIRED: Issues auto-created based on level thresholds.
+- REQUIRED: index.json updated with review status.
+- REQUIRED: Spec conflict check — if any finding directly contradicts a loaded spec entry (code behavior ≠ spec rule): if spec is outdated (code evolved), suggest `maestro spec supersede`; if genuinely disputed, suggest `maestro spec conflict mark`. Code is the single source of truth.
+
+**Output writes to REVIEW_DIR** (not EXEC_DIR):
+- `REVIEW_DIR/review.json` — findings, severity distribution, verdict
+
+**Register artifact on completion:**
+
+Confirm before writing state.json and issues.jsonl:
+```
+AskUserQuestion("Register review artifact REV-{NNN} in state.json and create {N} issues in issues.jsonl? (yes/no)")
+→ yes: proceed with both writes
+→ no: skip registration and issue creation, continue to completion
+```
+
+```
+Append to state.json.artifacts[]:
+{
+  id: nextArtifactId(artifacts, "review"),  // REV-001
+  type: "review",
+  milestone: current_milestone,
+  phase: target_phase,
+  scope: "phase",
+  path: "scratch/{YYYYMMDD}-review-P{N}-{slug}",    // relative to .workflow/
+  status: "completed",
+  depends_on: exec_art.id,                 // or prior debug/review if re-review
+  harvested: false,
+  created_at: start_time,
+  completed_at: now()
+}
+```
+
+Report format defined in workflow review.md Report Format section.
+</execution>
+
+<completion>
+### Standalone report
+
+```
+--- COMPLETION STATUS ---
+STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_RETRY
+CONCERNS: {description if applicable}
+--- END STATUS ---
+```
+
+Status mapping:
+- **DONE** — PASS verdict, no critical findings
+- **DONE_WITH_CONCERNS** — WARN verdict, issues found but non-blocking
+- **NEEDS_RETRY** — BLOCK verdict, critical findings require fix first
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| PASS verdict | `/quality-test {phase}` |
+| WARN verdict (non-blocking issues) | `/quality-test {phase}` (proceed with caveats) |
+| BLOCK verdict (critical findings) | `/maestro-plan {phase} --gaps` (fix first) |
+| Spec contradictions found | `maestro spec conflict list` → `/manage-knowledge-audit --scope spec` |
+| Want code cleanup | `/quality-refactor {phase}` |
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Phase argument required | Check arguments format, re-run with correct input |
+| E002 | error | Phase directory not found | Check arguments format, re-run with correct input |
+| E003 | error | No execution results found (no task summaries) | Verify execution completed with task summaries |
+| E004 | error | No changed files detected in phase | Verify execution completed with task summaries |
+| W001 | warning | Some dimension agents failed, partial results | Retry failed dimensions or accept partial results |
+| W002 | warning | Deep-dive iteration limit reached with unresolved criticals | Accept current findings or escalate manually |
+</error_codes>
+
+<success_criteria>
+- [ ] Phase resolved and changed files collected from task summaries
+- [ ] Review level determined (explicit flag or auto-detected)
+- [ ] Project specs loaded as review context (unless --skip-specs)
+- [ ] Dimension reviews executed (inline for quick, parallel agents for standard/deep)
+- [ ] All dimension results aggregated with severity classification
+- [ ] Deep-dive completed if triggered (standard: auto, deep: forced)
+- [ ] review.json written with complete findings, severity distribution, verdict
+- [ ] Issues auto-created based on level thresholds
+- [ ] index.json updated with review status
+- [ ] Next step routed by verdict (PASS→test, WARN→test with caveats, BLOCK→plan --gaps)
+</success_criteria>

package/skills/quality-sync/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: quality-sync
+description: "Sync codebase docs by tracing git diff impact Arguments: [--full] [--since <commit|HEAD~N>] [--dry-run]"
+allowed-tools: Read Write Edit Bash Glob Grep Agent AskUserQuestion
+---
+
+<purpose>
+Sync codebase docs after code changes: git diff → trace impact via doc-index.json → refresh `.workflow/codebase/` docs.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/sync.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- optional flags:
+- `--full` -- Complete resync of all tracked files (ignores git diff, rebuilds all docs)
+- `--since <commit|HEAD~N>` -- Diff since specific commit (default: last sync timestamp)
+- `--dry-run` -- Show what would be updated without writing changes
+
+**Output boundary**: ALL file writes MUST target `.workflow/codebase/`, `.workflow/state.json`, or `doc-index.json` only. NEVER modify source code or files outside `.workflow/`. `--dry-run` MUST suppress all writes.
+</context>
+
+<invariants>
+1. **Source code is read-only** — sync reads source files to generate documentation. NEVER modify source code, test files, or any non-documentation files.
+2. **Dry-run is side-effect-free** — when `--dry-run` is set, NO file writes occur. Report only what would change.
+3. **Impact trace before refresh** — NEVER regenerate a doc file without first tracing which source changes affect it via doc-index.json. Untargeted full-refresh requires explicit `--full` flag.
+4. **Idempotent sync** — running sync twice with the same diff MUST produce identical results. State.json timestamp prevents redundant re-runs.
+5. **Incremental by default** — without `--full`, only changed components are refreshed. NEVER silently expand to a full rebuild.
+</invariants>
+
+<execution>
+Follow '~/.maestro/workflows/sync.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Diff → Impact Trace**
+- REQUIRED: Git diff computed (or --full flag set for all files).
+- BLOCKED if no diff and no --full: nothing to sync (W001).
+
+**GATE 2: Impact Trace → Refresh**
+- REQUIRED: Affected components traced via doc-index.json.
+- BLOCKED if trace fails: cannot refresh docs without impact mapping.
+
+**GATE 3: Refresh → Completion**
+- REQUIRED: `.workflow/codebase/` docs refreshed for affected components.
+- REQUIRED: If `--dry-run` is set, skip state.json write and report what would change. Otherwise, update state.json with sync timestamp.
+- BLOCKED if missing: do not report completion without updated docs.
+</execution>
+
+<completion>
+### Standalone report
+
+```
+--- COMPLETION STATUS ---
+STATUS: DONE|DONE_WITH_CONCERNS
+CONCERNS: {description if applicable}
+--- END STATUS ---
+```
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Docs refreshed | `/manage-status` |
+| Major structural changes | `/manage-codebase-rebuild` |
+| Incremental refresh | Use `--since` flag |
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | .workflow/ not initialized | Suggest running `/maestro-init` first|
+| W001 | warning | No changes detected since last sync | Report clean state, skip updates |
+</error_codes>
+
+<success_criteria>
+- [ ] state.json updated with current sync timestamp (skipped if `--dry-run`)
+- [ ] Codebase docs refreshed for all affected components
+- [ ] doc-index.json reflects current file state
+- [ ] Changes tracked and logged
+- [ ] project.md Tech Stack section refreshed if dependency manifests changed
+</success_criteria>