Skip to content

try-works/role-model / .agents/skills/recursive-mode

recursive-mode

Unverified

Repository workflow orchestration skill for staged implementation, locked artifacts, late-phase receipts, and durable memory maintenance. Use when executing recursive-mode runs, resuming a run, locking a phase, or verifying locks.

FileKindSize
.agent/PLANS.mdmarkdown2.6 KB
.codex/AGENTS.mdmarkdown7.5 KB
.gitattributesother522 B
.gitignoreother553 B
.recursive/AGENTS.mdmarkdown3.3 KB
.recursive/DECISIONS.mdmarkdown1.1 KB
.recursive/README.mdmarkdown8.5 KB
.recursive/RECURSIVE.mdmarkdown107.5 KB
.recursive/STATE.mdmarkdown1.6 KB
.recursive/config/recursive-router.jsonconfig1.4 KB
.recursive/memory/MEMORY.mdmarkdown3.3 KB
.recursive/memory/archive/.gitkeepother1 B
.recursive/memory/domains/.gitkeepother1 B
.recursive/memory/episodes/.gitkeepother1 B
.recursive/memory/incidents/.gitkeepother1 B
.recursive/memory/patterns/.gitkeepother1 B
.recursive/memory/skills/SKILLS.mdmarkdown4.3 KB
.recursive/memory/skills/availability/.gitkeepother1 B
.recursive/memory/skills/issues/.gitkeepother1 B
.recursive/memory/skills/patterns/.gitkeepother1 B
.recursive/memory/skills/patterns/delegated-verification-and-refresh.mdmarkdown1.7 KB
.recursive/memory/skills/patterns/phase8-skill-memory-promotion.mdmarkdown1.4 KB
.recursive/memory/skills/usage/.gitkeepother1 B
.recursive/memory/skills/usage/skill-discovery-and-evaluation.mdmarkdown1.6 KB
.recursive/run/.gitkeepother1 B
AGENTS.mdmarkdown7.8 KB
LICENSEother11.1 KB
README.mdmarkdown17.8 KB
SKILL.mdskill md13.1 KB
agents/code-reviewer.mdmarkdown6.1 KB
agents/implementer.mdmarkdown6.3 KB
agents/openai.yamlconfig202 B
docs/templates/commands/check-reusable-repo-hygiene.mdmarkdown1.3 KB
docs/templates/commands/recursive-closeout.mdmarkdown2.8 KB
docs/templates/commands/recursive-init.mdmarkdown2.2 KB
docs/templates/commands/recursive-lock.mdmarkdown1.3 KB
docs/templates/commands/recursive-review-bundle.mdmarkdown3.6 KB
docs/templates/commands/recursive-status.mdmarkdown2.0 KB
docs/templates/commands/recursive-subagent-action.mdmarkdown4.2 KB
docs/templates/commands/test-recursive-mode-smoke.mdmarkdown3.4 KB
docs/templates/hooks/hooks.jsonconfig400 B
docs/templates/hooks/run-hook.cmdscript1.2 KB
docs/templates/hooks/session-start.ps1script3.6 KB
docs/templates/hooks/session-start.shscript3.5 KB
references/agents-block.mdmarkdown7.4 KB
references/artifact-template.mdmarkdown70.7 KB
references/benchmark-addon/recursive-benchmark/BENCHMARK-ADDON.mdmarkdown6.7 KB
references/benchmark-addon/recursive-benchmark/recursive-benchmark/BENCHMARK-ADDON.mdmarkdown6.7 KB
references/benchmark-addon/recursive-benchmark/recursive-benchmark/references/patterns.mdmarkdown4.9 KB
references/benchmark-addon/recursive-benchmark/references/patterns.mdmarkdown4.9 KB
references/benchmarks/README.mdmarkdown1.5 KB
references/benchmarks/local-first-planner/00-requirements.mdmarkdown3.3 KB
references/benchmarks/local-first-planner/README.mdmarkdown1.1 KB
references/benchmarks/local-first-planner/prompt-recursive-off.mdmarkdown1.1 KB
references/benchmarks/local-first-planner/prompt-recursive-on.mdmarkdown14.8 KB
references/benchmarks/local-first-planner/scoring-rubric.mdmarkdown1.3 KB
references/benchmarks/local-first-planner/starter/.gitignoreother30 B
references/benchmarks/local-first-planner/starter/README.mdmarkdown264 B
references/benchmarks/local-first-planner/starter/index.htmlother316 B
references/benchmarks/local-first-planner/starter/package.jsonmanifest628 B
references/benchmarks/local-first-planner/starter/src/App.test.tsxother334 B
references/benchmarks/local-first-planner/starter/src/App.tsxother971 B
references/benchmarks/local-first-planner/starter/src/main.tsxother238 B
references/benchmarks/local-first-planner/starter/src/styles.cssother976 B
references/benchmarks/local-first-planner/starter/src/test-setup.tsscript43 B
references/benchmarks/local-first-planner/starter/src/vite-env.d.tsscript38 B
references/benchmarks/local-first-planner/starter/tsconfig.app.jsonconfig552 B
references/benchmarks/local-first-planner/starter/tsconfig.jsonconfig89 B
references/benchmarks/local-first-planner/starter/vite.config.tsscript214 B
references/benchmarks/release-readiness-dashboard/00-requirements.mdmarkdown5.9 KB
references/benchmarks/release-readiness-dashboard/README.mdmarkdown1.2 KB
references/benchmarks/release-readiness-dashboard/prompt-recursive-off.mdmarkdown1.1 KB
references/benchmarks/release-readiness-dashboard/prompt-recursive-on.mdmarkdown14.8 KB
references/benchmarks/release-readiness-dashboard/scoring-rubric.mdmarkdown1.8 KB
references/benchmarks/release-readiness-dashboard/starter/.gitignoreother30 B
references/benchmarks/release-readiness-dashboard/starter/README.mdmarkdown272 B
references/benchmarks/release-readiness-dashboard/starter/index.htmlother324 B
references/benchmarks/release-readiness-dashboard/starter/package.jsonmanifest628 B
references/benchmarks/release-readiness-dashboard/starter/src/App.test.tsxother342 B
references/benchmarks/release-readiness-dashboard/starter/src/App.tsxother979 B
references/benchmarks/release-readiness-dashboard/starter/src/main.tsxother238 B
references/benchmarks/release-readiness-dashboard/starter/src/styles.cssother976 B
references/benchmarks/release-readiness-dashboard/starter/src/test-setup.tsscript43 B
references/benchmarks/release-readiness-dashboard/starter/src/vite-env.d.tsscript38 B
references/benchmarks/release-readiness-dashboard/starter/tsconfig.app.jsonconfig552 B
references/benchmarks/release-readiness-dashboard/starter/tsconfig.jsonconfig89 B
references/benchmarks/release-readiness-dashboard/starter/vite.config.tsscript214 B
references/benchmarks/scientific-calculator-rust/00-requirements.mdmarkdown4.1 KB
references/benchmarks/scientific-calculator-rust/README.mdmarkdown1.4 KB
references/benchmarks/scientific-calculator-rust/prompt-recursive-off.mdmarkdown1.1 KB
references/benchmarks/scientific-calculator-rust/prompt-recursive-on.mdmarkdown16.6 KB
references/benchmarks/scientific-calculator-rust/scoring-rubric.mdmarkdown1.5 KB
references/benchmarks/scientific-calculator-rust/starter/.gitignoreother14 B
references/benchmarks/scientific-calculator-rust/starter/Cargo.lockmanifest25.7 KB
references/benchmarks/scientific-calculator-rust/starter/Cargo.tomlmanifest226 B
references/benchmarks/team-capacity-board/00-requirements.mdmarkdown3.6 KB
references/benchmarks/team-capacity-board/README.mdmarkdown1.0 KB
references/benchmarks/team-capacity-board/prompt-recursive-off.mdmarkdown1.1 KB
references/benchmarks/team-capacity-board/prompt-recursive-on.mdmarkdown14.8 KB
references/benchmarks/team-capacity-board/scoring-rubric.mdmarkdown1.4 KB
references/benchmarks/team-capacity-board/starter/.gitignoreother30 B
references/benchmarks/team-capacity-board/starter/README.mdmarkdown264 B
references/benchmarks/team-capacity-board/starter/index.htmlother316 B
references/benchmarks/team-capacity-board/starter/package.jsonmanifest628 B
references/benchmarks/team-capacity-board/starter/src/App.test.tsxother334 B
references/benchmarks/team-capacity-board/starter/src/App.tsxother971 B
references/benchmarks/team-capacity-board/starter/src/main.tsxother238 B
references/benchmarks/team-capacity-board/starter/src/styles.cssother976 B
references/benchmarks/team-capacity-board/starter/src/test-setup.tsscript43 B
references/benchmarks/team-capacity-board/starter/src/vite-env.d.tsscript38 B
references/benchmarks/team-capacity-board/starter/tsconfig.app.jsonconfig552 B
references/benchmarks/team-capacity-board/starter/tsconfig.jsonconfig89 B
references/benchmarks/team-capacity-board/starter/vite.config.tsscript214 B
references/bootstrap/RECURSIVE.mdmarkdown109.9 KB
references/fixtures/tiny-tasks-smoke-recipe.mdmarkdown2.6 KB
references/local-first-web-app-checklist.mdmarkdown1.6 KB
references/plans-canonical.mdmarkdown10.8 KB
scripts/check-reusable-repo-hygiene.ps1script625 B
scripts/check-reusable-repo-hygiene.pyscript6.3 KB
scripts/install-recursive-mode.ps1script36.0 KB
scripts/install-recursive-mode.pyscript31.8 KB
scripts/install-recursive-mode.shscript363 B
scripts/lint-recursive-run.ps1script739 B
scripts/lint-recursive-run.pyscript127.4 KB
scripts/recursive-closeout.ps1script1015 B
scripts/recursive-closeout.pyscript24.0 KB
scripts/recursive-init.ps1script18.7 KB
scripts/recursive-init.pyscript12.6 KB
scripts/recursive-lock.ps1script677 B
scripts/recursive-lock.pyscript12.6 KB
scripts/recursive-review-bundle.ps1script2.9 KB
scripts/recursive-review-bundle.pyscript22.1 KB
scripts/recursive-router-cli-configure.ps1script86 B
scripts/recursive-router-cli-configure.pyscript230 B
scripts/recursive-router-cli-init.ps1script81 B
scripts/recursive-router-cli-init.pyscript225 B
scripts/recursive-router-cli-invoke.ps1script83 B
scripts/recursive-router-cli-invoke.pyscript227 B
scripts/recursive-router-cli-probe.ps1script82 B
scripts/recursive-router-cli-probe.pyscript226 B
scripts/recursive-router-cli-resolve.ps1script84 B
scripts/recursive-router-cli-resolve.pyscript228 B
scripts/recursive-router-cli-validate.ps1script85 B
scripts/recursive-router-cli-validate.pyscript229 B
scripts/recursive-router-configure.ps1script798 B
scripts/recursive-router-configure.pyscript2.8 KB
scripts/recursive-router-init.ps1script490 B
scripts/recursive-router-init.pyscript925 B
scripts/recursive-router-invoke.ps1script1.5 KB
scripts/recursive-router-invoke.pyscript4.4 KB
scripts/recursive-router-probe.ps1script735 B
scripts/recursive-router-probe.pyscript1.6 KB
scripts/recursive-router-resolve.ps1script803 B
scripts/recursive-router-resolve.pyscript1.6 KB
scripts/recursive-router-validate.ps1script494 B
scripts/recursive-router-validate.pyscript804 B
scripts/recursive-status.ps1script674 B
scripts/recursive-status.pyscript97.7 KB
scripts/recursive-subagent-action.ps1script5.8 KB
scripts/recursive-subagent-action.pyscript12.4 KB
scripts/recursive-training-extract.ps1script586 B
scripts/recursive-training-extract.pyscript1.0 KB
scripts/recursive-training-grpo.ps1script1.2 KB
scripts/recursive-training-grpo.pyscript47.2 KB
scripts/recursive-training-loader.ps1script2.3 KB
scripts/recursive-training-loader.pyscript20.1 KB
scripts/recursive-training-mcp.ps1script721 B
scripts/recursive-training-mcp.pyscript10.1 KB
scripts/recursive-training-phase8-trigger.ps1script1.4 KB
scripts/recursive-training-phase8-trigger.pyscript4.0 KB
scripts/recursive-training-sync.ps1script735 B
scripts/recursive-training-sync.pyscript6.9 KB
scripts/recursive_phase_rules.pyscript12.7 KB
scripts/recursive_router_cli_lib.pyscript77 B
scripts/recursive_router_lib.pyscript84.5 KB
scripts/run-recursive-benchmark.ps1script2.1 KB
scripts/run-recursive-benchmark.pyscript376.1 KB
scripts/test-recursive-mode-smoke.ps1script1.0 KB
scripts/test-recursive-mode-smoke.pyscript121.0 KB
scripts/test_install_recursive_mode.pyscript38.4 KB
scripts/test_lint_recursive_run.pyscript4.1 KB
scripts/test_recursive_phase_rules.pyscript21.4 KB
scripts/test_recursive_review_bundle.pyscript5.8 KB
scripts/test_recursive_router.pyscript53.3 KB
scripts/test_recursive_subagent_action.pyscript3.2 KB
scripts/test_recursive_training.pyscript12.0 KB
scripts/test_run_recursive_benchmark.pyscript160.0 KB
scripts/verify-locks.ps1script733 B
scripts/verify-locks.pyscript13.8 KB

references/artifact-template.md

View on GitHub
# recursive-mode Artifact Writing Guide and Templates

Use this file when writing any per-run artifact in:
- `/.recursive/run/<run-id>/00-worktree.md`
- `/.recursive/run/<run-id>/00-requirements.md`
- `/.recursive/run/<run-id>/01-as-is.md`
- `/.recursive/run/<run-id>/01.5-root-cause.md`
- `/.recursive/run/<run-id>/02-to-be-plan.md`
- `/.recursive/run/<run-id>/03-implementation-summary.md`
- `/.recursive/run/<run-id>/03.5-code-review.md`
- `/.recursive/run/<run-id>/04-test-summary.md`
- `/.recursive/run/<run-id>/05-manual-qa.md`
- `/.recursive/run/<run-id>/06-decisions-update.md`
- `/.recursive/run/<run-id>/07-state-update.md`
- `/.recursive/run/<run-id>/08-memory-impact.md`
- `/.recursive/run/<run-id>/addenda/*.md`

This guide is intentionally prescriptive so two different agents produce equivalent artifacts.

## Table of Contents

- [Quick Start Checklist](#quick-start-checklist)
- [Required Header (All Artifacts)](#required-header-all-artifacts)
- [Universal Sections (All Artifacts Except `00-requirements.md`)](#universal-sections-all-artifacts-except-00-requirementsmd)
- [Memory Metadata Block (Durable Memory Docs)](#memory-metadata-block-durable-memory-docs)
- [Evidence Directory (Per Run)](#evidence-directory-per-run)
- [Review Bundle Template](#review-bundle-template)
- [Subagent Action Record Template](#subagent-action-record-template)
- [Phase-by-Phase Authoring Templates](#phase-by-phase-authoring-templates)
- [Phase 0 Template (`00-worktree.md`) - Isolation REQUIRED](#phase-0-template-00-worktreemd---isolation-required)
- [Phase 0 Requirements Template (`00-requirements.md`)](#phase-0-requirements-template-00-requirementsmd)
- [Phase 1 Template (`01-as-is.md`)](#phase-1-template-01-as-ismd)
- [Phase 1.5 Template (`01.5-root-cause.md`) - Debug Mode Only](#phase-15-template-015-root-causemd---debug-mode-only)
- [Phase 2 Template (`02-to-be-plan.md`, ExecPlan Grade)](#phase-2-template-02-to-be-planmd-execplan-grade)
- [Phase 3 Template (`03-implementation-summary.md`)](#phase-3-template-03-implementation-summarymd)
- [Phase 3.5 Template (`03.5-code-review.md`) - Optional](#phase-35-template-035-code-reviewmd---optional)
- [Phase 4 Template (`04-test-summary.md`)](#phase-4-template-04-test-summarymd)
- [Phase 5 Template (`05-manual-qa.md`)](#phase-5-template-05-manual-qamd)
- [Phase 6 Template (`06-decisions-update.md`)](#phase-6-template-06-decisions-updatemd)
- [Phase 7 Template (`07-state-update.md`)](#phase-7-template-07-state-updatemd)
- [Phase 8 Template (`08-memory-impact.md`)](#phase-8-template-08-memory-impactmd)
- [Addenda Templates](#addenda-templates)
- [Stage-Local Addendum](#stage-local-addendum)
- [Upstream-Gap Addendum](#upstream-gap-addendum)
- [Artifact Linting (Structure + TODO Discipline)](#artifact-linting-structure--todo-discipline)
- [Locking Commands](#locking-commands)
- [Common Failure Modes (Use as Pre-Lock Checklist)](#common-failure-modes-use-as-pre-lock-checklist)
- [Lock Verification](#lock-verification)

## Quick Start Checklist

1. Resolve the run id and exact output path.
2. **Ensure `00-requirements.md` exists, then create/lock Phase 0 worktree (`00-worktree.md`) before Phase 1+ (isolated workspace setup).**
3. **If writing Phase 3 or later, verify all prior phase artifacts are lock-valid before proceeding.**
4. Verify phase isolation: only the current phase may be `DRAFT`; do not proceed if a prior phase is unresolved.
5. Determine effective inputs:
   - base input files for this phase
   - plus stage-local addenda for each base input, lexical order
   - plus current-phase upstream-gap addenda when they compensate for locked-history gaps you must account for now
6. Write the required header with exact input/output paths.
7. Write phase-specific content sections from this guide.
8. For audited phases, write the audit sections and complete the `draft -> audit -> repair -> re-audit` loop.
9. Write `Traceability`, `Coverage Gate`, and `Approval Gate`.
10. Perform a pre-lock completeness check using this template's required sections and gates.
11. Verify LockHash matches SHA-256 of content before locking.
12. Lock only after all required gates pass (`Status`, `LockedAt`, `LockHash`).

## Required Header (All Artifacts)

```md
Run: `/.recursive/run/<run-id>/`
Phase: `0N <phase-name>`
Status: `DRAFT`
Inputs:
- `/<path-to-input-1>`
- `/<path-to-input-2>`
Outputs:
- `/<path-to-this-output>`
Scope note: One short paragraph describing what this artifact decides or enables.
```

When locking, append:

```md
LockedAt: `YYYY-MM-DDTHH:MM:SSZ`
LockHash: `<sha256-hex>`
```

## Universal Sections (All Artifacts Except `00-requirements.md`)

Traceability is not required in `00-requirements.md`, but every downstream artifact (Phase 1+) must include it.

```md
## Traceability

- `R1` -> [where this artifact addresses it] | Evidence: [files, commands, observations]
- `R2` -> [where this artifact addresses it] | Evidence: [files, commands, observations]
- `R3` -> Deferred in this phase | Rationale: [...] | Impact: [...]
```

```md
## Coverage Gate

- Effective inputs reviewed:
  - `/<base-input-1>`
  - `/<matching-addendum-1>`
  - `/<matching-addendum-2>`
- Requirement coverage check:
  - `R1`: Covered at [section]
  - `R2`: Covered at [section]
  - `R3`: Deferred [why]
- Out-of-scope confirmation:
  - `OOS1`: unchanged
  - `OOS2`: unchanged

Coverage: PASS
```

```md
## Approval Gate

- Objective readiness checks:
  - [artifact is internally consistent]
  - [commands are runnable and specific]
  - [tests/QA expectations are explicit for this phase]
  - [no required section is missing]
- Remaining blockers:
  - none

Approval: PASS
```

If either gate fails, set `FAIL` and list exact fixes required before proceeding.

## Universal Audit Sections (Audited Phases)

Use this block in every audited phase for `recursive-mode-audit-v1` and `recursive-mode-audit-v2`:

```md
## Audit Context

Audit Execution Mode: self-audit / subagent
Subagent Availability: available / unavailable
Subagent Capability Probe: [what proved availability or unavailability]
Delegation Decision Basis: [why self-audit or delegation was chosen]
Delegation Override Reason: [required when subagents were available but self-audit was still chosen]
Audit Inputs Provided:
- `/.recursive/run/<run-id>/00-requirements.md`
- `/.recursive/run/<run-id>/00-worktree.md`
- [other upstream artifacts]
- Changed files:
  - `path/to/file`
- Targeted code references:
  - `path/to/file`

## Effective Inputs Re-read

- `/.recursive/run/<run-id>/...`

## Earlier Phase Reconciliation

- Upstream artifact:
  - Claim carried forward:
  - Current reconciliation:

## Subagent Contribution Verification

- Reviewed Action Records: `none` / `/.recursive/run/<run-id>/subagents/<record>.md`
- Main-Agent Verification Performed: `path/to/file`, `/.recursive/run/<run-id>/artifact.md`, diff-owned paths actually checked by the controller
- Acceptance Decision: `accepted|partially accepted|rejected`
- Refresh Handling: [whether the bundle/action record was refreshed after repairs or why no refresh was needed]
- Repair Performed After Verification: `none` / [concrete repair paths or artifact updates performed after checking delegated work]

Controller verification rule:

- `Main-Agent Verification Performed` should cite real files or recursive artifacts that exist, not placeholder prose
- if `Repair Performed After Verification` cites paths, those paths should also exist
- if `Subagent Availability` is `available` and `Audit Execution Mode` is `self-audit`, `Delegation Override Reason` should state the concrete reason the controller chose not to delegate
- these fields may be written inline or as multi-line bullet lists; lint/status should accept either form as long as the cited paths and decisions are concrete

## Worktree Diff Audit

- Baseline type: `local commit|local branch|remote ref|merge-base derived`
- Baseline reference: `origin/main` / `main` / `<commit>`
- Comparison reference: `working-tree` / `HEAD` / `<branch-or-ref>`
- Normalized baseline: `<commit-sha>`
- Normalized comparison: `working-tree` / `<commit-sha>`
- Normalized diff command: `git diff --name-only <normalized-basis>`
- Planned or claimed changed files:
  - `path/to/file`
- Actual changed files reviewed:
  - `path/to/file`
- Unexplained drift:
  - none / [explain]

Incidental runtime noise such as `__pycache__/`, `*.pyc`, `.pytest_cache/`, `.mypy_cache/`, and `.ruff_cache/` is excluded from meaningful diff audit unless the repo intentionally tracks it.

For Phase 0 specifically, `recursive-init` should prefill a safe executable default from the current `HEAD` commit when possible. If you later choose a different baseline, update `Baseline reference`, `Normalized baseline`, `Comparison reference`, `Normalized comparison`, and `Normalized diff command` together and rerun lint before locking.

## Phase-Scoped Diff Ownership

Treat `## Worktree Diff Audit` as phase-scoped, not as a permanent obligation for every earlier artifact to explain the eventual end-state diff forever.

- Phase 2 owns planning completeness plus the expected product/worktree change surface.
- Phase 3, Phase 3.5, and Phase 4 own the actual product/worktree diff.
- Phase 6 owns `/.recursive/DECISIONS.md` plus the reviewed final product/worktree paths.
- Phase 7 owns `/.recursive/STATE.md` plus the reviewed final product/worktree paths.
- Phase 8 owns `/.recursive/memory/**` plus the reviewed final product/worktree paths.
- Late control-plane or memory churn must not retroactively invalidate an earlier locked planning artifact.
- If a later phase discovers a real upstream gap, create a current-phase upstream-gap addendum and compensate there instead of editing locked history.

## Gaps Found

- none / [list in-scope gaps, missing evidence, or drift]

## Repair Work Performed

- none / [list repairs made before re-audit]

## Requirement Completion Status

- `R1 | Status: implemented | Changed Files: /path/to/file | Implementation Evidence: /path/to/file, /path/to/artifact`
- `R2 | Status: verified | Changed Files: /path/to/file | Implementation Evidence: /path/to/file | Verification Evidence: /path/to/test-summary.md`
- `R3 | Status: deferred | Rationale: [why] | Deferred By: /.recursive/run/<run-id>/addenda/...`
- `R4 | Status: out-of-scope | Rationale: [why] | Scope Decision: /.recursive/run/<run-id>/addenda/...`
- `R5 | Status: blocked | Rationale: [why] | Blocking Evidence: /path/to/log, /path/to/artifact`
- `R6 | Status: superseded by approved addendum | Addendum: /.recursive/run/<run-id>/addenda/...`

Use status-specific evidence fields rather than a generic `Evidence:` field:

- `implemented` -> `Changed Files` and `Implementation Evidence`
- `verified` -> `Changed Files`, `Implementation Evidence`, and `Verification Evidence`
- `deferred` -> `Deferred By` or `Addendum`
- `out-of-scope` -> `Scope Decision` or `Addendum`
- `blocked` -> `Blocking Evidence`

Contradiction rule:

- do not mix fields from conflicting statuses in one `R#` entry
- do not mark a requirement `implemented` or `verified` without concrete changed-file refs
- do not mark a requirement `verified` without verification evidence that is stronger than merely restating implementation evidence
- in phases that own product/worktree diff, every diff-owned changed file should appear under some in-scope requirement's `Changed Files`

## Audit Verdict

- Audit summary:
- Follow-up required before lock:
- Audit: FAIL
```

Additional audited-phase requirement:

- Phase 1, Phase 2, Phase 4, Phase 7, and Phase 8 must also include `## Prior Recursive Evidence Reviewed`.
- Do not set `Coverage: PASS` or `Approval: PASS` unless `Audit: PASS`.
- Phase 8 must also include `## Run-Local Skill Usage Capture` and `## Skill Memory Promotion Review`.

## Memory Metadata Block (Durable Memory Docs)

Every durable memory doc under `/.recursive/memory/` except `MEMORY.md` must include this metadata block near the top.

```md
Type: `domain|pattern|incident|episode`
Status: `CURRENT|SUSPECT|STALE|DEPRECATED|DRAFT`
Scope: `<what this memory doc covers>`
Owns-Paths:
- `path/or/glob/**`
Watch-Paths:
- `path/or/glob/**`
Source-Runs:
- `/.recursive/run/<run-id>/`
Validated-At-Commit: `<git-sha>`
Last-Validated: `YYYY-MM-DDTHH:MM:SSZ`
Tags:
- `tag-one`
- `tag-two`
Parent: `<optional parent memory doc path>`
Children:
- `<optional child memory doc path>`
Supersedes:
- `<optional older memory doc path>`
Superseded-By:
- `<optional newer memory doc path>`
```

Notes:
- `MEMORY.md` is the router/index and does not require the metadata block.
- `SKILLS.md` is the skill-memory router/index and does not require the metadata block.
- `Owns-Paths` may be empty for non-domain docs, but the field must exist.
- `Watch-Paths` may be empty, but the field must exist.
- Phase 8 should downgrade affected `CURRENT` docs to `SUSPECT` until semantic revalidation is complete.

## Evidence Directory (Per Run)

To keep Phase 4/5 fast and reproducible, store all non-Markdown evidence artifacts under a standard folder:

- `/.recursive/run/<run-id>/evidence/`
  - `screenshots/` (UI screenshots, failure screenshots)
  - `logs/` (console/server/CI excerpts)
  - `perf/` (profiles, measurements, benchmarks)
  - `traces/` (Playwright traces, HARs; if applicable)
  - `review-bundles/` (canonical delegated review handoff files)
  - `other/` (fallback)

Per-run delegated work records live under:

- `/.recursive/run/<run-id>/subagents/`

Reference these artifacts in Phase 3/4/5 using repo-relative paths.

## Review Bundle Template

Use this when delegating a Phase 3.5 review or any other review/audit that needs a reproducible context handoff. Prefer generating it with `recursive-review-bundle`.
The helper auto-discovers relevant addenda by default; do not trim them out unless you are deliberately debugging bundle generation.

```md
Run: `/.recursive/run/<run-id>/`
Bundle Type: `review-bundle`
Phase: `03.5 Code Review`
Role: `code-reviewer`
Artifact path: `/.recursive/run/<run-id>/03.5-code-review.md`
Artifact Content Hash: `<sha256>`

## Routing

- Routed CLI: `none`
- Routed Model: `none`
- Routing Config Path: `none`
- Routing Discovery Path: `none`

## Upstream Artifacts

- `/.recursive/run/<run-id>/00-requirements.md`
- `/.recursive/run/<run-id>/00-worktree.md`
- `/.recursive/run/<run-id>/02-to-be-plan.md`
- `/.recursive/run/<run-id>/03-implementation-summary.md`

## Addenda

- none / `/.recursive/run/<run-id>/addenda/...`

## Prior Recursive Evidence

- none / `/.recursive/run/<run-id>/...`
- none / `/.recursive/memory/...`

## Control-Plane Docs

- none / `/.recursive/DECISIONS.md`
- none / `/.recursive/STATE.md`

## Diff Basis

- Baseline type:
- Baseline reference:
- Comparison reference:
- Normalized baseline:
- Normalized comparison:
- Normalized diff command:

## Changed Files

- `path/to/file`

## Targeted Code References

- `path/to/file`

## Evidence References

- `/.recursive/run/<run-id>/evidence/logs/...`

## Audit Questions

- Which `R#` remain incomplete or weakly evidenced?
- Which changed files drift from the plan or implementation claims?
- Is TDD and test evidence sufficient for this phase?
- What must be repaired before lock?

## Required Output

- Findings ordered by severity
- Missing evidence or traceability gaps
- Concrete repair recommendations
- Final verdict suitable for `Audit: PASS` or `Audit: FAIL`
```

Review-artifact expectation:

- The written review narrative should cite the `Review Bundle Path`, at least one upstream artifact from the bundle, relevant addenda when present, and changed files or code refs from the bundle.
- Relevant addenda should appear in the bundle automatically unless auto-discovery is intentionally disabled for debugging.
- `## Changed Files Reviewed` and `## Targeted Code References` should be concrete, non-empty, and grounded in the changed-file scope being reviewed.
- Main-agent acceptance should record how delegated claims were checked against actual files, actual recursive artifacts, actual diff scope, and any repairs performed after verification.

## Subagent Action Record Template

Use this when a meaningful subagent invocation contributes to a phase outcome. The record is a durable claim log that the main agent must verify before accepting the work.

```md
# Subagent Action Record

## Metadata
- Subagent ID:
- Run ID:
- Phase:
- Purpose:
- Execution Mode:
- Timestamp:
- Action Record Path:

## Inputs Provided
- Current Artifact:
- Artifact Content Hash:
- Upstream Artifacts:
- Addenda:
- Review Bundle:
- Diff Basis:
- Code Refs:
- Memory Refs:
- Audit / Task Questions:

## Routing
- Router Used:
- Routed Role:
- Routed CLI:
- Routed Model:
- Routing Config Path:
- Routing Discovery Path:
- Routing Resolution Basis:
- Routing Fallback Reason:
- CLI Probe Summary:
- Prompt Bundle Path:
- Invocation Exit Code:
- Output Capture Paths:

## Claimed Actions Taken
- [bullet list]

## Claimed File Impact
### Created
- path
### Modified
- path
### Reviewed
- path
### Relevant but Untouched
- path

## Claimed Artifact Impact
### Read
- artifact path
### Updated
- artifact path
### Evidence Used
- evidence path

## Claimed Findings
- [bullet list]

## Verification Handoff
- Inspect these files first:
- Reconcile these diffs:
- Cross-check these artifacts:
- Known uncertainties:
```

Meaningfulness rule:

- For materially contributing delegated work, `## Claimed Actions Taken` cannot be `none`.
- `## Claimed File Impact` should cite concrete created, modified, reviewed, or relevant untouched files.
- `## Claimed Artifact Impact` should cite recursive artifacts or evidence paths actually used.
- `Artifact Content Hash` should match the current artifact content at the time the controller accepts the record.
- For delegated review or audit, prefer a stable reviewed artifact for `Current Artifact` instead of a mutable controller-authored phase receipt draft. If that artifact changes materially, refresh the action record.
- The controller should verify the record against actual changed files, actual recursive artifacts, the review bundle when present, and earlier locked recursive docs before acceptance.

## Phase-by-Phase Authoring Templates

For Phases 4-8, prefer starting from `recursive-closeout` rather than hand-authoring a blank markdown file. The helper scaffolds the required headings, audited sections, and late-phase input/output lists before you fill in the final receipt content.

## Phase 0 Template (`00-worktree.md`) - Isolation REQUIRED

Required outcome:
- Isolated git worktree created on feature branch
- Worktree directory verified as git-ignored
- Project setup completed
- Clean test baseline verified
- Main branch protection confirmed

```md
Run: `/.recursive/run/<run-id>/`
Phase: `00 Worktree Setup`
Status: `DRAFT`
Inputs:
- Current git repository state
- User preference (for worktree location)
Outputs:
- `/.recursive/run/<run-id>/00-worktree.md`
- Isolated worktree at `[location]`
Scope note: This document records isolated workspace setup and verifies clean test baseline.

## TODO

- [ ] Verify current branch (main/master protection check)
- [ ] Select worktree location (`.worktrees/<run-id>/` preferred)
- [ ] Verify worktree directory is git-ignored
- [ ] Create git worktree with feature branch
- [ ] Run project setup (npm install, cargo build, etc.)
- [ ] Verify clean test baseline (all tests passing)
- [ ] Document worktree location and branch name
- [ ] Record baseline commit SHA
- [ ] Record reusable diff basis for later audited phases

## Directory Selection

**Convention checked:**
- [ ] `.worktrees/` exists
- [ ] `worktrees/` exists
- [ ] CLAUDE.md preference found
- [ ] User preference obtained

**Selected location:** `.worktrees/` (project-local, hidden)
**Rationale:** [why this location]

## Safety Verification

**Gitignore check:**
```bash
$ git check-ignore -q .worktrees && echo "IGNORED" || echo "NOT IGNORED"
IGNORED
```

**Result:** ? Directory is properly ignored

(If NOT ignored: added to .gitignore and committed before proceeding)

## Worktree Creation

**Current branch before:** `main` (or `master`)

**Command:**
```bash
git worktree add .worktrees/<run-id> -b recursive/<run-id>
```

**Output:**
```
Preparing worktree (new branch 'recursive/<run-id>')
HEAD is now at abc1234 Previous commit message
```

**Branch created:** `recursive/<run-id>`
**Worktree location:** `/full/path/to/project/.worktrees/<run-id>`

## Main Branch Protection

**Original branch:** `main`
**Action:** Created worktree (default behavior)
**Isolation:** ? Working in isolated worktree

(If on main and user insisted: document explicit consent here)

## Project Setup

**Detected project type:** [Node.js/Rust/Python/Go/etc.]

**Commands executed:**
```bash
cd .worktrees/<run-id>
[npm install / cargo build / pip install / etc.]
```

**Output:**
```
[setup output]
```

**Setup status:** ? Complete / ? Issues noted

## Test Baseline Verification

**Command:**
```bash
[npm test / cargo test / pytest / etc.]
```

**Results:**
- Total: [N] tests
- Passed: [N]
- Failed: [N]
- Skipped: [N]

**Baseline:** ? Clean (all tests passing) / ? Pre-existing failures noted

(If failures exist, document and get explicit consent to proceed)

## Worktree Context

**All subsequent phases will execute in:**
- Directory: `.worktrees/<run-id>/`
- Branch: `recursive/<run-id>`
- Base commit: `abc1234`

## Diff Basis For Later Audits

- Baseline type: `local commit|local branch|remote ref|merge-base derived`
- Baseline reference: `main` / `origin/main` / `abc1234`
- Comparison reference: `working-tree` / `HEAD` / `<branch-or-ref>`
- Normalized baseline: `abc1234`
- Normalized comparison: `working-tree` / `def5678`
- Normalized diff command: `git diff --name-only abc1234`
- Base branch: `main`
- Worktree branch: `recursive/<run-id>`
- Diff basis notes: [why this non-default basis was chosen, if applicable]

`recursive-init` should prefill this block from the current `HEAD` commit when possible. The executable source of truth is the combination of `Normalized baseline`, `Normalized comparison`, and `Normalized diff command`; Phase 0 lock must fail if those values do not match live git state.

## Traceability

- recursive-mode process -> Isolated workspace established | Evidence: worktree at `.worktrees/<run-id>`

## Coverage Gate

- [ ] Worktree location selected following priority rules
- [ ] Directory verified as git-ignored (if project-local)
- [ ] Worktree created successfully on feature branch
- [ ] Project setup completed without errors
- [ ] Clean test baseline verified (all tests passing, or failures documented)
- [ ] Main branch protection confirmed (working in isolation, or consent documented)

Coverage: PASS / FAIL

## Approval Gate

- [ ] Isolated workspace ready for development
- [ ] No pending setup issues
- [ ] Ready to proceed to Phase 1/2
- [ ] LockHash matches SHA-256 of content (verified)

Approval: PASS / FAIL

LockedAt: `YYYY-MM-DDTHH:MM:SSZ`
LockHash: `<sha256-hex>`
```

## Phase 0 Requirements Template (`00-requirements.md`)

Required outcome:
- stable requirement IDs (`R1`, `R2`, ...)
- out-of-scope IDs (`OOS1`, `OOS2`, ...)
- observable acceptance criteria per requirement
- constraints/assumptions

```md
Run: `/.recursive/run/<run-id>/`
Phase: `00 Requirements`
Status: `DRAFT`
Workflow version: `recursive-mode-audit-v2`
Inputs:
- [chat summary or source notes if captured in repo]
Outputs:
- `/.recursive/run/<run-id>/00-requirements.md`
Scope note: This document defines stable requirement identifiers and acceptance criteria.

## TODO

- [ ] Elicit requirements from user/context
- [ ] Define requirement identifiers (R1, R2, ...)
- [ ] Write acceptance criteria for each requirement
- [ ] Document out of scope items (OOS1, OOS2, ...)
- [ ] List constraints and assumptions
- [ ] Complete Coverage Gate checklist
- [ ] Complete Approval Gate checklist

## Requirements

### `R1` <short title>
Description:
Acceptance criteria:
- [observable condition 1]
- [observable condition 2]

### `R2` <short title>
Description:
Acceptance criteria:
- [...]

## Out of Scope

- `OOS1`: ...
- `OOS2`: ...

## Constraints

- ...

## Coverage Gate
...
Coverage: PASS

## Approval Gate
...
Approval: PASS
```

## Phase 1 Template (`01-as-is.md`)

Required outcome:
- novice-runnable repro
- current behavior tied to `R#`
- concrete code pointers
- known unknowns

```md
Run: `/.recursive/run/<run-id>/`
Phase: `01 AS-IS`
Status: `DRAFT`
Inputs:
- `/.recursive/run/<run-id>/00-requirements.md`
- `/.recursive/run/<run-id>/addenda/00-requirements.addendum-01.md` [if present]
Outputs:
- `/.recursive/run/<run-id>/01-as-is.md`
Scope note: This document captures current behavior and evidence before changes.

## TODO

- [ ] Read and understand requirements from Phase 1
- [ ] Read and understand requirements from Phase 0
- [ ] Create novice-runnable reproduction steps
- [ ] Document current behavior for each requirement (R1, R2, ...)
- [ ] Identify and record relevant code pointers
- [ ] List known unknowns
- [ ] Gather evidence (logs, screenshots, outputs)
- [ ] Review relevant prior recursive evidence for the affected area
- [ ] Assemble audit context bundle
- [ ] Run phase audit
- [ ] Repair gaps and re-audit until `Audit: PASS`
- [ ] Create traceability mapping
- [ ] Complete Coverage Gate checklist
- [ ] Complete Approval Gate checklist

## Reproduction Steps (Novice-Runnable)

1. ...
2. ...
3. ...

## Current Behavior by Requirement

- `R1`: [what currently happens]
- `R2`: [what currently happens]

## Relevant Code Pointers

- `path/to/file.ext`: [why relevant]
- `path/to/other.ext`: [why relevant]

## Known Unknowns

- ...

## Evidence

- Command output: ...
- Log snippet: ...
- UI observation: ...

## Audit Context

Audit Execution Mode: self-audit / subagent
Subagent Availability: available / unavailable
Audit Inputs Provided:
- `/.recursive/run/<run-id>/00-requirements.md`
- `/.recursive/run/<run-id>/00-worktree.md`
- Changed files:
  - none yet / `path`
- Targeted code references:
  - `path/to/file`

## Effective Inputs Re-read

- `/.recursive/run/<run-id>/00-requirements.md`
- [phase-local addenda]

## Prior Recursive Evidence Reviewed

- Prior run id:
  - Docs read:
  - Reused insight:
  - Superseded or contradicted:

## Earlier Phase Reconciliation

- `00-requirements.md`:
  - Requirement coverage status:
  - Unknowns carried forward:

## Worktree Diff Audit

- Diff basis used: `git diff --name-only <base-commit>..HEAD`
- Base branch:
- Worktree branch:
- Base commit:
- Planned or claimed changed files:
  - none yet / `path`
- Actual changed files reviewed:
  - none yet / `path`
- Unexplained drift:
  - none

## Gaps Found

- none / [list gaps]

## Repair Work Performed

- none / [list repairs]

## Audit Verdict

- Summary:
- Audit: FAIL / PASS

## Traceability
...

## Coverage Gate
...
Coverage: PASS

## Approval Gate
...
Approval: PASS
```

## Phase 1.5 Template (`01.5-root-cause.md`) - Debug Mode Only

Required outcome:
- systematic root cause analysis for bug fixes
- error analysis, reproduction verification, data flow tracing
- documented hypothesis testing
- root cause summary for Phase 2 planning

**Use when:** Requirement involves fixing a bug, test failure, or investigating unexpected behavior.

```md
Run: `/.recursive/run/<run-id>/`
Phase: `01.5 Root Cause Analysis`
Status: `DRAFT`
Inputs:
- `/.recursive/run/<run-id>/01-as-is.md`
- [relevant addenda]
Outputs:
- `/.recursive/run/<run-id>/01.5-root-cause.md`
Scope note: This document records systematic debugging process and identified root cause before any fix is attempted.

## TODO

- [ ] Analyze error messages and stack traces
- [ ] Verify reproduction (confirm bug is reproducible)
- [ ] Review recent changes (git history, dependencies)
- [ ] Gather evidence (logs, data flow, state inspection)
- [ ] Trace data flow to identify source
- [ ] Analyze patterns (working vs broken comparisons)
- [ ] Form and test hypotheses
- [ ] Confirm root cause (not just symptom)
- [ ] Define fix strategy for Phase 2
- [ ] Assemble audit context bundle
- [ ] Run phase audit
- [ ] Repair gaps and re-audit until `Audit: PASS`
- [ ] Complete Coverage Gate checklist
- [ ] Complete Approval Gate checklist

## Error Analysis

**Error Message:** [verbatim]
**Stack Trace:** [key frames]
**File:Line:** [locations]
**Key Insight:** [what the error is telling you]

## Reproduction Verification

**Steps:**
1. [exact step]
2. [exact step]
3. [exact step]

**Reproducible:** Yes / No / Intermittent
**Frequency:** [X out of Y attempts]
**Deterministic:** Yes / No

## Recent Changes Analysis

**Git History:** [relevant commits]
**Dependency Changes:** [if applicable]
**Environment:** [OS, runtime versions]
**Likely Culprit:** [most suspicious change]

## Evidence Gathering (Multi-Layer if applicable)

**Layer 1: [Component]**
- Input: [data]
- Output: [data]
- Status: ? Working / ? Broken

**Failure Boundary:** [where it breaks]

## Data Flow Trace

**Error Location:** [file:line - function]
**Bad Value:** [what was wrong]

**Call Stack (backward):**
1. `functionA()` at fileA:line - received [value]
2. `functionB()` at fileB:line - passed [value]
3. [source] `functionC()` at fileC:line - ORIGIN

## Pattern Analysis

**Working Example:** [file:location]
**Broken Code:** [file:location]

**Key Differences:**
| Aspect | Working | Broken |
|--------|---------|--------|
| [X] | [value] | [value] |

## Hypothesis Testing

### Hypothesis 1
**Statement:** [clear hypothesis]
**Test:** [minimal change]
**Result:** [confirmed/rejected]

### Hypothesis 2 (if needed)
[...]

**Confirmed Root Cause:** [final hypothesis]

## Root Cause Summary

**Root Cause:** [one sentence]
**Location:** [file:line]
**Detailed Explanation:** [paragraph]
**Fix Strategy:** [approach for Phase 2]
**Test Strategy:** [how to verify fix]

## Audit Context

Audit Execution Mode: self-audit / subagent
Subagent Availability: available / unavailable
Audit Inputs Provided:
- `/.recursive/run/<run-id>/01-as-is.md`
- `/.recursive/run/<run-id>/00-worktree.md`
- Changed files:
  - `path/to/file`
- Targeted code references:
  - `path/to/file`

## Effective Inputs Re-read

- `/.recursive/run/<run-id>/01-as-is.md`
- [phase-local addenda]

## Earlier Phase Reconciliation

- `01-as-is.md`:
  - Reproduction status:
  - Evidence carried forward:

## Worktree Diff Audit

- Diff basis used: `git diff --name-only <base-commit>..HEAD`
- Base branch:
- Worktree branch:
- Base commit:
- Planned or claimed changed files:
  - `path/to/file`
- Actual changed files reviewed:
  - `path/to/file`
- Unexplained drift:
  - none

## Gaps Found

- none / [list unresolved gaps]

## Repair Work Performed

- none / [list repairs]

## Audit Verdict

- Summary:
- Audit: FAIL / PASS

## Traceability

- R# (Bug fix requirement) -> Root cause identified at [location] | Evidence: [section]

## Coverage Gate

- [ ] Error messages analyzed
- [ ] Reproduction verified
- [ ] Recent changes reviewed
- [ ] Data flow traced to source
- [ ] Pattern analysis completed
- [ ] Hypothesis tested and confirmed
- [ ] Root cause documented (not just symptom)
- [ ] Fix strategy defined

Coverage: PASS / FAIL

## Approval Gate

- [ ] Root cause identified at source (not just symptom location)
- [ ] Fix approach clear and minimal
- [ ] Test strategy defined
- [ ] No "quick fix" attempts made
- [ ] Ready to proceed to Phase 2 with fix plan

Approval: PASS / FAIL
```

## Phase 2 Template (`02-to-be-plan.md`, ExecPlan Grade)

Required outcome:
- concrete edits by file and location
- exact commands
- tests to add/run
- manual QA scenarios
- recovery/idempotence
- traceability mapping `R# -> planned change + validation`
- sub-phases (`SP1`, `SP2`, ...) when scope/risk is large

```md
Run: `/.recursive/run/<run-id>/`
Phase: `02 TO-BE plan`
Status: `DRAFT`
Inputs:
- `/.recursive/run/<run-id>/01-as-is.md`
- `/.recursive/run/<run-id>/00-requirements.md`
- `/.recursive/run/<run-id>/addenda/01-as-is.addendum-01.md` [if present]
Outputs:
- `/.recursive/run/<run-id>/02-to-be-plan.md`
Scope note: This document defines the implementation and validation plan.

## TODO

- [ ] Read Phase 1 (AS-IS) and Phase 0 (Requirements) artifacts
- [ ] If Phase 1.5 exists: incorporate root cause findings
- [ ] Define sub-phases (SP1, SP2, ...) if scope/risk is large
- [ ] Specify concrete file changes (what, where, how)
- [ ] Define implementation steps in sequence
- [ ] Design testing strategy (new + regression + guardrail)
- [ ] Document Playwright test plan (if applicable)
- [ ] Define manual QA scenarios
- [ ] Review relevant prior recursive evidence for the affected area
- [ ] Assemble audit context bundle
- [ ] Run phase audit
- [ ] Repair gaps and re-audit until `Audit: PASS`
- [ ] Create traceability mapping (R# -> changes -> validation)
- [ ] Complete Coverage Gate checklist
- [ ] Complete Approval Gate checklist

## Planned Changes by File

- `path/to/file.ext`: [exact change]
- `path/to/file2.ext`: [exact change]

## Implementation Steps

1. ...
2. ...
3. ...

## Testing Strategy

- New behavior tests: ...
- Regression tests: ...
- Guardrail tests: ...
- Commands:
  - `...`
  - `...`

## Playwright Plan (if applicable)

- Tags: `@recursive:<run-id>`, `@sp1`, `@smoke`
- Tier A command(s): `...`
- Tier B command(s): `...`
- Evidence outputs: `playwright-report/`, `test-results/`

## Manual QA Scenarios

1. Scenario:
   - Steps:
   - Expected:

2. Scenario:
   - Steps:
   - Expected:

## Idempotence and Recovery

- Re-run safety notes:
- Rollback notes:

## Implementation Sub-phases

### `SP1` <name>
Scope and requirement mapping:
- Covers: `R1`, `R3`

Implementation checklist:
- [ ] edit `path/to/file.ext` ...
- [ ] add test `path/to/test.spec.ts` ...

Tests for this sub-phase:
- `...`
- Pass criteria: ...

Sub-phase acceptance:
- ...

### `SP2` <name>
[same structure]

## Audit Context

Audit Execution Mode: self-audit / subagent
Subagent Availability: available / unavailable
Audit Inputs Provided:
- `/.recursive/run/<run-id>/00-requirements.md`
- `/.recursive/run/<run-id>/00-worktree.md`
- `/.recursive/run/<run-id>/01-as-is.md`
- [relevant addenda]
- Changed files:
  - anticipated `path/to/file`
- Targeted code references:
  - `path/to/file`

## Effective Inputs Re-read

- `/.recursive/run/<run-id>/00-requirements.md`
- `/.recursive/run/<run-id>/01-as-is.md`
- [phase-local addenda]

## Prior Recursive Evidence Reviewed

- Prior run id:
  - Docs read:
  - Reused insight:
  - Superseded or contradicted:

## Earlier Phase Reconciliation

- `00-requirements.md`:
  - each in-scope `R#` planned:
- `01-as-is.md`:
  - current behavior reconciled:
- `01.5-root-cause.md`:
  - fix strategy incorporated:

## Worktree Diff Audit

- Diff basis used: `git diff --name-only <base-commit>..HEAD`
- Base branch:
- Worktree branch:
- Base commit:
- Planned or claimed changed files:
  - `path/to/file`
- Actual changed files reviewed:
  - none yet / `path/to/file`
- Unexplained drift:
  - none

Note: incidental runtime byproducts such as `__pycache__/`, `*.pyc`, `.pytest_cache/`, `.mypy_cache/`, and `.ruff_cache/` are excluded from meaningful diff audit unless the repository intentionally tracks them.

## Gaps Found

- none / [list planning gaps or missing concreteness]

## Repair Work Performed

- none / [list plan repairs made before re-audit]

## Audit Verdict

- Summary:
- Audit: FAIL / PASS

## Traceability
...

## Coverage Gate
...
Coverage: PASS

## Approval Gate
...
Approval: PASS
```

## Phase 3 Template (`03-implementation-summary.md`)

Required outcome:
- what changed, where, why
- implementation evidence
- **TDD compliance log (RED-GREEN-REFACTOR for each requirement)**
- deviations from plan (if any)

```md
Run: `/.recursive/run/<run-id>/`
Phase: `03 Implementation`
Status: `DRAFT`
Inputs:
- `/.recursive/run/<run-id>/02-to-be-plan.md`
- `/.recursive/run/<run-id>/addenda/02-to-be-plan.addendum-01.md` [if present]
Outputs:
- `/.recursive/run/<run-id>/03-implementation-summary.md`
Scope note: This document records completed code changes, TDD compliance, and implementation evidence.

## TODO

- [ ] Read locked Phase 2 (TO-BE) plan
- [ ] Determine execution mode (Parallel vs Sequential)
- [ ] For each sub-phase (SP1, SP2, ...):
  - [ ] Implement per plan (TDD discipline)
  - [ ] Write tests BEFORE code (RED phase)
  - [ ] Make tests pass (GREEN phase)
  - [ ] Refactor while keeping tests green
  - [ ] Self-review / subagent review
  - [ ] Run integration tests
- [ ] Complete TDD Compliance Log for all requirements
- [ ] Document any plan deviations
- [ ] Record implementation evidence (diffs, logs)
- [ ] Assemble audit context bundle
- [ ] Run implementation audit against requirements, plan, and actual diff
- [ ] Repair gaps and re-audit until `Audit: PASS`
- [ ] Complete Coverage Gate checklist
- [ ] Complete Approval Gate checklist

## Changes Applied

- `path/to/file.ext`: [change summary]
- `path/to/file2.ext`: [change summary]

## Sub-phase Implementation Summary

- `SP1`: [what shipped, files touched, notes]
- `SP2`: [what shipped, files touched, notes]

## TDD Compliance Log

**The Iron Law:** NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST.

TDD Mode: strict / pragmatic

RED Evidence:
- `/.recursive/run/<run-id>/evidence/logs/red/<file>.log`

GREEN Evidence:
- `/.recursive/run/<run-id>/evidence/logs/green/<file>.log`

### Requirement R1 ([description])

**Test:** `path/to/test.spec.ts` - "[test name]"

**RED Phase** ([ISO8601 timestamp]):
```bash
[exact command run]
[test failure output - showing it failed correctly]
```
- Expected failure: [what should fail]
- Actual failure: [what actually failed]
- RED verified: ? / ?

**GREEN Phase** ([ISO8601 timestamp]):
- Implementation: [minimal change made]
```bash
[exact command run]
[test pass output]
```
- GREEN verified: ? / ?

**REFACTOR Phase** ([ISO8601 timestamp]):
- Cleanups: [description of improvements]
- All tests still passing: ? / ?

**Final State:** [All tests passing / Issues noted]

### Requirement R2 (Bug Fix - Regression Test)

**Regression Test:** `path/to/regression.test.ts` - "[test name]"

**RED Phase** ([ISO8601 timestamp]):
- Bug reproduced: [evidence]
- RED verified: ? / ?

**GREEN Phase** ([ISO8601 timestamp]):
- Fix applied: [minimal change]
- GREEN verified: ? / ?

**REFACTOR:** [N/A or description]

**Final State:** [Test passes, bug fixed]

### TDD Red Flags Check

- [ ] No code written before failing test
- [ ] All RED phases documented with failure output
- [ ] All GREEN phases documented with minimal implementation
- [ ] No tests passing immediately (would indicate wrong test)
- [ ] No "tests to be added later"

## Pragmatic TDD Exception

Only include this section when `TDD Mode: pragmatic`.

Exception reason:
Compensating validation:
- `/.recursive/run/<run-id>/evidence/<supporting-file>`

## Plan Deviations

- Deviation:
  - Why:
  - Impact:
  - Evidence:

## Implementation Evidence

- Diff pointers:
- Runtime evidence:
- Build/lint results:

## Audit Context

Audit Execution Mode: self-audit / subagent
Subagent Availability: available / unavailable
Audit Inputs Provided:
- `/.recursive/run/<run-id>/00-requirements.md`
- `/.recursive/run/<run-id>/00-worktree.md`
- `/.recursive/run/<run-id>/02-to-be-plan.md`
- [relevant addenda]
- Changed files:
  - `path/to/file`
- Targeted code references:
  - `path/to/file`
- Review inputs:
  - failing tests
  - changed code
  - build/test evidence

## Effective Inputs Re-read

- `/.recursive/run/<run-id>/00-requirements.md`
- `/.recursive/run/<run-id>/02-to-be-plan.md`
- [phase-local addenda]

## Earlier Phase Reconciliation

- `00-requirements.md`:
  - in-scope `R#` implemented:
- `02-to-be-plan.md`:
  - planned steps/sub-phases completed:
  - deviations explained:

## Worktree Diff Audit

- Diff basis used: `git diff --name-only <base-commit>..HEAD`
- Base branch:
- Worktree branch:
- Base commit:
- Planned or claimed changed files:
  - `path/to/file`
- Actual changed files reviewed:
  - `path/to/file`
- Unexplained drift:
  - none / [explain]

## Gaps Found

- none / [list unfinished requirements, drift, or missing evidence]

## Repair Work Performed

- none / [list repairs completed before re-audit]

## Audit Verdict

- Summary:
- Audit: FAIL / PASS

## Traceability
...

## Coverage Gate

- [ ] All requirements (R1..Rn) have implementation
- [ ] All sub-phases completed
- [ ] TDD Compliance Log complete for all requirements
- [ ] No production code without preceding failing test
- [ ] Plan deviations documented (if any)
- [ ] Implementation evidence recorded

TDD Compliance: PASS / FAIL
Coverage: PASS / FAIL

## Approval Gate

- [ ] Implementation matches Phase 2 TO-BE plan (or deviations documented)
- [ ] All tests passing
- [ ] Build/lint clean
- [ ] TDD Iron Law followed (no code before tests)
- [ ] `Audit: PASS` recorded before phase lock

Approval: PASS / FAIL
```

## Phase 3.5 Template (`03.5-code-review.md`) - Optional

Required outcome:
- Independent review of Phase 3 implementation against plan
- Code quality assessment
- Issue classification (Critical/Important/Minor)
- Clear verdict (Approved / Changes Required)

```md
Run: `/.recursive/run/<run-id>/`
Phase: `03.5 Code Review`
Status: `DRAFT`
Inputs:
- `/.recursive/run/<run-id>/02-to-be-plan.md`
- `/.recursive/run/<run-id>/03-implementation-summary.md`
- Git range: BASE_SHA..HEAD_SHA
Outputs:
- `/.recursive/run/<run-id>/03.5-code-review.md`
Scope note: This document records independent review of implementation against plan and coding standards.

## TODO

- [ ] Read Phase 2 plan and Phase 3 implementation summary
- [ ] Review git diff (BASE_SHA..HEAD_SHA)
- [ ] Assess plan alignment for each requirement (R1, R2, ...)
- [ ] Assess plan alignment for each sub-phase (SP1, SP2, ...)
- [ ] Evaluate code quality (architecture, naming, error handling)
- [ ] Evaluate test quality (coverage, edge cases)
- [ ] Verify TDD compliance
- [ ] Categorize issues (Critical/Important/Minor)
- [ ] Document positive findings
- [ ] Record recommendations
- [ ] Render verdict (Approved / Changes Required)
- [ ] Generate or refresh the canonical review bundle
- [ ] Run review audit against requirements, plan, and actual diff
- [ ] Repair issues and re-audit until `Audit: PASS`
- [ ] Complete Coverage Gate checklist
- [ ] Complete Approval Gate checklist

## Review Scope

- Sub-phases reviewed: SP1, SP2, ...
- Git range reviewed: [BASE_SHA]..[HEAD_SHA]

## Plan Alignment Assessment

- **R1**: [description]
  - Plan requirement: [what was planned]
  - Implementation: [what was done]
  - Aligned: OK / WARN / FAIL
  - Notes: [deviations if any]

- **SP1**: [description]
  - Plan specification: [what was specified]
  - Implementation: [what was done]
  - Aligned: OK / WARN / FAIL
  - Notes: [deviations if any]

## Code Quality Assessment

### Architecture & Design
- SOLID principles: OK / WARN / FAIL
- Separation of concerns: OK / WARN / FAIL
- Integration with existing code: OK / WARN / FAIL

### Code Quality
- Naming conventions: OK / WARN / FAIL
- Error handling: OK / WARN / FAIL
- Type safety: OK / WARN / FAIL
- Maintainability: OK / WARN / FAIL

### Test Quality
- Test coverage adequate: OK / WARN / FAIL
- Test quality: OK / WARN / FAIL
- Edge cases covered: OK / WARN / FAIL

### TDD Compliance
- All production code preceded by failing tests: OK / WARN / FAIL
- TDD cycles documented: OK / WARN / FAIL
- Strict mode includes concrete RED and GREEN evidence paths: OK / WARN / FAIL
- Pragmatic mode has explicit exception rationale and compensating evidence: OK / WARN / FAIL
- No evidence of "code first, test later": OK / WARN / FAIL

## Issues Found

### Critical (must fix before proceeding)
1. **[Issue name]**
   - **Location:** `file:line`
   - **Problem:** [description]
   - **Recommendation:** [specific fix]

### Important (should fix)
1. **[Issue name]**
   - **Location:** `file:line`
   - **Problem:** [description]
   - **Recommendation:** [specific fix]

### Minor (suggestions)
1. **[Issue name]**
   - **Suggestion:** [description]

## Positive Findings

- [What was done well]

## Recommendations

- **Immediate:** [what to fix now]
- **Future:** [improvements for later]

## Verdict

- [ ] **APPROVED** - Ready to proceed to Phase 4
- [ ] **APPROVED WITH NOTES** - Minor issues, can proceed
- [ ] **CHANGES REQUIRED** - Fix issues, then re-review

## Review Metadata

- Reviewer: [agent name / self-review]
- Review Execution Mode: subagent / self-audit
- Review Bundle Path: `/.recursive/run/<run-id>/evidence/review-bundles/<bundle>.md`
- Bundle Scope Summary: [what the bundle covered]
- Reviewer Receipt: [review comment id / local note / n/a]
- Review duration: [time spent]
- Files reviewed: [count]
- Lines of code reviewed: [count]

## Audit Context

Audit Execution Mode: self-audit / subagent
Subagent Availability: available / unavailable
Audit Inputs Provided:
- `/.recursive/run/<run-id>/00-requirements.md`
- `/.recursive/run/<run-id>/00-worktree.md`
- `/.recursive/run/<run-id>/02-to-be-plan.md`
- `/.recursive/run/<run-id>/03-implementation-summary.md`
- Changed files:
  - `path/to/file`
- Targeted code references:
  - `path/to/file`

## Effective Inputs Re-read

- `/.recursive/run/<run-id>/00-requirements.md`
- `/.recursive/run/<run-id>/02-to-be-plan.md`
- `/.recursive/run/<run-id>/03-implementation-summary.md`
- [phase-local addenda]

## Earlier Phase Reconciliation

- Requirements vs implementation:
- Plan vs implementation:
- Prior fixes vs remaining issues:

## Worktree Diff Audit

- Diff basis used: `git diff --name-only <base-commit>..HEAD`
- Base branch:
- Worktree branch:
- Base commit:
- Planned or claimed changed files:
  - `path/to/file`
- Actual changed files reviewed:
  - `path/to/file`
- Unexplained drift:
  - none / [explain]

## Gaps Found

- none / [list blocking issues, drift, or missing evidence]

## Repair Work Performed

- none / [list repairs completed before re-audit]

## Audit Verdict

- Summary:
- Audit: FAIL / PASS

## Traceability
...

## Coverage Gate

- [ ] All sub-phases reviewed
- [ ] Plan alignment verified for all requirements
- [ ] Code quality assessed
- [ ] Issues categorized by severity
- [ ] Verdict recorded
- [ ] `Audit: PASS` recorded before phase lock

Coverage: PASS / FAIL

## Approval Gate

- [ ] Review completed objectively
- [ ] Issues clearly documented
- [ ] Verdict justified
- [ ] Ready for Phase 4 (if approved)

Approval: PASS / FAIL
```

## Phase 4 Template (`04-test-summary.md`)

Required outcome:
- pre-test implementation audit against requirements and TO-BE plan
- exact commands executed
- pass/fail outcomes
- evidence artifact locations (standardized under `/.recursive/run/<run-id>/evidence/`)
- flake/retry notes
- parallel test execution summary (if applicable)

```md
Run: `/.recursive/run/<run-id>/`
Phase: `04 Test Summary`
Status: `DRAFT`
Inputs:
- `/.recursive/run/<run-id>/02-to-be-plan.md`
- `/.recursive/run/<run-id>/03-implementation-summary.md`
- `/.recursive/run/<run-id>/03.5-code-review.md` [if present]
- [relevant addenda]
Outputs:
- `/.recursive/run/<run-id>/04-test-summary.md`
Scope note: This document records test execution evidence and readiness.

## TODO

- [ ] Read Phase 2 plan and Phase 3 implementation summary
- [ ] Audit implementation summary against `00-requirements.md` and `02-to-be-plan.md`
- [ ] Determine test execution mode (Parallel vs Sequential)
- [ ] Execute unit tests (document commands and results)
- [ ] Execute integration tests (document commands and results)
- [ ] Execute E2E Tier A tests (document commands and results)
- [ ] Execute Tier B regression tests (if applicable)
- [ ] Document any failures and diagnostics
- [ ] Note any flake/retry occurrences
- [ ] Verify TDD compliance (all Phase 3 tests passing)
- [ ] Review relevant prior recursive evidence for the affected area
- [ ] Assemble audit context bundle
- [ ] Run pre-test audit and post-test audit
- [ ] Repair gaps and re-audit until `Audit: PASS`
- [ ] Complete Coverage Gate checklist
- [ ] Complete Approval Gate checklist

## Pre-Test Implementation Audit

- Requirement alignment (`00-requirements.md`): list each requirement and confirm implemented/not implemented with evidence.
- Plan alignment (`02-to-be-plan.md`): list planned steps/sub-phases and confirm implemented/not implemented with evidence.
- Mismatches found:
  - [ ] None
  - [ ] Yes (document each mismatch and required addendum or fix before proceeding)

## Environment

- OS:
- Runtime versions:
- Test framework versions:
- Base URL / server mode:

## Execution Mode

- **Mode:** Parallel / Sequential
- **Subagent Usage:**
  - Unit tests: [subagent name] / Main agent
  - Integration tests: [subagent name] / Main agent
  - E2E tests: [subagent name] / Main agent
- **Parallel execution time:** [X] minutes (vs [Y] estimated sequential)

## Commands Executed (Exact)

- `...`
- `...`

## Results Summary

- Total:
- Passed:
- Failed:
- Skipped:

## Evidence and Artifacts

Store and reference artifacts under:
- `/.recursive/run/<run-id>/evidence/`
  - `evidence/screenshots/`
  - `evidence/logs/`
  - `evidence/perf/`
  - `evidence/traces/` (if applicable)

## By Sub-phase

- `SP1`:
  - Tier A command(s):
  - Result:
  - Evidence path(s):
- `SP2`:
  - Tier A command(s):
  - Result:
  - Evidence path(s):

## Tier B / Broader Regression

- Command(s):
- Result:
- Evidence path(s):

## Failures and Diagnostics (if any)

- Failing test:
  - Symptom:
  - Suspected cause:
  - Artifact path:
  - Mitigation:

## Flake/Rerun Notes

- Rerun command:
- Outcome:
- Deterministic or flaky:

## Audit Context

Audit Execution Mode: self-audit / subagent
Subagent Availability: available / unavailable
Audit Inputs Provided:
- `/.recursive/run/<run-id>/00-requirements.md`
- `/.recursive/run/<run-id>/00-worktree.md`
- `/.recursive/run/<run-id>/02-to-be-plan.md`
- `/.recursive/run/<run-id>/03-implementation-summary.md`
- `/.recursive/run/<run-id>/03.5-code-review.md` [if present]
- Changed files:
  - `path/to/file`
- Targeted code references:
  - `path/to/file`
- Test file references:
  - `path/to/test`

## Effective Inputs Re-read

- `/.recursive/run/<run-id>/00-requirements.md`
- `/.recursive/run/<run-id>/02-to-be-plan.md`
- `/.recursive/run/<run-id>/03-implementation-summary.md`
- `/.recursive/run/<run-id>/03.5-code-review.md` [if present]
- [phase-local addenda]

## Prior Recursive Evidence Reviewed

- Prior run id:
  - Docs read:
  - Reused insight:
  - Superseded or contradicted:

## Earlier Phase Reconciliation

- Requirements vs implementation:
- Plan vs implementation:
- Review findings vs repairs:

## Worktree Diff Audit

- Diff basis used: `git diff --name-only <base-commit>..HEAD`
- Base branch:
- Worktree branch:
- Base commit:
- Planned or claimed changed files:
  - `path/to/file`
- Actual changed files reviewed:
  - `path/to/file`
- Unexplained drift:
  - none / [explain]

## Gaps Found

- none / [list unfinished work, drift, or missing tests]

## Repair Work Performed

- none / [list repairs completed before re-audit]

## Audit Verdict

- Summary:
- Audit: FAIL / PASS

## Traceability
...

## Coverage Gate
...
Coverage: PASS

## Approval Gate
...
Approval: PASS
```

## Phase 5 Template (`05-manual-qa.md`)

Required outcome:
- plan scenarios executed according to the selected QA mode
- observed outcomes
- explicit `QA Execution Mode`
- required sign-off and/or execution evidence for that mode

Compact table is allowed in this phase.

```md
Run: `/.recursive/run/<run-id>/`
Phase: `05 Manual QA`
Status: `DRAFT`
Inputs:
- `/.recursive/run/<run-id>/02-to-be-plan.md`
- [relevant addenda]
Outputs:
- `/.recursive/run/<run-id>/05-manual-qa.md`
Scope note: This document records QA outcomes, the execution mode used, and the required evidence/sign-off for that mode.
QA Execution Mode: human / agent-operated / hybrid

## TODO

- [ ] Read Phase 2 plan (QA scenarios)
- [ ] Declare QA execution mode
- [ ] Present QA scenarios to the user if human input is required
- [ ] **PAUSE if needed:** Wait for user execution/sign-off when the selected mode requires it
- [ ] Record observed outcomes for each scenario
- [ ] Document pass/fail status
- [ ] Record QA execution metadata and evidence
- [ ] Record user sign-off if the selected mode requires it
- [ ] Complete Coverage Gate checklist
- [ ] Complete Approval Gate checklist

## QA Scenarios and Results

| Scenario | Expected | Observed | Pass/Fail | Notes |
| --- | --- | --- | --- | --- |
| ... | ... | ... | ... | ... |

## Evidence and Artifacts

Store and reference artifacts under:
- `/.recursive/run/<run-id>/evidence/`
  - `evidence/screenshots/` (screenshots, videos-as-files)
  - `evidence/logs/` (console/server output excerpts)
  - `evidence/perf/` (if QA included perf checks)

## QA Execution Record

QA Execution Mode: human / agent-operated / hybrid
- Agent Executor:
- Tools Used:
- Evidence:
  - `/.recursive/run/<run-id>/evidence/<file>`

## User Sign-Off

- Approved by:
- Date:
- Notes:

## Traceability
...

## Coverage Gate

- [ ] QA scenarios from Phase 2 are represented
- [ ] Observed results are recorded for all executed scenarios
- [ ] QA execution mode is declared
- [ ] Required execution metadata/evidence for that mode is present

Coverage: PASS / FAIL

## Approval Gate

- [ ] The selected QA mode's completion requirements are satisfied
- [ ] Human sign-off is present if mode is `human` or `hybrid`
- [ ] Agent execution evidence is present if mode is `agent-operated` or `hybrid`

Approval: PASS / FAIL
```

If the selected QA mode is not yet complete, keep `Approval: FAIL` and list what is pending.

## Phase 6 Template (`06-decisions-update.md`)

Required outcome:
- `/.recursive/DECISIONS.md` updated for the run
- exact ledger delta recorded in a lockable receipt
- rationale for any ledger structure changes documented

```md
Run: `/.recursive/run/<run-id>/`
Phase: `06 Decisions Update`
Status: `DRAFT`
Inputs:
- `/.recursive/run/<run-id>/05-manual-qa.md`
- `/.recursive/DECISIONS.md`
- [relevant addenda]
Outputs:
- `/.recursive/DECISIONS.md`
- `/.recursive/run/<run-id>/06-decisions-update.md`
Scope note: This document records the exact `DECISIONS.md` updates made for the completed run.

## TODO

- [ ] Read locked Phase 5 manual QA artifact
- [ ] Update `/.recursive/DECISIONS.md` with the run outcome
- [ ] Record a concise delta summary of the `DECISIONS.md` edits
- [ ] Document rationale for any structural ledger changes
- [ ] Verify run references and late-phase links are correct
- [ ] Assemble audit context bundle
- [ ] Audit receipt against final run folder and actual repo state
- [ ] Repair gaps and re-audit until `Audit: PASS`
- [ ] Complete Coverage Gate checklist
- [ ] Complete Approval Gate checklist

## Decisions Changes Applied

- Updated path or section:
- Run entry added or edited:
- Structural edits:

## Rationale

- Why these ledger changes were needed:
- Why this run belongs in this section/index:

## Resulting Decision Entry

```md
[quote or summarize only the final run entry excerpt needed for audit; prefer a short excerpt plus path over pasting large ledger sections]
```

## Audit Context

Audit Execution Mode: self-audit / subagent
Subagent Availability: available / unavailable
Audit Inputs Provided:
- `/.recursive/run/<run-id>/05-manual-qa.md`
- `/.recursive/run/<run-id>/00-worktree.md`
- `/.recursive/DECISIONS.md`
- Changed files:
  - `/.recursive/DECISIONS.md`
  - final product paths reviewed

## Effective Inputs Re-read

- `/.recursive/run/<run-id>/05-manual-qa.md`
- [relevant addenda]
- `/.recursive/DECISIONS.md`

## Earlier Phase Reconciliation

- Manual QA outcome reflected:
- Run outcome and scope reflected:
- Follow-ups and OOS reflected:

## Worktree Diff Audit

- Diff basis used: `git diff --name-only <base-commit>..HEAD`
- Base branch:
- Worktree branch:
- Base commit:
- Planned or claimed changed files:
  - `/.recursive/DECISIONS.md`
- Actual changed files reviewed:
  - `/.recursive/DECISIONS.md`
  - final product paths reviewed
- Unexplained drift:
  - none / [explain]

## Gaps Found

- none / [list receipt or ledger gaps]

## Repair Work Performed

- none / [list repairs completed before re-audit]

## Audit Verdict

- Summary:
- Audit: FAIL / PASS

## Traceability
...

## Coverage Gate
...
Coverage: PASS

## Approval Gate
...
Approval: PASS
```

## Phase 7 Template (`07-state-update.md`)

Required outcome:
- `/.recursive/STATE.md` updated to reflect post-change reality
- exact state delta recorded in a lockable receipt
- rationale for any interpretation changes documented

```md
Run: `/.recursive/run/<run-id>/`
Phase: `07 State Update`
Status: `DRAFT`
Inputs:
- `/.recursive/run/<run-id>/06-decisions-update.md`
- `/.recursive/STATE.md`
- `/.recursive/DECISIONS.md`
- [relevant addenda]
Outputs:
- `/.recursive/STATE.md`
- `/.recursive/run/<run-id>/07-state-update.md`
Scope note: This document records the exact `STATE.md` changes made after the run was validated.

## TODO

- [ ] Read locked Phase 6 decisions receipt
- [ ] Update `/.recursive/STATE.md` with current truths from the validated implementation
- [ ] Record a concise delta summary of the `STATE.md` edits
- [ ] Document any major interpretation changes
- [ ] Verify the updated state matches the implemented system
- [ ] Review relevant prior recursive evidence for the affected area
- [ ] Assemble audit context bundle
- [ ] Audit receipt against final code reality and state truth
- [ ] Repair gaps and re-audit until `Audit: PASS`
- [ ] Complete Coverage Gate checklist
- [ ] Complete Approval Gate checklist

## State Changes Applied

- Updated path or section:
- Current truth changed:
- Removed or superseded statement:

## Rationale

- Why these state changes were needed:
- Why any interpretation changed:

## Resulting State Summary

- Link or section updated: `/.recursive/STATE.md#[section]`
- Current behavior delta:
- Current limitations delta:
- Operational notes delta:

## Audit Context

Audit Execution Mode: self-audit / subagent
Subagent Availability: available / unavailable
Audit Inputs Provided:
- `/.recursive/run/<run-id>/00-worktree.md`
- `/.recursive/run/<run-id>/06-decisions-update.md`
- `/.recursive/STATE.md`
- `/.recursive/DECISIONS.md`
- Changed files:
  - `/.recursive/STATE.md`
  - final product paths reviewed

## Effective Inputs Re-read

- `/.recursive/run/<run-id>/06-decisions-update.md`
- `/.recursive/STATE.md`
- `/.recursive/DECISIONS.md`
- [relevant addenda]

## Prior Recursive Evidence Reviewed

- Prior run id:
  - Docs read:
  - Reused insight:
  - Superseded or contradicted:

## Earlier Phase Reconciliation

- Decisions receipt reflected:
- Current product truths reflected:
- Known limitations reflected:

## Worktree Diff Audit

- Diff basis used: `git diff --name-only <base-commit>..HEAD`
- Base branch:
- Worktree branch:
- Base commit:
- Planned or claimed changed files:
  - `/.recursive/STATE.md`
- Actual changed files reviewed:
  - `/.recursive/STATE.md`
  - final product paths reviewed
- Unexplained drift:
  - none / [explain]

## Gaps Found

- none / [list missing or inaccurate state claims]

## Repair Work Performed

- none / [list repairs completed before re-audit]

## Audit Verdict

- Summary:
- Audit: FAIL / PASS

## Traceability
...

## Coverage Gate
...
Coverage: PASS

## Approval Gate
...
Approval: PASS
```

## Phase 8 Template (`08-memory-impact.md`)

Required outcome:
- changed paths analyzed against the memory plane
- affected memory docs reviewed and updated
- uncovered changed paths handled explicitly
- final memory statuses recorded
- run-local skill usage captured before durable promotion decisions
- durable skill-memory promotions justified explicitly
- receipt remains a concise delta summary that points to final memory docs rather than duplicating them

```md
Run: `/.recursive/run/<run-id>/`
Phase: `08 Memory Impact`
Status: `DRAFT`
Inputs:
- `/.recursive/run/<run-id>/00-worktree.md`
- `/.recursive/run/<run-id>/01-as-is.md`
- `/.recursive/run/<run-id>/02-to-be-plan.md`
- `/.recursive/run/<run-id>/03-implementation-summary.md`
- `/.recursive/run/<run-id>/04-test-summary.md`
- `/.recursive/run/<run-id>/05-manual-qa.md`
- `/.recursive/run/<run-id>/06-decisions-update.md`
- `/.recursive/run/<run-id>/07-state-update.md`
- `/.recursive/DECISIONS.md`
- `/.recursive/STATE.md`
- `/.recursive/memory/MEMORY.md`
- `/.recursive/memory/skills/SKILLS.md`
- [affected memory docs]
- [relevant addenda]
Outputs:
- `/.recursive/run/<run-id>/08-memory-impact.md`
- [updated memory docs]
Scope note: This document records memory freshness review and durable memory maintenance after the run is fully validated.

## TODO

- [ ] Read diff basis from `00-worktree.md`
- [ ] Compute final changed paths
- [ ] Exclude run-artifact churn unless explicitly relevant
- [ ] Match changed paths to memory doc owners/watchers
- [ ] Identify uncovered changed paths
- [ ] Downgrade affected `CURRENT` docs to `SUSPECT` before review
- [ ] Semantically review affected docs against final code + `STATE.md` + `DECISIONS.md`
- [ ] Update/create/split/deprecate memory docs as needed
- [ ] Promote durable skill lessons into `/.recursive/memory/skills/` or record why no promotion was needed
- [ ] Refresh parent/router docs if child memory changed materially
- [ ] Record final memory statuses
- [ ] Review relevant prior recursive evidence for the affected area
- [ ] Assemble audit context bundle
- [ ] Audit memory updates against diff, state, decisions, and prior memory truth
- [ ] Repair gaps and re-audit until `Audit: PASS`
- [ ] Complete Coverage Gate checklist
- [ ] Complete Approval Gate checklist

## Diff Basis

- Base commit / anchor:
- Head commit / comparison target:
- Exclusions applied:

## Changed Paths Review

- Changed path:
  - Owning doc(s):
  - Watching doc(s):
  - Review result:

## Affected Memory Docs

- `/.recursive/memory/domains/<doc>.md`
  - Prior status:
  - Temporary downgrade:
  - Final status:
  - Change summary:
  - Final doc path to review:
- `/.recursive/memory/skills/<category>/<doc>.md`
  - Prior status:
  - Final status:
  - Skill lesson captured:

## Uncovered Paths

- Changed path without owner:
  - Action: [created new domain doc / explicit follow-up]
  - Follow-up path or note:

## Router and Parent Refresh

- `/.recursive/memory/MEMORY.md` changes:
- `/.recursive/memory/skills/SKILLS.md` changes:
- Parent doc updates:

## Final Status Summary

- Restored to `CURRENT`:
- Left as `SUSPECT`:
- Marked `STALE`:
- Deprecated / archived:

## Run-Local Skill Usage Capture

- Skill Usage Relevance: `relevant|not-relevant`
- Available Skills:
- Skills Sought:
- Skills Attempted:
- Skills Used:
- Worked Well:
- Issues Encountered:
- Future Guidance:
- Promotion Candidates:

## Skill Memory Promotion Review

- Durable Skill Lessons Promoted:
- Generalized Guidance Updated:
- Run-Local Observations Left Unpromoted:
- Promotion Decision Rationale:

## Audit Context

Audit Execution Mode: self-audit / subagent
Subagent Availability: available / unavailable
Audit Inputs Provided:
- `/.recursive/run/<run-id>/00-worktree.md`
- final validated run artifacts
- `/.recursive/DECISIONS.md`
- `/.recursive/STATE.md`
- `/.recursive/memory/MEMORY.md`
- `/.recursive/memory/skills/SKILLS.md`
- affected memory docs
- Changed files:
  - final product paths reviewed
  - memory doc paths reviewed

## Effective Inputs Re-read

- `/.recursive/run/<run-id>/00-worktree.md`
- `/.recursive/run/<run-id>/03-implementation-summary.md`
- `/.recursive/run/<run-id>/04-test-summary.md`
- `/.recursive/run/<run-id>/06-decisions-update.md`
- `/.recursive/run/<run-id>/07-state-update.md`
- `/.recursive/DECISIONS.md`
- `/.recursive/STATE.md`
- `/.recursive/memory/MEMORY.md`
- affected memory docs
- [relevant addenda]

## Prior Recursive Evidence Reviewed

- Prior run id:
  - Docs read:
  - Reused insight:
  - Superseded or contradicted:

## Earlier Phase Reconciliation

- Final diff vs memory ownership:
- State update vs memory truth:
- Decisions update vs memory truth:

## Worktree Diff Audit

- Diff basis used: `git diff --name-only <base-commit>..HEAD`
- Base branch:
- Worktree branch:
- Base commit:
- Planned or claimed changed files:
  - memory-impact targets
- Actual changed files reviewed:
  - final product paths reviewed
  - memory doc paths reviewed
- Unexplained drift:
  - none / [explain]

## Gaps Found

- none / [list uncovered paths, stale memory, or unresolved status transitions]

## Repair Work Performed

- none / [list repairs completed before re-audit]

## Audit Verdict

- Summary:
- Audit: FAIL / PASS

## Traceability
...

## Coverage Gate
...
Coverage: PASS

## Approval Gate
...
Approval: PASS
```

## Addenda Templates

## Stage-Local Addendum

File name:
- `<base>.addendum-01.md`

```md
Run: `/.recursive/run/<run-id>/`
Phase: `<current phase>`
Status: `DRAFT`
Inputs:
- `<base artifact>`
Outputs:
- `/.recursive/run/<run-id>/addenda/<base>.addendum-01.md`
Scope note: This addendum supplements phase-local content without changing locked history.

## TODO

- [ ] Add the missing information
- [ ] Update Traceability/Coverage implications in the current phase artifact (if needed)
- [ ] Complete Coverage Gate checklist
- [ ] Complete Approval Gate checklist

## Addendum Content

- Added/clarified information:
- Rationale:
- Impact on phase output:

## Coverage Gate
...
Coverage: PASS

## Approval Gate
...
Approval: PASS
```

## Upstream-Gap Addendum

File name:
- `<current>.upstream-gap.<prior>.addendum-01.md`

```md
Run: `/.recursive/run/<run-id>/`
Phase: `<current phase>`
Status: `DRAFT`
Inputs:
- `<current phase inputs>`
- `<locked prior artifact>`
Outputs:
- `/.recursive/run/<run-id>/addenda/<current>.upstream-gap.<prior>.addendum-01.md`
Scope note: This addendum records a discovered gap in a locked upstream artifact.

## TODO

- [ ] Record the upstream gap precisely
- [ ] Add discovery evidence (commands, files, outputs)
- [ ] State impact and compensation plan
- [ ] Update current-phase planning/implementation accordingly
- [ ] Complete Coverage Gate checklist
- [ ] Complete Approval Gate checklist

## Gap Statement

- Missing or incorrect upstream content:

## Discovery Evidence

- How the gap was found:
- Supporting evidence:

## Impact

- Impact on current phase:
- Impact on later phases:

## Compensation Plan

- Tests, validation, or process compensations applied now:

## Traceability Impact

- Affected requirements: `R#`, `R#`

## Coverage Gate
...
Coverage: PASS

## Approval Gate
...
Approval: PASS
```

## Artifact Linting (Structure + TODO Discipline)

Before locking (or when a lock verification fails unexpectedly), lint the run artifacts for required header fields, required section headings, and TODO completion rules:

```powershell
# Python (cross-platform):
python ./.agents/skills/recursive-mode/scripts/lint-recursive-run.py --run-id "<run-id>"
# Or, when running from this repo:
python ./scripts/lint-recursive-run.py --run-id "<run-id>"
python3 ./.agents/skills/recursive-mode/scripts/lint-recursive-run.py --run-id "<run-id>"
python3 ./scripts/lint-recursive-run.py --run-id "<run-id>"

# Treat WARN as FAIL
python ./.agents/skills/recursive-mode/scripts/lint-recursive-run.py --run-id "<run-id>" --strict
python ./scripts/lint-recursive-run.py --run-id "<run-id>" --strict
python3 ./.agents/skills/recursive-mode/scripts/lint-recursive-run.py --run-id "<run-id>" --strict
python3 ./scripts/lint-recursive-run.py --run-id "<run-id>" --strict

# Lint specific run
.\.agents\skills\recursive-mode\scripts\lint-recursive-run.ps1 -RunId "<run-id>"
# Or, when running from this repo:
.\scripts\lint-recursive-run.ps1 -RunId "<run-id>"

# Treat WARN as FAIL
.\.agents\skills\recursive-mode\scripts\lint-recursive-run.ps1 -RunId "<run-id>" -Strict
.\scripts\lint-recursive-run.ps1 -RunId "<run-id>" -Strict
```

## Locking Commands

Preferred:

```powershell
# Python (cross-platform)
python ./.agents/skills/recursive-mode/scripts/recursive-lock.py --run-id "<run-id>" --artifact "<artifact>.md"
# Or, when running from this repo:
python ./scripts/recursive-lock.py --run-id "<run-id>" --artifact "<artifact>.md"
python3 ./.agents/skills/recursive-mode/scripts/recursive-lock.py --run-id "<run-id>" --artifact "<artifact>.md"
python3 ./scripts/recursive-lock.py --run-id "<run-id>" --artifact "<artifact>.md"

# PowerShell
.\.agents\skills\recursive-mode\scripts\recursive-lock.ps1 -RunId "<run-id>" -Artifact "<artifact>.md"
# Or, when running from this repo:
.\scripts\recursive-lock.ps1 -RunId "<run-id>" -Artifact "<artifact>.md"
```

The lock command is the primary supported path. It must refuse to lock artifacts whose required gates or lint-critical structure are still invalid.

Manual fallback for hash computation only:

PowerShell:

```powershell
$p = '.recursive/run/<run-id>/<artifact>.md'
$t = Get-Content -LiteralPath $p -Raw -Encoding UTF8
$n = ($t -replace "`r`n","`n") -replace "(?m)^LockHash:.*(?:`n|$)",""
$b = [System.Text.Encoding]::UTF8.GetBytes($n)
$h = [System.Security.Cryptography.SHA256]::Create().ComputeHash($b)
($h | ForEach-Object { $_.ToString("x2") }) -join ""
```

Shell:

```bash
sed '/^LockHash:/d' .recursive/run/<run-id>/<artifact>.md | tr -d '\r' | sha256sum
```

## Common Failure Modes (Use as Pre-Lock Checklist)

- Missing one or more effective-input addenda under `Inputs`.
- Relevant addenda exist but are not re-read in `## Effective Inputs Re-read`.
- Relevant addenda exist but are not reconciled in `## Earlier Phase Reconciliation`.
- Coverage Gate says PASS but does not map every `R#`.
- Approval Gate says PASS with unresolved blockers.
- `Traceability` references vague evidence instead of concrete files/commands.
- Artifact locked without `LockedAt` and `LockHash`.
- **LockHash does not match SHA-256 of normalized content (tampering detected).**
- Editing locked prior-phase artifacts instead of writing addenda.
- Delegated review has a bundle file but the written review does not cite upstream artifacts, relevant addenda, or changed files/code refs from that bundle.
- Diff audit is failing on transient runtime noise because incidental cache files were mistaken for meaningful repo changes.
- Working on main/master branch without explicit consent documented.
- Worktree directory not git-ignored (project-local worktrees).
- Baseline tests failing (pre-existing issues not documented).

## Lock Verification

### Automated Verification

Use the provided script to verify all locks in a run:

```bash
# Verify specific run
python ./.agents/skills/recursive-mode/scripts/verify-locks.py --run-id "<run-id>"
# Or, when running from this repo:
python ./scripts/verify-locks.py --run-id "<run-id>"
python3 ./.agents/skills/recursive-mode/scripts/verify-locks.py --run-id "<run-id>"
python3 ./scripts/verify-locks.py --run-id "<run-id>"

# Fix incorrect hashes (use with caution)
python ./.agents/skills/recursive-mode/scripts/verify-locks.py --run-id "<run-id>" --fix
# Or, when running from this repo:
python ./scripts/verify-locks.py --run-id "<run-id>" --fix
python3 ./.agents/skills/recursive-mode/scripts/verify-locks.py --run-id "<run-id>" --fix
python3 ./scripts/verify-locks.py --run-id "<run-id>" --fix
```

```powershell
# Verify specific run
.\.agents\skills\recursive-mode\scripts\verify-locks.ps1 -RunId "<run-id>"
# Or, when running from this repo:
.\scripts\verify-locks.ps1 -RunId "<run-id>"

# Fix incorrect hashes (use with caution)
.\.agents\skills\recursive-mode\scripts\verify-locks.ps1 -RunId "<run-id>" -Fix
# Or, when running from this repo:
.\scripts\verify-locks.ps1 -RunId "<run-id>" -Fix
```

### Manual Verification

Compute SHA-256 hash:

**PowerShell:**
```powershell
$p = '.recursive/run/<run-id>/<artifact>.md'
$t = Get-Content -LiteralPath $p -Raw -Encoding UTF8
$n = ($t -replace "`r`n","`n") -replace "(?m)^LockHash:.*(?:`n|$)",""
$b = [System.Text.Encoding]::UTF8.GetBytes($n)
$h = [System.Security.Cryptography.SHA256]::Create().ComputeHash($b)
($h | ForEach-Object { $_.ToString("x2") }) -join ""
```

**Shell:**
```bash
sed '/^LockHash:/d' .recursive/run/<run-id>/<artifact>.md | tr -d '\r' | sha256sum
```

Compare computed hash with `LockHash` in artifact header. They must match exactly.


reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall