Skip to content

Spec2Contract Workflows

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

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

This page maps the Workflows area of the pi-schematic Product Book (left-space IDs PB-WORKFLOW-01…PB-WORKFLOW-39; 39 rows) onto the existing tests that seal each claim. Rows 01–10 cover the saved-prompt/skill user-facing surface and $@ expansion; rows 11–39 cover frontmatter policy resolution (readonly, model-group, model, thinking). The contracts are carried mainly by T32 (frontmatter-cache), T24 (model-group-frontmatter), and T26 (readonly-frontmatter: the deferred readonly half).

Junction rows

Claim ID Assertion (terse) Fixture(s) Status Notes
PB-WORKFLOW-01 Project stores a reusable prompt at .pi/prompts/<name>.md, invoked as /<name>. T32, T26 ✅ asserted frontmatter-cache.test.ts — "populatePromptCacheFromResolvedCommandsAndDirs caches .md files from project dir"; readonly-frontmatter.test.ts — "unresolved /name uses trusted cwd/.pi/prompts frontmatter via deferred fallback". Scope: name↔file mapping via frontmatter resolution; prompt-body expansion is host (Pi) behavior and is not asserted here.
PB-WORKFLOW-02 Prompt fallback checks trusted cwd/.pi/prompts/ before ~/.pi/agent/prompts/. T32, T26 ✅ asserted frontmatter-cache.test.ts — "project prompt overrides global prompt for the same name", "project/global precedence rebinding refreshes the cache for the same prompt name"; readonly-frontmatter.test.ts — "unresolved /name uses ~/.pi/agent/prompts frontmatter via deferred fallback".
PB-WORKFLOW-03 A resolved prompt command takes precedence over same-named prompt files in either prompt dir. T32 ✅ asserted frontmatter-cache.test.ts — "resolved prompt command stays authoritative over directory fallback"; also "resolved prompt command rebinding to a different file refreshes the cache".
PB-WORKFLOW-04 Project prompt dir is considered only when the project is trusted. T32 ✅ asserted frontmatter-cache.test.ts — "populatePromptCacheFromResolvedCommandsAndDirs does not scan project dir when projectTrusted is false", "evicts untrusted project prompt entries on rebuild".
PB-WORKFLOW-05 Skill invoked as /skill:<name>; prompt command invoked as /<name>. T32, T24 ✅ asserted frontmatter-cache.test.ts — "/name prompt lookup stays distinct from /skill:name lookup for the same name"; model-group-frontmatter.test.ts — "model-group frontmatter triggers model switch for /skill:name command" vs "…for /name command".
PB-WORKFLOW-06 Built-in/non-prompt slash commands do not acquire saved-prompt frontmatter from a same-named file. T32, T26 ✅ asserted frontmatter-cache.test.ts — "resolved non-prompt command blocks prompt-dir fallback for the same name"; readonly-frontmatter.test.ts — "late-resolved non-prompt /name does not inherit readonly from a same-named prompt file", "known non-prompt /name already present in the registry does not enqueue a deferred toggle".
PB-WORKFLOW-07 description supplies the human-facing description of a saved workflow. — ⚠️ no test yet No fixture reads/asserts a command's human-facing description. Would seal: a test that a saved prompt's description surfaces as the command's description in the command/TUI surface.
PB-WORKFLOW-08 argument-hint declares the presented argument shape for a saved workflow. — ⚠️ no test yet No occurrence of argument-hint outside README. Would seal: a test that the frontmatter argument-hint is surfaced as the command's argument shape.
PB-WORKFLOW-09 $@ in a workflow body expands to the argument supplied after the slash command. — ⚠️ no test yet No $@ assertion anywhere in tests. Would seal: a test that invoking /<name> args… substitutes the supplied args at the $@ placeholder.
PB-WORKFLOW-10 (aspect: model choice) A named Model Group owns the replaceable model choice. T24 ✅ asserted model-group-frontmatter.test.ts — "model-group frontmatter triggers model switch for /name command" resolves provider/modelId/thinking from group config without touching the prompt.
PB-WORKFLOW-10 (aspect: procedure ownership) A saved workflow owns the repeatable procedure. — ⚠️ no test yet No test asserts that the same prompt file yields a stable procedure independent of the selected model/group. Would seal: a test that the prompt body is applied identically while only the model-group config varies.
PB-WORKFLOW-11 readonly accepts only boolean true/false. T32 ✅ asserted frontmatter-cache.test.ts — "populateFromSkills returns null for non-boolean readonly frontmatter" (string/number/array), "caches a skill with readonly: true" / "…false".
PB-WORKFLOW-12 readonly: true enables readonly posture when the workflow resolves. T26 ✅ asserted readonly-frontmatter.test.ts — "single /name input activates readonly frontmatter" (subsequent write blocked), "/skill:name activates readonly from skill frontmatter".
PB-WORKFLOW-13 readonly: false disables readonly posture when the workflow resolves. T26 ✅ asserted readonly-frontmatter.test.ts — "readonly: false frontmatter keeps readonly disabled and stays silent when already disabled", "deferred readonly disable emits a one-shot context nudge".
PB-WORKFLOW-14 model-group accepts a non-empty group name. T32 ✅ asserted frontmatter-cache.test.ts — "populateFromSkills caches model-group frontmatter", "returns null and records issue for invalid model-group value", "treats whitespace-only model-group as empty/invalid".
PB-WORKFLOW-15 model is <provider>/<model-id>; only the first slash splits, model IDs may contain slashes. T32 ✅ asserted frontmatter-cache.test.ts — "populateFromSkills accepts slashes inside model IDs" (openrouter/anthropic/claude-sonnet), "returns null and records issue for invalid explicit model format" (no slash / empty provider / empty id).
PB-WORKFLOW-16 thinking accepts off|minimal|low|medium|high|xhigh|max. T32 ✅ asserted frontmatter-cache.test.ts — "populateFromSkills accepts all valid thinking levels" (off…xhigh), "accepts max thinking level", "normalizes thinking level case".
PB-WORKFLOW-17 A valid model selects that configured, authenticated model for the command. T24 ✅ asserted model-group-frontmatter.test.ts — "explicit model frontmatter switches model" (setModel + pi-schematic-model-switch entry); auth gate in "unauthenticated model in registry blocks explicit model selection".
PB-WORKFLOW-18 Explicit model takes precedence over model-group; TUI warns the group was overridden. T24 ✅ asserted model-group-frontmatter.test.ts — "explicit model + model-group warns and uses explicit model", "explicit model + model-group + thinking uses explicit model and thinking, warns about override".
PB-WORKFLOW-19 model-group routes the command through the named group when no explicit model is supplied. T24 ✅ asserted model-group-frontmatter.test.ts — "model-group frontmatter triggers model switch for /name command", "model-group frontmatter triggers model switch for /skill:name command".
PB-WORKFLOW-20 A frontmatter thinking value overrides the Model Group's thinking level. T24 ✅ asserted model-group-frontmatter.test.ts — "model-group + thinking overrides group thinking level" (setThinkingLevel gets frontmatter low, not group level).
PB-WORKFLOW-21 A frontmatter thinking value is clamped to the selected model's capabilities. T24 ◐ partly asserted model-group-frontmatter.test.ts — "model-group-only frontmatter applies and records the group's effective thinking" clamps the group level. Missing: no test where a frontmatter thinking exceeds the selected model's capability (e.g. reasoning level on a non-reasoning model) and asserts the clamped effective level; the valid-level tests all use models that support the requested level.
PB-WORKFLOW-22 thinking alone changes the current model's thinking level without switching models. T24 ✅ asserted model-group-frontmatter.test.ts — "thinking only frontmatter sets thinking level without changing model" (setModel 0, setThinkingLevel once, pi-schematic-thinking-change entry).
PB-WORKFLOW-23 Successful frontmatter model/thinking changes remain in effect for later commands. — ⚠️ no test yet No sticky-across-commands test. model-group commands are applied during their input preflight runs two commands but each re-resolves its own selection. Would seal: command A with model/thinking, then a plain command B, asserting B still runs under A's switched model/level.
PB-WORKFLOW-24 In the interactive TUI, model/model-group/thinking resolve during idle input, before slash-command expansion. T24 ✅ asserted model-group-frontmatter.test.ts — "model-group commands are applied during their input preflight" (setModel during the input handler, before agent start).
PB-WORKFLOW-25 readonly resolution is deferred to before_agent_start, where complete skill metadata is available. T26 ✅ asserted readonly-frontmatter.test.ts — "input handler queues a prompt command even when the registry is unavailable until before_agent_start", "before_agent_start skips readonly cache population while no slash-command toggle is pending", "/skill:name activates readonly from skill frontmatter".
PB-WORKFLOW-26 Headless/RPC invocation ignores saved-workflow model-selection policy. T24 ✅ asserted model-group-frontmatter.test.ts — "headless session does not inherit model-group changes", "explicit model frontmatter is ignored in headless session".
PB-WORKFLOW-27 Headless/RPC invocation ignores saved-workflow readonly policy. T26 ✅ asserted readonly-frontmatter.test.ts — "headless /name frontmatter stays a no-op through the deferred pipeline", "extension input stays a no-op when hasUI is false".
PB-WORKFLOW-28 During a streaming steer/follow-up, model/model-group/thinking frontmatter is blocked with an idle-agent warning. T24 ✅ asserted model-group-frontmatter.test.ts — "streaming blocks model selection without mutation" (steer+model, followUp+group, steer+thinking all {action:"handled"} with a warning).
PB-WORKFLOW-29 During a streaming steer/follow-up, readonly frontmatter is blocked with an idle-agent warning. T26 ✅ asserted readonly-frontmatter.test.ts — "streaming readonly frontmatter is blocked without a delayed toggle" (prompt/skill × true/false × steer/followUp; warning matches /readonly frontmatter requires an idle agent/).
PB-WORKFLOW-30 A streaming command without model-selection or readonly frontmatter continues rather than being blocked. — ⚠️ no test yet No streaming test registers a command carrying only non-policy frontmatter (or no frontmatter) and asserts {action:"continue"}. Would seal: a streamed /name with description-only frontmatter returns continue and does not warn.
PB-WORKFLOW-31 Readonly posture is enforced at the tool boundary after a workflow activates it. T26 ✅ asserted readonly-frontmatter.test.ts — "single /name input activates readonly frontmatter" repeatedly asserts toolCall({toolName:"write"}) returns block:true after the deferred toggle.
PB-WORKFLOW-32 Unknown/unauthenticated/unavailable/failed-to-switch explicit model blocks expansion with an error. T24 ✅ asserted model-group-frontmatter.test.ts — "unknown model in frontmatter blocks execution", "unauthenticated model in registry blocks explicit model selection", "model switch failure blocks explicit model selection".
PB-WORKFLOW-33 An unknown or unusable Model Group blocks expansion with an error. T24 ✅ asserted model-group-frontmatter.test.ts — "unknown model-group in frontmatter blocks execution with error", "unknown model-group in /skill:name frontmatter blocks execution before agent start", "empty model-group (SpawnRouteError) blocks execution with error".
PB-WORKFLOW-34 A failed model switch records no successful model/group/thinking change entry. T24 ✅ asserted model-group-frontmatter.test.ts — "setModel failures block explicit and group selection without success entries" (setModel false/reject for model and group; hasModelSelectionEntry false).
PB-WORKFLOW-35 (aspect: invalid ignored) An invalid readonly/model-group/model/thinking value is ignored. T32, T24, T26 ✅ asserted frontmatter-cache.test.ts — "returns null and records issue for invalid model-group value" / "…invalid explicit model format" / "…invalid thinking value"; model-group-frontmatter.test.ts — "invalid model-group value produces warning notification" (setModel 0).
PB-WORKFLOW-35 (aspect: warning names field) The TUI warning identifies the offending field. T24, T26 ✅ asserted model-group-frontmatter.test.ts — "invalid model-group value produces warning notification" (/model-group.*non-empty/), "invalid model format in frontmatter produces warning" (/`model`.*`<provider>\/<model-id>`/), "invalid thinking value produces warning" (/`thinking`.*off, minimal, low/); readonly-frontmatter.test.ts — "invalid /prompt readonly value records a warning for the prompt source" (/`readonly` frontmatter must be `true` or `false`/).
PB-WORKFLOW-35 (aspect: warning names source file) The TUI warning identifies the source file. — ⚠️ no test yet Warnings assert the command ref (/broken-prompt) and field, but no test asserts issue.filePath ("at ``") appears in the notification. Would seal: assert the notification contains the offending prompt/skill file path.
PB-WORKFLOW-36 Malformed frontmatter or an unreadable workflow file is ignored with a TUI warning. T32, T26 ✅ asserted frontmatter-cache.test.ts — "records malformed frontmatter issues", "records unreadable prompt issues", "populateFromSkills records malformed frontmatter issues"; readonly-frontmatter.test.ts — "malformed /prompt frontmatter records a parse warning for the prompt source", "unreadable /prompt frontmatter records a warning for the prompt source".
PB-WORKFLOW-37 Invalid thinking does not prevent a valid explicit model; the invalid thinking is warned and not applied. T24 ✅ asserted model-group-frontmatter.test.ts — "explicit model applies while invalid thinking is reported" (setModel once, setThinkingLevel 0, one warning + invalid-thinking-value issue).
PB-WORKFLOW-38 A failed model change leaves the current model and thinking level unchanged. T24 ◐ partly asserted model-group-frontmatter.test.ts — "model switch failure blocks explicit model selection" and "setModel failures … without success entries" assert the error and absence of a change entry; "explicit model without thinking does not change thinking level" shows no thinking call. Missing: no assertion of the live model/thinking values after the failure — only "no recorded entry" and "no setThinking call" are checked.
PB-WORKFLOW-39 A streaming model-selection block leaves model and thinking unchanged and records no successful selection entry. T24 ✅ asserted model-group-frontmatter.test.ts — "streaming blocks model selection without mutation" (modelCalls 0, thinkingCalls 0, hasModelSelectionEntry false, warning emitted).

Empty surfaces in this area

  • PB-WORKFLOW-07 — no fixture asserts description as the human-facing description. Would seal: a test that a saved prompt's description is surfaced as the command description.
  • PB-WORKFLOW-08 — no fixture touches argument-hint. Would seal: a test that argument-hint is surfaced as the command's presented argument shape.
  • PB-WORKFLOW-09 — no fixture asserts $@ argument expansion. Would seal: a test that /<name> args… substitutes the typed args into the body.
  • PB-WORKFLOW-10 / procedure-ownership aspect — no test that the saved procedure is stable while the model/group choice varies. Would seal: same prompt body applied under two model-group configs with only the model changing.
  • PB-WORKFLOW-23 — no sticky-across-commands test. Would seal: model/thinking frontmatter on command A, then a plain command B, asserting B runs under A's switched values.
  • PB-WORKFLOW-30 — no test for a streamed non-policy command continuing. Would seal: streamed /name with no policy frontmatter returns {action:"continue"}, no warning.
  • PB-WORKFLOW-35 / source-file aspect — no test asserts the warning contains the offending file path (issue.filePath). Would seal: assert the notification text includes the prompt/skill path.

Area coverage summary

Claims Junction rows ✅ ◐ ⚠️
39 42 33 2 7

Clone this wiki locally