theslopmachine 1.0.2 → 1.0.3

package/assets/slopmachine/phase-2-plan-template.md

@@ -3,6 +3,8 @@
 Use this template to produce the accepted execution plan.
 The output should normally be written to `plan.md`.
 
+> Write this template section by section, appending each completed section to `plan.md`. Do not paste full section text in chat or dump the accumulated document at the end.
+
 This file is the authoritative execution checklist inside the repo.
 
 ---
@@ -30,12 +32,13 @@ This file is the authoritative execution checklist inside the repo.
 - No unauthorized narrowing
 - No `.env` or `.env.example` files anywhere
 - Tests travel with implementation
-- Shared files are main-lane controlled
+- Shared files are controlled by the primary implementation sequence
 - Runtime/test must remain honest and portable
-- Final integrated verification and hardening is mandatory
+- Final integrated local verification and hardening is mandatory
+- External planning documents under `../docs/` are planning/reference inputs only. Delivery evidence must exist inside the repo through `README.md`, code structure, route/app/server registration, tests, scripts, config/manifests, Docker/runtime files, and seeded/bootstrap paths where applicable. Do not rely on parent-directory docs as the only evidence for any final delivery, runtime, README, API, frontend, security, or test obligation.
 
 ### 1.3 Handoff exceptions
-| Exception | Why it exists | Impact | Required owner decision |
+| Exception | Why it exists | Impact | Required decision |
 |---|---|---|---|
 |  |  |  |  |
 
@@ -49,13 +52,22 @@ This file is the authoritative execution checklist inside the repo.
 - Shared-foundation-first rule:
 - Parallelization rule:
 - Merge discipline rule:
-- Final convergence rule: `P5` is one minimal gate that includes the owner-run local test harness. If that passes and the repo is roughly coherent with `plan.md`, stop and ask whether to proceed to evaluation. Fix only owner-side local-harness/config/wrapper/README/docs/light-script churn there, reroute any real code or actual test-file work back to the developer, and defer Docker/runtime plus dockerized `./run_tests.sh` to final packaging confirmation.
+- Vertical implementation rule: build one complete user/operator flow end-to-end before starting the next; do not build broad placeholder coverage across modules
+- Form-contract rule: every form must have matching frontend field names and backend handler field names, proven by a test that submits the rendered form through the real handler
+- Runtime-wiring rule: every background job must be wired from the entrypoint and verified reachable before claiming complete
+- Security-layer rule: every security control must be enforced at the correct layer (service, middleware, DB, template, runtime) before claiming complete
+- No artifact-count completion rule: do not claim completion based on file counts, route counts, template counts, or test counts
+- Final convergence rule: once implementation is complete, run the accepted local harness, reconcile the repo against `plan.md`, fix narrow docs/config/wrapper/light-script issues directly when assigned, route real code or test-file fixes through the active correction workstream, and leave Docker/runtime plus dockerized `./run_tests.sh` for the explicit final runtime confirmation step.
+
+If your active instruction asks only for implementation readiness, report readiness after integrated local verification and a truthful handoff.
+
+If implementation is explicitly scoped end to end in one autonomous execution run, it must not stop at rough local readiness. It must continue through all implementation, assigned tests, README/runtime/script reconciliation, integrated local verification, and final truthful handoff unless the active instruction explicitly says to stop earlier.
 
 ---
 
 ## 3. Scaffold Step at the Start of Development
 
-This section is planned during `P2` and then executed as the first step of development. It is not a separate lifecycle phase or owner gate.
+This section is planned before implementation and then executed as the first step of development. It is not a separate product feature.
 
 This scaffold step should be strict and straightforward. Its job is only to establish the minimal honest delivery baseline before real feature development starts.
 
@@ -64,10 +76,12 @@ This scaffold step should be strict and straightforward. Its job is only to esta
 - Exact bootstrap command:
 - Expected directories/files immediately after bootstrap:
 - Language/framework bootstrap notes to preserve:
+- Frontend defaults applied if prompt/repo are silent: Vue 3 + Vite + TypeScript, Tailwind CSS, and shadcn/ui when compatible:
 - Minimal bootstrap proof surface to land now (for example a hello-world route/page/app shell):
-- Docker/runtime setup required in this step so the owner can later run `docker compose up --build` during final packaging confirmation:
+- Docker/runtime setup required in this step so `docker compose up --build` can be run during final runtime confirmation:
+- Seeded quick-start data strategy required in this step, or `Not Applicable` with reason:
 - `./run_tests.sh` setup required in this step as the dockerized broad-test path reserved for final packaging confirmation:
-- Local test harness setup required in this step so development and owner-side `P5` can use it:
+- Local test harness setup required in this step so implementation and later local readiness checks can use it:
 This should name the stack-native local suite explicitly, for example Vitest, Jest, PHPUnit, pytest, go test, cargo test, or another framework-native equivalent.
 - Reliability rules the local test harness and deferred Docker/runtime plus dockerized broad-test path must satisfy later:
 Include what must be installed/configured locally if the stack-native local suite is not already available on the machine.
@@ -75,29 +89,30 @@ Include what must be installed/configured locally if the stack-native local suit
 - Local testing harness/tooling to establish now:
 - Exact README template/section structure to land now:
 - Files that must exist before deeper feature work:
-- Stop boundary if the owner explicitly isolates only this step:
+- Stop boundary if the active instruction explicitly isolates only this step:
 - Completion evidence for this step, including Docker/runtime files and dockerized `./run_tests.sh` being present plus the separate local test harness being prepared honestly:
 
 ### 3.1 Required scaffold work inside development
 
 - bootstrap the project for the selected language/framework/runtime with only a minimal hello-world-style proof surface
-- set up the real Docker/runtime path required by the project so the owner can run `docker compose up --build` later during final packaging confirmation
+- set up the real Docker/runtime path required by the project so `docker compose up --build` can run later during final runtime confirmation
+- set up deterministic, idempotent seeded quick-start data through the normal bootstrap/database/runtime path when the product is not useful from an empty state
 - set up repo-root `./run_tests.sh` as the real dockerized broad-test entrypoint for the later final packaging confirmation run
 - make the local test harness and deferred Docker/runtime plus dockerized broad-test path reviewably reliable: no hidden setup steps, no manual exports for Docker, no hidden shell state for local tests, deterministic execution, and useful failure output
 - do not run Docker or dockerized `./run_tests.sh` during the scaffold step; prepare the local harness for immediate development use
-- set up the local testing harness/tooling used for ordinary development and owner-side `P5`
+- set up the local testing harness/tooling used for ordinary development and later local readiness checks
 - set up `README.md` to the exact required template/section shape
 - keep the scaffold free of prompt-specific business logic, deep domain implementation, or polish work beyond the baseline needed to prove startup and test wiring
 - require the scaffold to avoid local dependency setup beyond Docker and the documented host minimums
 - finish this step before broader module implementation starts
-- once this step is complete, continue directly into the remaining development work unless the owner explicitly says to stop
+- once this step is complete, continue directly into the remaining development work unless the active instruction explicitly says to stop
 
 ---
 
 ## 4. Security Execution Contract
 
 ### 4.1 Security-sensitive surfaces
-| Surface | Required control | Must land before module implementation? | Owning module/lane | Required negative tests |
+| Surface | Required control | Must land before module implementation? | Responsible module/work package | Required negative tests |
 |---|---|---|---|---|
 |  |  |  |  |  |
 
@@ -106,16 +121,16 @@ Include what must be installed/configured locally if the stack-native local suit
 -
 -
 
-### 4.3 Security lane plan if needed
-- Dedicated security lane needed? [yes/no]
+### 4.3 Security work package plan if needed
+- Dedicated security work package needed? [yes/no]
 - If yes:
-  - Lane label:
+  - Work package label:
   - Owned files:
-  - Merge target:
+  - Integration target:
   - Blocking dependencies:
-  - Merge gate:
+  - Integration check:
 
-### 4.4 Security merge gates
+### 4.4 Security integration checks
 -
 -
 -
@@ -123,33 +138,36 @@ Include what must be installed/configured locally if the stack-native local suit
 ### 4.5 Role Surface Matrix
 Required for any role-sensitive project. If not applicable, state `Not Applicable` and why.
 
-| Route / page / API / action / data object / notification / export / admin function | Roles allowed | Read/write scope | Object ownership rule | Admin override rule | Viewer/read-only rule | Audit/logging requirement | Frontend route/nav expectation | Required implementation evidence | Required test evidence |
+| Route / page / API / action / data object / notification / export / admin function | Roles allowed | Read/write scope | Object ownership rule | Admin override rule | Viewer/read-only rule | Logging/accountability requirement | Frontend route/nav expectation | Required implementation evidence | Required test evidence |
 |---|---|---|---|---|---|---|---|---|---|
 |  |  |  |  |  |  |  |  |  |  |
 
-Any contradiction between this matrix and `../docs/design.md`, `../docs/api-spec.md`, router/frontend behavior, backend checks, README, or tests is a planning defect before development and a release-alignment defect before evaluation.
+Any contradiction between this matrix and `../docs/design.md`, `../docs/api-spec.md`, router/frontend behavior, backend checks, README, or tests is a planning defect before development and a release-alignment defect before handoff.
 
 ---
 
 ## 5. Test Coverage Execution Contract
 
 ### 5.1 Coverage target and floor
-- Coverage target: meaningful mapped tests for every evaluator-relevant endpoint, core flow, security boundary, and major failure path
+- Coverage target: meaningful mapped tests for every delivery-relevant endpoint, core flow, security boundary, and major failure path
+- Unit coverage floor: at least `90%` line/branch coverage for unit-testable product code where stack tooling can measure this honestly; otherwise name the exact measurement limitation and substitute a complete file/function/assertion ledger
+- E2E/platform coverage floor: at least `90%` of planned prompt-critical E2E/platform flow rows complete before clean development completion; otherwise name the exact accepted exception and compensating proof
+- API coverage floor when APIs exist: `100%` of documented prompt-relevant `METHOD + PATH` surfaces have true no-mock HTTP tests unless a per-endpoint narrow exception and compensating proof are recorded
 - Measurement path:
 - Confidence notes / expected weak spots if any:
 
 ### 5.2 Surface-to-test mapping
-| Planned surface / work package | Source requirement ID(s) | Required test layers | Planned test files / suites | Coverage evidence expected | Owning lane | Merge proof required |
+| Planned surface / work package | Source requirement ID(s) | Required test layers | Planned test files / suites | Coverage evidence expected | Responsible module/work package | Integration proof required |
 |---|---|---|---|---|---|---|
 |  |  |  |  |  |  |  |
 
 ### 5.3 Full prompt-relevant surface inventory
-| Surface / flow / module | Source requirement ID(s) | Unit coverage | API coverage | Integration coverage | E2E/platform coverage | Planned test files / suites | Owning lane |
+| Surface / flow / module | Source requirement ID(s) | Unit coverage | API coverage | Integration coverage | E2E/platform coverage | Planned test files / suites | Responsible module/work package |
 |---|---|---|---|---|---|---|---|
 |  |  |  |  |  |  |  |  |
 
 ### 5.4 Important risk coverage
-| Risk point | Planned tests | Expected assertions | Owning lane |
+| Risk point | Planned tests | Expected assertions | Responsible module/work package |
 |---|---|---|---|
 | 401 unauthenticated |  |  |  |
 | 403 unauthorized |  |  |  |
@@ -170,7 +188,7 @@ Any contradiction between this matrix and `../docs/design.md`, `../docs/api-spec
 ### 5.5 Frontend coverage obligations
 If applicable:
 - frontend unit tests required? [yes/no]
-- Frontend unit tests verdict for later audit: [PRESENT | MISSING]
+- Frontend unit tests status for later review: [PRESENT | MISSING]
 - frontend unit-test file-level evidence plan:
 - important frontend components/modules that must not remain untested:
 - component/state tests:
@@ -196,7 +214,7 @@ Required for every fullstack or backend-backed frontend project. If not applicab
 
 Planning must prove both directions before development starts: every meaningful frontend surface must have real backend support, and every prompt-relevant backend capability must be surfaced in the frontend or explicitly justified as internal/API-only.
 
-| Frontend page/component/action | User intent / requirement ID | Backend `METHOD + PATH` / service / job used | Request payload / query / state input | Expected response / side effect | Frontend states to implement | Real integration proof planned | Owner/lane |
+| Frontend page/component/action | User intent / requirement ID | Backend `METHOD + PATH` / service / job used | Request payload / query / state input | Expected response / side effect | Frontend states to implement | Real integration proof planned | Responsible module/work package |
 |---|---|---|---|---|---|---|---|
 |  |  |  |  |  | loading / empty / submitting / disabled / success / error / duplicate-action |  |  |
 
@@ -233,6 +251,7 @@ If applicable:
 - accepted `../docs/api-spec.md` source of truth:
 - resolved endpoint inventory required? [yes/no]
 - target `100%` of documented `METHOD + PATH` surfaces through true no-mock HTTP tests unless a narrow exception is accepted:
+- any endpoint below true no-mock HTTP coverage must have a row naming the exception reason, compensating proof, residual risk, and acceptance decision:
 - allowed exceptions:
 - exact planned API test files / suites by endpoint family:
 - endpoint-family mapping table or equivalent location in this plan:
@@ -294,9 +313,10 @@ The final `README.md` must include these sections exactly:
 8. verification method
 9. testing
 10. authentication and roles
-11. workflow / operational notes if applicable
-12. feature-flag/mock/debug/demo disclosure if applicable
-13. important limitations or non-goals if material
+11. quick-start seeded data
+12. lifecycle / operational notes if applicable
+13. feature-flag/mock/debug/demo disclosure if applicable
+14. important limitations or non-goals if material
 
 ### 6.1 Required command strings
 - `docker compose up --build`
@@ -309,9 +329,16 @@ Choose one:
 - credentials table for every relevant role
 - exact statement `No authentication required`
 
+### 6.2.1 Quick-start seeded data rule
+Choose one:
+- seeded accounts/sample records/fixture data table with values, roles, IDs, URLs, and steps needed to exercise the main flows quickly
+- exact statement `No seeded data required; the app is useful from an empty state` with a short reason
+
+Seeded data must be deterministic and idempotent. It must be created by the normal runtime/bootstrap/database path, not by hidden manual setup. It may provide local demo/test fixtures, but it must not replace real product behavior with fake success paths or static demo-only UI.
+
 ### 6.3 Ownership rule
-- Main-lane owner:
-- Parallel lanes may propose updates through:
+- Primary-sequence responsibility:
+- Parallel work packages may propose updates through:
 - Final reconciliation point:
 
 ---
@@ -341,7 +368,7 @@ Choose one:
 
 ## 9. Module-First Product Decomposition
 
-Planning must identify modules before creating execution order or file/location ownership details. A full optimistic file tree is no longer required; file, route, directory, and test paths should be named where they make module packets executable and reviewable.
+Planning must identify modules before creating execution order or file/location responsibility details. A full optimistic file tree is no longer required; file, route, directory, and test paths should be named where they make module packets executable and verifiable.
 
 ### 9.1 Module inventory
 | Module | Requirement IDs | Purpose | Actors served | Owns frontend surfaces? | Owns backend/API/jobs? | Owns data/storage? | Core success behavior | Depends on |
@@ -370,7 +397,7 @@ Every critical module behavior needs at least one assertion-level row. Generic p
 ### 9.3 Module coverage contract
 Every module must have concrete planned proof. Do not let a module rely only on broad smoke tests unless it is truly a trivial wrapper and the reason is stated.
 
-| Module | Unit tests | API tests | Integration tests | E2E/platform tests | Frontend component/state tests | Required negative/risk tests | Main-lane module verification before development exit | Coverage owner |
+| Module | Unit tests | API tests | Integration tests | E2E/platform tests | Frontend component/state tests | Required negative/risk tests | Integrated module verification before development exit | Coverage responsibility |
 |---|---|---|---|---|---|---|---|---|
 |  |  |  |  |  |  |  |  |  |
 
@@ -384,7 +411,7 @@ Every module must have concrete planned proof. Do not let a module rely only on
 - every frontend-bearing module must have real backend wiring when backend support exists
 - every backend feature required by the prompt must be exposed through the frontend when user-facing, or explicitly marked internal/API-only with accepted rationale
 - every module must own or explicitly inherit its unit/API/integration/E2E/frontend-state proof
-- every module must be rechecked by the main lane after fan-in before development is declared complete: files are real, integrated, covered by assigned tests, and not orphaned from the rest of the app
+- every module must be rechecked after fan-in before development is declared complete: files are real, integrated, covered by assigned tests, and not orphaned from the rest of the app
 - lazy completion examples that must not pass: shell handlers, hardcoded success, uncalled services, static demo data presented as backend data, disconnected forms, TODO client methods, untested security checks, and orphaned backend capabilities
 
 ### 9.5.1 Module requirement closure checklist
@@ -395,12 +422,29 @@ Each module packet must carry this checklist into development. A module may not
 |  |  |  |  |  |  | planned |
 
 ### 9.6 Development exit module verification matrix
-Complete this before leaving development for owner-side integrated verification. Use the stack-native local suite and targeted module tests; Docker and dockerized `./run_tests.sh` remain deferred to final packaging confirmation.
+Complete this before claiming development readiness. Use the stack-native local suite and targeted module tests; Docker and dockerized `./run_tests.sh` remain deferred to the explicit final runtime confirmation step.
 
-| Module | Files reviewed by main lane | Module tests run | FE↔BE wiring verified | API/route coverage verified | E2E/platform proof status | Integration issues found/fixed | Exit status |
+| Module | Files reviewed after integration | Module tests run | FE↔BE wiring verified | API/route coverage verified | E2E/platform proof status | Integration issues found/fixed | Exit status |
 |---|---|---|---|---|---|---|---|
 |  |  |  |  |  |  |  | pending |
 
+### 9.7 Plan-Row Execution Ledger
+Every actionable plan row must appear here or in an equivalent section-specific checklist. This ledger is the source of truth for whether `plan.md` was actually executed, not merely referenced.
+
+| Plan section / row | Required implementation evidence | Required verification evidence | Responsible module/work package | Status | Blocker / risk / exception |
+|---|---|---|---|---|---|
+|  |  |  |  | planned |  |
+
+Clean development completion requires every row to be `complete`, `not applicable`, or explicitly `risk accepted` with evidence. Rows left `planned`, `in progress`, `delegated without receiver`, or `unverified` block completion.
+
+### 9.8 Coverage Closure Ledger
+
+| Coverage surface | Required floor | Measured / closed result | Evidence path | Exception / compensating proof | Status |
+|---|---|---|---|---|---|
+| API true no-mock HTTP coverage for documented prompt-relevant endpoints | 100% |  |  |  | planned |
+| Unit-testable product-code line/branch coverage | >=90% where measurable |  |  |  | planned |
+| Planned E2E/platform-critical flow coverage | >=90% closed rows |  |  |  | planned |
+
 ---
 
 ## 9.7 In-Scope Domains / Modules Summary
@@ -469,12 +513,19 @@ Every accepted requirement, clarification, design no-orphan row, and API spec ro
 - Retention/reporting/scheduling rules if applicable:
 
 ### 13.1 Prompt-Critical Rule Matrix
-Every prompt-critical rule must have an owner and a proof path. Include dates, thresholds, limits, states, scheduling/timing, retries, security constraints, public/private boundaries, actor identity, and operator promises.
+Every prompt-critical rule must have a responsible implementation surface and a proof path. Include dates, thresholds, limits, states, scheduling/timing, retries, security constraints, public/private boundaries, actor identity, and operator promises.
 
-| Source prompt phrase / accepted clarification | Normalized rule | Implementation owner | Test owner | README/doc implication | P5 proof expectation | Status |
+| Source prompt phrase / accepted clarification | Normalized rule | Implementation responsibility | Test responsibility | README/doc implication | Local proof expectation | Status |
 |---|---|---|---|---|---|---|
 |  |  |  |  |  |  | planned |
 
+### 13.1.1 Prompt Verb Acceptance Matrix
+Every action verb in the original prompt or accepted clarification that implies product behavior must have an acceptance row. Use this to prevent broad nouns such as `dashboard`, `lifecycle`, `approval`, `export`, or `sync` from hiding missing actor actions.
+
+| Source phrase / verb | Actor | Starting state / fixture | Action performed | Required state change or side effect | Observable UI/API/artifact result | Negative or edge behavior | Proof path | Owning module |
+|---|---|---|---|---|---|---|---|---|
+|  |  |  |  |  |  |  |  |  |
+
 ### 13.2 Scaffold Versus Product Completion Matrix
 
 Use this to prevent setup shells from being mistaken for delivered behavior. A row may move to `done` only when the product-facing path is wired to real behavior and tests.
@@ -491,7 +542,7 @@ Use this to prevent setup shells from being mistaken for delivered behavior. A r
 
 ## 14. State / Lifecycle Rules
 
-| Entity / workflow | States | Valid transitions | Invalid transitions | Required cleanup |
+| Entity / lifecycle | States | Valid transitions | Invalid transitions | Required cleanup |
 |---|---|---|---|---|
 |  |  |  |  |  |
 
@@ -563,12 +614,22 @@ Complete only when the product has background work, timed behavior, async jobs,
 - If yes, where it is called:
 - If no, why not applicable:
 
+### 18.4 Seeded quick-start data
+- Seeded data applicable? [yes/no]
+- If yes, seed entrypoint and when it runs:
+- Idempotency rule:
+- Seeded accounts / roles:
+- Seeded sample records / IDs / URLs:
+- Main flows the seeded data unlocks:
+- README quick-start section responsibility:
+- If no, why the app is useful from empty state:
+
 ---
 
 ## 19. Delivery Review Requirement Matrices
 
 ### 19.0 Core Semantic Path Proof
-This is the centerpiece path that proves the product is not only a shell. `P5` cannot close unless this path is explicitly proven or the user accepts a named residual risk.
+This is the centerpiece path that proves the product is not only a shell. Do not claim implementation readiness unless this path is explicitly proven or the user accepts a named residual risk.
 
 | Field | Required value |
 |---|---|
@@ -580,17 +641,17 @@ This is the centerpiece path that proves the product is not only a shell. `P5` c
 | Expected failure-mode behavior |  |
 | Test file(s) proving the path |  |
 | Manual/runtime proof if automated proof is not feasible |  |
-| P5 acceptance evidence expected |  |
+| Local readiness evidence expected |  |
 
 ### 19.0.1 Prompt-critical proof ledger
-Use this ledger during development and `P5` to prevent planned-but-missing drift.
+Use this ledger during development and readiness hardening to prevent planned-but-missing drift.
 
 | Planned claim | Required proof | Current proof location | Gap | Decision |
 |---|---|---|---|---|
 |  |  |  |  |  |
 
 ### 19.1 Prompt-fit and end-to-end delivery obligations matrix
-| Obligation | Planned repo evidence | Planned verification evidence | Owning lane |
+| Obligation | Planned repo evidence | Planned verification evidence | Responsible module/work package |
 |---|---|---|---|
 | core business goal preserved |  |  |  |
 | main user flows complete |  |  |  |
@@ -599,18 +660,21 @@ Use this ledger during development and `P5` to prevent planned-but-missing drift
 | explicit non-goals are safe |  |  |  |
 
 ### 19.2 Static reviewability and repository traceability obligations matrix
-| Obligation | Planned repo evidence | Planned verification evidence | Owning lane |
+| Obligation | Planned repo evidence | Planned verification evidence | Responsible module/work package |
 |---|---|---|---|
 | startup path traceable |  |  |  |
 | broad test path traceable |  |  |  |
 | entry points visible |  |  |  |
 | route registration visible |  |  |  |
 | config path centralized |  |  |  |
+| README/docs/scripts/routes/config/examples/manifests/env examples statically consistent |  |  |  |
 | module boundaries visible |  |  |  |
+| no excessive single-file implementation or fragmented snippets |  |  |  |
+| redundant/unnecessary files removed or justified |  |  |  |
 | mock/local-data boundary visible |  |  |  |
 
 ### 19.3 Runtime and broad-test contract obligations matrix
-| Obligation | Planned repo evidence | Planned verification evidence | Owning lane |
+| Obligation | Planned repo evidence | Planned verification evidence | Responsible module/work package |
 |---|---|---|---|
 | exact runtime command honored |  |  |  |
 | exact broad test command honored |  |  |  |
@@ -624,7 +688,7 @@ Use this ledger during development and `P5` to prevent planned-but-missing drift
 | Linux portability is preserved |  |  |  |
 
 ### 19.4 Logging, validation, and error-handling obligations matrix
-| Obligation | Planned repo evidence | Planned verification evidence | Owning lane |
+| Obligation | Planned repo evidence | Planned verification evidence | Responsible module/work package |
 |---|---|---|---|
 | logging categories explicit |  |  |  |
 | redaction enforced |  |  |  |
@@ -633,7 +697,7 @@ Use this ledger during development and `P5` to prevent planned-but-missing drift
 | operator-visible failures traceable |  |  |  |
 
 ### 19.5 Backend and API obligations matrix
-| Obligation | Planned repo evidence | Planned verification evidence | Owning lane |
+| Obligation | Planned repo evidence | Planned verification evidence | Responsible module/work package |
 |---|---|---|---|
 | endpoint inventory complete |  |  |  |
 | endpoint coverage summary computable |  |  |  |
@@ -643,24 +707,28 @@ Use this ledger during development and `P5` to prevent planned-but-missing drift
 | API surfaces mapped to tests |  |  |  |
 
 ### 19.6 Frontend and UX obligations matrix
-| Obligation | Planned repo evidence | Planned verification evidence | Owning lane |
+| Obligation | Planned repo evidence | Planned verification evidence | Responsible module/work package |
 |---|---|---|---|
 | pages/routes/screens complete |  |  |  |
+| pages/routes/app shell connected |  |  |  |
 | core interactions complete |  |  |  |
+| state/data flow organized and traceable |  |  |  |
+| service/adaptor/mock/storage boundaries clear |  |  |  |
 | task closure real |  |  |  |
 | UI states complete |  |  |  |
 | validation/disclosure explicit |  |  |  |
 | frontend test obligations explicit |  |  |  |
 | static visual/interaction quality evidence planned |  |  |  |
+| pure-frontend mock/local data disclosed without implying backend integration where applicable |  |  |  |
 
 ### 19.7 End-to-end and platform verification obligations matrix
-| Obligation | Planned repo evidence | Planned verification evidence | Owning lane |
+| Obligation | Planned repo evidence | Planned verification evidence | Responsible module/work package |
 |---|---|---|---|
 | major flow E2E/platform coverage exists |  |  |  |
 | platform-proof boundary is honest |  |  |  |
 
 ### 19.8 README and documentation obligations matrix
-| Obligation | Planned repo evidence | Planned verification evidence | Owning lane |
+| Obligation | Planned repo evidence | Planned verification evidence | Responsible module/work package |
 |---|---|---|---|
 | README exists at repo root | `README.md` | static file check |  |
 | project type near top is one of `backend`, `fullstack`, `web`, `android`, `ios`, `desktop` |  | static README check |  |
@@ -671,17 +739,29 @@ Use this ledger during development and `P5` to prevent planned-but-missing drift
 | access method documented |  |  |  |
 | verification method documented |  |  |  |
 | credentials/no-auth disclosure correct |  |  |  |
+| quick-start seeded data or empty-state rationale documented |  |  |  |
+| Configuration and Environment Model explains local config, runtime defaults, Docker/Compose defaults, seeded/bootstrap data, auth/no-auth, no committed `.env` requirement, no manual package/runtime/database setup beyond documented host prerequisites, and config-sensitive verification |  | static README/config check |  |
+
 | no manual install/runtime setup dependency (`npm install`, `pip install`, `apt-get`, manual DB setup, `.env`, `.env.example`) |  | static README/config check |  |
 | mock/debug/demo disclosure honest |  |  |  |
 
+If no configuration is required, the README should state: `No manual environment configuration is required for local Docker startup. The delivered local runtime uses repo-controlled Docker/Compose defaults and bootstrap paths.`
+
 ---
 
 ## 20. Shared-File Contract
 
-| Shared file / surface | Why shared | Main-sequence owner | Module edit rule | Notes |
+| Shared file / surface | Why shared | Primary-sequence responsibility | Module edit rule | Notes |
 |---|---|---|---|---|
 |  |  |  |  |  |
 
+### 20.0 Canonical Cross-Surface Contracts
+Use this when data crosses boundaries between UI, API, jobs, imports, exports, notifications, files, reports, clipboard payloads, templates, or third-party adapters. If not applicable, state `Not Applicable`.
+
+| Contract / payload | Surfaces using it | Canonical schema or fields | Validation / normalization rule | Producer | Consumer | Tests / proof | README or docs implication |
+|---|---|---|---|---|---|---|---|
+|  |  |  |  |  |  |  |  |
+
 ### 20.1 Shared foundation to land before module execution
 -
 -
@@ -689,7 +769,7 @@ Use this ledger during development and `P5` to prevent planned-but-missing drift
 
 ### 20.2 Execution order rule
 - scaffold step lands first
-- shared foundation lands second in the main lane
+- shared foundation lands second in the primary implementation sequence
 - ordered module packets execute after the shared foundation is stable
 - helper work is used only for low-risk independent module packets or verification tasks where it is safer than normal sequential execution
 - full-suite, E2E/platform-equivalent, and cross-module verification run after all modules are built
@@ -698,7 +778,7 @@ Use this ledger during development and `P5` to prevent planned-but-missing drift
 
 ## 21. Ordered Module Packet Execution Map
 
-Default to executing modules one by one in the main developer lane. Use helper work only when a module packet or verification task is genuinely independent and lower risk than serial execution. Every module packet must be complete enough to execute without inventing scope, files, tests, or proof.
+Default to executing modules one by one in the primary implementation sequence. Use helper work only when a module packet or verification task is genuinely independent and lower risk than serial execution. Every module packet must be complete enough to execute without inventing scope, files, tests, or proof.
 
 | Module order | Module ID | Purpose | Dependencies | Owned files/directories | Explicitly shared files | Owned tests | FE↔BE/API proof | File/import/route/service/data existence proof | Verification before next module | Standard completion checklist | Helper work? |
 |---|---|---|---|---|---|---|---|---|---|---|---|
@@ -709,7 +789,7 @@ For each module, the plan should name the exact actor-facing flows, routes/scree
 Module completion evidence must use the standard completion checklist and include owned file/test list, exact verification commands/results, FE↔BE proof where applicable, real file/import/route/service/data proof, and a self-check that owned files are not placeholders or orphan code.
 
 ### 21.1 Module packet sequence
-This section must be directly executable after scaffold and shared foundation land. The developer should be able to complete each module packet in order without inventing ownership, tests, FE↔BE proof, file-existence proof, or report shape.
+This section must be directly executable after scaffold and shared foundation land. The developer should be able to complete each module packet in order without inventing file responsibility, tests, FE↔BE proof, file-existence proof, or report shape.
 
 Every module packet below must include: module ID, requirement IDs, owned files/tests, forbidden shared files, frontend/backend/data/security/failure-state scope, verification commands, and required standard completion checklist.
 
@@ -722,26 +802,33 @@ Every module packet below must include: module ID, requirement IDs, owned files/
 Each module must produce this packet before the next module starts:
 
 - Module ID and status: complete, partial, or blocked
-- Files changed and ownership status
+- Files changed and responsibility status
 - Requirement IDs closed, partial, or blocked
 - Tests added or updated and proof intent
 - Exact verification commands run and results
 - FE↔BE proof where applicable
 - Security and failure-state proof
-- Shared integration required from main lane
+- Shared integration required from the primary sequence
 - Known risks or `none`
 
+### 21.1.1.1 Plan Section Closure Evidence
+Every major completion claim must cite the accepted `plan.md` sections it closes. A development-complete report is incomplete if it only summarizes work without mapping back to section-addressable plan evidence.
+
+| Plan section / matrix row | Closure evidence | Test or verification result | Residual risk or blocker | Decision |
+|---|---|---|---|---|
+|  |  |  |  |  |
+
 ### 21.1.2 Module Integration Consumption Rule
 
 - Inspect each module completion checklist before moving to the next module
 - Reject incomplete or misleading packets instead of silently marking the module complete
 - Integrate helper work one module at a time when helper work is used
-- Wire shared surfaces only in the main lane unless this plan explicitly delegates them
+- Wire shared surfaces only in the primary sequence unless this plan explicitly delegates them
 - Rerun each module's targeted tests in the integrated checkout after the module is wired
 - Record integrated evidence in the development completion report
 
 ### 21.2 Optional Helper Opportunities
-Use only when safer than normal sequential execution. Do not add branch/worktree mechanics unless the owner explicitly asks.
+Use only when safer than normal sequential execution. Do not add branch/worktree mechanics unless explicitly required for implementation.
 
 | Module/task | Why helper execution is safer | Owned files/tests | Shared-file restrictions | Verification commands | Integration rule |
 |---|---|---|---|---|---|
@@ -803,38 +890,39 @@ For `web` and `fullstack`, frontend unit/component/state tests are required unle
 - Android broad proof avoids emulator as default? [yes/no]
 - iOS Linux proof boundary stated honestly? [yes/no]
 - Platform honesty notes:
-- Rerun triggers after major merges:
+- Rerun triggers after major integrations:
 
-This section is about overall delivery verification planning. It must not imply that such proof runs before evaluation or before the owner-side pre-submission step.
+This section is about overall delivery verification planning. It must not imply that every broad proof runs during ordinary implementation unless the active instruction asks for it.
 
 ---
 
 ## 26. Integrated Verification and Hardening Plan
 
-### 27.1 Broad final proof
-- Static/non-Docker checks to use before evaluation:
-- Proceed-to-evaluation rule when those checks pass:
+### 26.1 Broad final proof
+- Static/non-Docker checks to use before readiness handoff:
+- Readiness handoff rule when those checks pass:
 - Major flow proof required:
 - Security/auth proof required:
 - Runtime/README contract proof required:
 - Coverage proof required:
-- Required internal `P5` issue-discovery loop: one evaluator subagent session; send the exact prepared evaluation packet once; run four additional same-session scans for additional prompt-fit/compliance, security, delivery, test-coverage, README/static-verifiability, mock/demo/fake-success, and frontend state/interaction issues not already reported; do not remediate between rounds; save five reports and extracted Blocker/High findings under `../.ai/p5-evaluation/`; consolidate, owner-analyze, route one developer remediation brief, verify fixes, then continue to the proceed-to-evaluation pause
-- Development-completion audit before `P5`: reread original prompt, approved requirements breakdown, accepted clarifications, accepted design, accepted API spec when applicable, accepted `plan.md`, `../docs/test-coverage.md`, `README.md`, code, tests, and current proof in one sweep; every module row must be marked complete, blocked, or explicitly risk-accepted before handoff
-- P3 Development Completion Report must include: modules completed, requirements closed, files/routes/tests changed, unit/API/integration/E2E/frontend-state commands run, FE↔BE/API/data proof, edge/failure/security proof, remaining risks, and exact handoff status for `P5`
+- Independent readiness review expectation: after implementation, the repo must withstand a strict prompt-fit, security, delivery, test-coverage, README/static-verifiability, mock/demo/fake-success, and frontend state/interaction review. Fix all concrete Blocker/High-equivalent issues before handoff unless the user explicitly accepts the risk.
+- Development-completion review: reread original prompt, approved requirements breakdown, accepted clarifications, accepted design, accepted API spec when applicable, accepted `plan.md`, `../docs/test-coverage.md`, `README.md`, code, tests, and current proof in one sweep; every module row must be marked complete, blocked, or explicitly risk-accepted before handoff
+- Development Completion Report must include: modules completed, requirements closed, files/routes/tests changed, unit/API/integration/E2E/frontend-state commands run, FE↔BE/API/data proof, edge/failure/security proof, remaining risks, and exact readiness handoff status
+- Development Completion Report must include Plan Section Closure Evidence for every major plan section or matrix row that claims completion
 
-### 27.2 Narrow rerun strategy after discovered failures
-- Owner pass scope rule: every `P5` owner pass must reread the accepted design, accepted `../docs/api-spec.md` when applicable, `plan.md`, `README.md`, repo state, and current evidence in one full sweep rather than reducing follow-up passes to targeted sections only
+### 26.2 Narrow rerun strategy after discovered failures
+- Review scope rule: each integrated readiness pass must reread the accepted design, accepted `../docs/api-spec.md` when applicable, `plan.md`, `README.md`, repo state, and current evidence in one full sweep rather than reducing follow-up passes to targeted sections only
 - Known failure class isolation rule:
 - Narrow rerun examples:
 - When to stop broad reruns:
 - Issue-batching rule for integrated verification:
 - Owner-side fixes allowed directly before reroute:
-- Remediation expectation: default to ordered fixes through the main developer lane; use helper work only for genuinely independent fixes where that is safer, and require per-bundle verification plus integrated proof before accepting completion
-- Maximum owner sweep expectation from `P5` before evaluation: 3
-- Maximum developer reroute expectation from `P5` before evaluation:
+- Remediation expectation: default to ordered fixes through the active correction workstream, use helper work only for genuinely independent fixes where that is safer, and require per-bundle verification plus integrated proof before accepting completion
+- Maximum integrated readiness sweep expectation before handoff: 3
+- Maximum correction reroute expectation before handoff:
 
-### 27.3 Optional UI/platform sanity checks before evaluation
-- When extra UI/platform sanity is actually needed before evaluation:
+### 26.3 Optional UI/platform sanity checks before handoff
+- When extra UI/platform sanity is actually needed before handoff:
 - Screenshot review requirements if used:
 - Web/fullstack Playwright sanity if used:
 - Desktop Playwright Electron/Xvfb or equivalent sanity if used:
@@ -843,15 +931,15 @@ This section is about overall delivery verification planning. It must not imply
 - Visual regression notes if used:
 - Artifact storage notes if used:
 
-### 27.4 Doc tightening after verification
+### 26.4 Doc tightening after verification
 - `README.md`:
 - `../docs/design.md` if applicable:
 - `../docs/api-spec.md` if applicable:
 - `../docs/test-coverage.md` if applicable:
 
-### 27.5 Final close conditions
-- No major prompt, product, security, or runtime breakage remains obvious enough to make evaluation premature
-- Development-completion audit is done and the handoff to `P5` names exact passed checks, skipped/deferred checks, and residual risks
+### 26.5 Final close conditions
+- No major prompt, product, security, or runtime breakage remains obvious enough to make handoff premature
+- Development-completion review is done and the handoff names exact passed checks, skipped/deferred checks, and residual risks
 - Docker execution remains deferred until final packaging confirmation
 
 ---
@@ -863,7 +951,7 @@ This section is about overall delivery verification planning. It must not imply
 - Confirm mock/debug/demo disclosure:
 - Confirm shared-file coherence:
 - Confirm coverage docs and README match reality:
-- Confirm Docker files and dockerized `./run_tests.sh` are ready for final packaging confirmation, and confirm the separate local test harness is ready for ordinary development plus owner-side `P5`:
+- Confirm Docker files and dockerized `./run_tests.sh` are ready for explicit final runtime confirmation, and confirm the separate local test harness is ready for ordinary development plus later readiness checks:
 
 ---
 
@@ -877,11 +965,11 @@ The execution plan is ready only when:
 - any helper work is clearly safer than sequential execution and has owned files/tests, shared-file restrictions, verification commands, and an integration rule
 - each module packet names the exact behaviors it must finish rather than vague implementation buckets
 - tests are attached to each meaningful surface
-- the full prompt-relevant app surface is mapped to planned test ownership early
+- the full prompt-relevant app surface is mapped to planned test responsibility early
 - runtime/test/README contracts are exact
 - collision-safe runtime assumptions are explicit where relevant
 - final integrated verification includes exact README-documented external-contract proof when documented
-- the final integrated verification and hardening phase is explicit
-- merge/fan-in proof is explicit
+- final integrated verification and hardening is explicit
+- integration/fan-in proof is explicit
 - shell/demo/placeholder completion paths are made unacceptable by the plan structure itself
 - the plan is detailed enough to execute without broad reinvention