Repository navigation
Spec2Contract Lifecycle
Grzegorz Nowak edited this page Oct 10, 2026
·
4 revisions
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.
| Claim ID | Assertion (terse) | Fixture(s) | Status | Notes |
|---|---|---|---|---|
| PB-LIFE-01 | Install with pi install npm:pi-schematic
|
— | 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
|
— | 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 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}}
|
— | 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 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, 🧭 -) |
— | 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) | — | 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 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
|
— | 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. |
-
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 readspackage.json.version; a metadata invariant asserting the version (and CHANGELOG parity) would seal it. -
PB-LIFE-07 (
./index.tsPi extension entry): no fixture readspackage.jsonpi.extensions; assertingpi.extensions === ["./index.ts"]would seal it. -
PB-LIFE-09 (
settings.jsoncompaction-disabled recommendation): no fixture reads the documented settings block; a docs invariant would seal it. -
PB-LIFE-14 (
/newis not extension-registered): no fixture asserts the absence of anewextension command; an e2ecmdsassertion excludingnewwould 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-agenticodingmigration): 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.
| Claims | Junction rows | ✅ | ◐ | |
|---|---|---|---|---|
| 48 | 73 | 62 | 2 | 9 |