Skip to content

Spec2Contract Notebook

Grzegorz Nowak edited this page Sep 30, 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…-45, 45 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/T47 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.

Junction rows

Claim ID Assertion (terse) Fixture(s) Status Notes
PB-NOTEBOOK-01 Notebook = name→markdown-body page map T08, T47 ✅ asserted T08 "notebook tools add/get/list return stable contract details" (write entry-a, read back body); T47 "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, T47 ✅ asserted T08 "saveNotebookPage serializes concurrent writes and preserves completion order" (entry-a → "second"), "session_tree…" (a-v2); T47 "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 reports Saved notebook page "<name>". + current page list T47, T08 ✅ asserted Phrase asserted by T47 "notebook write/read round-trip" (OK:Saved notebook page); page-list formatting asserted via T08 read/index result texts.
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 full body between --- <name> --- delimiters T08, T47 ✅ asserted T08 "notebook tools add/get/list…" (--- entry-a ---, body); T47 "notebook write/read round-trip" (OK:--- my-page ---).
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 T08 "notebook tools add/get/list…" (entry-a: first line), "notebook tools show empty-state placeholders" (Notebook Pages:\n(empty)).
PB-NOTEBOOK-14 notebook_index order is alphabetical T08 ◐ partly asserted aspect: ordering. Observed index orders are insertion order; alphabetical sort is asserted only for the /notebook overlay ("/notebook overlay sorts entries consistently"), not for notebook_index/getPageNames.
PB-NOTEBOOK-15 Preview = first line, capped 80 chars → 77 + ... — ⚠️ no test yet No test uses a first line >80 chars; would need to assert formatPagePreview clips to 77 + "..." and leaves ≤80 unchanged.
PB-NOTEBOOK-16 Write head-truncates at first of 2,000 lines / 50 KiB, keeps beginning T08 ◐ partly asserted T08 "saveNotebookPage truncates oversized content before persisting" asserts size shrink + /^first line/m; exact 2,000-line and 50 KiB thresholds are not asserted.
PB-NOTEBOOK-17 Truncation is silent (result carries no clip notice) — ⚠️ no test yet Would need an oversized-page write and an assertion that the success result text contains no truncation/clip marker.
PB-NOTEBOOK-18 First line >50 KiB ⇒ empty persisted body, still reports success — ⚠️ no test yet Would need a no-newline >50 KiB content write; assert persisted body "" and a Saved notebook page success result.
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, T47 ✅ asserted T09 "notebook_topic_set establishes a fresh topic…" (details.topic="oauth", source agent); T47 "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, T47 ✅ asserted T09 "…preserves human authority…" (/human-set notebook topic is authoritative/i); T47 "notebook topic lifecycle: set via command, agent-set blocked" (authoritative).
PB-NOTEBOOK-27 /notebook <topic> sets a human-sourced topic T08, T47 ✅ asserted T08 "/notebook notifies…" sets via command; T47 "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.

Empty surfaces in this area

  • PB-NOTEBOOK-15 — page preview 80-char cap. Would seal it: a test calling formatPagePreview with a >80-char first line and asserting first 77 chars + "...", plus a ≤80-char line returned unchanged.
  • PB-NOTEBOOK-17 — silent truncation in the write result. Would seal it: an oversized-content write asserting the returned/success text contains no truncation/clip marker.
  • PB-NOTEBOOK-18 — >50 KiB single first line ⇒ empty stored body, still success. Would seal it: a newline-free >50 KiB write asserting the persisted body is "" and the result still reports success.
  • 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 ✅ ◐ ⚠️
45 48 31 13 4

Clone this wiki locally