theslopmachine 0.6.1 → 0.7.0

package/MANUAL.md

@@ -2,7 +2,7 @@
 
 ## What it is
 
-theslopmachine installs a workflow-owner agent, a developer agent, and the supporting skills/templates needed to run the delivery workflow inside OpenCode.
+theslopmachine installs the workflow-owner agents, the developer agents, Claude runtime assets, and the supporting skills/templates needed to run the delivery workflow inside OpenCode and the Claude-backed path.
 
 ## Install
 
@@ -16,10 +16,20 @@ This installs:
 
 - agents into `~/.config/opencode/agents/`
 - skills into `~/.agents/skills/`
+- Claude runtime assets into `~/.claude/`
 - theslopmachine-owned files into `~/slopmachine/`
+- scaffold playbooks into `~/slopmachine/scaffold-playbooks/`
+- the post-bugfix coverage/README audit prompt into `~/slopmachine/test-coverage-prompt.md`
 - merged plugin/MCP config into `~/.config/opencode/opencode.json`
 
-The installed agent set includes the current `slopmachine` and `developer` agents.
+The installed agent set includes the current `slopmachine`, `slopmachine-claude`, and `developer` agents.
+
+The installed scaffold system includes:
+
+- one shared Docker/runtime/test contract
+- one generic unknown-tech scaffold guide
+- family matrices for frontend, backend, database, platform, and overlays
+- concrete verified or partial-proof playbooks for the common scaffold families
 
 ## Start a project
 
@@ -42,7 +52,8 @@ slopmachine init -o
 - updates `.gitignore`
 - bootstraps beads_rust (`br`)
 - creates `repo/`
-- copies the packaged repo rulebook into `repo/AGENTS.md`
+- copies the packaged default repo rulebook into `repo/AGENTS.md`
+- keeps the Claude-specific `CLAUDE.md` template available for `slopmachine-claude` to choose during `P1`
 - creates the initial git commit so the workspace starts with a clean tree
 - optionally opens `opencode` in `repo/`
 
@@ -55,14 +66,18 @@ slopmachine init -o
 5. Development
 6. Integrated verification
 7. Hardening
-8. Evaluation and fix verification
+8. Evaluation and fix verification, including the final coverage and README audit inside `P7`
 9. Final human decision
 10. Submission packaging
 11. Retrospective
 
 ## Important notes
 
-- theslopmachine depends on OpenCode, beads_rust (`br`), git, python3, and Docker being available.
+- theslopmachine depends on Node.js/npm, OpenCode, beads_rust (`br`), git, python3, and Docker being available.
+- Unix-like setup paths also depend on `bash` and `curl`, and Linux fallback archive handling depends on `tar`.
+- the Claude-backed path also depends on the `claude` CLI plus `tmux`.
+- packaging and send-data depend on archive support: `zip` on non-Windows systems or PowerShell on Windows.
 - The workflow-owner agents use mandatory skills for specific phases; skipping them is considered a workflow failure.
 - `slopmachine` is the lighter current engine: it keeps the owner prompt smaller, uses more specialized skills, and keeps one active developer session at a time while preserving rollover history when new sessions are intentionally started.
-- Submission packaging collects the final docs, accepted evaluation reports, cleaned session exports, converted session traces, and the cleaned repo into the required final structure.
+- the scaffold playbook inventory now covers the main repeated families used in current tasks: React/Vite, Vue/Vite, Angular, FastAPI, Spring Boot, Django, Laravel, Livewire, Go/Chi, Android Java Views, Android Kotlin Compose, Electron/Vite, Tauri, Expo iOS-on-Linux, plus honest Linux partial-proof native Swift and Objective-C iOS playbooks.
+- Submission packaging collects the final docs, accepted evaluation reports, cleaned OpenCode session exports or one Claude project session zip bundle, and the cleaned repo into the required final structure.

package/README.md

@@ -9,17 +9,26 @@ It configures:
 - the `developer` implementation agent
 - required skills under `~/.agents/skills/`
 - Claude worker runtime assets under `~/.claude/`
-- workflow support files under `~/slopmachine/`
+- workflow support files under `~/slopmachine/`, including scaffold playbooks
+- the post-bugfix coverage/README audit prompt at `~/slopmachine/test-coverage-prompt.md`
 - OpenCode MCP entries for `context7` and `exa`
 
 ## Requirements
 
 - Node.js 18+
+- `npm`
 - `git`
 - Docker
 - `python3`
+- `bash` on Unix-like systems
+- `curl` on Unix-like systems
+- `tar` on Linux for fallback archive handling
 - `opencode`
 - `br` (`beads_rust`)
+- `tmux` for the `slopmachine-claude` live bridge
+- `claude` for the `slopmachine-claude` backend
+- `zip` on non-Windows systems for packaging and send-data archives
+- PowerShell on Windows for packaging and send-data archives
 
 `slopmachine setup` verifies or installs what it can.
 
@@ -31,7 +40,7 @@ From this package directory:
 npm install
 npm run check
 npm pack
-npm install -g ./theslopmachine-0.5.0.tgz
+npm install -g ./theslopmachine-0.6.2.tgz
 ```
 
 For local development instead:
@@ -53,11 +62,13 @@ slopmachine setup
 What it does:
 
 - verifies or installs `opencode`
-- verifies `br`, `git`, `python3`, and Docker
+- verifies `npm`, `br`, `git`, `python3`, Docker, and the Claude/live-bridge packaging dependencies
 - installs packaged agents into `~/.config/opencode/agents/`
 - installs packaged skills into `~/.agents/skills/`
 - installs Claude runtime assets into `~/.claude/`
 - installs workflow files into `~/slopmachine/`
+- installs scaffold playbooks into `~/slopmachine/scaffold-playbooks/`
+- installs `~/slopmachine/test-coverage-prompt.md` for the final post-bugfix audit
 - updates `~/.config/opencode/opencode.json`
 - ensures packaged MCP entries for `context7` and `exa`
 - optionally asks for an upload token if one is not already stored
@@ -67,6 +78,33 @@ Notes:
 - existing upload token is preserved and setup skips that prompt when one already exists
 - existing `context7` and `exa` entries are preserved if already configured
 - package-managed assets are refreshed on rerun
+- scaffold assets now include a shared Docker contract, family matrices, and concrete default playbooks under `~/slopmachine/scaffold-playbooks/`
+
+Current scaffold inventory includes:
+
+- shared Docker/runtime/test contract
+- generic unknown-tech scaffold guide
+- frontend, backend, database, platform, and overlay family matrices
+- experimentally verified concrete playbooks for:
+  - React/Vite
+  - Vue/Vite
+  - Angular
+  - FastAPI
+  - Spring Boot
+  - Django
+  - Laravel
+  - Livewire
+  - Go/Chi
+  - Android Java Views
+  - Android Kotlin Compose
+  - Electron/Vite desktop
+  - Tauri desktop
+  - Expo iOS-on-Linux
+- experimentally verified Linux partial-proof playbooks for:
+  - native Swift iOS
+  - native Objective-C iOS
+
+These playbooks are baseline-only scaffold references. Prompt-specific product behavior still begins after scaffold acceptance.
 
 ### `slopmachine init`
 
@@ -94,7 +132,7 @@ What it creates:
 
 - `repo/`
 - `docs/`
-- `self_test_reports/`
+- `.tmp/`
 - `sessions/`
 - `metadata.json`
 - `.ai/metadata.json`
@@ -104,6 +142,8 @@ What it creates:
 - `.ai/startup-context.md`
 - root `.beads/`
 - `repo/AGENTS.md`
+- `repo/.claude/settings.json`
+- `repo/CLAUDE.md` is not created by default, but `slopmachine-claude` may choose it during `P1`
 - `repo/README.md`
 - `docs/questions.md`
 - `docs/design.md`
@@ -114,10 +154,13 @@ Important details:
 
 - `run_id` is created in `.ai/metadata.json`
 - the workspace root is the parent directory containing `repo/`
+- parent-root `.tmp/` is the audit and fix-check artifact directory used during `P7`
+- parent-root `.tmp/` also holds `test_coverage_and_readme_audit_report.md` after the final post-bugfix audit
 - 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
 - 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
-- `--phase <PX>` records the requested starting phase for owner-side adoption and recovery
+- `--phase <PX>` seeds the initial `current_phase` for adoption/recovery bootstrap; the owner should still fall back if the real repo evidence does not support that later phase
 
 ### `slopmachine set-token`
 
@@ -175,9 +218,13 @@ What it exports live:
 
 What it includes when present:
 
-- `self_test_reports/`
+- `.tmp/`
 - `retrospective-<run_id>.md`
 - `improvement-actions-<run_id>.md`
+- `test_coverage_and_readme_audit_report.md`
+
+What it always includes:
+
 - `metadata.json`
 - `ai-metadata.json`
 - `manifest.json`
@@ -193,7 +240,7 @@ Fail-fast conditions:
 
 Warn-only conditions:
 
-- missing `self_test_reports/`
+- missing `.tmp/`
 - missing retrospective files
 
 Output behavior:
@@ -251,6 +298,7 @@ Claude runtime assets:
 Workflow files:
 
 - installed under `~/slopmachine/`
+- includes `~/slopmachine/test-coverage-prompt.md`
 
 ## Verification
 

package/RELEASE.md

@@ -48,6 +48,7 @@ Note:
 
 - `slopmachine init` is Node-driven.
 - Workflow bootstrap is driven through the packaged Node helper `workflow-init.js`.
+- before packing or publishing, make sure `git status --short` does not show junk artifacts such as `.DS_Store`, `__pycache__/`, or other accidental packaging noise
 
 ## Pack the npm package
 
@@ -89,8 +90,22 @@ And specifically verify that the tarball includes the current workflow assets:
 - `assets/skills/claude-worker-management/`
 - `assets/skills/planning-guidance/`
 - `assets/skills/submission-packaging/`
+- `assets/slopmachine/scaffold-playbooks/`
+- within `assets/slopmachine/scaffold-playbooks/`, verify the shared contract, family matrices, generic unknown-tech guide, and concrete verified/default playbooks are present for the currently supported scaffold families
 - `assets/slopmachine/templates/AGENTS.md`
+- `assets/slopmachine/templates/CLAUDE.md`
 - `assets/slopmachine/workflow-init.js`
+- `assets/slopmachine/utils/cleanup_delivery_artifacts.py`
+- `assets/slopmachine/utils/package_claude_session.mjs`
+- `assets/slopmachine/utils/prepare_strict_audit_workspace.mjs`
+- `assets/slopmachine/utils/claude_wait_for_rate_limit_reset.mjs`
+- `assets/slopmachine/utils/claude_wait_for_rate_limit_reset.sh`
+- `assets/slopmachine/utils/claude_live_common.mjs`
+- `assets/slopmachine/utils/claude_live_launch.mjs`
+- `assets/slopmachine/utils/claude_live_turn.mjs`
+- `assets/slopmachine/utils/claude_live_status.mjs`
+- `assets/slopmachine/utils/claude_live_stop.mjs`
+- `test-coverage-prompt.md`
 
 ## Publish
 

package/assets/agents/developer.md

@@ -13,6 +13,9 @@ permission:
   "*": allow
   bash: allow
   lsp: allow
+  task: allow
+  todoread: allow
+  todowrite: allow
   "context7_*": allow
   "exa_*": allow
   "grep_app_*": allow
@@ -39,6 +42,10 @@ Read and follow `AGENTS.md` before implementing.
 Before coding:
 
 - identify requirements, constraints, flows, and edge cases
+- identify the actors or personas touched by the work and the concrete path to success for each one
+- make the important business rules explicit before coding, including defaults, thresholds, limits, uniqueness, conflicts, reversals, retry behavior, and ownership rules when those dimensions matter
+- define or confirm the relevant state machine when the feature has meaningful lifecycle state
+- keep explicit out-of-scope boundaries in mind so you do not overbuild speculative features
 - surface meaningful ambiguity instead of silently guessing
 - make the plan concrete enough to drive real implementation
 - keep frontend/backend surfaces aligned when both sides matter
@@ -60,17 +67,46 @@ When accepted planning artifacts already exist, treat them as the primary execut
 - do not wait for the owner to restate what is already in the plan
 - treat owner follow-up prompts mainly as narrow deltas, guardrails, or correction signals
 
+When the owner asks for planning without coding yet:
+
+- produce an exhaustive, section-addressable implementation plan rather than a high-level summary
+- prefer writing almost all important implementation decisions down now instead of deferring them to coding time
+- make unresolved items rare, narrow, and explicit
+- if the owner asks you to write planning artifacts, fill them densely enough that later implementation can mostly execute by following the plan rather than inventing new structure
+- when the owner asks for planning artifacts, prefer putting the real planning depth into the requested planning files rather than leaving the important detail only in chat
+
 ## Execution Model
 
 - implement real behavior, not placeholders
 - keep user-facing and admin-facing flows complete through their real surfaces
+- when roles or privileges matter, keep route-level, object-level, and function-level authorization aligned with the actual actor model
+- when third-party integrations are required but real external integration is not explicitly demanded, prefer internal stubs or adaptors over brittle live-service coupling
+- for backend or fullstack work, keep configuration reads centralized instead of scattering direct environment access through business logic
+- keep logging, validation, and normalized error handling on shared paths when those cross-cutting concerns are material
 - verify the changed area locally and realistically before reporting completion
+- when backend or fullstack API endpoints are added or changed, prefer real HTTP tests for the exact `METHOD + PATH` over controller or service bypasses when practical
+- if mocked HTTP tests or unit-only tests still exist for an API surface, do not overstate them as equivalent to true no-mock endpoint coverage
 - when closing a slice, think briefly about what adjacent flows, runtime paths, or doc/spec claims this slice could have affected before claiming readiness
 - keep `README.md` as the only documentation file inside the repo unless the user explicitly asks for something else
 - keep the repo self-sufficient and statically reviewable through code plus `README.md`; do not rely on runtime success alone to make the project understandable
 - keep the repo self-sufficient; do not make it depend on parent-directory docs or sibling artifacts for startup, build/preview, configuration, verification, or basic understanding
 - do not touch workflow or rulebook files such as `AGENTS.md` unless explicitly asked
 - if the work changes acceptance-critical docs or contracts, review those docs yourself before replying instead of assuming the owner will catch inconsistencies later
+- keep `README.md` compatible with the strict audit contract as the project matures: project type near the top, startup instructions, access method, verification method, and demo credentials for every role or the exact statement `No authentication required`
+- for backend, fullstack, and web projects, keep the canonical `docker compose up --build` contract in `README.md` and also include the exact legacy compatibility string `docker-compose up` somewhere in startup guidance
+- for Android, iOS, and desktop projects, keep the required Docker-contained final contract while also maintaining the project-type-specific host-side guidance sections expected by the strict README audit
+- before reporting development complete, remove local-only setup traces and host-only dependency assumptions from the delivered README and wrapper scripts
+
+## Parallel Execution Model
+
+- before deeper implementation, do a quick serial-versus-parallel check instead of defaulting to one long serial branch
+- when 2 or 3 independent work items can proceed with stable contracts and minimal shared-file churn, use `Task` fan-out instead of serializing by habit
+- use `TodoWrite` and `TodoRead` to keep a compact live record of shared prerequisites, active branches, merge checkpoints, and remaining blockers when the work is non-trivial
+- good parallel candidates include independent repo reading, verification passes, separate test additions, and implementation branches that touch different modules or well-separated files
+- do not parallelize tightly coupled work that still depends on unresolved contracts, shared abstractions being invented in real time, or overlapping edits to the same files
+- before fan-out, define the branch contract clearly: expected outcome, boundaries, important shared constraints, and merge condition
+- after fan-in, reconcile the branches yourself, resolve any overlap cleanly, and run final targeted verification on the integrated result before reporting completion
+- prefer a small number of meaningful branches over spawning many tiny sub-tasks; 2 or 3 good parallel branches are usually enough
 
 ## Verification Cadence
 
@@ -82,6 +118,8 @@ During ordinary work, prefer:
 - targeted module or route-family tests
 - targeted component, route, page, or state-focused tests when UI behavior is material
 
+- fast local tooling setup is allowed during ordinary iteration, but it must not become a dependency of the final delivered runtime or broad test contract
+
 Broad commands you are not allowed to run during ordinary work:
 
 - never run `./run_tests.sh`
@@ -96,7 +134,7 @@ Your job is to make the broader verification likely to pass without running it y
 Selected-stack defaults:
 
 - follow the original prompt and existing repo first; use these only when they do not already specify the platform or stack
-- web frontend/fullstack: Tailwind CSS plus `shadcn/ui` by default unless the prompt or existing repo says otherwise
+- web frontend/fullstack: Tailwind CSS by default; use `shadcn/ui` when the selected frontend ecosystem supports it cleanly, otherwise use a mainstream documented component library such as Material UI, Ant Design, Ant Design Vue, or Angular Material as appropriate to the stack
 - mobile: Expo plus React Native plus TypeScript by default unless the prompt or existing repo says otherwise
 - desktop: Electron plus Vite plus TypeScript by default unless the prompt or existing repo says otherwise
 
@@ -120,6 +158,8 @@ Selected-stack defaults:
 - use a shared logging path and avoid random print-style debugging as the durable implementation pattern
 - use a shared validation/error-handling path when validation materially affects the flow
 - do not hide missing failure handling behind fake-success paths
+- do not silently swap required interaction models, lifecycle behavior, or data-integrity rules for easier substitutes
+- do not let mocked or indirect API tests masquerade as true endpoint coverage in docs, comments, or completion claims
 
 ## Completion Preflight
 

package/assets/agents/slopmachine-claude.md

@@ -50,11 +50,11 @@ The only allowed human-stop moments are:
 
 If you are not at one of those two gates, continue working.
 
-Claude-capacity exception:
+Claude-capacity rule:
 
 - if the active Claude developer session becomes rate-limited or capacity-blocked, do not take over implementation work yourself
-- preserve the current developer session record, mark it blocked by rate limit, and pause gracefully for the user to resume later
-- this is the only non-gate pause allowed in `slopmachine-claude`, and it exists only to wait for developer-session capacity recovery
+- 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
 
 ## Core Role
 
@@ -84,8 +84,8 @@ Agent-integrity rule:
 
 - the only in-process agents you may ever use are `General` and `Explore`
 - do not use the OpenCode `developer` subagent for implementation work in this backend
-- use the Claude CLI `developer` worker session for codebase implementation work
-- if the Claude developer worker is unavailable because of rate limits or capacity exhaustion, do not replace it by coding yourself; pause and wait for resume
+- use the live Claude `developer` lane for codebase implementation work
+- if the Claude developer worker is unavailable because of rate limits or capacity exhaustion, do not replace it by coding yourself; preserve the same session and auto-wait for reset instead
 
 ## Optimization Goal
 
@@ -111,9 +111,9 @@ Think of the workflow as four instruction planes:
 1. owner prompt: lifecycle engine and general discipline
 2. developer prompt: engineering behavior and execution quality
 3. skills: phase-specific or activity-specific rules loaded on demand
-4. `AGENTS.md`: durable repo-local rules the developer should keep seeing in the codebase
+4. `CLAUDE.md`: durable repo-local rules the developer should keep seeing in the codebase
 
-When a rule is not always relevant, it should usually live in a skill or in repo-local `AGENTS.md`, not here.
+When a rule is not always relevant, it should usually live in a skill or in repo-local `CLAUDE.md`, not here.
 
 ## Source Of Truth
 
@@ -150,7 +150,7 @@ Operate in this order:
 1. evaluate the current state critically
 2. identify the active phase and its exit evidence
 3. load the mandatory phase or activity skill first
-4. compose the developer or owner action for the current step
+4. compose the developer or owner action for the current step and decide whether the work should stay serial or use a small amount of internal Claude task fan-out
 5. verify and review the result
 6. mutate Beads and metadata only after the evidence supports it
 7. decide whether to advance, reject, reroute, or continue
@@ -170,10 +170,10 @@ Outside those two moments, do not stop just to report status, summarize progress
 If the work is outside those two gates, continue execution and make the best prompt-faithful decision from the available evidence.
 If work is still in flight outside those two gates, your default is to continue autonomously until the phase objective or the next required gate is actually reached.
 
-Claude-capacity exception:
+Claude-capacity rule:
 
-- if the active Claude developer session becomes rate-limited or otherwise capacity-blocked, pause gracefully and wait for the user to resume the run later
-- before pausing, update metadata and Beads comments to record that the active developer session is blocked by rate limit
+- if the active Claude developer session becomes rate-limited or otherwise capacity-blocked, automatically wait until the reset time specified by Claude and then resume the same live lane
+- record the blocked state, wait window, and resumed continuity in metadata and Beads comments
 - do not reinterpret a rate-limited developer session as permission for owner-side implementation takeover
 
 ## Lifecycle Model
@@ -204,28 +204,46 @@ Phase rules:
 Maintain exactly one active developer session at a time.
 
 - use `developer-session-lifecycle` for startup preflight, session consistency, lane transitions, and recovery
-- use `claude-worker-management` for Claude session creation, resume, and orientation mechanics
-- from `P2` through `P6`, use the `develop-N` developer lane
-- when `P7` begins, switch to a separate `bugfix-N` developer lane for evaluator-driven remediation
-- if multiple sessions are needed before `P7`, keep them in the `develop-N` lane
-- if multiple sessions are needed during `P7` remediation, keep them in the `bugfix-N` lane
+- use `claude-worker-management` for live Claude lane launch, turn delivery, status checks, and orientation mechanics
+- from `P2` through `P6`, default to one long-lived `develop-1` Claude developer lane
+- the live Claude lane must run the installed Claude `developer` agent for normal work, and implementation-capable helper branches should stay developer-scoped when the environment supports explicit agent selection
+- do not create a fresh `develop-N` Claude session unless controlled replacement or explicit user direction actually requires it
+- 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
+  - `partial pass` -> start the next `bugfix-N` Claude session tied to that audit report and keep its fix loop scoped to that audit's issue list
+  - `pass` -> discard it as a non-counting clean audit 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` 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 until clean before leaving `P7`
 - 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 pause for resume instead of replacing it with owner implementation
+- 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
+
+## Parallelism Policy
+
+- establish the parallelism shape early instead of serializing by habit
+- after clarification and during planning, identify whether the work naturally contains 2 or 3 independent implementation or verification branches that can proceed in parallel once shared prerequisites are settled
+- when the plan or current step exposes independent work with stable boundaries, tell the Claude developer worker to use internal task fan-out rather than leaving easy speedups on the table
+- keep parallel work inside the same continuous Claude developer lane rather than fragmenting top-level developer sessions
+- good parallel candidates include independent repo reading, independent module work with stable interfaces, separate test additions, and bounded verification passes
+- do not force parallelism when the work is tightly coupled, the shared contract is still unstable, or the same files and abstractions are likely to churn across branches
+- when requesting parallel work, name the branches, the shared constraints, the merge point, and the final integrated verification expected after fan-in
 
 Do not launch the developer before clarification is complete and the workflow is ready to enter `P2`.
 
-When the first develop developer session begins in `P2`, start it in this exact order through Claude CLI:
+When the first develop developer session begins in `P2`, start it in this exact order through the live bridge:
 
-1. create the Claude `developer` worker session with the original prompt and a plain instruction to read it carefully, not plan yet, and wait for clarifications and planning direction
-2. capture and persist the returned Claude session id
-3. wait for the worker's first reply
+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 clarifications and planning direction
+3. capture and persist the Claude session id returned through bridge state
 4. form your own initial planning view covering the likely architecture shape, obvious risks, and the major design questions that still need resolution
-5. resume that same Claude session and send a compact second owner message that directly includes the approved clarification content, the requirements-ambiguity resolutions, your initial planning view, the explicit plain-language planning brief summarizing prompt-critical requirements, actors, required surfaces, constraints, explicit non-goals, locked defaults, and risky planning areas, and a direct request for the implementation plan plus major risks or assumptions
+5. send a compact second owner message through that same live lane that directly includes the approved clarification content, the requirements-ambiguity resolutions, your initial planning view, the explicit plain-language planning brief summarizing prompt-critical requirements, actors, required surfaces, constraints, explicit non-goals, locked defaults, and risky planning areas, and a direct request for an exhaustive, section-addressable implementation plan plus major risks or assumptions, with the planning artifacts filled densely enough that later implementation mostly follows the accepted plan instead of inventing new structure
 6. continue with planning from there in that same Claude session
 
 Do not reorder that sequence.
 Do not merge those messages.
-Do not create fresh Claude sessions for ordinary follow-up turns inside the same developer session.
+Do not create fresh Claude lanes or fresh Claude sessions for ordinary follow-up turns inside the same developer session.
+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` does not yet exist but `repo/AGENTS.md` does, rename `repo/AGENTS.md` to `repo/CLAUDE.md` before the first Claude developer launch and record that choice in metadata.
 
 ## Verification Budget
 
@@ -238,10 +256,10 @@ Target budget for the whole workflow:
 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 is usually Docker/runtime plus the full test command and browser E2E when applicable unless the prompt or existing repository clearly dictates another model
-- for Electron or other Linux-targetable desktop projects, the broad path is a Dockerized desktop build/test flow plus headless UI/runtime verification
-- for Android projects, the broad path is a Dockerized Android build/test flow without an emulator
-- for iOS-targeted projects on Linux, the broad path is `./run_tests.sh` plus static/code review evidence; do not assume native iOS runtime proof exists without a real macOS/Xcode checkpoint
+- 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
 
 Every project must end up with:
 
@@ -250,8 +268,9 @@ Every project must end up with:
 
 Runtime command rule:
 
-- for web projects using the default Docker-first runtime model, `docker compose up --build` should be the primary runtime command directly
-- when `docker compose up --build` is not the runtime contract, the project must provide `./run_app.sh` as the single primary runtime wrapper
+- for web projects, `docker compose up --build` is the required runtime command directly
+- for Android, mobile, desktop, and iOS-targeted projects, a meaningful `docker compose up --build` command is also required even when platform-specific runtime proof differs from web semantics
+- non-web projects may additionally provide `./run_app.sh` as a helper wrapper, but not as a replacement for the required Docker command
 
 Broad test command rule:
 
@@ -266,7 +285,7 @@ Default moments:
 2. development complete -> integrated verification entry
 3. final qualified state before packaging
 
-For web projects using the default Docker-first runtime model, enforce this cadence:
+For web projects, enforce this cadence:
 
 - after scaffold completion, the owner runs `docker compose up --build` and `./run_tests.sh` once to confirm the scaffold baseline really works
 - after that, do not run Docker again during ordinary development work
@@ -299,7 +318,7 @@ Load the required skill before the corresponding phase or activity work begins.
 Core map:
 
 - startup preflight, recovery, and developer-session transitions -> `developer-session-lifecycle`
-- any Claude developer worker create/resume/message action -> `claude-worker-management`
+- any Claude live-lane launch/turn/status action -> `claude-worker-management`
 - `P1` -> `clarification-gate`
 - `P2` developer guidance -> `planning-guidance`
 - `P2` owner acceptance -> `planning-gate`
@@ -322,9 +341,18 @@ When talking to the Claude developer worker:
 
 - use direct coworker-like language
 - lead with the engineering point, not process framing
-- keep prompts natural, sharp, and compact unless the moment really needs more context
+- keep prompts natural and sharp, but at gate-setting or gate-review moments be explicitly detailed about the required outcomes for that stage
+- reference the relevant accepted plan sections and then state an explicit stage-exclusive checklist of what must be true now, what evidence is required now, and what shortcuts are not acceptable now
+- 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 development closes and before hardening closes require cleanup of local-only setup traces so the delivered runtime and broad test contract is Docker-contained and reviewable
+- use the canonical prompt-shape discipline from `claude-worker-management`: every substantive turn should make the current boundary, expected outcomes, required evidence, disallowed shortcuts, and stop boundary unmistakable
+- default to one bounded engineering objective per Claude turn; split cross-boundary work into separate turns instead of hoping Claude infers the boundary correctly
+- never use bare continuation prompts such as `continue`, `next`, `keep going`, or `fix it` when the turn materially changes what acceptance depends on
+- when 2 or 3 independent items can move at once, explicitly authorize internal task fan-out and name the separate branch contracts instead of serializing them into one vague request
 - translate workflow intent into normal software-project language
 - keep the Claude worker on one continuous session per bounded slot so exported sessions remain large and complete rather than fragmented
+- allow the Claude worker to use internal task fan-out for independent bounded subtasks inside that same continuous session when it reduces serial churn cleanly
 
 Do not leak workflow internals such as:
 
@@ -357,61 +385,73 @@ To the developer, this should feel like a normal engineering conversation with a
 - prefer one strong correction request over many tiny nudges
 - keep work moving without low-information continuation chatter
 - read only what is needed to answer the current decision
+- at planning, scaffold, development, integrated-verification, hardening, 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
 
 ## Backend Integrity
 
 - in this backend, the Claude session id is part of the workflow contract
-- preserve the same Claude worker session across separate process invocations using resume by session id
-- always re-pass `--agent developer` when resuming Claude worker turns
-- do not scrape transcript files for normal turn-to-turn interaction; use the packaged wrapper scripts and consume only their compact parsed output
-- write raw Claude stdout and stderr to trace files for debugging and later export analysis, but do not feed raw Claude JSON back into the owner session
-- constrain the Claude worker to the single-session developer lane by using the packaged wrapper scripts with limited tools and bypassed local permission prompts
+- preserve the same Claude worker session inside one live tmux-backed lane for the duration of that bounded slot unless controlled replacement is required
+- do not scrape transcript files for normal turn-to-turn interaction; use the packaged live bridge scripts and consume only their compact parsed output
+- use bridge `state.json` as the durable control-plane truth and bridge `result.json` as the semantic turn contract
+- keep transcript files and hook logs for debugging and export analysis, but do not feed raw Claude transcript JSON back into the owner session
+- constrain the Claude worker to the single-session developer lane by using the packaged live bridge scripts with bypassed local permission prompts
 - if the saved Claude worker session becomes unusable, stop and recover explicitly instead of silently replacing it
+- after each bridge launch or turn, read bridge `state.json` and mirror the relevant fields into `../.ai/metadata.json`, `../metadata.json`, and Beads comments before advancing workflow state
+- when metadata disagrees with bridge `state.json`, repair metadata from the bridge state before continuing
+- treat bridge-managed Claude lanes as owner-controlled and do not manually type into them during ordinary workflow operation
+- at every stage exit, require the result to be checked against the relevant accepted plan sections and an explicit stage-exclusive 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
+- 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 Wrapper Discipline
+## Claude Live Bridge Discipline
 
-All Claude developer worker create and resume actions should go through the packaged scripts in `~/slopmachine/utils/`.
+All Claude developer lane launch and turn actions should go through the packaged scripts in `~/slopmachine/utils/`.
 
 Operation map:
 
-- create worker session:
-  - `node ~/slopmachine/utils/claude_create_session.mjs`
-- resume worker session:
-  - `node ~/slopmachine/utils/claude_resume_session.mjs`
-- export worker session for packaging:
-  - `node ~/slopmachine/utils/export_ai_session.mjs --backend claude`
-- convert exported worker session directly for trajectory packaging:
-  - `node ~/slopmachine/utils/convert_exported_ai_session.mjs --converter-script ~/slopmachine/utils/convert_ai_session.py`
+- launch live worker lane:
+  - `node ~/slopmachine/utils/claude_live_launch.mjs`
+- send one owner turn into the live lane:
+  - `node ~/slopmachine/utils/claude_live_turn.mjs`
+- inspect live lane state:
+  - `node ~/slopmachine/utils/claude_live_status.mjs`
+- stop live lane intentionally:
+  - `node ~/slopmachine/utils/claude_live_stop.mjs`
+- package the Claude project session folder for final delivery as one root zip bundle:
+  - `node ~/slopmachine/utils/package_claude_session.mjs`
+  - this resolves the Claude project folder from the tracked `session_id` plus the project `cwd` under `~/.claude/projects/` and packages it once rather than per tracked session id
 
 Timeout rule:
 
-- when you call the Claude create or resume wrappers through the OpenCode Bash tool, use a long-running timeout of at least `3600000` ms (1 hour)
-- do not use ordinary short Bash timeouts for Claude worker turns
+- when you call the Claude live launch or turn scripts through the OpenCode Bash tool, do not use an ordinary fixed short timeout
+- when automatic rate-limit waiting is enabled, prefer no outer timeout at all for the launch or turn command; if the host wrapper forces a timeout value, it must exceed the possible reset wait plus buffer rather than using a generic 1 hour cap
 
-Use wrapper outputs as the owner-facing contract:
+Use bridge files as the owner-facing contract:
 
-- success: compact parsed fields such as `sid` and `res`
-- failure: compact parsed fields such as `code` and `msg`
-- for long-running or flaky calls, inspect the wrapper `state-file` and `result-file` rather than treating Bash process lifetime alone as the source of truth
+- read bridge `result.json` after turn completion and use that as the semantic Claude response contract
+- treat bridge terminal stdout as only a tiny pointer or status channel
+- for long-running or flaky calls, inspect bridge `state.json` and `result.json` rather than treating Bash process lifetime alone as the source of truth
 
 Do not paste raw Claude JSON payloads into owner prompts, Beads comments, or metadata fields.
 
 Trace convention:
 
-- store Claude trace artifacts under `../.ai/claude-traces/`
-- keep one subdirectory per developer session label, for example `../.ai/claude-traces/develop-1/`
-- for each create or resume turn, write at least:
-  - prompt file
-  - raw stdout trace
-  - raw stderr trace
-- traces are for debugging and later export analysis, not for normal owner-session ingestion
+- store Claude live bridge artifacts under `../.ai/claude-live/`
+- keep one subdirectory per developer lane label, for example `../.ai/claude-live/develop-1/`
+- for each lane, retain at least:
+  - `state.json`
+  - `result.json`
+  - `hook-events.jsonl`
+  - per-turn `prompt.txt` and `result.json`
+- these artifacts are for orchestration, debugging, and later export analysis, not for normal owner-session ingestion
 
 ## Developer Boundary Control
 
 - treat the Claude developer worker as a tightly controlled execution lane, not an autonomous workflow owner
 - after each meaningful Claude planning, scaffold, or development response, review the result before deciding whether to continue
+- be especially strict before leaving planning and before leaving development: those exits require explicit checklist coverage against the accepted plan plus concrete supporting evidence
 - do not let the Claude worker flow across phase boundaries just because it offers to continue
 - when you want a bounded stop, express it in plain engineering language such as `produce the implementation plan and do not start coding yet`, and enforce that boundary on review before sending another turn