@gobing-ai/spur 0.3.91 → 0.3.92

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` · `hitl.select` · `agent.run` · `proof.fingerprint` · `run.artifact` · `command.gate`
 
 **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`
@@ -482,7 +509,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

@@ -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: