[obvious-autobuild]

LeChef beyond chat: spec (five jobs, cook mode, contracts, mocks)

Draft for review — do not merge. Adds docs/spec/lechef/ under alpha: the full LeChef spec (SPEC.md, assembled from SPEC-part1–5) plus a machine-checked contract pack under docs/spec/lechef/contracts/.

Human author: Sam Gu (sgu07966@gmail.com)

What changed and why

SPEC.md (17 sections) turns LeChef from a transcript with a camera into the cooking companion PR #86 §4 defines: five local-first jobs (plan, substitute, coach, adapt, remember), dedicated surfaces with chat as a fallback, a phone-authoritative proposal/receipt model, device-persisted timers, and push-to-look as the default camera direction. Key reconciliation decisions (researched from the open draft PRs):

• feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102 wire contract adopted and re-cut (rename map in §8.1, machine-checked): envelope {id, tool, payload, payloadHash, snapshotRevision, createdAt, expiresAt, requiredApproval?, userInitiated?} from src/lechef/wire.ts:169-181; re-cut to proposalID under the phone's prop_ prefix, top-level snake_case kinds (camelCase payload kinds hoisted: timerStart→timer_start … note→save_note), sha256:-prefixed hash, additive display-only rationale, optional requiredApproval. Nine payload kinds: feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102's six re-cut plus the three application kinds (plan, swap, adaptation); suggest_recipe is a read tool, not a proposal.
• Overhaul: reviewed substitution table (data milestone 1) #114 substitution corpus adapted: role-scoped reviewed swaps derived from pairs.json (schema 1.1.0: 279 pairs, 381 ingredients, 11 roles, 13 restrictions), rechecked fail-closed via exact facts_key match; composition-unknown blocks rather than warns.
• Stop persisting camera frames; bound transient cache; add 24h session expiry #26/feat(backend): harden live-agent authority boundaries #39 privacy and authority findings tightened: frames in process memory only (two-minute cache), 24-hour session expiry, bounded snapshot; the phone's persistent receipt log is the dedupe authority across restarts.
• LeChef suite D: 155 scripted sessions + fail-closed scorer, real run #101's 158-session corpus (despite its 155-session title) anchors §10's evaluation gates: safety and pantry-truth assertions as pass/fail.
• feat(ios): weekly-plan planner core, flow, store, and check harness #52/feat(planning): calculate missing groceries for a guest menu #141/Add guest menus with stock review and grocery quantities #142 planning patterns merged into one deterministic allocator over a single stock pool (no double counting; unknown quantity = unavailable), not a second planner.

contracts/ — six JSON Schemas (proposal, receipt, cook-step, plan, substitution, scaling-rules), nine example fixtures (including #102's frozen action-proposal.json), and check.py.

---

Review round 1 (post #147 independent review) — commit 9d987b3

All three findings adopted; none disputed. One directional choice, explained below.

1. HIGH — proposal envelope schema vs the #102 wire it cited — FIXED

• proposal.schema.json now requires snapshotRevision (integer ≥ 1), giving §8.1's revision-binding rule the wire field it rode on in prose only. Both proposal fixtures carry it (12, matching the receipt examples).
• rationale and requiredApproval are now optional — feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102's wire has no rationale, and requiredApproval is absent from its frozen fixture; the phone still derives and always emits requiredApproval on re-cut proposals (§8.1 prose says exactly this now).
• The "verbatim" claims are gone: §8 intro, §8.1's rules line, and the schema title/description now say adopted and re-cut, list feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102's actual camelCase payload kinds (timerStart…note, types.ts:259-281 — save_note is a rename of note), and give the full rename map (id→prop_-prefixed proposalID, kind hoisted to top-level snake_case, bare-hex hash sha256:-prefixed). §14's feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102 row carries the same map. §8.3's "Adopted verbatim" became "Adapted from".
• New cross-check (the reviewer's (c)): contracts/examples/action-proposal-102.json is feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102's frozen fixture fetched verbatim from overhaul/lechef-f1; check.py maps it through the rename map and requires the mapped envelope to validate against proposal.schema.json. The mapping recomputes the hash per the runtime rule (wire.ts:90-93 — sha256 over compact canonical JSON of the payload) because the frozen fixture's literal payloadHash is a placeholder: it reproduces neither the payload digest (95281fe6…) nor any constant I could identify (verified: it is not sha256 of "hello world", b94d27b9…).
• Why the re-cut envelope stays (not feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102's raw wire): the reviewer's smallest-fix offered this path (add the field, fix the prose, add the round-trip), and the downstream tools PR feat(lechef): bounded tool layer, fake phone/model, and 65-session scripted suite #156 is already cut to these contracts — its README states "Wire shapes follow docs/spec/lechef/contracts/", its test file loads the contracts directory by URL and runs check.py, and its wire.ts/fakePhone.ts use proposalID, snapshotRevision, and sha256:-prefixed hashes (all read from feat(lechef): bounded tool layer, fake phone/model, and 65-session scripted suite #156's diff this round). Re-basing the schema on feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102's raw envelope now would move two open PRs for no behavioral gain; the map makes the re-cut traceable and machine-checked instead.

2. LOW — corpus-naming claim not supported — FIXED

§8.3 now says the three spec-added kinds are named by this spec's registry and that no plan/swap/adaptation kind string exists in #102's corpus or ProposalTool union — the unsupported "the suite's corpus already names them" claim is gone, as is §8.1's "the suite names speculatively".

3. LOW — check.py documents a hash round-trip it didn't perform — FIXED

• check.py now recomputes payloadHash = sha256 over the compact canonical JSON of the payload for every proposal fixture and compares (the docstring's claim, previously unchecked).
• Receipts are matched to proposals by proposalID (a receipt citing an unknown proposal id fails), replacing hash set-membership.
• resolve() fails loudly on an unknown $defs ref (was: silently validated as "any").
• The shoppingList emptiness error now fires only when short lines exist (was unconditional, with a message that could be wrong).

Fail-before-fix evidence (commands and results)

• Finding 1: after tightening the schema but before touching the fixtures, python3 contracts/check.py → exit 1: examples/proposal-substitute.json: 'snapshotRevision' is a required property + same for proposal-add-timer.json. Fixtures updated → green.
• Finding 3 (recompute): scratch-mutating proposal-substitute.json's payloadHash to sha256:000…0 → exit 1, two errors (recompute mismatch + its receipt's hash-equality mismatch). Under the old checker the same mutation only tripped set-membership — and only because both proposals are receipt-pinned; an unreferenced invented hash passed. Stated plainly: the reviewer's "an invented hash passes" was slightly overstated for these fixtures, the substance (no recomputation, reference-blind matching) was correct and is now fixed.
• Finding 3 (proposalID matching): mutating receipt-executed.json's proposalID to an unknown id → exit 1, references proposalID 'prop_01J9ZZZZZZ', which no proposal fixture defines.
• Finding 3 (fail-loud $defs): pointing a schema property at #/$defs/nope → exit 1, KeyError: 'unknown $defs reference: #/$defs/nope — fix the schema, do not validate as any'.
• Finding 1 (rename-map gate): setting the feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102 fixture's payload kind to the already-snake_case step_advance → exit 1, payload kind 'step_advance' is missing from the §8.1 rename map.
• Assembly invariant: SPEC.md is byte-identical to the parts pipeline (head -11 SPEC-part1.md + separators + tail -n +13 + parts 2–5), verified programmatically this round.
• All mutations were made on scratch copies and restored; final state: check.py: 23 checks over 6 schemas and 8 fixtures / OK — all schemas and fixtures valid (was 20 checks).

What I could not check

• Nothing here builds an app target — docs and JSON schemas only; swift test / macOS CI compile the untouched app targets on this branch but exercise none of this content.
• §8.4's step shape remains RECONCILE against the future recipes spec; §13's TasteEvent kinds defer to the taste spec (separate packets, not in this PR).
• feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102/LeChef suite D: 155 scripted sessions + fail-closed scorer, real run #101/Overhaul: reviewed substitution table (data milestone 1) #114 remain open drafts; if they change before adoption, §8/§10/§14 need another pass. The feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102 fixture embedded here is a copy as of overhaul/lechef-f1 today — if feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102 edits it, check.py's placeholder-hash comment will not catch a drift (only the rename-map and mapped-envelope checks run).

Assumptions

• Base branch is alpha per the packet id; branch obv/burst5-fridgeluck-spec-lechef. Review fixes pushed as a fast-forward (no force-push), PR stays draft.
• Keeping the re-cut envelope rather than re-basing on feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102's raw wire — justified by feat(lechef): bounded tool layer, fake phone/model, and 65-session scripted suite #156's live dependency above; the reviewer's smallest-fix path (a)+(b)+(c) is what landed.

Co-authored-by: obvious-autobuild[bot] <262744130+obvious-autobuild[bot]@users.noreply.github.com>

🔗 Obvious Project · 🧵 Obvious Thread · 🔀 Obvious PR Artifact

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: b07332fc-ff20-45a4-a826-fddea4571b71

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[obvious-autobuild]

Independent review (Obvious, Autobuild + Max)

Verdict: changes needed — small schema/prose edits only; the spec's research claims check out almost everywhere, but the proposal envelope schema cannot validate a proposal produced by the wire contract it says it adopts verbatim, and it drops the field its own revision-binding rule needs.

Findings (by severity)

1. HIGH — proposal envelope schema is not the #102 wire it claims to adopt, and omits snapshotRevision

• Claim under test: SPEC.md:306 — "This section adopts PR feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102's pinned wire contract verbatim (src/lechef/wire.ts …) rather than inventing a parallel one"; SPEC.md:323 — "Rules (all verbatim-adapted from feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102 unless noted)"; schema title proposal.schema.json:4 "(ActionProposalWire, adopted from PR feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102)"; PR body — "feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102 wire contract adopted verbatim".
• feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102's actual envelope (pr-102 src/lechef/wire.ts:169-181): { id, tool, payload, payloadHash, snapshotRevision, createdAt, expiresAt, requiredApproval?, userInitiated? }, with the kind discriminant inside the payload in camelCase (fixture action-proposal.json: "kind": "stepAdvance") and payloadHash as a bare hex digest (wire.ts:90-93, digest("hex")).
• This PR's proposal.schema.json requires proposalID, a top-level snake_case kind, rationale (a field feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102's wire does not have) and mandatory requiredApproval (optional in feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102 — absent from its own frozen fixture), requires payloadHash to carry a sha256: prefix, and sets additionalProperties:false. It would reject every feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102-produced proposal on at least five counts.
• Sharpest part: the schema has no snapshotRevision on the proposal (the only occurrence in §8's examples is on the receipt, SPEC.md:340), yet SPEC.md §8.1 rules say "a proposal built at an older snapshot revision is rejected as 'superseded' at approval". feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102's envelope carries that field (snapshotRevision, present in its frozen fixture); this schema would reject it via additionalProperties:false. The revision-binding rule currently has no wire field to ride on.
• Attribution: SPEC.md:332 calls the six kinds "The six registered in feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102's registry: timer_start · … · save_note". feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102 registers camelCase payload kinds timerStart, timerAdjust, stepAdvance, inventoryCorrection, mealLog, note (types.ts:259-281; ProposalTool = the six propose* tools, types.ts:247-253); no snake_case kind exists anywhere in feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102's tree (git grep timer_start|step_advance|meal_log on pr-102 → zero hits). save_note is a rename of feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102's note. SPEC.md:486 (§14) does declare the re-cut — but §8:306/332 contradict it while asserting verbatim adoption.
• Smallest correct fix: (a) add snapshotRevision (integer ≥ 1) to proposal.schema.json's required properties and to both proposal fixtures; (b) reword SPEC.md:306/332 to "adopted and re-cut" (matching §14) and either list feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102's actual kind names with a rename map or drop the "feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102's registry" attribution; (c) ideally add one check.py cross-check that round-trips a feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102-shaped action-proposal.json envelope — it would have caught every mismatch above. (Unchanged and verified-correct: TTL 300 s = feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102's PROPOSAL_TTL_SECONDS at types.ts:358; derived requiredApproval = feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102's approvalFor(...) at proposals.ts:188; receipt state enum matches feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102 exactly.)

2. LOW — corpus-naming claim not supported

• SPEC.md:373 — "The three spec-added kinds are named exactly as the suite's corpus already names them, so no harness mismatch is introduced". In pr-102's evaluation corpus (src/lechef/designs/*/scripts/*.json) there are zero occurrences of "plan", "swap", or "adaptation" as kind strings, and the ProposalTool union has only the six propose* tools. The claim's supporting evidence doesn't exist on the branch it cites.
• Smallest correct fix: reword to name this spec's registry as the source of the names (or cite the actual corpus file that uses them, if one exists elsewhere).

3. LOW — check.py documents a hash round-trip it doesn't perform

• check.py:10 (docstring cross-check 2) and the PR body say receipt payloadHash values are "computed over the canonical payloads, not invented"; the code (check.py:197-198) only checks set membership against the proposal fixtures' own hash strings and never recomputes any digest (hashlib is never imported). A proposal fixture with an invented payloadHash passes the "machine-checked" pack.
• For the record, I recomputed both digests myself and they do reproduce: sha256 over json.dumps(payload, sort_keys=True, separators=(",",":")) yields 557d9ef5… (timer) and 3ec4d524… (swap), matching the fixtures. The fixtures are right; the checker just doesn't police it.
• Smallest correct fix: in step 4, recompute the digest per proposal fixture and compare (and match receipts to proposals by proposalID, not just set membership). Two adjacent one-liners while in there: resolve() (check.py:147-149) silently maps an unknown $defs ref to {} (accept-anything) — fail loudly instead; and the shoppingList emptiness error fires unconditionally, so its "short lines exist" message can be wrong when no short lines exist.

What I verified (commands and results)

• gh pr view 147 --comments / --json: draft, base alpha@0309dd11, head 615fc1b6; no human reviews; sole comment is CodeRabbit's "review skipped". gh pr checks 147: build-and-test pass (5m52s), dead-code-advisory pass (2m45s) — run 38722083500.
• gh pr diff --name-only: 21 files, all under docs/spec/lechef/ — docs-only scope as claimed; nothing else touched.
• Checked out head 615fc1b in a worktree; python3 contracts/check.py → check.py: 20 checks over 6 schemas and 8 fixtures / OK — all schemas and fixtures valid, exit 0, exercised the real jsonschema 4.26.0 Draft 2020-12 path; also green with jsonschema import blocked (the inline fallback validator), same 20 checks.
• Negative controls on a scratch copy (mutate → run → restore): expiresAt +1 s → expiresAt != createdAt + 300 s; receipt hash zeroed → payloadHash does not match any proposal fixture; fitSummary.totalLines +1 → counted 4 lines, fitSummary.totalLines is 5; allergen mustard → schema enum + nine-class cross-check errors; kind add_timer → enum rejection; unknown field → additionalProperties rejection. All exit 1 — the checker's cross-checks fail when they should. check.py does not exist on origin/alpha (new-dir PR, as the body says).
• Retired-kind sweep reproduced: no add_timer/substitute_ingredient/start_cook_session/change_quantity in SPEC*.md; suggest_recipe appears only as prose stating it is not a proposal kind (SPEC.md:332).
• Assembly claim reproduced: cat SPEC-part1..5.md differs from SPEC.md only by the --- separators between parts.
• Overhaul: reviewed substitution table (data milestone 1) #114 claims verified on pr-114 data/substitutions/pairs.json: schema_version 1.1.0, 279 pairs, 381 ingredients, 11 roles, 13 restrictions, 9 allergen classes, and exactly 123 of 381 ingredient records carry facts_key (258 fail closed) — SPEC.md:§6's numbers are all exact.
• LeChef suite D: 155 scripted sessions + fail-closed scorer, real run #101/feat(data): resolve ingredient identity and compile validated bundle-v2 #158 claim: LeChef suite D: 155 scripted sessions + fail-closed scorer, real run #101's title says "155 scripted sessions"; feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102's merged-suite body reports "158/158 sessions conform" — matching the body's "158-session corpus (despite its 155-session title)".
• alpha@0309dd1 evidence spot-checks: LiveAssistantView.swift is 777 lines; liveSessionStore.ts:242-256 is recordLatestFrame persisting latestCameraFrame to Firestore; toolRegistry.ts has get_recipe_context (line 26) and mutate_inventory (line 96); planning/stage_0-brainstorm/fridgeluck planning.md:1205 carries the guard-rails quote verbatim.

What I couldn't verify

• The other drafts' CI runs themselves (feat(lechef): shared LeChef tool layer — phone-authoritative proposals, read tools, eval harness (Part 1, M1) #102's "434 tests / 0 failures", Overhaul: reviewed substitution table (data milestone 1) #114's validator, LeChef suite D: 155 scripted sessions + fail-closed scorer, real run #101's scorer execution) — I verified constants, counts, and shapes on their branch heads, not their test executions.
• Nothing here builds an iOS target; docs-only, so no Swift was compiled by me (hosted macOS CI built the untouched app targets green, above). The swift test claims in §15's slices are future work, not this PR.
• The deferred packets (docs/spec/recipes/, docs/spec/taste/) that §8.4/§13 mark RECONCILE are not in this PR, so their side of the reconciliation is unchecked.