Repository navigation
Spec2Contract Workflows
Grzegorz Nowak edited this page Sep 30, 2026
·
1 revision
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).
| 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 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 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 $@ 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 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 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 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. | — | 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). |
-
PB-WORKFLOW-07 — no fixture asserts
descriptionas the human-facing description. Would seal: a test that a saved prompt'sdescriptionis surfaced as the command description. -
PB-WORKFLOW-08 — no fixture touches
argument-hint. Would seal: a test thatargument-hintis 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
/namewith 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.
| Claims | Junction rows | ✅ | ◐ | |
|---|---|---|---|---|
| 39 | 42 | 33 | 2 | 7 |