Repository navigation
Spec2Contract
This is the canonical junction between two spaces — not a second product specification.
Left space: the published Product Book claims, referenced by stable claim ID
PB-<AREA>-<nn>. Right space: the contracts registry directly below, referenced by fixture
id (T01…T50). Each junction row associates one claim ID (optionally through an aspect) with
fixture id(s) and carries the status payload and notes. The junction lives in one index page (this
one) plus nine per-area pages, one per book chapter.
Ownership. This document and its area pages own planned pairs and coverage status; the book carries only stable claim IDs and contains no status markers. A materialized test is the evidence for its pair; this junction is the sole coverage record.
Materialization rule. Every fixture in the registry is a test that already exists in the
repository at pi-schematic @ 36bd569. This junction records which existing test represents
which book claim; it does not add, plan, modify or remove tests. No implementation or new
coverage is claimed here.
Allocation ledger. Ledger head = T50 (tests/unit/time-format.test.ts, the date anchor).
Fixture IDs are allocated sequentially in registry reading order, are never renumbered or reused,
and a future fixture takes the next sequential number. Tombstones: none.
Status legend. ✅ asserted · ◐ partly asserted · ⚠️ no test yet. Asserted means
represented by an existing test, not passing. Every ◐ names its missing portion. Fixture
ambition never upgrades a status.
Claim and aspect notation. A junction row's key is claim_id, optionally refined by an aspect
named in its Notes. A claim with several distinct contract surfaces gets several junction rows;
claim status is derived from all of its rows (any ⚠️ row ⇒ ⚠️; else any ◐ row ⇒ ◐; else
✅). Adding an aspect never invents a product promise; uncovered surfaces are marked, never
silently dropped.
Evidence baselines. The book and its contracts are at pi-schematic @ 36bd569
(main, 2026-10-12, v0.6.0). The wiki records its at-checksum with a single
<!-- wiki-provenance: code=<sha> --> marker on the Home page.
Notebook claims -46…-49 use T08/T37; the fixture ledger head is T50. This is the pi-schematic
analogue of the reference junction grzegorznowak/pi-cure-light-census#3.
| Area page | Book chapter | Left-space prefix | Claims |
|---|---|---|---|
| Spec2Contract-Spawn | Product-Book-Spawn | PB-SPAWN-nn |
45 |
| Spec2Contract-Notebook | Product-Book-Notebook | PB-NOTEBOOK-nn |
49 |
| Spec2Contract-Handoff | Product-Book-Handoff | PB-HANDOFF-nn |
46 |
| Spec2Contract-Model-Groups | Product-Book-Model-Groups | PB-GROUPS-nn |
47 |
| Spec2Contract-Readonly | Product-Book-Readonly | PB-READONLY-nn |
45 |
| Spec2Contract-Workflows | Product-Book-Workflows | PB-WORKFLOW-nn |
39 |
| Spec2Contract-TUI | Product-Book-TUI | PB-TUI-nn |
45 |
| Spec2Contract-Watchdog | Product-Book-Watchdog | PB-WATCHDOG-nn |
45 |
| Spec2Contract-Lifecycle | Product-Book-Lifecycle | PB-LIFE-nn |
48 |
Canonical per-fixture registry for this junction. Every fixture id cited on any area page resolves
to a row here. State values as in the reference: materialized (test on disk) · planned ·
approved-unimplemented · registered-new · absorbed. All 50 rows are materialized.
| ID | One-line intent | Owning book area | Materialization target | State |
|---|---|---|---|---|
| T01 | spawn tool execute/render/child-tool inheritance, requirements envelope, abort/reset races | Spawn | tests/unit/spawn.test.ts |
materialized |
| T02 | nested-spawn dispose/reattach, child-session dedup, epoch/reset event drops | Spawn | tests/unit/spawn-lifecycle.test.ts |
materialized |
| T03 | collapsed/expanded nested-spawn rendering, truncation, identity, render cache | Spawn/TUI | tests/unit/spawn-render.test.ts |
materialized |
| T04 | frame scheduler and nested-spawn event handling/recovery | Spawn | tests/unit/spawn-event.test.ts |
materialized |
| T05 | spawn works after handoff-first module initialization | Spawn/Lifecycle | tests/unit/spawn-after-handoff.test.ts |
materialized |
| T06 | real child session end-to-end (thinking, abort, reset, stats, notebooks) | Spawn | tests/unit/spawn-runtime-compatibility.test.ts |
materialized |
| T07 | abortChildSession promise identity/dedup/throw handling | Spawn | tests/unit/abort-child-session.test.ts |
materialized |
| T08 | notebook rehydration, tools, overlay, write lock, discard/epoch, write-size report/rejection/flag/notice | Notebook | tests/unit/notebook.test.ts |
materialized |
| T09 | notebook topic lifecycle and human-authority rules | Notebook | tests/unit/topic.test.ts |
materialized |
| T10 | CONTEXT_PRIMER and before_agent_start notebook/topic/date-anchor guidance | Notebook/Lifecycle | tests/unit/system-prompt.test.ts |
materialized |
| T11 | /handoff command, cut/deliver verbatim, discard, retry, eligibility, frame | Handoff | tests/unit/handoff.test.ts |
materialized |
| T12 | handoff eligibility thresholds and percent/token estimates | Handoff | tests/unit/handoff-eligibility.test.ts |
materialized |
| T13 | lost-successor recovery on settle/session-start/tree | Handoff | tests/unit/handoff-recovery.test.ts |
materialized |
| T14 | handoff module import graph / initialization order | Handoff | tests/unit/handoff-import-graph.test.ts |
materialized |
| T15 | route resolution, capability/modality selection, ceilings, fallbacks | Model-Groups | tests/unit/model-groups-router.test.ts |
materialized |
| T16 | store CRUD, validation, migrations, scopes, persistence failure | Model-Groups | tests/unit/model-groups-crud.test.ts |
materialized |
| T17 | constraint descriptor registry/engine/codecs, generic editors | Model-Groups | tests/unit/model-groups-constraints.test.ts |
materialized |
| T18 | modality derivation and compatibility facade | Model-Groups | tests/unit/model-groups-modalities.test.ts |
materialized |
| T19 | MODALITY letter/color lexicon and letterRun canonicalization | Model-Groups | tests/unit/model-groups-modality.test.ts |
materialized |
| T20 | display codec escape/unescape round-trip | Model-Groups | tests/unit/model-groups-display.test.ts |
materialized |
| T21 | #group autocomplete provider | Model-Groups | tests/unit/model-groups-autocomplete.test.ts |
materialized |
| T22 | session_start/before_agent_start wiring, load-issue notifications, trust flow | Model-Groups | tests/unit/model-groups-integration.test.ts |
materialized |
| T23 | full Model Groups TUI (list, wizard, editor, modality, picker) | Model-Groups/TUI | tests/unit/model-groups-tui.test.ts |
materialized |
| T24 | saved-workflow model/model-group/thinking frontmatter application | Workflows/Model-Groups | tests/unit/model-group-frontmatter.test.ts |
materialized |
| T25 | /readonly toggle, nudges, headless no-op, idle-only | Readonly | tests/unit/readonly-mode.test.ts |
materialized |
| T26 | deferred readonly frontmatter from prompts/skills, queue, bypasses | Readonly/Workflows | tests/unit/readonly-frontmatter.test.ts |
materialized |
| T27 | bash mutation classifier (writes, wrappers, substitutions) | Readonly | tests/unit/readonly-bash-classifier.test.ts |
materialized |
| T28 | readonly tool filtering and child authority/guards | Readonly/Spawn | tests/unit/readonly-spawn.test.ts |
materialized |
| T29 | readonly state restored from branch/CLI flag | Readonly | tests/unit/readonly-rehydration.test.ts |
materialized |
| T30 | /handoff readonly bypass, topic-boundary promotion, resume | Readonly/Handoff | tests/unit/readonly-handoff.test.ts |
materialized |
| T31 | OS sandbox profile/quoting/temp-write behaviour | Readonly | tests/unit/os-sandbox.test.ts |
materialized |
| T32 | prompt/skill frontmatter cache, precedence, trust, issue reporting, fields | Workflows | tests/unit/frontmatter-cache.test.ts |
materialized |
| T33 | pinned Pi metadata, CI matrix, audit-ci config invariants | Lifecycle | tests/unit/config-invariants.test.ts |
materialized |
| T34 | Phase-2 latest-Pi compatibility lane assertions | Lifecycle | tests/unit/dependency-graph-assertions.test.ts |
materialized |
| T35 | handoff-before-spawn module evaluation order | Lifecycle | tests/unit/module-evaluation-order.test.ts |
materialized |
| T36 | runtime singleton swap/restore, write-lock serialization | Lifecycle | tests/unit/runtime-singletons.test.ts |
materialized |
| T37 | state invariants (topic, child epoch, reset, properties, clipped-page containment) | Lifecycle/Notebook | tests/unit/state-invariants.test.ts |
materialized |
| T38 | register-loader path resolution and error surfacing | Lifecycle | tests/unit/register-loader.test.ts |
materialized |
| T39 | resolveRealPath symlink/temp behaviour | Lifecycle | tests/unit/resolve-path.test.ts |
materialized |
| T40 | pi.image / README brand asset consistency | Lifecycle | tests/unit/brand-assets.test.ts |
materialized |
| T41 | compatibility artifact writer | Lifecycle | tests/unit/compat-fixture.test.ts |
materialized |
| T42 | compatibility npm-runner/process helpers | Lifecycle | tests/unit/compat-process.test.ts |
materialized |
| T43 | notification copy constants/builders | Readonly/Model-Groups | tests/unit/notifications.test.ts |
materialized |
| T44 | context indicator tones, notebook/readonly/topic status, warning widget | TUI | tests/unit/tui-indicators.test.ts |
materialized |
| T45 | snapshot goldens for spawn/nested/context-indicator rendering | TUI/Spawn | tests/unit/render-snapshots.test.ts |
materialized |
| T46 | context watchdog bands, nudges, handoff cancellation, readonly nudges | Watchdog | tests/unit/watchdog.test.ts |
materialized |
| T47 | line-host end-to-end: headless mode, unavailable context usage, stale compaction after tree navigation, spawn without model infrastructure, line-protocol errors | Lifecycle/all | tests/e2e/basic.test.ts |
materialized |
| T48 | compile-time type contract (tsc --noEmit; not a runtime test) | Lifecycle | tests/typecheck/ |
materialized |
| T49 | real pi CLI over RPC: notebook, topic, handoff, recovery, session-tree, readonly | Lifecycle/all | tests/e2e/real-host.test.ts |
materialized |
| T50 | date-anchor formatting, zone fallback, day/DST stability, prompt block | Lifecycle | tests/unit/time-format.test.ts |
materialized |
Snapshots used by T45: tests/snapshots/{spawn-call-collapsed,spawn-call-long,spawn-result-success,spawn-result-error,spawn-result-aborted,nested-collapsed-running,nested-collapsed-success,nested-expanded,indicator-30,indicator-50,indicator-70}.txt. |
||||
Helpers, not fixtures: tests/unit/helpers.ts, tests/unit/test-host.ts, tests/test-utils.ts, tests/e2e/pty-harness.ts, tests/e2e/test-host.ts, tests/e2e/real-host.ts, tests/e2e/real-host-probe.ts, tests/e2e/real-host-protocol.ts, tests/unit/model-groups-helpers.ts, tests/unit/*fixture.ts. |
Counts are junction rows unless marked claim-level. Repeated fixture references across areas are intentional joins.
| Area | Book chapter | Claims | Junction rows | ✅ rows | ◐ rows | Claim-level ✅ / ◐ / |
|
|---|---|---|---|---|---|---|---|
| Spawn | Product-Book-Spawn | 45 | 49 | 41 | 7 | 1 | 37 / 7 / 1 |
| Notebook | Product-Book-Notebook | 49 | 52 | 40 | 11 | 1 | 37 / 11 / 1 |
| Handoff | Product-Book-Handoff | 46 | 49 | 42 | 4 | 3 | 39 / 4 / 3 |
| Model-Groups | Product-Book-Model-Groups | 47 | 50 | 45 | 4 | 1 | 42 / 4 / 1 |
| Readonly | Product-Book-Readonly | 45 | 49 | 43 | 2 | 4 | 39 / 2 / 4 |
| Workflows | Product-Book-Workflows | 39 | 42 | 33 | 2 | 7 | 30 / 2 / 7 |
| TUI | Product-Book-TUI | 45 | 46 | 29 | 13 | 4 | 28 / 13 / 4 |
| Watchdog | Product-Book-Watchdog | 45 | 46 | 23 | 17 | 6 | 22 / 17 / 6 |
| Lifecycle | Product-Book-Lifecycle | 48 | 73 | 62 | 2 | 9 | 37 / 2 / 9 |
| Total | — | 409 | 456 | 358 | 62 | 36 | 311 / 62 / 36 |
Derived claim-level total: 409 claims = 311 ✅ / 62 ◐ / 36 ⚠️ count is inflated by |
|||||||
| the derive rule (any unrepresented aspect marks the whole claim); most such claims also have | |||||||
✅ aspects. Per-row totals are 456 rows = 358 ✅ / 62 ◐ / 36 |
These fixtures are materialized and seal real engineering contracts, but no PB-* row maps onto
them (the book does not claim them). They are registered here for completeness, not dropped.
| Fixture | Target | What it seals | Why no claim |
|---|---|---|---|
| T14 | tests/unit/handoff-import-graph.test.ts |
handoff module-initialization order (handoff modules must not top-level import notebook/store) |
internal import-graph constraint; not a product behaviour row |
| T35 | tests/unit/module-evaluation-order.test.ts |
handoff-before-spawn evaluation order in a fresh extension process | internal initialization order |
| T36 | tests/unit/runtime-singletons.test.ts |
singleton swap/restore and write-lock serialization | internal infrastructure |
| T38 | tests/unit/register-loader.test.ts |
register-loader path resolution and error surfacing | build/test tooling |
| T39 | tests/unit/resolve-path.test.ts |
resolveRealPath symlink/temp behaviour |
internal helper |
| T41 | tests/unit/compat-fixture.test.ts |
compatibility artifact writer | release-engineering tooling |
| T42 | tests/unit/compat-process.test.ts |
compatibility npm-runner/process helpers | release-engineering tooling |
Book limits and non-promises that are not testable product promises and therefore are not junction rows.
| Book policy | Junction assertion (terse) | Policy statement (product prose) | Notes |
|---|---|---|---|
| Readonly guardrail | In-process guardrail, never presented as a security boundary | Readonly is a coding guardrail, not a hardened security boundary. Write/edit are blocked everywhere; shell commands are classified and additionally OS-sandboxed on macOS/Linux when the sandbox binary is present. | Windows is classifier-only; interpreters and piped indirection can bypass classification. Classifier/sandbox mechanics are junction rows (T27/T31); the security non-claim is policy. |
| Child isolation scope | Children share the parent's working directory and authority | Spawn is context isolation, not filesystem or privilege isolation: no worktree isolation and no per-child tool policy beyond readonly inheritance. | The child-tool-name exclusion of spawn/handoff is a junction row; the isolation limit is policy. |
| Model Group selection | Selection is uniform with replacement; no routing heuristics | A group selects uniformly with replacement from its authenticated, usable members; repeated calls may pick the same model. No weighting, no-repeat, health routing, retry/failover or optimizer. | Uniformity/no-repeat is only partly tested (◐ PB-GROUPS-39); the absence of heuristics is policy. |
| Provider cache | The extension creates cache-aware boundaries but configures no provider cache lifetime | Handoff and spawn create separate input prefixes; a model/provider switch starts a different cache. The extension does not configure provider cache lifetimes. | Cache-separation boundaries are junction rows; cache-lifetime non-configuration is policy. |
| Notebook lifetime | Notebook is task-scoped memory, not permanent memory | The notebook is branch- and work-stream-scoped, survives handoff, and clears with /new. It is memory for this task, not forever memory. |
The clearing/branch behaviour is a junction row; the "not forever" framing is policy. |
| Windows shell guarding | Classifier-only on Windows | Windows has no syscall-level sandbox; enforcement is classifier-only. | Selection of classifier-only mode on Windows is ⚠️ (PB-READONLY-28); the platform limit is policy. |
-
Fixture granularity = one test file. A fixture is one
tests/unit/*.test.tsortests/e2e/*.test.tsfile. Named test cases (fromdescribe/test/ittitles) are cited in the Notes column so each pair is verifiable. Snapshot.txtfiles are data of T45, not separate fixtures. Helper/fixture modules are not fixtures. -
tests/typecheck/is registered as T48 — a compile-only contract exercised bynpm run typecheck, not a runtime test. It is cited where a claim is genuinely compile-time. -
Aspect rows. A claim whose row describes several surfaces is split into aspect rows sharing
the claim ID; the aspect is named in Notes. This mirrors the reference and keeps
◐honest. -
Cross-area citations are allowed. A fixture may be cited by more than one area page when it
genuinely seals claims in both (e.g.
state-invariantsT37 serves Notebook, Handoff, Spawn and Lifecycle). -
Conservative statuses. A test title alone does not establish coverage: the body must assert
the exact claim. Partial assertions are
◐; unrepresented claims are⚠️. "Asserted" never means "passing".
The book's Honest caveats section is deliberately reflected rather than smoothed over:
| Book caveat | Junction rows |
|---|---|
| Notebook clipping reported/rejected; index remains undecorated, no aggregate cap |
PB-NOTEBOOK-14/-15/-16/-17/-18/-46…-49 are ✅ for the documented semantics, including undecorated index/plain previews. PB-NOTEBOOK-19 is |
| 70% advice differs from documentation |
PB-WATCHDOG-09 (and -07, -08 tier-intent rows) — ⚠️ no test yet
|
Modality-name drift (code text|image|reasoning vs README text|image) |
Model-Groups and Spawn schema claims are asserted for the code set; the README drift itself is not a claim |
| Handoff recovery is quiet | asserted as-is (no timeout/counter is claimed) |
console.warn diagnostics exception |
internal path; no book claim (not a junction row) |