theslopmachine 0.4.3 → 0.4.5

package/MANUAL.md

@@ -63,5 +63,5 @@ slopmachine init -o
 
 - theslopmachine depends on OpenCode, beads_rust (`br`), git, python3, and Docker being available.
 - 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 uses up to three bounded developer sessions instead of one long-lived session.
-- Submission packaging collects the final docs, reports, screenshots, session export, trajectory, and cleaned repo into the required final structure.
+- `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, screenshots, cleaned session exports, converted session traces, and cleaned repo into the required final structure.

package/README.md

@@ -1,59 +1,32 @@
 # theslopmachine
 
-Installer package for the theslopmachine workflow owner, developer agents, required skills, templates, and local support files.
+`theslopmachine` installs the SlopMachine owner/developer workflow into OpenCode, sets up the required support files on your machine, and bootstraps new project workspaces.
 
-## What This Package Installs
+**Quickstart**
 
-`slopmachine setup` installs the current workflow assets.
+This is the full machine-to-project flow:
 
-That includes:
-
-- owner agents under `~/.config/opencode/agents/`
-- required skills under `~/.agents/skills/`
-- packaged workflow files under `~/slopmachine/`
-- repo templates, evaluation prompts, bootstrap helpers, and session export utilities
-
-The canonical package documents in `~/slopmachine/` are:
-
-- `backend-evaluation-prompt.md`
-- `frontend-evaluation-prompt.md`
-- `document-completeness.md`
-- `engineering-results.md`
-- `implementation-comparison.md`
-- `quality-document.md`
-
-Usage split:
-
-- the two evaluation prompt files are used exactly in evaluation runs
-- the other four files are used in the submission packaging phase
-
-Installed agent set:
-
-- `slopmachine.md`
-- `developer.md`
-
-The current engine is the lighter workflow line:
-
-- smaller always-loaded owner shell
-- smaller developer rulebook
-- richer phase-specific skills loaded when needed
-- bounded 2-session developer-session model
-- `beads_rust` bootstrap path
+1. install the package
+2. run `slopmachine setup`
+3. add MCP API keys if prompted
+4. log into Codex with OpenCode
+5. initialize a project workspace
+6. enter `repo/`
+7. start OpenCode and choose the `slopmachine` agent
 
 ## Requirements
 
 - Node.js 18+
-- OpenCode installed and usable on the machine
-- `br` (`beads_rust`) will be installed or verified during setup
-- git available in the shell
+- `git`
+- Docker running on the machine
+- `curl` on Unix-like systems for automatic `br` install
 
-## Commands
+`slopmachine setup` can install or verify:
 
-- `slopmachine setup` - configures agents, files, scripts, and beads_rust (`br`)
-- `slopmachine init` - sets up a project
-- `slopmachine init -o` to bootstrap the project and immediately open OpenCode inside `repo/`
+- `opencode`
+- `br` (`beads_rust`)
 
-## Installation
+## 1. Install The Package
 
 From this package directory:
 
@@ -63,206 +36,197 @@ npm run check
 npm pack
 ```
 
-This produces a tarball such as:
+That produces a tarball such as:
 
 ```bash
-theslopmachine-0.4.3.tgz
+theslopmachine-0.4.5.tgz
 ```
 
-You can then install it globally with:
+Install it globally:
 
 ```bash
-npm install -g ./theslopmachine-0.4.3.tgz
+npm install -g ./theslopmachine-0.4.5.tgz
 ```
 
-For local development instead of global install:
+For local package development instead:
 
 ```bash
 npm link
 ```
 
-## Initial Setup
+## 2. Run Setup
 
-Run once per machine or whenever you want to refresh the packaged assets:
+Run this once per machine, or rerun it any time you want to refresh packaged assets:
 
 ```bash
 slopmachine setup
 ```
 
-What setup does:
+`setup` does the following:
 
-- installs or refreshes the packaged agents
-- installs or refreshes the packaged skills
-- installs packaged workflow files into `~/slopmachine/`
-- merges required OpenCode plugin/MCP configuration
-- installs or verifies `br` (`beads_rust`)
+- installs or verifies `git`, `python3`, `opencode`, `br`, and Docker availability
+- installs the packaged OpenCode agents into `~/.config/opencode/agents/`
+- installs the packaged skills into `~/.agents/skills/`
+- installs workflow support files into `~/slopmachine/`
+- updates `~/.config/opencode/opencode.json`
+- prompts for missing Context7 and Exa MCP API keys
 
-## Project Bootstrap
+If `setup` installs `opencode` for the first time, open a fresh terminal before running `opencode` commands.
 
-Create a new project root:
+## 3. Get MCP API Keys
 
-```bash
-mkdir my-project
-cd my-project
-slopmachine init
-```
+During `slopmachine setup`, you may be prompted for:
 
-This creates the expected structure, including:
+- Context7: `https://context7.com`
+- Exa: `https://exa.ai`
 
-- `repo/` as the working codebase directory
-- parent-root workflow files such as `metadata.json`
-- parent-root `docs/` and `sessions/`
-- repo-local `AGENTS.md`
-- initialized `beads_rust` state
-- an initial git checkpoint
-
-To bootstrap and open OpenCode directly in `repo/`:
+You can leave either blank and add it later by editing:
 
 ```bash
-slopmachine init -o
+~/.config/opencode/opencode.json
 ```
 
-## Recommended Operation
-
-After init:
-
-1. open OpenCode in `repo/`
-2. choose the `slopmachine` owner agent
-3. let the owner run the lifecycle using the packaged skills
-4. let the owner delegate implementation work to `developer`
+If `context7` or `exa` is already configured in `opencode.json`, `setup` leaves the existing entries in place.
 
-The expected high-level lifecycle is:
+## 4. Log Into Codex With OpenCode
 
-1. clarification
-2. planning
-3. scaffold
-4. development
-5. integrated verification
-6. hardening
-7. evaluation and triage
-8. final human decision
-9. remediation when needed
-10. submission packaging
-11. retrospective
+Authenticate OpenCode against Codex:
 
-## How It Is Intended To Operate
-
-`slopmachine` is designed to keep the owner prompt light while moving the important operational detail into loaded skills.
+```bash
+opencode auth login -p codex
+```
 
-That means:
+Optional check:
 
-- the owner shell stays small
-- planning, scaffold, development, verification, hardening, remediation, and packaging load detailed skills only when needed
-- early and late phases do not carry each other's full instruction payloads all the time
+```bash
+opencode auth list
+```
 
-The current workflow also expects:
+## 5. Initialize A Project Workspace
 
-- targeted reads over broad rereads
-- local and narrow verification during ordinary iteration
-- broad selected-stack owner-run gates used sparingly
-- no `.env` files in the repo
-- real integration evidence, not mocked API integration tests
+Create a new workspace directory and bootstrap it:
 
-Every bootstrapped project should expose:
+```bash
+mkdir my-project
+cd my-project
+slopmachine init
+```
 
-- one primary documented runtime command
-- one primary documented broad test command: `./run_tests.sh`
+This creates:
 
-Follow the original prompt and the existing repository first. Use the examples below only when they do not already specify the platform or stack.
+- `repo/` for the actual codebase work
+- parent-level workflow files such as `metadata.json` and `.ai/metadata.json`
+- parent-level `docs/` and `sessions/`
+- `repo/AGENTS.md`
+- initialized `br` state
+- an initial git commit
 
-Examples:
+If you want `init` to open OpenCode automatically in `repo/`, use:
 
-- web backend/fullstack: `docker compose up --build` and `./run_tests.sh`
-- mobile or desktop when Docker runtime is not the direct run path: `./run_app.sh` and `./run_tests.sh`
+```bash
+slopmachine init -o
+```
 
-## What It Does Well
+## 6. Enter `repo/`
 
-- keeps the owner shell strict without carrying a giant monolith prompt
-- loads detailed phase and activity skills only when they are actually needed
-- uses a bounded 2-session model to reduce long-run context drag
-- pushes prompt-fit, security, testing, and engineering-quality concerns earlier into planning and hardening
-- standardizes runtime and broad-test expectations with `docker compose up --build` or `./run_app.sh` plus `./run_tests.sh`
-- preserves strong packaging/report discipline with canonical files in `~/slopmachine/`
+If you used plain `slopmachine init`, move into the working repository:
 
-## Installed Assets
+```bash
+cd repo
+```
 
-The package installs:
+## 7. Start OpenCode
 
-- owner and developer agents
-- phase and activity skills
-- canonical evaluation and report templates in `~/slopmachine/`
-- workflow bootstrap helper
-- repo rulebook template
-- session export utilities
+Start OpenCode inside `repo/`:
 
-Canonical files in `~/slopmachine/`:
+```bash
+opencode
+```
 
-- `backend-evaluation-prompt.md`
-- `frontend-evaluation-prompt.md`
-- `document-completeness.md`
-- `engineering-results.md`
-- `implementation-comparison.md`
-- `quality-document.md`
-- `retrospectives/`
+Then select the `slopmachine` agent and begin the workflow.
 
-## Dependencies And Assumptions
+The normal operating split is:
 
-- Node.js 18+ is required for the package CLI itself
-- OpenCode must already be available on the machine
-- git must be available
-- `beads_rust` / `br` is installed or verified by `slopmachine setup`
+- `slopmachine` is the owner/orchestrator
+- `developer` is the implementation worker
 
-Generated projects follow the original prompt and the existing repository first.
+## Configured Items
 
-Default runtime/test wrapper expectations:
+These are the main files and directories `setup` configures.
 
-- Dockerized web backend/fullstack: `docker compose up --build` and `./run_tests.sh`
-- non-web or non-Docker runtime cases: `./run_app.sh` and `./run_tests.sh`
+### OpenCode Agents
 
-`./run_tests.sh` is always the broad test wrapper.
+- `~/.config/opencode/agents/slopmachine.md`
+- `~/.config/opencode/agents/developer.md`
 
-## Command Summary
+### OpenCode Skills
 
-Package CLI:
+- `~/.agents/skills/clarification-gate/`
+- `~/.agents/skills/developer-session-lifecycle/`
+- `~/.agents/skills/session-rollover/`
+- `~/.agents/skills/final-evaluation-orchestration/`
+- `~/.agents/skills/beads-operations/`
+- `~/.agents/skills/planning-guidance/`
+- `~/.agents/skills/planning-gate/`
+- `~/.agents/skills/scaffold-guidance/`
+- `~/.agents/skills/development-guidance/`
+- `~/.agents/skills/verification-gates/`
+- `~/.agents/skills/integrated-verification/`
+- `~/.agents/skills/hardening-gate/`
+- `~/.agents/skills/evaluation-triage/`
+- `~/.agents/skills/remediation-guidance/`
+- `~/.agents/skills/submission-packaging/`
+- `~/.agents/skills/retrospective-analysis/`
+- `~/.agents/skills/owner-evidence-discipline/`
+- `~/.agents/skills/report-output-discipline/`
+- `~/.agents/skills/frontend-design/`
 
-- `slopmachine setup`
-- `slopmachine init`
-- `slopmachine init -o`
+### SlopMachine Support Files
 
-Package validation:
+Installed under `~/slopmachine/`:
 
-- `npm run check`
-- `npm pack`
+- `backend-evaluation-prompt.md`
+- `frontend-evaluation-prompt.md`
+- `document-completeness.md`
+- `quality-document.md`
+- `engineering-results.md`
+- `implementation-comparison.md`
+- `workflow-init.js`
+- `templates/AGENTS.md`
+- `utils/strip_session_parent.py`
+- `utils/convert_ai_session.py`
 
-Generated project conventions:
+### OpenCode Config
 
-- `docker compose up --build` or `./run_app.sh`
-- `./run_tests.sh`
+Config file:
 
-## Files And Locations
+```bash
+~/.config/opencode/opencode.json
+```
 
-Main install locations:
+`setup` ensures these entries exist:
 
-- agents: `~/.config/opencode/agents/`
-- skills: `~/.agents/skills/`
-- packaged workflow files: `~/slopmachine/`
+- plugin: `oc-chatgpt-multi-auth`
+- MCP server: `chrome-devtools`
+- MCP server: `context7`
+- MCP server: `exa`
+- MCP server: `shadcn` disabled by default
 
-Inside a bootstrapped project root:
+If you want to customize agents, MCP settings, or plugins, these are the files to edit.
 
-- working codebase: `repo/`
-- external docs: `docs/`
-- session exports: `sessions/`
-- project metadata: `metadata.json`
+## Daily Use
 
-See also:
+After the machine is set up, the common flow is:
 
-- `MANUAL.md` for the short workflow guide
-- `RELEASE.md` for packaging and release checks
+```bash
+cd my-project/repo
+opencode
+```
 
-## Package layout
+Or for a brand new project in one shot:
 
-- `assets/agents/`
-- `assets/skills/`
-- `assets/slopmachine/`
-- `bin/`
-- `src/`
+```bash
+mkdir my-project
+cd my-project
+slopmachine init -o
+```

package/RELEASE.md

@@ -18,13 +18,14 @@ SLOPMACHINE_HOME="$(pwd)/.tmp-home" SLOPMACHINE_NONINTERACTIVE=1 SLOPMACHINE_PLU
 
 ```bash
 mkdir -p .tmp-project
-SLOPMACHINE_HOME="$(pwd)/.tmp-home" node ./bin/slopmachine.js init
+SLOPMACHINE_HOME="$(pwd)/.tmp-home" node ./bin/slopmachine.js init .tmp-project
 ```
 
 4. Test the open-after-bootstrap path:
 
 ```bash
-SLOPMACHINE_HOME="$(pwd)/.tmp-home" node ./bin/slopmachine.js init -o
+mkdir -p .tmp-project-open
+SLOPMACHINE_HOME="$(pwd)/.tmp-home" node ./bin/slopmachine.js init -o .tmp-project-open
 ```
 
 Note:
@@ -41,13 +42,13 @@ npm pack
 This should produce a tarball such as:
 
 ```bash
-theslopmachine-0.4.3.tgz
+theslopmachine-0.4.5.tgz
 ```
 
 ## Inspect package contents
 
 ```bash
-tar -tzf theslopmachine-0.4.3.tgz
+tar -tzf theslopmachine-0.4.5.tgz
 ```
 
 Check that the tarball includes:

package/assets/agents/developer.md

@@ -62,7 +62,12 @@ During ordinary work, prefer:
 - targeted module or route-family tests
 - the selected stack's local UI or E2E tool on affected flows when UI is material
 
-Do not jump to broad Docker and full-suite commands on ordinary turns.
+Owner-only broad gate commands:
+
+- never run `./run_tests.sh`
+- never run `docker compose up --build`
+- treat both commands as owner-run gate commands only, even if they are documented in the repo 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 owner-run broad verification
 
 The owner reserves the limited broad gate budget. Your job is to make those owner-run gates likely to pass.
 
@@ -90,4 +95,6 @@ Selected-stack defaults:
 
 - be direct and technically clear
 - report what changed, what was verified, and what still looks weak
+- always name the exact verification commands you ran and the concrete results they produced
+- if you ran no verification command for part of the work, say that explicitly instead of implying broader proof than you have
 - if a problem needs a real fix, fix it instead of explaining around it

package/assets/agents/slopmachine.md

@@ -78,6 +78,7 @@ Default to:
 - targeted reads instead of broad rereads
 - targeted execution instead of broad reruns
 - local and narrow verification before expensive gate commands
+- do not rerun expensive commands just to duplicate clear developer-provided evidence
 - file-backed reports with short in-chat summaries when the output would otherwise bloat context
 
 Stay aggressive about cutting waste, but do not weaken the actual standard.
@@ -171,16 +172,30 @@ Phase rules:
 - `P9 Remediation` stays its own root phase once evaluation has accepted follow-up work
 - `P6 Hardening` may reopen `P5` if hardening exposes unresolved integrated instability
 - `P11 Retrospective` runs automatically after successful packaging and is non-blocking unless it finds a real delivery defect
+- post-submission external evaluation feedback may reopen `P9 Remediation`, then rerun `P10 Submission Packaging`, and then rerun `P11 Retrospective`
 
 ## Developer Session Model
 
-Use up to two bounded developer sessions:
+Maintain exactly one active developer session at a time.
 
-1. develop session: planning, scaffold, development
-2. bugfix session: integrated verification, hardening, and remediation, only if needed
+Track every developer session in metadata, but create a new one only in these cases:
+
+1. you explicitly request a new session
+2. after successful submission, you return with external evaluation issues that require more fixes
+
+Session classes:
+
+1. `develop`: every developer session created before the first successful submission packaging
+2. `bugfix`: every developer session created after successful submission packaging when the project is reopened for external-evaluation follow-up
+
+There may be multiple `develop` sessions and multiple `bugfix` sessions over the life of one project.
+
+During the first full run from planning through initial submission packaging, keep all work in the `develop` session class, including integrated verification, hardening, evaluation-driven remediation, and packaging follow-through.
+
+If you explicitly request a new session while one is active, ask the current developer exactly `give me a summary of all the work that has been done`, then use that handoff to seed the next session.
 
 Use `developer-session-lifecycle` for startup, resume detection, session consistency checks, and recovery.
-Use `session-rollover` only for planned transitions between those bounded developer sessions.
+Use `session-rollover` only when intentionally starting a new developer session because of an explicit user request or post-submission external-feedback reopen.
 
 Do not launch the developer during `P0` or `P1`.
 
@@ -198,6 +213,14 @@ Do not merge those messages.
 
 Broad project-standard gate commands are expensive and must stay rare.
 
+Owner-side discipline:
+
+- do not run `./run_tests.sh` casually
+- do not run `docker compose up --build` casually
+- do not rerun expensive local test or E2E commands just because the developer already ran them
+- when the developer reports the exact verification command and its result clearly, use that evidence unless there is a concrete reason to challenge it
+- rerun expensive verification only when the developer evidence is weak, contradictory, flaky, high-risk, needed for a true broad gate, or needed to answer a new question
+
 Target budget for the whole workflow:
 
 - at most 3 broad owner-run verification moments using the selected stack's full verification path
@@ -272,7 +295,7 @@ Core map:
 - `P11` -> `retrospective-analysis`, `owner-evidence-discipline`, `report-output-discipline`
 - state mutations -> `beads-operations`
 - evidence-heavy review -> `owner-evidence-discipline`
-- planned developer-session switch -> `session-rollover`
+- intentional new developer session -> `session-rollover`
 
 Do not improvise a phase from memory when a phase skill exists.
 
@@ -284,6 +307,7 @@ When talking to the developer:
 - lead with the engineering point, not process framing
 - keep prompts natural, sharp, and compact unless the moment really needs more context
 - translate workflow intent into normal software-project language
+- for each development slice or bugfix request, require the reply to state the exact verification commands that were run and the concrete results they produced
 
 Do not leak workflow internals such as:
 
@@ -344,6 +368,7 @@ Treat packaging as a first-class delivery contract from the start, not as late c
 - the two evaluation prompt files are used exactly during evaluation runs
 - the four non-evaluation package documents are used during submission packaging to generate the required submission outputs
 - exact packaging file outputs and final paragraph outputs are mandatory in `P10`
+- accepted evaluation reports and cleaned original session exports are mandatory submission artifacts in `P10`
 - do not leave packaging structure, screenshots, self-test outputs, or exports to be improvised at the end
 
 When `P10 Submission Packaging` begins:
@@ -358,7 +383,7 @@ After `P10 Submission Packaging` closes successfully:
 
 - automatically enter `P11 Retrospective`
 - load `retrospective-analysis`
-- write dated retrospective output under `~/slopmachine/retrospectives/`
+- write `run_id`-scoped retrospective output under `~/slopmachine/retrospectives/`
 - keep it owner-only and non-blocking by default
 - reopen packaging only if the retrospective finds a real packaged-result defect
 

package/assets/skills/beads-operations/SKILL.md

@@ -24,7 +24,7 @@ When a root phase changes:
 - do not close multiple root phases in one transition block
 - keep structured comments specific and auditable
 - treat phase-closure failures as real workflow failures to resolve
-- keep Beads and metadata aligned on current phase and active developer session slot when either changes
+- keep Beads and metadata aligned on current phase and active developer session record when either changes
 
 ## Structured comment prefixes
 

package/assets/skills/clarification-gate/SKILL.md

@@ -28,7 +28,7 @@ Use this skill only during `P1 Clarification`.
 - decompose the prompt thoroughly into explicit requirements, implied requirements, user flows, constraints, boundaries, risks, quality expectations, and verification expectations
 - identify and lock safe default decisions that are consistent with the prompt and improve execution quality without changing intent
 - when more than one safe default is available, prefer the one that preserves or slightly over-covers the full prompt scope rather than the one that narrows scope for implementation convenience
-- record meaningful ambiguities, locked safe defaults, and decision rationale in the working questions record that will later become `../docs/questions.md`
+- record meaningful ambiguities, locked safe defaults, and decision rationale directly in mandatory parent-root `../docs/questions.md`
 - prepare a developer-facing clarification prompt in `../.ai/clarification-prompt.md`
 - keep clarification aligned with the original prompt
 - do not let clarification reduce, weaken, narrow, or silently reinterpret the prompt
@@ -50,7 +50,7 @@ Use this skill only during `P1 Clarification`.
 
 ## Required outputs
 
-- working clarification record that will become `../docs/questions.md`
+- parent-root `../docs/questions.md`
 - developer-facing clarification prompt in `../.ai/clarification-prompt.md`
 - explicit list of safe defaults and resolved ambiguities
 
@@ -94,7 +94,7 @@ Preferred entry shape:
 <brief justification tied to prompt faithfulness>
 ```
 
-If nothing material was unclear, keep `questions.md` minimal rather than inventing content.
+If nothing material was unclear, still create `questions.md` and keep it minimal rather than inventing content.
 
 ## Clarification-prompt validation loop
 
@@ -119,5 +119,6 @@ If nothing material was unclear, keep `questions.md` minimal rather than inventi
 - the owner is confident the scope is understood clearly enough to enter planning
 - the clarification prompt is strong enough for the developer to start from the right understanding
 - material ambiguities are resolved or safely locked and documented
+- `../docs/questions.md` exists and reflects the accepted clarification record
 - prompt drift has been checked and rejected
 - human approval exists

package/assets/skills/developer-session-lifecycle/SKILL.md

@@ -11,7 +11,7 @@ Use this skill during `P0 Intake and Setup` and whenever startup or recovery sta
 
 - detect whether the run is new or resumed
 - initialize or recover workflow metadata consistently
-- initialize the planned bounded developer-session slots
+- initialize developer-session tracking for the run
 - recover the current active developer session when one already exists
 
 ## Usage rules
@@ -55,10 +55,10 @@ Optional startup inputs may include:
 2. create `../.ai/metadata.json` for internal workflow state
 3. initialize parent-root `../metadata.json` with the required schema and store the full prompt text in `prompt`
 4. initialize root workflow state and top-level phase Beads items
-5. complete clarification using the clarification skill
-6. wait only for the initial clarification approval before development starts
-7. ensure the parent project root has the required working structure, especially `../sessions/` and `../docs/`
-8. initialize the bounded developer-session slots
+5. ensure the parent project root has the required working structure, especially `../sessions/` and `../docs/`
+6. complete clarification using the clarification skill
+7. wait only for the initial clarification approval before development starts
+8. initialize developer-session tracking for the run
 9. start the develop developer session only after `P2` is ready to begin
 10. send this exact first planning opener as the first message in that session: `lets plan this <original-prompt>`
 11. wait for the developer's first exchange
@@ -67,7 +67,7 @@ Optional startup inputs may include:
 
 ## First developer-session handshake
 
-The first bounded developer session must begin in this exact order:
+The first developer session of the run must begin in this exact order:
 
 1. owner starts the develop developer session
 2. owner sends: `lets plan this <original-prompt>`
@@ -84,7 +84,7 @@ Do not merge those two messages into one.
 - root workflow state exists
 - `../.ai/metadata.json` exists
 - `../metadata.json` exists
-- planned developer session slots are initialized
+- developer-session tracking is initialized
 - required parent-root directories exist
 
 ## Metadata and workflow files
@@ -107,19 +107,26 @@ Track at least:
 - `backend_evaluation_session_id`
 - `frontend_evaluation_session_id`
 - `last_evaluation_session_id`
+- `backend_evaluation_report_path`
+- `frontend_evaluation_report_path`
 - `passed_evaluation_tracks`
 - `developer_sessions`
-- `active_developer_session_index`
+- `active_developer_session_id`
+- `next_develop_session_number`
+- `next_bugfix_session_number`
+- `submission_completed`
 
-Each planned developer session record should include enough to recover it later, such as:
+Each developer session record should include enough to recover and export it later, such as:
 
-- `index`
+- `session_class`
+- `sequence`
 - `label`
-- `phase_group`
+- `created_phase`
 - `session_id`
 - `status`
 - `handoff_in`
 - `handoff_out`
+- `reopened_after_submission`
 
 Required project metadata fields in `../metadata.json` when relevant:
 
@@ -136,19 +143,29 @@ Required project metadata fields in `../metadata.json` when relevant:
 - fill known values immediately and keep the file current as the project becomes clearer
 - prefer explicit values; use `null` only when a field is genuinely unknown or not applicable
 
-## Bounded session model
+## Session model
 
-Track up to two planned developer sessions:
+- keep exactly one active developer session at a time
+- record every developer session in `developer_sessions`
+- classify sessions as `develop` or `bugfix`
+- every session created before the first successful submission packaging is `develop`
+- every session created after successful submission packaging to address external evaluation follow-up is `bugfix`
+- create a new developer session only when:
+  - the user explicitly requests a new session
+  - post-submission external evaluation feedback reopens the project for more fixes
 
-1. develop
-2. bugfix
+If the user explicitly requests a new session while one is active:
 
-Later session slots may remain unused if the workflow never needs them.
+1. ask the current developer exactly: `give me a summary of all the work that has been done`
+2. treat that reply as the handoff summary
+3. start the new developer session with that summary as the handoff-in context
+4. keep the session class as `develop` before first successful submission, otherwise keep it as `bugfix`
 
 ## Initial structure rule
 
 - parent-root `../docs/` is the owner-maintained external documentation directory
 - parent-root `../sessions/` is the session artifact directory for exported conversation traces
+- `../docs/questions.md` is a mandatory project artifact produced during clarification and preserved through packaging
 - do not treat repo-local `docs/` as the active external documentation location
 
 ## Recovery rule

package/assets/skills/development-guidance/SKILL.md

@@ -29,7 +29,7 @@ Use this skill during `P4 Development` before prompting the developer.
 - verify tenant or ownership isolation where relevant so access is scoped to the authorized context rather than merely functionally working for one actor
 - verify file and export paths are validated and confined to allowed roots when the module reads, writes, imports, or exports files
 - verify error and auth responses are user-safe and do not leak internal reasons, paths, stack details, or sensitive state
-- perform a clean-slate sweep before reporting module completion: remove seeded credentials, weak demo defaults, test-account hints, prototype residue, and other production-inappropriate artifacts
+- perform a clean-slate sweep before reporting module completion: remove weak demo defaults, stray test-account hints, prototype residue, and other production-inappropriate artifacts; deterministic non-secret Dockerized dev/test default credentials are allowed only when clearly labeled local-only and required for startup or test stability
 - do not treat backend existence, composable existence, or partial wiring as completion if the user-visible flow is still incomplete
 - when the prompt says users can manage or configure something, implement full management behavior rather than create-only controls where appropriate
 - if a required user-facing or admin-facing surface is missing, treat that gap as incomplete implementation rather than a reason to bypass the surface with direct API calls or test-only shortcuts
@@ -54,6 +54,7 @@ Use this skill during `P4 Development` before prompting the developer.
 - for mobile projects, default local UI testing to the selected mobile test stack and use a platform-appropriate mobile UI/E2E tool when device-flow proof matters
 - for desktop projects, default local UI verification to Playwright's Electron support or another platform-appropriate desktop UI/E2E tool when window-flow proof matters
 - when the slice materially changes frontend code, frontend tooling, or release-facing build behavior, include production build health in meaningful local verification when practical
+- in each slice reply, report the exact verification commands that were run and the concrete results they produced so the owner can review the evidence without blindly rerunning the same commands
 
 ## Quality rules
 

package/assets/skills/final-evaluation-orchestration/SKILL.md

@@ -36,12 +36,13 @@ These two files are the only evaluation prompt sources for evaluation runs.
 - send that fully composed text block directly to the fresh `General` evaluator session
 - never tell the evaluator to go read prompt files, metadata files, or evaluation template paths on its own
 - never send only a path, filename, or shorthand reference and expect the evaluator to assemble the prompt itself
-- never reuse, resume, or continue a prior evaluation session
+- do not reuse, resume, or continue a prior evaluation session except for the explicit pass-3 fallback on the last still-failing track
 - run the two evaluations sequentially, not in parallel, so shared runtime state, ports, databases, and artifacts do not conflict
 - track backend and frontend evaluation status separately
 - once backend evaluation passes, do not run backend evaluation again in later remediation rounds
 - once frontend evaluation passes, do not run frontend evaluation again in later remediation rounds
 - require each evaluation session to produce its own detailed evaluation report artifact
+- record the current accepted backend and frontend evaluation report paths in metadata for later packaging
 - always compare both evaluations against the original prompt for alignment, not just the delivered implementation
 - keep reports file-backed and bring only short summaries into chat
 - rerun only the evaluation track that still needs re-evaluation after remediation
@@ -61,7 +62,7 @@ These two files are the only evaluation prompt sources for evaluation runs.
 
 ## Remediation loop
 
-- route accepted blocking issues back into the active remediation developer-session slot rather than inventing an untracked side path
+- route accepted blocking issues back into the active developer session rather than inventing an untracked side path
 - after remediation, rerun strong local verification before any re-evaluation:
     - relevant local test commands
     - local runtime checks when affected behavior needs runtime proof

package/assets/skills/integrated-verification/SKILL.md

@@ -23,6 +23,8 @@ Once a failure class is known:
 - run the relevant tests for the changed behavior
 - during in-phase verification, prefer the fastest meaningful local test commands for the known failure class
 - use local verification to prepare for the next owner-run broad gate rather than duplicating it casually
+- when sending a developer fix request for integrated-verification failures, require the reply to name the exact rerun commands and the concrete results they produced
+- do not reflexively rerun the same expensive local test or E2E command on the owner side when the developer's reported evidence is already clear and sufficient
 - for applicable UI-bearing work, run the selected stack's platform-appropriate UI/E2E tool for the affected flows in-phase, capture screenshots or equivalent artifacts, and verify the UI behavior and quality directly
 - verify requirement closure, not just feature existence
 - verify behavior against the current plan, the actual requirements, and any settled project decisions that affect the change

package/assets/skills/planning-guidance/SKILL.md

@@ -91,6 +91,9 @@ Selected-stack defaults:
 - for Dockerized web backend/fullstack projects, `./run_tests.sh` must run the full test path through Docker rather than a purely local test invocation
 - for non-web or non-Docker projects, `./run_tests.sh` must call the selected stack's equivalent full test path while keeping the same single-command interface
 - local tests should still exist for ordinary developer iteration, but `./run_tests.sh` is the broad final test path for the project
+- for Dockerized web backend/fullstack projects, plan collision-resistant Compose defaults from the start: unique `COMPOSE_PROJECT_NAME`, no unnecessary `container_name`, only the app-facing port exposed to host by default, and internal services kept off host ports unless required
+- for Dockerized web backend/fullstack projects, prefer random host-port binding on `127.0.0.1` for the default runtime so parallel projects can start cleanly; if a fixed host port is genuinely required, plan an override plus a free-port fallback in the runtime or test wrapper
+- when Dockerized dev/test runtime or tests require credentials or bootstrap accounts, plan deterministic non-secret default runtime env values through Compose or wrapper configuration so local startup does not fail on missing credentials, while keeping those defaults out of `.env` files and out of Dockerfile image layers
 - define frontend validation and accessibility expectations when the product surface materially depends on them, including keyboard, focus, feedback, and other user-interaction quality requirements where relevant
 - if backup or recovery behavior is prompt-critical, plan the designated media, operator drill flow, visibility, and verification expectations explicitly
 - if the prompt names literal storage, indexing, partitioning, retention, or performance dimensions, represent them literally in the planning artifacts rather than abstracting them away

package/assets/skills/remediation-guidance/SKILL.md

@@ -21,7 +21,7 @@ Use this skill only during `P9 Remediation`.
 - rerun the relevant verification after each fix
 - if the issue exposed drift, docs overclaim, or missing acceptance coverage, repair that too before closing the issue
 - update docs if behavior or instructions changed
-- report exactly what was fixed, what was rerun, and what still looks risky if anything remains
+- report exactly what was fixed, the exact verification commands that were rerun, the concrete results they produced, and what still looks risky if anything remains
 
 ## Rules
 

package/assets/skills/retrospective-analysis/SKILL.md

@@ -24,17 +24,19 @@ Use this skill only after `P10 Submission Packaging` has materially and formally
 
 ## Output location
 
-Write dated retrospective files under:
+Write run-scoped retrospective files under:
 
 - `~/slopmachine/retrospectives/`
 
 Preferred filenames:
 
-- `retrospective-YYYY-MM-DD.md`
-- `improvement-actions-YYYY-MM-DD.md`
+- `retrospective-<run_id>.md`
+- `improvement-actions-<run_id>.md`
 
 If only one file is needed, the retrospective file is sufficient.
 
+The `run_id` must come from the current project's `../.ai/metadata.json` so the retrospective can be matched back to one exact workflow run.
+
 ## Evidence sources
 
 Prefer existing workflow artifacts first:

package/assets/skills/scaffold-guidance/SKILL.md

@@ -49,6 +49,13 @@ For Dockerized web backend/fullstack projects, scaffold must make these commands
 - remove prototype residue from runtime foundations: no placeholder titles, hidden setup, fake defaults, or seeded live-path assumptions
 - make prompt-critical runtime behavior visible in the scaffold instead of hand-waving it for later, especially offline, worker, backup, or HTTPS requirements
 - for Dockerized web projects, keep runtime isolation clean in shared environments: use self-contained Compose namespacing, avoid fragile generic project names, and prefer Compose-managed service naming over unnecessary hardcoded `container_name` values
+- for Dockerized web projects, derive a unique `COMPOSE_PROJECT_NAME` from the repo or worktree identity for runtime wrappers, and use a separate unique test namespace for `./run_tests.sh` so parallel local projects do not collide
+- for Dockerized web projects, expose only the primary app-facing port to the host by default, keep databases/cache/internal services off host ports unless the prompt truly requires exposure, and bind exposed ports to `127.0.0.1`
+- for Dockerized web projects, prefer Docker-assigned random host ports for the default host binding so plain `docker compose up --build` can run without host-port collisions; if the prompt requires a fixed host port, support an overrideable host-port variable and make the runtime or test wrapper fall back to a free port automatically when needed
+- for Dockerized web projects, keep image, network, and volume naming under Compose project scoping; if explicit image names are needed, namespace them with the Compose project name instead of using generic shared names
+- for Dockerized web projects, add healthchecks and make runtime or test wrappers wait for service readiness before proceeding so startup is reliable on slower machines
+- when Dockerized dev/test startup or tests require credentials or bootstrap accounts, provide deterministic non-secret default values through Compose/runtime environment configuration so `docker compose up --build` and `./run_tests.sh` do not fail due to missing credentials
+- keep those Dockerized dev/test default credentials clearly marked as local-only test credentials, do not store them in `.env` files, and do not bake them into the Dockerfile image layers
 - require reproducible build and tooling foundations: prefer lockfile-driven installs where the stack supports them, keep source and build outputs clearly separated, and do not allow generated runtime artifacts to drift back into source directories
 - for typed build pipelines, keep source-of-truth boundaries clean so compiled output does not create TS/JS or similar dual-source drift in the working tree
 - establish README structure early instead of leaving it until the end

package/assets/skills/session-rollover/SKILL.md

@@ -1,22 +1,36 @@
 ---
 name: session-rollover
-description: Planned developer-session handoff and rollover rules for bounded slopmachine developer sessions.
+description: Developer-session handoff and rollover rules for intentional slopmachine session switches.
 ---
 
 # Session Rollover
 
-Use this skill only when intentionally moving from one planned developer session slot to the next.
+Use this skill only when intentionally starting a new developer session while preserving the old one as history.
 
 ## Typical uses
 
-- develop session -> bugfix session
+- the user explicitly asks for a new developer session
+- post-submission external evaluation feedback reopens the project for more fixes
 
 ## Rules
 
-- rollover is planned, not a recovery event
+- rollover is intentional, not a recovery event
+- keep exactly one active developer session at a time
 - do not open the next developer session until the current session has a clear handoff out
 - record the new session id and status immediately after the new session is created
 
+If the user explicitly requests a new session while one is active:
+
+1. ask the current developer exactly: `give me a summary of all the work that has been done`
+2. store that reply as the handoff artifact for the closing session
+3. start the new developer session with that summary as the handoff-in context
+
+If the project is reopened after successful submission because of external evaluation feedback:
+
+1. record the external issue list and any accepted evaluation report references in the handoff
+2. start a new `bugfix` developer session
+3. use that external feedback plus the handoff summary as the starting context
+
 ## Required handoff contents
 
 - current phase and why rollover is happening
@@ -32,7 +46,8 @@ When rollover succeeds, update metadata so it is obvious:
 - which prior session is now completed or inactive
 - which new session is active
 - where the handoff artifact lives
-- which phase group the new session now owns
+- which session class the new session belongs to
+- whether the new session was opened after successful submission
 
 ## Avoid
 

package/assets/skills/submission-packaging/SKILL.md

@@ -73,14 +73,16 @@ The final submission layout in the parent project root must be:
   - `questions.md`
 - `submission/`
   - generated submission documents based on the reference files in `~/`
-  - evaluation reports
+  - `backend-evaluation-report.md` when applicable
+  - `frontend-evaluation-report.md` when applicable
+  - cleaned original session exports for every tracked developer session
   - repo file structure screenshot
   - working app screenshots
   - relocated screenshots and proof materials needed for submission review
 - current working directory delivered as parent-root `repo/`
 - `../sessions/`
-  - `develop-N.json`
-  - `bugfix-N.json`
+  - converted `develop-N.json` session exports for all pre-submission developer sessions
+  - converted `bugfix-N.json` session exports for all post-submission external-follow-up developer sessions
 - `../metadata.json`
 - parent-root `../.tmp/` directory moved out of current `.tmp/` when it exists
 
@@ -91,7 +93,7 @@ The final submission layout in the parent project root must be:
 - verify parent-root `../docs/design.md` exists and reflects the final delivered design when applicable
 - verify parent-root `../docs/api-spec.md` exists and reflects the final delivered interfaces when applicable
 - verify parent-root `../docs/test-coverage.md` exists and reflects the final delivered verification coverage
-- verify parent-root `../docs/questions.md` exists from the accepted clarification/question record when applicable
+- verify parent-root `../docs/questions.md` exists from the accepted clarification/question record
 - create parent-root `../submission/` for final generated submission artifacts and reviewer-facing proof
 - use these exact `~/slopmachine/` document templates as the packaging reference sources:
   - `~/slopmachine/document-completeness.md`
@@ -100,10 +102,12 @@ The final submission layout in the parent project root must be:
   - `~/slopmachine/quality-document.md`
 - ensure `README.md` matches the delivered codebase, functionality, runtime steps, and test steps, stays friendly to a junior developer, and does not reference the external docs set in `../docs/`
 - include `./run_tests.sh` and any supporting runner logic it needs to execute the project's broad test path from a clean environment
-- relocate evaluation artifacts into parent-root `../submission/`
+- relocate accepted backend and frontend evaluation reports into parent-root `../submission/` as `backend-evaluation-report.md` and `frontend-evaluation-report.md` when those tracks apply
 - relocate screenshots and proof materials relevant to runtime behavior and major flows into parent-root `../submission/`
 - preserve parent-root `../sessions/` as the session artifact directory for converted workflow session exports
 - export all tracked workflow sessions before generating the final submission documents
+- preserve all cleaned original session exports under parent-root `../submission/`
+- when packaging succeeds, mark `submission_completed` as true in internal metadata so later reopen handling can classify post-submission sessions correctly
 - after the session exports are complete, the owner should answer the final submission-document questions based on the recent review responses gathered across evaluation reports, remediation results, verification notes, and packaging checks
 
 ## Session export sequence
@@ -112,22 +116,34 @@ This export sequence must happen first in packaging, before final submission doc
 
 Export every tracked workflow session from metadata.
 
+Use a class-and-sequence label for each tracked session, for example:
+
+- `develop-1`
+- `develop-2`
+- `bugfix-1`
+
 For each tracked session:
 
 1. `opencode export <session-id> > ../session-export-<label>.json`
 2. `python3 ~/utils/strip_session_parent.py ../session-export-<label>.json --output ../session-clean-<label>.json`
 3. `python3 ~/utils/convert_ai_session.py -i ../session-clean-<label>.json -o ../sessions/<final-name>.json`
+4. copy `../session-clean-<label>.json` to `../submission/session-clean-<label>.json`
 
 Naming rule for converted files under `../sessions/`:
 
-- the develop session becomes `develop-N.json`
-- the bugfix session becomes `bugfix-N.json`
+- every pre-submission developer session becomes `develop-N.json`
+- every post-submission external-follow-up developer session becomes `bugfix-N.json`
+
+Naming rule for cleaned original session exports under `../submission/`:
+
+- `session-clean-develop-N.json`
+- `session-clean-bugfix-N.json`
 
 After those steps:
 
-- verify every planned developer session has been exported and converted before continuing packaging
+- verify every tracked developer session has been exported, cleaned, converted, and copied into `../submission/` before continuing packaging
 - keep the converted session outputs in `../sessions/` using the naming rules above
-- treat the `../session-export-*.json` and `../session-clean-*.json` files as temporary packaging intermediates unless the package contract later says otherwise
+- treat only the raw `../session-export-*.json` files as temporary packaging intermediates unless the package contract later says otherwise
 - if the required utilities, metadata session ids, or output files are missing, packaging is not ready to continue
 - only after these exports are complete may you generate the final submission documents
 
@@ -147,7 +163,7 @@ If the gathered review evidence is incomplete, stop and repair the missing evide
 
 - if repo-local `docs/` exists, treat it as accidental residue, reconcile any missing content into parent-root `../docs/`, and remove it from the delivered `repo/` tree
 - if current `.tmp/` exists, move the whole directory to parent-root `../.tmp/` before harvesting any reviewer-facing artifacts from it
-- after preserving parent-root `../.tmp/`, collect the relevant evaluation reports and proof artifacts from it into parent-root `../submission/`
+- after preserving parent-root `../.tmp/`, collect the accepted backend and frontend evaluation reports plus other relevant proof artifacts into parent-root `../submission/`
 - collect screenshots and other required proof materials from repo-local runtime/output directories into parent-root `../submission/`
 - after relocation, the final submission should not require digging through repo-local output directories to find evidence
 - keep screenshot filenames clear enough that the referenced runtime page, flow, or evidence purpose is understandable
@@ -166,13 +182,15 @@ If the gathered review evidence is incomplete, stop and repair the missing evide
 - confirm docs describe delivered behavior, not planned or aspirational behavior
 - confirm parent-root `../docs/test-coverage.md` explains the tested flows, coverage boundaries, and how the evaluator should interpret the coverage evidence
 - confirm generated submission documents exist under parent-root `../submission/` and correspond to the final qualified state
-- confirm evaluation reports and screenshots have been relocated into parent-root `../submission/`
+- confirm accepted backend and frontend evaluation reports have been relocated into parent-root `../submission/` when those tracks apply
+- confirm cleaned original session exports for every tracked developer session exist under parent-root `../submission/`
 - confirm shared project docs live in parent-root `../docs/` and any accidental repo-local `docs/` copy has been removed from the delivered tree
 - confirm required screenshots have been relocated into parent-root `../submission/`
 - confirm parent-root metadata fields are populated correctly
+- confirm internal metadata marks `submission_completed` as true for a successful packaged state
 - confirm session export naming rules are followed under `../sessions/`:
-  - `develop-N.json` for the develop session
-  - `bugfix-N.json` for the bugfix session
+  - `develop-N.json` for every pre-submission developer session
+  - `bugfix-N.json` for every post-submission external-follow-up developer session
 
 ## Submission artifact and response contract
 

package/assets/skills/verification-gates/SKILL.md

@@ -42,7 +42,8 @@ Use this skill after development begins whenever you are reviewing work, decidin
 - do not accept frontend/backend drift in fullstack work
 - do not accept missing end-to-end coverage for major fullstack flows
 - do not accept UI claims without screenshot-backed or platform-equivalent visual evidence when the change affects real UI behavior
-- do not accept prototype residue such as seeded credentials, weak demo defaults, login hints, or unsanitized user-facing error behavior
+- do not accept production-inappropriate residue such as weak demo defaults, stray login hints, or unsanitized user-facing error behavior
+- deterministic non-secret Dockerized dev/test default credentials are acceptable only when they are clearly labeled local-only, supplied through runtime configuration rather than `.env` files or Dockerfile image layers, and required so local startup or tests do not fail on missing credentials
 - do not accept multi-tenant or cross-user security claims without negative isolation evidence when that boundary matters
 - do not accept file-bearing flows without path confinement and traversal-style validation when that boundary matters
 - do not accept partial foundation work for complex features when the prompt implies broader usable scope, infrastructure depth, or security depth than what was actually delivered
@@ -55,6 +56,8 @@ Use this skill after development begins whenever you are reviewing work, decidin
 - use targeted local verification as the default during scaffold corrections, development, hardening, and remediation
 - reserve the selected stack's broad verification path for the limited owner-run gate moments in the workflow budget
 - do not turn ordinary acceptance into repeated integrated-style gate runs
+- do not run `./run_tests.sh` casually on the owner side
+- do not run `docker compose up --build` casually on the owner side
 - for Dockerized web backend/fullstack projects, the owner must run `docker compose up --build` and `./run_tests.sh` once after scaffold completion to confirm the scaffold baseline
 - after that scaffold confirmation, the next Docker-based run should be at development completion or integrated-verification entry unless a real blocker forces earlier escalation
 
@@ -64,10 +67,12 @@ Use this skill after development begins whenever you are reviewing work, decidin
 - review technical quality, prompt alignment, architecture impact, and verification depth of the current work
 - during normal implementation iteration, always prefer fast local language-native or framework-native verification for the changed area instead of the selected stack's broad gate path
 - require the developer to set up and use the project-appropriate local test environment in the current working directory when normal local verification is needed
+- require the developer to report the exact verification commands that were run and the concrete results they produced
 - require local runtime proof when relevant by starting the app or service through the selected stack's local run path and exercising the changed behavior directly rather than jumping to the broad gate path
 - if the local toolchain is missing, require the developer to install or enable it first; do not jump to the broad gate path during ordinary iteration just because local setup is inconvenient
 - do not accept hand-wavy claims that local verification is unavailable without a real setup attempt and clear explanation
 - for applicable UI-bearing work, require the selected stack's local UI/E2E tool on affected flows plus screenshot review or equivalent platform artifacts and explicit UI validation
+- if the developer already ran the relevant targeted test or E2E command and reported it clearly, do not rerun the same command on the owner side unless the evidence is weak, contradictory, flaky, high-risk, or needed to answer a new question
 - if verification is weak, missing, or failing, require fixes and reruns before acceptance
 - if documentation or repo hygiene drifts, secrets leak, contracts drift, or frontend integrity is compromised, require cleanup before acceptance
 - keep looping until the current work is genuinely acceptable
@@ -101,6 +106,8 @@ Use evidence such as internal metadata files, structured Beads comments, verific
 - when scaffold includes prompt-critical security controls, acceptance requires real runtime or endpoint verification of the protection rather than helper-only or shape-only proof
 - for security-bearing scaffolds, require applicable rejection evidence such as stale replay rejection, nonce reuse rejection, CSRF rejection on protected mutations, lockout triggering when lockout is in scope, or equivalent proof that the control is truly enforced
 - scaffold acceptance also requires clean startup and teardown behavior in the selected runtime model; for Dockerized web projects this includes self-contained Compose namespacing and no unnecessary fragile `container_name` usage
+- for Dockerized web projects, scaffold acceptance also requires collision-resistant shared-machine defaults: only the primary app-facing port exposed to host by default, internal services not bound to host without prompt need, default host binding on `127.0.0.1`, and either random host-port assignment or a real free-port fallback when fixed ports are required
+- for Dockerized web projects, scaffold acceptance also requires deterministic non-secret local-only default credentials in runtime configuration when startup or tests depend on credentials, and those defaults must not live in `.env` files or Dockerfile image layers
 - for Dockerized web backend/fullstack projects, scaffold acceptance is not complete until the owner has actually run `docker compose up --build` and `./run_tests.sh` once successfully after scaffold completion
 - module implementation requires platform-appropriate local verification and selected-stack UI/E2E evidence when UI-bearing flows are material
 - module implementation acceptance should challenge tenant isolation, path confinement, sanitized error behavior, prototype residue, integration seams, and cross-cutting consistency when those concerns are in scope

package/assets/slopmachine/templates/AGENTS.md

@@ -41,6 +41,10 @@ For Dockerized web backend/fullstack projects:
 - `./run_tests.sh` must run the broad full-test path through Docker
 - local non-Docker tests should still exist for normal development work
 - final broad verification should use the Dockerized `./run_tests.sh` path, not only local test commands
+- keep Compose isolation safe for shared machines: no unnecessary `container_name`, unique `COMPOSE_PROJECT_NAME`, and Compose-scoped image/network/volume naming
+- expose only the primary app-facing port to host by default, bind it to `127.0.0.1`, and keep databases/cache/internal services off host ports unless truly required
+- prefer random host-port assignment by default so parallel local projects do not collide; if a fixed host port is truly required, support override plus free-port fallback in the runtime or test wrapper
+- add healthchecks and wait for service readiness before tests or dependent startup steps proceed
 
 When `docker compose up --build` is not the runtime contract, provide `./run_app.sh` as the single primary runtime wrapper.
 
@@ -74,6 +78,8 @@ Selected-stack defaults:
 - Do not rely on `.env`, `.env.local`, `.env.example`, or similar files for project startup.
 - Do not hardcode secrets.
 - If runtime env-file format is required, generate it ephemerally and do not commit or package it.
+- If Dockerized dev/test startup or tests require credentials, provide deterministic non-secret local-only default values through Docker runtime configuration so `docker compose up --build` and `./run_tests.sh` do not fail on missing credentials.
+- Keep those Dockerized dev/test default credentials out of Dockerfile image layers.
 
 Selected-stack secret/config defaults:
 

package/assets/slopmachine/utils/strip_session_parent.py

@@ -2,10 +2,32 @@
 
 import argparse
 import json
+import re
 from pathlib import Path
 from typing import Any
 
 
+SUBAGENT_TITLE_SUFFIX = re.compile(r"\s+\(@[^)]*subagent\)\s*$")
+
+
+def clean_title(title: Any) -> Any:
+    if not isinstance(title, str):
+        return title
+    return SUBAGENT_TITLE_SUFFIX.sub("", title)
+
+
+def clean_message_info(info: Any) -> Any:
+    if not isinstance(info, dict):
+        return info
+
+    cleaned = dict(info)
+    tools = cleaned.get("tools")
+    if isinstance(tools, dict) and tools and all(value is False for value in tools.values()):
+        cleaned.pop("tools", None)
+
+    return cleaned
+
+
 def strip_parent_id(data: Any) -> Any:
     if not isinstance(data, dict):
         raise ValueError("Expected top-level JSON object")
@@ -20,13 +42,30 @@ def strip_parent_id(data: Any) -> Any:
     # Remove only the session-level parent marker. Message-level parentIDs
     # are preserved so the conversation structure remains intact.
     cleaned_info.pop("parentID", None)
+    cleaned_info.pop("permission", None)
+    cleaned_info["title"] = clean_title(cleaned_info.get("title"))
     cleaned["info"] = cleaned_info
+
+    messages = cleaned.get("messages")
+    if isinstance(messages, list):
+        cleaned_messages = []
+        for message in messages:
+            if not isinstance(message, dict):
+                cleaned_messages.append(message)
+                continue
+
+            cleaned_message = dict(message)
+            cleaned_message["info"] = clean_message_info(message.get("info"))
+            cleaned_messages.append(cleaned_message)
+
+        cleaned["messages"] = cleaned_messages
+
     return cleaned
 
 
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(
-        description="Remove the top-level parentID from an OpenCode session export."
+        description="Remove subagent-only top-level metadata from an OpenCode session export."
     )
     parser.add_argument("input", type=Path, help="Path to the source session JSON file")
     parser.add_argument(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "theslopmachine",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "SlopMachine installer and project bootstrap CLI",
   "license": "MIT",
   "type": "module",

package/src/constants.js

@@ -2,7 +2,7 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-export const PACKAGE_VERSION = "0.4.3";
+export const PACKAGE_VERSION = "0.4.5";
 export const OPCODE_VERSION = "1.3.5";
 export const BR_VERSION = "0.1.34";
 export const PACKAGE_ROOT = path.resolve(

package/src/init.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs/promises'
+import { randomUUID } from 'node:crypto'
 import path from 'node:path'
 
 import { buildPaths } from './constants.js'
@@ -150,12 +151,59 @@ async function runWorkflowBootstrap(paths, targetPath, trackerScript) {
 }
 
 async function createRepoStructure(targetPath, agentsTemplate) {
+  log('Creating parent workflow directories')
+  await ensureDir(path.join(targetPath, 'docs'))
+  await ensureDir(path.join(targetPath, 'sessions'))
+
   log('Creating repo/ working directory')
   await ensureDir(path.join(targetPath, 'repo'))
 
   log('Copying AGENTS template into repo/')
   await fs.copyFile(agentsTemplate, path.join(targetPath, 'repo', 'AGENTS.md'))
 
+  const projectMetadataPath = path.join(targetPath, 'metadata.json')
+  if (!(await pathExists(projectMetadataPath))) {
+    log('Creating parent metadata.json')
+    await fs.writeFile(projectMetadataPath, `${JSON.stringify({
+      prompt: null,
+      project_type: null,
+      frontend_language: null,
+      backend_language: null,
+      database: null,
+      session_id: null,
+      frontend_framework: null,
+      backend_framework: null,
+    }, null, 2)}\n`, 'utf8')
+  }
+
+  const workflowMetadataPath = path.join(targetPath, '.ai', 'metadata.json')
+  if (!(await pathExists(workflowMetadataPath))) {
+    log('Creating .ai/metadata.json')
+    await fs.writeFile(workflowMetadataPath, `${JSON.stringify({
+      run_id: randomUUID(),
+      current_phase: null,
+      awaiting_human: false,
+      clarification_approved: false,
+      remediation_round: 0,
+      clarification_validator_session_id: null,
+      evaluation_pass: 0,
+      backend_evaluation_session_id: null,
+      frontend_evaluation_session_id: null,
+      last_evaluation_session_id: null,
+      backend_evaluation_report_path: null,
+      frontend_evaluation_report_path: null,
+      passed_evaluation_tracks: [],
+      developer_sessions: [],
+      active_developer_session_id: null,
+      next_develop_session_number: 1,
+      next_bugfix_session_number: 1,
+      submission_completed: false,
+    }, null, 2)}\n`, 'utf8')
+  }
+
+  await fs.writeFile(path.join(targetPath, '.ai', 'artifacts', '.gitkeep'), '', 'utf8')
+  await fs.writeFile(path.join(targetPath, 'docs', '.gitkeep'), '', 'utf8')
+  await fs.writeFile(path.join(targetPath, 'sessions', '.gitkeep'), '', 'utf8')
   await fs.writeFile(path.join(targetPath, 'repo', '.gitkeep'), '', 'utf8')
 }