theslopmachine 0.4.0 → 0.4.2

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

@@ -1,20 +1,49 @@
 ---
 name: submission-packaging
-description: Final delivery packaging checklist and artifact assembly rules for repo-cwd blueprint-driven projects. Use only during the submission packaging phase.
+description: Submission packaging and final closure rules for slopmachine.
 ---
 
 # Submission Packaging
 
-Use this skill only when the project has already passed integrated verification, hardening, and the final evaluation/remediation loop closely enough to qualify for packaging.
+Use this skill only during `P10 Submission Packaging`.
 
-## Usage rules
+## Canonical package documents
 
-- Load this skill only in the submission packaging phase.
-- Treat it as internal packaging guidance, not developer-visible workflow text.
-- Do not use it to justify skipping verification or evaluation gates.
-- Packaging is not cleanup theater. Preserve required evidence and remove only local junk, caches, and accidental noise.
-- Do not declare packaging complete early.
-- Packaging is incomplete until every required step in this skill has been executed and every required artifact path has been verified to exist.
+The canonical package documents under `~/slopmachine/` are:
+
+1. `~/slopmachine/backend-evaluation-prompt.md`
+2. `~/slopmachine/frontend-evaluation-prompt.md`
+3. `~/slopmachine/document-completeness.md`
+4. `~/slopmachine/engineering-results.md`
+5. `~/slopmachine/implementation-comparison.md`
+6. `~/slopmachine/quality-document.md`
+
+Usage split:
+
+- the two evaluation prompt files are used only for evaluation runs
+- the other four files are used during submission packaging to generate the final submission documents
+
+Do not invent alternate template sources when these canonical package documents exist.
+
+Packaging document mapping:
+
+- `~/slopmachine/document-completeness.md` feeds the delivery-completeness and hard-threshold packaging outputs
+- `~/slopmachine/quality-document.md` feeds the engineering-and-architecture packaging output
+- `~/slopmachine/engineering-results.md` feeds the engineering-details-and-professionalism packaging output
+- `~/slopmachine/implementation-comparison.md` feeds the prompt-understanding-and-adaptability packaging output
+- the aesthetics packaging output is based on actual delivered UI evidence, screenshots, and the real shipped product state; use the implementation-comparison and other package docs only as supporting context when relevant
+
+## Core rules
+
+- enter `P10` before packaging work begins
+- keep packaging work inside the formal phase window
+- package from an already-clean state instead of compensating for avoidable earlier drift
+- treat formal workflow closure failures as real packaging failures
+- treat this as internal packaging guidance, not developer-visible workflow text
+- do not use it to justify skipping verification or evaluation gates
+- packaging is not cleanup theater; preserve required evidence and remove only local junk, caches, and accidental noise
+- do not declare packaging complete early
+- packaging is incomplete until every required step in this skill has been executed and every required artifact path has been verified to exist
 - do not stop packaging for approval, status confirmation, or handoff once this phase has begun; continue until the package is complete
 
 ## Completion discipline
@@ -27,11 +56,11 @@ Use this skill only when the project has already passed integrated verification,
 
 ## Packaging goals
 
-- produce the exact required delivery structure
-- make the package reviewable and reproducible
-- keep development docs separate from final generated submission artifacts
-- include the required docs, metadata, submission artifacts, evidence, and session artifacts
-- exclude local-only junk, transient noise, and secret material
+- assemble the required final structure
+- preserve required evidence
+- exclude local-only junk and secret material
+- export session and trajectory artifacts correctly
+- make the final package easy to review
 
 ## Required final structure
 
@@ -50,15 +79,11 @@ The final submission layout in the parent project root must be:
   - relocated screenshots and proof materials needed for submission review
 - current working directory delivered as parent-root `repo/`
 - `../sessions/`
+  - `develop-N.json`
+  - `bugfix-N.json`
 - `../metadata.json`
-- `../session.json`
-- `../session-N.json` when multiple exported sessions exist
-- `../trajectory.json`
-- `../trajectory-N.json` when multiple trajectories exist
 - parent-root `../.tmp/` directory moved out of current `.tmp/` when it exists
 
-Do not treat `.ai/` as part of the final submission structure unless the user explicitly changes that requirement later.
-
 ## Required packaging actions
 
 - verify the root package structure matches the blueprint exactly
@@ -68,43 +93,55 @@ Do not treat `.ai/` as part of the final submission structure unless the user ex
 - verify parent-root `../docs/test-coverage.md` exists and reflects the final delivered verification coverage
 - verify parent-root `../docs/questions.md` exists from the accepted clarification/question record when applicable
 - create parent-root `../submission/` for final generated submission artifacts and reviewer-facing proof
+- use these exact `~/slopmachine/` document templates as the packaging reference sources:
+  - `~/slopmachine/document-completeness.md`
+  - `~/slopmachine/engineering-results.md`
+  - `~/slopmachine/implementation-comparison.md`
+  - `~/slopmachine/quality-document.md`
 - ensure `README.md` matches the delivered codebase, functionality, runtime steps, and test steps, stays friendly to a junior developer, and does not reference the external docs set in `../docs/`
-- include `run_tests.sh`
-- relocate evaluation artifacts into parent-root `../submission/`, including:
-  - backend evaluation report
-  - frontend evaluation report
+- include `./run_tests.sh` and any supporting runner logic it needs to execute the project's broad test path from a clean environment
+- relocate evaluation artifacts into parent-root `../submission/`
 - relocate screenshots and proof materials relevant to runtime behavior and major flows into parent-root `../submission/`
-- gather required screenshots from test-output or artifact directories and relocate them into parent-root `../submission/` during packaging
-- include exported session artifacts at the parent project root using the naming rules:
-  - `../session.json` for a single exported session
-  - `../session-N.json` when multiple exported sessions exist
-- include trajectory artifacts at the parent project root using the naming rules:
-  - `../trajectory.json` for a single trajectory
-  - `../trajectory-N.json` when multiple trajectories exist
-- preserve parent-root `../sessions/` as the session artifact directory for any additional exported conversation traces the package needs to retain
-- include any required package/tree proof or delivery evidence
+- preserve parent-root `../sessions/` as the session artifact directory for converted workflow session exports
+- export all tracked workflow sessions before generating the final submission documents
+- after the session exports are complete, use the last evaluation session recorded in metadata when generating the final submission report content so the report answers can come from cached evaluation context instead of rebuilding that context from scratch
 
 ## Session export sequence
 
-For the developer session, run these exact steps:
+This export sequence must happen first in packaging, before final submission documents are generated.
+
+Export every tracked workflow session from metadata.
 
-- this sequence is mandatory
-- do not skip, reorder, or replace these commands with approximations
-- if one of these commands fails, stop and fix the export pipeline before continuing packaging
-- do not proceed to later packaging steps until the export, strip, and trajectory conversion steps have all succeeded
+For each tracked session:
 
-1. `opencode export <developer-session-id> > ../session-export.json`
-2. `python3 ~/utils/strip_session_parent.py ../session-export.json --output ../session.json`
-3. `python3 ~/utils/convert_ai_session.py -i ../session.json -o ../trajectory.json`
+1. `opencode export <session-id> > ../session-export-<label>.json`
+2. `python3 ~/utils/strip_session_parent.py ../session-export-<label>.json --output ../session-clean-<label>.json`
+3. `python3 ~/utils/convert_ai_session.py -i ../session-clean-<label>.json -o ../sessions/<final-name>.json`
+
+Naming rule for converted files under `../sessions/`:
+
+- development-phase sessions become `develop-N.json`
+- hardening or remediation sessions become `bugfix-N.json`
 
 After those steps:
 
-- keep the cleaned final exported session as parent-root `../session.json` unless multiple exports require `../session-N.json`
-- keep the generated final trajectory as parent-root `../trajectory.json` unless multiple trajectories require `../trajectory-N.json`
-- treat parent-root `../session-export.json` as a temporary packaging intermediate
-- treat parent-root `../session.json` and `../trajectory.json` as final package artifacts unless numbering rules require the `-N` variants
-- immediately verify that all expected directories and required files exist before running any later packaging scripts
-- if the required utilities or output files are missing, packaging is not ready to continue
+- verify every planned developer session has been exported and converted before continuing packaging
+- keep the converted session outputs in `../sessions/` using the naming rules above
+- treat the `../session-export-*.json` and `../session-clean-*.json` files as temporary packaging intermediates unless the package contract later says otherwise
+- if the required utilities, metadata session ids, or output files are missing, packaging is not ready to continue
+- only after these exports are complete may you generate the final submission documents
+
+## Final report generation order
+
+After all session exports are complete:
+
+1. recover the last evaluation session id from metadata
+2. use that last evaluation session to answer the final submission-document questions from its cached context
+3. generate the required final submission documents from that evaluation context plus the canonical `~/slopmachine/` reference files
+
+Do not start generating the final submission documents before the session exports are complete.
+Do not create a new evaluation session for final report generation if the last evaluation session is still available.
+If the last evaluation session id is missing or unusable, stop and repair metadata/session recovery before continuing packaging.
 
 ## Required file moves
 
@@ -113,168 +150,112 @@ After those steps:
 - after preserving parent-root `../.tmp/`, collect the relevant evaluation reports and proof artifacts from it into parent-root `../submission/`
 - collect screenshots and other required proof materials from repo-local runtime/output directories into parent-root `../submission/`
 - after relocation, the final submission should not require digging through repo-local output directories to find evidence
-- find required screenshots in their generated locations and move or copy them into parent-root `../submission/` so reviewers do not have to inspect e2e artifact directories manually
-- keep screenshot filenames clear enough that the referenced runtime page, flow, or evidence purpose is understandable from the file name or nearby document reference
+- keep screenshot filenames clear enough that the referenced runtime page, flow, or evidence purpose is understandable
 
 ## Repo cleanup rules
 
-Clean the current working directory that will be delivered as parent-root `repo/` before final submission.
-
-Remove runtime, editor, cache, tooling noise, generated artifacts, and environment junk recursively anywhere in the delivered repo tree, such as:
-
-- `.git/`
-- `.opencode/`
-- `.codex/`
-- `.vscode/`
-- `.env`
-- `.env.local`
-- `.env.example`
-- other env-file variants
-- `__pycache__/`
-- `.pytest_cache/`
-- `node_modules/`
-- `.venv/`
-- `.net/`
-- `playwright-report/`
-- `test-results/`
-- `dist/` or similar generated build output when not part of the delivered runtime contract
-- generated screenshots, reports, and proof artifacts that have already been relocated into parent-root `../submission/`
-- `AGENTS.md`
-- similar environment-dependent or local-only directories
-
+- remove runtime, editor, cache, tooling noise, generated artifacts, and environment junk recursively anywhere in the delivered repo tree
+- do not remove required evidence just because it looks noisy
+- remove `.git/`, `.opencode/`, `.codex/`, `.vscode/`, env-file variants, caches, `node_modules/`, build outputs not part of delivery, raw test artifact directories once evidence is relocated, and repo-local `AGENTS.md`
 - if repo-local `.tmp/` existed, do not delete it before preserving it as parent-root `../.tmp/`
-
-- this cleanup is recursive; do not leave forbidden directories or generated junk buried deeper in the repo hierarchy after required artifacts have been moved out
-
-Product attachment packaging is not allowed.
-
-Do not include environment-dependent local runtime content in the delivered package.
+- the cleanup is recursive; do not leave forbidden directories or generated junk buried deeper in the repo hierarchy after required artifacts have been moved out
 
 ## Validation checklist
 
 - confirm the final package contains what reviewers actually need to inspect the project
 - confirm docs describe delivered behavior, not planned or aspirational behavior
 - confirm parent-root `../docs/test-coverage.md` explains the tested flows, coverage boundaries, and how the evaluator should interpret the coverage evidence
-- confirm generated submission documents exist under parent-root `../submission/` and correspond to the final qualified state, not an older revision
-- confirm evaluation reports and screenshots have been relocated into parent-root `../submission/` and correspond to the final qualified state, not an older revision
+- confirm generated submission documents exist under parent-root `../submission/` and correspond to the final qualified state
+- confirm evaluation reports and screenshots have been relocated into parent-root `../submission/`
 - confirm shared project docs live in parent-root `../docs/` and any accidental repo-local `docs/` copy has been removed from the delivered tree
-- confirm repo-local evidence directories have been harvested so required reports and screenshots now live in parent-root `../submission/`
 - confirm required screenshots have been relocated into parent-root `../submission/`
-- confirm parent-root metadata fields are populated correctly:
-  - `prompt`
-  - `project_type`
-  - `frontend_language`
-  - `backend_language`
-  - `database`
-  - `session_id`
-  - `frontend_framework`
-  - `backend_framework`
-- confirm session export naming rules are followed:
-  - parent-root `../session.json`
-  - parent-root `../session-N.json` when multiple exported sessions exist
-  - parent-root `../trajectory.json`
-  - parent-root `../trajectory-N.json` when multiple trajectories exist
+- confirm parent-root metadata fields are populated correctly
+- confirm session export naming rules are followed under `../sessions/`:
+  - `develop-N.json` for development-phase sessions
+  - `bugfix-N.json` for hardening/remediation sessions
 
 ## Submission artifact and response contract
 
-Use parent-root `../submission/` for the file-based final generated submission artifacts.
-
-Keep the generated content tied to the real delivered project, not generic template text.
-
-Use real screenshots from the delivered product and real project evidence.
-
-The packaging-stage outputs are two kinds only:
+- use parent-root `../submission/` for file-based final generated submission artifacts
+- keep the generated content tied to the real delivered project, not generic template text
+- use real screenshots from the delivered product and real project evidence
+- generate the submission documents from the four canonical `~/slopmachine/` packaging reference files rather than ad hoc freeform output
+- the packaging-stage outputs are `FILE` outputs under `../submission/` plus `PARAGRAPH` outputs in the final packaging-stage response
 
-- `FILE` outputs: create the specified file under parent-root `../submission/`
-- `PARAGRAPH` outputs: answer directly in the final packaging-stage response instead of creating a file
+### Required FILE outputs
 
-Create these file outputs:
+Create these exact `FILE` outputs under parent-root `../submission/`:
 
 1. `FILE` -> `../submission/self-test-results-hard-threshold.md`
-   - Can the delivered product actually run and be verified, including error pages and successful running pages.
-   - Include the relevant working app screenshots.
+   - based primarily on `~/slopmachine/document-completeness.md` plus actual runtime/test evidence
+   - answer whether the delivered product can actually run and be verified
+   - include both successful running paths and important failure or error behavior when relevant
+   - include the relevant working-app screenshots or equivalent platform artifacts
+
 2. `FILE` -> `../submission/self-test-status-delivery-completeness.md`
-   - Do the delivered deliverables fully cover the core requirements explicitly stated in the prompt.
-   - Does the delivered product possess a basic delivery form from 0 to 1 rather than partial functionality, schematic implementation, or code snippets.
-   - If unable, provide a specific reason.
+   - based primarily on `~/slopmachine/document-completeness.md`
+   - answer whether the delivered output fully covers the core requirements explicitly stated in the prompt
+   - answer whether the delivered product has a basic 0-to-1 delivery shape rather than a partial feature, schematic implementation, tutorial sample, or code fragment
+   - if not, give the specific reason
+
 3. `FILE` -> `../submission/self-assessment-engineering-and-architecture-quality.md`
-   - Based on `~/quality-document.md`.
-   - Does the delivered product employ a reasonable engineering structure and modular division under the current problem.
-   - Does the delivered product demonstrate basic maintainability and scalability rather than a temporary or stacked implementation.
-   - Include a screenshot of the current working directory folder structure that will be delivered as `repo/`.
+   - based primarily on `~/slopmachine/quality-document.md`
+   - answer whether the delivered product uses a reasonable engineering structure and modular division for the current problem
+   - answer whether the delivered product demonstrates basic maintainability and extensibility rather than a temporary or stacked implementation
+   - include a screenshot of the current working directory folder structure that will be delivered as `repo/`
+
 4. `FILE` -> `../submission/self-test-results-engineering-details-and-professionalism.md`
-   - Cover these exact checks:
-     - Error handling: all APIs return standard HTTP codes and JSON error format
-     - Logging: key flows have structured logs
-     - Input validation: all body/query/path params validated
-     - No secrets/keys in config files
-     - No `node_modules` / `.venv` committed
-     - No `console.log("here")` debug statements left in code
+   - based primarily on `~/slopmachine/engineering-results.md`
+   - cover these exact checks using selected-stack equivalents when the project type changes the exact surface:
+     - error handling: API-bearing or platform-equivalent interfaces return appropriate structured errors and user-safe behavior
+     - logging: key flows have useful troubleshooting-oriented logs or platform-equivalent diagnostics
+     - input validation: important body/query/path/CLI/form/event inputs are validated as applicable to the project type
+     - no secrets or keys are committed in config or source files
+     - no dependency directories such as `node_modules`, `.venv`, or platform-equivalent local dependency trees are committed
+     - no obvious leftover debug statements such as `console.log("here")`, `print("debug")`, or platform-equivalent temporary debugging output remain in shipped code
+
 5. `FILE` -> `../submission/self-test-results-prompt-understanding-and-adaptability.md`
-   - Explain whether the delivered product accurately understands and responds to business objectives, use cases, and implicit constraints in the prompt rather than merely mechanically implementing presentation-layer technical requirements.
+   - based primarily on `~/slopmachine/implementation-comparison.md`
+   - explain whether the delivered product accurately understands and responds to business objectives, use cases, and implicit constraints in the prompt rather than mechanically implementing surface-level technical features
+
 6. `FILE` -> `../submission/self-test-results-aesthetics.md`
-   - Fullstack or pure frontend only.
-   - Does the visual and interaction of the delivered product fit the scene and is the design aesthetically pleasing.
-   - If not applicable, write `Not Applicable`.
-   - If aesthetically unappealing, provide a specific reason.
-
-In the final packaging-stage response, include these paragraph outputs in order:
-
-1. `PARAGRAPH` -> Hard threshold explanation
-   - Whether the delivered product can actually be operated and verified.
-   - Whether the delivered product significantly deviates from the prompt topic.
-2. `PARAGRAPH` -> Delivery completeness statement
-   - Whether the delivered deliverables fully cover the core prompt requirements.
-   - Whether the delivered product has a real 0-to-1 delivery form rather than partial or schematic output.
-   - If unable, provide a specific reason.
-3. `PARAGRAPH` -> Engineering and architecture quality statement
-4. `PARAGRAPH` -> Engineering details and professionalism description
-   - Error handling: all APIs return standard HTTP codes plus JSON error format.
-   - Logging: key flows have structured logs.
-   - Input validation: all body/query/path parameters validated.
-   - No secrets or keys in config files.
-   - No `node_modules` or `.venv` committed.
-   - No `console.log("here")` debug statements left in code.
-5. `PARAGRAPH` -> Prompt requirements understanding and adaptability explanation
-   - Whether the delivered product accurately understands and responds to business objectives, use cases, and implicit constraints in the prompt rather than merely implementing presentation-layer technical requirements.
-6. `PARAGRAPH` -> Aesthetics assessment
-   - Fullstack or pure frontend only.
-   - Whether the visual and interaction of the delivered product fit the scene and are aesthetically pleasing.
-   - If not applicable, state `Not Applicable`.
-   - If aesthetically unappealing, provide a specific reason.
+   - frontend/fullstack/mobile/desktop UI-bearing projects only
+   - based primarily on actual delivered UI evidence, screenshots, and the real shipped product state
+   - answer whether the visual design and interaction quality fit the actual use case and are aesthetically credible
+   - if not applicable, write `Not Applicable`
+   - if aesthetically weak, provide the specific reason
 
-Store supporting screenshots and reviewer-facing proof in `../submission/`, including:
+### Required PARAGRAPH outputs
 
-- repo file structure screenshot
-- working app screenshots
-- relocated evaluation reports
-- other proof artifacts referenced by the generated submission files
+In the final packaging-stage response, include these `PARAGRAPH` outputs in this exact order:
 
-## Cleanliness rules
+1. `PARAGRAPH` -> Hard-threshold explanation
+   - whether the delivered product can actually be operated and verified
+   - whether the delivered product significantly deviates from the prompt topic
 
-- remove caches, temp outputs, build junk, editor noise, and accidental local files that are not part of the package contract
-- do not remove required evidence just because it looks noisy
-- verify no local secret files or sensitive values are included in the final package
-- verify no `.env` or env-file variant exists anywhere in the delivered repo tree or related package artifacts
-- verify the delivered package can be started from scratch without any preexisting `.env` file; if runtime env-file generation is part of the stack, it must be generated ephemerally from Docker-provided variables rather than shipped as a package artifact
-- verify frontend screenshots do not show demo/debug/setup leakage
-- verify evaluation rebuttal notes, if any, remain attached to the relevant evaluation reports
-- verify the final package does not include pointless tests or artifacts whose only purpose was to assert documentation-directory existence
-- verify that required submission artifacts and evidence are centralized under parent-root `../submission/` rather than scattered across repo-local output directories
-- do not leave required screenshots stranded only inside raw e2e artifact directories
-
-## Optional final archive
-
-- after packaging is complete, you may create a parent-root zip archive for handoff review
-- if you do, the archive should include the final delivered structures and exports only
-- because final submission artifacts now live under `../submission/`, include it alongside the other delivered paths
-- recommended parent-root archive contents are:
-  - `docs/`
-  - `submission/`
-  - `repo/`
-  - `session*.json`
-  - `sessions/`
-  - `trajectory*.json`
+2. `PARAGRAPH` -> Delivery-completeness statement
+   - whether the delivered output fully covers the core prompt requirements
+   - whether the delivered product has a real 0-to-1 delivery shape rather than partial or schematic output
+   - if not, provide the specific reason
+
+3. `PARAGRAPH` -> Engineering-and-architecture quality statement
+
+4. `PARAGRAPH` -> Engineering-details-and-professionalism description
+   - error handling
+   - logging or equivalent diagnostics
+   - input validation
+   - no committed secrets or keys
+   - no committed dependency directories such as `node_modules` or `.venv`
+   - no leftover debug statements
+
+5. `PARAGRAPH` -> Prompt-understanding-and-adaptability explanation
+   - whether the delivered product accurately understands and responds to business objectives, use cases, and implicit constraints in the prompt rather than merely implementing presentation-layer technical requirements
+
+6. `PARAGRAPH` -> Aesthetics assessment
+   - UI-bearing projects only
+   - whether the visual and interaction quality fit the actual use case and are aesthetically credible
+   - if not applicable, state `Not Applicable`
+   - if aesthetically weak, provide the specific reason
 
 ## Final packaging verification
 
@@ -282,19 +263,4 @@ Store supporting screenshots and reviewer-facing proof in `../submission/`, incl
 - confirm the package is coherent as a delivered submission, not just a working repo snapshot
 - confirm the final git checkpoint can be created cleanly for the packaged state
 - if packaging reveals a real defect or missing artifact, fix it before closing the phase
-
-## Required completion checklist
-
-Do not close packaging until all of these are true:
-
-- final docs exist in parent-root `../docs/`
-- any accidental repo-local `docs/` copy no longer remains in the delivered repo tree
-- parent-root `../metadata.json` exists and is populated correctly
-- parent-root `../session.json` or `../session-N.json` exists as required
-- parent-root `../trajectory.json` or `../trajectory-N.json` exists as required
-- parent-root `../sessions/` exists
-- generated submission files exist under parent-root `../submission/`
-- evaluation reports are present under parent-root `../submission/`
-- required screenshots and proof materials are present under parent-root `../submission/`
-- delivered repo no longer contains forbidden junk directories
-- final structure matches the required layout exactly
+- do not close packaging until all required docs, exports, submission files, screenshots, and cleanup conditions are satisfied