Skip to content

Spec2Contract Lifecycle

Grzegorz Nowak edited this page Oct 10, 2026 · 4 revisions

Spec-to-contracts — Lifecycle (book ↔ in-tests contracts)

The Lifecycle area covers packaged-metadata/install claims (PB-LIFE-01..09) and the extension's registration + event-hook wiring (PB-LIFE-10..48); the left space is PB-LIFE-nn, 48 rows. Its contracts are carried mainly by the config/metadata invariants (T33, T34, T40), the state/rehydration fixtures (T37, T08, T29), and the end-to-end registration/hook fixtures (T47/T49, plus T10, T11, T13, T22, T25, T26, T30, T44, T46, T50 for individual hooks). The lifecycle-area fixtures T35, T36, T38, T39, T41, T42 and T48 exercise loader/order/singleton/compat-infra and compile-time surfaces but do not by themselves seal any PB-LIFE-nn row; T41/T42 cover the compatibility-lane scripts exercised by T33/T34.

Junction rows

Claim ID Assertion (terse) Fixture(s) Status Notes
PB-LIFE-01 Install with pi install npm:pi-schematic — ⚠️ no test yet README-only instruction; no fixture reads it.
PB-LIFE-02 Supported Pi runtime is 0.99.2+ T33, T34 ✅ asserted T33 config-invariants.test.ts — "pinned Pi compatibility metadata and source boundaries stay exact" pins the Pi peer floor >=0.99.2 and devDependency 0.99.2; T34 dependency-graph-assertions.test.ts — "latest compatibility lane guards every installed Pi package" keeps the latest-Pi lane tracking all installed Pi packages. README's prose claim is not read directly.
PB-LIFE-03 Supported Node.js runtime is 22.19.0+ T33 ✅ asserted T33 "pinned Pi compatibility metadata and source boundaries stay exact" asserts engines.node === ">=22.19.0"; "workflow keeps the expected matrix and audit/test order" derives the ubuntu-latest@22.19.0 matrix entry from the same floor.
PB-LIFE-04 Published package version is 0.6.0 — ⚠️ no test yet T33/T40 parse package.json but never read .version. A metadata invariant asserting package.json.version (and parity with the CHANGELOG head) would seal it.
PB-LIFE-05 Peers pi-ai/pi-coding-agent/pi-tui at >=0.99.2 T33 ✅ asserted T33 "pinned Pi compatibility metadata and source boundaries stay exact" asserts each of the three peer entries equals >=0.99.2 and the pinned devDependency equals 0.99.2.
PB-LIFE-06 Peer typebox at >=1.3.27 T33 ✅ asserted T33 "pinned Pi compatibility metadata and source boundaries stay exact" asserts peerDependencies.typebox === ">=1.3.27" and lock/dev pin 1.3.27.
PB-LIFE-07 Declares ./index.ts as Pi extension entry point — ⚠️ no test yet No fixture reads package.json pi.extensions. T47 loads the host but not via that declaration. Asserting pi.extensions equals ["./index.ts"] (mirroring T40's pi.image read) would seal it.
PB-LIFE-08 Gallery image is assets/logo-animated.gif T40 ◐ partly asserted T40 brand-assets.test.ts ("pi.image resolves to an existing brand asset", "the gallery image is a 360x360 GIF89a", "README hero references the same asset as pi.image") resolves pi.image to an existing assets/* GIF89a and checks README parity — the exact filename logo-animated.gif is not pinned. Missing portion: exact image filename.
PB-LIFE-09 Documented settings.json with {"compaction":{"enabled":false}} — ⚠️ no test yet README-only recommendation; no fixture reads it. A docs invariant matching the settings JSON block would seal it.
PB-LIFE-10 Registers notebook_write/notebook_read/notebook_index T49 ✅ asserted T49 real-host.test.ts — "host starts and extension registers" snapshots all three tool names after loading the extension; T08 notebook.test.ts — "notebook tools add/get/list return stable contract details" exercises the same definitions.
PB-LIFE-11 Registers notebook_topic_set T49, T09 ✅ asserted T49 "host starts and extension registers" snapshots notebook_topic_set; T09 topic.test.ts — "notebook_topic_set establishes a fresh topic, is idempotent, and refuses overrides".
PB-LIFE-12 Registers handoff tool T49 ✅ asserted T49 "host starts and extension registers" snapshots handoff.
PB-LIFE-13 Registers spawn tool T49 ✅ asserted T49 "host starts and extension registers" snapshots spawn; T01 spawn.test.ts — "registerSpawnTool registers a tool with correct name and metadata".
PB-LIFE-14 Registers /handoff and /notebook commands T49 ✅ asserted T49 "commands are registered" asserts both notebook and handoff appear in the command list.
PB-LIFE-14 Registers /model-groups command T22 ✅ asserted T22 model-groups-integration.test.ts — "/model-groups command registers and opens ctx.ui.custom with live registry/cwd".
PB-LIFE-14 Registers /readonly command T25 ✅ asserted T25 readonly-mode.test.ts — "readonly toggle on blocks write, edit, handoff, and bash mutations" drives pi.commands.get("readonly").
PB-LIFE-14 /new is not an extension command — ⚠️ no test yet No fixture asserts the extension does not call registerCommand("new"). An e2e cmds assertion that the extension command list excludes new would seal it.
PB-LIFE-15 TUI context-pressure indicator w/ tones + malformed/overflow T44, T45 ✅ asserted T44 tui-indicators.test.ts covers accent/warning/error tones, --% for null/malformed, overflow preservation, and the ≥70% warning widget; T45 render-snapshots.test.ts — "context indicator at 30% matches snapshot", "…at 50% matches snapshot", "…at 70% matches snapshot".
PB-LIFE-15 TUI notebook-count, topic, readonly indicators T44 ✅ asserted T44 "updateIndicators shows notebook page count in status", "shows active notebook topic when set", "shows readonly indicator when enabled", "hides readonly indicator when disabled".
PB-LIFE-15 Empty/unset indicator placeholders (📒 0, 🧭 -) — ⚠️ no test yet T44 only exercises a populated notebook and a set topic. A T44 case asserting STATUS_KEY_NOTEBOOK === "📒 0" on empty pages and the dim 🧭 - placeholder on a null topic would seal it.
PB-LIFE-16 session_start gains #group autocomplete on supported UI T22, T21 ✅ asserted T22 "session_start registers Model Groups autocomplete provider when UI supports it"; T21 model-groups-autocomplete.test.ts covers the provider itself.
PB-LIFE-17 before_agent_start applies deferred readonly frontmatter T26 ✅ asserted T26 readonly-frontmatter.test.ts drives input → before_agent_start and asserts the deferred readonly entry/toggle ("deferred readonly enable emits a one-shot context nudge", "one readonly entry is appended per consumed queued toggle").
PB-LIFE-17 before_agent_start adds CONTEXT_PRIMER + active topic + names-only page index T10 ✅ asserted T10 system-prompt.test.ts — "CONTEXT_PRIMER states the notebook, topic, and handoff contracts", "before_agent_start injects notebook contracts plus live topic and page data", "before_agent_start injects no-topic guidance when the topic is unset".
PB-LIFE-17 before_agent_start adds available group names T22 ✅ asserted T22 "before_agent_start injects fresh names-and-effective-modalities guidance", "before_agent_start clears stale Model Groups guidance when registry becomes unavailable".
PB-LIFE-18 context supplies one-shot readonly posture reminders T25, T26, T46 ✅ asserted T25 "readonly toggle delivers an activation nudge via context hook" / "...deactivation nudge..."; T26 "deferred readonly enable/disable emits a one-shot context nudge"; T46 watchdog.test.ts — "context injects a readonly-mode nudge after toggle".
PB-LIFE-18 context supplies band-throttled context-pressure guidance T46 ✅ asserted T46 "context nudges at band crossings and after a below-30% reset", "context consumes a boundary hint after the first injected nudge", "context injects a boundary nudge below 30% after an explicit topic change".
PB-LIFE-19 input pre-checks interactive prompt/skill model selection; blocked selection does not run T24, T26, T32 ✅ asserted T24 model-group-frontmatter.test.ts — "unknown model-group in frontmatter blocks execution with error", "model-group commands are applied during their input preflight"; T26 "streaming readonly frontmatter is blocked without a delayed toggle"; T32 frontmatter-cache.test.ts covers cache/selection inputs.
PB-LIFE-20 tool_call blocks write/edit while readonly T25, T49 ✅ asserted T25 "readonly toggle on blocks write, edit, handoff, and bash mutations"; T49 "readonly lifecycle: handoff bypass clears after compaction while readonly persists" asserts write stays blocked.
PB-LIFE-20 tool_call guards bash while readonly T27, T47 ✅ asserted T27 readonly-bash-classifier.test.ts covers writes/redirects/substitutions/chains and temp allowances; T47 headless test shows the guard wiring.
PB-LIFE-20 tool_call blocks ordinary handoff without the requested bypass T30, T25, T49 ✅ asserted T30 readonly-handoff.test.ts — "/handoff command creates temporary bypass for handoff tool only", "blocked readonly handoff never invokes compaction"; T25 and T49 assert the direct-call block.
PB-LIFE-21 session_start resets extension state on /new T37, T11 ✅ asserted T37 state-invariants.test.ts — "Property 4: Reset clears all state fields", "reset clears deferred readonly frontmatter commands"; T11 handoff.test.ts — "session_start new clears stale handoff status and warning widget" invokes the real session_start with reason:"new".
PB-LIFE-21 session_start rebuilds notebook pages from the active branch T08 ✅ asserted T08 notebook.test.ts — "session_start rehydrates the latest persisted notebook state through the full hook chain", "rehydration uses only the active session branch".
PB-LIFE-21 session_start restores readonly T30 ✅ asserted T30 readonly-handoff.test.ts — "session resume restores readonly enforcement from persisted state" drives the real session_start handlers.
PB-LIFE-21 session_start checks Model Groups configuration T22 ✅ asserted T22 "index session_start stores model group validation and notifies load and validation issues" and the sibling boot-notification cases.
PB-LIFE-21 session_start attempts missing-successor recovery T13 ✅ asserted T13 handoff-recovery.test.ts — "session start recovers on reasons other than load when the queue is empty", "a session start re-opens the delivery scope after an in-process session load".
PB-LIFE-22 session_tree switches notebook state to the selected branch T08 ✅ asserted T08 "session_tree rehydrates notebook state branch-scoped: pages and epoch follow the branch, writes use B state".
PB-LIFE-22 session_tree switches readonly state to the branch T30 ✅ asserted T30 "session tree re-announces readonly even when the rehydrated value is unchanged".
PB-LIFE-22 session_tree abandons branch-local handoff work T11, T37 ✅ asserted T11 "stale handoff compaction is ignored after session-tree navigation"; T37 "invalidateHandoffState clears branch-local compaction reservations".
PB-LIFE-22 session_tree checks for an undelivered successor T13 ✅ asserted T13 "repeated tree triggers coalesce and a settled run retries only while absent", "tree navigation and resume queue a missing successor in a fresh process", "a cut shared across tree branches coalesces instead of double-sending".
PB-LIFE-23 turn_end refreshes TUI indicators after each turn T11 ✅ asserted T11 "turn_end fallback keeps requested handoff status sticky until real handoff happens" invokes the real turn_end handler and observes a status set through updateIndicators; the other indicator fields are separately covered by T44.
PB-LIFE-24 agent_end records valid context usage T46 ✅ asserted T46 "watchdog records context usage without user notifications", "watchdog ignores malformed percentages", "watchdog records overflow percentages".
PB-LIFE-24 agent_end cancels an ignored eligible requested handoff after the retry limit + notifies T46 ✅ asserted T46 "watchdog auto-cancels a required handoff after enough unanswered turns", "watchdog stays advisory for a fresh user-requested handoff", "watchdog does not cancel an in-flight handoff".
PB-LIFE-25 agent_settled rechecks a still-absent successor T13, T49 ✅ asserted T13 "repeated tree triggers coalesce and a settled run retries only while absent", "a later settled run recovers an absent successor only after its queue drains"; T49 "recovery resends a lost successor and stops once it lands".
PB-LIFE-26 session_before_compact installs a fixed continuation frame and stores the successor payload T11 ✅ asserted T11 "handoff compaction keeps the frame constant and the state contract intact", "the continuation frame is pinned byte-for-byte", "handoff compaction summaries identify each cut without changing the frame", "buildNextUserMessage carries the instruction verbatim and the context second".
PB-LIFE-27 Notebook/readonly/handoff state held together for one session T37 ✅ asserted T37 state-invariants.test.ts drives one SchematicState across topic, page, child-session, handoff, readonly and frontmatter operations and asserts the invariants ("Property 1..6", "Property 4: Reset clears all state fields").
PB-LIFE-28 Notebook writes append session custom entries, not an external file T08 ✅ asserted T08 "notebook tools add/get/list return stable contract details" asserts the appended notebook-entry custom entry; "session_start rehydrates..." round-trips it from pi.appendedEntries.
PB-LIFE-29 /new clears pages, topic, readonly and pending handoff T37, T11 ✅ asserted T37 "Property 4: Reset clears all state fields" plus "reset increments handoffGeneration and clears compaction reservations"; T11 "session_start new clears stale handoff status and warning widget" runs the real reset path; T08 "resetState clears the discard watermark for a fresh session".
PB-LIFE-30 Resume//tree rebuild pages from the active branch; branches differ T08 ✅ asserted T08 "session_start rehydrates the latest persisted notebook state through the full hook chain", "rehydration uses only the active session branch", "session_tree rehydrates notebook state branch-scoped...".
PB-LIFE-31 Readonly persists as pi-schematic-readonly entries; last entry on branch wins T29, T26, T30 ✅ asserted T29 readonly-rehydration.test.ts — "getReadonlyFromBranch picks the latest entry (true wins)" / "(false wins)", "skips entries with wrong customType"; T26 "one readonly entry is appended per consumed queued toggle"; T30 validates restore through session_start.
PB-LIFE-32 Successor stored on the compaction entry; retry only without a later user turn / owned delivered successor T13, T11, T49 ✅ asserted T13 covers lineage/ownership/dedupe extensively ("a persisted successor ends recovery", "a distinct user turn after the cut abandons recovery", "a successor carrying an appended operational report is owned delivery", "repeated tree triggers coalesce..."); T11 "the continuation frame is pinned byte-for-byte"; T49 e2e "persisted successor is not re-delivered by settle or tree navigation".
PB-LIFE-33 Global config at ~/.pi/agent/pi-schematic/model-groups.json T16 ✅ asserted T16 model-groups-crud.test.ts — "model groups use branded paths, global-only access, canonical own keys, and native max".
PB-LIFE-34 Trusted-project path <cwd>/.pi/pi-schematic/model-groups.json; untrusted = global-only T16, T22 ✅ asserted T16 "model groups use branded paths, global-only access..."; T22 "model groups untrusted root flow never probes project data and publishes global-only state to TUI".
PB-LIFE-35 Project group shadows same-named global for routing T15, T16 ✅ asserted T15 model-groups-router.test.ts — "effective model group names use project-over-global names"; T16 CRUD scope/precedence cases.
PB-LIFE-36 Malformed/unsupported-future-version file loads empty for its scope T16 ✅ asserted T16 "model groups load recovery handles malformed, schema-invalid, unsupported version, and backup failure", "store strictly partitions schema and legacy version domains".
PB-LIFE-37 Frontmatter selects model, model-group, thinking T24, T32 ✅ asserted T24 "explicit model frontmatter switches model", "model-group frontmatter triggers model switch for /name command", "thinking only frontmatter sets thinking level..."; T32 frontmatter-cache.test.ts covers each field's parse/normalization.
PB-LIFE-37 Frontmatter selects readonly T26, T32 ✅ asserted T26 "single /name input activates readonly frontmatter", "/skill:name activates readonly from skill frontmatter"; T32 caches the readonly field.
PB-LIFE-37 Explicit model takes precedence over model-group T24 ✅ asserted T24 "explicit model + model-group warns and uses explicit model", "explicit model + model-group + thinking uses explicit model and thinking...".
PB-LIFE-38 Model-selection frontmatter does not run headless T24 ✅ asserted T24 "headless session does not inherit model-group changes", "explicit model frontmatter is ignored in headless session".
PB-LIFE-38 Frontmatter selection does not run for extension-sourced input T26 ✅ asserted T26 "extension input stays a no-op when hasUI is false", "extension plain text without a slash stays a no-op", "queued slash + extension message preserves the first pending command".
PB-LIFE-38 Model-selection frontmatter blocked during streaming steer/follow-up T24, T26, T43 ✅ asserted T24 "streaming blocks model selection without mutation"; T26 "streaming readonly frontmatter is blocked without a delayed toggle"; T43 notifications.test.ts — "streaming model-selection notification explains the idle-agent requirement".
PB-LIFE-39 Spawn group randomly samples usable authenticated models each invocation, no no-repeat T15 ✅ asserted T15 "capability pre-selection excludes unauthenticated capable models and picks randomly from the capable set" asserts each of 6 selections consults the RNG (no cursor short-circuit) and reaches both capable members; "routed empty modality requirements select by RNG across usable members".
PB-LIFE-40 Delegated children cannot call spawn or handoff T01, T28 ✅ asserted T01 spawn.test.ts — "child tool names inherit active registered builtins and exclude recursive controls", "buildChildToolNames (2-arg fallback) removes spawn and handoff..."; T28 readonly-spawn.test.ts — "buildChildToolNames excludes spawn and handoff from inherited tools" and the real-child tool-set assertion.
PB-LIFE-41 Parent-only transient credentials/catalog edits may be absent in the child runtime T06 ✅ asserted T06 spawn-runtime-compatibility.test.ts — "a parent-transient selected model fails explicitly in the real child runtime without fallback" and "spawn routes through the public registry but uses only the selected-model child session boundary".
PB-LIFE-42 A model/provider switch starts a different provider cache (not cache preservation) — ⚠️ no test yet README-only statement; T06 covers selected-model boundaries but not cross-provider cache separation. A test asserting a newly selected provider misses the prior provider's cache would seal it.
PB-LIFE-43 Old pi-agenticoding sessions/config are not migrated — ⚠️ no test yet No fixture references pi-agenticoding. A test asserting a legacy path/config yields empty state with no migration would seal it.
PB-LIFE-44 0.6.0 renamed pi-agenticoding to pi-schematic — ⚠️ no test yet CHANGELOG-only; no fixture reads the rename or the 0.6.0 version (see PB-LIFE-04). A CHANGELOG/package-metadata invariant would seal it.
PB-LIFE-45 TUI keys use the pi-schematic-* prefix T44 ✅ asserted T44 reads STATUS_KEY_TOPIC/STATUS_KEY_READONLY and asserts literals pi-schematic-ctx, pi-schematic-warning, pi-schematic-notebook; T11 asserts pi-schematic-handoff status/widget keys.
PB-LIFE-45 Renamed session custom entries use the pi-schematic-* prefix T26, T30, T49 ✅ asserted T26/T30 assert pi-schematic-readonly entries; T49 asserts pi-schematic-handoff / pi-schematic-readonly-nudge. Note: notebook persistence entries are notebook-entry / notebook-generation (T08) and are not part of the renamed set.
PB-LIFE-17 before_agent_start injects one per-run date anchor after the primer and before the dynamic sections T10 ✅ asserted T10 system-prompt.test.ts — "before_agent_start places date anchor after primer and before dynamic sections" asserts the order and counts a single anchor block; "before_agent_start injects a parseable date anchor".
PB-LIFE-46 Date anchor is one ## Current date block: ISO date + weekday + IANA zone + UTC offset + resolve-relative directive, no clock T50 ✅ asserted T50 time-format.test.ts — "formatCurrentDatePrompt anchors the date and instructs resolution" pins the whole block literal; "formatCurrentDatePrompt renders exactly one ISO date"; "formatCurrentDate carries no clock reading".
PB-LIFE-47 Anchor is byte-stable within a calendar day; midnight keeps the prior day; DST offset flips at most once T50 ✅ asserted T50 "formatCurrentDatePrompt is byte-stable across a whole calendar day", "…across the host day", "…holds one date change and one offset flip across a DST transition" (asserts an ordered single flip, not set cardinality).
PB-LIFE-47 Anchor is rebuilt once per agent run (not per turn) T50 ◐ partly asserted T50 pins "date anchor changes across midnight" at the pure-function level, and T10 drives the handler ("before_agent_start injects a parseable date anchor"). Missing portion: a handler-level test with a controlled clock proving before_agent_start re-reads the date each run rather than caching it.
PB-LIFE-48 All fields from one Intl call for the rendered zone; unrenderable zone → UTC; host zone default T50 ✅ asserted T50 "formatCurrentDate degrades an unusable zone to the fallback", "hostZone drives a renderable default anchor", "formatCurrentDate renders the calendar day of the zone, not the host", "formatCurrentDate defaults to the host zone under a pinned TZ" (child process, TZ=America/New_York), and the whole-offset-range property test.

Empty surfaces in this area

  • PB-LIFE-01 (pi install npm:pi-schematic): no fixture reads the README install line; a docs invariant asserting that exact command would seal it.
  • PB-LIFE-04 (package version 0.6.0): no fixture reads package.json.version; a metadata invariant asserting the version (and CHANGELOG parity) would seal it.
  • PB-LIFE-07 (./index.ts Pi extension entry): no fixture reads package.json pi.extensions; asserting pi.extensions === ["./index.ts"] would seal it.
  • PB-LIFE-09 (settings.json compaction-disabled recommendation): no fixture reads the documented settings block; a docs invariant would seal it.
  • PB-LIFE-14 (/new is not extension-registered): no fixture asserts the absence of a new extension command; an e2e cmds assertion excluding new would seal it.
  • PB-LIFE-15 (empty/unset TUI placeholders 📒 0, 🧭 -): T44 only exercises populated state; asserting the empty-notebook count and unset-topic placeholder would seal it.
  • PB-LIFE-42 (provider switch = different provider cache): README-only; a cross-provider cache-separation test would seal it.
  • PB-LIFE-43 (no pi-agenticoding migration): no fixture references the old name; a legacy-config load showing no migration would seal it.
  • PB-LIFE-44 (0.6.0 rename): CHANGELOG-only, no fixture; a CHANGELOG/metadata invariant would seal it.

Area coverage summary

Claims Junction rows ✅ ◐ ⚠️
48 73 62 2 9

Clone this wiki locally