@gobing-ai/spur 0.3.90 → 0.3.91

package/plugins/sp/scripts/surface-drift-inventory.ts

@@ -346,6 +346,67 @@ export function checkNounVerbFlags(
     }
 }
 
+// ─── Semantic operand layer (I7 / task 0906 R2) ─────────────────────────────
+
+/**
+ * Metadata-only operands the I6 sweep classified. This is the audit boundary, not a
+ * CLI section matrix: a key that is ALSO a genuine body heading for the noun (feature
+ * `Scope`) is accepted per-noun in checkSectionOperand; anything outside this set is
+ * not statically classifiable and stays unverified.
+ */
+const SECTION_METADATA_KEYS = new Set([
+    'tags',
+    'priority',
+    'status',
+    'phase',
+    'id',
+    'parent',
+    'name',
+    'owner',
+    'scope',
+]);
+
+/** Body headings that overlap the swept metadata keys, per noun (case-insensitive). */
+const NOUN_BODY_SECTIONS: Record<string, ReadonlySet<string>> = {
+    feature: new Set(['scope']),
+};
+
+/**
+ * Semantic operand check (I7 / task 0906 R2): `--section` is a real flag on
+ * task/feature update, so existence parity passes while the operand names a
+ * metadata-only key instead of a body section. Classify literal operands only —
+ * dynamic operands (placeholders) stay unverified under the existing scanner
+ * convention, and quoted/equal forms are handled alongside the spaced form.
+ * Comparison is case-normalized; the original operand text stays in the row evidence.
+ */
+export function checkSectionOperand(spanRaw: string, occ: { file: string; line: number }): void {
+    const parsed = parseInvocation(spanRaw);
+    if (!parsed) return;
+    const noun = parsed.nouns[0];
+    if ((noun !== 'task' && noun !== 'feature') || !parsed.verbs.includes('update')) return;
+    for (const m of spanRaw.matchAll(/--section(?:=|\s+)("([^"]*)"|'([^']*)'|[^\s]+)/g)) {
+        const operand = (m[2] ?? m[3] ?? m[1] ?? '').replace(/[.,;:]+$/, '');
+        if (!operand || PLACEHOLDER.test(operand)) continue; // dynamic — unverified by convention
+        const key = operand.toLowerCase();
+        if ((NOUN_BODY_SECTIONS[noun] ?? new Set()).has(key)) continue; // genuine body heading
+        if (!SECTION_METADATA_KEYS.has(key)) continue; // outside the audit boundary — unverified
+        // P3 (0906 review): feature update owns the generic --field/--value pair; task update
+        // exposes metadata only via dedicated flags (no --field/--value, no --tags), so the hint
+        // must not suggest a pair that would fail with VALIDATION_FAILED on task rows.
+        const remediation =
+            noun === 'feature'
+                ? `use --field ${operand} --value <value>`
+                : `task update exposes metadata only via dedicated flags (e.g. --priority <value>), not --section`;
+        record(
+            `spur ${noun} update --section ${operand}`,
+            'semantic-operand(I6 metadata keys vs noun body sections)',
+            'mismatch',
+            `--section writes a body section; "${operand}" is a metadata-only ${noun} operand — ${remediation}`,
+            occ,
+        );
+    }
+}
+
 export function sweepPluginTrees(root: string = PLUGIN_ROOT): void {
     const files = [
         ...walk(join(root, 'commands'), ['.md']),
@@ -398,6 +459,7 @@ export function sweepPluginTrees(root: string = PLUGIN_ROOT): void {
                         continue;
                     }
                     checkNounVerbFlags(parsed.nouns, parsed.verbs, parsed.flags, occ);
+                    checkSectionOperand(span, occ);
                 }
                 if (file.endsWith('.ts')) return;
                 if (inVerbTable && refNoun && /^\|/.test(line)) {
@@ -430,7 +492,10 @@ export function sweepPluginTrees(root: string = PLUGIN_ROOT): void {
             } else {
                 for (const span of lineInvocationSpans(line)) {
                     const parsed = parseInvocation(span);
-                    if (parsed) checkNounVerbFlags(parsed.nouns, parsed.verbs, parsed.flags, occ);
+                    if (parsed) {
+                        checkNounVerbFlags(parsed.nouns, parsed.verbs, parsed.flags, occ);
+                        checkSectionOperand(span, occ);
+                    }
                 }
             }
         });
@@ -764,11 +829,11 @@ export function sweepWorkflows(opts: { run?: CliRunner; wfDir?: string; link?: s
             .forEach((line: string, i: number) => {
                 for (const span of lineInvocationSpans(line)) {
                     const parsed = parseInvocation(span);
-                    if (parsed)
-                        checkNounVerbFlags(parsed.nouns, parsed.verbs, parsed.flags, {
-                            file: path,
-                            line: i + 1,
-                        });
+                    if (parsed) {
+                        const occ = { file: path, line: i + 1 };
+                        checkNounVerbFlags(parsed.nouns, parsed.verbs, parsed.flags, occ);
+                        checkSectionOperand(span, occ);
+                    }
                 }
             });
     }

package/plugins/sp/scripts/validate-flag-contracts.ts

@@ -406,9 +406,9 @@ export function extractTriggerTable(crossCuttingRaw: string): string[] | null {
 function adrAgentClaims(adrRaw: string): Map<string, SurfaceBehavior> | null {
     if (adrRaw.includes('## ADR-047')) {
         const out = new Map<string, SurfaceBehavior>();
-        // G5 amendment (feature G5 / task 0565): explicit inline is host-session-only — headless
-        // surfaces reject it with the stable special error; 0508 native-subagent eligibility
-        // applies to omitted --agent only, never explicit inline.
+        // ADR-087 (task 0687) retired the G5 frozen rejection: explicit `inline` on a headless
+        // surface resolves via role/tier substitution with one warning. This claims map mirrors
+        // the ADR-047 amendment text as written; ADR-087-aware parsing is a follow-up.
         out.set('inline', {
             surfaces: new Set(['inline']),
             conditional: false,

package/plugins/sp/skills/spur-cli/references/agent.md

@@ -231,8 +231,17 @@ to executors via `agent.executors[].agent` (or the model's `<provider>/` prefix)
 write path. A provider is exhausted when any `primary|secondary|tertiary` window reports
 `usedPercent >= 100`; the window name and `resetsAt` go into the observation reason. Per-provider
 `{ "error": … }` entries are skipped (listed, never treated as recovery); healthy entries still
-apply. A missing codexbar binary or an unparsable payload exits `1` and changes nothing.
-Unmapped providers are listed and never guessed.
+apply. Providers whose windows are all null carry no signal (`no-usage`): they are reported and
+excluded from availability decisions — an absent signal neither disables nor recovers, and an
+exhausted signal wins on shared executors. Operator-owned availability (`disabled: true` or an
+operator ownership object) is never touched. A missing codexbar binary or an unparsable payload
+exits `1` and changes nothing. Unmapped providers are listed and never guessed.
+
+Each reported change carries a delivery-semantics `action` (0907): `would-apply` (dry run),
+`applied` — the exact observation created by the invocation was acknowledged without a skip
+(desired state confirmed; not proof of a YAML byte change), `no-op` — already satisfied or
+operator-owned, `skipped` — the observation was superseded or rejected, `pending` — delivery
+unconfirmed or failed. For `skipped`/`pending` the printed target is intent only.
 
 **Scheduling is external** (cron/launchd, same pattern as `spur history daily`):
 

package/plugins/sp/skills/spur-cli/references/self.md

@@ -90,7 +90,11 @@ spur self status --json               # machine-readable
 ```
 
 Reports the project's Spur configuration state (init status, feature/task counts, rule preset
-health) and git working-tree status. Optional `[path]` argument targets a different project
+health), git working-tree status, and DecisionMaker readiness (0911): the human output adds a
+`DecisionMaker:` line and `--json` exposes `decisionMaker: {enabled, provider,
+credentialPresent, state, connectivity, inlineSupport}` with states `disabled` / `missing-key` /
+`configured-not-probed`. Presence check only — never a live probe, never echoes the key.
+Optional `[path]` argument targets a different project
 directory. Only flag is `--json`.
 
 ## What this skill is NOT

package/plugins/sp/skills/spur-cli/references/workflows.md

@@ -80,7 +80,9 @@ Use this skill to:
 - **Author a workflow** — turn a described process into a validated, dry-run-verified YAML definition
   in the right mode. → authoring-workflows.md
 - **Validate before trusting** — schema + semantic-check a workflow file (references, terminal
-  reachability, template vars) before running it.
+  reachability, template vars, and since 0911 the HITL decision policy: `decision` only on
+  `hitl.confirm`/`hitl.select`, evidence mode banned in `pause: true` states/nodes, one evidence
+  action per state/node, existing producer nodes, valid select choices) before running it.
 - **Run a workflow** — execute a definition and read its run trace (states/nodes entered, transitions
   taken, terminal status).
 - **Refine an existing workflow** — fix a stuck guard, add a state/node, retune `iterationBound`,

package/plugins/sp/skills/spur-dev/references/cross-cutting.md

@@ -61,6 +61,18 @@ The explicit-rejection carve-out above was superseded by ADR-087 (task 0687): a
 substitutes tier resolution with a warning instead of rejecting — see the substitution blockquote
 above and `resolveAgent` in `packages/app/src/services/agent-service.ts`.
 
+### Run-scoped session policy (B7, summary)
+
+When an inline resolution dispatches a native subagent, or a workflow `agent.run` executes, the
+run-scoped session policy applies: coder stages default to `session: reuse`; reviewer, planner,
+and scribe stages default to `fresh`; a reviewer stage may declare `session: reuse` explicitly.
+A runner record without resume capability (`supportsResumeById: false`) forces a fresh dispatch,
+and a disabled pinned executor re-resolves once, then starts fresh. Run traces record the session
+provenance (`reused | fresh`). This is a summary only: the owning contract is
+[session-pinned-dispatch.md §4](../../../../../docs/design/session-pinned-dispatch.md) with role
+semantics in [roles.md](../../../references/roles.md); this section does not restate that
+contract.
+
 ### Objective triggers override the answer
 
 The one rule resolves operator *intent*. A trigger is a detected *requirement* the chosen executor
@@ -188,8 +200,15 @@ Do not read provider auth or quota from `spur agent doctor`. The doctor resolves
 config), so it historically degraded to `status: usable · auth: no · model: unknown` for GLM-style
 executors and was useless as a preflight gate. Feature B4 removed the auth signal from the surface
 entirely (no column, no `authenticated` in `--json`) precisely so nothing can read it by mistake;
-the precheck probe classifies on usability alone. Exhaustion is detected mid-run by the escalation
-classifier, not by any preflight probe.
+the precheck probe classifies on usability alone. Preflight availability does exist — as a
+separate, owned surface (session-pinned-dispatch.md §3.4): `spur agent usage` captures provider
+quota windows into a durable snapshot, the availability drain derives `quota.exhausted` /
+`quota.recovered` observations from it, and `spur agent doctor` renders the provenance (`owner`,
+`since`, `reason`, snapshot `age`). A snapshot older than `agent.usage.maxAgeMs` renders `stale`
+and never enables an executor. Usability (doctor) is not authentication, and neither is a live
+quota guarantee — the signals stay distinct. Mid-run exhaustion is still detected by the
+escalation classifier; the preflight surface informs planning, it does not replace the in-run
+detector.
 
 ### Explicit subprocess surfaces are unchanged
 

package/plugins/sp/skills/spur-dev/references/execution-workflow.md

@@ -260,7 +260,10 @@ an executor failed — the executor is swappable via config, the pipeline is not
 **When an `agent.run` step fails (timeout, non-zero exit, empty output):**
 
 1. **Diagnose, don't bypass.** Check `spur agent doctor <executor>` — is the agent
-   installed? Is auth present? Then check `.spur/config.yaml` → which role/executor does the
+   installed and usable? Doctor reports usability plus availability provenance (`owner`,
+   `since`, `reason`, snapshot `age`); it is read-only and a stale availability snapshot never
+   enables an executor — `spur agent usage` is the preflight availability signal. Then check
+   `.spur/config.yaml` → which role/executor does the
    run resolve to (`agent.default` role → stage-registry tier ladder)? Which model does that
    executor use? Could that model be out of tokens, rate-limited, or deprecated?
 2. **Switch executors, don't abandon the pipeline.** Override the agent for the run:
@@ -275,12 +278,18 @@ an executor failed — the executor is swappable via config, the pipeline is not
    Manual section fills outside either driver are indistinguishable from pipeline output and bypass
    the provenance contract silently.
 
-**Known diagnostic gap:** `spur agent doctor` checks installation, version, and auth — it
-cannot detect token quota exhaustion, model deprecation, or rate limits. An executor
-configured with `agent: omp` + `model: <provider/model>` passes doctor if `omp` is
+**Known diagnostic gap:** `spur agent doctor` checks installation, version, and usability
+(read-only, with availability provenance from `spur agent usage`; a stale snapshot never
+enables) — it cannot detect mid-run token quota exhaustion, model deprecation, or rate limits.
+An executor configured with `agent: omp` + `model: <provider/model>` passes doctor if `omp` is
 installed, even if the model is unavailable. If an `agent.run` times out with no useful
 diagnostic, suspect the model, not the agent binary.
 
+Executor switching also interacts with run-scoped session policy (coder `reuse`,
+reviewer/planner/scribe `fresh`): see the session-policy summary in
+[cross-cutting.md#inline-default-execution-surface](cross-cutting.md#inline-default-execution-surface);
+this file does not restate that contract.
+
 ## Large tasks and timed-out implement resume (task 0424)
 
 Two obligations when driving a task that may not fit one implement pass.

package/plugins/sp/skills/spur-dev/references/glossary.md

@@ -72,10 +72,18 @@ reserved for this specific planning/execution split).
 **HITL** (human-in-the-loop) — a workflow state that pauses for explicit operator approval
 before continuing (`hitl.confirm`). A HITL gate is never auto-dismissed by the engine; `--auto`
 can only route *around* one whose objective precondition is already met (see the `--auto`
-routing contract in `cross-cutting.md`).
+routing contract in `cross-cutting.md`). A `decision` option (0911) pins that action's policy:
+`mode: never` forces the human responder, `mode: evidence` lets the optional DecisionMaker answer
+only from verified prior action evidence (deferring otherwise), and absence keeps the 0910
+implicit behavior when `workflow.hitlDecisionMaker` is enabled.
 Avoid: *prompt* (reserved for LLM input text), *interrupt* (implies an exception, not a planned
 pause point).
 
+**DecisionMaker** — optional provider-backed responder for executed `hitl.confirm`/`hitl.select`
+actions (ADR-123), enabled via `workflow.hitlDecisionMaker: true` and `TYPESAFE_API_KEY`.
+Evidence answers clear the answer variable and record `statusVar: accepted/deferred`; unresolved
+cases defer or delegate to the human. Offline readiness: `spur self status`.
+
 **WBS** (work-breakdown-structure ID) — the four-digit task identifier (e.g. `0187`) that
 names a task file and its position in the corpus. WBS IDs are assigned once and never reused.
 Avoid: *task ID* alone (acceptable in prose, but *WBS* is the canonical term when precision

package/plugins/sp/skills/spur-dev/references/inline-pipeline-driver.md

@@ -23,7 +23,7 @@ the resolved actions and guards of every `.spur/workflows/*.yaml`; any element p
 in one and absent in the other fails the check. Add a new kind here when the driver
 implements it; remove the entry when the corresponding kind is dropped from the YAML.
 
-**Actions:** `shell` · `note` · `doctor.probe` · `file.read.into-var` · `hitl.confirm` · `agent.run` · `proof.fingerprint` · `run.artifact` · `command.gate`
+**Actions:** `shell` · `note` · `doctor.probe` · `file.read.into-var` · `hitl.confirm` · `hitl.select` · `agent.run` · `proof.fingerprint` · `run.artifact` · `command.gate`
 
 **Guards (transitions):** `always` · `shell` · `action-ok` · `contract-violation`
 
@@ -45,6 +45,14 @@ FSM definition. The driver MUST read that file
 at invocation time. It must not copy the state list, actions, guards, or transition order into a
 command, skill, script, or second workflow.
 
+**Inline HITL defer semantics (0911):** bundled pipeline human gates ship `decision: {mode:
+never}`, so the inline driver always prompts the operator for those gates regardless of
+`workflow.hitlDecisionMaker` — the decision policy never answers inline pipeline gates. A local
+workflow override (`.spur/workflows/*.yaml`) may declare `mode: evidence`, but the driver does
+not claim full inline parity for the DecisionMaker path: evidence-mode auto-answering inside the
+inline driver is an explicit non-goal (subprocess runs own that behavior). No hot reload: config
+and YAML changes require restarting the invoking process.
+
 ## Run setup
 
 **Shared startup contract (task 0814 R1/R3/R4/R6/R7).** The order is load-bearing: publish a compact

package/plugins/sp/skills/wayfinder/SKILL.md

@@ -120,7 +120,7 @@ Invoked when the operator has a loose idea and the destination itself is foggy.
    - **## Decisions so far** — empty on creation; populated as questions and tickets resolve (one line each: the decision, or WBS + title + one-line gist)
    - **### Not yet specified** — the fog of war: in-scope questions you can sense but can't yet phrase sharply enough to ticket. Nest under `## Notes`.
    - **### Out of scope** — work consciously ruled beyond this destination. Nest under `## Notes`.
-   - **Tag the feature as a wayfinder map.** `spur feature update <id> --section tags --from-file <(printf '["wayfinder-map"]')`. The `wayfinder-map` tag tells `feature check` to skip BDD AC validation — maps deliberately carry a prose no-AC disclaimer instead of Gherkin scenarios, so without the tag the checker flags a false error.
+   - **Tag the feature as a wayfinder map.** `spur feature update <id> --field tags --value wayfinder-map`. The `wayfinder-map` tag tells `feature check` to skip BDD AC validation — maps deliberately carry a prose no-AC disclaimer instead of Gherkin scenarios, so without the tag the checker flags a false error.
 4. **Create child tasks only for executable investigations.** `spur task create "<title>" --feature <feature-id>` for each sharp question **an implementer can answer without the operator** — research, prototype, inventory, measurement. Anything needing the operator's judgment goes to **## Open questions** instead. Ticket types (see below) determine which skill resolves the tasks.
 5. **Wire blocking edges.** After all tickets exist (they need IDs before they can reference each other), set dependencies via `spur task update`. Wiring sorts tickets into the frontier (open, unblocked, unclaimed) and the blocked.
 6. **Populate the fog.** Everything you can't yet specify stays in **### Not yet specified** — sketch it as loosely or as fully as the view allows. Don't pre-slice fog into ticket-sized pieces; one patch may graduate into several tickets, or none.