theslopmachine 0.4.0 → 0.4.2

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

@@ -1,34 +1,30 @@
 ---
 name: beads-operations
-description: Tracker workflow mutation rules, state-transition discipline, and direct command reference for repo-cwd blueprint-driven orchestration using beads_rust.
+description: Beads mutation and lifecycle-transition rules for slopmachine.
 ---
 
-# Tracker Operations
+# Beads Operations
 
-Use this skill whenever you need to inspect, create, update, or transition tracker state.
+Use this skill whenever you mutate Beads state.
 
-## Usage rules
+## Transition discipline
 
-- Load this skill before making tracker mutations if you are not already actively operating within the tracked workflow state flow.
-- Treat this as the operational source of truth for tracker transitions and command usage.
-- Do not improvise state mutations from memory when precise tracker changes matter.
+When a root phase changes:
 
-## Tracker update discipline
+1. verify exit conditions from evidence
+2. add final phase evidence comments
+3. close the current root phase
+4. update metadata files to the new phase state
+5. open the next root phase
+6. add a `STATE:` transition comment
 
-When phases change, mutate tracker state in this order:
+## Rules
 
-1. verify exit conditions from evidence
-2. append final evidence comments for the closing phase
-3. close the current phase only after evidence exists
-4. update `../.ai/metadata.json` to the next workflow state and current phase item id
-5. update `../.ai/metadata.json` and `../metadata.json` fields that changed as part of the transition:
-   - set `clarification_approved=true` only when clarification is actually approved
-   - set `awaiting_human=true` only at the two allowed human-stop points: initial clarification approval and final evaluation decision
-   - increment `remediation_round` only when entering a new remediation cycle after failed manual evaluation
-    - keep parent-root `../metadata.json` aligned on project facts such as prompt text, project type, session id, and selected stack fields when they become known or change
-6. set the next phase status to `in_progress` or `blocked`
-7. append a `STATE:` transition comment
-8. append a `SESSION:` comment if the developer session was created, resumed, or materially changed
+- enter the next phase before real work for that phase begins
+- 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
 
 ## Structured comment prefixes
 
@@ -46,31 +42,41 @@ Use comments with fixed prefixes such as:
 ## Dependency rules
 
 - use explicit dependencies only for real sibling or cross-phase gating
-- do not add explicit dependencies from a parent bead to its own child bead
-- technical blockers may set tracker items to `blocked`, but they must not create new human-stop points unless the workflow is at the initial clarification approval or final evaluation decision
+- do not add explicit dependencies from a parent Beads item to its own child Beads item
+- technical blockers may set Beads items to `blocked`, but they must not create new human-stop points unless the workflow is at the initial clarification approval or final human decision
 
 ## Forbidden workflow-state shortcuts
 
 - do not use QMD as the workflow state system
-- do not use tracker-local config or ad hoc notes as the primary workflow-state mechanism
+- do not use Beads-local config or ad hoc notes as the primary workflow-state mechanism
 
 ## Direct command reference
 
 Use these `br` commands directly without needing a help lookup first:
 
-- `br list` -> view current backlog and statuses
-- `br ready` -> list actionable unblocked work
-- `br blocked` -> inspect blocked work
-- `br show <id>` -> inspect one task item in detail
-- `br create "Title"` -> create a new task item
-- `br update <id> --status <status>` -> change task item status
-- `br update <id> --parent <parent-id>` -> reparent a task item when needed
-- `br dep add <blocked-id> <blocker-id> --type blocks` -> add a blocking dependency edge
-- `br dep add <child-id> <parent-id> --type parent-child` -> represent hierarchy explicitly when needed
-- `br dep list <id>` -> inspect dependency relationships
-- `br comments add <id> "..."` -> append structured history or evidence
-- `br comments <id>` -> inspect task-item comment history
-- `br close <id>` -> mark work complete
-- `br reopen <id>` -> reopen previously closed work
+- `br list`
+- `br ready`
+- `br blocked`
+- `br show <id>`
+- `br create "Title"`
+- `br update <id> --status <status>`
+- `br update <id> --parent <parent-id>`
+- `br dep add <blocked-id> <blocker-id> --type blocks`
+- `br dep add <child-id> <parent-id> --type parent-child`
+- `br dep list <id>`
+- `br comments add <id> "..."`
+- `br comments <id>`
+- `br close <id>`
+- `br reopen <id>`
 
 If you truly need a command outside this core set, use `br -h` or `br <command> -h` only then.
+
+## Useful comment prefixes
+
+- `STATE:`
+- `APPROVAL:`
+- `VERIFY:`
+- `ISSUE:`
+- `SESSION:`
+- `HANDOFF:`
+- `ARTIFACT:`

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

@@ -1,17 +1,26 @@
 ---
 name: clarification-gate
-description: Clarification decomposition, safe-default locking, and clarification-prompt validation workflow for repo-cwd blueprint-driven projects.
+description: Clarification decomposition, ambiguity handling, safe-default locking, and prompt-faithfulness validation for slopmachine.
 ---
 
 # Clarification Gate
 
-Use this skill only during clarification and understanding work before tracked development begins.
+Use this skill only during `P1 Clarification`.
+
+## Goals
+
+- make the scope clear enough for planning to start cleanly
+- resolve or safely lock material ambiguities
+- prepare a strong developer-facing clarification prompt
+- prevent prompt drift or scope narrowing
 
 ## Usage rules
 
-- Load this skill during initial clarification and whenever clarification must be revisited before development starts.
-- Treat it as internal clarification workflow guidance, not developer-visible text.
-- Do not start tracked development until this gate is satisfied and the required approval exists.
+- enter `P1` before the first real clarification draft or validation pass
+- keep clarification work inside `P1`
+- treat this as internal clarification workflow guidance, not developer-visible text
+- do not start planning or developer launch while clarification is still active
+- stop for human approval only after the clarification artifact is ready and validated
 
 ## Clarification standard
 
@@ -23,7 +32,7 @@ Use this skill only during clarification and understanding work before tracked d
 - 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
-- use clarification to sharpen the build and improve output quality only when that improvement stays fully consistent with the prompt's intent
+- use clarification to sharpen the build and improve output quality only when that improvement stays fully consistent with the prompt intent
 - do not start tracked development until the human approval step is complete
 
 ## Clarification discipline
@@ -36,23 +45,79 @@ Use this skill only during clarification and understanding work before tracked d
 - never use defaults that drift from the original prompt
 - do not use quick, loose, or simplifying assumptions that shrink what the prompt asked for
 - do not guess through material ambiguity
+- do not expand the clarification artifact just to exhaust every minor edge case when the scope is already clear enough to plan correctly
+- once the core scope is understood, prefer a compact clarification record plus explicit safe defaults over a giant exhaustive rewrite
+
+## Required outputs
+
+- working clarification record that will become `../docs/questions.md`
+- developer-facing clarification prompt in `../.ai/clarification-prompt.md`
+- explicit list of safe defaults and resolved ambiguities
+
+## `questions.md` contract
+
+`../docs/questions.md` is not a general project summary.
+
+It exists only for prompt items that needed interpretation because they were unclear, incomplete, or materially ambiguous.
+
+Each entry should answer this structure:
+
+1. what was unclear from the original prompt
+2. how you interpreted it
+3. what decision or solution you chose for it
+4. why that choice is prompt-faithful and reasonable
+
+Keep the file narrow and explicit.
+
+Do not use `questions.md` for:
+
+- a full restatement of the entire prompt
+- broad planning notes
+- general project requirements that were already clear
+- implementation details that belong in planning or design docs
+
+Preferred entry shape:
+
+```md
+## Item N: <short ambiguity title>
+
+### What was unclear
+<the exact ambiguity or missing detail>
+
+### Interpretation
+<how it was interpreted>
+
+### Decision
+<the chosen resolution or safe default>
+
+### Why this is reasonable
+<brief justification tied to prompt faithfulness>
+```
+
+If nothing material was unclear, keep `questions.md` minimal rather than inventing content.
 
 ## Clarification-prompt validation loop
 
-- compare the original prompt and the prepared clarification prompt using a fresh ephemeral `General` session, never the developer session
-- build one self-contained validation prompt block for that `General` session every time
-- include the full original prompt text, the full current questions or clarification record, and the full current `../.ai/clarification-prompt.md` in that block
+- compare the original prompt and the prepared clarification prompt using one dedicated `General` validation session, never the developer session
+- do not create a new validation session for every retry unless the session became unusable or a fundamental misunderstanding requires a clean restart
+- on the first validation pass, build one self-contained validation prompt block for that `General` session
+- on that first pass, include the full original prompt text, the full current questions or clarification record, and the full current `../.ai/clarification-prompt.md`
 - do not use placeholders such as `same as previous`, `from context`, `see above`, or `latest artifact`
 - ask that `General` session whether the clarification prompt deviates from, weakens, narrows, or violates the original prompt in any way
 - require it to judge whether the clarification prompt is a genuine improvement in execution quality while remaining faithful to the original intent
-- if mismatches or prompt drift are found, revise the questions record and clarification prompt, then build a newly composed full validation block and run the check again
-- do not require perfection, but do require that the original prompt is not being violated
+- if the validator suggests real fixes, patch the existing questions record and clarification prompt directly; do not restart the clarification phase from scratch unless the validator found a fundamental scope misunderstanding
+- treat validator output as a correction list, not as a reason to regenerate giant clarification blocks repeatedly
+- when rerunning validation in the same validator session, send only the improved clarification payload and the concrete fixes you made; do not resend the original prompt block if the session already has that context
+- rerun validation only after applying the concrete fixes that matter
+- keep the validation loop bounded and intentional; prefer one strong pass plus a small number of revision cycles over repeated loose churn
+- once prompt-faithfulness is satisfied and the remaining notes are minor or cosmetic, stop iterating and proceed
 - only treat the clarification prompt as approved for developer use after this validation loop passes and your own review agrees
 - requesting human approval before this validation loop passes is illegal
 
 ## Exit conditions
 
-- accepted questions/clarification record exists and will later become `../docs/questions.md`
-- approved `../.ai/clarification-prompt.md` exists
+- 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
 - prompt drift has been checked and rejected
-- the required human approval is present
+- human approval exists

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

@@ -1,28 +1,40 @@
 ---
 name: developer-session-lifecycle
-description: Startup, primary developer-session persistence, recovery, and initial project structure rules for repo-cwd tracked development.
+description: Startup, resume detection, metadata consistency, and developer-session recovery rules for slopmachine.
 ---
 
 # Developer Session Lifecycle
 
-Use this skill during startup, tracked developer-session creation, and recovery.
+Use this skill during `P0 Intake and Setup` and whenever startup or recovery state is uncertain.
+
+## Purpose
+
+- detect whether the run is new or resumed
+- initialize or recover workflow metadata consistently
+- initialize the planned bounded developer-session slots
+- recover the current active developer session when one already exists
 
 ## Usage rules
 
-- Load this skill before starting the main developer session.
-- Load it again during any recovery or session-consistency check.
-- Treat it as internal orchestration guidance, not developer-visible text.
-- outside the initial clarification approval stop, do not use this skill to create extra pause points; startup should continue directly into development bootup once approval exists
+- keep startup and recovery in one skill; both begin from the same state inspection problem
+- treat this as internal orchestration guidance, not developer-visible text
+- do not launch the developer during `P0` or `P1`
+- do not use this skill to create extra approval stops beyond the two allowed human gates
+
+## State inspection sequence
+
+Inspect:
+
+- Beads root state and current phase
+- `../.ai/metadata.json`
+- `../metadata.json`
+- existing session comments or recorded session ids
 
-## Main developer session
+Decide whether the run is:
 
-- use the current working directory as the live codebase and start the fresh developer session in it
-- ensure the parent project root has the required supporting structure, especially `../sessions/`
-- record the developer session id immediately in the tracker and `.ai/metadata.json`
-- persist the developer session id in more than one durable place
-- reuse that same session throughout development and remediation whenever possible
-- if the developer session crashes, resume it and continue the same work loop
-- if the owner process crashes, recovery happens externally; when restarted, recover from state and continue
+- a fresh startup
+- a resumed run with consistent state
+- a run needing consistency repair before it can continue
 
 ## Startup contract
 
@@ -42,15 +54,38 @@ Optional startup inputs may include:
 1. receive the prompt and stack context
 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 tracker items
+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. start the main developer session
-9. send `Let's plan this project: <original-prompt>` as the first message in that session
-10. wait for the developer's first exchange
-11. send the approved clarification prompt as the next guidance message
-12. continue orchestration from there
+8. initialize the bounded developer-session slots
+9. start the build 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
+12. send the approved clarification prompt as the second owner message in that same session
+13. only after that second message, continue with the normal planning conversation
+
+## First developer-session handshake
+
+The first bounded developer session must begin in this exact order:
+
+1. owner starts the build developer session
+2. owner sends: `lets plan this <original-prompt>`
+3. developer responds
+4. owner sends the approved clarification prompt
+5. planning proceeds from there
+
+Do not skip the initial planning opener.
+Do not send the clarification prompt first.
+Do not merge those two messages into one.
+
+## Required startup outputs
+
+- root workflow state exists
+- `../.ai/metadata.json` exists
+- `../metadata.json` exists
+- planned developer session slots are initialized
+- required parent-root directories exist
 
 ## Metadata and workflow files
 
@@ -59,16 +94,34 @@ Optional startup inputs may include:
 - the project artifact metadata file is `../metadata.json`
 - do not use `../metadata.json` as internal workflow scratch state
 
-Required internal workflow fields in `../.ai/metadata.json`:
+## Suggested metadata fields
 
-- `workflow_state`
-- `current_phase_item`
-- `session_id`
-- `clarification_approved`
+Track at least:
+
+- `current_phase`
 - `awaiting_human`
+- `clarification_approved`
 - `remediation_round`
+- `clarification_validator_session_id`
+- `evaluation_pass`
+- `backend_evaluation_session_id`
+- `frontend_evaluation_session_id`
+- `last_evaluation_session_id`
+- `passed_evaluation_tracks`
+- `developer_sessions`
+- `active_developer_session_index`
+
+Each planned developer session record should include enough to recover it later, such as:
+
+- `index`
+- `label`
+- `phase_group`
+- `session_id`
+- `status`
+- `handoff_in`
+- `handoff_out`
 
-Required project metadata fields in `../metadata.json`:
+Required project metadata fields in `../metadata.json` when relevant:
 
 - `prompt`
 - `project_type`
@@ -83,24 +136,33 @@ Required project metadata fields in `../metadata.json`:
 - 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
+
+Track up to three planned developer sessions:
+
+1. build
+2. stabilization
+3. remediation
+
+Later session slots may remain unused if the workflow never needs them.
+
 ## Initial structure rule
 
 - parent-root `../docs/` is the owner-maintained external documentation directory
-- do not treat repo-local `docs/` as the active documentation location in `v3`
 - parent-root `../sessions/` is the session artifact directory for exported conversation traces
+- do not treat repo-local `docs/` as the active external documentation location
 
 ## Recovery rule
 
-- orchestrator restart is handled externally
-- developer-session restart is your responsibility
-- on recovery, read `../.ai/metadata.json`, `../metadata.json`, current phase tracker item, latest `SESSION:` comment, latest unresolved `ISSUE:` comments, and any persistent session record before continuing
-- treat resume as deterministic state recovery, not guesswork
+- if session records disagree, stop and resolve the inconsistency before continuing
+- if the current phase already has an active developer session, recover that session instead of silently creating a new one
+- treat resume as deterministic recovery, not guesswork
+- on recovery, read `../.ai/metadata.json`, `../metadata.json`, current phase Beads item, latest `SESSION:` comment, latest unresolved `ISSUE:` comments, and any persistent session record before continuing
 
 ## Session persistence rule
 
-- store the main developer session id in the root tracker item comments using `SESSION:`
+- store the active developer session id in Beads comments using `SESSION:`
 - mirror it in `../.ai/metadata.json`
-- mirror it in parent-root `../metadata.json` as `session_id`
-- once created, treat that session id as locked unless an explicit reset policy is introduced later
+- mirror the active session id in parent-root `../metadata.json` as `session_id`
 - if these records disagree, stop and resolve the inconsistency before continuing
-- do not silently create a replacement main developer session if the existing one can still be resumed
+- do not silently create a replacement developer session if the intended existing one can still be resumed

package/assets/skills/{development-guidance-v2 → development-guidance}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: development-guidance-v2
-description: Developer-facing slice execution and local verification guidance for slopmachine-v2.
+name: development-guidance
+description: Developer-facing slice execution and local verification guidance for slopmachine.
 ---
 
-# Development Guidance v2
+# Development Guidance
 
 Use this skill during `P4 Development` before prompting the developer.
 
@@ -36,7 +36,7 @@ Use this skill during `P4 Development` before prompting the developer.
 - do not leave computed-but-unrendered or partially surfaced requirement behavior in place
 - do not treat a module as complete when a meaningful user-facing, release-facing, production-path, or build verification is known to be failing unless the owner explicitly scopes that check out
 - use the `frontend-design` skill for frontend component or page work
-- use the `frontend-design` skill during frontend/UI verification when reviewing Playwright screenshots and tightening the interface
+- use the `frontend-design` skill during web or desktop UI verification when reviewing screenshots and tightening the interface
 - do not hardcode secrets or persist local sensitive values in the repo while implementing
 - explain behavior changes clearly enough that the documentation discipline can be satisfied accurately
 - verify the module against its planned behavior before trying to move on
@@ -45,11 +45,14 @@ Use this skill during `P4 Development` before prompting the developer.
 ## Verification model
 
 - use targeted local verification by default
-- use local Playwright on affected flows when UI is material
-- avoid broad Docker/full-suite commands during ordinary slice work
+- use the selected stack's local UI/E2E tool on affected flows when UI is material
+- avoid broad project-standard gate commands during ordinary slice work
 - prefer fast local language-native or framework-native test commands for the changed area during normal iteration
 - set up and use the local test environment inside the current working directory so normal verification does not depend on hidden global tooling assumptions
 - if the local toolchain is missing, try to install or enable it before falling back to the broad gate path
+- for web UI projects, default local UI/E2E verification to Playwright when that stack is in use
+- 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
 
 ## Quality rules

package/assets/skills/{evaluation-triage-v2 → evaluation-triage}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: evaluation-triage-v2
-description: Owner-side evaluation report triage rules for slopmachine-v2.
+name: evaluation-triage
+description: Owner-side evaluation report triage rules for slopmachine.
 ---
 
-# Evaluation Triage v2
+# Evaluation Triage
 
 Use this skill during `P7 Evaluation and Triage` after evaluation reports exist.
 
@@ -15,15 +15,54 @@ Use this skill during `P7 Evaluation and Triage` after evaluation reports exist.
 - do not enter remediation just because a report found something; enter it only when the accepted findings justify it
 - if no remediation is needed, move directly to the final human decision
 
+## Non-negotiable evaluation buckets
+
+These areas are hard gates and should not be passed with known meaningful failures:
+
+1. prompt compliance
+2. requirement fulfillment / delivery completeness
+3. security-critical flaws
+
+If evaluation finds a real issue in one of those buckets, the default outcome is remediation, not leniency.
+
+Do not wave through:
+
+- prompt drift or meaningful requirement mismatch
+- missing core flows or partial delivery of prompt-critical functionality
+- real security defects involving auth, authorization, ownership, isolation, exposure, or secret handling
+
+## Leniency buckets
+
+These areas may pass with minor residual issues when the product is still clearly acceptable overall:
+
+1. testing cases / test sufficiency
+2. engineering architecture / engineering quality
+3. aesthetics
+
+Leniency is allowed only when the issue is:
+
+- minor in impact
+- not hiding a likely blocker in another bucket
+- not undermining overall confidence in the delivered product
+
+High-severity findings in these leniency buckets may still be passed when they are not materially relevant to actual acceptance readiness, but that should be a deliberate exception backed by direct evidence.
+
+If the hard gates pass cleanly, the leniency buckets should usually not force remediation unless the issue is a true `Blocker` or a materially relevant `High` finding.
+
 ## Triage rules
 
 - read both reports and merge the findings into one explicit triage set before deciding what happens next
 - use the evaluator priority ordering directly when triaging findings unless stronger direct evidence says otherwise
-- any finding marked `Blocker` or `High` should normally be returned for remediation
+- any finding in the non-negotiable buckets should normally be returned for remediation if it is real
+- findings marked `Blocker` should normally be returned for remediation
+- findings marked `High` should normally be returned for remediation unless they fall in a leniency bucket and your direct evidence shows they are not materially relevant to acceptance
 - findings marked `Medium` may be passed in limited cases, but should usually be fixed when they materially improve confidence, correctness, or acceptance readiness
 - findings marked `Low` may be passed without remediation
 - do not treat complaints about test coverage depth, unverifiable tests, or evaluator inability to confirm a test path as automatic blockers by themselves
 - if your own direct evidence shows the tests run and the coverage is acceptable for qualification, defend the project and pass those findings instead of automatically remediating
+- minor engineering-architecture quality issues may pass if the system is still structurally credible and maintainable overall
+- minor aesthetics issues may pass if the UI is still clearly usable and credible for the actual use case
+- if prompt compliance, requirement fulfillment, and security all pass, testing/engineering/aesthetics findings should generally be treated more leniently unless they are blocking or materially high-risk
 - if a report says it could not verify some behavior because of environment limits or avoidable verification setup issues, first decide whether you can remove that constraint and rerun the evaluation in a cleaner state
 - if the evaluator could not verify something but your own verified evidence already shows the behavior is acceptable, do not treat that as an automatic remediation trigger
 - challenge weak, random, or overreaching findings using your stronger project context and direct codebase knowledge