@gobing-ai/spur 0.2.5 → 0.2.9

package/spur-cli/config/workflows/planning-pipeline.yaml

@@ -0,0 +1,166 @@
+$schema: "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
+# Planning pipeline — front-half of the development workflow (task 0088, design §6).
+#
+# Orchestration is configuration (ADR-022 / §3.2): this is YAML over the existing
+# dual-workflow engine — zero new engine code. The pipeline automates steps 3–6 of the
+# ideation→implementation chain: phasing → feature-ID derivation → design-doc generation →
+# design-doc approval. It terminates at a drafted feature list and hands off to sp:spur-dev
+# (steps 7–12), which is already shipped and unchanged.
+#
+# Every authoritative-doc touch invokes sp:doc-evolve to honor the constitution §5 sync triggers.
+# Derived docs (docs/design/*, docs/features/*, 05_FEATURES index) are auto-written; high-risk
+# authoritative edits (02_ROADMAP phasing, 04_DESIGN index) are STAGED to docs/plans/ for human
+# commit (Q3 — hybrid by risk).
+#
+# Shape: phasing(HITL) → feature-id → design-gen → design-approval(HITL) → handoff
+#        (phasing/design-approval skipped when profile=auto).
+#
+# Vars (passed as a JSON object via `--vars`):
+#   slug     — the design-doc slug, e.g. `--vars '{"slug":"auth-migration"}'`
+#   profile  — set `--vars '{"profile":"auto"}'` to skip the HITL gates (Q4)
+#   feature  — optional parent feature ID for derivation context
+#
+# Seeded by `spur init`; adapt the agent.run inputs to your project's command set.
+
+"$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
+kind: state-machine
+name: planning-pipeline
+description: "Front-half planning pipeline (phasing → feature-ID → design-gen → design-approval → handoff)"
+iterationBound: 20
+initialState: start
+terminalStates:
+  - handoff
+  - cancelled
+vars:
+  slug: "draft"
+  profile: "interactive"
+  feature: ""
+
+states:
+  - id: start
+    description: >
+      Entry pass-through. Routes to the phasing HITL gate (interactive) or straight to
+      feature-id (profile=auto), so the phasing onEnter hitl.confirm only fires when a
+      human is in the loop. No actions — a pure routing node.
+
+  - id: phasing
+    description: >
+      Decide whether this requirement needs a new phase in 02_ROADMAP. The HITL gate asks
+      the operator; if a new phase is needed, the edit is STAGED to docs/plans/ (never
+      auto-written — Q3). Under profile=auto this state is never entered (start routes
+      around it straight to feature-id).
+    onEnter:
+      - kind: hitl.confirm
+        options:
+          prompt: "Does this requirement need a new phase in 02_ROADMAP? (Stage the edit if yes.)"
+
+  - id: feature-id
+    description: >
+      Derive the feature ID by scanning docs/features + 05_FEATURES for the parent and
+      allocating the child id (same rule as `spur feature create`). Result is recorded for
+      the design-doc generation step. Invokes sp:doc-evolve if 05_FEATURES index needs a
+      placeholder row.
+    onEnter:
+      - kind: agent.run
+        options:
+          input: "Derive the feature ID for ${vars.slug} (scan docs/features + docs/05_FEATURES.md; allocate child id under parent ${vars.feature}). Record the derived id."
+
+  - id: design-gen
+    description: >
+      Author the design doc at docs/design/${vars.slug}.md from the brainstormed feature
+      draft (docs/plans/${vars.slug}-drafted.md). ADVISORY: use the highest-quality coding
+      agent available (Q8 — tier rule is guidance, not enforced). Invokes sp:doc-evolve to
+      stage the 04_DESIGN index edit (never auto-write the authoritative index — Q3).
+    onEnter:
+      - kind: agent.run
+        options:
+          input: "Author the design doc at docs/design/${vars.slug}.md from docs/plans/${vars.slug}-drafted.md. Invoke sp:doc-evolve to stage the 04_DESIGN index edit."
+
+  - id: design-approval
+    description: >
+      HITL gate — the highest-leverage gate in the pipeline. Loop until the operator
+      approves the design doc. Under profile=auto this state is never entered (design-gen
+      routes around it straight to handoff).
+    onEnter:
+      - kind: hitl.confirm
+        options:
+          prompt: "Approve the design doc at docs/design/${vars.slug}.md? (Loop back to design-gen for revisions.)"
+
+  - id: handoff
+    description: >
+      Terminal — design doc approved; the drafted feature list is ready. Hand off to
+      sp:spur-dev (steps 7–12), which starts at `spur feature create`. The seam is the
+      drafted-feature-list file at docs/plans/${vars.slug}-drafted.md.
+
+  - id: cancelled
+    description: Terminal — planning abandoned by the operator.
+
+transitions:
+  # ── start: route AROUND the phasing HITL gate when profile=auto ──
+  # Auto-skip guard tried FIRST: under profile=auto the run goes straight to
+  # feature-id and never ENTERS phasing (whose onEnter hitl.confirm would block).
+  # Otherwise fall through to phasing for the human gate.
+  - from: start
+    to: feature-id
+    description: profile=auto — skip the phasing HITL gate.
+    guard:
+      kind: shell
+      options:
+        command: 'test "${vars.profile}" = auto'
+  - from: start
+    to: phasing
+    description: Interactive — enter the phasing HITL gate.
+    guard:
+      kind: always
+
+  # ── phasing: HITL gate (reached only when profile != auto) ──
+  - from: phasing
+    to: feature-id
+    description: Phasing decided — proceed to feature-ID derivation.
+    guard:
+      kind: always
+  - from: phasing
+    to: cancelled
+    description: Operator cancelled planning.
+    guard:
+      kind: always
+
+  # ── linear body ──
+  - from: feature-id
+    to: design-gen
+    description: Feature ID derived — generate the design doc.
+    guard:
+      kind: always
+
+  # ── design-gen → design-approval, OR skip the HITL gate when profile=auto ──
+  # Auto-skip guard tried FIRST: under profile=auto, route straight to handoff
+  # without entering design-approval (whose onEnter hitl.confirm would block).
+  - from: design-gen
+    to: handoff
+    description: profile=auto — skip the design-approval HITL gate, hand off directly.
+    guard:
+      kind: shell
+      options:
+        command: 'test "${vars.profile}" = auto'
+  - from: design-gen
+    to: design-approval
+    description: Design doc drafted — gate on human approval.
+    guard:
+      kind: always
+
+  # ── design-approval: HITL gate (reached only when profile != auto) ──
+  - from: design-approval
+    to: handoff
+    description: Design approved — hand off to sp:spur-dev.
+    guard:
+      kind: always
+  - from: design-approval
+    to: design-gen
+    description: Rework — operator requested design revisions.
+    guard:
+      kind: always
+  - from: design-approval
+    to: cancelled
+    description: Operator cancelled planning.
+    guard:
+      kind: always

package/spur-cli/config/workflows/task-lifecycle.yaml

@@ -0,0 +1,128 @@
+$schema: "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
+"$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
+kind: state-machine
+name: task-lifecycle
+description: >
+  Task lifecycle FSM (design §2.3, §5.1). States are the canonical TaskStatus
+  vocabulary (DD-01); transitions encode the §2.3 graph; guards invoke
+  `${vars.spurBin} task check` at the wip→testing and testing→done placements.
+  `done` is re-enterable (reopen with a warning); `cancelled` is terminal.
+  Guard commands reference the check verb (0051) — structural validation passes
+  today, behavioral wiring activates as the verb ships. Unconditional transitions
+  use the `always` guard (externally-driven via `requestTransition`, not
+  auto-advance).
+initialState: backlog
+terminalStates:
+  - cancelled
+vars:
+  spurBin: 'spur'
+  wbs: '0000'
+
+states:
+  - id: backlog
+    description: Initial state — task exists but has not been triaged.
+  - id: todo
+    description: Triaged and ready to start.
+  - id: wip
+    description: Actively being worked on.
+  - id: testing
+    description: Implementation complete; under test/verification.
+  - id: blocked
+    description: Impediment; work suspended.
+  - id: done
+    description: Completed. Re-enterable (reopen with warning + mandatory History entry).
+  - id: cancelled
+    description: Terminal — abandoned.
+
+transitions:
+  # Forward path: backlog → todo → wip → testing → done
+  - from: backlog
+    to: todo
+    description: Triage — task is ready to start
+    guard:
+      kind: always
+  - from: todo
+    to: wip
+    description: Start work
+    guard:
+      kind: always
+  - from: wip
+    to: testing
+    description: Implementation complete; enter testing
+    guard:
+      kind: shell
+      options:
+        command: '${vars.spurBin} task check ${vars.wbs}'
+  - from: testing
+    to: done
+    description: Testing passed — task complete
+    guard:
+      kind: shell
+      options:
+        command: '${vars.spurBin} task check ${vars.wbs} --strict-core'
+
+  # Reopen: done → wip (warned, mandatory History entry)
+  - from: done
+    to: wip
+    description: Reopen — work resumed (warning + mandatory History entry)
+    guard:
+      kind: always
+
+  # Blocked ↔ (todo, wip, testing) — bidirectional from/to active states
+  - from: todo
+    to: blocked
+    description: Blocked by an impediment
+    guard:
+      kind: always
+  - from: blocked
+    to: todo
+    description: Impediment resolved — back to todo
+    guard:
+      kind: always
+  - from: wip
+    to: blocked
+    description: Blocked by an impediment
+    guard:
+      kind: always
+  - from: blocked
+    to: wip
+    description: Impediment resolved — back to wip
+    guard:
+      kind: always
+  - from: testing
+    to: blocked
+    description: Blocked by an impediment
+    guard:
+      kind: always
+  - from: blocked
+    to: testing
+    description: Impediment resolved — back to testing
+    guard:
+      kind: always
+
+  # Cancel: any non-terminal → cancelled (terminal)
+  - from: backlog
+    to: cancelled
+    description: Cancel task
+    guard:
+      kind: always
+  - from: todo
+    to: cancelled
+    description: Cancel task
+    guard:
+      kind: always
+  - from: wip
+    to: cancelled
+    description: Cancel task
+    guard:
+      kind: always
+  - from: testing
+    to: cancelled
+    description: Cancel task
+    guard:
+      kind: always
+  - from: blocked
+    to: cancelled
+    description: Cancel task
+    guard:
+      kind: always

package/spur-cli/config/workflows/task-pipeline.yaml

@@ -0,0 +1,244 @@
+$schema: "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
+# Task execution pipeline — one run per execution attempt of a task (design §6).
+#
+# Orchestration is configuration (ADR-022 / §3.2): this is YAML over the existing
+# dual-workflow engine — zero new engine code. The pipeline NEVER touches files
+# directly — `record` writes via `spur task update --section`, and status moves go
+# through the normal `spur task update <wbs> <status>` verb so the lifecycle guards
+# (0055) apply identically. Run linkage is written to `task_run_links` (kind=pipeline).
+#
+# Shape: precheck → implement → test → review → approve(HITL) → verify → record → done
+#        (precheck failure short-circuits to `failed`).
+#
+# Vars (passed as a JSON object via `--vars`):
+#   wbs      — the task WBS (required), e.g. `--vars '{"wbs":"0042"}'`
+#   profile  — set `--vars '{"profile":"auto"}'` to skip the HITL approve gate (R4)
+#
+# Seeded by `spur init`; adapt the agent.run inputs to your project's command set.
+
+"$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
+kind: state-machine
+name: task-pipeline
+description: "Standard task execution pipeline (precheck → implement → test → review → approve → verify → record → done)"
+iterationBound: 20
+initialState: precheck
+terminalStates:
+  - done
+  - failed
+vars:
+  wbs: "0000"
+  profile: "standard"
+  # PATH-independent spur invocation for shell guards/actions. The CLI overrides this
+  # at run start (resolveSpurBin); the literal default is a safe fallback so direct/dry
+  # runs and `workflow validate` resolve the template. (See AGENTS.md / ADR-026.)
+  spurBin: "spur"
+  # Agent the pipeline's agent.run steps invoke. Override per run with
+  # `--vars '{"agent":"claude"}'`. Pinned (not left to the AiRunner's <default>
+  # selection) so a broken/misconfigured agent on the box can't silently capture the run.
+  agent: "omp"
+  # Step-level timeout for agent.run steps in milliseconds. A timed-out agent
+  # subprocess is killed (not abandoned) and the step fails → pipeline routes to
+  # `failed`. Override per run with `--vars '{"stepTimeoutMs":120000}'`.
+  stepTimeoutMs: "600000"
+
+states:
+  - id: precheck
+    description: >
+      Pre-flight structural validation. The precheck→implement guard runs
+      `spur task check <wbs>`; a failure routes to `failed` (blocked report).
+    onEnter:
+      - kind: note
+        options:
+          # R4 task_run_links linkage (kind=pipeline) is written by a WorkflowService
+          # hook at run start — see the 0062 follow-up note; there is no link-writing
+          # CLI verb to call from a shell step, so it cannot live in pure YAML.
+          message: "Pipeline start for task ${vars.wbs}."
+
+  - id: implement
+    description: >
+      Run agent-driven implementation via /sp:dev-run --mode implement, THEN move the
+      task to `wip` via the normal verb. The lifecycle transition fires AFTER the
+      implement agent.run succeeds — onEnter runs in declaration order and the default
+      'fail' policy halts the sequence (routing the run to `failed`) if the agent.run
+      fails or times out, so a halted implement never leaves the task at `wip` with an
+      empty Solution (the F3 half-state). The `--no-lifecycle` flag is correct here: the
+      pipeline owns this transition; the FSM guard would otherwise re-run `spur task
+      check`, which is precheck's job.
+      NOTE: this step must NOT call /sp:dev-run in full mode (the default) —
+      that command DRIVES this pipeline, so calling it here recurses.
+      --mode implement is the single-step implement entry.
+    onEnter:
+      - kind: agent.run
+        options:
+          agent: ${vars.agent}
+          input: /sp:dev-run --mode implement ${vars.wbs} --auto
+          timeoutMs: ${vars.stepTimeoutMs}
+      - kind: shell
+        options:
+          command: "${vars.spurBin} task update ${vars.wbs} wip --no-lifecycle"
+
+  - id: test
+    description: Test execution + coverage via /sp:dev-unit.
+    onEnter:
+      - kind: agent.run
+        options:
+          agent: ${vars.agent}
+          input: /sp:dev-unit ${vars.wbs} --auto
+          timeoutMs: ${vars.stepTimeoutMs}
+
+  - id: review
+    description: SECUA-framework code review via /sp:dev-review (Security, Efficiency, Correctness, Usability, Architecture).
+    onEnter:
+      - kind: agent.run
+        options:
+          agent: ${vars.agent}
+          input: /sp:dev-review ${vars.wbs} --auto
+          timeoutMs: ${vars.stepTimeoutMs}
+
+  - id: approve
+    description: >
+      Human-in-the-loop approval gate. Under `profile=auto` this state is never entered
+      (review routes around it straight to verify). NOTE: to make this state PAUSE for `spur workflow continue`
+      (E3), add `pause: true` here — deferred until the globally-installed `@gobing-ai/spur`
+      schema (currently a stale 0.2.5 that lacks the `pause` field) is refreshed, so
+      full `spur workflow validate` stays green. The workspace schema already supports it.
+    onEnter:
+      - kind: hitl.confirm
+        options:
+          prompt: "Approve task ${vars.wbs} to proceed to verification?"
+
+  - id: verify
+    description: >
+      Functional verification (BDD + traceability) via /sp:dev-verify. The agent's
+      captured answer is written to `.spur/run/<wbs>-verify-answer.txt`; a deterministic
+      shell step then derives the verdict and writes the gate artifact
+      `.spur/run/<wbs>-verdict.json` (so the completion gate reads a real verdict, not
+      agent discretion — R9). The verdict is PASS only if the agent both reported PASS
+      AND `spur task check` passes; otherwise FAIL.
+    onEnter:
+      - kind: agent.run
+        options:
+          agent: ${vars.agent}
+          input: /sp:dev-verify ${vars.wbs} --auto --fix all
+          timeoutMs: ${vars.stepTimeoutMs}
+          answerFile: .spur/run/${vars.wbs}-verify-answer.txt
+      - kind: shell
+        options:
+          command: "${vars.spurBin} task verdict ${vars.wbs} --from-answer .spur/run/${vars.wbs}-verify-answer.txt"
+
+  - id: record
+    description: >
+      Record pipeline results into the task file via `spur task record` —
+      Testing/Review from the verdict, Solution backfilled from git diff as a
+      safety net, optional transition to testing. A single verb replaces the
+      previous ~50 lines of embedded shell (0108; ADR-022).
+    onEnter:
+      - kind: shell
+        options:
+          command: "${vars.spurBin} task record ${vars.wbs} --solution-from-diff --transition testing"
+
+  - id: done
+    description: >
+      Terminal — task executed, verified, and recorded. The `record → done`
+      guard runs `spur task check` before certifying; a genuinely non-compliant
+      task routes to `failed` instead of a silent bad `done`.
+    onEnter:
+      - kind: shell
+        options:
+          command: "${vars.spurBin} task update ${vars.wbs} done --no-lifecycle"
+      - kind: note
+        options:
+          message: "Pipeline complete for task ${vars.wbs} (done gate cleared)."
+
+  - id: failed
+    description: Terminal — precheck (or a gated step) failed; reported, not advanced.
+
+transitions:
+  # ── precheck: shell guard runs `spur task check`; pass → implement, fail → failed ──
+  - from: precheck
+    to: implement
+    description: Precheck passed — begin implementation.
+    guard:
+      kind: shell
+      options:
+        command: "${vars.spurBin} task check ${vars.wbs}"
+  - from: precheck
+    to: failed
+    description: Precheck failed — report and stop (no fall-through to implement).
+    guard:
+      kind: shell
+      options:
+        command: '! ${vars.spurBin} task check ${vars.wbs}'
+
+  # ── linear body ──
+  - from: implement
+    to: test
+    description: Implementation done — run tests.
+    guard:
+      kind: always
+  - from: test
+    to: review
+    description: Tests done — run review.
+    guard:
+      kind: always
+  # ── review → approve, OR skip the HITL gate entirely when profile=auto (R4) ──
+  # Declaration order matters: the auto-skip guard is tried FIRST, so under
+  # profile=auto the run routes straight to verify and never ENTERS approve
+  # (whose onEnter hitl.confirm would otherwise block). Otherwise fall through
+  # to approve for the human gate.
+  - from: review
+    to: verify
+    description: profile=auto — skip the human approval gate, go straight to verify.
+    guard:
+      kind: shell
+      options:
+        command: 'test "${vars.profile}" = auto'
+  - from: review
+    to: approve
+    description: Review done — gate on human approval.
+    guard:
+      kind: always
+
+  # ── approve: HITL gate (reached only when profile != auto) ──
+  - from: approve
+    to: verify
+    description: Approved — proceed to verification.
+    guard:
+      kind: always
+  # ── completion gate (the YAML-native replacement for rd3's default-on --postflight-verify) ──
+  # The verify step emits .spur/run/<wbs>-verdict.json. Only `verdict: PASS` clears
+  # the gate to `record`; any non-PASS (PARTIAL/FAIL), a missing file, or malformed
+  # JSON routes to `failed`. Declaration order: PASS guard tried FIRST.
+  - from: verify
+    to: record
+    description: Verification verdict is PASS — record results and proceed to done.
+    guard:
+      kind: shell
+      options:
+        command: 'test "$(jq -r .verdict .spur/run/${vars.wbs}-verdict.json 2>/dev/null)" = PASS'
+  - from: verify
+    to: failed
+    description: Verification verdict is not PASS (PARTIAL/FAIL/missing) — block before done.
+    guard:
+      kind: shell
+      options:
+        command: 'test "$(jq -r .verdict .spur/run/${vars.wbs}-verdict.json 2>/dev/null)" != PASS'
+  # ── done gate: record → done/failed gated on `spur task check` (ADR-026 amendment 2026-06-23) ──
+  # The record step guarantees every done-required section ([Solution, Testing, Review])
+  # has real content (each owned by its pipeline step). This guard is defense-in-depth —
+  # it certifies the matrix before done; a genuinely non-compliant task routes to failed.
+  # Declaration order: pass guard first.
+  - from: record
+    to: done
+    description: Task check passed — certify done.
+    guard:
+      kind: shell
+      options:
+        command: "${vars.spurBin} task check ${vars.wbs}"
+  - from: record
+    to: failed
+    description: Task check failed — block before done; investigate missing sections.
+    guard:
+      kind: shell
+      options:
+        command: '! ${vars.spurBin} task check ${vars.wbs}'