theslopmachine 0.3.7 → 0.4.0

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

@@ -13,6 +13,15 @@ Use this skill after development begins whenever you are reviewing developer wor
 - Treat it as owner-side review and gate guidance, not developer-visible text.
 - Use `get-overlays` as the source of truth for developer-facing execution guidance.
 - Use this skill as the source of truth for owner-side verification, review pressure, and gate interpretation.
+- outside the final evaluation decision, do not pause execution for human approval while using this skill; continue reviewing, rejecting, fixing, and rerunning until the work qualifies
+
+## Documentation And Repo Hygiene
+
+- maintain the owner-managed external docs in parent-root `../docs/` from accepted clarification, accepted planning, accepted major implementation changes, and hardening verification
+- keep `README.md` codebase-specific, junior-friendly, and separate from the external docs set
+- do not allow `.env` files or env-file variants anywhere in the repo tree
+- do not allow a project that requires a preexisting `.env` file in the repo or package to start from scratch
+- if env-file format is needed at runtime, it must be generated ephemerally from Docker-provided runtime variables rather than stored in the repo or package
 
 ## Review standard
 
@@ -35,18 +44,20 @@ Use this skill after development begins whenever you are reviewing developer wor
 - do not accept frontend-bearing slice completion without checking production build health when the change materially affects frontend code or tooling
 - do not accept module completion that ignores integration seams or cross-cutting consistency with the existing system
 - do not accept end-to-end evidence that bypasses a required user-facing or admin-facing surface with direct API shortcuts
+- do not accept mocked APIs as integration evidence; integration verification must use real HTTP requests against the actual running service surface
 
 ## Verify-fix loop
 
 - inspect the result and the evidence, not just the developer's confidence
 - review technical quality, prompt alignment, architecture impact, and verification depth of the current work
-- during normal implementation iteration, prefer fast local language-native or framework-native verification for the changed area instead of forcing `run_tests.sh` every turn
+- during normal implementation iteration, always prefer fast local language-native or framework-native verification for the changed area instead of `docker compose up --build` or `run_tests.sh`
 - 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
-- if the local toolchain is missing, require the developer to install or enable it first; allow fallback to `run_tests.sh` only when that is not practical
+- require local runtime proof when relevant by starting the server locally and exercising the changed behavior directly rather than jumping to Docker-based proof
+- if the local toolchain is missing, require the developer to install or enable it first; do not jump to `run_tests.sh` 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 fullstack or UI-bearing work, require local Playwright on affected flows plus screenshot review and explicit UI validation
 - if verification is weak, missing, or failing, require fixes and reruns before acceptance
-- if docs drift, secrets leak, contracts drift, or frontend integrity is compromised, require cleanup 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
 
 ## Heavy-gate definition
@@ -54,30 +65,40 @@ Use this skill after development begins whenever you are reviewing developer wor
 - a heavy gate is an owner-run integrated verification boundary, not every ordinary phase change
 - a phase change alone does not automatically require a heavy gate unless that phase's exit criteria explicitly call for one
 - a heavy gate normally means some combination of full clean runtime proof, full `run_tests.sh`, and Playwright plus screenshot evidence when UI or fullstack flows exist
-- heavy gates are required at scaffold acceptance, integrated/full verification, and post-evaluation remediation re-acceptance
-- a mid-phase extra heavy gate is allowed only when the risk profile justifies it, such as major runtime, infra, migration, auth, security, build, or cross-module integration changes
+- heavy gates are required only at these milestone boundaries:
+  - scaffold acceptance
+  - when development/coding is complete and the project enters integrated verification
+  - when integrated verification is complete and the project is ready to leave that phase
+  - when hardening is complete and the project is ready for final evaluation
+  - once more on the final qualified state before submission packaging
 - planning acceptance, ordinary module acceptance, and routine in-phase verification are not heavy gates by default and should rely on targeted local verification unless the risk profile says otherwise
 
 ## Testing cadence interpretation
 
 - the first required `run_tests.sh` pass happens in scaffold once the clean foundation exists
-- after scaffold, do not force `docker compose up --build` or `run_tests.sh` on every normal development step when faster local verification is sufficient
+- after scaffold, do not force `docker compose up --build` or `run_tests.sh` on normal development steps
 - prefer local targeted or native test commands during module implementation and ordinary verify-fix iteration
+- prefer local runtime startup and direct local behavior checks instead of Docker whenever runtime proof is needed during ordinary work
 - local verification should run inside the current working directory using the project's own environment and tooling rather than hidden global assumptions
 - during applicable fullstack or UI-bearing implementation work, require local Playwright on affected flows and review screenshots
-- treat `docker compose up --build` and `run_tests.sh` as critical-gate verification commands for integrated/full verification, hard gates, and final-evaluation readiness rather than normal iteration tools
+- during integrated verification, do not rerun `docker compose up --build` or `run_tests.sh` on every small fix inside the phase; use local verification until the next milestone boundary is reached
+- reserve `docker compose up --build` and `run_tests.sh` for these owner-run milestone checks only:
+  - scaffold acceptance
+  - development/coding complete -> integrated verification entry
+  - integrated verification complete -> hardening entry
+  - hardening complete -> final evaluation readiness
+  - final qualified state -> submission packaging readiness
 - the workflow owner handles those expensive critical-gate runs; do not require the developer to duplicate them during normal phase progression
-- run `run_tests.sh` again at integrated/full verification
-- integrated/full verification must also run Playwright for major flows and inspect screenshots
-- run `run_tests.sh` again after post-evaluation remediation before re-acceptance
-- after post-evaluation remediation affecting real flows or UI, rerun Playwright and inspect fresh screenshots before re-acceptance
+- each integrated-verification milestone run must also include Playwright for major flows and screenshot review when UI or fullstack flows exist
+- after post-evaluation remediation, prefer local reruns, affected local runtime checks, and affected Playwright checks
+- after remediation, return the project to the appropriate milestone boundary and run the next owner-run gate there rather than turning every remediation fix into an immediate Docker and `run_tests.sh` rerun
 
 ## Runtime gate interpretation
 
-Use evidence such as Bead metadata, structured Bead comments, verification command results, and file/project-state checks.
+Use evidence such as internal metadata files, structured tracker comments, verification command results, and file/project-state checks.
 
 - clarification requires the `clarification-gate` conditions plus explicit approval record
-- development bootstrap requires the `developer-session-lifecycle` conditions plus a fresh planning-oriented start in the current working directory with working planning docs under `docs/`
+- development bootstrap requires the `developer-session-lifecycle` conditions plus a fresh planning-oriented start and the required documentation and repo hygiene state when relevant
 - scaffold requires evidence for `docker compose up --build`, `run_tests.sh`, baseline logging/config, and when relevant the chosen frontend stack and UI approach being set intentionally
 - scaffold also requires safe env/config handling, no persisted local secrets, real migration/runtime foundations, and a usable local test environment in the current working directory when practical
 - 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
@@ -86,21 +107,28 @@ Use evidence such as Bead metadata, structured Bead comments, verification comma
 - module implementation requires module planning notes, module definition of done, relevant local verification for the changed area, and for applicable fullstack or UI work local Playwright evidence with screenshots, plus docs sync and review acceptance
 - module implementation also requires integration-seam verification against adjacent modules and cross-cutting concerns where relevant, and known release-facing or build failures block acceptance unless explicitly scoped out
 - module implementation acceptance should also challenge tenant isolation, path confinement, sanitized error behavior, and prototype residue when those concerns are in scope
-- integrated verification requires owner-run `docker compose up --build`, owner-run `run_tests.sh`, end-to-end, Playwright, prompt-alignment, README/runtime, and cross-module evidence
+- integrated verification entry requires owner-run `docker compose up --build`, owner-run `run_tests.sh`, end-to-end, Playwright, prompt-alignment, README/runtime, and cross-module evidence once development/coding is complete
+- integrated verification completion requires one more owner-run `docker compose up --build`, one more owner-run `run_tests.sh`, and the corresponding end-to-end and screenshot evidence before the phase can close
 - fullstack integrated verification must include Playwright coverage for every major flow, plus screenshots used to evaluate frontend behavior and UI quality along the flow using `frontend-design`
 - if a required flow cannot be exercised through the intended UI surface, treat that as incomplete implementation rather than acceptable E2E coverage
 - hardening requires security, maintainability, exploratory, and release-freeze evidence
+- hardening completion requires one owner-run `docker compose up --build` and one owner-run `run_tests.sh` on the hardened state before final evaluation begins
 - hardening must explicitly re-check secret handling, redaction, and frontend/backend observability hygiene
+- hardening must explicitly satisfy the documentation and repo hygiene policy in this file before final evaluation can begin
 - final evaluation readiness requires automated evaluation to be complete and triaged, with a clear go-to-packaging vs return-to-fixes decision
-- remediation requires accepted issue records plus rerun verification, and after post-evaluation remediation it requires an owner-run fresh `run_tests.sh` pass and Playwright rerun where applicable before re-acceptance
+- submission packaging readiness requires one final owner-run `docker compose up --build` and one final owner-run `run_tests.sh` on the final qualified state immediately before packaging
+- remediation requires accepted issue records plus rerun local verification and affected Playwright where applicable; if remediation materially reopens the integrated verification boundary, route it back through integrated verification before re-evaluation
 
 ## Hardening and pre-evaluation discipline
 
 When all planned modules are complete:
 
-- run integrated verification
+- run the owner-run milestone gate for development/coding completion and enter integrated verification
 - run hardening and exploratory testing
 - for fullstack applications, rerun Playwright coverage for major flows and inspect screenshots for frontend regressions or weak UX
+- run the documentation and repo-hygiene verification required by this file before final evaluation
+- close integrated verification only after its completion milestone gate has passed
+- close hardening only after its completion milestone gate has passed
 - enforce release-candidate freeze
 - allow only fixes, verification improvements, doc corrections, and packaging work
 - prepare the package and evidence cleanly before the final evaluation decision gate

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

@@ -0,0 +1,102 @@
+---
+name: verification-gates-v2
+description: Owner-side review, acceptance, rejection, and gate-interpretation rules for slopmachine-v2.
+---
+
+# Verification Gates v2
+
+Use this skill after development begins whenever you are reviewing work, deciding acceptance, or interpreting phase exits.
+
+## Usage rules
+
+- load this skill before review, acceptance, rejection, runtime gate interpretation, hardening readiness decisions, or broad-gate decisions
+- treat it as owner-side review and gate guidance, not developer-visible text
+- use this skill as the source of truth for owner-side verification, review pressure, and gate interpretation
+- outside the final human decision, do not pause execution for human approval while using this skill; continue reviewing, rejecting, fixing, and rerunning until the work qualifies
+
+## Documentation and repo hygiene
+
+- maintain the owner-managed external docs in parent-root `../docs/` from accepted clarification, accepted planning, accepted major implementation changes, and hardening verification
+- keep `README.md` codebase-specific, junior-friendly, and separate from the external docs set
+- do not allow `.env` files or env-file variants anywhere in the repo tree
+- do not allow a project that requires a preexisting `.env` file in the repo or package to start from scratch
+- if env-file format is needed at runtime, it must be generated ephemerally from Docker-provided runtime variables rather than stored in the repo or package
+
+## Review standard
+
+- do not accept fake tests, weak evidence, documentation drift, missing real surfaces, or unresolved release-facing failures
+- do not accept mocked APIs as integration evidence
+- do not accept placeholder or demo UI in product-facing flows
+- do not accept `.env` files or similar env-file artifacts
+- do not accept shallow Docker verification
+- do not accept happy-path-only implementation when failure paths matter
+- do not accept unsupported claims
+- do not accept work that looks complete but is not resilient
+- do not accept committed secrets, hardcoded sensitive values, or sloppy env handling
+- 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 Playwright evidence when the change affects real frontend behavior
+- do not accept prototype residue such as seeded credentials, weak demo defaults, login hints, or unsanitized user-facing error behavior
+- 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
+- do not accept frontend-bearing slice completion without checking production build health when the change materially affects frontend code or tooling
+- do not accept module completion that ignores integration seams or cross-cutting consistency with the existing system
+- do not accept end-to-end evidence that bypasses a required user-facing or admin-facing surface with direct API shortcuts
+
+## Cadence rule
+
+- use targeted local verification as the default during scaffold corrections, development, hardening, and remediation
+- reserve the broad Docker/full-suite path for the limited owner-run gate moments in the workflow budget
+- do not turn ordinary acceptance into repeated integrated-style gate runs
+
+## Verify-fix loop
+
+- inspect the result and evidence, not just the developer claim
+- 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 broad Docker or full-suite proof
+- 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 local runtime proof when relevant by starting the server locally and exercising the changed behavior directly rather than jumping to Docker-based proof
+- 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 fullstack or UI-bearing work, require local Playwright on affected flows plus screenshot review and explicit UI validation
+- 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
+
+## Broad-gate definition
+
+- a broad gate is an owner-run integrated verification boundary, not every ordinary phase change
+- a phase change alone does not automatically require a broad gate unless that phase exit explicitly calls for one
+- a broad gate normally means some combination of full clean runtime proof, the broad `run_tests.sh` path, and Playwright plus screenshot evidence when UI or fullstack flows exist
+- in v2, the workflow target is at most 3 broad owner-run verification moments across the whole cycle
+- ordinary planning, ordinary slice acceptance, and routine in-phase verification are not broad gates by default and should rely on targeted local verification unless the risk profile says otherwise
+
+## Runtime gate interpretation
+
+Use evidence such as internal metadata files, structured Beads comments, verification command results, and file/project-state checks.
+
+- clarification requires the `clarification-gate-v2` conditions plus explicit approval record
+- planning requires the `developer-session-lifecycle-v2` and planning-gate conditions plus a fresh planning-oriented start and the required documentation and repo hygiene state when relevant
+- scaffold requires evidence for the bounded scaffold gate, baseline logging/config, and when relevant the chosen frontend stack and UI approach being set intentionally
+- scaffold also requires safe env/config handling, no persisted local secrets, real migration/runtime foundations, and a usable local test environment in the current working directory when practical
+- 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 self-contained Compose namespacing, no unnecessary fragile `container_name` usage, and clean startup plus teardown behavior in the intended shared-environment model
+- module implementation requires module planning notes, module definition of done, relevant local verification for the changed area, and for applicable fullstack or UI work local Playwright evidence with screenshots, plus docs sync and review acceptance
+- 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
+- integrated verification entry requires one of the limited owner-run broad gate moments once development is complete
+- integrated verification completion requires explicit full-system evidence before the phase can close
+- fullstack integrated verification must include Playwright coverage for every major flow, plus screenshots used to evaluate frontend behavior and UI quality along the flow using `frontend-design`
+- if a required flow cannot be exercised through the intended UI surface, treat that as incomplete implementation rather than acceptable E2E coverage
+- hardening requires security, maintainability, exploratory, and release-freeze evidence
+- hardening must explicitly re-check secret handling, redaction, and frontend/backend observability hygiene
+- hardening must explicitly satisfy the documentation and repo hygiene policy in this file before final evaluation can begin
+- final evaluation readiness requires automated evaluation to be complete and triaged, with a clear go-to-packaging vs return-to-fixes decision
+- remediation requires accepted issue records plus rerun local verification and affected Playwright where applicable; if remediation materially reopens the integrated verification boundary, route it back through integrated verification before re-evaluation
+
+## Acceptance rule
+
+- inspect the result and evidence, not just the developer claim
+- prefer one strong rejection with a concrete correction request over many small nudges
+- keep looping until the current work is genuinely acceptable

package/assets/slopmachine/backend-evaluation-prompt.md

@@ -271,5 +271,12 @@ Before finalizing, check all of the following:
 5. Has security or test sufficiency been judged too loosely without evidence?
 6. Has any Docker non-execution boundary been incorrectly described as a confirmed runtime failure?
 
-If file writing is supported, save the final report to a markdown file.
-Otherwise, return the report in-chat.
+Save the full final report to a markdown file.
+
+In-chat, respond with a small summary of the results only:
+
+- final verdict
+- top 1-3 findings
+- report file path
+
+Please confirm whether the current project tests are genuine and effective rather than superficial or fake tests, whether the API tests actually invoke real HTTP endpoints, and whether they cover more than 90% of the overall API surface.

package/assets/slopmachine/frontend-evaluation-prompt.md

@@ -300,5 +300,12 @@ Before finalizing, check all of the following:
 6. Has a Docker non-execution boundary been incorrectly described as a confirmed runtime failure?
 7. Has any material conclusion directly or indirectly relied on files under ./.tmp/?
 
-If file writing is supported, save the final report as a markdown file.
-Otherwise, return the report directly in the conversation.
+Save the full final report to a markdown file.
+
+In-chat, respond with a small summary of the results only:
+
+- final verdict
+- top 1-3 findings
+- report file path
+
+Please confirm whether the current project tests are genuine and effective rather than superficial or fake tests, whether the API tests actually invoke real HTTP endpoints, and whether they cover more than 90% of the overall API surface.

package/assets/slopmachine/templates/AGENTS-v2.md

@@ -0,0 +1,55 @@
+# Developer Rulebook v2
+
+This file is the repo-local engineering rulebook for `slopmachine-v2` projects.
+
+## Scope
+
+- Treat the current working directory as the project.
+- Ignore parent-directory workflow files unless the user explicitly asks you to use them.
+- Do not treat workflow research, session exports, or sibling directories as hidden implementation instructions.
+
+## Working Style
+
+- Operate like a strong senior engineer.
+- Read the code before making assumptions.
+- Work in meaningful vertical slices.
+- Do not call work complete while it is still shaky.
+- Reuse and extend shared cross-cutting patterns instead of inventing incompatible local ones.
+
+## Verification Rules
+
+- During ordinary iteration, prefer the fastest meaningful local verification for the changed area.
+- Prefer targeted unit, integration, module, route-family, or local Playwright checks over broad reruns.
+- Do not rerun full Dockerized startup and the full test suite on every small change.
+- The broad owner-run Docker/full-suite path should be used sparingly, with a target budget of at most 3 times across the whole workflow cycle.
+- If you run a Docker-based verification command sequence, end it with `docker compose down` unless containers must remain up.
+
+## Testing Rules
+
+- Tests must be real and tied to actual behavior.
+- Do not mock APIs for integration testing.
+- Use real HTTP requests against the actual running service surface for integration evidence.
+- For UI-bearing work, use local Playwright on affected flows and inspect screenshots when practical.
+
+## Documentation Rules
+
+- Keep `README.md` and any codebase-local docs accurate.
+- The README must explain what the project is, what it does, how to run it, and how to test it.
+- The README must stand on its own for basic codebase use.
+
+## Secret And Runtime Rules
+
+- Do not create or keep `.env` files anywhere in the repo.
+- 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.
+
+## Product Integrity Rules
+
+- Do not leave placeholder, setup, debug, or demo content in product-facing UI.
+- If a real user-facing or admin-facing surface is required, build that surface instead of bypassing it with API shortcuts.
+- Treat missing real surfaces as incomplete implementation.
+
+## Rulebook Files
+
+- Do not edit `AGENTS.md` or other workflow/rulebook files unless explicitly asked.

package/assets/slopmachine/templates/AGENTS.md

@@ -6,7 +6,7 @@ This file is the developer-facing operating rulebook for project execution.
 
 - Treat the current working directory as the project.
 - Ignore files outside the current working directory unless the user explicitly asks you to use them.
-- Do not use parent-directory files as hidden requirements.
+- Do not use unrelated parent-directory files as hidden requirements.
 
 ## Working Style
 
@@ -26,19 +26,16 @@ This file is the developer-facing operating rulebook for project execution.
 
 ## Runtime And Verification Rules
 
-- A heavy gate is an owner-run integrated verification boundary, not every ordinary phase change.
-- Heavy gates normally include full clean runtime proof, full `run_tests.sh`, and Playwright plus screenshot evidence when UI or fullstack flows exist.
-- Heavy gates are expected at scaffold acceptance, integrated/full verification, and post-evaluation remediation re-acceptance.
-- Ordinary phase progression and module completion do not automatically mean rerunning every heavy-gate command.
 - Treat Docker as the main runtime contract.
-- `docker compose up --build` is the canonical startup path and must work when the project expects Dockerized execution.
+- `docker compose up --build` must work when the project expects Dockerized execution, but it is not the default per-turn verification command during normal iteration.
 - `run_tests.sh` is a required project test entrypoint and must exist and work.
 - After scaffold is established, do not rerun full `docker compose up --build` and `run_tests.sh` on every small implementation step.
 - During normal iteration, prefer the fastest meaningful local verification inside the current working directory using the project-appropriate test environment and tooling.
-- If the local test toolchain is missing, try to install or enable it before falling back to `run_tests.sh`.
-- Treat `docker compose up --build` and `run_tests.sh` as critical-gate verification commands, not normal per-turn iteration commands.
-- The workflow owner handles those expensive critical-gate runs; focus on strong local verification during normal work so the gate passes succeed cleanly.
-- After post-evaluation remediation, strengthen local verification and affected Playwright checks rather than rerunning every full gate command yourself unless explicitly required.
+- When runtime proof is needed during ordinary work, prefer starting and exercising the app locally instead of using Docker gate commands.
+- If the local test toolchain is missing, try to install or enable it; do not jump to `run_tests.sh` on ordinary turns just because local setup takes work.
+- The workflow owner runs `run_tests.sh` only at milestone boundaries: after scaffold, after development/coding is complete, after integrated verification is complete, after hardening is complete, and once more before final submission.
+- Do not rerun `docker compose up --build` or `run_tests.sh` on every small fix inside integrated verification; use local verification until the next milestone boundary is reached.
+- After post-evaluation remediation, strengthen local verification and affected Playwright checks rather than rerunning full gate commands yourself unless explicitly required.
 - Do not let unverified work accumulate.
 
 ## Testing Rules
@@ -46,6 +43,7 @@ This file is the developer-facing operating rulebook for project execution.
 - Tests must be real, meaningful, and tied to actual behavior.
 - Cover happy paths, failure paths, and realistic edge cases.
 - For API-bearing projects, prefer real endpoint invocation where practical.
+- Do not mock APIs for integration testing; integration evidence must use real HTTP requests against the actual running service surface.
 - For backend integration tests, prefer production-equivalent infrastructure when practical instead of a weaker substitute that can hide real defects.
 - For applicable frontend or fullstack work, run local Playwright against affected end-to-end flows during implementation and inspect screenshots to verify the UI actually matches.
 - Do not pad the test suite with superficial or fake tests.
@@ -53,6 +51,8 @@ This file is the developer-facing operating rulebook for project execution.
 
 ## Frontend Product Integrity
 
+- Unless the prompt, existing repository, or established stack clearly dictates otherwise, default frontend work to Tailwind CSS for styling and `shadcn/ui` for component primitives.
+- If the existing project already uses a different UI system, preserve and extend that system instead of forcing Tailwind CSS or `shadcn/ui` into it.
 - Do not place development, setup, scaffold, seed, or debug information in the product UI.
 - Do not add demo banners, `database is working` messages, scaffold-password hints, setup reminders, or similar developer-facing content to frontend screens.
 - If a screen exists, it should serve the real user or operator purpose it was created for.
@@ -61,12 +61,11 @@ This file is the developer-facing operating rulebook for project execution.
 ## Documentation Rules
 
 - Keep docs aligned with the current implementation.
-- During development, keep working technical docs under `docs/`.
-- Maintain a test-coverage document under `docs/` that explains the major flow coverage, the relevant test entry points, and any important coverage boundaries.
 - Do not add or keep tests that only assert that docs directories or docs files exist.
-- Delivery packaging may relocate docs, but that is not product behavior and should not be tested as application logic.
-- Update technical docs when behavior, architecture, interfaces, runtime steps, or verification expectations change.
-- The README must explain what the project is, how to run it, how to test it, and how to verify it.
+- Documentation structure outside the repo is not application behavior and should not be tested as application logic.
+- Keep `README.md` and any codebase-local docs accurate when behavior, runtime steps, or verification expectations change.
+- The README must explain what the project is, what it does, how to run it, and how to test it in a way that is friendly to a junior developer.
+- The README must stand on its own for basic codebase use and must not depend on separate external documentation for run/test basics.
 - Do not leave misleading docs in place after changing behavior.
 
 ## Engineering Quality Rules
@@ -78,10 +77,14 @@ This file is the developer-facing operating rulebook for project execution.
 
 ## Secret Handling Rules
 
+- Do not create, keep, or rely on `.env` files anywhere in the codebase.
+- Treat `.env`, `.env.local`, `.env.example`, and similar env-file variants as forbidden artifacts.
 - Do not persist local secrets anywhere in the repository.
 - Do not hardcode credentials, API keys, tokens, signing material, database passwords, certificate private keys, or similar sensitive values in code.
-- Keep committed env/config examples limited to placeholders or clearly non-production defaults.
-- If a real secret is needed, inject it through Docker-managed runtime configuration and keep it out of committed source files.
+- Do not use env files even for placeholders or setup examples.
+- The delivered repo and package must not require any preexisting `.env` file to start from scratch.
+- If environment variables are needed, rely on Docker-provided runtime variables or generate any required env-file format ephemerally at runtime from those variables.
+- If runtime generation is used, the generated env file must not be committed, packaged, or treated as a persistent project artifact.
 - Do not leak raw secrets into logs, docs, screenshots, telemetry, or operator-facing UI.
 - Treat frontend and backend observability paths as secret-sensitive by default and redact accordingly.
 

package/assets/slopmachine/tracker-init.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { spawn } from 'node:child_process'
+
+const targetInput = process.argv[2] || '.'
+const target = path.resolve(process.cwd(), targetInput)
+const trackerCommand = process.env.BR_COMMAND || 'br'
+
+function log(message) {
+  console.log(`[tracker-init] ${message}`)
+}
+
+function die(message) {
+  console.error(`[tracker-init] ERROR: ${message}`)
+  process.exit(1)
+}
+
+function run(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      env: options.env || process.env,
+      stdio: options.stdio || 'pipe',
+      shell: false,
+    })
+
+    let stdout = ''
+    let stderr = ''
+
+    if (child.stdout) child.stdout.on('data', (chunk) => { stdout += chunk.toString() })
+    if (child.stderr) child.stderr.on('data', (chunk) => { stderr += chunk.toString() })
+
+    if (options.input !== undefined && child.stdin) {
+      child.stdin.write(options.input)
+      child.stdin.end()
+    }
+
+    child.on('error', reject)
+    child.on('close', (code) => resolve({ code: code ?? 1, stdout, stderr }))
+  })
+}
+
+async function commandExists(command) {
+  const checker = process.platform === 'win32' ? 'where' : 'which'
+  const result = await run(checker, [command])
+  return result.code === 0
+}
+
+async function pathExists(targetPath) {
+  try {
+    await fs.access(targetPath)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function runTracker(args, options = {}) {
+  return run(trackerCommand, args, { cwd: target, ...options })
+}
+
+async function main() {
+  const trackerAvailable = trackerCommand !== 'br' ? await pathExists(trackerCommand) : await commandExists('br')
+  if (!trackerAvailable) {
+    die(`'${trackerCommand}' is not available. Install beads_rust first.`)
+  }
+
+  if (!(await pathExists(target))) {
+    die(`Target directory '${targetInput}' does not exist or is not accessible.`)
+  }
+
+  log(`Target: ${target}`)
+
+  const beadsDir = path.join(target, '.beads')
+  if (!(await pathExists(beadsDir))) {
+    log("Running 'br init --quiet'")
+    const initResult = await runTracker(['init', '--quiet'], {
+      env: { ...process.env, CI: '1' },
+    })
+    if (initResult.code !== 0) {
+      console.error(`${initResult.stdout}${initResult.stderr}`.trim())
+      die("'br init' failed. Review output above.")
+    }
+  } else {
+    log('Found existing .beads; skipping init to avoid destructive re-initialization')
+  }
+
+  log("Running 'br sync --flush-only'")
+  const syncResult = await runTracker(['sync', '--flush-only'], {
+    env: { ...process.env, CI: '1' },
+  })
+  if (syncResult.code !== 0) {
+    console.error(`${syncResult.stdout}${syncResult.stderr}`.trim())
+    die("'br sync --flush-only' failed. Review output above.")
+  }
+
+  log('Success: tracker initialized and JSONL exported')
+}
+
+main().catch((error) => {
+  die(error instanceof Error ? error.message : String(error))
+})

package/assets/slopmachine/workflow-init-v2.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { spawn } from 'node:child_process'
+
+const targetInput = process.argv[2] || '.'
+const target = path.resolve(process.cwd(), targetInput)
+const beadsCommand = process.env.BR_COMMAND || 'br'
+
+function log(message) {
+  console.log(`[workflow-init-v2] ${message}`)
+}
+
+function die(message) {
+  console.error(`[workflow-init-v2] ERROR: ${message}`)
+  process.exit(1)
+}
+
+function run(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      env: options.env || process.env,
+      stdio: options.stdio || 'pipe',
+      shell: false,
+    })
+
+    let stdout = ''
+    let stderr = ''
+
+    if (child.stdout) child.stdout.on('data', (chunk) => { stdout += chunk.toString() })
+    if (child.stderr) child.stderr.on('data', (chunk) => { stderr += chunk.toString() })
+
+    child.on('error', reject)
+    child.on('close', (code) => resolve({ code: code ?? 1, stdout, stderr }))
+  })
+}
+
+async function pathExists(targetPath) {
+  try {
+    await fs.access(targetPath)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function commandExists(command) {
+  const checker = process.platform === 'win32' ? 'where' : 'which'
+  const result = await run(checker, [command])
+  return result.code === 0
+}
+
+async function runBeads(args, options = {}) {
+  return run(beadsCommand, args, { cwd: target, ...options })
+}
+
+async function main() {
+  const beadsAvailable = beadsCommand !== 'br' ? await pathExists(beadsCommand) : await commandExists('br')
+  if (!beadsAvailable) {
+    die(`'${beadsCommand}' is not available. Install beads_rust first.`)
+  }
+
+  if (!(await pathExists(target))) {
+    die(`Target directory '${targetInput}' does not exist or is not accessible.`)
+  }
+
+  log(`Target: ${target}`)
+
+  const beadsDir = path.join(target, '.beads')
+  if (!(await pathExists(beadsDir))) {
+    log("Running 'br init --quiet'")
+    const initResult = await runBeads(['init', '--quiet'], {
+      env: { ...process.env, CI: '1' },
+    })
+    if (initResult.code !== 0) {
+      console.error(`${initResult.stdout}${initResult.stderr}`.trim())
+      die("'br init' failed. Review output above.")
+    }
+  } else {
+    log('Found existing .beads; skipping init to avoid destructive re-initialization')
+  }
+
+  log("Running 'br sync --flush-only'")
+  const syncResult = await runBeads(['sync', '--flush-only'], {
+    env: { ...process.env, CI: '1' },
+  })
+  if (syncResult.code !== 0) {
+    console.error(`${syncResult.stdout}${syncResult.stderr}`.trim())
+    die("'br sync --flush-only' failed. Review output above.")
+  }
+
+  log('Success: beads_rust workspace initialized and JSONL exported')
+}
+
+main().catch((error) => {
+  die(error instanceof Error ? error.message : String(error))
+})

package/package.json

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