theslopmachine 0.4.0 → 0.4.2

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

@@ -1,82 +0,0 @@
----
-name: beads-operations-v2
-description: Beads mutation and lifecycle-transition rules for slopmachine-v2.
----
-
-# Beads Operations v2
-
-Use this skill whenever you mutate Beads state.
-
-## Transition discipline
-
-When a root phase changes:
-
-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
-
-## Rules
-
-- 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
-
-Use comments with fixed prefixes such as:
-
-- `STATE:`
-- `APPROVAL:`
-- `SESSION:`
-- `ARTIFACT:`
-- `VERIFY:`
-- `DECISION:`
-- `ISSUE:`
-- `HANDOFF:`
-
-## Dependency rules
-
-- use explicit dependencies only for real sibling or cross-phase gating
-- 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 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`
-- `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-v2/SKILL.md

@@ -1,74 +0,0 @@
----
-name: clarification-gate-v2
-description: Clarification decomposition, ambiguity handling, safe-default locking, and prompt-faithfulness validation for slopmachine-v2.
----
-
-# Clarification Gate v2
-
-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
-
-- 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
-
-- preserve the full original prompt text in parent-root `../metadata.json` under `prompt`
-- 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`
-- 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 intent
-- do not start tracked development until the human approval step is complete
-
-## Clarification discipline
-
-- clarification must be thorough, not superficial
-- ask targeted questions for material ambiguity
-- lock decisions that are safe defaults when they do not need human choice
-- implementation difficulty is not a reason to narrow requirements when a stronger prompt-faithful default is still safe
-- prefer resolving uncertainty into stronger engineering direction rather than carrying vague assumptions forward
-- 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
-
-## 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
-
-## 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
-- 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
-- keep the validation loop bounded and intentional; prefer one strong pass plus a small number of revision cycles over repeated loose churn
-- 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
-
-- 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
-- human approval exists

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

@@ -1,148 +0,0 @@
----
-name: developer-session-lifecycle-v2
-description: Startup, resume detection, metadata consistency, and developer-session recovery rules for slopmachine-v2.
----
-
-# Developer Session Lifecycle v2
-
-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
-
-- 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
-
-Decide whether the run is:
-
-- a fresh startup
-- a resumed run with consistent state
-- a run needing consistency repair before it can continue
-
-## Startup contract
-
-Expect to start from:
-
-- a project prompt
-- tech stack information when it is not already clear from the prompt
-
-Optional startup inputs may include:
-
-- task id
-- project type
-- explicit constraints or preferences
-
-## Startup flow
-
-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 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
-9. start the build developer session only after `P2` is ready to begin
-10. send `Let's plan this project: <original-prompt>` as the first message in that session
-11. wait for the developer's first exchange
-12. send the approved clarification prompt as the next guidance message
-13. continue orchestration from there
-
-## 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
-
-- the internal workflow mirror is `../.ai/metadata.json`
-- the internal clarification artifact is `../.ai/clarification-prompt.md`
-- the project artifact metadata file is `../metadata.json`
-- do not use `../metadata.json` as internal workflow scratch state
-
-## Suggested metadata fields
-
-Track at least:
-
-- `current_phase`
-- `awaiting_human`
-- `clarification_approved`
-- `remediation_round`
-- `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` when relevant:
-
-- `prompt`
-- `project_type`
-- `frontend_language`
-- `backend_language`
-- `database`
-- `session_id`
-- `frontend_framework`
-- `backend_framework`
-
-- maintain `../metadata.json` as a real project artifact from the beginning of the workflow
-- 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
-- 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
-
-- 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 active developer session id in Beads comments using `SESSION:`
-- mirror it in `../.ai/metadata.json`
-- 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 developer session if the intended existing one can still be resumed

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

@@ -1,57 +0,0 @@
----
-name: final-evaluation-orchestration-v2
-description: Evaluation execution rules for slopmachine-v2.
----
-
-# Final Evaluation Orchestration v2
-
-Use this skill only during `P7 Evaluation and Triage`.
-
-## Usage rules
-
-- load this skill only during final evaluation and evaluation-driven remediation decisions
-- treat it as internal orchestration guidance
-- do not let evaluator findings automatically override your triage judgment
-
-## Prompt sources
-
-- `~/backend-evaluation-prompt.md`
-- `~/frontend-evaluation-prompt.md`
-
-## Evaluation execution rules
-
-- run backend and frontend evaluation in separate fresh `General` sessions
-- compose the evaluation prompts yourself; do not tell the evaluator to read prompt files on its own
-- use the original project prompt from metadata
-- read the respective evaluation prompt file contents yourself before launching evaluation
-- compose each evaluation request yourself as one large final prompt block
-- prefix each evaluation request with a clear instruction that the reviewer must work in the current project directory and evaluate that delivered project
-- inject the full original project prompt into the `{prompt}` placeholder for the chosen evaluation prompt content
-- 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
-- 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
-- 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
-
-## Remediation loop
-
-- route accepted blocking issues back into the active remediation developer-session slot 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
-  - Playwright where applicable, with fresh screenshots
-- if remediation materially reopens an owner-run broad milestone boundary, route the project back to that boundary before re-evaluation instead of treating every remediation pass as an automatic broad rerun moment
-- keep the remediation loop bounded and explicit so you never lose track of the active evaluation round or the accepted issue set
-- remember the external process allows a maximum of 3 repair rounds
-
-## Boundaries
-
-- this phase is owner-side analysis, not the final human decision gate
-- do not create extra human pauses while evaluation and triage are still active

package/assets/skills/get-overlays/SKILL.md

@@ -1,228 +0,0 @@
----
-name: get-overlays
-description: Loads the developer phase overlays so the workflow owner can extract only the relevant guidance for the current implementation phase without naming workflow internals to the developer.
----
-
-# Get Overlays
-
-Use this skill when you need the detailed developer overlay guidance for one of the active implementation phases.
-
-## Usage rules
-
-- Load this skill when entering an overlay-backed developer phase or when switching to a different overlay-backed developer phase.
-- Do not mention the skill or the word `overlay` to the developer.
-- Treat this content as internal scaffolding for composing a natural developer message.
-- Pass only the relevant guidance for the current engineering step, not the whole section verbatim unless the moment truly needs it.
-- Prefer short, natural teammate-style prompts.
-
-## Cross-Cutting Documentation Discipline
-
-- the owner maintains external docs under parent-root `../docs/`
-- the developer should keep `README.md` and any codebase-local docs accurate for repo-local use
-- planning and implementation guidance should stay explicit enough that owner-maintained external docs can be updated accurately
-- verification and hardening should check both `README.md` and the owner-maintained external docs against implementation reality
-- `README.md` must stay codebase-specific and must not become an index or explanation of the external docs set
-
-## Cross-Cutting Env-File Discipline
-
-- never create or keep `.env` files anywhere in the repo tree
-- do not allow committed `.env` files even as placeholders or examples
-- keep real secrets out of the repository and rely on Docker-provided runtime variables for sensitive values
-- if the stack requires env-file format at runtime, generate it ephemerally from Docker-provided runtime variables rather than storing it in the repo or package
-- verify the delivered project can start from scratch without any preexisting `.env` file in the repo or package
-
-## Phase mapping
-
-- `P2 Development Bootstrap and Planning` -> `Planning And Design`
-- `P3 Scaffold and Foundation` -> `Scaffold And Foundation`
-- `P4 Module Implementation` -> `Module Implementation`
-- `P5 Ongoing Verification` -> `Verification And Review`
-- `P6 Integrated Verification` -> `Verification And Review`
-- `P7 Hardening` -> `Hardening`
-- `P9 Remediation` -> `Remediation`
-- `P10 Submission Packaging` -> `Packaging Preparation`
-
-## Planning And Design
-
-- start from the actual project prompt and build the plan from there
-- carry the settled project requirements forward consistently as you plan
-- identify the hard non-negotiable requirements early and do not quietly trade them away for implementation convenience
-- when planning technical items that depend on a library, framework, API, or tool, check Context7 documentation first for authoritative usage details
-- when planning needs targeted outside research beyond direct documentation, use Exa web search next
-- use technical research to strengthen concrete planning decisions, interfaces, constraints, and verification strategy rather than leaving them vague
-- break the problem into explicit requirements, constraints, flows, boundaries, and edge cases
-- map each meaningful requirement to its owning module, visible UI/API surface, failure behavior, test target, and final acceptance check
-- make the planning explicit enough that the owner can maintain external design notes and API/spec docs accurately when relevant
-- keep the spec focused on required behavior rather than turning it into a progress or completion narrative
-- define major modules as meaningful delivery units, not arbitrary folders
-- for fullstack work, map frontend surfaces, routes, components, and state boundaries to the backend modules and contracts that support them
-- for fullstack work, make the frontend-to-backend crosswalk explicit enough that each major route, page, component group, or state boundary has a defined supporting backend module, endpoint, and data shape
-- when the prompt says behavior is configurable, plan the real configuration surface, data model, permissions, and operator flow rather than treating configurability as an implementation detail to invent later
-- when a feature must be admin-manageable or operator-manageable, plan the real usable UI surface for that management flow, not just the backing API or data model
-- define failure paths, permissions, validation, logging, runtime assumptions, and test strategy before coding
-- for complex security, offline, sync, authorization, or data-governance features, define what `done` means across all prompt-promised dimensions rather than stopping at a partial foundation or hook layer
-- define shared lifecycle and state models when the product has meaningful workflow state, and keep those models aligned across design notes and API/spec notes
-- require cross-document consistency so design, API/spec, and test-planning artifacts do not drift on lifecycle/state models, flow coverage, permissions, or operational behavior
-- define logging and observability expectations for both frontend and backend
-- define operator visibility and operator workflow expectations when the prompt implies admin, operational, audit, backup, or support responsibilities
-- when the system has meaningful cross-cutting behavior, define shared implementation contracts early rather than leaving each module to invent its own pattern
-- define error-handling contracts when relevant, including normalization patterns for user-visible errors and backend error-shape expectations
-- define audit contracts when relevant, including centralized helper or service expectations and redaction rules
-- define permission contracts when relevant so navigation visibility, route guards, and API enforcement stay aligned
-- define state-lifecycle contracts when relevant, including context-switch or tenant-switch cleanup expectations
-- define auth edge-case expectations when relevant, such as token refresh, session expiry, or clock-skew tolerance
-- call out operational obligations early when they are prompt-critical, such as scheduling, retention, backups, workers, auditability, or offline behavior
-- define infrastructure requirements early when they are material to correctness, such as rate limiting, encryption boundaries, production-equivalent test infrastructure, and browser-storage rules for sensitive data
-- 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
-- for frontend work, unless the prompt, existing repository, or established stack clearly dictates otherwise, default 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
-- define end-to-end coverage for major user flows before coding
-- for fullstack work, explicitly plan Playwright coverage for the synchronized frontend/backend flows when end-to-end testing is applicable
-- when UI-bearing flows are material, explicitly plan screenshot review as part of Playwright verification so UI correctness is checked, not just browser success
-- aim for at least 90 percent meaningful coverage of the relevant behavior surface
-- define verification strategy, Docker expectations, and documentation implications before coding
-- for each major module, define how it integrates with existing modules and which shared contracts it must follow consistently
-- define verification plans that include cross-module scenarios and seam checks, not just isolated feature checks
-- make the plan detailed enough to guide real implementation and later verification
-- review the module map and make sure it is stable before deeper implementation begins
-- do not move into deeper implementation with vague architecture or unstable module boundaries
-
-## Scaffold And Foundation
-
-- create the initial project structure intentionally
-- establish Docker as the main runtime contract
-- create `run_tests.sh` as the standard test entrypoint
-- create required testing directories and baseline docs structure
-- put baseline config and logging structure in place
-- put migrations, worker/job foundation, and real runtime health surfaces in place when the project needs them
-- never create or keep `.env` files anywhere in the repo tree
-- treat prompt-critical security controls as real baseline runtime behavior, not placeholder checks or visual wiring
-- if a requirement implies enforcement, persistence, statefulness, or rejection behavior, make that behavior real in the scaffold unless the prompt clearly scopes it down
-- do not accept shape-only security implementations such as header presence checks, passive constants, or partially wired middleware when the requirement implies real protection
-- when applicable at scaffold time, require real security baselines such as nonce reuse rejection rather than nonce-header presence, real lockout behavior rather than config-only lockout values, CSRF rejection on protected mutations, and meaningful server-side state when the protection model depends on it
-- keep real secrets out of the repository and rely on Docker-provided runtime variables for sensitive values
-- do not allow committed `.env` files even as placeholders or examples
-- if the stack requires env-file format at runtime, generate it ephemerally from Docker-provided runtime variables rather than storing it in the repo or package
-- 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
-- keep Docker 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
-- 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
-- prove the scaffold in a clean state before deeper feature work
-- verify `docker compose up` and `run_tests.sh` in the clean scaffold state
-- verify clean `docker compose up --build -d` and `docker compose down` behavior under the chosen project namespace when Dockerized execution is in scope
-- when the architecture materially depends on infrastructure capabilities such as rate limiting, encryption, offline support, or browser-storage policy, put the baseline framework and policy in place during scaffold rather than deferring it to late implementation
-- for backend integration paths, prefer production-equivalent test infrastructure when practical rather than silently substituting a weaker database or runtime model that can hide real defects
-- do not treat scaffold as placeholder boilerplate or rely on hidden setup
-
-## Module Implementation
-
-- work module by module in vertical slices
-- define lightweight planning notes for the module before coding
-- define the module's purpose, constraints, and edge cases before coding
-- keep the original requirement and clarified interpretation visible while implementing so the module does not silently drift
-- implement real behavior, not partial scattered logic
-- handle failure paths and boundary conditions
-- add or update tests as part of the module 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 `run_tests.sh`
-- for applicable fullstack or UI-bearing work, run local Playwright on the affected flows during implementation and inspect screenshots to confirm the UI actually matches
-- when the slice materially changes frontend code, frontend tooling, or release-facing build behavior, include production build health in meaningful local verification when practical
-- make sure the module is moving toward full definition-of-done completion, not just happy-path completion
-- keep auth, authorization, ownership, validation, and logging concerns in view when relevant
-- keep frontend and backend contracts synchronized when the module spans both sides
-- verify the module integrates cleanly with existing modules, routes, permissions, shared state, and cross-cutting helpers rather than only proving the new feature path in isolation
-- check cross-cutting consistency where relevant, especially permissions, error handling, audit/logging/redaction behavior, and state or context transition behavior
-- 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
-- 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
-- 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
-- do not ship frontend screens with demo/debug/setup messaging or development-only status text; product UI should serve the real workflow only
-- 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
-- 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
-- do not move on while the module is still obviously weak or half-finished
-
-## Verification And Review
-
-- run the relevant tests for the changed behavior
-- during normal in-phase verification, prefer the fastest meaningful local test commands for the changed area
-- if local tooling is unavailable, try to install or enable the repo-local test setup when practical; otherwise fall back to `run_tests.sh`
-- the workflow owner handles the expensive critical-gate runs for `docker compose up --build` and `run_tests.sh`; use local verification to prepare for those gates rather than duplicating them casually
-- integrated/full verification should rely on owner-run `docker compose up --build`, owner-run `run_tests.sh`, and Playwright gate evidence
-- after post-evaluation remediation, strengthen local verification and rerun affected Playwright checks so the next owner-run gate pass is likely to succeed
-- for applicable fullstack or UI-bearing work, run Playwright for the affected flows in-phase, capture screenshots, and verify the UI behavior and quality directly
-- rerun the runtime startup path when the phase expects it
-- 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
-- verify end-to-end flow behavior where the change affects real workflows
-- do not use mocked APIs as integration evidence; integration verification must use real HTTP requests against the actual running service surface
-- for fullstack work, run Playwright coverage for major flows and review screenshots for real UI behavior and regressions
-- end-to-end coverage must use the real intended user-facing or admin-facing surfaces for the flow; if the flow cannot be exercised that way, treat the missing surface as incomplete work
-- use `frontend-design` while reviewing frontend screenshots so UI issues are challenged, not just functionally observed
-- verify screenshots do not contain demo placeholders, scaffold instructions, debug notices, or other development-only UI leakage
-- verify important failure, conflict, stale-state, negative-auth, and cross-user-isolation paths where relevant
-- verify required remediation guidance is actually visible to the user, not just computed internally
-- verify security-sensitive behavior where applicable
-- verify multi-tenant and cross-user isolation where applicable, including negative checks rather than single-actor happy paths only
-- verify file/path safety for file-bearing flows where applicable, including traversal-style negative cases
-- verify secrets are not committed, hardcoded, or leaking through logs/config/docs
-- apply the cross-cutting env-file discipline during verification
-- verify error surfaces and auth-related failures are sanitized for users and operators appropriately
-- apply the cross-cutting documentation discipline during verification
-- trace the changed tests and verification back to the prompt-critical risks, not just the easiest happy paths
-- challenge integration seams and adjacent-module behavior, not just the changed module's local path
-- when frontend behavior or tooling changed materially, treat known production build breakage as blocking evidence rather than optional cleanup
-- do not treat a module as done until functional behavior, failure behavior, tests, docs, security considerations, and required runtime verification are all in place
-- call out weak evidence, missing coverage, or unresolved issues plainly
-- do not treat developer claims as enough without real verification
-
-## Hardening
-
-- audit security boundaries, validation, ownership, and secret handling
-- audit env/config paths so sensitive values are injected safely and are not baked into committed files or images
-- inspect architecture, coupling, file size, and maintainability risks
-- check for bad engineering practices that accumulated during implementation
-- tighten weak tests, weak docs, and weak operational instructions
-- run exploratory testing around awkward states, repeated actions, and realistic edge behavior
-- re-check frontend and backend observability, redaction, and operator visibility paths
-- run a prompt-fidelity sweep for silent requirement substitution, partially delivered hard requirements, and frontend/backend mismatch
-- run a prototype-residue sweep for hardcoded preview values, placeholder text, seeded defaults, hidden fallbacks, and computed-but-unrendered behavior
-- enforce the cross-cutting env-file discipline during hardening
-- run documentation verification against the real codebase and runtime behavior, not just document existence
-- enforce the cross-cutting documentation discipline during hardening
-- re-check prompt-critical operational obligations such as scheduled jobs, retention, backups, worker behavior, privacy/accountability logging, and admin controls
-- enter release-candidate mode: stop feature work and focus only on fixes, verification, docs, and packaging preparation
-- make sure the system is genuinely reviewable and reproducible
-
-## Packaging Preparation
-
-- move or copy the final development docs into the required root `docs/` structure
-- make sure package structure matches the blueprint exactly
-- verify required artifacts are present and named correctly
-- prepare screenshots, proof materials, and other delivery evidence
-- review package cleanliness so caches, junk, and local-only files are not included
-- verify no local secret files or sensitive values are included in the package
-- verify docs, specs, and runtime instructions describe what is actually delivered rather than what was only planned or partially built
-- archive or exclude transient review artifacts so delivery evidence stays intentional and clean
-
-## Remediation
-
-- focus only on accepted defects and the work needed to fix them cleanly
-- fix the issue completely instead of layering hacks on top
-- trace the fix back to the original requirement so the remediation restores fidelity instead of only hiding the symptom
-- 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