@gobing-ai/spur 0.3.99 → 0.4.0

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

@@ -301,10 +301,13 @@ tasks by `updated_at >= date`).
 
 **Anchor:** `#flag-fix`.
 
-Remediation policy on verify-family commands (`dev-verify`, `dev-verifyall`) and the refactor
-coordinator (`dev-refactor`):
+Remediation policy on verify-family commands (`dev-verify`, `dev-verifyall`), the refactor
+coordinator (`dev-refactor`) and the session review (`dev-review-session`):
 `none|blockers-first|all`. `none` reports findings without fixing; `blockers-first` fixes only P1/P2;
-`all` fixes everything found. Deprecated on `dev-review` (routes to `dev-verify --fix`).
+`all` fixes everything found. On `dev-review-session` the vocabulary is `none|auto|all`: `none`
+report-only, `auto` the `--triage` behavior (inline direct fixes, the rest filed as tasks), `all`
+fixes every actionable finding inline and files no task. Deprecated on `dev-review` (routes to
+`dev-verify --fix`).
 
 ### `--until <ref>` — upper bound on a range
 
@@ -336,6 +339,14 @@ specific status slice).
 Skip the shippable guard on verify-family commands (`dev-verify`, `dev-verifyall`). Used when
 verifying a task whose artifact is intentionally not yet shippable (e.g. a doc-only task).
 
+### `--no-summary` — skip the execution summary
+
+**Anchor:** `#flag-no-summary`.
+
+Skip the measured execution summary that run commands (`dev-run`, `dev-runall`) print by default
+once the run settles: per-stage (or per-run) time, operator wait, tool calls and total / non-cached
+tokens from the host transcript. Procedure: [dev-operations.md § Execution summary](dev-operations.md#execution-summary).
+
 ### `--skip-design` — omit the design package
 
 **Anchor:** `#flag-skip-design`.
@@ -445,7 +456,8 @@ Review commands (`dev-review`, `dev-review-session`): after the report, bucket e
 remainder through `spur task` — never fix straight from the raw findings list. Off by default
 (report-only). Both file one or more implement-ready tasks sized per cohesive unit, under existing
 features ([dev-operations.md § 2. review](dev-operations.md#2-review)); `dev-review-session` keeps
-the stricter direct-fix bar (pure docs / one-to-two-line fixes).
+the stricter direct-fix bar (pure docs / one-to-two-line fixes), and there `--triage` is an alias
+of `--fix auto` ([`--fix`](#flag-fix)).
 
 ### `--worktree [<name>]` — run the batch in an isolated git worktree (create or reuse)
 

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

@@ -159,6 +159,11 @@ the human/native presentation layer — labels are display addresses only, never
    resolved definition identity against the bound `__definitionDigest`; a mismatch is identity drift
    and fails closed (step 8 already caught projection-side drift; this re-checks the same definition
    the interpreter will execute).
+   - **Runtime-written vars are re-read, never cached.** A var a later state writes (`proofDigest`,
+     `proofDigestNow`, `taskSpecPath`, `featureSpecPath`, `taskPriority`, `mode`, `gateFindings`) is a
+     run artifact, not a YAML default: re-resolve it from `.spur/run/`/`.spur/memory/runs/` at every
+     state boundary, and never let a host-side copy of the invocation vars shadow it — a stale empty
+     `proofDigest` silently fails the bound `run.artifact` equivalence and the `record` proof guard.
    - **Layer 2** = the active state's `onEnter` actions (`kind` + resolved `input`/`command`), from
      the YAML read here, shown only for the active state.
    - **Refresh cadence** = stage boundaries only (when the current state changes after a transition),
@@ -342,9 +347,13 @@ or terminal close. Measure its actual duration and preserve its declared failure
 
 ```bash
 bun "$SETUP_SCRIPT" --action --run-id "$RUN_ID" --node <state-id> --kind <action-kind> \
-  --status <done|failed> --ok <true|false> --duration-ms <measured-ms>
+  --status <done|failed> --ok <true|false> --duration-ms <measured-ms> [--estimated]
 ```
 
+`--duration-ms` is the wall clock measured around the action. Pass `--estimated` when you did
+**not** time it — for example a duration reconstructed after a subagent returned — so the row is
+labelled instead of presented as measured. `--estimated` is valid only with `--action`.
+
 For a multi-action state, `--actions-file` may emit the measured boundaries together before leaving
 that state. Follow [Structured trace emission](#structured-trace-emission-adr-117-task-0868) for the
 payload, delegated `decide` emission and best-effort failure handling. Never retry a failed batch
@@ -357,6 +366,14 @@ Action semantics come from the YAML and the workflow action contract:
 - `note` — append the expanded message to the inline run log.
 - `doctor.probe` — run the declared Spur doctor once, persist its status file, and apply any
   `setVars` result (including a resolved executor) before the next action or state.
+  **Role-map mode has no inline surface (task 1088 session finding).** A `doctor.probe` that
+  declares `roles` resolves them through `AgentService.resolve`, which is reachable only in-process
+  (the engine composition injects the service); no CLI verb exposes it, so the host session cannot
+  reproduce `__executor.<role>` pins. The driver therefore probes the host-session agent instead,
+  writes that verdict to the declared status file, and records one run-log line naming the
+  substitution. Nothing downstream degrades: `__executor.<role>` pins are consumed by the
+  subprocess dispatch path, and the inline path executes its stages in the host session without
+  reading them. Never fabricate pins to satisfy the shape, and never skip the status file.
 - `file.read.into-var` — read the declared file into the declared run variable before subsequent
   actions/guards.
 - `hitl.confirm` — under `profile=auto`, follow the YAML's auto-skip transition. Otherwise pause,
@@ -628,23 +645,29 @@ The driver reaches it through the existing run delegate (`$SETUP_SCRIPT`,
 
   ```bash
   bun "$SETUP_SCRIPT" --action --run-id "$RUN_ID" --node <state-id> --kind <action-kind> \
-    --status <done|failed> --ok <true|false> --duration-ms <measured-ms>
+    --status <done|failed> --ok <true|false> --duration-ms <measured-ms> [--estimated]
   ```
 
   `<state-id>` is the current YAML state id (the `node`), `<action-kind>` the YAML action kind
   (`agent.run`, `shell`, `note`, `doctor.probe`, …). `--status` is `done` when the action settled
   under its declared error policy and `failed` otherwise; `--duration-ms` is the wall clock the
-  driver measured around the action. This writes the `action_runs` row (node, kind, status, `ok`,
-  `duration_ms`, `run_id`) the engine would have written, so the run's rows are queryable by run id
-  (`spur workflow progress <run-id>`, `ActionRunDao`) without reading the text log. The writer
+  driver measured around the action, and `--estimated` marks a duration the driver did **not**
+  time (a value reconstructed after the action returned). The row's provenance stamp rides
+  `action_runs.result_json` as `{provenance:'host-reported', estimated}`, and the projection
+  exposes it per attempt — `provenance` is `host-reported` for every inline row and `unknown`
+  for an engine-written or pre-stamp row, so the Board can label a host-reported duration
+  instead of presenting it as measured. This writes the `action_runs` row (node, kind, status,
+  `ok`, `duration_ms`, `run_id`) the engine would have written, so the run's rows are queryable
+  by run id (`spur workflow progress <run-id>`, `ActionRunDao`) without reading the text log.
+  The writer
   back-dates the row's `started_at` from its own `completed_at` minus the measured duration
   (0887 R8), so `completed_at − started_at == duration_ms` exactly; a back-date failure is
   recorded (`action.backdate`) and never affects the run.
 
 - **A state with several actions (1007 R5)** — emit the whole state's boundaries in one call
   instead of one `--action` invocation per action. Write a JSON array
-  (`[{node,kind,status,ok,durationMs}, …]` — same fields the `--action` flags carry) to a temp
-  file and pass it with `--actions-file`:
+  (`[{node,kind,status,ok,durationMs,estimated?}, …]` — the `--action` fields, `estimated`
+  optional and `false` when absent) to a temp file and pass it with `--actions-file`:
 
   ```bash
   bun "$SETUP_SCRIPT" --actions-file <actions.json> --run-id "$RUN_ID"
@@ -692,6 +715,8 @@ The driver reaches it through the existing run delegate (`$SETUP_SCRIPT`,
   `--status` is the declared terminal state's verdict, not a guess: a run that reached a terminal
   state is `done`; a run halted by a failing action under its error policy is `failed`. On success
   the close reports the recorded evidence: `{"ok":true,"runId":…,"actionRows":<n>}`.
+  After the close, the invoking command prints the measured
+  [execution summary](dev-operations.md#execution-summary) for `$RUN_ID` unless `--no-summary`.
 
   **Zero-row done closes are a named failure (task 0975 R2).** A run closed `done` with **zero**
   `action_runs` rows (`actionRows:0`) finalizes the row but exits `1` with

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

@@ -43,6 +43,12 @@ creation.
 spur feature create "<name>" [--parent <id>]
 ```
 
+Without `--parent`, choose one before creating: list the tree (`spur feature list --json`) and nest the
+feature under the existing feature that owns the surface or its design satellite. A new root feature
+is a last resort that needs an explicit operator decision. When a parent is full (the 9-child limit),
+nest under the closest owning child, and use `spur feature move <id> --parent <id> --dry-run` to
+relocate an existing feature.
+
 The feature file lands in `docs/features/<ID>_<slug>.md`. Immediately author the `## Goal`
 (single sentence) and `## Scope` (in/out bullets).
 

package/schemas/decision-catalog.schema.json

@@ -0,0 +1,226 @@
+{
+    "$schema": "http://json-schema.org/draft/2020-12/schema",
+    "title": "AI decision catalog",
+    "description": "Declarative decision catalog for @gobing-ai/ts-ai-decision (task 0089). Strict: unknown keys are rejected at every level. Cross-field checks (fallback vocabulary, ${params.*} references, defaults, reserved instructions parameter) run at load time.",
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["version", "decisions"],
+    "properties": {
+        "$schema": {
+            "type": "string",
+            "description": "Bundled package-specifier ref to this schema; validated when present."
+        },
+        "version": {
+            "const": 1
+        },
+        "defaults": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "maker": {
+                    "type": "string",
+                    "pattern": "^[a-z][a-z0-9-]*$",
+                    "description": "Registered maker name (built-ins: typesafe | fm-local | laya-local)."
+                },
+                "model": {
+                    "type": "string",
+                    "description": "Forwarded as the ask-level model; omit for the backend default."
+                },
+                "minConfidence": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 1
+                }
+            }
+        },
+        "decisions": {
+            "type": "object",
+            "minProperties": 1,
+            "propertyNames": {
+                "pattern": "^[a-z][a-z0-9_-]*$"
+            },
+            "additionalProperties": {
+                "$ref": "#/$defs/decision"
+            }
+        }
+    },
+    "$defs": {
+        "jsonValue": {
+            "anyOf": [
+                {
+                    "type": "string"
+                },
+                {
+                    "type": "number"
+                },
+                {
+                    "type": "boolean"
+                },
+                {
+                    "type": "null"
+                },
+                {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/jsonValue"
+                    }
+                },
+                {
+                    "type": "object",
+                    "additionalProperties": {
+                        "$ref": "#/$defs/jsonValue"
+                    }
+                }
+            ]
+        },
+        "jevEntry": {
+            "description": "A Jev entry: description string, JSON object, JSON array, or null (left undescribed). Description string leaves support ${params.*} templating.",
+            "anyOf": [
+                {
+                    "type": "string"
+                },
+                {
+                    "type": "null"
+                },
+                {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/jsonValue"
+                    }
+                },
+                {
+                    "type": "object",
+                    "additionalProperties": {
+                        "$ref": "#/$defs/jsonValue"
+                    }
+                }
+            ]
+        },
+        "paramType": {
+            "enum": ["string", "number", "boolean", "enum", "json"]
+        },
+        "param": {
+            "anyOf": [
+                {
+                    "$ref": "#/$defs/paramType"
+                },
+                {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["type"],
+                    "properties": {
+                        "type": {
+                            "$ref": "#/$defs/paramType"
+                        },
+                        "default": {},
+                        "values": {
+                            "type": "array",
+                            "items": {
+                                "type": "string"
+                            },
+                            "minItems": 1,
+                            "description": "Accepted strings for type: enum (at least one)."
+                        },
+                        "description": {
+                            "type": "string"
+                        }
+                    }
+                }
+            ]
+        },
+        "choiceCriteria": {
+            "type": "object",
+            "minProperties": 2,
+            "additionalProperties": {
+                "$ref": "#/$defs/jevEntry"
+            }
+        },
+        "scoreCriteria": {
+            "type": "array",
+            "minItems": 2,
+            "items": {
+                "$ref": "#/$defs/jevEntry"
+            }
+        },
+        "noulCriteria": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "true": {
+                    "$ref": "#/$defs/jevEntry"
+                },
+                "false": {
+                    "$ref": "#/$defs/jevEntry"
+                }
+            }
+        },
+        "decision": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["type", "fallback"],
+            "properties": {
+                "type": {
+                    "enum": ["choice", "score", "noul"]
+                },
+                "description": {
+                    "type": "string",
+                    "description": "Documentation only; never sent to the model."
+                },
+                "instructions": {
+                    "$ref": "#/$defs/jevEntry",
+                    "description": "Templated Jev entry; defaults to \"${params.instructions}\"."
+                },
+                "parameters": {
+                    "type": "object",
+                    "propertyNames": {
+                        "pattern": "^[a-z][a-zA-Z0-9_]*$"
+                    },
+                    "additionalProperties": {
+                        "$ref": "#/$defs/param"
+                    }
+                },
+                "criteria": {
+                    "description": "choice: label map (>= 2 labels); score: ordered rubric (>= 2 levels); noul: optional { true?, false? }.",
+                    "anyOf": [
+                        {
+                            "$ref": "#/$defs/choiceCriteria"
+                        },
+                        {
+                            "$ref": "#/$defs/scoreCriteria"
+                        },
+                        {
+                            "$ref": "#/$defs/noulCriteria"
+                        }
+                    ]
+                },
+                "fallback": {
+                    "description": "choice: a declared label; score: integer level in [0, levels-1]; noul: boolean.",
+                    "anyOf": [
+                        {
+                            "type": "string"
+                        },
+                        {
+                            "type": "number"
+                        },
+                        {
+                            "type": "boolean"
+                        }
+                    ]
+                },
+                "minConfidence": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 1
+                },
+                "maker": {
+                    "type": "string",
+                    "pattern": "^[a-z][a-z0-9-]*$",
+                    "description": "Registered maker name; checked by the hub, not the loader."
+                },
+                "model": {
+                    "type": "string"
+                }
+            }
+        }
+    }
+}

package/schemas/spur-config.schema.json

@@ -287,6 +287,31 @@
                 }
             }
         },
+        "decisions": {
+            "type": "object",
+            "description": "Decision-catalog resolution and DecisionMaker selection (feature P / ADR-134). The whole section is optional.",
+            "properties": {
+                "paths": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "Extra catalog folders for the registered decision layer (absolute, project-relative, or 'bundled:<sub>' against the installed package's config root)."
+                },
+                "maker": {
+                    "type": "string",
+                    "pattern": "^[a-z][a-z0-9-]*$",
+                    "description": "Default DecisionMaker for every decision point (built-ins: typesafe | fm-local | laya-local). Must be registered; an unknown name is a config error, never a silent fallback."
+                },
+                "makers": {
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "string"
+                    },
+                    "description": "Per-decision-point maker overrides, keyed by decision id; outrank decisions.maker."
+                }
+            }
+        },
         "redaction": {
             "type": "object",
             "properties": {