@gobing-ai/spur 0.3.98 → 0.4.0

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

@@ -142,7 +142,10 @@ the human/native presentation layer — labels are display addresses only, never
    safety checks succeed, create/adopt and `cd` into the execution tree; confirm absolute cwd,
    branch, base SHA, and ownership. An invalid/empty target, unsupported mode, ambiguous ownership,
    or stale target stops without creating a tree or discarding work. All subsequent tools, agents,
-   corpus writes, and run artifacts use the confirmed execution tree.
+   corpus writes, and run artifacts use the confirmed execution tree — **re-selected per call, not
+   inherited**: a host shell call starts in an arbitrary directory and carries no cwd from the
+   previous call, so every later call runs inside the **Per-call execution-tree pin** protocol
+   below (task 1058), which consumes the identity confirmed here.
 8. **Publish the workflow inventory (R4), BEFORE reading the YAML.** Resolve the selected workflow
    through the same project/bundled resolver as execution and run
    `spur workflow show <resolved-file> --no-logo --format todo --json`. Validate the projection with
@@ -156,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),
@@ -186,6 +194,12 @@ the human/native presentation layer — labels are display addresses only, never
    This is required for the normal `testing → done` provenance guard. Planning pipelines have no
    task lifecycle link and skip this task-specific action.
 
+   **Run it from the task's execution tree.** Every tree has an isolated `.spur` DB, so a link
+   recorded from the invoking tree never satisfies a worktree's guard — the exact failure that
+   forced audited `--provenance-bypass` on tasks 1029/1030 (E93). Under `--worktree`, enter the
+   worktree first and run this command (and every lifecycle-touching command: `task record`,
+   `task update <wbs> testing|done`) from the worktree root.
+
 ### Idea-pipeline quick start (0887 R1/R2)
 
 Minimum files to read for `/sp:dev-idea` inline runs — then drive `idea-pipeline.yaml`:
@@ -215,6 +229,91 @@ Expected artifacts per stage (all run-scoped under `.spur/run/<run-id>-*`):
 | ready-prepare | `-idea-ready.json` |
 | handoff-finalize | `-idea-handoff.md` |
 
+## Per-call execution-tree pin (task 1058)
+
+A host shell tool call may start in an arbitrary directory; no earlier call's `cd` is input to the
+next call. During inline run `95522d21` that drift silently landed corpus writes in the invoking
+tree instead of the run worktree. Every host-session corpus command — reads, writes, absolute
+section-input files and output artifacts — therefore selects the confirmed execution tree **within
+the same tool call**, in a self-contained subshell. The identity is never re-derived: it is the
+tree path, branch and resolved Spur invocation confirmed at bootstrap isolation (step 7) and, for
+batch worktrees, recorded in the WT-3 marker (execution-batch.md). The resolved invocation is
+field 4 of the dispatch payload — never a bare `spur`.
+
+Template — every host shell call follows this shape; paths are quoted because trees may contain
+spaces:
+
+```bash
+(
+  cd -- "$SPUR_TREE" || { echo "tree missing: expected $SPUR_TREE" >&2; exit 1; }
+  ACTUAL_TREE="$(pwd -P)"
+  [ "$ACTUAL_TREE" = "$SPUR_TREE" ] || { echo "tree mismatch: expected $SPUR_TREE, got $ACTUAL_TREE" >&2; exit 1; }
+  GIT_TOP="$(git rev-parse --show-toplevel)" || exit 1
+  [ "$GIT_TOP" = "$SPUR_TREE" ] || { echo "toplevel mismatch: expected $SPUR_TREE, got $GIT_TOP" >&2; exit 1; }
+  ACTUAL_BRANCH="$(git branch --show-current)"
+  [ "$ACTUAL_BRANCH" = "$SPUR_BRANCH" ] || { echo "branch mismatch: expected $SPUR_BRANCH, got $ACTUAL_BRANCH" >&2; exit 1; }
+  exec <resolved-spur-invocation> task show <wbs> --json   # the already-resolved CLI command
+)
+```
+
+Rules (R1):
+
+- **Pin reads as well as writes.** `task show`, `feature show`, `workflow show` and `task check`
+  use the same subshell — a read from the wrong tree is a wrong answer, not a harmless one.
+- **Validate the returned `filePath`.** A pinned `task show --json` must return a `filePath`
+  inside the expected configured corpus/tree. Configured task folders may intentionally live
+  outside the default `docs/tasks` — check membership in the configured folder set, not one
+  literal path.
+- **Prove sections with a fresh pinned read.** After a section write, re-run a pinned
+  `task show <wbs> --json` and assert the new body there; a heading-only grep is not proof of
+  section contents.
+- **Resolve section input/output paths before changing tree.** `--section <name> --from-file
+  <path>`, `answerFile`/`expectFile` and run artifacts are resolved against the confirmed tree
+  (dispatch field 5) before the subshell `cd`s.
+- **Fail closed before writing.** A failed `cd` or any identity mismatch exits nonzero naming
+  expected vs actual, before the CLI runs — there is no designated exit code; consumers read
+  nonzero and the named expected/actual trees. A PWD assertion alone cannot select a tree: `cd`
+  first, then verify the physical path and repository identity.
+- **Native tool cwd options are additive.** A tool-level cwd/`cd` pin may additionally set the
+  call's directory, but never replaces the identity checks above.
+- **Host-only scope.** Engine `shell` actions already bind `context.workdir`
+  (`packages/app/src/workflow/actions/shell.ts:98`) — leave them alone. No service-wide
+  `process.chdir`, no new public flag, no helper framework.
+
+The `spur …` command examples in this driver (run setup, workflow inventory, `task run-link`,
+fingerprint capture, record/done sequencing) abbreviate the pinned subshell form for readability;
+each executes inside the template above with the confirmed tree, branch and resolved invocation
+substituted. A dispatched subagent inherits the same duty: its own tool calls may each start in
+an arbitrary directory, so every shell call the delegate makes re-pins the execution tree with
+the identity supplied in the dispatch payload — never re-derived.
+
+## Chunked implement dispatch contract (cap-limited worker models, task 1066)
+
+Cap-limited worker executors die on monolithic implement briefs: the output cap is consumed by
+one giant thinking block before any file action lands. Recognized failure signature —
+consecutive implement dispatches end with `stopReason=length` and **zero output** (no tool
+call, no file write), optionally with a `contact_supervisor` call mid-death. The trigger is
+the observed signature, never a model name: any executor that exhibits it is treated as
+cap-limited for the rest of the run.
+
+Before dispatching an `implement` stage to a worker executor:
+
+1. **Chunk the brief.** Split the implement scope into small, independent dispatches ordered
+   by dependency (e.g. test cases → doc rewrite → task sections), one bounded objective per
+   dispatch. Never pack the whole task plan into one dispatch.
+2. **Cap thinking.** Instruct the worker to keep every thinking block under ~150 words and act
+   between thoughts; never plan the whole task in one block.
+3. **Fallback ladder.** A worker still dying with the signature: re-chunk the remaining scope
+   smaller once; still failing → execute the stage host-inline (the driver's inline stage
+   fallback) and record the fallback in the run log.
+
+Evidence (2026-10-02, task 1059 implement stage, runall-D63-2ebbd97c): 4/4 single-shot
+implement dispatches died `stopReason=length` on a 16k-output-cap worker; the same scope in
+three chunked dispatches with the thinking cap succeeded 3/3. See the pitfalls 2026-10-02
+entry and `.spur/memory/runs/runall-D63-2ebbd97c.md`.
+
+## Comprehensive-check retention and evidence (R7/R8)
+
 ## Comprehensive-check retention and evidence (R7/R8)
 
 **R7 — comprehensive checks stay at their owning boundaries.** Quick readiness and plan projection are
@@ -248,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
@@ -263,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,
@@ -296,7 +407,8 @@ Action semantics come from the YAML and the workflow action contract:
   `verify-verdict`: verdict `PASS`), `proofBinding: current` is honored against a freshly captured
   proof digest — capture it with `bun "$SETUP_SCRIPT" --fingerprint --task-file <task path>
   [--feature-file <feature path>]`, the same entry point used at Run setup, which prints the engine
-  `sha256:<hex>` digest. Run it from the worktree root (cwd feeds the git-tree half of the digest)
+  `sha256:<hex>` digest. Run it inside a per-call pin subshell for the confirmed execution tree
+  (the cwd feeds the git-tree half of the digest)
   and pass the same `--feature-file` the run folded in — omitting it, or running from elsewhere,
   yields a different digest and the mismatch surfaces later as a refused `run.artifact`
   registration — and the run-scoped review-completion marker exists — then appends one provenance
@@ -314,6 +426,10 @@ Action semantics come from the YAML and the workflow action contract:
 
 **Native-subagent dispatch (R2 eligibility, evaluated before each action):**
 
+Before dispatching an `implement` stage to a worker executor, apply the chunked implement
+dispatch contract (§ Chunked implement dispatch contract): chunk the brief, cap thinking
+blocks, and know the fallback ladder before spending a dispatch.
+
 1. The invocation is one of the two interactive inline full-pipeline surfaces (`dev-run --mode full`
    or sequential `dev-runall`) and the resolved selector is inline — i.e. `--agent` **omitted**
    (0687 R1 default) or `--agent inline` passed explicitly (0687 R2 generalized from omit-only).
@@ -391,7 +507,10 @@ boundary, and a delegate left to re-derive them re-derives them against its own
    that invocation and MUST NOT rely on a bare `spur`: a competing `spur` earlier on the delegate's
    PATH otherwise wins. Setting `SPUR_BIN` alone does **not** change bare-command resolution — only
    using the supplied invocation does. Spur-owned scripted calls take it through the existing
-   `--spur-bin` flag rather than a new mechanism.
+   `--spur-bin` flag rather than a new mechanism. A delegate's tool calls may each start in an
+   arbitrary directory, so every shell call the delegate makes re-pins the execution tree per the
+   **Per-call execution-tree pin** protocol using this supplied identity — never an inherited cwd
+   and never a re-derivation.
 5. The **resolved absolute output path** (`answerFile`/`expectFile`, resolved as above) and the
    **owning stage's artifact contract** — for a verify stage, the compact contract below.
 6. **The implement-stage acceptance-evidence requirement** — for the implement stage and any stage
@@ -526,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"
@@ -590,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
@@ -636,6 +763,8 @@ tasks (0617, 0619) because the sections were hand-written **before** the verdict
    ```bash
    # verdict artifact first (shape: {wbs, verdict, requirements:[{id,status,evidence}], checks:[], source})
    # then the record hop; then re-write Testing/Solution if record's backfill is thinner than intended.
+   # Both calls are per-call pinned (task 1058): the record hop selects the execution tree inside
+   # the same tool call — never through a cwd a previous call happened to leave behind.
    spur task update <wbs> wip --no-lifecycle
    spur task record <wbs> --solution-from-diff --transition testing
    ```

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": {