Skip to content

Spec2Contract

Grzegorz Nowak edited this page Oct 12, 2026 · 9 revisions

spec-to-contracts — product-book ↔ contracts junction (pi-schematic, v1)

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.

Page tree

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

Contracts registry (right-side table)

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.

Coverage rollup (derived; not junction rows)

Counts are junction rows unless marked claim-level. Repeated fixture references across areas are intentional joins.

Area Book chapter Claims Junction rows ✅ 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 ⚠️. The ⚠️ 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 ⚠️.

Registered fixtures with no book-claim destination

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

Policy list (outside the pair relation; no claim IDs, no fixtures, no status)

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.

Method and design choices for this junction

  • Fixture granularity = one test file. A fixture is one tests/unit/*.test.ts or tests/e2e/*.test.ts file. Named test cases (from describe/test/it titles) are cited in the Notes column so each pair is verifiable. Snapshot .txt files are data of T45, not separate fixtures. Helper/fixture modules are not fixtures.
  • tests/typecheck/ is registered as T48 — a compile-only contract exercised by npm 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-invariants T37 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".

Book caveats and their junction status

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 ⚠️. See Notebook for named tests.
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)

Clone this wiki locally