Repository navigation
Spec2Contract Notebook
Grzegorz Nowak edited this page Sep 30, 2026
·
5 revisions
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.
| 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 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) | — | 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 | — | 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 | — | 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. |
-
PB-NOTEBOOK-15 — page preview 80-char cap. Would seal it: a test calling
formatPagePreviewwith a >80-char first line and assertingfirst 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.
| Claims | Junction rows | ✅ | ◐ | |
|---|---|---|---|---|
| 45 | 48 | 31 | 13 | 4 |