Skip to content

Spec2Contract Watchdog

Grzegorz Nowak edited this page Sep 30, 2026 · 1 revision

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

This area covers pi-schematic's primacy-zone watchdog: context-band nudges, default/boundary guidance copy, the ≥70% TUI warning widget, the system-prompt context primer and topic/model-group sections, and readonly nudge/promotion behaviour. Left space is PB-WATCHDOG-<nn> (45 rows). Contracts are carried mainly by T46 (watchdog.test.ts) plus T44/T45 (TUI indicators/snapshots), T11/T12 (handoff status/eligibility), T30 (readonly topic-boundary promotion), T22 (Model Groups prompt section), T10 (system-prompt primer), and T25 (readonly toggle nudge).

Junction rows

Claim ID Assertion (terse) Fixture(s) Status Notes
PB-WATCHDOG-01 Practical primacy zone ≈ first 30%; quality degrades before the token limit T11, T10 ◐ partly asserted T11 handoff.test.ts — "handoff tool metadata and schema describe the prompt contract" asserts past ~30% in tool copy. Missing: the docs/why rationale that degradation precedes the limit; the primer's primacy-zone section is not asserted by T10.
PB-WATCHDOG-02 Bands + high-usage warning are awareness aids; no automatic compaction T44, T46 ◐ partly asserted T44 "shows readonly-specific warning widget at 70%+ context" and T46 nudge tests show advisory spawn-vs-handoff copy. Missing: no test asserts that no auto-compaction fires (awareness-only contract).
PB-WATCHDOG-03 Ordinary reminders omitted when usage unavailable or below 30% T46 ✅ asserted T46 "context treats malformed percentages as unavailable", "context nudges at band crossings and after a below-30% reset", "watchdog band-crossing: nudge iff context enters a higher band".
PB-WATCHDOG-04 30–49% reminder opens Context at <rounded>% — choose your next step by topic fit. T46 ◐ partly asserted Band entry at 30% is asserted to nudge ("context nudges at band crossings…", property test). Missing: the exact 30–49% opening copy is not asserted.
PB-WATCHDOG-05 50–69% reminder opens Context at <rounded>% — topic discipline matters now. T46 ◐ partly asserted Band entry at 50% is asserted to nudge. Missing: the exact 50–69% opening copy is not asserted.
PB-WATCHDOG-06 ≥70% reminder opens Context at <rounded>% — topic discipline is urgent. T46 ◐ partly asserted T46 "context injects watchdog reminder before each LLM call" asserts the 70% reminder contains 70%. Missing: the exact "topic discipline is urgent" wording is not asserted.
PB-WATCHDOG-07 Documented 30–49% intent is a primacy-zone reminder — ⚠️ no test yet No test reads the CHANGELOG tier-intent lines. A docs assertion (cf. T01 "spawn docs document active registered inheritance") matching the 30–50% tier line would seal it.
PB-WATCHDOG-08 Documented 50–69% intent is to consider handoff soon — ⚠️ no test yet No test reads the CHANGELOG tier-intent lines. A changelog assertion for the 50–70% tier would seal it.
PB-WATCHDOG-09 Documented ≥70% intent is that auto-compaction may trigger soon — ⚠️ no test yet No test reads the CHANGELOG tier-intent lines. A changelog assertion for the 70%+ tier would seal it.
PB-WATCHDOG-10 Reminders throttled to one delivery on entry into each band T46 ✅ asserted T46 "context nudges at band crossings and after a below-30% reset" ([29,f],[30,t],[49,f],[50,t],[69,f],[70,t]) and "watchdog band-crossing: nudge iff context enters a higher band".
PB-WATCHDOG-11 Returning below 30% clears the remembered band T46 ✅ asserted Same two band tests (reset then re-entry at 30% nudges again; property raw<30 sets lastBand=null).
PB-WATCHDOG-12 Reminder appended as custom / pi-schematic-watchdog / display:false T46 ✅ asserted T46 "context injects watchdog reminder before each LLM call" asserts role, customType, display:false, and content reaching the message list.
PB-WATCHDOG-13 agent_end records latest valid percent; malformed → null T46 ✅ asserted T46 "watchdog records context usage without user notifications" (70), "watchdog ignores malformed percentages" (NaN/∞/-1→null), "watchdog records overflow percentages" (125).
PB-WATCHDOG-14 Status bar ctx <pct>% tones: dim/accent/warning/error for <30/30–49/50–69/≥70 T44, T45 ◐ partly asserted T44 "uses accent tone at 30-49%", "uses warning tone at 50-69%", "uses error tone at 70%+"; T45 "context indicator at 30/50/70% matches snapshot". Missing: dim tone for a valid <30% (e.g. 20%) is not asserted.
PB-WATCHDOG-15 Missing/negative/non-finite/malformed percent renders ctx --% T44 ✅ asserted T44 "handles null context usage" and "treats malformed percentages as unavailable".
PB-WATCHDOG-16 Finite non-negative accepted with no 100% cap; overflow displayable T44, T12 ✅ asserted T44 "preserves overflow context percentages" (125%); T12 "context percentage normalization accepts finite non-negative usage, including overflow".
PB-WATCHDOG-17 ≥70% shows above-editor warning widget; <70/invalid removes it T44 ✅ asserted T44 "shows readonly-specific warning widget at 70%+", "hides widget below 70% context", "treats malformed percentages as unavailable", "sets context usage status with correct color tone" (42 no widget).
PB-WATCHDOG-18 Widget with active topic: same topic → spawn; different → handoff — ⚠️ no test yet No test asserts the non-readonly active-topic widget copy. updateIndicators with activeNotebookTopic set at ≥70% asserting "same topic → spawn, different topic → handoff" would seal it.
PB-WATCHDOG-19 Widget with no topic: hand off soon unless a topic can be assigned cleanly — ⚠️ no test yet No test asserts the no-topic widget copy. updateIndicators with no topic at ≥70% asserting the "handoff soon unless you can assign one cleanly" wording would seal it.
PB-WATCHDOG-20 Widget switches to readonly wording: same topic → spawn; different → readonly trigger T44 ✅ asserted T44 "shows readonly-specific warning widget at 70%+ context" asserts "readonly", "spawn", "explicit /handoff".
PB-WATCHDOG-21 Default reminder names the active topic as the semantic frame T46 ✅ asserted T46 "context injects watchdog reminder before each LLM call" (/oauth/) and "buildNudge emits topic and spawn guidance" (Active notebook topic: oauth).
PB-WATCHDOG-22 Same-topic work → spawn for isolated noisy subtasks T46 ✅ asserted T46 "buildNudge emits topic and spawn guidance" (/prefer spawn/i) and "context injects watchdog reminder…" (/spawn/i).
PB-WATCHDOG-23 Different-topic work → deliberate handoff if eligible, else continue until available T46 ◐ partly asserted T46 "default watchdog guidance respects token eligibility" asserts the ineligible branch (continue working until handoff is available, no "prefer a deliberate handoff"). Missing: the eligible default reminder's "prefer a deliberate handoff" wording is not asserted.
PB-WATCHDOG-24 No topic → assign a short stable topic; urgent by eligibility (next clean context vs now) T46 ◐ partly asserted T46 "context injects a no-topic nudge when context is high" asserts no-topic + fresh topic + handoff (ineligible urgent branch). Missing: the eligible "assign in the next clean context after handoff" branch.
PB-WATCHDOG-25 Pending topic change replaces reminder, names old+new, calls it a strong boundary signal T46 ✅ asserted T46 "context injects a boundary nudge below 30% after an explicit topic change" (oauth/billing/topic changed), "buildNudge handles null percent and boundary hints before topic guidance", "buildNudge uses prompt wording… topic boundaries" (task-boundary signal).
PB-WATCHDOG-26 Boundary reminder recommends handoff if eligible, advisory while not ready T46 ◐ partly asserted Eligible recommendation asserted (/call handoff/ in "buildNudge uses prompt wording…"). Missing: the ineligible "this boundary remains advisory for now" wording.
PB-WATCHDOG-27 Boundary reminder permits continuing inline when change was only a rename — ⚠️ no test yet No test asserts the rename clause. A buildNudge boundary test matching "Only continue inline if this was merely a rename" would seal it.
PB-WATCHDOG-28 Boundary guidance not suppressed below 30% or by ordinary throttling T46 ✅ asserted T46 "context injects a boundary nudge below 30% after an explicit topic change" (percent 20) and "context consumes a boundary hint after the first injected nudge".
PB-WATCHDOG-29 Readonly posture change → one-shot hidden pi-schematic-readonly-nudge with current constraints T46, T25 ✅ asserted T46 "context injects a readonly-mode nudge after toggle" (customType + readonly/write-edit/bash/handoff); T25 "readonly toggle delivers an activation nudge via context hook" asserts display:false; one-shot drain via T46 "context hook suppresses watchdog after readonly toggle nudge is drained".
PB-WATCHDOG-30 Readonly with no pending handoff/boundary suppresses regular reminders T46 ✅ asserted T46 "context hook suppresses watchdog after readonly toggle nudge is drained" ([70,30,50,80] all undefined).
PB-WATCHDOG-31 Readonly eligible human boundary = /handoff exception; UI warns to complete before normal work T46, T30 ◐ partly asserted T46 "eligible readonly human topic boundary auto-creates handoff bypass equivalent to /handoff"; T30 "readonly topic boundary creates the same bypass contract as explicit /handoff", "readonly topic boundary promotion exposes the handoff status" (handoff exception is now active). Missing: the "complete the handoff before continuing normal work" UI clause.
PB-WATCHDOG-32 Ineligible readonly human boundary stays advisory and is retained until eligible T46, T30 ✅ asserted T30 "readonly topic boundary stays advisory until handoff is eligible", "readonly human topic boundary promotes exactly at the token threshold without repeated advisory nudges", "advisoryDelivered flag prevents repeated advisory nudges for ineligible boundary"; T46 "eligible readonly human topic boundary…".
PB-WATCHDOG-33 Handoff eligible only at ≥30,000 measured/estimated tokens T12, T11 ✅ asserted T12 ("prefers explicit tokens", "estimates tokens from percent and context window", "rejects malformed or unestimable usage"); T11 "handoff tool accepts the exact 30000-token minimum" and "rejects session just below the 30000-token minimum".
PB-WATCHDOG-34 Each agent start appends the context-management primer to the system prompt T10 ✅ asserted T10 "before_agent_start injects notebook contracts plus live topic and page data" asserts base prompt kept and ## Context management added.
PB-WATCHDOG-35 Primer teaches "one context, one topic" + handoff when the ask no longer matches T10 ✅ asserted T10 "CONTEXT_PRIMER states the notebook, topic, and handoff contracts" matches "When the ask no longer matches the topic, call the handoff tool."; the literal "one context, one topic" line is co-located but not separately regexed.
PB-WATCHDOG-36 Primer planning choice: delegate same-topic work with spawn; else prefer handoff T10 ✅ asserted T10 topic section asserts /prefer spawn/ and /prefer handoff/; the ">10k-token" delegate threshold itself is not asserted.
PB-WATCHDOG-37 Primer: child agents isolate noise, return condensed results, parent orchestrates T10 ◐ partly asserted T10 asserts /overlong child output is truncated/i. Missing: "isolate noise" and "orchestration level" wording.
PB-WATCHDOG-38 Primer defines the notebook as a two-tier work-stream cache T10 ✅ asserted T10 notebook section /two-tier cache/; rules section /non-recoverable knowledge/ and /discard pages holding only recoverable code facts/.
PB-WATCHDOG-39 Primer: notebook_index then notebook_read only relevant pages; no body pre-load T10 ◐ partly asserted T10 notebook section asserts /notebook_index/ and /notebook_read/. Missing: the "fetch on demand / never pre-load bodies" assertion.
PB-WATCHDOG-40 Active topic is the semantic frame: same → spawn, different → handoff T10 ✅ asserted T10 topic section asserts /semantic frame/, /prefer spawn/, /prefer handoff/.
PB-WATCHDOG-41 Injected topic section names topic + source; unset → establish; human-set authoritative T10 ◐ partly asserted T10 "before_agent_start injects notebook contracts…" asserts Current topic: \oauth`; "injects no-topic guidance…"asserts the unset prompt +notebook_topic_set. Missing: the source label ((human-set)/(agent-set)`) and the "Human-set topics are authoritative" line in the injected section.
PB-WATCHDOG-42 Model Groups prompt section lists name + effective modalities/constraints T22 ✅ asserted T22 "before_agent_start injects fresh names-and-effective-modalities guidance", "exposes union-effective modalities for automatic mixed groups", "labels empty effective modalities unambiguously", "reinjects updated effective modalities after registry changes".
PB-WATCHDOG-42 Prompt withholds provider/model membership, thinking level, auth, validation, storage T22 ◐ partly asserted T22 asserts doesNotMatch /gpt-5/ (model id) and /model-groups\.json/ (storage path). Missing: no assertion that thinking-level, auth status, or validation details are withheld.
PB-WATCHDOG-43 Use requested known group exactly, pass required capabilities, never substitute T22 ◐ partly asserted T22 asserts /exact group name/, /known and confident/, /omit group and inherit/, /constraints/. Missing: the binding "do NOT fall back / stop and report" clause is not asserted.
PB-WATCHDOG-44 Notebook pages listed sorted, each name + first-line preview capped at 80 chars T10 ◐ partly asserted T10 asserts ## Active Notebook Pages and /alpha: first line/. Missing: sorted-order and the 80-char cap are not asserted.
PB-WATCHDOG-45 Listing directs notebook_read fetch; page bodies are not inlined T10 ◐ partly asserted T10 asserts /notebook_read/ and /Reference pages by name/i. Missing: no negative assertion that full page bodies are not inlined.

Empty surfaces in this area

  • PB-WATCHDOG-07 — no test asserts the documented 30–49% tier intent. Seal it with a CHANGELOG assertion matching the "primacy-zone heuristic" line (like T01's docs assertion).
  • PB-WATCHDOG-08 — no test asserts the documented 50–69% tier intent. Seal it with a CHANGELOG assertion matching the "consider handoff soon" line.
  • PB-WATCHDOG-09 — no test asserts the documented ≥70% tier intent. Seal it with a CHANGELOG assertion matching the "automatic compaction may trigger soon" line.
  • PB-WATCHDOG-18 — no test asserts the active-topic ≥70% widget copy. Seal it with an updateIndicators test (topic set, percent ≥70) matching "same topic → spawn, different topic → handoff".
  • PB-WATCHDOG-19 — no test asserts the no-topic ≥70% widget copy. Seal it with an updateIndicators test (no topic, percent ≥70) matching "handoff soon unless you can assign one cleanly".
  • PB-WATCHDOG-27 — no test asserts the rename escape hatch. Seal it with a buildNudge boundary test matching "Only continue inline if this was merely a rename".

Area coverage summary

Claims Junction rows ✅ asserted ◐ partly asserted ⚠️ no test yet
45 46 23 17 6

Clone this wiki locally