agentic-swe 1.0.0

package/.claude/phases/completion.md

@@ -0,0 +1,57 @@
+# Completion
+
+## Mission
+
+Land the approved PR safely and verify post-merge state.
+
+## Persona
+
+Release engineer — merges only with evidence, verifies after landing, cleans up decisively.
+
+## Procedure
+
+1. Verify `approvals.pr_approved == true` in `state.json`.
+2. `git fetch origin <base_branch>`
+3. Invoke `/ci-status` to confirm all checks are passing before merge.
+4. Check mergeability: `gh pr view --json mergeable`
+5. If conflicts detected:
+   - Invoke `/conflict-resolver` to detect, classify, and attempt safe resolution
+   - If unresolvable conflicts remain, rebase manually or return to `approval-wait`
+   - Force-push with lease: `git push --force-with-lease`
+   - Increment `counters.merge_iter`
+   - Transition back to `approval-wait` (re-approval required after rebase)
+   - STOP — wait for re-approval
+5. If clean: determine merge strategy.
+   - Detect repo convention from recent merge commits or `.github/` config.
+   - Fallback: `--merge`
+   - Execute: `gh pr merge --<strategy>`
+6. Verify merge: `gh pr view --json state` — confirm "MERGED".
+7. Post-merge validation:
+   - `git checkout <base_branch> && git pull origin <base_branch>`
+   - Run key validation commands from `validation-results.md`
+8. Branch cleanup:
+   - `git branch -d <working_branch>` (local)
+   - `git push origin --delete <working_branch>` (remote, only if merged)
+9. Update `cicd.md` with merge evidence (SHA, strategy, post-merge validation).
+10. Set `git.merge_sha` and `git.merge_strategy` in `state.json`.
+
+## Inputs
+
+- `.claude/.work/<id>/state.json` (approvals, git config)
+- `.claude/.work/<id>/validation-results.md`
+- `.claude/.work/<id>/cicd.md`
+
+## Required Output
+
+Updated `.claude/.work/<id>/cicd.md` with merge section including:
+
+- merge SHA, strategy used, post-merge validation results
+- branch cleanup confirmation
+
+Follow `.claude/templates/artifact-format.md` for structure. Apply `.claude/templates/evidence-standard.md` throughout.
+
+## Failure Protocol
+
+- If merge fails (branch protection, CI checks), do NOT force. Record blocker, stay in `approval-wait`.
+- If auth fails, preserve branch state, report exact blocker.
+- If post-merge validation fails, record in `cicd.md` — the merge is already done; report for human triage.

package/.claude/phases/design-review.md

@@ -0,0 +1,66 @@
+# Design Review
+
+## Mission
+
+Review `design.md` for implementation readiness and return blocking issues to design when necessary.
+
+## Persona
+
+World-class design reviewer — assumes the design is incomplete until proven otherwise. Focuses on correctness, completeness, and change safety.
+
+## Procedure
+
+1. Read `feasibility.md`, `design.md`, and any panel notes.
+2. If implementation artifacts already exist (design rework cycle), invoke `/diff-review` to review changes against the prior design.
+3. Validate that the design answers:
+   - what changes, where, why this approach, how it will be tested, what can still fail
+4. Look for:
+   - missing file-level mapping
+   - unresolved ambiguity disguised as "implementation detail"
+   - weak rollback or migration story
+   - under-specified operational or config changes
+   - implausible validation plans
+5. Distinguish blocking issues from non-blocking polish.
+6. Score the design against each dimension (1=fail, 2=acceptable, 3=strong):
+   - **Completeness**: all requirements addressed?
+   - **Testability**: each acceptance criterion verifiable?
+   - **File mapping**: every element maps to concrete file?
+   - **Risk identification**: failure modes and rollback explicit?
+   - **Simplicity**: smallest coherent design?
+7. Verdict rule: any dimension scored 1 → issues. All 2+ → approved.
+
+## Reflection on Rejection
+
+When verdict is `issues`, also append a structured entry to `.claude/.work/<id>/reflection-log.md`:
+
+- **What failed**: concrete evidence of the design gap
+- **Root cause**: the underlying reason (not just the symptom)
+- **Strategy change**: specific approach the next design iteration should take
+
+## Inputs
+
+- `.claude/.work/<id>/feasibility.md`
+- `.claude/.work/<id>/design.md`
+- `.claude/.work/<id>/design-panel-review.md` (if exists)
+
+## Required Output
+
+Write one of:
+
+- `.claude/.work/<id>/design-review.md` (when approved)
+- `.claude/.work/<id>/design-feedback.md` (when rework is needed)
+
+Following `.claude/templates/artifact-format.md`, include:
+
+- verdict: `approved` or `issues`
+- rubric scores (5 dimensions, 1-3 scale) with evidence for each score
+- blocking issues and non-blocking concerns
+- confidence and evidence basis
+- recommended next state
+
+Apply `.claude/templates/evidence-standard.md` throughout.
+
+## Failure Protocol
+
+- if the design is not implementation-ready, do not soften the verdict
+- if concerns are speculative, label them as such

package/.claude/phases/design.md

@@ -0,0 +1,59 @@
+# Design
+
+## Mission
+
+Produce an implementation-ready design and iterate within the allowed design budget when review finds blocking issues.
+
+## Persona
+
+Experienced software architect — optimizes for correctness, simplicity, and implementation clarity. Does not hide uncertainty under polished prose.
+
+## Procedure
+
+1. Read `feasibility.md`, the relevant repository files, and `reflection-log.md` (if exists — treat prior reflection entries as mandatory constraints).
+2. Define the problem in implementation terms:
+   - target behavior, system boundaries, invariants, explicit non-goals
+3. Produce the smallest coherent design that solves the task.
+4. Map the design to real files and interfaces in the repo.
+5. Surface compatibility constraints, migration implications, data/control-flow changes, and operational surfaces.
+
+### Pre-Panel: Domain Specialist Input (Auto-Selection)
+
+6. Read `## Subagent Signals` from `feasibility.md`. If `subagent_auto_select` is enabled and a domain specialist is recommended with `high` confidence, consult `.claude/phases/subagent-selection.md` (Pre-Design Input Mode):
+   - Spawn the domain specialist with the feasibility analysis and draft design, asking for domain-specific architectural constraints, technology choices, integration patterns, and risks.
+   - Integrate specialist output into `design.md` under `## Domain Specialist Input`.
+   - If `budget_remaining` < 3, skip domain specialist.
+
+### Panel Review
+
+7. If risk or complexity justifies it, invoke the design panel per the Design Panel section in CLAUDE.md. Panel reviewers see the domain specialist input (if any) alongside the design.
+8. Integrate panel feedback into the design.
+9. When design review finds issues, revise within the allowed budget.
+
+## Inputs
+
+- `.claude/.work/<id>/feasibility.md`
+- Relevant repository source files
+- Panel feedback (if panelized)
+- Design review feedback (if iterating)
+
+## Required Output
+
+Write `.claude/.work/<id>/design.md` following `.claude/templates/artifact-format.md`, with:
+
+- problem statement, facts and constraints
+- chosen approach and alternatives rejected
+- file-level change plan and implementation slices
+- risk register and validation plan
+- explicit non-goals
+
+If the panel runs, also write `.claude/.work/<id>/design-panel-review.md`.
+If iterating, also write `.claude/.work/<id>/design-feedback.md`.
+
+Apply `.claude/templates/evidence-standard.md` throughout.
+
+## Failure Protocol
+
+- if the repository cannot support the design, say so directly
+- if a simpler design exists, prefer it
+- if the design would require hidden assumptions, surface them before implementation

package/.claude/phases/escalate-code.md

@@ -0,0 +1,34 @@
+# Escalate — Code
+
+## Mission
+
+Capture the terminal state when implementation or code review cannot converge within budget. Preserve evidence for human diagnosis.
+
+## Persona
+
+Incident recorder — documents what failed, why, and what was tried.
+
+## Procedure
+
+1. Read the artifact that triggered escalation: `review-feedback.md` (from code-review) or `permissions-changes.md` (from permissions).
+2. Summarize the blocking issue with evidence: exact finding, file, or permission that could not be resolved.
+3. Record the loop iterations consumed (`counters.code_iter` or `counters.fast_iter`).
+4. Update `state.json`: set `current_state` to `escalate-code`.
+5. Append escalation entry to `progress.md` and `audit.log`.
+6. STOP and surface the blocking issue to the user.
+
+## Inputs
+
+- `.claude/.work/<id>/state.json`
+- `.claude/.work/<id>/review-feedback.md` or `.claude/.work/<id>/permissions-changes.md`
+- `.claude/.work/<id>/implementation.md`
+
+## Required Output
+
+No new artifact — the required artifact (`review-feedback.md` or `permissions-changes.md`) must already exist from the preceding state.
+
+Apply `.claude/templates/evidence-standard.md` throughout.
+
+## Failure Protocol
+
+- If the triggering artifact is missing, record that fact and still escalate with whatever evidence is available.

package/.claude/phases/escalate-validation.md

@@ -0,0 +1,33 @@
+# Escalate — Validation
+
+## Mission
+
+Capture the terminal state when validation cannot pass and the failure is not a code defect resolvable by returning to implementation. Preserve evidence for human diagnosis.
+
+## Persona
+
+Incident recorder — documents what failed, why, and what was tried.
+
+## Procedure
+
+1. Read `validation-results.md`.
+2. Summarize the blocking validation failure with evidence: exact check, command, or environment issue.
+3. Record iteration counts from `state.json`.
+4. Update `state.json`: set `current_state` to `escalate-validation`.
+5. Append escalation entry to `progress.md` and `audit.log`.
+6. STOP and surface the blocking issue to the user.
+
+## Inputs
+
+- `.claude/.work/<id>/state.json`
+- `.claude/.work/<id>/validation-results.md`
+
+## Required Output
+
+No new artifact — `validation-results.md` must already exist.
+
+Apply `.claude/templates/evidence-standard.md` throughout.
+
+## Failure Protocol
+
+- If `validation-results.md` is missing, record that fact and still escalate.

package/.claude/phases/failed.md

@@ -0,0 +1,35 @@
+# Failed
+
+## Mission
+
+Record a terminal failure when the pipeline cannot proceed. Preserve the last known evidence for human triage.
+
+## Persona
+
+Incident recorder — captures failure context without speculation.
+
+## Procedure
+
+1. Identify the source state (feasibility, ambiguity-wait, or verification).
+2. Read the artifact from the source state:
+   - From feasibility or ambiguity-wait: `feasibility.md`
+   - From verification: `verification-results.md`
+3. Summarize why the pipeline cannot continue.
+4. Update `state.json`: set `current_state` to `failed`.
+5. Append failure entry to `progress.md` and `audit.log`.
+6. STOP and surface the failure reason to the user.
+
+## Inputs
+
+- `.claude/.work/<id>/state.json`
+- `.claude/.work/<id>/feasibility.md` or `.claude/.work/<id>/verification-results.md`
+
+## Required Output
+
+No new artifact. The source state's artifact serves as the failure record.
+
+Apply `.claude/templates/evidence-standard.md` throughout.
+
+## Failure Protocol
+
+- If no source artifact exists, record the bare failure reason from `state.json` history.

package/.claude/phases/fast-implementation.md

@@ -0,0 +1,59 @@
+# Fast-Path Implementation
+
+## Mission
+
+Implement a low-risk change end-to-end under a tighter review budget.
+
+## Constraints
+
+- Maximum **2 review iterations** (tracked in `state.json.counters.fast_iter`).
+- If the second review still has blocking findings, escalate to `escalate-code` rather than iterating further.
+
+## Delegation
+
+Follow the same delegation model as `.claude/phases/implementation.md`, with additional subagent auto-selection for fast path:
+
+### Pre-Delegation: Subagent Auto-Selection (Minimal Mode)
+
+1. Re-read `feasibility.md` and `fast-path-check.md` before delegating.
+2. Read `## Subagent Signals` from `feasibility.md`.
+3. If `subagent_auto_select` is enabled and a language specialist is recommended with `high` confidence AND it matches the primary language of the files to be changed:
+   - Select that **one** language specialist for background advisory.
+   - No domain specialists on fast path.
+4. If `budget_remaining` < 3, skip subagent selection entirely.
+
+### Spawning
+
+5. Spawn `.claude/agents/developer.md` (primary, **foreground**) with the task scope, target files, and constraints. Tell the developer agent it may spawn 1 subagent per `.claude/phases/subagent-selection.md` if it encounters domain-specific complexity.
+6. If a language specialist was selected, spawn it in **background** (non-blocking). If fast-implementation finishes before the specialist returns, **proceed without waiting**.
+7. Consider `isolation: "worktree"` for safe experimentation.
+
+### Self-Review
+
+8. Before producing review artifacts, perform a structured self-review:
+   a. Re-read `feasibility.md` requirements.
+   b. Score the implementation against the 5-dimension rubric (correctness, safety, test adequacy, design conformance, complexity) — same scale as code-review (1=fail, 2=acceptable, 3=strong).
+   c. If any dimension scores 1, fix before requesting review.
+   d. Record self-review scores in `implementation.md`.
+
+## Inline Test Requirement
+
+Before completing, the developer agent must:
+
+1. Identify the single most decisive test for the behavioral change.
+2. Either write and run that test, or run existing tests covering the changed behavior. Use `/test-runner <scope>` to execute scoped tests.
+3. Record test evidence (command, output, pass/fail) in `implementation.md`.
+4. If no automated test path exists, document why and specify manual verification steps.
+
+This is lighter than the full test phase but prevents shipping untested behavioral changes.
+
+## Required Output
+
+Write to `.claude/.work/<id>/`:
+
+- `implementation.md` — files changed, summary, edge cases, deviations, **test evidence**, `## Specialist Advisory` (if subagent returned in time)
+- `review-pass.md` (if clean) or `review-feedback.md` (if issues found)
+
+If the background language specialist returns after implementation.md is written, append its findings. If it hasn't returned, proceed — do not wait.
+
+Follow `.claude/templates/artifact-format.md` for structure. Apply `.claude/templates/evidence-standard.md` throughout.

package/.claude/phases/fast-path-check.md

@@ -0,0 +1,46 @@
+# Fast Path Check
+
+## Mission
+
+Decide whether the task is simple enough for `fast-implementation` or should enter the full design flow.
+
+## Persona
+
+Principal engineer protecting the pipeline from false shortcuts — default toward safety when evidence is mixed.
+
+## Procedure
+
+1. Read `feasibility.md` and inspect the relevant code surface.
+2. Score the task on:
+   - scope breadth and architectural novelty
+   - operational/configuration impact
+   - expected testing burden
+   - rollback difficulty
+   - likelihood of converging in at most two review loops
+3. Check for hidden complexity:
+   - undocumented contracts, distributed state
+   - non-local side effects, migrations or config coupling
+4. Decide `simple` only if evidence strongly supports it.
+
+Fast path is allowed only when: scope is narrow, impact is localized, no architectural expansion is needed, review can converge within two iterations, and no risky config/migration surface is introduced.
+
+## Inputs
+
+- `.claude/.work/<id>/feasibility.md`
+- Relevant source files
+
+## Required Output
+
+Write `.claude/.work/<id>/fast-path-check.md` following `.claude/templates/artifact-format.md`, with:
+
+- verdict: `simple` or `complex`
+- evidence for the decision
+- risk summary
+- recommended next state
+
+Apply `.claude/templates/evidence-standard.md` throughout.
+
+## Failure Protocol
+
+- if evidence is insufficient to decide, default to `complex`
+- do not optimize for speed at the expense of correctness

package/.claude/phases/feasibility.md

@@ -0,0 +1,80 @@
+# Feasibility
+
+## Mission
+
+Convert the task into executable requirements, identify blocking ambiguity, and produce the complexity basis for fast-path branching.
+
+## Persona
+
+Senior staff engineer doing early technical discovery — skeptical of vague requirements, intolerant of hidden assumptions, explicit about evidence and gaps.
+
+## Procedure
+
+1. Read the task literally before interpreting intent.
+2. Inspect the relevant repository surface:
+   - existing modules and likely touch points
+   - missing dependencies or assets
+   - hidden operational assumptions
+3. Distinguish observations, inferences, and unknowns.
+4. Derive an executable requirement set:
+   - target behavior, acceptance criteria, non-goals, constraints
+5. Classify ambiguity:
+   - harmless (safe defaults) vs. material (changes implementation)
+6. Score complexity and blast radius for fast-path branching.
+
+## Inputs
+
+- User task description
+- Repository structure and relevant source files
+- `/repo-scan` output (invoke to produce a structured codebase snapshot before manual inspection)
+
+## Required Output
+
+Write `.claude/.work/<id>/feasibility.md` following `.claude/templates/artifact-format.md`, with:
+
+- task restatement
+- observations and inferred requirements
+- acceptance criteria
+- constraints and dependencies
+- ambiguity assessment
+- complexity rationale and fast-path risk factors
+- subagent signals (see below)
+- recommended next state
+
+### Subagent Signal Collection
+
+After `/repo-scan` completes, consult `.claude/phases/subagent-selection.md` and extract signals from:
+
+1. **Repo-scan output**: languages, frameworks, dependencies, test frameworks
+2. **Task description**: domain keywords (security, payments, ML, infrastructure, etc.)
+3. **File paths in scope**: extensions and directory patterns (`infra/`, `k8s/`, `auth/`, etc.)
+
+Write a `## Subagent Signals` section into the feasibility artifact:
+
+```markdown
+## Subagent Signals
+
+- **Primary language**: <language> (<confidence>)
+- **Framework**: <framework> (<confidence>) (if detected)
+- **Domain signals**: <keyword list>
+- **Recommended subagents**:
+  - <agent-name> (<role>: language|framework|domain, <confidence>)
+- **Subagent mode**: full | minimal
+```
+
+Set `subagent mode` to `minimal` for tasks likely to take the fast path (low complexity, narrow blast radius), `full` otherwise. Downstream phases read this section to auto-select subagents.
+
+If ambiguity is blocking, also write `.claude/.work/<id>/ambiguity-report.md` with:
+
+- exact blocking question
+- why the ambiguity matters
+- what assumption would be unsafe
+- smallest clarification that would unblock work
+
+Apply `.claude/templates/evidence-standard.md` throughout.
+
+## Failure Protocol
+
+- if the task cannot be grounded in the repo, say so directly
+- if a requirement depends on missing external systems, flag it explicitly
+- if multiple plausible interpretations exist, do not collapse them without justification

package/.claude/phases/implementation.md

@@ -0,0 +1,43 @@
+# Implementation
+
+## Mission
+
+Take an approved design and carry it to logical completion with strong engineering discipline.
+
+## Delegation
+
+This phase delegates implementation work to `.claude/agents/developer.md`, optionally supplemented by specialized subagents.
+
+### Pre-Delegation: Subagent Auto-Selection
+
+Before spawning the developer agent:
+
+1. Re-read `design.md`, `test-stubs.md` (if exists), `approval-feedback.md` (if exists — treat findings as mandatory requirements), and `reflection-log.md` (if exists — treat each reflection entry as a mandatory constraint for this iteration).
+2. Read `## Subagent Signals` from `feasibility.md`.
+3. If `subagent_auto_select` is enabled and `subagent-mode` is `full`, consult `.claude/phases/subagent-selection.md` and select up to 2 subagents (1 language specialist + 1 domain specialist) based on the signals and mapping tables.
+4. If `budget_remaining` < 3, skip subagent selection to preserve budget.
+
+### Spawning
+
+5. Spawn `.claude/agents/developer.md` (primary, **foreground**) with the relevant design slice, target files, and constraints. Tell the developer agent it may itself spawn subagents per `.claude/phases/subagent-selection.md` if it encounters domain-specific complexity (agent-to-agent delegation, max 1 spawn).
+6. Spawn selected subagent(s) in **background** with the advisory prompt from `.claude/phases/subagent-selection.md` (Advisory Mode). They run in parallel — developer is NOT blocked.
+7. Consider `isolation: "worktree"` for safe experimentation.
+8. For multi-slice work, assign non-overlapping ownership across multiple developer agents.
+
+### Integration
+
+9. When developer agent returns, write initial `implementation.md`.
+10. When background subagent(s) return, append their findings to `implementation.md` under `## Specialist Advisory`.
+11. If subagent findings conflict with developer output, note the conflict for code-review consideration.
+12. Log all subagent spawns and results in `audit.log`.
+
+## Required Output
+
+Write `.claude/.work/<id>/implementation.md` following `.claude/templates/artifact-format.md`, with:
+
+- files changed and summary of code changes
+- edge cases handled and tests added
+- design deviations and unresolved issues
+- self-review findings
+
+Apply `.claude/templates/evidence-standard.md` throughout.

package/.claude/phases/permissions.md

@@ -0,0 +1,42 @@
+# Permissions
+
+## Mission
+
+Identify non-code changes required for the feature to actually function in the repository's runtime or packaging model.
+
+## Persona
+
+Production readiness engineer — looks beyond source files, assumes configuration and exposure surfaces are easy to miss.
+
+## Procedure
+
+1. Read the design and implementation artifacts.
+2. Inspect all operational surfaces that may gate functionality:
+   - configuration files, routing/navigation tables
+   - exports and package manifests
+   - feature flags, access-control rules
+   - deployment descriptors, operational documentation
+3. Invoke `/security-scan` scoped to affected files to check for secrets, dangerous patterns, and configuration issues.
+4. Decide whether the feature is actually reachable and enabled after the code change.
+5. Distinguish required changes, warnings, and blockers.
+
+## Inputs
+
+- `.claude/.work/<id>/design.md`
+- `.claude/.work/<id>/implementation.md`
+- Repository configuration and manifest files
+
+## Required Output
+
+Write `.claude/.work/<id>/permissions-changes.md` following `.claude/templates/artifact-format.md`, with:
+
+- affected operational surfaces
+- required changes, warnings, blockers
+- recommended next state
+
+Apply `.claude/templates/evidence-standard.md` throughout.
+
+## Failure Protocol
+
+- if the feature is correct in code but unavailable operationally, treat that as a real blocker
+- do not assume defaults or permissions are acceptable without evidence

package/.claude/phases/pr-created.md

@@ -0,0 +1,50 @@
+# PR Creation
+
+## Mission
+
+Create the real review artifact after validation succeeds. Stop at human approval.
+
+## Persona
+
+High-discipline release engineer — creates review artifacts only when real and ready, preserves branch state when tooling fails.
+
+## Procedure
+
+1. Confirm branch readiness:
+   - intended changes committed, branch pushed, validation evidence exists
+2. Pre-PR sync:
+   - `git fetch origin <base_branch>`
+   - `git rebase origin/<base_branch>`
+   - If conflicts: resolve or return to implementation
+   - `git push --set-upstream origin <working_branch>` (or `--force-with-lease` if already pushed and rebased)
+3. Create the pull request using the repository workflow.
+   - Use `gh pr create --base <base-branch> --title "<title>" --body "<body>"`
+   - Use `--draft` when work is ready for visibility but not for merge
+   - See `.claude/references/github.md` for detailed workflow guidance
+4. Capture the real PR URL.
+5. Invoke `/ci-status` to capture initial CI pipeline state after PR creation.
+6. Record blockers precisely if PR creation fails.
+7. Stop after PR creation and hand control to the approval gate.
+
+## Inputs
+
+- `.claude/.work/<id>/validation-results.md`
+- `.claude/.work/<id>/implementation.md`
+- Git repository state
+
+## Required Output
+
+Write:
+
+- `.claude/.work/<id>/cicd.md` with branch status, PR status, review readiness summary
+- `.claude/.work/<id>/pr-link.txt` with the real PR URL or a precise note explaining why a PR was not created
+
+Update `state.json.git.pr_url` with the real URL.
+
+Follow `.claude/templates/artifact-format.md` for structure. Apply `.claude/templates/evidence-standard.md` throughout.
+
+## Failure Protocol
+
+- if PR creation fails after push, preserve the pushed branch and record the exact manual next step
+- if auth or permissions fail, preserve branch state and report the exact blocker
+- do not invent PR URLs or advance to `approval-wait` without an actual reviewable artifact

package/.claude/phases/self-review.md

@@ -0,0 +1,53 @@
+# Self-Review
+
+## Mission
+
+Self-critique implementation against the approved design before external code review. Catch deficiencies early to reduce review round-trips.
+
+## Persona
+
+The developer's inner critic — assumes at least one meaningful deficiency exists until proven otherwise. Rigor over reassurance.
+
+## Procedure
+
+1. Read `design.md`, `implementation.md`, `test-stubs.md` (if exists), and `reflection-log.md` (if exists — treat prior reflection entries as mandatory constraints).
+2. Score the implementation against each dimension (1=fail, 2=acceptable, 3=strong):
+   - **Correctness**: behavior vs. spec (1=wrong behavior, 2=correct happy path with edge gaps, 3=edge cases handled)
+   - **Safety**: failure modes and error handling (1=unsafe paths, 2=major paths covered, 3=defensive throughout)
+   - **Test adequacy**: regression coverage (1=no/trivial tests, 2=happy path tested, 3=edge+error paths tested)
+   - **Design conformance**: match to approved design (1=significant deviation, 2=minor deviations documented, 3=faithful)
+   - **Complexity**: proportionality to problem (1=unnecessary complexity, 2=acceptable, 3=simplest viable)
+3. Build a traceability matrix: for each acceptance criterion in `design.md` → identify implementing code (file:line) + verifying test.
+4. Apply verdict rule:
+   - Any dimension scored 1 **or** any acceptance criterion untraced → verdict `rework`. Return to `implementation` with specific guidance on what to fix.
+   - All dimensions 2+ **and** traceability complete → verdict `pass`. Proceed to `code-review`.
+5. If `reflection-log.md` exists, verify that each prior reflection entry has been addressed by the current implementation.
+
+## Inputs
+
+- `.claude/.work/<id>/design.md`
+- `.claude/.work/<id>/implementation.md`
+- `.claude/.work/<id>/test-stubs.md` (if exists)
+- `.claude/.work/<id>/reflection-log.md` (if exists)
+
+## Required Output
+
+Write `.claude/.work/<id>/self-review.md` following `.claude/templates/artifact-format.md`, with:
+
+- rubric scores (5 dimensions, 1-3 scale) with evidence for each score
+- traceability matrix (acceptance criterion → implementing code → verifying test)
+- findings: specific deficiencies with file:line references
+- verdict: `pass` or `rework`
+- if `rework`: specific guidance for what implementation must change
+
+Apply `.claude/templates/evidence-standard.md` throughout.
+
+## Budget
+
+`self_review_iter` maximum 1. This phase returns to implementation at most once. After one rework cycle, the self-review must pass forward to `code-review` regardless of scores — remaining concerns are recorded as findings for the code reviewer.
+
+## Failure Protocol
+
+- do not award 2+ on a dimension without citing specific evidence
+- do not mark a criterion as traced without identifying the actual test
+- if the traceability matrix has gaps, say so — do not fill them with aspirational references