@gobing-ai/spur 0.3.91 → 0.3.93

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` · `hitl.select` · `agent.run` · `proof.fingerprint` · `run.artifact` · `command.gate`
+**Actions:** `shell` · `note` · `doctor.probe` · `file.read.into-var` · `hitl.confirm` · `hitl.input` · `agent.run` · `proof.fingerprint` · `run.artifact` · `command.gate` · `decide`
 
 **Guards (transitions):** `always` · `shell` · `action-ok` · `contract-violation`
 
@@ -39,8 +39,8 @@ interactive `/sp:dev-run --mode full`, sequential `/sp:dev-runall`, `/sp:dev-ide
 `--agent auto`, parallel batch mode, `spur workflow run`, and `spur agent run` keep the existing
 subprocess path.
 
-The selected project runtime definition — `task-pipeline.yaml` or `idea-pipeline.yaml`, resolved through the two-tier
-project→bundled model (task 0648/0650, never an unbundled runtime path) — remains the sole
+The selected project runtime definition — `task-pipeline.yaml` or `idea-pipeline.yaml`, resolved through the
+project→registered→shared model (ADR-113) — remains the sole
 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.
@@ -69,23 +69,31 @@ the human/native presentation layer — labels are display addresses only, never
 1. Resolve the command inputs, `--auto`, and any explicit `--vars` — **without reading the selected
    YAML yet**. An explicit non-inline executor selection chooses the subprocess workflow path.
 2. Allocate a collision-resistant inline run id (`uuidgen`, with a timestamp/pid fallback), create
-   `.spur/run/`, and use `.spur/run/<run-id>.log` as the run log.
+   `.spur/run/`, and use the two-file run record (task 0927) — append lines to
+   `.spur/run/<run-id>.md` and read machine state from `.spur/run/<run-id>.state.json`.
 3. **Authoritative run identity (task 0804 R1, fail-closed).** Persist the run row through the
    internal delegate before any stage executes — this is what makes bound `run.artifact` record
    accept the inline run (0785 R3):
 
    ```bash
    SETUP_SCRIPT="plugins/sp/scripts/inline-run-setup.ts";
-   [ -f "$SETUP_SCRIPT" ] || SETUP_SCRIPT="$(superskill script path sp inline-run-setup.ts 2>/dev/null)";
+   [ -f "$SETUP_SCRIPT" ] || SETUP_SCRIPT="$(superskill script path sp inline-run-setup.mjs 2>/dev/null)";
    [ -n "$SETUP_SCRIPT" ] && [ -f "$SETUP_SCRIPT" ] && \
      bun "$SETUP_SCRIPT" --run-id "$RUN_ID" --file <selected-pipeline-yaml> \
      || { echo "inline run setup failed closed — checker not found; run 'superskill install sp'" >&2; exit 1; }
    ```
 
-   The delegate resolves the app service from the SPUR_BIN chain, creates-or-attaches the row,
-   and writes `.spur/run/<run-id>-inline-setup.json`. Seed `__runId` and `__definitionDigest`
-   from that file so proof capture and bound registration verify against the persisted identity.
-   A non-zero exit (missing row identity, changed definition, bundle-only install) stops the run —
+   The delegate uses the source app service when the SPUR_BIN chain identifies a checkout;
+   otherwise it loads the generated application bundle shipped with the plugin. Both setup paths
+   obtains the selected definition from the existing CLI `workflow show --format todo --json`
+   projection and revalidates its schema/name/digest before preserving its source layer.
+   Both paths create-or-attach the row,
+   and writes the run-record state `.spur/run/<run-id>.state.json` plus the `.md` run-start
+   header (task 0927; a legacy pre-0927 run keeps its `<run-id>-inline-setup.json` sidecar).
+   Seed `__runId` and `__definitionDigest`
+   from that state so proof capture and bound registration verify against the persisted identity.
+   Bun remains required for SQLite; the Node-runnable installed twin re-enters Bun on PATH.
+   A non-zero exit (missing runtime/bundle, invalid projection, missing row identity, changed definition) stops the run —
    never continue unbound and never fabricate a PASS. (The delegate persists the authoritative
    RUN row only — the 0808 inline record is the registration-equivalent convention below, not a
    setup-time artifact-ledger insert.)
@@ -236,10 +244,19 @@ Action semantics come from the YAML and the workflow action contract:
   actions/guards.
 - `hitl.confirm` — under `profile=auto`, follow the YAML's auto-skip transition. Otherwise pause,
   surface the prompt, and resume from the same state with the operator's answer.
+- `hitl.input` — pause, surface the declared prompt (the agent's operator question, 0933), and
+  resume from the same state with the operator's answer written into the declared var (default
+  `__hitlInput`); the subsequent guards route on answer presence exactly as the engine does.
+  **Host-session exception (0933 R5):** because a host session can talk to the operator
+  directly, do NOT pause the run at `hitl.input` — ask the question in the session, write the
+  answer into the declared var, and continue. The same 2-escalation bound applies: after the
+  bound the ask routes to `failed` like the engine does.
 - `agent.run` — execute the action's input in the host session. Task execution may use the native
   subagent eligibility below; idea/plan never dispatch a native subagent unless the operator
   explicitly requested delegation. Do not call `spur agent run` or re-enter a full pipeline. Preserve the YAML options: capture
-  `answerFile`; assert `expectFile`; enforce `requireDiff` against a pre-action git snapshot,
+  `answerFile`; assert `expectFile`; honor `escalationFile` (a non-empty file after exit 0 means
+  the agent paused on an operator question — treat the attempt as succeeded-with-escalation and
+  skip `requireDiff` for that attempt only); enforce `requireDiff` against a pre-action git snapshot,
   including the task-scope guard; honor declared error policy. `timeoutMs` is recorded as not
   applicable because the host session has no independent kill boundary.
 - `run.artifact` — the engine's ledger registration has **no inline execution surface** (0808 R4).
@@ -253,13 +270,14 @@ Action semantics come from the YAML and the workflow action contract:
   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
-  line to `.spur/run/<run-id>.log` naming the equivalence (artifact kind, path, verdict, digest) and
+  line to `.spur/run/<run-id>.md` naming the equivalence (artifact kind, path, verdict, digest) and
   proceeds to `spur task record`. A failed validation stops at the state and follows the failure
   contract; the step is never silently skipped. Artifact-provenance consumers read that run-log
   line on the inline path — there is no ledger row. The validation also includes **run/definition
   identity agreement from authoritative evidence** (task 0809 R4): the verdict's `proof.runId` and
-  `proof.definitionDigest` must agree with the setup artifact `.spur/run/<run-id>-inline-setup.json`
-  and the persisted run row; if that identity is absent or conflicts, STOP — recreating a row is
+  `proof.definitionDigest` must agree with the run-record state `.spur/run/<run-id>.state.json`
+  (legacy pre-0927 runs: `<run-id>-inline-setup.json`) and the persisted run row; if that identity
+  is absent or conflicts, STOP — recreating a row is
   not a diagnostic operation. The app-service bound-artifact fixture (which writes a real engine
   ledger row) is service-level test evidence for this identity mechanics, not evidence that the
   inline host writes a ledger.
@@ -369,6 +387,14 @@ A behavioral AC marked MET requires executable evidence (test | command);
 static-ref or llm-judge alone cannot carry it.
 ```
 
+**AC table shape (0948 R9).** The AC table must be exactly **4 columns** and **cell 3 must hold a
+single evidence-type token** from the allowlist above. The token is *isolated* — never merged or
+concatenated with another token or with prose (`static-reftest` is a lint failure, not a shorthand
+for "static-ref + test"). Evidence detail belongs in cell 4. The verify-answer linter rejects a
+merged token, and `spur task verdict` then derives the wrong artifact — this exact shape failed the
+0926 verify lint once before it was canonicalized, so it is stated here rather than left implicit in
+the header row.
+
 **Review-stage artifact contract.** A review handoff carries the Review output contract owned by
 `plugins/sp/agents/super-reviewer.md` — native `P1 (blocker)` / `P2 (major)` / `P3 (minor)` /
 `P4 (advisory)` priority cells and section-relative headings — **not** the verify answer schema.
@@ -429,7 +455,7 @@ or an operator decision returns a blocker; the host pauses at the current state
 subagent cannot approve, infer consent, or recursively invoke the full pipeline.
 
 After every successful inline `agent.run` action append exactly one provenance line (inline or
-subagent form above) to `.spur/run/<run-id>.log`, where `<id>` is the current YAML state id. Also
+subagent form above) to `.spur/run/<run-id>.md`, where `<id>` is the current YAML state id. Also
 log start/failure and the ignored timeout value so an inline run remains auditable without
 fabricating an `AgentRunTracedResult`.
 
@@ -441,7 +467,8 @@ in one file and makes the run unauditable (task 0726 mixed both forms).
 
 ## Structured trace emission (ADR-117, task 0868)
 
-`.spur/run/<run-id>.log` is a human convenience, **not the record of truth**. A run's
+`.spur/run/<run-id>.md` is the human half of the two-file run record — evidence, **not the record
+of truth**. A run's
 observability is a property of the run, so the inline driver owes the same structured trace the
 engine subprocess writes — and it owes it through the **same writer**, never a parallel
 implementation. The shared writer is `WorkflowActionTraceWriter`
@@ -470,6 +497,24 @@ The driver reaches it through the existing run delegate (`$SETUP_SCRIPT`,
   (0887 R8), so `completed_at − started_at == duration_ms` exactly; a back-date failure is
   recorded (`action.backdate`) and never affects the run.
 
+- **A `decide` action (0941)** — the driver never executes the DecisionMaker itself; it delegates
+  to the same app runner the engine registers, which writes the resultFile row (schemaVersion 1)
+  and returns the decision, then the delegate records the `action_runs` row (`kind=decide`)
+  through the same writer as every other action:
+
+  ```bash
+  bun "$SETUP_SCRIPT" --decide --run-id "$RUN_ID" --node <state-id> --options-json <options-file>
+  ```
+
+  The options JSON mirrors the YAML `decide` options (`id`, `method: choice|noul`, `question`,
+  `choices`/`default`, optional `evidence`, optional `minConfidence`, `resultFile`); paths resolve
+  against the project workdir. The decision never pauses and never fails the run for model
+  problems: a degraded outcome (feature switch off, no backend, error, timeout, low confidence)
+  prints `ok:true` with `degraded:true`, the declared `reason`, and `value = default`, and exits
+  `0` — route on the resultFile's `.value` with the declared file guards. Only an invalid options
+  schema exits `1` (fail closed), and usage errors exit `2`. The `action_runs` trace row is
+  best-effort exactly like `--action`.
+
 - **At the run's declared terminal state** — before the driver reports the run complete, close the
   row so a successful inline run is never left non-terminal for `spur workflow clean` to reap as
   stale:
@@ -482,7 +527,7 @@ The driver reaches it through the existing run delegate (`$SETUP_SCRIPT`,
   state is `done`; a run halted by a failing action under its error policy is `failed`.
 
 **Best-effort at the action boundary only (ADR-117).** An `--action` persistence failure is
-recorded — the delegate appends a `trace-emission-failed` line to `.spur/run/<run-id>.log` and
+recorded — the delegate appends a `trace-emission-failed` line to `.spur/run/<run-id>.md` and
 prints `{"ok":false}` on stdout — and the run continues to its declared terminal state; the
 delegate exits `0` for that outcome and the driver must never treat an emission failure as a run
 failure, retry it in a loop, or substitute a hand-written row. The run-row closure (`--close`) is

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

@@ -198,11 +198,11 @@ task Design.
 order (§4.5 rule 5 / sync trigger **T9**):
 
 1. **Satellite first.** Write/update `docs/design/<slug>.md`. `<slug>` is the stable grep anchor —
-   derive it from the feature name (kebab-case), and **reuse the existing slug** on re-runs. Capture
-   the chosen approach + one-line reason, rejected alternatives, key interface/type **signatures**
-   (not bodies), invariants, and the surface it touches. Do **not** restate the satellite file format
-   here — follow the shape of existing satellites (`docs/design/server-side-adjustment-design.md`,
-   `workflow-observability.md`).
+   derive it from the feature name (kebab-case), and **reuse the existing slug** on re-runs. For a
+   new file use [document-authoring.md](document-authoring.md) and its design template; for an
+   existing file preserve its headings and anchors. Capture the chosen approach + one-line reason,
+   rejected alternatives, key interface/type **signatures** (not bodies), invariants, and the
+   surface it touches.
 2. **Index second.** Add or update the satellite's row in `docs/04_DESIGN.md §0` (the `| Satellite |
    Area | Status |` table) — pointer + one-line area + status only, never a restatement of the body.
 
@@ -277,6 +277,11 @@ design, plan, acceptance criteria, decisions, dependencies and premises present
 non-placeholder so `spur task check <wbs> --json` exits 0. Write planning sections only, through
 `spur task update <wbs> --section <Name> --from-file <file>` — never Solution, Testing, Review
 or History. Record one checklist row per id, with concrete evidence of how you verified it.
+The `premises` row passes only when each material premise was read against the current tree:
+identify each material premise in the task Background, open the cited file at the cited line and
+confirm the claim, then record the evidence as verified `path:line` citations — handoff-finalize
+lints the row and degrades the task to ready refine when the evidence carries no citation or
+cites a missing file or an out-of-range line.
 Compute the planning digest with the project's own implementation when this is a monorepo
 checkout — resolve the file with `spur task path <wbs> --json`, then run:
 

package/plugins/sp/skills/spur-dev/templates/design.md

@@ -0,0 +1,31 @@
+---
+kind: design
+title: <specific non-UI contract or system design>
+status: proposed
+created_at: YYYY-MM-DD
+updated_at: YYYY-MM-DD
+related: []
+tags: []
+---
+
+# <Specific non-UI contract or system design>
+
+## 1. Issue and scope
+
+<Specific issue or tasks this design addresses, observed impact, boundaries, and whether the solution is proposed or current. Link the owning records.>
+
+## 2. Context and constraints
+
+<Relevant current behavior, evidence for the issue, and constraints the solution must respect. Link to 03 for wider architecture.>
+
+## 3. Solution
+
+<Chosen approach and how it resolves the issue. Show ownership, boundaries, and flow; distinguish proposed behavior from implemented behavior.>
+
+## 4. Contract and compatibility
+
+<Observable inputs, outputs, defaults, errors, invariants, edge cases, and migration behavior needed to implement or use the solution. Omit inapplicable parts.>
+
+## 5. Tradeoffs and open questions
+
+<Why this solution was chosen, material costs or alternatives, and unresolved questions or follow-up. Link ADR decisions instead of restating them.>

package/plugins/sp/skills/spur-dev/templates/plan.md

@@ -0,0 +1,32 @@
+---
+kind: plan
+title: <specific title>
+status: draft
+created_at: YYYY-MM-DD
+updated_at: YYYY-MM-DD
+related: []
+tags: []
+---
+
+# <Specific title>
+
+## 1. Objective and outcome
+
+<Issue or tasks this plan addresses, intended result, scope, and how completion will be recognized. Link the owning feature or tasks.>
+
+## 2. Premises and dependencies
+
+<Facts, assumptions, prerequisites, decisions, and blockers that affect the sequence. Link evidence; mark unverified premises.>
+
+## 3. Execution sequence
+
+1. <Action, prerequisite, and tangible output or checkpoint. Name an owner when coordination matters.>
+2. <Next action. Show dependencies and safe parallel work explicitly.>
+
+## 4. Risks and verification
+
+<What could change the sequence, the fallback or decision point, and how the intended result will be verified.>
+
+## 5. Follow-up
+
+<Handoff, remaining actions, and deferred work with owners or links when known. Omit if none.>

package/plugins/sp/skills/spur-doctor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spur-doctor
-description: "Evaluate spur artifacts from read-only CLI evidence — tasks, features, rules, workflows, agent specs — reflect over sp:history-anatomy findings, and return a proposal table. Diagnoses spur artifacts, not runtime environments (that is spur agent doctor). Triggers: check artifact health, propose evolution, reflect over history findings."
+description: "Evaluate spur artifacts and plan/design Markdown from read-only evidence, reflect over sp:history-anatomy findings, and return a proposal table. Diagnoses artifacts, not runtime environments (that is spur agent doctor). Triggers: check artifact health, propose evolution, review legacy documents."
 license: Apache-2.0
 version: 1.0.0
 metadata:
@@ -26,16 +26,19 @@ see_also:
 # sp:spur-doctor — evaluate spur artifacts and propose changes
 
 One cross-noun method (ADR-114, [spur artifact evolution](../../../../docs/design/spur-artifact-evolution.md)
-§2): gather **read-only CLI evidence** about tasks, features, rules, workflows and agent specs,
-**reflect** over `sp:history-anatomy` findings, and return a **proposal table**. It diagnoses spur
-**artifacts** — definitions, rules, corpus records — not runtime environments: whether an agent
+§2): gather **read-only evidence** about tasks, features, rules, workflows, agent specs, and
+plan/design Markdown; **reflect** over `sp:history-anatomy` findings; and return a
+**proposal table**. It diagnoses spur artifacts — definitions, rules, corpus records and documents —
+not runtime environments: whether an agent
 binary, host session or tool install is healthy is `spur agent doctor`'s job, not this skill's.
 
 ## Read-only invariant
 
-The doctor **writes nothing and names no mutating verb**. It performs no task, feature, rule or
-workflow write — the operator accepts rows and `sp:spur-composer`
-([../spur-composer/SKILL.md](../spur-composer/SKILL.md)) applies them. A caller that wants a
+The doctor **writes nothing and names no mutating verb**. It performs no task, feature, rule,
+workflow or document write. The operator accepts rows; `sp:spur-composer`
+([../spur-composer/SKILL.md](../spur-composer/SKILL.md)) applies corpus rows, while a document
+author applies plan/design rows using the
+[spur-dev authoring guide](../spur-dev/references/document-authoring.md). A caller that wants a
 record saves the returned table under `docs/reports/`; the doctor creates no artifact store.
 
 - **History enters only through `sp:history-anatomy` findings.** Raw history records stay out
@@ -55,9 +58,51 @@ record saves the returned table under `docs/reports/`; the doctor creates no art
 | workflow | `spur workflow validate --json` (findings by `level`), `node "$(superskill script path sp workflow-step-profile.mjs)" <workflow> --json` |
 | agent spec | `spur agent list --specs --json` |
 | history | A `sp:history-anatomy` report ([../history-anatomy/SKILL.md](../history-anatomy/SKILL.md)), never raw history records |
+| plan/design Markdown | The file itself, the project constitution, the relevant spur-dev template, and inbound index/links; no new CLI needed |
 
 Every row of a proposal cites the evidence it rests on. No anchor, no proposal.
 
+## Legacy plan and design review
+
+Enumerate `docs/plans/*.md` and `docs/design/*.md` with `rg --files` and sort the paths. Include
+every Markdown path in the review; JSON and other files are outside this contract. For a large set,
+freeze the list and split it into named path groups by record type (for example
+`docs/plans/*-brainstorm.md`, other plans, designs), at most ~40 files each, and combine their
+coverage lists. Read each file and the project constitution before judging it. Report scanned paths
+and counts of proposals and no-ops, so an omitted file is visible.
+
+Compare each plan with the [plan template](../spur-dev/templates/plan.md) and each design with the
+[design template](../spur-dev/templates/design.md), using the
+[authoring guide](../spur-dev/references/document-authoring.md) for meaning. Look for missing or
+unsupported `kind`, title, status, dates, material related links or useful tags; unclear objective,
+premises, execution sequence or follow-up in a plan; unclear issue, context, solution, contract or
+compatibility in a design; and a missing `04_DESIGN.md` pointer for a design satellite.
+These are **review prompts**, not format errors. Keep specialized sections required by a producing workflow.
+
+Judge metadata against the authoring guide's **frontmatter vocabulary** and **legacy metadata
+upgrade** rules, so every row in a batch makes the same choice: the same key mapping, `title` from
+the H1, `related` from owner keys or linking feature/task records, `created_at` source order
+(legacy `date`, filename prefix, first commit, else flag), status mapping only when unambiguous,
+and tags in record-type → feature → area order from the shared list. A row whose status or tag needs
+judgment says so in `change` instead of picking a value. Never propose renumbering or renaming a
+legacy heading.
+
+Propose only evidence-backed, useful edits. A proposal names the exact file and heading or
+frontmatter field, cites a line and the governing rule, and says what can be inferred and what
+needs an operator answer. Preserve filenames, anchors, original dates, decisions and historical
+status. Do not silently promote a proposal to current behavior, invent metadata, or rewrite a
+whole file to fit a template. A conforming or intentionally specialized file is a no-op.
+
+The `apply` cell for a document row points to the spur-dev authoring guide; the author edits an
+accepted row in place, then runs `sp:doc-evolve` sync-check for affected key documents and verifies
+links, headings, frontmatter and the `04` index when applicable. No bulk conversion or strict
+validator is required for old files.
+
+For a batch, the caller saves each group's table as
+`docs/reports/YYYY-MM-DD-<group>-doc-upgrade-review.md`. After the operator accepts rows, the author
+applies one group's metadata-only rows together and commits them as one change; body restructuring
+rows stay per file. Flagged rows wait for the operator's answer.
+
 ## Workflow step profile and cache-window flags
 
 The step profile (`plugins/sp/scripts/workflow-step-profile`, ADR-065 plugin entrypoint) reads
@@ -114,25 +159,26 @@ Return one row per actionable finding, with exactly these columns:
 | Column | Content |
 | --- | --- |
 | `key` | The finding key, or `<noun>:<id>:<check>` for an artifact finding |
-| `evidence` | The CLI output or report section the row rests on |
+| `evidence` | CLI output, report section, or document path and line the row rests on |
 | `action` | One action class from the reflection map (or the per-noun evaluation) |
 | `change` | The proposed change, in one line |
-| `apply` | The `spur` verb or composer procedure that lands it |
+| `apply` | The `spur`/composer route for corpus rows or the spur-dev authoring guide for document rows |
 | `verify` | The evidence to re-run after applying |
 
 Rules:
 
-- The `apply` route is always a `spur` verb or a gated composer step — never a raw file edit this
-  skill performs. Shared-workflow rows route through the composition ladder's shared step.
+- Corpus `apply` routes use a `spur` verb or gated composer step; document rows use the spur-dev
+  authoring guide. The doctor itself never edits either surface. Shared-workflow rows route
+  through the composition ladder's shared step.
 - A `task` row carries the finding `key` in the task body (the history-anatomy handoff route).
 - Rows are proposals only. No applied change, diff, or command output claimed as run.
 
 ## What this skill is not
 
-- **Not the applier.** `sp:spur-composer` applies accepted rows; this skill performs no
-  task/feature/rule/workflow write.
+- **Not the applier.** `sp:spur-composer` applies accepted corpus rows and document authors apply
+  accepted document rows; this skill performs no write.
 - **Not a runtime doctor.** Environment, binary and session readiness belong to
-  `spur agent doctor`; this skill diagnoses spur artifacts from CLI evidence.
+  `spur agent doctor`; this skill diagnoses artifacts from read-only evidence.
 - **Not a history interpreter.** Findings come from `sp:history-anatomy` reports, never from raw
   history records.
 - **Not a loop.** Recurring evolution passes belong to `sp:super-planner` or a workflow.

package/schemas/state-machine-workflow.schema.json

@@ -135,6 +135,10 @@
                         "type": "string",
                         "minLength": 1
                     },
+                    "terminalReason": {
+                        "type": "string",
+                        "description": "Closed terminal-reason enum declared when this edge finalizes the run (0937 R3; required for edges into failureStates)."
+                    },
                     "description": {
                         "type": "string"
                     },