theslopmachine 0.3.7 → 0.4.0

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

@@ -15,6 +15,7 @@ Use this skill only when the project has already passed integrated verification,
 - 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
 
@@ -28,7 +29,8 @@ Use this skill only when the project has already passed integrated verification,
 
 - produce the exact required delivery structure
 - make the package reviewable and reproducible
-- include the required docs, metadata, evidence, and session artifacts
+- 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
 
 ## Required final structure
@@ -40,27 +42,19 @@ The final submission layout in the parent project root must be:
   - `api-spec.md` when applicable
   - `test-coverage.md`
   - `questions.md`
-  - `submission-self-test-index.md`
-  - `hard-threshold-explanation.md`
-  - `document-completeness-report.md`
-  - `engineering-architecture-quality-report.md`
-  - `engineering-architecture-quality-statement.md`
-  - `engineering-results-report.md`
-  - `engineering-details-professionalism.md`
-  - `implementation-comparison-report.md`
-  - `prompt-understanding-adaptability.md`
-  - `aesthetics.md` when applicable
-  - `aesthetics-assessment.md` when applicable
+- `submission/`
+  - generated submission documents based on the reference files in `~/`
   - evaluation reports
-  - screenshots and proof materials
-  - relocated screenshots and proof images needed for submission review
+  - repo file structure screenshot
+  - working app screenshots
+  - relocated screenshots and proof materials needed for submission review
 - current working directory delivered as parent-root `repo/`
 - `../sessions/`
-  - `trajectory.json`
-  - `trajectory-N.json` when multiple session trajectories exist
 - `../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.
@@ -69,24 +63,25 @@ Do not treat `.ai/` as part of the final submission structure unless the user ex
 
 - verify the root package structure matches the blueprint exactly
 - make sure parent-root `../metadata.json` is complete and reflects the delivered project truthfully
-- create or finalize parent-root `../docs/design.md` from the working `docs/design.md`
-- create or finalize parent-root `../docs/api-spec.md` from the working `docs/api-spec.md` when applicable
-- create or finalize parent-root `../docs/test-coverage.md` from the working `docs/test-coverage.md`
-- create or finalize parent-root `../docs/questions.md` from the accepted clarification/question record
-- move the final docs set out of current `docs/` into parent-root `../docs/` after development is complete
-- ensure `README.md` matches the delivered runtime, verification, and feature behavior
+- verify parent-root `../docs/design.md` exists and reflects the final delivered design when applicable
+- verify parent-root `../docs/api-spec.md` exists and reflects the final delivered interfaces when applicable
+- verify parent-root `../docs/test-coverage.md` exists and reflects the final delivered verification coverage
+- verify parent-root `../docs/questions.md` exists from the accepted clarification/question record when applicable
+- create parent-root `../submission/` for final generated submission artifacts and reviewer-facing proof
+- 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 `../docs/`, including:
+- relocate evaluation artifacts into parent-root `../submission/`, including:
   - backend evaluation report
   - frontend evaluation report
-- relocate screenshots and proof materials relevant to runtime behavior and major flows into parent-root `../docs/`
-- gather required screenshots from test-output or artifact directories and relocate them into parent-root `../docs/` during packaging
+- 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 in `../sessions/` using the naming rules:
-  - `../sessions/trajectory.json` for a single trajectory
-  - `../sessions/trajectory-N.json` when multiple trajectories 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
 
 ## Session export sequence
@@ -99,46 +94,58 @@ For the developer session, run these exact steps:
 - do not proceed to later packaging steps until the export, strip, and trajectory conversion steps have all succeeded
 
 1. `opencode export <developer-session-id> > ../session-export.json`
-2. `python3 ~/slopmachine/utils/strip_session_parent.py ../session-export.json --output ../session.json`
-3. `python3 ~/slopmachine/utils/convert_ai_session.py -i ../session.json -o ../trajectory.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`
 
 After those steps:
 
 - keep the cleaned final exported session as parent-root `../session.json` unless multiple exports require `../session-N.json`
-- move or copy the generated trajectory into `../sessions/trajectory.json` unless multiple trajectories require `../sessions/trajectory-N.json`
-- treat `../session-export.json` and the intermediate parent-root `../session.json` as temporary packaging intermediates unless the package contract later says otherwise
-- pause immediately after the export/clean/convert sequence and verify that all expected directories and required files exist before running any later packaging scripts
+- 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
 
 ## Required file moves
 
-- move the final docs set out of current `docs/` into parent-root `../docs/`
-- after packaging, current `docs/` must not remain in the delivered `repo/` tree
-- if current `.tmp/` exists, collect the relevant evaluation reports and proof artifacts from it into parent-root `../docs/`
-- collect screenshots and other required proof materials from repo-local runtime/output directories into parent-root `../docs/`
+- if repo-local `docs/` exists, treat it as accidental residue, reconcile any missing content into parent-root `../docs/`, and remove it from the delivered `repo/` tree
+- if current `.tmp/` exists, move the whole directory to parent-root `../.tmp/` before harvesting any reviewer-facing artifacts from it
+- after preserving parent-root `../.tmp/`, collect the relevant evaluation reports and proof artifacts from it into parent-root `../submission/`
+- 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 `../docs/` so reviewers do not have to inspect e2e artifact directories manually
+- 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
 
 ## Repo cleanup rules
 
 Clean the current working directory that will be delivered as parent-root `repo/` before final submission.
 
-Remove runtime, editor, cache, and tooling noise such as:
+Remove runtime, editor, cache, tooling noise, generated artifacts, and environment junk recursively anywhere in the delivered repo tree, such as:
 
-- `.tmp/`
 - `.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
 
+- 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.
@@ -147,11 +154,12 @@ Do not include environment-dependent local runtime content in the delivered pack
 
 - confirm the final package contains what reviewers actually need to inspect the project
 - confirm docs describe delivered behavior, not planned or aspirational behavior
-- confirm `docs/test-coverage.md` explains the tested flows, coverage boundaries, and how the evaluator should interpret the coverage evidence
-- confirm evaluation reports and screenshots have been relocated into parent-root `../docs/` and correspond to the final qualified state, not an older revision
-- confirm current `docs/` has been handled correctly so final delivery docs live in parent-root `../docs/`
-- confirm repo-local evidence directories have been harvested so required reports and screenshots now live in parent-root `../docs/`
-- confirm required screenshots have been relocated into parent-root `../docs/`
+- 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 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`
@@ -164,87 +172,110 @@ Do not include environment-dependent local runtime content in the delivered pack
 - confirm session export naming rules are followed:
   - parent-root `../session.json`
   - parent-root `../session-N.json` when multiple exported sessions exist
-  - `../sessions/trajectory.json`
-  - `../sessions/trajectory-N.json` when multiple trajectories exist
-
-## Submission reporting documents
-
-Create a root document at:
-
-- `docs/submission-self-test-index.md`
-
-Use it as the master index of packaging/self-test outputs.
-
-Rules:
-
-- answer the direct questions inline in this index when a standalone document is not required
-- when a standalone document is required, create the file and include its path in the index
-- keep the answers tied to the real delivered project, not generic template text
-- use real screenshots from the delivered product and real project evidence
-
-Create or populate these deliverables:
-
-1. `docs/submission-self-test-index.md`
-   - answer whether the delivered product can actually run and be verified
-   - link screenshots proving successful runtime pages and, when relevant, error pages
-2. `docs/hard-threshold-explanation.md`
-   - explain success/failure status
-   - state whether the delivered product can actually be operated and verified
-   - state whether the delivered product significantly deviates from the prompt topic
-3. `docs/document-completeness-report.md`
-   - based on `~/slopmachine/document-completeness.md`
-   - create a similar table document for this codebase
-   - include screenshots with real product data where applicable
-4. Add to `docs/submission-self-test-index.md`
-   - Self-Test Status — Delivery Completeness Statement
-   - answer whether the deliverables fully cover the core prompt requirements
-   - answer whether the product has a real 0-to-1 delivery form rather than partial/schematic output
-   - if unable, provide a specific reason
-5. `docs/engineering-architecture-quality-report.md`
-   - based on `~/slopmachine/quality-document.md`
-   - generate a report with the same type of information and proper formatting
-   - include a screenshot of the current working directory folder structure that will be delivered as `repo/`
-   - suggested method: run a tree command such as `tree . -a -L 3 > ../repo-structure.txt`, open that output in the terminal or editor, and capture a screenshot manually
-6. `docs/engineering-architecture-quality-statement.md`
-   - Self-test results: engineering and architecture quality statement
-7. `docs/engineering-results-report.md`
-   - based on `~/slopmachine/engineering-results.md`
-   - generate a similar document for this codebase
-8. `docs/engineering-details-professionalism.md`
-   - cover these exact checks:
+  - parent-root `../trajectory.json`
+  - parent-root `../trajectory-N.json` when multiple trajectories exist
+
+## 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:
+
+- `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
+
+Create these file outputs:
+
+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.
+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.
+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/`.
+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 stray debug statements such as `console.log("here")`
-9. `docs/implementation-comparison-report.md`
-   - based on `~/slopmachine/implementation-comparison.md`
-   - generate a similar document for this codebase with real evidence
-10. `docs/prompt-understanding-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 implementing presentation-layer technical requirements
-11. `docs/aesthetics.md`
-   - for fullstack or pure frontend only
-   - answer whether the visual/interaction fits the scene and is aesthetically pleasing
-   - if not applicable, write `Not Applicable`
-   - if aesthetically unappealing, provide a specific reason
-12. `docs/aesthetics-assessment.md`
-   - for fullstack or pure frontend only
-   - produce the aesthetics assessment in a separate document
-   - if not applicable, write `Not Applicable`
-   - if aesthetically unappealing, provide a specific reason
+     - No `console.log("here")` debug statements left in 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.
+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.
+
+Store supporting screenshots and reviewer-facing proof in `../submission/`, including:
+
+- repo file structure screenshot
+- working app screenshots
+- relocated evaluation reports
+- other proof artifacts referenced by the generated submission files
 
 ## Cleanliness rules
 
 - 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 evidence is centralized under parent-root `../docs/` rather than scattered across repo-local output directories
+- 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`
+
 ## Final packaging verification
 
 - do one final package review before declaring packaging complete
@@ -257,12 +288,13 @@ Create or populate these deliverables:
 Do not close packaging until all of these are true:
 
 - final docs exist in parent-root `../docs/`
-- current `docs/` no longer remains in the delivered repo tree
+- 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
-- `../sessions/trajectory.json` or `../sessions/trajectory-N.json` exists as required
-- evaluation reports are present under parent-root `../docs/`
-- required screenshots and proof materials are present under parent-root `../docs/`
-- required submission-report documents exist in parent-root `../docs/`
+- 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

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

@@ -0,0 +1,142 @@
+---
+name: submission-packaging-v2
+description: Submission packaging and final closure rules for slopmachine-v2.
+---
+
+# Submission Packaging v2
+
+Use this skill only during `P10 Submission Packaging`.
+
+## 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
+
+- execute packaging in order; do not jump to the end and assume missing pieces can be filled later
+- after each major packaging block, verify the expected outputs before continuing
+- before closing the packaging phase, explicitly check that every required file and directory exists in its final location
+- if any required artifact is missing, packaging is still in progress
+- if any cleanup, move, export, or reporting step is incomplete, packaging is still in progress
+
+## Packaging goals
+
+- 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
+
+The final submission layout in the parent project root must be:
+
+- `docs/`
+  - `design.md`
+  - `api-spec.md` when applicable
+  - `test-coverage.md`
+  - `questions.md`
+- `submission/`
+  - generated submission documents based on the reference files in `~/`
+  - evaluation reports
+  - repo file structure screenshot
+  - working app screenshots
+  - relocated screenshots and proof materials needed for submission review
+- current working directory delivered as parent-root `repo/`
+- `../sessions/`
+- `../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
+
+## Required packaging actions
+
+- verify the root package structure matches the blueprint exactly
+- make sure parent-root `../metadata.json` is complete and reflects the delivered project truthfully
+- verify parent-root `../docs/design.md` exists and reflects the final delivered design when applicable
+- verify parent-root `../docs/api-spec.md` exists and reflects the final delivered interfaces when applicable
+- verify parent-root `../docs/test-coverage.md` exists and reflects the final delivered verification coverage
+- verify parent-root `../docs/questions.md` exists from the accepted clarification/question record when applicable
+- create parent-root `../submission/` for final generated submission artifacts and reviewer-facing proof
+- 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/`
+- relocate screenshots and proof materials relevant to runtime behavior and major flows into parent-root `../submission/`
+- 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
+
+## Session export sequence
+
+For the developer session, run these exact steps:
+
+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`
+
+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
+- immediately verify that all expected directories and required files exist before running later packaging steps
+- if the required utilities or output files are missing, packaging is not ready to continue
+
+## Required file moves
+
+- if repo-local `docs/` exists, treat it as accidental residue, reconcile any missing content into parent-root `../docs/`, and remove it from the delivered `repo/` tree
+- if current `.tmp/` exists, move the whole directory to parent-root `../.tmp/` before harvesting any reviewer-facing artifacts from it
+- after preserving parent-root `../.tmp/`, collect the relevant evaluation reports and proof artifacts from it into parent-root `../submission/`
+- collect screenshots and other required proof materials from repo-local runtime/output directories into parent-root `../submission/`
+- after relocation, the final submission should not require digging through repo-local output directories to find evidence
+- keep screenshot filenames clear enough that the referenced runtime page, flow, or evidence purpose is understandable
+
+## Repo cleanup rules
+
+- 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/`
+- 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
+- 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 required screenshots have been relocated into parent-root `../submission/`
+- confirm parent-root metadata fields are populated correctly
+- confirm session export naming rules are followed
+
+## Submission artifact and response contract
+
+- 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
+- the packaging-stage outputs are `FILE` outputs under `../submission/` plus `PARAGRAPH` outputs in the final packaging-stage response
+
+## Final packaging verification
+
+- do one final package review before declaring packaging complete
+- 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
+- do not close packaging until all required docs, exports, submission files, screenshots, and cleanup conditions are satisfied