Repository navigation
Spec2Contract Notebook
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.
| 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 | — | 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. |
- 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 | ✅ | ◐ | |
|---|---|---|---|---|
| 49 | 52 | 40 | 11 | 1 |
Claim-level: 37 ✅ / 11 ◐ / 1