COMPLETION.md — the master completion checklist (no silently half-done work)
Written into the repo at the start of the complete-to-spec build program (PLANNING §97). Purpose: every screen, flow and print the specs promise is listed here with an honest status — nothing is "done" until it passes its Definition of Done AND the owner signs the phase's Verification Sheet. This document is the mechanism that makes "no half-hearted product" a checkable fact rather than a promise.
The agreement (PLANNING §97, this session)
- Model decision: deepseek-v4-flash ONLY for all development work — the cheapest flagship in the harness catalog (1M context, ~50x-cheaper cached re-reads). No other provider/model unless a concrete under-delivery is raised with the owner first — never speculative spend.
- Build stance: neither "from scratch" nor "patchwork" — REBUILD TO SPEC over the verified foundation (costing engine verified to the owner's sheet ~0.002%, the 27-table schema holding the real imported data: 909 contracts · 6,688 beams · 2,048 lots · 468 parties, the journey harness). Per phase/slice every existing piece is audited against the spec and classified KEEP or REBUILD by evidence; the verdict for every piece is recorded here (status column).
- Ordering: technically dependency-correct phases (0-8 below), NOT business priority — the system goes live only after complete development, so the build follows the dependency graph.
- Crew: role-separated agents with governed hand-offs; owner = product owner (decides, tests with real documents, signs).
Definition of Done — every slice must pass all six
- Every field the docs specify is present, entered the right way (auto / scan / select / number / text — no typing on the floor).
- The flow works end to end — a completed step creates the next step's card/record (no dead-ends).
- Paper prints match the agreed formats — only at EXTERNAL boundaries (internal steps are system-approval taps).
- The CSV/Excel dump works for that screen (DUMPS.md standard).
- Works with the real imported data — numbers make sense, nothing crashes, nothing silently drops.
- All existing checks stay green (unit suite + journey suite); nothing outside the slice was touched.
Then: the owner tests the slice with one real document from the desk the same day, and the phase's Verification Sheet is signed. If it does not match the real paper, that slice REOPENS.
How non-UI phases are verified (owner contract)
- Automated proof — the check suite is the measurement instrument; every phase adds its invariant tests. The owner sees "all checks green", never reads code.
- Plain-language Verification Sheet per phase — What changed / Why / How it is proven / Owner 5-minute spot-check / What it unlocks next. The owner signs the sheet, not the code.
- Observable spot-checks — e.g. Phase 0: log out and confirm every work screen refuses you and that no Edit/Delete exists outside the audited masters exception; Phase 2: Quote numbers == the owner's costing sheet.
The phases (dependency order — PLANNING §97)
Status values: pending · in-progress · done-verified (signed) ·
blocked-owner (waiting on a 10-minute owner decision).
| Phase | Contents | Status | Owner spot-check |
|---|---|---|---|
| 0 Foundations & invariants | Append-only/event enforcement (every mutation logs an event), role choke point (no anonymous writes, ROLE_PAGES coverage), test + deploy baseline green | done-verified (owner signed 2026-09-06 — PHASES-GUIDE spot-check; still green: suite ~1750+ incl. journey 53/53, BUILD-LOG rev 89) | Log out → screens refuse; no Edit/Delete outside masters; guards' picks appear in events |
| 1 Database complete | Full schema audit vs FIELDMAP: every table/column/status value set, types correct, tenancy seams, migrations captured | in-progress (near-complete) — migrations through 0015; added since 09-06: fabric_in, stocktake, production_plan, gatepass_link, mill_lot_no chain, dispatch address/bill/tags. Remaining: weft_issue table, winding-receipt cols (empties/ring-wt), contract_lines, lumps/bales entity (blocked-owner ③), numbering sequences (blocked-owner ①), GSTIN (blocked-owner) | Open a party/yarn/design record; all expected fields present; data intact |
| 2 Engine & domain services | Costing/conversion (multi-warp/weft, margin table, GST toggles), krill solver, capture parser, numbering/event/amendment/approval services — all unit-tested | in-progress (code-complete, sign-off pending) — yarnMath spec-6b row-aware + per-row GST pinned to sheet (~0.002%); tippanSolver guards + regression pins; ops role choke + amend/approve flows; capture parser; GP→lot automation; per-role queue. Remaining: owner-blocked numbering, amendment APPLY semantics, winding cone-measure confirmation | Quote numbers == owner's costing sheet |
| 3 Shared platform layer | List standard (search/filter/sort/pagination), record pages + amend/approve/print verbs, CSV dumps, error banners, comboboxes — built once, consumed by all screens | in-progress (built, never formally verified) — SmartTable/ListToolbar/RecordDialog/ReviewSheet/Combobox live on all list screens; record + amend/approve/print verbs; /api/dump CSVs; UploadDrop; design-conformance + monochrome pass (PLANNING §§194–195). Needs owner walkthrough to sign | Pick any list screen; search/filter/sort work; row opens its record |
| 4 Transactional spine (dependency-ordered) | masters → commercial (leads/quote/orders + amendments/approvals) → yarn procurement (booking/rates/procure) → yarn intake & stock (gatepass → gate-in → lot → stock → movements → allocations) → beams & sizing → weaving → checking/grading → dispatch → hishob & reconciliations | in-progress — built: masters, commercial, procurement, intake & stock COMPLETE (gate evidence persisted, per-bag grain + Code39 G4 label print, bag-grain weft-issue/stocktake/movements, B4 allocations), D2 weft-issue, beams/sizing/winding, planning/loomgate/beam-end, checking + report, fabric-in, dispatch, hishob/recon. Missing: folding screen, lumps→bales flow, contract_lines grid, GAP-21/22 outward-fill + stock-transfer print | Per slice: one real document entered end-to-end |
| 5 Read models | Boards/dashboards (BOARDS-A), realtime hub, reports, dump station — aggregates over real data | in-progress (partial) — home per-role pending queue, /board, /reports, checking report, dump station + upload-reports. Pending: realtime hub, full BOARDS-A tile set | Dashboard numbers match this morning's reality |
| 6 Capture & OCR | Handwritten paper → system (per-form templates), camera QR scanner, rate-list/contract OCR | in-progress (substantially built) — /capture + share_target, /api/capture drafts funnel, /api/ocr (server tesseract), QR-assisted beam-out (C61), vehicle-no OCR. Per-form handwritten-template coverage not yet audited | Photo a handwritten gatepass → fields prefill → confirm |
| 7 External integrations & packaging | Tally bridge (file contract), Android APK, WhatsApp confirm-links finalization, tenancy/Postgres stage-2 trigger check | in-progress (partial) — file interchange live (/imports, /upload-backup, BRIDGE.md), WhatsApp share-links (no automation by policy, mandate 6). Pending: Tally bridge (F4 deferred to reports freeze), APK, Postgres trigger check | — |
| 8 Hardening & cutover | Role-by-role journey run on real data, security audit, performance pass, full owner walkthrough, sign-off, one flip | pending (role-gating deferred to here per F0-7; gates stay open through the build) | Owner walks every screen |
Refreshed 2026-09-14 (PLANNING §199) — table untouched since 09-06; every status above re-verified against the code (routes, schema, engine, tests, BUILD-LOG revs 89–95). No phase signed beyond 0; Phase 8 is the only fully-pending one.
Phase-0 findings ledger (verified by reading the code — PLANNING §97)
| # | Finding (silent mutation — no event logged) | Disposition |
|---|---|---|
| F0-1 | Guard exit tap updates gatepass → picked without an event (guard/+page.server.ts) | fixed + regression test (deployed 3dfe0be) |
| F0-2 | Transporter pick updates → picked/partial without an event (transporter/+page.server.ts) | fixed + regression test (deployed 3dfe0be) |
| F0-3 | Draft discard → discarded without an event (drafts/+page.server.ts) | fixed + regression test (deployed 3dfe0be) |
| F0-4 | Owner-approval API /api/approve mutates without its own event (ops.ts approve*) | fixed + regression test (deployed 3dfe0be) |
| F0-5 | Dispatch load marks rolls dispatched without per-roll events (dispatch/+page.server.ts) | fixed + regression test (deployed 3dfe0be) |
| F0-6 | Rate-board create insert unlogged (rates/+page.server.ts) | fixed + regression test (deployed 3dfe0be) |
| F0-7 | Role-gate coverage: /reports /quote /drafts /runner /masters /search open to all logged-in roles | deferred-owner (2026-09-06: owner defers role-gating until project done — gates stay open through the build; per-role composition set at Phase 8 hardening) |
Progress ledger (append per phase/slice, newest last)
- Phase 0 slice 1 (event invariance) DEPLOYED: F0-1…F0-6 fixed with regression pins (tests/events.test.ts; suite 93 green, type-check exit 0, build clean), live via deploy 3dfe0be. F0-7 resolved by owner decision 2026-09-06: role-gating deferred until project end (PLANNING §98).
- Phase 0 VERIFIED + SIGNED (owner, 2026-09-06): owner completed the 10-minute spot-check per docs/PHASES-GUIDE.md (logged-out bounce to sign-in; no Edit/Delete outside audited masters; guard exit tap leaves its event trace; paper trail rev 47) and signed the Verification Sheet. Phase 0 status → done-verified. Next: Phase 1 (database complete).
Phase-2 kickoff (owner, 2026-09-06)
Owner: "start phase 2. it will be very crucial to get this right. here full flow will be your guide along with all other docs." Phase 2 = Engine & domain services (PHASES-GUIDE "the calculator"). Per the program contract (PLANNING §97) every existing piece is audited against the spec and classified KEEP/REBUILD by evidence — nothing is presumed; verdicts land in the §2 ledger below. Verification contract: unit suite against COSTING.md §5 (yarn maths ~0.002% vs the owner's sheet), plus the per-piece checks from PHASES-GUIDE §Phase 2; the Phase-2 Verification Sheet closes the phase (owner 10-minute check: quote numbers == costing sheet).
Pieces under audit (with spec sources)
- yarnMath (src/lib/server/yarnMath.ts) vs COSTING.md §5 + §10 (kg↔mtrs incl. denier /9000, 0.5905/Ne, multi-warp/weft splits, lasa/ L2L warp allowance, size add-on, weft waste, margin 1–20%, GST toggles).
- tippanSolver (krill × parts → beams/warping) vs FIELDMAP §3.46/C1, BUSINESS.md alleys.
- intake / capture parser (forward/OCR drafts → fields) vs full-flow G0/direct-delivery + FIELDMAP.
- ops services (document numbering, logEvent/appendAmendment, approvals) vs full-flow paper trail + PLANNING events/amendments.
Phase-2 audit — verdicts & dispositions (2026-09-06)
Audit run against COSTING.md §5 trace + FIELDMAP/full-flow (yarnMath audited in-session cell-by-cell; tippanSolver / intake / ops audited by parallel agents with file:line evidence). Verdicts:
| Piece | Verdict | Key findings → disposition |
|---|---|---|
| yarnMath | PARTIAL-FIX → engine complete | ① K corrected to sheet (110/104.25, ≤0.003% on cost cells) ② warping line implemented ③ invalid counts skipped. Round 4: spec-6b row-aware costing with per-row GST% + incl/excl toggles and per-row rates implemented (design weights expose per-row kg/m; gstTotal + per-row cost breakdown in the result; legacy trace path byte-identical). Open: row-aware entry UI (Phase-3/4) — engine is spec-complete and pinned. |
| tippanSolver | PARTIAL-FIX | ① krill=0 → infinite loop (Infinity parts) → input guards + throws + regression pins. ② soft end-slack was dead code → slack now proposes the slack-reduced part count (1210/1200 → 1 part). ③ cone-measure must also bound parts (BUSINESS.md) — needs owner's winding-process confirmation before semantics are set (open). ④ ends derivation lacks the FIELDMAP width-shrink term — schema has no shrink column yet (Phase-1 item) (open). |
| intake (capture) | rounds 3+5 closed | |
| ops | PARTIAL-FIX → rounds 2+5 closed | ① numbering sequential — open, tied to the pending owner numbering decision (blocked-owner). ② role gate moved INTO the service + reconciliations/[id] routes through ops (FIXED, tests/ops-role.test.ts). ③ amendments: NO more byte-identical snapshot notes — reason-only amends + genuine fields diff path (round 5); the APPLY + owner-approval stage (spec §30) awaits the owner's amendment-semantics decision (blocked-owner). ④ mutation+event ONE transaction per approval (FIXED); ⑤ re-approval no-ops (FIXED); ⑥ api/amend actor from session (FIXED); /api/events dedupe at the route (FIXED round 5; unique index deferred to Phase-1 migration). Round 5 also: intake numeric bounds + OCR exit-code retention. Suite 133/133 (tests/phase2-round5.test.ts). |
Open Phase-2 work (tracked): yarnMath per-row GST toggles (spec 6b) · tippanSolver cone-measure + shrink · intake GP/DD fields · ops numbering/ role-in-service/amend-applies/transactionality — each with its regression pins before close. Owner spot-check items per PHASES-GUIDE §Phase 2: quote construction → weight ladder + ₹/m vs costing sheet · margin 1–20% & GST toggles · krill solver parts · procurement suggestion numbers.
Phase-1 kickoff (2026-09-06) — sequencing correction
Owner: "what I meant by phase 2 was phase 1." Phase 1 (Database complete) is now the active phase; the Phase-2 engine run stays verified. Audit fan-out (agents): ① masters fields (party/yarn/design/loom/flange) vs FIELDMAP §1 · ② status/dropdown value sets · ③ tenancy + migrations + data integrity · ④ the documented forms' field coverage vs the app. Verdicts per piece land below; fixes ship with regression pins; imported data stays an invariant.
Phase-1 preliminary verification notes (2026-09-06, read-only ground truth)
- Migration series 0000–0008 all present (drizzle/); live data.db has NO __drizzle_migrations journal → the DB was push-generated; drift between snapshot DDL and live DDL must be verified per the tenancy/migrations audit (in flight).
- Confirmed gap (migration 0009+):
design.warp_shrinkage_pctdoes not exist (FIELDMAP C1 "total ends = EPI×width+shrink"; currently ends are reed×warp_reed_space with no shrink term). - Company identity: src/lib/company.ts has name+address but gstin is EMPTY (prints show the ________ placeholder) — this is the owner's pre-listed decision ① (GSTIN for the print header) → blocked-owner.
- Imported-data counts: auditor query in flight (909·6,688·2,048·468 claim to be confirmed against data.db).
- Audit fan-out running: masters fields · status/dropdown value sets · tenancy+migrations+data · form-field coverage. Verdicts will land below on completion.
Phase-1 audit ledger (2026-09-06 — consolidated)
| Area | Verdict | Evidence |
|---|---|---|
| Tenancy seams | PASS 27/27 tables carry tenant_id+setup_id (migration 0006) | agent report + direct grep; staging per PLATFORM §3 (single-tenant go-live) |
| Migrations 0000–0008 | PASS — zero drift; live DDL == snapshot 0008; series clean on scratch DB | agent report (PRAGMA compare); live DB has no journal (push-built) |
| Imported data | PASS — 909 orders · 6,686 beams (+2 fx) · 2,047 lots (+1) · 464 parties (+4), all match PLANNING:2112 | agent counts vs claim |
| Masters | 5/5 KEEP — Party/Yarn/Loom/Flange complete; Design gaps FIXED (warping rate, GLM, GST, shrink, rows rate/GST) | masters agent + tests/masters.test.ts pins |
| Status value sets | CONSISTENT — live distinct values within documented sets (order open/closed · gatepass intimated/due/delivered · roll A/B/R FG/dispatched/reject · beam floor/onLoom/finished/repair); formal text({enum}) pass is a follow-up | direct sqlite distinct query |
| Schema expansion | DONE via migration 0009 — 9 columns + evt unique index applied; 609 designs preserved | migrated live DB + snapshot 0009 |
| Company GSTIN | owner-gated (decision ①) — src/lib/company.ts gstin empty; prints show placeholder | agent + code |
| Bale/lump entity | owner-gated (decision ③) — no lump class, no bale table; SO deliveryForm:lump is a dead end | coverage agent F8 |
| Form coverage | ~35 forms · ~30 screens; 5 screens field-gapped; 2 no screen (lumps/bales, fabric-inward) — top schema gaps queued for Phase-4 spines (sizing-receipt grid, weft-issue loom/shift/type, winding empties/ring-wt, contract_lines, dispatch address/bill/tags) | coverage agent F1–F12 |
Fixes shipped: buildDesignValues + DesignForm (warpingRatePaise/glm/ gstPct/warpShrinkagePct inputs; rows rate/gstPct/inclusive quints), PartyForm Transport, migration 0009 as above. Pins 141/141, journey 53/53, deployed 4724e0d (PLANNING §110, BUILD-LOG 59). Verification Sheet for Phase 1 to follow once the owner-gated calls are in.