MEGAINFRA-WEBAPP/docs/handoffs/2026-09-17-minimax-dn-tasks-6-11.md

Handoff brief — MiniMax: delivery note inbox Tasks 6–11

Paste this whole file as your instructions. Everything you need is either here or in the plan it names.

---

Your job

Implement Tasks 6, 7, 8, 9, 10 and 11 — and only those from:

docs/superpowers/plans/2026-09-17-dn-inbox-corrections.md

Read that plan first. It contains complete, final code for every step. It was written after auditing 34 real documents and the live database. Its code blocks are meant to be typed in as given.

Do not do Task 1 (manual n8n UI work), Task 12 (a human does the ledger audit), or Tasks 2–5 (already done).

Starting state

• Branch: fix/dn-inbox-corrections — stay on it, do not create another.
• Starting commit: b4b6108
• Baseline: 882 tests passing, npm run typecheck clean. If either is broken before you start, stop and say so.
• Tasks 2–5 are already merged into this branch. src/lib/dn-pipeline/ currently contains: types.ts, segment.ts, checks.ts, extract.ts, split.ts, promote.ts, run.ts and their tests. match-po-item.ts and aliases.ts do not exist yet — you create them in Tasks 6 and 7.

---

HARD CONSTRAINT 1 — never write to PocketBase

The PocketBase instance is production, holding real supplier payment data.

Tasks 7, 10 and 11 tell you to create scripts/pb-*.py migration scripts.

CREATE THE SCRIPT FILES. DO NOT RUN THEM.

Skip every step that runs one (Task 7 Step 2, Task 10's "run it twice", Task 11 Step 1b). Note in your report that you skipped them. A human runs all migrations after reviewing them.

Also forbidden:

• any curl with POST, PATCH, PUT or DELETE against the PocketBase URL
• running any existing scripts/pb-*.py or scripts/migrate-*.py
• npm run dev and any attempt to exercise the UI against live data

Read-only curl -s GET against PocketBase is allowed if you must inspect a schema. You should not need to.

Consequence: Tasks 7, 10 and 11 add database fields your code then reads. Those fields will not exist while you work, so you cannot run the app end to end. That is expected. Your acceptance gate is the unit tests, not a live run.

HARD CONSTRAINT 2 — never improvise

If a code block in the plan looks wrong to you, implement it exactly as written and flag it in your report. Several decisions are deliberate and counter-intuitive:

• A check returning passed: null is not a failure. Only false blocks a note.
• A purchase order line with no unit must not block a delivery.
• resolvePoItem returning ambiguous is a correct, desirable outcome. Do not "fix" it into a match.
• The allNotesPromoted gate in run.ts is intentionally redundant. Leave it.

If a plan step quotes code that does not match the real file:

STOP. Do not guess. Leave that step undone and report the exact difference.

Guessing is how data gets silently corrupted here. A reported mismatch costs a human two minutes; a wrong guess costs a wrong supplier payment.

HARD CONSTRAINT 3 — Task 6 is the one that can cost money

Task 6 builds the matcher that decides which purchase order line a delivery line refers to — and therefore which rate gets applied to real money.

Two earlier attempts at this produced wrong matches:

Slip line	Wrongly matched to	Correct answer
U PIPES-600 X 2.5(100D)	S&S Pipes-1050 X 2.5(100D)RR	IJ PIPES-600 X 2.5(100D)
160x6M KABELFLEX PIPE & COUPLING	160mm uPVC Cl 16 Pipe	160mm Sleeves Black

A wrong match is worse than no match. A block is visible and costs someone two minutes; a wrong match silently pays the wrong amount.

Task 6's test file contains 15 ground-truth cases plus a test named never returns a wrong match for any known input. Every one must pass.

If a case fails, fix the implementation — never loosen WORD_FLOOR (0.30) or MARGIN (0.15) to make it pass. Those numbers were tuned against 23 real descriptions. If you believe one must change, stop and report it instead.

---

Order of work

Strictly sequential. Task 8 depends on 6 and 7. Do not reorder.

Task	What	Gate
6	match-po-item.ts — three-outcome matcher	its 15 test cases pass
7	aliases.ts + alias collection script	aliases.test.ts passes
8	Wire matcher + aliases through checks, promote, run	full suite passes, grep -rn "matchPoItem" src/ returns nothing
9	Resolve-item route + board UI	typecheck clean
10	Document type classification	full suite passes
11	open_pages — stray page stops blocking	full suite passes

What to run

Do run these. Run them often.

npx vitest run src/lib/dn-pipeline/<file>.test.ts   # one file
npm run test:run                                     # full suite
npm run typecheck                                    # must be clean before every commit

npm run typecheck must pass before every commit. If it fails, fix the cause — do not commit and do not comment out the failing code.

Commits

Commit per task, using the exact message from that task's commit step. End each commit message with:

Co-Authored-By: MiniMax <noreply@minimax.io>

Do not squash, do not amend, do not rebase, do not push.

Known trap, already hit once

Tasks 10 adds required fields to PageRead and NoteSegment. Every hand-built test fixture in promote.test.ts, run.test.ts and segment.test.ts will then fail typecheck until the new fields are added to them.

When that happens: add the new fields to those fixtures with values consistent with their siblings. Change no test logic and no assertions — fixture completeness only. This is expected and is not a sign you broke something.

---

Report back

Be specific and honest. A skipped step reported is fine; a skipped step hidden is not.

1. Per task: done or not, and the commit SHA.
2. Tests: final npm run test:run count, and the names of every test you added.
3. Typecheck: clean or not.
4. Skipped steps and why (the PocketBase ones are expected — list them anyway).
5. Mismatches: any place the plan's quoted code differed from the real file, with the exact difference. Quote both versions.
6. Migration scripts created but not run — list the file paths.
7. Anything in the plan you think is wrong. Do not act on it. Just say so.
8. Task 6 specifically: confirm the never returns a wrong match for any known input test passes, and state whether you changed WORD_FLOOR or MARGIN (you should not have).

What happens next

A human then:

• reviews every diff against the live database
• reads and dry-runs your migration scripts, then applies them
• runs Task 12: re-processes all 34 batches and audits every delivery line item for wrong product links

So: correctness and honest reporting matter far more than speed or completeness. If you finish four of the six tasks properly, that is a better outcome than six done loosely.