@gobing-ai/spur 0.3.63 → 0.3.65

package/config/rules/boundary/sp-runtime-path.yaml

@@ -1,41 +1,51 @@
 $schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
-# Runtime-path boundary rule (task 0217, R6) — zero `config/(plugins|rules|tasks|templates|workflows)`
-# references in agent-facing instructions and runtime source code. `config/` is the build-time
-# bundled-asset source-of-truth (ADR-015); `.spur/` is the runtime configuration directory that
-# agents and runtime code MUST reference. A `config/...` literal in scope teaches the wrong
-# convention and propagates confusion into every project created via `/sp:spur-init`.
+# Runtime-path boundary rule (task 0217, R6) — zero
+# `config/(plugins|rules|tasks|templates|workflows)` references in agent-facing
+# instructions and runtime source code. `config/` is the build-time bundled-asset
+# source-of-truth (ADR-015); `.spur/` is the runtime configuration directory that
+# agents and runtime code MUST reference. A `config/...` literal in scope teaches
+# the wrong convention and propagates confusion into every project created via
+# `/sp:spur-init`.
 #
-# Blanket scope (all file types across apps/packages/plugins/sp) chosen deliberately:
-# even build-time JSDoc and test-fixture `config/` literals are caught, forcing rephrase rather
-# than false-positive triage. See task 0217 Design "Standing enforcement (R6)" for rationale.
+# Blanket scope (all file types across apps/packages/plugins/sp) chosen
+# deliberately: even build-time JSDoc and test-fixture `config/` literals are
+# caught, forcing rephrase rather than false-positive triage. See task 0217
+# Design "Standing enforcement (R6)" for rationale.
 #
-# This is a STANDING gate (not transitional like rg-migration.yaml) — it runs on every pre-check.
+# This is a STANDING gate (not transitional like rg-migration.yaml) — it runs on
+# every pre-check.
 include:
-  - "apps/**"
-  - "packages/**"
-  - "plugins/sp/**"
+    - "apps/**"
+    - "packages/**"
+    - "plugins/sp/**"
 exclude:
-  - "**/node_modules/**"
-  - "**/dist/**"
-  # `.pi-lens/cache/` holds autogenerated project snapshots (absolute paths that
-  # legitimately contain `config/...` substrings). Not source — exclude to avoid
-  # triaging snapshot noise every pre-check.
-  - "**/.pi-lens/**"
-  # Package build artifacts: `build:bundle` copies repo-root config/ → apps/cli/config/
-  # (and legacy spur-cli/config/). Those trees are the ADR-015 SSOT payload itself and
-  # legitimately contain `config/...` documentation / self-references — not runtime paths.
-  - "apps/cli/config/**"
-  - "apps/cli/spur-cli/**"
+    - "**/node_modules/**"
+    - "**/dist/**"
+    # `.pi-lens/cache/` holds autogenerated project snapshots (absolute paths that
+    # legitimately contain `config/...` substrings). Not source — exclude to avoid
+    # triaging snapshot noise every pre-check.
+    - "**/.pi-lens/**"
+    # `.spur/` runtime dirs hold run records, agent sessions, and captured test
+    # output (e.g. e2e failed-agent dumps embedding real source diffs). Not
+    # source — same class as the .pi-lens exclusion above.
+    - "**/.spur/**"
+    # Package build artifacts: `build:bundle` copies repo-root config/ →
+    # apps/cli/config/ (and legacy spur-cli/config/). Those trees are the ADR-015
+    # SSOT payload itself and legitimately contain `config/...` documentation /
+    # self-references — not runtime paths.
+    - "apps/cli/config/**"
+    - "apps/cli/spur-cli/**"
 rules:
-  - id: sp-runtime-path
-    description: >
-      Use `.spur/` paths for runtime configuration references, not `config/`. `config/` is the
-      build-time bundled-asset source-of-truth (ADR-015); `.spur/` is the runtime directory.
-      Agent-facing instructions (`plugins/sp/`) and runtime code (`apps/`, `packages/`) MUST NOT
-      contain literal `config/plugins`, `config/rules`, `config/tasks`, `config/templates`, or
-      `config/workflows` path references.
-    severity: error
-    evaluator:
-      type: rg
-      config:
-        pattern: "config/(plugins|rules|tasks|templates|workflows)"
+    - id: sp-runtime-path
+      description: >
+          Use `.spur/` paths for runtime configuration references, not `config/`.
+          `config/` is the build-time bundled-asset source-of-truth (ADR-015);
+          `.spur/` is the runtime directory. Agent-facing instructions
+          (`plugins/sp/`) and runtime code (`apps/`, `packages/`) MUST NOT contain
+          literal `config/plugins`, `config/rules`, `config/tasks`,
+          `config/templates`, or `config/workflows` path references.
+      severity: error
+      evaluator:
+          type: rg
+          config:
+              pattern: "config/(plugins|rules|tasks|templates|workflows)"

package/config/rules/surface/check-cli-surface.yaml

@@ -1,7 +1,7 @@
 $schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
 # CLI surface consistency — structural checks that every command file follows
 # the registerXxxCommand convention and that --json claims are backed by real
-# output serialization (toJson or JSON.stringify).
+# output serialization (toEnvelopeJson, toJson, or JSON.stringify).
 #
 # Part of the recommended-pre-check preset. Run:
 #   spur rule run --preset recommended-pre-check
@@ -11,7 +11,8 @@ include:
 
 exclude:
   - "apps/cli/src/commands/stubs.ts"
-  - "apps/cli/src/commands/shared-options.ts" # option registry, not a command module (consistency.test.ts excludes it too)
+  - "apps/cli/src/commands/shared-options.ts" # option registry, not a command
+  # module (consistency.test.ts excludes it too)
 
 rules:
   - id: cli-register-pattern
@@ -27,11 +28,12 @@ rules:
 
   - id: cli-json-output
     description: >
-      Command files that register --json options must call toJson() or
-      JSON.stringify() to produce machine-readable output.
+      Command files that register --json options must call toEnvelopeJson()
+      (ADR-091 envelope seam), toJson(), or JSON.stringify() to produce
+      machine-readable output.
     severity: error
     evaluator:
       type: rg
       config:
-        pattern: "toJson\\b|JSON\\.stringify\\b"
+        pattern: "toEnvelopeJson\\b|toJson\\b|JSON\\.stringify\\b"
         mode: require

package/config/workflows/history-anatomy.yaml

@@ -14,7 +14,8 @@
 #   start -> resolve-scope -> resolve-paths -> analyze -> cache-probe
 #            (hit  -> refresh-provenance -> publish -> published)
 #            (miss -> render -> enrich -> structure-gate -> validate -> stamp -> publish)
-#            (validate FAIL -> correct (max 1) -> structure-gate ...; exhausted -> failed)
+#            (structure-gate FAIL -> correct (max 2 total) -> structure-gate; exhausted -> failed)
+#            (validate FAIL -> correct (max 2 total) -> structure-gate ...; exhausted -> failed)
 #            (any all-paths failure -> failed)
 #
 # `analyze` precedes `cache-probe` deliberately: ADR-079 makes cache validity a DERIVED fact, so
@@ -131,12 +132,12 @@ states:
         options:
           command: >-
             mkdir -p .spur/run;
-            . .spur/run/$__runId-paths.env;
+            . .spur/run/$__runId-paths.txt;
             $spurBin history analyze --out .spur/run/$__runId-history-anatomy-current.json --since "$HA_SINCE" --until "$HA_UNTIL" --json
       - kind: shell
         options:
           command: >-
-            . .spur/run/$__runId-paths.env;
+            . .spur/run/$__runId-paths.txt;
             $spurBin history analyze --out .spur/run/$__runId-history-anatomy-baseline.json --since "$HA_BASELINE_SINCE" --until "$HA_BASELINE_UNTIL" --json 2>/dev/null || true
 
   - id: cache-probe
@@ -229,14 +230,37 @@ states:
 
   - id: correct
     description: >
-      One bounded correction pass. onEnter increments the counter; the retry edge guards on
-      correctionCount < 1, the second failure takes the -> failed edge.
+      A two-pass correction budget (0690). onEnter increments the counter; retry edges guard on
+      the run-scoped correction-count file < 2 (`vars.correctionCount` is the declared home; the
+      file is the live bound), and a failure after the second repair takes the -> failed edge. The
+      counter is shared by the structure-gate and validate FAIL edges, so a structure repair can
+      still be followed by one validation-driven repair. The
+      model half re-authors the candidate in place from the gate findings and validation notes —
+      re-anchoring evidence rows to a backticked .md/.ts/.json path or path:line, stripping
+      placeholders, restoring the canonical twelve-section order, and reconciling quantitative
+      claims against the current/baseline artifacts — before the deterministic gate re-runs.
     onEnter:
       - kind: shell
         options:
           command: >-
             n=$(cat .spur/run/$__runId-correction-count 2>/dev/null || echo 0) &&
             printf '%s\n' "$((n + 1))" > .spur/run/$__runId-correction-count
+      - kind: shell
+        options:
+          command: >-
+            git status --porcelain > .spur/run/$__runId-baseline-correct.txt || true
+      - kind: agent.run
+        options:
+          agent: ${vars.agent}
+          input: "Repair .spur/run/${vars.__runId}-candidate.md in place. Read its structure-gate findings, optional validation notes, references/report-contract.md, and the references/operations.md validate rubric; fix every violation. Use a backticked `.md`/`.ts`/`.json` path or a `path:line` anchor, never `current #/...`; remove placeholders and empty rows; restore the twelve-section order; ensure every problem and positive finding carries the full field set; verify every quantitative claim (counts, durations, percentages, distributions) and every current/baseline full-digest match against .spur/run/${vars.__runId}-history-anatomy-current.json and -baseline.json. Overwrite only the candidate; never launch a workflow."
+          # Declared Layer-1 role (0538 R2): repair reuses enrich-class judgment.
+          role: reviewer
+          expectFile: .spur/run/${vars.__runId}-candidate.md
+          timeoutMs: ${vars.stepTimeoutMs}
+      - kind: shell
+        options:
+          command: >-
+            node "$(superskill script path sp history-anatomy-cache.mjs)" assert-clean --baseline .spur/run/$__runId-baseline-correct.txt --expect .spur/run/$__runId-candidate.md
 
   - id: refresh-provenance
     description: >
@@ -352,7 +376,14 @@ transitions:
         command: 'grep -q "^PASS$" .spur/run/$__runId-structure-gate.txt 2>/dev/null'
   - from: structure-gate
     to: failed
-    description: Structure gate FAIL — never publish a malformed candidate.
+    description: Structure gate FAIL with the correction cap exhausted — never publish a malformed candidate.
+    guard:
+      kind: shell
+      options:
+        command: '! grep -q "^PASS$" .spur/run/$__runId-structure-gate.txt 2>/dev/null && test "$(cat .spur/run/$__runId-correction-count 2>/dev/null || echo 0)" -ge 2'
+  - from: structure-gate
+    to: correct
+    description: Structure gate FAIL under the shared two-pass correction cap (0690).
     guard:
       kind: always
 
@@ -365,11 +396,11 @@ transitions:
         command: 'grep -q "Verdict: PASS" .spur/run/$__runId-validation.txt 2>/dev/null'
   - from: validate
     to: correct
-    description: Validation FAIL under the correction cap — one bounded pass.
+    description: Validation FAIL under the shared two-pass correction cap.
     guard:
       kind: shell
       options:
-        command: '! grep -q "Verdict: PASS" .spur/run/$__runId-validation.txt 2>/dev/null && test "$(cat .spur/run/$__runId-correction-count 2>/dev/null || echo 0)" -lt 1'
+        command: '! grep -q "Verdict: PASS" .spur/run/$__runId-validation.txt 2>/dev/null && test "$(cat .spur/run/$__runId-correction-count 2>/dev/null || echo 0)" -lt 2'
   - from: validate
     to: failed
     description: Validation FAIL with the correction cap exhausted — terminate without publishing.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.3.63",
+    "version": "0.3.65",
     "description": "Spur CLI — local-first harness for mainstream coding agents: constraint checking, workflow orchestration, agent health, and history analytics. Bun-native; exposes the `spur` command.",
     "keywords": [
         "spur",
@@ -53,14 +53,14 @@
     },
     "devDependencies": {
         "@commander-js/extra-typings": "^14.0.0",
-        "@gobing-ai/ts-db": "^0.4.43",
-        "@gobing-ai/ts-ai-runner": "^0.4.43",
-        "@gobing-ai/ts-dual-workflow-engine": "^0.4.43",
-        "@gobing-ai/ts-infra": "^0.4.43",
-        "@gobing-ai/ts-llm-jsonl-importer": "^0.4.43",
-        "@gobing-ai/ts-rule-engine": "^0.4.43",
-        "@gobing-ai/ts-runtime": "^0.4.43",
-        "@gobing-ai/ts-utils": "^0.4.43",
+        "@gobing-ai/ts-db": "^0.4.46",
+        "@gobing-ai/ts-ai-runner": "^0.4.46",
+        "@gobing-ai/ts-dual-workflow-engine": "^0.4.46",
+        "@gobing-ai/ts-infra": "^0.4.46",
+        "@gobing-ai/ts-llm-jsonl-importer": "^0.4.46",
+        "@gobing-ai/ts-rule-engine": "^0.4.46",
+        "@gobing-ai/ts-runtime": "^0.4.46",
+        "@gobing-ai/ts-utils": "^0.4.46",
         "@types/bun": "1.3.14",
         "@types/figlet": "^1.7.0",
         "@types/node-notifier": "8.0.5",

package/plugins/sp/README.md

@@ -129,13 +129,14 @@ list this README is checked against.
 | `dev-daily`         | Generate a daily summary report from agent usage data, git history, and notes                                                                                                                     |
 | `dev-dogfood`       | Dogfood an agent skill/command/CLI — drive it end-to-end with bounded auto-fix, self-monitor, and emit a comprehensive report                                                                     |
 | `dev-find-issue`    | Generate the daily/ad-hoc history-anatomy diagnostic report over already-imported history — mode contract, closed finding taxonomy, twelve-section report contract, cache branch, atomic publication; forwards to sp:history-anatomy                               |
+| `dev-review-session` | Review the active coding-agent session inline — compact outcome, resolved/open issues with evidence, proposal-only improvements, and next actions; forwards to sp:session-review                                                                                  |
 | `dev-find-conflict` | Authority-aware semantic audit across source, task, feature, and project authority files — detect conflicts, resolve claim-specific authority, and route confirmed repairs through owner surfaces |
 | `dev-find-next`     | Prompt-first feature frontier prioritizer — ranks the open feature frontier by derived importance/urgency with per-candidate evidence; gates unactionable features; emits tree defects as proposals only     |
 | `dev-fixall`        | Fix all lint, type, and test errors systematically across the working tree                                                                                                                        |
 | `dev-simplify`      | Simplify recently-changed code for clarity without changing behavior — incremental, test-after-each, revert on regression                                                                         |
 | `dev-arch`          | Survey a codebase (or module tree) for shallow modules and deepening opportunities — emit a ranked MARKDOWN candidate report that feeds the planning half; never auto-refactors                   |
 | `dev-reverse`       | Reverse-engineer a codebase — analyze unfamiliar repos, generate HLD/architecture docs, audit quality/security, and produce onboarding documentation                                              |
-| `dev-gitmsg`        | Generate conventional commit message(s) from staged changes via per-file summarization, optionally commit                                                                                         |
+| `dev-gitmsg`        | Generate conventional commit message(s) from the current change set via one bounded diff capture, optionally commit                                                                                         |
 | `dev-gtd`           | Get things done — quality gate (auto-fix) → conventional commit → push → gh verify in one flow; optional act CI simulation via `--act`                                                          |
 | `dev-changelog`     | Generate changelog from git commits                                                                                                                                                               |
 
@@ -173,7 +174,8 @@ and verification (`sp:code-verification`) — plus a CLI facade (`sp:spur-cli`,
 `spur` noun) and standalone technique skills (`sp:next-router`, `sp:test-driven-development`, `sp:brainstorm`,
 `sp:wayfinder`, `sp:sys-debugging`, `sp:code-review`, `sp:code-simplification`, `sp:code-improvement`,
 `sp:parallel-execution`, `sp:branch-workflow`, `sp:doc-evolve`, `sp:dogfood-testing`,
-`sp:daily-summary`, `sp:reverse-engineering`, `sp:issue-finding`, `sp:conflict-finding`, `sp:indexed-context`). See
+`sp:daily-summary`, `sp:reverse-engineering`, `sp:issue-finding`, `sp:conflict-finding`,
+`sp:indexed-context`, `sp:session-review`, `sp:redesign-web-ui`). See
 [skills/spur-dev/SKILL.md](skills/spur-dev/SKILL.md)'s Step routing table for which skill owns which
 pipeline step.
 
@@ -181,7 +183,7 @@ pipeline step.
 
 ```
 plugins/sp/
-├── skills/                          # Domain knowledge + workflow docs (28 skills)
+├── skills/                          # Domain knowledge + workflow docs (32 skills)
 │   ├── brainstorm/                  # Structured ideation workflow
 │   │   ├── agents/openai.yaml
 │   │   ├── examples/ideation-example.md
@@ -239,14 +241,17 @@ plugins/sp/
 │   │   └── references/{authority-resolution.md, comparison-protocol.md, finding-contract.md, remediation-routing.md}
 │   ├── next-feature/                # Prompt-first feature frontier prioritizer (backs /sp:dev-find-next)
 │   │   └── references/{signal-derivation.md, ranking-rubric.md, proposal-contract.md, handoff-routing.md}
+│   ├── redesign-web-ui/             # Existing-UI visual upgrade past generic AI defaults
+│   │   └── references/{audit-checklist, upgrade-techniques}.md
 │   ├── history-anatomy/             # Diagnostic interpretation owner over already-imported history (backs /sp:dev-find-issue)
 │   │   └── references/{modes.md, report-contract.md, operations.md}
+│   ├── session-review/              # Inline, report-only review of the active coding-agent session
 │   ├── sys-architecture/            # Architecture / ADR judgment competency
 │   │   └── references/decision-method.md
 │   ├── sys-debugging/               # Structured debugging protocol
 │   │   └── references/debugging-protocol.md
 │   └── wayfinder/                   # Multi-session investigation maps (SKILL.md only)
-├── commands/                        # 37 slash-command wrappers — the SSOT (hand-editable thin wrappers; see Commands below)
+├── commands/                        # 39 slash-command wrappers — the SSOT (hand-editable thin wrappers; see Commands below)
 ├── agents/                          # 4 specialist subagents (expert-spur, super-coder, super-planner, super-reviewer)
 ├── hooks/                           # hooks.json + task-write-guard.{ts,test.ts} + context-{session-start,post-tool,session-stop}.ts
 │                                    # + careful-guard.{ts,test.ts} + context-hooks.test.ts + token-estimate.test.ts
@@ -284,8 +289,8 @@ Tier 3 — Execution Layer (spur CLI + Guard Scripts)
 The single source of truth for domain knowledge and workflow documentation. Each skill is a
 self-contained knowledge module that teaches the agent how to operate one slice of the Spur CLI
 surface or run one workflow. All skills target the same five core platforms: `claude-code`, `codex`,
-`antigravity`, `opencode`, `openclaw`; `conflict-finding`, `issue-finding`, `next-feature`, and
-`reverse-engineering` additionally declare `pi`.
+`antigravity`, `opencode`, `openclaw`; selected read-only and review skills additionally declare
+`pi`.
 
 | Skill                       | Ver   | Domain                                                                                                                                                                                                                                     |
 | --------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -319,6 +324,8 @@ surface or run one workflow. All skills target the same five core platforms: `cl
 | `pr-reviewing`              | 1.0   | GitHub Codex PR review — PR prepare/reuse, `@codex review` request with per-HEAD dedupe, bounded polling, findings normalization, validated fix + re-review; spine SSOT `pr-review.yaml` + `scripts/pr-reviewing.ts`; backs `/sp:dev-pr-review`     |
 | `indexed-context`           | 1.0   | Cross-agent project context — anatomy/learnings/pitfalls/buglog/memory in `.spur/context/`; hook-tracked token-ledger; graceful degradation on agents without hooks                                                                        |
 | `history-anatomy`           | 1.0   | Diagnostic interpretation owner over already-imported history — daily/ad-hoc mode contract, closed finding taxonomy, twelve-section report contract, `enrich`/`validate` rubrics; no workflow launch, no JSONL fallback, no corpus mutation                                                                   |
+| `session-review`            | 1.0   | Inline review of the active coding-agent session — compact outcomes, evidence-backed resolved/open issue classification, proposal-only improvements, and next actions; no workflow, import, delegation, or mutation                                                                                           |
+| `redesign-web-ui`           | 1.0   | Existing-UI visual upgrade — audit generic AI fingerprints, apply in-stack polish against `DESIGN.md` / live tokens, verify behavior and viewports; does not migrate frameworks                                                                                                                            |
 
 #### Bounded coexistence and retirement gate — `sp:issue-finding` (HA-S1 0661)
 
@@ -351,11 +358,11 @@ Skills contain zero validation logic — the CLI is the gate.
 
 Thin slash-command wrappers that parse user arguments and delegate to the corresponding skill. Each
 command is a user-facing entry point that bridges natural language to skill invocation. There are
-**38 commands** (see the Command index above for the full list), organized by the surface they wrap:
+**39 commands** (see the Command index above for the full list), organized by the surface they wrap:
 
 | Prefix       | Count | Delegates to                                                                                                                                                                                                                                                                                                        | Purpose                                                                                |
 | ------------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
-| `dev-*`      | 32    | `sp:spur-dev`, `sp:code-implementation`, `sp:code-testing`, `sp:code-verification`, `sp:code-simplification`, `sp:next-router`, `sp:brainstorm`, `sp:dogfood-testing`, `sp:parallel-execution`, `sp:sys-debugging`, `sp:daily-summary`, `sp:history-anatomy`, `sp:conflict-finding`, `sp:reverse-engineering`, `sp:pr-reviewing`, inline | The dev-workflow surface — planning, execution, batch, wrap-up, review/verify, hygiene |
+| `dev-*`      | 33    | `sp:spur-dev`, `sp:code-implementation`, `sp:code-testing`, `sp:code-verification`, `sp:code-simplification`, `sp:next-router`, `sp:brainstorm`, `sp:dogfood-testing`, `sp:parallel-execution`, `sp:sys-debugging`, `sp:daily-summary`, `sp:history-anatomy`, `sp:session-review`, `sp:conflict-finding`, `sp:reverse-engineering`, `sp:pr-reviewing`, inline | The dev-workflow surface — planning, execution, batch, wrap-up, review/verify, hygiene |
 | `rule-*`     | 3     | `sp:spur-cli`                                                                                                                                                                                                                                                                                                       | The rule surface — `rule-add`, `rule-refine`, `rule-scan`                              |
 | `workflow-*` | 2     | `sp:spur-cli`                                                                                                                                                                                                                                                                                                       | The workflow surface — `workflow-add`, `workflow-refine`                               |
 | `spur-init`  | 1     | `sp:doc-evolve`                                                                                                                                                                                                                                                                                                     | Project bootstrap (`spur init`) with doc-evolve integration                            |
@@ -365,7 +372,7 @@ Each command file contains:
 - YAML frontmatter (`description`, `argument-hint`, `allowed-tools`).
 - A delegation block: `Skill(skill="sp:<skill-name>", args="<operation> $ARGUMENTS")`.
 
-**Commands as SSOT (ADR-032).** The 38 `.md` files in `commands/` are the authoritative,
+**Commands as SSOT (ADR-032).** The 39 `.md` files in `commands/` are the authoritative,
 hand-editable source for the operator command surface. Per-platform adapters are **install-time
 output** owned by `superskill` (`superskill install sp`) and never committed here. Plugin `sp` ships
 no per-platform artifacts — only the platform-independent thin wrappers.
@@ -494,7 +501,7 @@ the hard gate that the soft skill cannot enforce on its own.
 ```mermaid
 graph TB
     subgraph "User entry points"
-        CMD["Commands<br/>37 slash commands<br/>/sp:dev-plan, /sp:dev-runall, /sp:dev-refineall, /sp:rule-add, ..."]
+        CMD["Commands<br/>39 slash commands<br/>/sp:dev-plan, /sp:dev-runall, /sp:dev-review-session, /sp:rule-add, ..."]
         AGENT["Agents<br/>4 subagents<br/>expert-spur, super-coder, super-planner, super-reviewer"]
         HOOK["PreToolUse hook<br/>Write|Edit matcher"]
     end

package/plugins/sp/agents/expert-spur.md

@@ -45,10 +45,24 @@ guide and conventions before acting.
 - **Traceability audits** — verify every task links to a feature, every scenario maps to a task.
 - **Section-editing campaigns** — update the same section across multiple tasks.
 - **Rule-catalog work** — author, fine-tune, validate, or harden constraint rules across the catalog.
-- **Workflow work** — author, validate, dry-run, or refactor one or more workflows.
-  When authoring or refactoring, read the composition-measures section in
-  `sp:spur-cli` `references/workflows.md` and apply the advisory's fix-path map — findings are
-  advisory only; never block a run or edit an executing pipeline over them.
+- **Workflow work** — decide fit, author, validate, dry-run, tune, or refactor one or more workflows.
+  Read `sp:spur-cli` `references/workflows/workflow-fit-and-tuning.md` before authoring or
+  refactoring, and apply it in this order:
+  - **Fit first.** A process earns a `spur workflow` only when it replays, branches on a
+    machine-checkable predicate, **and** needs a durable per-run record. Fewer than three → recommend
+    a descriptive procedure or checklist and stop. Author the mode gate only after fit clears.
+  - **Simplicity is the budget, and it is measured.** `shell` commands at or under 5 non-comment
+    units, `agent.run` inputs referencing a slash command rather than carrying a raw prompt, guards
+    a single predicate. Over budget → pick a recorded owner from
+    `docs/design/workflow-shell-ownership.md`; never reformat to dodge the measure.
+  - **Latency and observability are authoring decisions.** Minimize `agent.run` node count first;
+    soft status-file probe over repeated probing; guards ordered cheapest-discriminating-first;
+    `iterationBound` from a latency budget; states named for outcomes; `failureStates` declared.
+  - **Refactor in a named direction** — promote (prose → workflow), demote (workflow → prose),
+    or optimize in place. Back an optimization with a before/after `spur workflow trace` pair,
+    never with a feel.
+  - Composition-advisory findings (`workflow validate --json` → `composition`) are advisory only;
+    never block a run or edit an executing pipeline over them.
 - **Corpus health checks** — run `check`/`validate` across a batch and report findings.
 
 For a single operation, use the `spur` CLI directly. For the planning/execution lifecycle, use
@@ -72,12 +86,14 @@ Invoke `sp:spur-cli` for verb guidance and per-noun conventions:
 - [ ] Run the corpus-wide sweep after batch edits: `spur task check --corpus --json` (fails on structural errors outside `config/corpus-baseline.json`).
 - [ ] Use `spur task update --section --from-file` for all task section edits.
 - [ ] Run the noun's scoped `refresh` after batch operations where one exists (`spur task refresh`, `spur feature refresh --feature <id>` or `--all`).
+- [ ] Run the workflow fit gate before authoring any new workflow, and recommend a descriptive procedure when it does not clear all three parts.
 
 ### Never
 
 - [ ] Never edit corpus files directly — always through CLI verbs.
 - [ ] Never reimplement verb logic or validation — the CLI owns it.
 - [ ] Never drive the planning/execution lifecycle through this agent — use `sp:spur-dev`.
+- [ ] Never author a workflow whose every node is a raw-prompt `agent.run` — that is a descriptive procedure paying a process spawn per step.
 
 ## Output Format
 

package/plugins/sp/commands/dev-find-issue.md

@@ -1,5 +1,5 @@
 ---
-description: "Generate the daily or ad-hoc history-anatomy diagnostic report over already-imported history: the twelve-section report contract, closed finding taxonomy, cache branch, bounded correction, and atomic publication. Triggers: find issues, post-mortem, performance analysis, session review, history-anatomy, run the daily report, ad-hoc diagnosis"
+description: "Generate the daily or ad-hoc history-anatomy diagnostic report over already-imported history: the twelve-section report contract, closed finding taxonomy, cache branch, bounded correction, and atomic publication. Triggers: find historical issues, post-mortem, performance analysis, history-anatomy, run the daily report, ad-hoc diagnosis"
 role: reviewer
 argument-hint: "[<focus>] [--mode <daily|ad-hoc>] [--date <YYYY-MM-DD>] [--since <RFC3339>] [--until <RFC3339>] [--recompute] [--agent <auto|name>] [--output <path>]"
 allowed-tools: ["Bash", "Read", "Skill"]
@@ -15,6 +15,9 @@ exposes the `enrich` and `validate` operations the `history-anatomy.yaml` workfl
 Publication is atomic and gated behind both the deterministic structure gate and independent
 evidence validation. This command never triggers an import.
 
+For an immediate review of the active conversation, route to `/sp:dev-review-session`; this command
+owns imported-history windows, recurrence, trends, and quantitative forensics only.
+
 ## Argument Flags
 
 | Flag                                   | Description                                                                                        | Default  |
@@ -25,7 +28,7 @@ evidence validation. This command never triggers an import.
 | `--since` `<RFC3339>`                  | Inclusive lower bound (ad-hoc; required).                                                          | omitted  |
 | `--until` `<RFC3339>`                  | Inclusive upper bound (ad-hoc; required).                                                          | omitted  |
 | `--recompute`                          | Force the full analyze/render/enrich/validate path; records disposition forced-recompute.          | off      |
-| `--agent` `<auto\|name>`               | Execution surface selector. This target is engine-driven (headless): omit resolves through the executor precedence chain to `agent.default`, then the workflow literal. Explicit `--agent inline` is rejected with the stable special error (exit 2). | omitted  |
+| `--agent` `<auto\|name>`               | Execution surface selector. This target is engine-driven (headless). Per task 0687, omit and explicit `--agent inline` resolve identically — tier resolution with one warning naming the substituted executor; there is deliberately **no** host-session inline driver for `history-anatomy.yaml` (mechanism (b)). A name pins the executor. | omitted  |
 | `--output` `<path>`                    | Explicit report output path (ad-hoc; default writes to the run directory).                         | run dir  |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).

package/plugins/sp/commands/dev-gitmsg.md

@@ -1,7 +1,7 @@
 ---
-description: Generate conventional commit message(s) from staged changes via per-file summarization, optionally commit
+description: Generate conventional commit message(s) from the current change set via one bounded diff capture, optionally commit
 role: scribe
-argument-hint: "[--commit] [--squash] [--scope <path>]"
+argument-hint: "[--commit] [--squash] [--all] [--scope <path>]"
 allowed-tools: ["Bash", "Read"]
 ---
 
@@ -13,17 +13,23 @@ Implements an inline procedure — see [dev-operations.md](../skills/spur-dev/re
 
 | Flag | Description | Default |
 | --- | --- | --- |
-| `--commit` | Stage and commit with the generated message. | off |
-| `--squash` | Squash staged changes into one commit. | off |
-| `--scope` `<path>` | Scope the diff to a path. | all staged changes |
+| `--commit` | Commit the change set — one commit per concern. | off |
+| `--squash` | Collapse every concern into one message and one commit; implies `--commit`. | off |
+| `--all` | Widen the change set past the index to every change in the tree — unstaged **and untracked**. | off |
+| `--scope` `<path>` | Path filter on the change set; always wins over change-set auto-discovery. | the whole change set |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
 
 ## Usage
 
-/sp:dev-gitmsg [--commit] [--squash] [--scope <path>]
+/sp:dev-gitmsg [--commit] [--squash] [--all] [--scope <path>]
 
 ## Implementation
 
 Follow the inline procedure in [dev-operations.md](../skills/spur-dev/references/dev-operations.md#9-gitmsg) (gitmsg).
 
+One diff capture per run — `-U0`, lockfiles excluded, 60 KB cap — is the token contract; never re-read
+the diff wider. Neither `--commit` nor `--squash` → messages only. `--commit` → one commit per concern, split automatically,
+so the operator is never asked to re-stage and re-run. `--squash` → one commit for everything.
+An empty index widens to the whole tree only on a message-only run, and says so; a committing run
+stops there and prints the exact `--all` re-run line instead of guessing.

package/plugins/sp/commands/dev-gtd.md

@@ -62,25 +62,14 @@ The real GitHub CI runner passes. **Do not** modify the build infrastructure to
 Then stop the run (this stage failed). The operator can proceed by re-running without `--act`.
 
 **3 — Generate a conventional commit message.** Follow the gitmsg procedure (the same one
-`/sp:dev-gitmsg` runs). Run `git diff --cached --stat` (add `-- <path>` when `--scope` is given) for
-the outline; if it is empty, stage the intended changes first and report "no staged changes" if
-nothing was meant to be committed. Capture the full diff to a temp file
-(`TEMP_FILE="/tmp/gitdiff_$(date +%s)"; git diff --cached > "$TEMP_FILE" 2>&1`). Read it and write
-**one sentence per changed file** — what changed and why. Group the per-file sentences by concern;
-for each group derive its commit type (`feat` · `fix` · `refactor` · `docs` · `chore` · `perf` ·
-`test` · `style`), scope (affected module/package, or the `--scope` value), and message:
-
-```
-<type>(<scope>): <summary>
-
-<body — optional bullets from the group's per-file sentences>
-```
-
-Summary: imperative mood, ≤72 chars, lowercase first word, no period. Body only when the change is
-non-obvious. Resolve groups: one group → emit its message; multiple groups → emit one message per
-group plus a split recommendation (stage per concern, re-run); under this all-in-one flow, prefer a
-single combined message (dominant type/scope, per-file bullets) so the push is atomic. Delete the
-temp file (`rm "$TEMP_FILE"`) — no `/tmp` diff residue.
+`/sp:dev-gitmsg` runs) — see
+[dev-operations.md](../skills/spur-dev/references/dev-operations.md#9-gitmsg): one bounded diff
+capture, concern grouping, conventional `<type>(<scope>): <summary>` formatting. Two deviations
+belong to this flow: read the change set with `--all` semantics (this stage commits everything the
+gate just proved green, not only what happens to be staged), and resolve multiple concerns to a
+**single combined message** (dominant type/scope, one body bullet per concern) so the push is
+atomic. `--scope <path>` bounds the capture as usual. If the change set is empty, report
+"no changes to commit" and stop.
 
 **4 — Commit.** Stage all intended changes (`git add`) and commit with the resolved message
 (`git commit -m "$MESSAGE"`). When `--dry-run`, print the message and the copy-paste `git commit` /

package/plugins/sp/commands/dev-idea.md

@@ -20,7 +20,7 @@ contract below maps to that workflow's transitions.
 | `--approve-taste` | With `--auto`: set idea_approved + design_approved so idea-eval / design-approval do not pause. | off |
 | `--idea-approved` | Compatibility alias for idea_approved=true (subset of --approve-taste). | off |
 | `--design-approved` | Compatibility alias for design_approved=true (subset of --approve-taste). | off |
-| `--agent` `<auto\|name>` | Who runs the model-bearing ideation. The pipeline's `agent.run` stages are headless — they always dispatch a subprocess, so `--agent inline` is rejected there with the stable special error (exit 2). Use `omit` (resolves to `agent.default`), `auto` (tier-resolves an executor), or a name (pins that executor). | agent.default |
+| `--agent` `<auto\|name>` | Who runs the model-bearing ideation. The pipeline's `agent.run` stages are headless — they always dispatch a subprocess. Omission and explicit `--agent inline` resolve identically per task 0687: tier substitution plus one warning naming the substituted executor; `auto` (tier-resolves an executor); a name (pins that executor). | inline |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
 

package/plugins/sp/commands/dev-plan.md

@@ -16,7 +16,7 @@ Wraps the **sp:spur-dev** skill.
 | `"<description>"` | Feature description to plan. | required |
 | `--feature` `<id>` | Attach to an existing feature. | omitted |
 | `--parent` `<feature-id>` | Create under a parent feature. | omitted |
-| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing planning. The planning pipeline's `agent.run` stages are headless — they always dispatch a subprocess. Explicit `--agent inline` is rejected there with the stable special error (exit 2): a headless surface cannot host a session — no dispatch, no `agent.default` fallback. Use `omit` (resolves to `agent.default`), `auto` (tier-resolves an executor), or a name (pins that executor). | agent.default |
+| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing planning. The planning pipeline's `agent.run` stages are headless — they always dispatch a subprocess. `inline` — also what omission resolves to since task 0687 — substitutes tier resolution there with one warning naming the resolved executor; `auto` (tier-resolves an executor); a name (pins that executor). | inline |
 | `--skip-design` | Omit the system-design hop. | off |
 | `--auto` | Skip objective HITL gates. | off |
 | `--approve-taste` | With --auto: skip design-approval pause. | off |

package/plugins/sp/commands/dev-review-session.md

@@ -0,0 +1,36 @@
+---
+description: "Review the active coding-agent session immediately: summarize outcomes, distinguish resolved and open issues with evidence, and propose bounded improvements. Triggers: review this session, session wrap-up, immediate retrospective, what happened, what was resolved"
+role: reviewer
+argument-hint: "[<focus>]"
+allowed-tools: ["Bash", "Read", "Grep", "Glob", "Skill"]
+---
+
+# Dev Review Session
+
+Wraps the **sp:session-review** skill for a lightweight, report-only review of the active host
+session. It uses the current conversation plus read-only repository evidence, runs inline so the
+session context is preserved, and never launches a workflow, imports history, creates a task, or
+applies a remediation.
+
+## Argument Flags
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| `[<focus>]` | Optional question or operation to emphasize without excluding material session outcomes. | full active session |
+
+For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
+
+## Usage
+
+```
+/sp:dev-review-session
+/sp:dev-review-session "why the verification loop repeated"
+```
+
+## Implementation
+
+Invoke the skill directly in the active host session; do not delegate to a subagent or subprocess.
+
+```
+Skill(skill="sp:session-review", args="$ARGUMENTS")
+```

package/plugins/sp/commands/dev-run.md

@@ -15,7 +15,7 @@ Wraps the **sp:spur-dev** and **sp:code-implementation** skills.
 | --- | --- | --- |
 | `<wbs>` | Task WBS to run. | required |
 | `--mode` `<full\|implement>` | Full pipeline or single implement step. | full |
-| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing stages. In an interactive session, omit/`inline` keeps the controller in the host session (non-subprocess) — **omit**'s eligible full-mode `agent.run` stages may dispatch once to a native subagent, with host fallback (task 0508); explicit `--agent inline` is the zero-dispatch carve-out (every stage executes in the invoking session, never a native subagent). `auto` or a name keeps subprocess dispatch. | omit |
+| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing stages. omit and explicit `--agent inline` resolve identically (task 0687): eligible stages dispatch once to a native subagent with host-session fallback (0508 eligibility); otherwise every stage executes in the invoking session. `auto` or a name keeps subprocess dispatch.. | omit |
 | `--auto` | Skip objective HITL confirmations. | off |
 | `--next` | Chain-to-completion via the next-router. | off |
 | `--wrap` | Run the wrap hop after the main step. The `--agent` selector is preserved into the `/sp:dev-wrap <wbs>` handoff when supplied; omission remains omission. The wrap hop is workflow-backed and reports its trigger-3 subprocess override. | off |
@@ -39,7 +39,7 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 
 **Flags:**
 
-- `--auto` | `--agent <inline|auto|name>` — Skip objective HITL confirmations (taste/irreversible gates still pause). `--agent` names who does the model-bearing work. Interactive omit/`inline` keeps the controller and implement-only stages in this session; full mode reads `task-pipeline.yaml` as the SSOT and interprets its actions/guards through the inline driver, where **omitted** `--agent`'s eligible `agent.run` stages may dispatch once to a native subagent and otherwise run in the host (task 0508); explicit `--agent inline` is the zero-dispatch carve-out — every stage executes in the invoking session. It records `stage <id> executed inline in session <session-id>` or `stage <id> executed via subagent <agent-id> (host session <session-id>)` in the run log. `auto` or a name is merged into `vars.agent` and `vars.implementAgent` and keeps the existing subprocess workflow. Headless `spur workflow run` / `spur agent run` is unchanged. See the [execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
+- `--auto` | `--agent <inline|auto|name>` — Skip objective HITL confirmations (taste/irreversible gates still pause). `--agent` names who does the model-bearing work. Interactive omit/`inline` keeps the controller and implement-only stages in this session; full mode reads `task-pipeline.yaml` as the SSOT and interprets its actions/guards through the inline driver, whose eligible `agent.run` stages dispatch once to a native subagent and otherwise run in the host (0508 eligibility — task 0687 resolved-inline) It records `stage <id> executed inline in session <session-id>` or `stage <id> executed via subagent <agent-id> (host session <session-id>)` in the run log. `auto` or a name is merged into `vars.agent` and `vars.implementAgent` and keeps the existing subprocess workflow. Headless `spur workflow run` / `spur agent run` is unchanged. See the [execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
 
 `--worktree` `[<name>]` (run the task's pipeline in an isolated git worktree — FF-merge onto the
 base ref on full success, retain intact on any failure/halt/non-FF; bare form creates a fresh tree,