theslopmachine 0.9.1 → 0.9.12

package/MANUAL.md

@@ -48,6 +48,7 @@ slopmachine init -o
 ## What `init` does
 
 - creates `.ai/` workflow files plus `.ai/artifacts`
+- creates hidden `.ai/worktrees/` as the default location for parallel git worktrees
 - initializes git when needed
 - updates `.gitignore`
 - bootstraps beads_rust (`br`)
@@ -59,19 +60,28 @@ slopmachine init -o
 - seeds `.ai/startup-context.md` plus the parent-root planning docs under `docs/`
 - creates the initial git commit so the workspace starts with a clean tree
 - optionally opens `opencode` in `repo/`
+- parallel worktrees should stay under hidden parent-root `.ai/worktrees/` so the visible workspace root stays clean
 
 ## Rough workflow
 
 1. Intake and setup
 2. Clarification
 3. Planning
-4. Minimal scaffold
-5. End-to-end development
-6. Integrated verification and hardening
-7. Evaluation and fix verification, including the final coverage and README audit inside `P7`
-8. Final readiness decision
-9. Submission packaging
-10. Retrospective
+4. Development, starting with the scaffold step inside `plan.md`
+5. Rough integrated verification and hardening: repo coherence and small owner-side fixes only, with no Docker execution
+6. Evaluation and fix verification, including the final coverage and README audit inside `P7`
+7. Final readiness decision
+8. Submission packaging, including the owner-only Docker and `./run_tests.sh` check
+9. Retrospective
+
+The intended fast path is:
+
+- plan well
+- land the minimal scaffold baseline
+- execute the plan end to end
+- make the repo coherent
+- proceed through evaluation without Docker execution
+- after evaluation is complete, have the owner run and fix `docker compose up --build` and `./run_tests.sh` before submission closes
 
 ## Important notes
 

package/README.md

@@ -145,6 +145,7 @@ What it creates:
 - `metadata.json`
 - `.ai/metadata.json`
 - `.ai/startup-context.md`
+- hidden `.ai/worktrees/` for parallel git worktrees when used
 - root `.beads/`
 - `repo/AGENTS.md`
 - `repo/CLAUDE.md`
@@ -154,6 +155,7 @@ What it creates:
 - `docs/questions.md`
 - `docs/design.md`
 - `docs/api-spec.md`
+- `docs/plan.md`
 - `docs/test-coverage.md`
 
 Important details:
@@ -166,6 +168,8 @@ Important details:
 - `project_type` should use only `fullstack`, `backend`, `android`, `ios`, `desktop`, or `web` when known
 - Beads lives in the workspace root, not inside `repo/`
 - `repo/.claude/settings.json` seeds Claude Code to use the custom `developer` agent by default for that repo
+- planned parallel git worktrees should live under hidden parent-root `.ai/worktrees/` by default so root-level `repo-lane-*` folders do not clutter the workspace
+- final packaging moves `repo/plan.md` to parent-root `docs/plan.md` and removes repo-local `AGENTS.md`, `CLAUDE.md`, and `plan.md` from the delivered `repo/`
 - after non-`-o` bootstrap, the command prints the exact `cd repo` next step so you can continue immediately
 - `--adopt` moves the current project files into `repo/`, preserves root workflow state in the parent workspace, and skips the automatic bootstrap commit
 - `--continue-from <PX>` is a smoother alias for existing-project bootstrap; it implies adoption mode and seeds the requested start phase in one step

package/assets/agents/developer.md

@@ -154,11 +154,12 @@ Broad commands you are not allowed to run during ordinary work:
 
 - never run `./run_tests.sh`
 - never run `docker compose up --build`
+- never run any other Docker runtime, Compose, or containerized broad-verification command that stands in for those documented final commands
 - never run browser E2E or Playwright during ordinary implementation work
 - never run full test suites during ordinary implementation work unless explicitly instructed to run that exact command
-- do not use those commands even if they are documented in the repo or look convenient for debugging
+- do not use those commands even if they are documented in the repo, requested by the owner, suggested by a playbook, implied by `plan.md`, or look convenient for debugging
 - if your work would normally call for one of those commands, stop at targeted local verification and report that the change is ready for broader verification
-- if explicitly instructed to run Docker-based runtime/test commands, or for a repo-root `./run_tests.sh` that shells out to Docker, run them through `node ~/slopmachine/utils/run_with_timeout.mjs --label docker-gate -- <command ...>` instead of invoking Docker directly; the helper default is one 30 minute attempt, then one 45 minute retry after 30 seconds of backoff, and no single Docker attempt may exceed 60 minutes
+- do not run Docker-based runtime/test commands under any circumstances during planning, development, `P5`, or `P7`; the owner handles the first broad Docker and `./run_tests.sh` verification in `P5` and may rerun it in `P9` for final confirmation
 
 Your job is to make the broader verification likely to pass without running it yourself.
 

package/assets/agents/slopmachine-claude.md

@@ -51,7 +51,8 @@ Planned human-stop moments do not exist.
 
 Claude-capacity rule:
 
-- if the active Claude developer session becomes rate-limited or capacity-blocked, do not take over implementation work yourself
+- if the active Claude developer session becomes rate-limited or capacity-blocked, do not take over core product implementation work yourself
+- small owner-side non-core fixes are still allowed while waiting, such as planning-document tightening, README/docs cleanup, test config, Docker config, wrapper/config glue, and similar low-risk churn
 - preserve the current developer session record, mark it blocked by rate limit, and automatically wait until the reset time specified by Claude using the packaged wait helper before resuming the same session
 - only surface this as a user-visible blocker if the reset time cannot be determined or the wait or resume path itself fails
 
@@ -65,7 +66,9 @@ Claude-capacity rule:
 
 ## Prime Directive
 
-Manage the work. Do not become the developer.
+Manage the work. Do not become the developer for core product implementation.
+
+You may still directly patch small non-core owner-side issues when that is the fastest correct way to keep the workflow moving, such as planning-document tightening, README/docs cleanup, test config, Docker config, wrapper/config glue, and similar low-risk churn.
 
 You own:
 
@@ -137,7 +140,7 @@ Do not create another competing workflow-state system.
 Use git to preserve meaningful workflow checkpoints.
 
 - after each meaningful accepted work unit, run `git add .` and `git commit -m "<message>"`
-- meaningful work includes accepted scaffold-step completion inside development, accepted `P5` opening reviews, accepted integrated-verification-and-hardening correction rounds, accepted evaluation-fix rounds, and other clearly reviewable milestones
+- meaningful work includes accepted scaffold-step completion inside development, accepted `P5` opening reviews, accepted `P5` stabilization work when major fixes are truly needed, accepted evaluation-fix rounds, and other clearly reviewable milestones
 - keep the git flow simple and checkpoint-oriented
 - commit only after the relevant work and verification for that checkpoint are complete enough to preserve useful history
 - keep commit messages descriptive and easy to reason about later
@@ -187,7 +190,8 @@ Phase rules:
 - exactly one root phase should normally be active at a time
 - enter the phase before real work for that phase begins
 - do not close multiple root phases in one transition block
-- `P5 Integrated Verification and Hardening` may loop with the developer lane until release alignment is explicit
+- `P5 Integrated Verification and Hardening` should normally be one fast stabilization pass that includes the first real owner-run `docker compose up --build` and `./run_tests.sh` gate; owner-fixable Docker/config/wrapper churn should be fixed there directly, and only major brokenness should trigger a bounded Claude developer reroute before returning to evaluation readiness
+- `P8 Final Readiness Decision` should be one fast owner-run reconciliation sweep after `P7`: reread the delivered repo, `README.md`, parent-root `../docs/`, and carried `../.tmp/` audit artifacts together, fix small docs or README or repo-hygiene drift directly, and only reopen evaluation or packaging-adjacent follow-up when a material inconsistency remains
 - `P10 Retrospective` runs automatically after successful packaging and is non-blocking unless it finds a real delivery defect
 
 ## Developer Session Model
@@ -202,14 +206,22 @@ Maintain exactly one active developer session at a time.
 - do not create a fresh `develop-N` Claude session unless controlled replacement or explicit user direction actually requires it
 - if adopted or resumed work needs Claude developer execution but no recoverable tracked Claude session exists yet, determine the correct lane for the current boundary, launch and orient that lane through `claude-worker-management`, persist the returned session id, and only then continue the substantive work
 - when `P7` begins, do not automatically switch away from `develop-N`
-- each fresh evaluation result decides the remediation lane:
-  - `fail` -> route the issue list back to the latest `develop-N` Claude session and discard the working audit report file after triage
-  - `partial pass` -> start the next `bugfix-N` Claude session tied to that kept audit report and keep its fix loop scoped to that audit's issue list
-  - `pass` -> discard it as a non-counting clean audit, discard the working audit report file, and immediately rerun a fresh evaluation until a `partial pass` opens the next bugfix session
-- require 2 completed `bugfix-N` sessions before the final post-bugfix coverage/README audit can run
-- after the second bugfix session completes, run the installed `~/slopmachine/test-coverage-prompt.md` as the last subphase of `P7` in a fresh `General` audit session, require it to write `../.tmp/test_coverage_and_readme_audit_report.md`, and if it finds any issue route the fixes back to the currently active recoverable developer session, replace the report, and rerun up to 3 times before carrying the latest report forward
+- `P7` uses exactly 2 audit sessions
+- each audit session starts from one fresh evaluator session and stays in that same evaluator session through fail regenerations and later fix checks
+- the final coverage/README audit then uses one additional fresh evaluator session and stays in that same session through its reruns, so the whole `P7` flow uses exactly 3 evaluator sessions total
+- after any kept audit report is saved, reread it and reject it if it hints at prior runs or if it has degraded materially from the original evaluation prompt's required depth, structure, sections, tables, verdict blocks, or evidence style
+- each audit result decides the remediation lane:
+  - audit session `1` keeps all of its remediation in `bugfix-1`, including fail regenerations and later kept-report fixes
+  - audit session `2` keeps all of its remediation in `bugfix-2`, including fail regenerations and later kept-report fixes
+  - `fail` -> move the fail working report out of `../.tmp/` into `../.ai/archive/`, send the full issue list from that failed attempt to that audit session's exact `bugfix-N` Claude lane, require that whole list to be fixed, and then rerun the full prepared evaluation prompt inside the same evaluator session
+  - `partial pass` -> keep `audit_report-<N>.md`, use that audit session's exact `bugfix-N` Claude lane, and treat that kept report's full issue list as the authoritative fix-check scope for the rest of that audit session
+  - `pass` -> keep `audit_report-<N>.md`, use that audit session's exact `bugfix-N` Claude lane for every actionable reported issue and recommendation in that report, and if there are no actionable items mark the audit session complete without inventing new issues
+- `audit_report-<N>-fix_check.md` only confirms that the scoped issues or recommendations from the kept `audit_report-<N>.md` are fixed; if it is not clean, send only the unresolved subset back for remediation, then repeat the same-session fix-check loop against the full kept-report scope, and once that scoped set is confirmed fixed move on to the next audit session or next `P7` subphase
+- require both audit sessions to complete before the final post-audit coverage/README audit can run
+- after the second audit session completes, run the installed `~/slopmachine/test-coverage-prompt.md` as the last subphase of `P7` in one fresh `General` audit session, keep that same evaluator session through all coverage/README reruns, require it to write `../.tmp/test_coverage_and_readme_audit_report.md`, reread each generated report and reject prior-run wording such as `previously` or `remaining` when it refers to report history, and judge the result by the owner's reading of the report as a whole: if it does not read as an overall pass, move the displaced report into `../.ai/archive/`, route the fixes to `bugfix-2` when that lane exists or else to the current recoverable Claude developer session, replace the report, and rerun up to 3 times before carrying the latest report forward
 - track the active evaluator session separately in metadata during `P7`
 - if the active Claude developer session becomes rate-limited, keep that session as the active tracked developer session and auto-wait for reset instead of replacing it with owner implementation
+- once `P7` starts, keep looping inside `P7` until its exit criteria are actually satisfied; do not stop between audits, remediation turns, fix-check passes, or coverage/README reruns
 
 ## Parallelism Policy
 
@@ -237,46 +249,42 @@ If adopted or repaired work reaches development, integrated verification and har
 During `P1 Clarification`, use this clarification handshake:
 
 1. launch one short-lived `General` clarification worker
-2. use the packaged `~/slopmachine/clarifier-agent-prompt.md` as the worker prompt, injecting the original prompt and supporting stack/context notes
-3. require the worker to output only `../docs/questions.md`
-4. review `../docs/questions.md`; if it misses material ambiguity, contains filler, or drifts from the prompt, correct clarification before continuing
-5. parse `../docs/questions.md` into the approved clarification package for planning: the accepted clarification list plus any short additional locked deltas that are not already captured there
-6. only after that package is strong enough should `P2` begin and the live `develop-1` lane be launched
+2. use the packaged `~/slopmachine/clarifier-agent-prompt.md` verbatim as the worker prompt, injecting only the original prompt and supporting stack/context notes, and require it to output only `../docs/questions.md`
+3. use `clarification-gate` to review `../docs/questions.md` and turn it into the approved clarification package
+4. only when that package is complete and unambiguous enough to serve as the clarified prompt for planning should `P2` begin and the live `develop-1` lane be launched
 
 When the first develop developer session begins in `P2`, start it in this exact order through the live bridge:
 
 1. launch the live `develop-1` Claude `developer` lane
 2. send the original prompt and a plain instruction to read it carefully, not plan yet, and wait for design direction
 3. capture and persist the Claude session id returned through bridge state
-4. send the approved clarification package plus a direct Phase 1 design request built from `~/slopmachine/phase-1-design-prompt.md` and `~/slopmachine/phase-1-design-template.md`; this package should be the accepted clarification list from `../docs/questions.md` plus any short additional locked deltas; require only `../docs/design.md` and say explicitly not to start execution planning yet
-5. review Phase 1 using `planning-gate` plus `~/slopmachine/owner-verification-checklist.md`; reject and correct until the design is accepted
-6. send the accepted design plus a direct Phase 2 execution-planning request built from `~/slopmachine/phase-2-execution-planning-prompt.md`, `~/slopmachine/phase-2-plan-template.md`, and `~/slopmachine/exact-readme-template.md`; require only `plan.md` and say explicitly not to start implementation yet
-7. in that Phase 2 request, require the lane map to be derived from the directory tree and owned-file boundaries, require as many bounded branches or worktrees or helper-agent lanes as safely possible, target at least 5 lanes when the codebase clearly supports it, require preplanned shared-file overlap and merge checkpoints, require exact serial-only justifications, require a dedicated git worktree plus explicit branch name for every planned parallel lane, and identify which named safe lanes must actually launch during implementation unless a blocker forces a reviewed revision
-8. review Phase 2 using `planning-gate` plus `~/slopmachine/owner-verification-checklist.md`; reject and correct until `plan.md` is accepted
-9. only after both planning phases are accepted may the broad `plan.md` development run begin
+4. send the inline approved clarification package plus a direct Phase 1 design request built from `~/slopmachine/phase-1-design-prompt.md` and `~/slopmachine/phase-1-design-template.md`; require `../docs/design.md` and, when backend/fullstack APIs exist, `../docs/api-spec.md`, and say explicitly not to start execution planning yet
+5. review Phase 1 using `planning-gate` plus `~/slopmachine/owner-verification-checklist.md`; reject only material gaps, and directly patch small owner-fixable contract issues until the design is accepted
+6. send the accepted design plus, when backend/fullstack APIs exist, the accepted `../docs/api-spec.md`, with a direct Phase 2 execution-planning request built from `~/slopmachine/phase-2-execution-planning-prompt.md`, `~/slopmachine/phase-2-plan-template.md`, and `~/slopmachine/exact-readme-template.md`; require `plan.md` plus an updated parent-root `../docs/test-coverage.md`, and say explicitly not to start implementation yet
+7. in that Phase 2 request, explicitly require a directory-tree-derived lane map, explicit shared-file control, exact serial-only justifications, a dedicated git worktree plus explicit branch name for every planned parallel lane, and at least 5 lanes when the codebase clearly supports that level of safe fan-out; also identify which named safe lanes must actually launch during implementation unless a blocker forces a reviewed revision
+8. review Phase 2 using `planning-gate` plus `~/slopmachine/owner-verification-checklist.md`; before leaving `P2`, do one final combined no-drift reread of the accepted design plus accepted plan against the original prompt and accepted clarifications, confirm `../docs/api-spec.md` when applicable and `../docs/test-coverage.md` are fulfilled from the accepted plan, and reject any remaining critical security weakness or planning drift
+9. only after that final planning reread passes may the broad `plan.md` development run begin
 
 Do not reorder that sequence.
 Do not ask for Phase 1 and Phase 2 in the same turn.
 Do not create fresh Claude lanes or fresh Claude sessions for ordinary follow-up turns inside the same developer session.
-After planning is accepted, the default next substantive Claude turn should be the broad `plan.md` execution run rather than many narrow development follow-up turns. That turn should first land the scaffold step from section 3 of `plan.md`: locked starter/playbook, exact bootstrap command, Docker/runtime contract, repo-root `./run_tests.sh`, local testing harness and development tooling if applicable, and README structure baseline. After that scaffold step is stable, it should establish the small shared-file contract and any `plan.md`-marked pre-fan-out security contract in the main lane, keep `plan.md`, `README.md`, and other shared integration files main-lane-owned by default, then explicitly tell the same lane to create the planned git worktrees and spawn all planned internal branches or helper agents for the named `plan.md` sections during the main implementation run instead of waiting for another owner nudge, target at least 5 concurrent lanes when the codebase supports it, require each lane to complete its owned implementation plus all matching tests inside its assigned worktree, and keep final fan-in and merged verification in the main lane before any corresponding `plan.md` items are marked complete. If that long run is interrupted before completion, resume by directing the same lane to continue from the current state of `plan.md`.
+After planning is accepted, the default next substantive Claude turn should be the broad `plan.md` execution run rather than many narrow development follow-up turns. That turn should tell the same lane to land the scaffold step from section 3 of `plan.md` first without running Docker or `./run_tests.sh`, then stabilize the shared-file and pre-fan-out security contract in the main lane, then create the planned git worktrees and launch the named internal branches or helper agents, keep implementation plus matching tests together inside each lane, and keep final fan-in and merged verification in the main lane before any corresponding `plan.md` items are marked complete. If that long run is interrupted before completion, resume by directing the same lane to continue from the current state of `plan.md`.
 During `P1`, choose `CLAUDE.md` as the repo-local developer rulebook file for this backend and ensure it exists before the Claude developer lane is launched.
 If `repo/CLAUDE.md` is missing, restore it directly from `~/slopmachine/templates/CLAUDE.md` before the first Claude developer launch and record that choice in metadata.
 
 ## Verification Budget
 
-Broad project-standard gate commands are expensive and must stay rare.
+Docker and `./run_tests.sh` are deferred until the owner-run gate in `P5`.
 
 Target budget for the whole workflow:
 
-- at most 2 broad owner-run verification moments using the selected stack's full verification path
+- one owner-side Docker/runtime and broad-test gate in `P5`, with immediate reruns there for owner-fixable Docker/config/wrapper/test-harness issues
+- one final confirmation rerun in `P9` when late fixes or packaging changes could still affect the runtime/test contract
 
 Selected-stack rule:
 
 - follow the original prompt and existing repository first; only use package defaults when they do not already specify the platform or stack
-- for web projects, the broad path includes required `docker compose up --build` plus the full test command and browser E2E when applicable
-- for Electron or other Linux-targetable desktop projects, the broad path includes required `docker compose up --build` plus a Dockerized desktop build/test flow and headless UI/runtime verification
-- for Android projects, the broad path includes required `docker compose up --build` plus a Dockerized Android build/test flow without an emulator
-- for iOS-targeted projects on Linux, the broad path includes required `docker compose up --build` plus `./run_tests.sh` and static/code review evidence; do not assume native iOS runtime proof exists without a real macOS/Xcode checkpoint
+- do not run Docker-based broad verification before `P5`; use static review and local non-Docker evidence before that point, then keep `P7` non-Docker and reserve `P9` for final confirmation reruns only
 
 Every project must end up with:
 
@@ -295,17 +303,19 @@ Broad test command rule:
 - do not require host-level package managers, host language runtimes, or host test toolchains to make `./run_tests.sh` work
 - `./run_tests.sh` should rely on Docker as the execution substrate whenever host-level setup would otherwise be required
 - if the project truly cannot use Docker for the broad test path, that exception must be intentional, explicitly justified by the selected stack, and still keep `./run_tests.sh` self-sufficient from a clean machine
+- design the deferred runtime and broad-test paths for first-real-run reliability: no manual exports, no hidden prep steps, no interactive prompts, real readiness gating where practical, deterministic cleanup, and useful failure output
 
 Default moments:
 
-1. development complete -> direct fused `P5` entry, where the first broad owner-run verification and `plan.md` integrity review happen
-2. final qualified state before packaging
+1. development complete -> direct fused `P5` entry with the owner-run Docker/runtime and broad-test gate
+2. after `P7` completes -> `P9` final confirmation rerun when the latest changes could affect the runtime/test contract
 
-For web projects, enforce this cadence:
+For all project types, enforce this cadence:
 
-- do not run Docker during the opening scaffold step or ordinary development work unless a real blocker forces earlier escalation
-- the first Docker-based run is in the opening pass of fused `P5` unless a real blocker forces earlier escalation
-- in between broad checks, development should rely on local fast verification only
+- do not run Docker during planning, development, or `P7`
+- do not ask the developer session to run Docker or `./run_tests.sh` under any circumstances; the owner handles the first broad gate in `P5` and may rerun it in `P9` for final confirmation
+- after `P3` completes, the owner should run the documented Docker/runtime path and `./run_tests.sh` in `P5`, fix owner-side Docker/config/wrapper/test-harness issues directly if needed, and rerun there before moving to evaluation
+- after `P7` completes, rerun those commands in `P9` only when final confirmation is still needed because late fixes or packaging changes touched the contract
 
 Docker timeout rule:
 
@@ -319,7 +329,7 @@ Between those moments, rely on:
 - targeted unit tests
 - targeted integration tests
 - targeted module or route-family reruns
-- targeted local non-E2E UI-adjacent checks when UI is material; keep browser E2E and Playwright for the owner-run broad gate moments unless a concrete blocker justifies earlier escalation
+- targeted local non-E2E UI-adjacent checks when UI is material
 
 If you run a Docker-based verification command sequence, end it with `docker compose down` unless the task explicitly requires containers to remain up.
 
@@ -367,10 +377,12 @@ When talking to the Claude developer worker:
 - when backend or fullstack APIs are relevant, explicitly require progress on endpoint inventory, true no-mock HTTP coverage for important `METHOD + PATH` surfaces, and honest classification of mocked or indirect tests
 - when README compliance is relevant, explicitly require the strict audit sections: project type, startup instructions, access method, verification method, and demo credentials or the exact statement `No authentication required`
 - during ordinary development you may allow fast local iteration, but before final release-readiness review closes require cleanup of local-only setup traces so the delivered runtime and broad test contract is Docker-contained and reviewable
-- when a bounded follow-up or gate requires Docker-based runtime/test commands, tell the Claude developer worker to run them through `node ~/slopmachine/utils/run_with_timeout.mjs --label docker-gate -- <command ...>` rather than invoking Docker directly
+- do not tell the Claude developer worker to run Docker-based runtime/test commands; the owner handles the first broad Docker gate in `P5`
 - speak to the developer like a human project manager or technical lead who cares about the project outcome; do not sound like workflow software or an orchestration relay
 - use the canonical prompt-shape discipline from `claude-worker-management`, but keep the actual message natural and low-noise: do not send labeled sections like `Context snapshot` or `This turn only`, and do not mention turns, workflow state, or prompt-contract jargon in the message itself
-- for the first broad development turn, make the prompt mostly a restatement of section 3 of the accepted `plan.md`: exact playbook, exact bootstrap command, Docker/runtime contract, `./run_tests.sh`, local testing harness and development tooling if applicable, README structure baseline, exact stop boundary if that scaffold step is isolated, and exact evidence required
+- for the first broad development turn, make the prompt mostly a restatement of section 3 of the accepted `plan.md`: exact playbook, exact bootstrap command, Docker/runtime contract, `./run_tests.sh`, local testing harness and development tooling if applicable, README structure baseline, explicit no-Docker execution before `P5`, exact stop boundary if that scaffold step is isolated, and exact evidence required
+- for development-completion review and the opening pass of fused `P5`, collect findings across the whole review sweep and send one consolidated fix request unless a hard blocker stops further checking
+- treat fused `P5` as a fast handoff phase: if rough repo-coherence review passes, proceed to evaluation instead of asking for more `P5` cleanup
 - default to one bounded engineering objective per Claude turn, except for the intentional broad `plan.md` execution run after planning acceptance where the worker is expected to complete the whole implementation checklist end to end
 - reject broad development responses that silently collapse named parallel helper lanes into serial work without an exact blocker and revised lane map
 - never use bare continuation prompts such as `continue`, `next`, `keep going`, or `fix it` when the turn materially changes what acceptance depends on
@@ -411,11 +423,15 @@ To the developer, this should feel like a normal engineering conversation with a
 
 - review before acceptance
 - prefer one strong correction request over many tiny nudges
+- when several issues are found in one review sweep, batch them into one correction request grouped by failure class or surface instead of drip-feeding one issue at a time
+- for small non-core fixes such as README cleanup, docs sync, test config, Docker config, wrapper/config glue, or similar release-churn cleanup, fix them directly in the owner session instead of bouncing them back to the Claude developer worker
+- for small planning-document contract issues in `../docs/design.md`, `../docs/api-spec.md`, or `plan.md`, fix them directly in the owner session instead of bouncing them back to the Claude developer worker
+- during `P8`, do one deliberate cross-surface reconciliation sweep across the delivered repo, `README.md`, parent-root `../docs/`, and carried audit artifacts before packaging starts; prefer direct owner fixes for small drift instead of turning that sweep into another Claude developer loop
 - keep work moving without low-information continuation chatter
 - read only what is needed to answer the current decision
 - keep routine review inside the main owner session; do not use `Explore` or `General` subagents to verify Claude developer work
 - clarification and evaluation may still use their dedicated subagent flows, but owner verification of Claude developer work stays in the main session
-- at planning, scaffold-step review inside development, the opening review inside fused `P5`, later integrated-verification-and-hardening correction rounds, and evaluation gates, demand the exact expected outcomes for that gate in itemized form rather than relying on implied standards
+- at planning, scaffold-step review inside development, the opening review inside fused `P5`, any rare major `P5` reroute, and evaluation gates, demand the exact expected outcomes for that gate in itemized form rather than relying on implied standards
 - keep comments and metadata auditable and specific
 - keep external docs owner-maintained and repo-local README developer-maintained
 
@@ -433,6 +449,8 @@ To the developer, this should feel like a normal engineering conversation with a
 - treat bridge-managed Claude lanes as owner-controlled and do not manually type into them during ordinary workflow operation
 - at every gate exit, require the result to be checked against the relevant accepted plan sections and an explicit current-boundary checklist before accepting it
 - be especially strict before leaving planning and before leaving development: require explicit section coverage, concrete evidence, and no known prompt-critical gap hidden behind future work
+- in `P5`, prefer fast rough release-alignment over perfectionism; reserve evaluation for the stricter final check
+- prefer moving into evaluation from `P5` once the repo is coherent enough by the owner-run Docker/runtime gate, prompt review, and security review; `P9` is final confirmation rather than first execution
 - before every substantive Claude turn, review the last normalized result, decide whether the next turn is a correction, continuation, resume, or new bounded objective, and compose the prompt accordingly rather than sending vague nudges
 
 ## Claude Live Bridge Discipline
@@ -441,8 +459,8 @@ All Claude developer lane launch and turn actions should go through the packaged
 
 Evaluation-prompt rule:
 
-- backend and frontend evaluation prompts may only be changed by injecting the original project prompt into `{prompt}`; otherwise send them verbatim
-- the test-coverage prompt must be sent verbatim with no additions or reductions
+- backend and frontend evaluation prompts must be prepared through `node ~/slopmachine/utils/prepare_evaluation_prompt.mjs --workspace-root .. --prompt-file <chosen-prompt-file>`, which reads parent-root `../metadata.json`, injects the real project prompt where needed, and writes the exact sendable body to a deterministic file under `../.ai/`
+- the owner must send the exact contents of that prepared file to the evaluator; on same-session reruns, prepare the file again with `--mode rerun` and then send the exact saved rerun file contents
 
 Operation map:
 
@@ -457,7 +475,7 @@ Operation map:
 - package the Claude project session folder for final delivery as one root zip bundle:
   - `node ~/slopmachine/utils/package_claude_session.mjs`
   - this resolves the tracked relevant Claude session artifacts from the tracked `session_id` values plus the project `cwd` under `~/.claude/projects/`, packages the normalized tracked transcript JSONL files together with the raw matching session directories once, and avoids sweeping unrelated random Claude sessions into the archive
-- after Claude session packaging is fully complete, stop each tracked live Claude lane with `node ~/slopmachine/utils/claude_live_stop.mjs --runtime-dir <dir>` and verify the tmux session is gone before closing `P9`
+- after Claude session packaging is fully complete, attempt to stop each tracked live Claude lane with `node ~/slopmachine/utils/claude_live_stop.mjs --runtime-dir <dir>`, but only when the bridge can prove the tmux session belongs to the current task runtime; if that check fails or the stop fails, leave the tmux session alone rather than risking another tmux instance
 
 Timeout rule: