Skip to content

Spec2Contract Notebook

Grzegorz Nowak edited this page Oct 10, 2026 · 5 revisions

Spec-to-contracts — Notebook (book ↔ in-tests contracts)

This page maps the Product Book Notebook area (left-space IDs PB-NOTEBOOK-01…-49, 49 rows) onto the existing test fixtures. The contracts are carried mainly by the Notebook fixture family T08 (notebook.test.ts), T09 (topic.test.ts), and T10 (system-prompt.test.ts), with sealing cross-references from T11/T37/T44/T49 and the spawn family T01/T06. Junction rows below cite the named test case(s) that carry each assertion; split rows for a single claim are labelled by aspect in Notes.

T08 is tests/unit/notebook.test.ts; T37 is tests/unit/state-invariants.test.ts. All claims map to these existing fixtures.

KEEP is not a coverage status. -14/-15 describe index/plain previews with no clipping marker. Their ✅ status comes from the named T08 regression tests below. Clipping is recorded by a durable flag and surfaced through a read notice and human-only selector badge; custom write/read tool renderers have no clipping badges.

Junction rows

Claim ID Assertion (terse) Fixture(s) Status Notes
PB-NOTEBOOK-01 Notebook = name→markdown-body page map T08, T49 ✅ asserted T08 "notebook tools add/get/list return stable contract details" (write entry-a, read back body); T49 "notebook write/read round-trip" persists content.
PB-NOTEBOOK-02 Pages are branch/work-stream scoped, not forever memory T08 ✅ asserted aspect: branch scope. T08 "rehydration uses only the active session branch", "session_tree rehydrates notebook state branch-scoped: pages and epoch follow the branch, writes use B state".
PB-NOTEBOOK-02 Work-stream cache framing ("not forever memory") T10 ✅ asserted aspect: cache framing. T10 "CONTEXT_PRIMER states the notebook, topic, and handoff contracts" asserts /two-tier cache/i, /Keep pages compact/i, and rejects "durable cross-context grounding".
PB-NOTEBOOK-03 notebook_write requires string name + string content T08 ◐ partly asserted T08 exercises writes with {name, content}; the required schema (omission rejected) is not checked — no Value.Check on notebookWrite.parameters.
PB-NOTEBOOK-04 notebook_write describes kebab-case / stable subject-oriented names T08 ◐ partly asserted T08 "notebook tool definitions include prompt hints…" asserts guidelines /subject-oriented pages/i; the "kebab-case" wording in the name param description is not asserted.
PB-NOTEBOOK-05 Same-name write replaces whole body (refinement, not append/merge) T08, T49 ✅ asserted T08 "saveNotebookPage serializes concurrent writes and preserves completion order" (entry-a → "second"), "session_tree…" (a-v2); T49 "notebook_write overwrites existing page" (v2 present, v1 absent).
PB-NOTEBOOK-06 Writes serialized; same-name writes land in completion order T08 ✅ asserted T08 "saveNotebookPage serializes concurrent writes and preserves completion order", "saveNotebookPage keeps write order across runtime singleton swaps".
PB-NOTEBOOK-07 Success + page list; clipped writes add report and split advice T08, T49 ✅ asserted T08 "complete writes preserve their text list and existing detail fields", "write final and update text report clipping without a badge", "write final and update text report byte clipping" (notebook.test.ts:1098-1129,1448-1468); T49 "notebook write/read round-trip".
PB-NOTEBOOK-08 Doctrine: re-derivable code facts are discardable cache material T10, T11 ✅ asserted T10 CONTEXT_PRIMER test asserts rules /discard pages holding only recoverable code facts/i; T11 "handoff tool metadata and schema describe the prompt contract" asserts /reusable knowledge/i.
PB-NOTEBOOK-09 Doctrine: keep/refresh non-recoverable guidance, design, scope, working memory T10 ✅ asserted T10 CONTEXT_PRIMER test asserts rules /non-recoverable knowledge/i and /current state, blockers, and next steps/i.
PB-NOTEBOOK-10 notebook_read requires string page name T08 ◐ partly asserted T08 reads with {name}; required-schema (missing name rejected) not checked.
PB-NOTEBOOK-11 Existing page returns stored body envelope, plus notice if clipped T08, T49 ✅ asserted T08 "complete reads preserve their body envelope and existing detail fields" and "read appends a generic notice only for a flagged page" (notebook.test.ts:1131-1148,1470-1481); T49 "notebook write/read round-trip".
PB-NOTEBOOK-12 Missing page does not throw; Notebook page "<name>" not found. + page list T08 ✅ asserted T08 "notebook_read reports not found with current page names" (found:false, default message, page list).
PB-NOTEBOOK-13 notebook_index takes no parameters T08 ✅ asserted T08 invokes notebookIndex.execute("3", {}, …) and asserts result; no-arg invocation is the claim. Schema rejection of extra params not tested.
PB-NOTEBOOK-14 notebook_index lists name + first-line preview, or (empty) T08 ✅ asserted No clipping marker: "notebook tools add/get/list return stable contract details", "notebook tools show empty-state placeholders", and "model listing surfaces remain free of clipping decorations" (notebook.test.ts:1483-1518).
PB-NOTEBOOK-14 notebook_index order is alphabetical T08 ✅ asserted aspect: ordering. "plain page list and index preserve previews and alphabetical order" (notebook.test.ts:1402-1413) inserts zeta before alpha and asserts sorted output.
PB-NOTEBOOK-15 Preview = first line, capped 80 chars → 77 + ... T08 ✅ asserted Plain previews carry no clipping marker. "plain preview preserves the 80-character boundary" (notebook.test.ts:1397-1400) asserts exact 80/81-char boundaries and excludes the second line.
PB-NOTEBOOK-16 Write head-truncates at first of 2,000 lines / 50 KiB, keeps beginning T08 ✅ asserted "line overflow retains exactly 2000 whole lines", "byte overflow preserves the first whole line in ASCII and UTF-8", "complete and empty bodies remain accepted at the existing caps" (notebook.test.ts:1415-1446); exact byte-cap fixtures at :41-42.
PB-NOTEBOOK-17 Final/onUpdate text reports tail loss, amounts and split advice; details expose report/flag T08 ✅ asserted "line overflow returns exact head and line report", "byte overflow retains whole lines and reports bytes (ASCII + UTF-8)", "write final and update text report clipping without a badge", "write final and update text report byte clipping" (notebook.test.ts:1073-1129). Complete-write null/false: "complete write exposes null truncation and false clipped" (:1056-1071). These are result-text assertions, not custom-renderer tests.
PB-NOTEBOOK-18 Zero-content truncation rejected before mutation; prior state preserved; empty complete write valid T08 ✅ asserted "oversized first line rejects a new page without side effects", "rejected overwrite preserves prior body and clipped flag", "blank first line plus oversized line rejects and preserves prior page state" (notebook.test.ts:1150-1262) assert distinct errors and preservation, no updates/UI changes, and valid empty overwrite.
PB-NOTEBOOK-19 No page-count cap and no accumulated-page-size warning — ⚠️ no test yet Would need many/large writes and an assertion that no cap warning/notification is emitted and all pages are retained.
PB-NOTEBOOK-20 notebook_topic_set requires string topic T09 ◐ partly asserted T09 passes {topic}; required-schema (missing topic rejected) not checked.
PB-NOTEBOOK-21 Topic normalized: trim, lowercase, non-alnum→-, trim edge dashes, 80-char cap T09 ◐ partly asserted T09 "topic helpers manage the active notebook topic lifecycle" asserts trim + lowercase ("OAuth"→"oauth"); dash substitution, edge-dash trim, and 80-char limit untested.
PB-NOTEBOOK-22 Topic normalizing to empty rejected Notebook topic cannot be empty. T09 ✅ asserted T09 "notebook_topic_set preserves human authority…" (@@@ rejects /notebook topic cannot be empty/i).
PB-NOTEBOOK-23 No active topic ⇒ agent-sourced topic set, normalized value reported T09, T49 ✅ asserted T09 "notebook_topic_set establishes a fresh topic…" (details.topic="oauth", source agent); T49 "agent-set topic works when unset".
PB-NOTEBOOK-24 Re-setting same normalized topic is idempotent, reports already set T09 ✅ asserted T09 "notebook_topic_set establishes a fresh topic, is idempotent…" (changed:false, /already set to "oauth"/i).
PB-NOTEBOOK-25 Tool cannot change existing topic; directs to handoff T09 ✅ asserted T09 "…refuses overrides" (/already exists/).
PB-NOTEBOOK-26 Human-set topic authoritative; agent rejection says cannot override T09, T49 ✅ asserted T09 "…preserves human authority…" (/human-set notebook topic is authoritative/i); T49 "notebook topic lifecycle: set via command, agent-set blocked" (authoritative).
PB-NOTEBOOK-27 /notebook <topic> sets a human-sourced topic T08, T49 ✅ asserted T08 "/notebook notifies…" sets via command; T49 "notebook topic lifecycle…" proves the command set a human topic (agent override then blocked).
PB-NOTEBOOK-28 Changing an existing topic warns "likely task boundary … handoff recommended" T08 ◐ partly asserted T08 "/notebook notifies…" asserts warning level + /Active notebook topic changed: oauth → billing/; the explicit "likely task boundary / handoff recommended" wording is not matched.
PB-NOTEBOOK-29 Successful handoff clears active topic (next context sets fresh frame) T11, T10 ✅ asserted T11 "handoff onComplete fails gracefully…", "post-commit reporting failure…", "a host delivery rejection finalizes the cut…", "successor delivery is requested as a followUp…" all assert activeNotebookTopic === null; T10 primer asserts "assign a fresh topic again in the next context".
PB-NOTEBOOK-30 /new clears notebook pages and active topic T37 ✅ asserted T37 "Property 4: Reset clears all state fields" asserts resetState empties notebookPages and nulls topic/source (the /new path in index.ts session_start).
PB-NOTEBOOK-31 Status bar 🧭 <topic>; dim 🧭 - when no topic T44, T08 ◐ partly asserted Set-state asserted: T44 "updateIndicators shows active notebook topic when set" (🧭 oauth), T08 "/notebook …" (🧭 billing); the dim 🧭 - unset state is not asserted.
PB-NOTEBOOK-32 Pages survive handoff/resume (stored in session custom entries) T11, T08 ✅ asserted T11 "handoff with empty discardPages retains all pages"; T08 "session_start rehydrates the latest persisted notebook state through the full hook chain" (reason resume).
PB-NOTEBOOK-33 Content stored with committed generation; resume picks newest committed T08 ✅ asserted T08 "notebook rehydration rebuilds the latest epoch…" (keep→"newer"), "rebuilds from the latest persisted epoch…" (epoch 8); staged-discard tests keep abandoned entries invisible.
PB-NOTEBOOK-34 Committing a generation makes page set visible; newer generation supersedes T08 ✅ asserted T08 "committed discard advances the active generation and persists survivors" (epoch 2, survivors only), plus failed-retry fresh-epoch tests.
PB-NOTEBOOK-35 Session start and session-tree nav reconstruct from active branch T08 ✅ asserted T08 "session_start rehydrates… through the full hook chain", "session_tree rehydrates notebook state branch-scoped…".
PB-NOTEBOOK-36 Reconstruction scans newest→oldest, keeps only committed generation T08 ✅ asserted T08 "notebook rehydration rebuilds the latest epoch and enables notebook tools" (duplicate keep at epoch 2 resolves to newest "newer").
PB-NOTEBOOK-37 Handoff accepts optional discardPages names to remove stale pages T11 ✅ asserted T11 "successful handoff discards pages after compaction" (executes with discardPages), "handoff with empty discardPages retains all pages".
PB-NOTEBOOK-38 Discards staged; visible only after successful compaction T08, T11 ✅ asserted T08 "prepared discard remains invisible to a fresh active-branch rehydration", "committed discard advances the active generation and persists survivors".
PB-NOTEBOOK-39 Failed discard commit ⇒ all pages retained + handoff completion warning T11 ✅ asserted T11 "handoff onComplete fails gracefully when the discard commit marker throws", "post-commit reporting failure does not claim pages were retained", "async handoff compaction error retains discard pages and restores a ready retry status".
PB-NOTEBOOK-40 Every agent start injects ## Active Notebook Topic (topic or no-topic) T10 ✅ asserted T10 "before_agent_start injects notebook contracts plus live topic and page data" (## Active Notebook Topic, Current topic: `oauth` ), "…injects no-topic guidance when the topic is unset".
PB-NOTEBOOK-40 Topic line names the source (human-set / agent-set) T10 ◐ partly asserted aspect: source suffix. The injected (${source ?? "unknown"}-set) suffix is not asserted by T10.
PB-NOTEBOOK-41 Pages exist ⇒ inject ## Active Notebook Pages names + previews, not bodies T10 ◐ partly asserted T10 asserts the section, alpha: first line, and "Reference pages by name"; no assertion that full bodies (e.g. second line) are excluded.
PB-NOTEBOOK-42 Children get shared notebook write/read/index; pages visible parent↔child T01, T06 ✅ asserted T06 "real child prompt includes injected notebook pages", "…uses the 'No notebook pages.' branch…"; T01 "child tool names inherit active registered builtins and exclude recursive controls" (child names include notebook_write/read/index), "spawn execute builds prompt with notebook pages and task".
PB-NOTEBOOK-43 /notebook with no argument opens a UI page selector T08 ✅ asserted T08 "/notebook empty overlay renders empty state and closes on input", "/notebook selection previews the chosen entry", "/notebook overlay sorts entries consistently"; headless no-op covered by "/notebook exits cleanly when headless".
PB-NOTEBOOK-44 Overlay selection shows at most first 500 chars + ... when clipped T08 ◐ partly asserted T08 "/notebook selection previews the chosen entry" asserts inline body view for a short body; the 500-char clip / ... behavior is not asserted.
PB-NOTEBOOK-45 Status bar 📒 N; dim 📒 0 when empty T44, T08 ◐ partly asserted Non-empty asserted: T44 "updateIndicators shows notebook page count in status" (count 2), T08 "notebook_write pushes onUpdate and refreshes UI indicators" (📒 1); the dim 📒 0 empty state is not asserted.
PB-NOTEBOOK-46 Write descriptions state shared size semantics and derived caps T08 ✅ asserted "notebook_write descriptions state the shared write-size semantics" (notebook.test.ts:1383-1393) checks tool and parameter suffixes; expected cap text derives from host constants (:51-54).
PB-NOTEBOOK-47 Optional v1 flag persists/reconstructs, clears on complete overwrite, and follows discard survivors T08, T37 ✅ asserted T08 "clipped flag survives fresh reconstruction without persisted quantities", "complete overwrite clears a durable clipped flag", "legacy page entries without clipped read as false", "discard survivor retains its durable clipped flag" (notebook.test.ts:1264-1343). T37 "clipped page flags stay contained and reset clears them" (state-invariants.test.ts:402-411) and "Property 7: clipped pages are a subset of notebook pages" (:448) protect state.clippedPages ⊆ state.notebookPages.
PB-NOTEBOOK-48 Read notice/details conditional on flag; description explains notice T08 ✅ asserted "read appends a generic notice only for a flagged page" (notebook.test.ts:1131-1148) checks exact notice once and true/false details; "notebook tool definitions include prompt hints when withPromptHints is true" (:731-764) asserts the read-description notice wording.
PB-NOTEBOOK-49 Human-only selector badge; plain/model listings undecorated; stored body unaffected T08 ✅ asserted "formatPageTuiPreview appends a badge only when clipped", "/notebook selector badges clipped pages without changing stored bodies" (notebook.test.ts:1345-1381), "model listing surfaces remain free of clipping decorations" (:1483-1518). No custom tool-renderer badge claim.

Empty surfaces in this area

  • PB-NOTEBOOK-19 — no page-count cap / accumulated-size warning. Would seal it: writing past any conceivable cap and asserting all pages persist and no cap/size warning is emitted.

Area coverage summary

Claims Junction rows ✅ ◐ ⚠️
49 52 40 11 1

Claim-level: 37 ✅ / 11 ◐ / 1 ⚠️. Claims -07/-11/-14/-15/-16/-17/-18 and -46…-49 are ✅, including the -14 ordering aspect; -19 is ⚠️. Status means represented by tests, not a fresh test run.

Clone this wiki locally