@gobing-ai/spur 0.3.61 → 0.3.62

package/config/workflows/history-anatomy.yaml

@@ -0,0 +1,366 @@
+# History-anatomy pipeline — daily/ad-hoc diagnostic report over already-imported history
+# (feature I8, HA-S1 0660 / ADR-079).
+#
+# Orchestration is configuration (ADR-022): a state machine over the existing dual-workflow
+# engine. The YAML owns ONLY the cache branch, deterministic stage ordering, executor dispatch,
+# bounded correction, and atomic publication sequencing. The deterministic cache/digest/
+# structure/publish work is 0659's dependency-free helper script; the judgment (mode validity,
+# what counts as evidence, the report contract, enrich/validate rubrics) is 0658's skill. Per
+# ADR-069 R1, cache-decide / digest / structure-check / publish must NOT be inline shell — every
+# shell action here is glue length (a single helper invocation), because each of those programs
+# would exceed the shell composition threshold and be flagged as an owned-capability candidate.
+#
+# Shape:
+#   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)
+#            (any all-paths failure -> failed)
+#
+# `analyze` precedes `cache-probe` deliberately: ADR-079 makes cache validity a DERIVED fact, so
+# the semantic digest must come from a fresh analyze, never from the cached report being judged.
+# The deterministic half is therefore never cached — only the model-authored half is reused.
+#
+# terminalStates: [published, failed]. Publication is reachable ONLY via `stamp` (guarded on a
+# passing validation) or `refresh-provenance` (whose model half was itself published through a
+# passing validation) — there is no edge into `publish` from structure-gate or enrich directly.
+#
+# Vars (all must be declared here — the vars: block is the only safe shape; `spur workflow
+# validate` and the skill-structure test enforce it):
+#   mode      — "daily" (default) | "ad-hoc" (validated in resolve-scope)
+#   date      — YYYY-MM-DD for --date (daily); empty for ad-hoc
+#   since     — inclusive ISO lower bound (ad-hoc; also normalizes daily via the DST-aware rule)
+#   until     — inclusive ISO upper bound (ad-hoc)
+#   focus     — ad-hoc focus string (required in ad-hoc mode, rejected in daily)
+#   recompute — "true" forces the full analyze/render/enrich/validate path (cache disposition
+#               forced-recompute)
+#   output    — explicit report output path; default run directory
+#   agent     — executor for the agent.run stages (enrich/validate)
+#   spurBin   — PATH-independent spur invocation (overridden by CLI at run start)
+#   __runId   — run-scoped id for explicit artifact paths (allocated in start)
+#   stepTimeoutMs — agent.run budget for enrich/validate
+#   correctionCount — bounded correction loop counter file path bits (name resolved in correct)
+
+"$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
+kind: state-machine
+name: history-anatomy
+description: "Daily/ad-hoc history-anatomy report: cache branch, deterministic analyze/render, skill enrichment, deterministic structure gate, independent evidence validation, bounded correction, atomic publication"
+iterationBound: 20
+initialState: start
+terminalStates:
+  - published
+  - failed
+failureStates:
+  - failed
+vars:
+  mode: "daily"
+  date: ""
+  since: ""
+  until: ""
+  focus: ""
+  recompute: "false"
+  output: ""
+  agent: "omp"
+  spurBin: "spur"
+  __runId: ""
+  stepTimeoutMs: "1800000"
+  correctionCount: "0"
+  workflowFile: "config/workflows/history-anatomy.yaml"
+  contractVersion: "1"
+  reportDir: "docs/report"
+
+states:
+  - id: start
+    description: >
+      Allocate the run-scoped id and root. Every analyze/render path in this workflow writes to
+      an explicit unique path under this run id — no stage reads the mutable latest.json pointer.
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            mkdir -p .spur/run;
+            if [ -z "$__runId" ]; then __runId=$(uuidgen | tr 'A-Z' 'a-z' | cut -c1-8); fi;
+            echo "$__runId" > .spur/run/history-anatomy-run.id
+
+  - id: resolve-scope
+    description: >
+      Dispatch the skill's mode validation (0658 references/modes.md): daily is the default and
+      rejects focus/since/until/output; ad-hoc requires a non-empty focus plus two ordered
+      inclusive bounds and rejects --date/--recompute. Writes the normalized selector artifact.
+    onEnter:
+      - kind: agent.run
+        options:
+          agent: ${vars.agent}
+          input: "Validate the mode arguments per sp:history-anatomy references/modes.md and write the normalized selector to .spur/run/${vars.__runId}-selector.json. mode=${vars.mode} date=${vars.date} since=${vars.since} until=${vars.until} focus=${vars.focus}. Reject conflicting arguments, naming the offending one; a rejection marks the run failed."
+          # Declared Layer-1 role (0538 R2): mode validation is a reviewer-standard judgment.
+          role: reviewer
+          expectFile: .spur/run/${vars.__runId}-selector.json
+          timeoutMs: ${vars.stepTimeoutMs}
+
+  - id: resolve-paths
+    description: >
+      Resolve the helper, the skill/contract logic paths, and the publication target once, into a
+      run-scoped env file every later stage sources. Keeps each downstream shell action at glue
+      length (ADR-069 R1) instead of repeating path arithmetic per stage.
+    onEnter:
+      - kind: shell
+        options:
+          # Path arithmetic lives in the helper (ADR-069 R1); the shell only locates it. Avoid
+          # `${...}` here — that syntax collides with the engine's own template interpolation.
+          command: >-
+            h=$(superskill script path sp history-anatomy-cache.mjs);
+            node "$h" paths --helper "$h" --report-dir "$reportDir" --date "$date"
+            --output "$output" --out .spur/run/$__runId-paths.env
+
+  - id: analyze
+    description: >
+      Deterministic analyze of the current window and the immediately preceding comparable
+      window, each to an explicit run-scoped path. Always reruns — the deterministic half is
+      never cached (ADR-079).
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            mkdir -p .spur/run;
+            $spurBin history analyze --out .spur/run/$__runId-history-anatomy-current.json --since "$since" --until "$until" --json
+      - kind: shell
+        options:
+          command: >-
+            $spurBin history analyze --out .spur/run/$__runId-history-anatomy-baseline.json --since "$baselineSince" --until "$until" --json 2>/dev/null || true
+
+  - id: cache-probe
+    description: >
+      Deterministic cache probe via the helper (0659). Runs AFTER analyze because ADR-079 makes
+      validity a derived fact: the semantic digest must come from the fresh artifact, never from
+      the cached report being judged. A hit skips only enrichment, never the probe. Daily only;
+      ad-hoc always reports miss (`ad-hoc-never-cached`). Also writes the run's full provenance.
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            . .spur/run/$__runId-paths.env;
+            node "$HA_HELPER" probe --artifact .spur/run/$__runId-history-anatomy-current.json
+            --baseline .spur/run/$__runId-history-anatomy-baseline.json --target "$HA_TARGET"
+            --mode "$mode" --date "$HA_DATE" --recompute "$recompute" --executor "$agent"
+            --skill-dir "$HA_SKILL" --contract "$HA_SKILL/references/report-contract.md"
+            --workflow "$workflowFile" --contract-version "$contractVersion" --run-id "$__runId"
+            --out .spur/run/$__runId-provenance.json
+            > .spur/run/$__runId-cache-disposition.txt
+
+  - id: render
+    description: >
+      Render both artifacts with report --mode forensics, naming the exact analyze paths.
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            mkdir -p .spur/run;
+            $spurBin history report .spur/run/$__runId-history-anatomy-current.json --mode forensics > .spur/run/$__runId-history-anatomy-current.md;
+            $spurBin history report .spur/run/$__runId-history-anatomy-baseline.json --mode forensics > .spur/run/$__runId-history-anatomy-baseline.md || true
+
+  - id: enrich
+    description: >
+      Model enrichment via the skill operation sp:history-anatomy enrich (0658 operations.md).
+      Consumes the two artifacts; authors the model half of the report.
+    onEnter:
+      - kind: agent.run
+        options:
+          agent: ${vars.agent}
+          input: "Run sp:history-anatomy enrich: given .spur/run/${vars.__runId}-history-anatomy-current.json and -baseline.json, author the model half of the report (Baseline comparison, Findings, Recurrence ledger, Remediation options, Performance analysis, Workflow/process improvements, Positive patterns) to .spur/run/${vars.__runId}-candidate.md per references/report-contract.md. This operation never launches a workflow."
+          # Declared Layer-1 role (0538 R2): enrichment is model judgment.
+          role: reviewer
+          expectFile: .spur/run/${vars.__runId}-candidate.md
+          timeoutMs: ${vars.stepTimeoutMs}
+
+  - id: structure-gate
+    description: >
+      Deterministic structure gate via the helper (0659). Asserts the eleven sections in order,
+      per-finding fields, no placeholders, evidence anchors. Not reachable on the hit path from
+      enrich — always gated before validation.
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            node "$(superskill script path sp history-anatomy-cache.mjs)" check \
+              .spur/run/$__runId-candidate.md > .spur/run/$__runId-structure-gate.txt 2>&1 || true
+
+  - id: validate
+    description: >
+      Independent evidence validation via the skill operation sp:history-anatomy validate.
+      Publication is reachable only from a PASS here.
+    onEnter:
+      - kind: agent.run
+        options:
+          agent: ${vars.agent}
+          input: "Run sp:history-anatomy validate: independently check .spur/run/${vars.__runId}-candidate.md against the two artifacts per references/operations.md; write Verdict: PASS or FAIL to .spur/run/${vars.__runId}-validation.txt. This operation never launches a workflow."
+          # Declared Layer-1 role (0538 R2): independent verification.
+          role: reviewer
+          expectFile: .spur/run/${vars.__runId}-validation.txt
+          timeoutMs: ${vars.stepTimeoutMs}
+
+  - 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.
+    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
+
+  - id: refresh-provenance
+    description: >
+      Cache-hit path. Keeps the published model half verbatim and refreshes only validated_at,
+      the cache disposition, and the imported-snapshot banner — which is the EARLIEST per-source
+      lastImportedAt, so the report never claims a source was imported after its own recorded
+      timestamp. Emits the publishable artifact the shared publish state consumes.
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            . .spur/run/$__runId-paths.env;
+            node "$HA_HELPER" refresh --report "$HA_TARGET"
+            --out .spur/run/$__runId-publishable.md --disposition hit
+
+  - id: stamp
+    description: >
+      Cache-miss path. Attaches the full R7 frontmatter provenance block (identity tuple, window
+      state, generated/validated timestamps, artifact paths + digests, contract/skill/workflow
+      digests, per-source coverage + last_imported_at, spur/schema version, executor, run id,
+      cache disposition) and the freshness banner to the validated candidate.
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            . .spur/run/$__runId-paths.env;
+            node "$HA_HELPER" stamp --candidate .spur/run/$__runId-candidate.md
+            --provenance .spur/run/$__runId-provenance.json
+            --out .spur/run/$__runId-publishable.md
+
+  - id: publish
+    description: >
+      Atomic publication via the helper (0659). Reachable only from `stamp` (which is reachable
+      only from a passing validate) or from `refresh-provenance` on the cache-hit path — the
+      model half a hit reuses was itself published through a passing validation.
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            . .spur/run/$__runId-paths.env;
+            mkdir -p "$(dirname "$HA_TARGET")";
+            node "$HA_HELPER" publish .spur/run/$__runId-publishable.md "$HA_TARGET"
+
+  - id: published
+    description: Terminal — report published atomically after a passing validation.
+
+  - id: failed
+    description: Terminal — mode rejection, gate failure, or validation failure not corrected.
+
+transitions:
+  - from: start
+    to: resolve-scope
+    description: Scope resolved.
+    guard:
+      kind: always
+
+  - from: resolve-scope
+    to: resolve-paths
+    description: Mode valid — resolve helper/skill/target paths once.
+    guard:
+      kind: always
+
+  - from: resolve-paths
+    to: analyze
+    description: Paths resolved — always rerun the deterministic half (ADR-079).
+    guard:
+      kind: always
+
+  - from: analyze
+    to: cache-probe
+    description: Fresh artifacts on disk — derive the digest and decide reuse.
+    guard:
+      kind: always
+
+  # Daily only takes the hit branch; ad-hoc always regenerates.
+  - from: cache-probe
+    to: refresh-provenance
+    description: Cache hit (daily) — refresh provenance and publish without re-enrichment.
+    guard:
+      kind: shell
+      options:
+        command: 'test "$mode" = daily && grep -q "^hit$" .spur/run/$__runId-cache-disposition.txt 2>/dev/null'
+  - from: cache-probe
+    to: render
+    description: Cache miss, forced recompute, or ad-hoc — render and re-enrich.
+    guard:
+      kind: always
+
+  - from: refresh-provenance
+    to: publish
+    description: Provenance refreshed — publish the cached model half.
+    guard:
+      kind: always
+
+  - from: render
+    to: enrich
+    description: Both artifacts rendered — enrich.
+    guard:
+      kind: always
+
+  - from: enrich
+    to: structure-gate
+    description: Candidate authored — deterministic structure gate.
+    guard:
+      kind: always
+
+  - from: structure-gate
+    to: validate
+    description: Candidate structurally sound — independent evidence validation.
+    guard:
+      kind: shell
+      options:
+        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.
+    guard:
+      kind: always
+
+  - from: validate
+    to: stamp
+    description: Independent validation PASS — stamp provenance, then publish atomically.
+    guard:
+      kind: shell
+      options:
+        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.
+    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'
+  - from: validate
+    to: failed
+    description: Validation FAIL with the correction cap exhausted — terminate without publishing.
+    guard:
+      kind: always
+
+  - from: correct
+    to: structure-gate
+    description: Corrected candidate re-enters the deterministic gate, then re-validates.
+    guard:
+      kind: always
+
+  - from: stamp
+    to: publish
+    description: Provenance stamped — publish atomically.
+    guard:
+      kind: always
+
+  - from: publish
+    to: published
+    description: Report published.
+    guard:
+      kind: always

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.3.61",
+    "version": "0.3.62",
     "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",

package/plugins/sp/README.md

@@ -127,9 +127,8 @@ list this README is checked against.
 | `dev-handover`      | Generate a structured handover document when blocked — captures goal, progress, blocker, rejected approaches, and next steps                                                                      |
 | `dev-debug`         | Systematic debugging protocol — reproduce, isolate, diagnose root cause, apply minimal fix, and verify with regression tests                                                                      |
 | `dev-daily`         | Generate a daily summary report from agent usage data, git history, and notes                                                                                                                     |
-| `dev-history-load`  | On-demand cumulative history load + narrowed analyze — import (checkpoint-resume) then analyze, optionally by session/task/window, with optional forensics render                                     |
 | `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`    | Review agent session logs, identify performance bottlenecks and behavioral anti-patterns, and generate a structured task file with proposed fixes                                                 |
+| `dev-find-issue`    | Generate the daily/ad-hoc history-anatomy diagnostic report over already-imported history — mode contract, closed finding taxonomy, eleven-section report contract, cache branch, atomic publication; forwards to sp:history-anatomy                               |
 | `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                                                                                                                        |
@@ -240,6 +239,8 @@ 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}
+│   ├── history-anatomy/             # Diagnostic interpretation owner over already-imported history (backs /sp:dev-find-issue)
+│   │   └── references/{modes.md, report-contract.md, operations.md}
 │   ├── sys-architecture/            # Architecture / ADR judgment competency
 │   │   └── references/decision-method.md
 │   ├── sys-debugging/               # Structured debugging protocol
@@ -312,11 +313,23 @@ surface or run one workflow. All skills target the same five core platforms: `cl
 | `daily-summary`             | 1.0.0 | Daily summary report generator — orchestrates ccusage CLI + git history into structured markdown summaries                                                                                                                                 |
 | `doc-evolve`                | 1.0   | Key-document evolution per `docs/99_PROJECT_CONSTITUTION.md` — drift audits, same-commit sync checks, frontmatter-contract verification, machine-appended lessons                                                                          |
 | `reverse-engineering`       | 1.1   | Codebase analysis / HLD generation / audit — depth-driven reverse engineering with orthogonal mode, focus, and format controls; backs `/sp:dev-reverse`                                                                                    |
-| `issue-finding`             | 1.1   | Session-log forensics — multi-source discovery, bottleneck ranking, optional topic focus, CLI-gated fix task generation; backs `/sp:dev-find-issue`                                                                                        |
+| `issue-finding`             | 1.1   | Session-log forensics — multi-source discovery, bottleneck ranking, optional topic focus, CLI-gated fix task generation; **legacy path** — superseded by `history-anatomy` for indexed reporting; backs no current command; directly invocable as sp:issue-finding |
 | `conflict-finding`          | 1.0   | Authority-aware semantic audit — four-pillar (source/task/feature/authority) conflict discovery, claim-specific authority resolution, reproducible evidence, confirmed owner-routed remediation; backs `/sp:dev-find-conflict`             |
 | `next-feature`              | 1.0   | Prompt-first feature frontier prioritizer — sync-first precondition, B3 actionability gate (cited, never restated), tiered rubric over measured signals, D1–D4 defect proposals conforming to the restructure map schema; backs `/sp:dev-find-next` |
 | `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, eleven-section report contract, `enrich`/`validate` rubrics; no workflow launch, no JSONL fallback, no corpus mutation                                                                   |
+
+#### Bounded coexistence and retirement gate — `sp:issue-finding` (HA-S1 0661)
+
+`sp:issue-finding` remains packaged and directly invocable as the **legacy path**; `/sp:dev-find-issue` resolves to `sp:history-anatomy`. No logic is shared between them. This coexistence is _bounded_, not permanent — the retirement gate below is the contract:
+
+- **Parity fixtures** the new contract must cover before retirement is considered: typed history analysis; daily and focused range selection; repeated-work and error reporting; evidence and confidence; remediation proposals; performance analysis; process observations; positive patterns.
+- **Intentional exclusions, not gaps:** raw history-file parsing and task creation are deliberately out of scope for `history-anatomy`; a missing parity item is checked against this list before it counts as a gap.
+- **Adoption evidence:** successful `history-anatomy.yaml` workflow run records across both modes (`daily`, `ad-hoc`) and the available source families. No bespoke telemetry is added to count adoption.
+- **Review point:** one minor release or 30 days after this feature ships, whichever is later.
+- **Gate:** parity PASS + demonstrated use of both modes + no open high-impact regression + explicit operator approval. A failed gate records the missing evidence and one dated extension.
+- **Retirement is a separate change.** This feature removes nothing; `sp:issue-finding` stays until the operator approves a dedicated retirement change.
 
 Each skill directory contains:
 
@@ -338,11 +351,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
-**39 commands** (see the Command index above for the full list), organized by the surface they wrap:
+**38 commands** (see the Command index above for the full list), organized by the surface they wrap:
 
 | Prefix       | Count | Delegates to                                                                                                                                                                                                                                                                                                        | Purpose                                                                                |
 | ------------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
-| `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:issue-finding`, `sp:conflict-finding`, `sp:reverse-engineering`, `sp:pr-reviewing`, inline | The dev-workflow surface — planning, execution, batch, wrap-up, review/verify, hygiene |
+| `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 |
 | `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                            |
@@ -352,7 +365,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 39 `.md` files in `commands/` are the authoritative,
+**Commands as SSOT (ADR-032).** The 38 `.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.

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

@@ -1,37 +1,32 @@
 ---
-description: "Render the session-forensics report from imported history data (8 CLI-derivable sections plus 6 model-authored), identify bottlenecks and behavioral anti-patterns, and optionally create a structured fix task behind --create-task. Triggers: post-mortem, performance analysis, session review, find issues, identify bottlenecks"
+description: "Generate the daily or ad-hoc history-anatomy diagnostic report over already-imported history: the eleven-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"
 role: reviewer
-argument-hint: "[<topic>] [--sessions <glob>] [--source <auto|pi|claude|codex|gemini|opencode|antigravity|openclaw|omp|grok|agy|all>] [--feature <id>] [--template <meta|issue|standard>] [--priority <P0|P1|P2|P3>] [--severity <S0|S1|S2>] [--category <list>] [--since <iso>] [--until <iso>] [--top <n>] [--min-cost <duration>] [--strict-topic] [--create-task] [--agent <inline|auto|name>] [--json]"
-allowed-tools: ["Bash", "Read", "Write", "Grep", "Glob", "Skill"]
+argument-hint: "[<focus>] [--mode <daily|ad-hoc>] [--date <YYYY-MM-DD>] [--since <RFC3339>] [--until <RFC3339>] [--recompute] [--agent <inline|auto|name>] [--output <path>]"
+allowed-tools: ["Bash", "Read", "Skill"]
 ---
 
 # Dev Find Issue
 
-Wraps the **sp:issue-finding** skill — report-first session forensics over the history data plane.
-The CLI renders the 8 derivable report sections (`spur history report --mode forensics`); the skill
-identifies bottlenecks, proposes fixes, and — only with `--create-task` — generates a structured
-task file via `spur task create`.
+Wraps the **sp:history-anatomy** skill — the independent owner of diagnostic interpretation over
+already-imported history. The skill resolves the mode contract (daily is the default and uses the
+current local calendar day; ad-hoc requires a focus plus two ordered bounds), owns the report
+contract (eleven sections, closed finding taxonomy, evidence rules, recurrence ledger), and
+exposes the `enrich` and `validate` operations the `history-anatomy.yaml` workflow invokes.
+Publication is atomic and gated behind both the deterministic structure gate and independent
+evidence validation. This command never triggers an import.
 
 ## Argument Flags
 
-| Flag                                                                                                 | Description                                                                                                                   | Default    |
-| ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------- |
-| `[<topic>]`                                                                                          | Narrow the analysis to a topic.                                                                                               | omitted    |
-| `--sessions` `<glob>`                                                                                | Session log glob (fallback input).                                                                                            | recent     |
-| `--source` `<auto\|pi\|claude\|codex\|gemini\|opencode\|antigravity\|openclaw\|omp\|grok\|agy\|all>` | Agent source to scan (CLI vocabulary; `all` fans out, `auto` resolves at runtime).                                            | auto       |
-| `--feature` `<id>`                                                                                   | Attach the generated task to a feature.                                                                                       | omitted    |
-| `--template` `<meta\|issue\|standard>`                                                               | Task template shape (`--create-task` only); `issue` is the explicit single-finding override, `standard` the generic override. | meta       |
-| `--priority` `<P0\|P1\|P2\|P3>`                                                                      | Filter / assign task priority.                                                                                                | P2         |
-| `--severity` `<S0\|S1\|S2>`                                                                          | Filter / assign severity.                                                                                                     | all        |
-| `--category` `<list>`                                                                                | Comma list of categories to keep.                                                                                             | all        |
-| `--since` `<iso>`                                                                                    | Start of the scan window.                                                                                                     | configured |
-| `--until` `<iso>`                                                                                    | End of the scan window.                                                                                                       | now        |
-| `--top` `<n>`                                                                                        | Limit to top N findings.                                                                                                      | omitted    |
-| `--min-cost` `<duration>`                                                                            | Minimum wasted duration to report.                                                                                            | omitted    |
-| `--strict-topic`                                                                                     | Drop findings off-topic.                                                                                                      | off        |
-| `--create-task`                                                                                      | Generate a fix task for findings.                                                                                             | off        |
-| `--agent` `<inline\|auto\|name>`                                                                     | Who runs the model-bearing analysis.                                                                                          | omit       |
-| `--json`                                                                                             | Emit structured JSON.                                                                                                         | off        |
+| Flag                                   | Description                                                                                        | Default  |
+| -------------------------------------- | -------------------------------------------------------------------------------------------------- | -------- |
+| `[<focus>]`                            | Ad-hoc focus string (required in `--mode ad-hoc`; rejected in daily).                              | omitted  |
+| `--mode` `<daily\|ad-hoc>`             | Report mode. Daily uses the current local calendar day.                                            | daily    |
+| `--date` `<YYYY-MM-DD>`                | Selects that local calendar day (daily; DST-aware).                                                | today    |
+| `--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` `<inline\|auto\|name>`       | Execution surface selector.                                                                        | inline   |
+| `--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).
 
@@ -39,31 +34,15 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 
 ```
 /sp:dev-find-issue
-/sp:dev-find-issue "test-loop spinning"
-/sp:dev-find-issue --sessions "~/.omp/agent/sessions/-xprojects-spur-new/2026-07-29T*"
-/sp:dev-find-issue "L3 guard format discovery" --feature H51 --priority P1 --severity S1
-/sp:dev-find-issue --category test-loop,guard --min-cost 30m
-/sp:dev-find-issue --source claude --since 2026-07-28 --create-task --json
+/sp:dev-find-issue --date 2026-08-24
+/sp:dev-find-issue --mode ad-hoc --since 2026-08-01T00:00:00Z --until 2026-08-15T00:00:00Z "focus"
+/sp:dev-find-issue --recompute
 ```
 
-**Report-first (task 0556).** Default output is the markdown report to stdout; no task file is
-written. Task creation moved behind `--create-task`. `--use-history` and `--no-task` are removed:
-the history data plane is now the primary source (no flag needed), and the old report-only behavior
-is the new default. Raw JSONL remains a fallback under the three conditions documented in
-`sp:issue-finding`.
-
-**Data-plane preflight.** Forensics read the imported history plane as-is. If findings come back
-empty or stale, run `/sp:dev-history-load` (on-demand cumulative `spur history import` + analyze,
-checkpoint resume — task 0567) before re-running forensics; it owns the interactive preflight, while
-`spur history daily` owns the periodic cadence.
-
-**See also:** skill `sp:issue-finding` (SSOT), `/sp:dev-runall`, `/sp:dev-dogfood`,
-`sp:daily-summary`, `sp:reverse-engineering`.
-
 ## Implementation
 
-Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface), then invoke the issue-finding skill, forwarding all arguments:
+Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
 
 ```
-Skill(skill="sp:issue-finding", args="$ARGUMENTS")
+Skill(skill="sp:history-anatomy", args="$ARGUMENTS")
 ```

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

@@ -1,7 +1,7 @@
 ---
 description: Run a task — full pipeline (precheck→implement→test→review→approve→verify→record→done) or single-step (implement)
 role: coder
-argument-hint: "<wbs> [--mode <full|implement>] [--agent <inline|auto|name>] [--auto] [--next] [--wrap] [--continue]"
+argument-hint: "<wbs> [--mode <full|implement>] [--agent <inline|auto|name>] [--auto] [--next] [--wrap] [--continue] [--worktree [<name>]]"
 allowed-tools: ["Bash", "Read", "Write", "Edit", "Skill"]
 ---
 
@@ -20,12 +20,13 @@ Wraps the **sp:spur-dev** and **sp:code-implementation** skills.
 | `--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 |
 | `--continue` | Resume an interrupted task from its checkpoint. | off |
+| `--worktree` `[<name>]` | Run the task pipeline in an isolated git worktree; FF-merge on success, retain on failure. Bare `--worktree` creates a fresh tree; `--worktree <name>` adopts an existing worktree by name/path/branch. Full mode only. | off |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
 
 ## Usage
 
-/sp:dev-run <wbs> [--mode <full|implement>] [--agent <inline|auto|name>] [--auto] [--next] [--wrap] [--continue]
+/sp:dev-run <wbs> [--mode <full|implement>] [--agent <inline|auto|name>] [--auto] [--next] [--wrap] [--continue] [--worktree [<name>]]
 
 ## Implementation
 
@@ -40,12 +41,30 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 
 - `--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).
 
+`--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,
+`<name>` form adopts an existing worktree by name/path/branch). The lifecycle — dirty-tree precheck,
+creation or adoption, crash-safe `.spur/run/` marker, merge-or-retain, `--continue` re-entry — is
+`execution-batch.md` § Worktree isolation applied to a batch of one: marker `command` is `dev-run`
+and `selector` is the `<wbs>`, the derived branch is `sp/run-<wbs>-<short-id>`, and the success
+condition is the task reaching terminal `done` with no failed stage. A failing gate, a non-PASS
+verify verdict, or a HITL pause that ends the run all take the retention path.
+
+**`--worktree` is full-mode only.** `--worktree --mode implement` is **rejected**. `--mode implement`
+*is* the pipeline's implement stage and runs in whatever tree the driver already set up (bug-742);
+giving it a second worktree would split one task's evidence across two trees. Use `--worktree` on the
+full-mode invocation, which carries the implement stage with it.
+
+**`--worktree` corpus visibility.** While the task runs in a worktree, corpus writes (status
+transitions, evidence sections, kanban) land in the worktree copy; your main tree still shows the
+pre-run status until the FF-merge on success. This is expected, not a bug.
+
 **Mode split (load-bearing — bug-742)**
 
 | Mode | What runs | Must not do |
 | --- | --- | --- |
 | `--mode full` (default) | Interactive omit/inline: host-session driver over `task-pipeline.yaml`; explicit/headless executor: workflow subprocess | — |
-| `--mode implement` | Single implement competency via `sp:code-implementation` | Re-launch the full pipeline, `spur workflow run …task-pipeline…`, or `/sp:dev-run` **without** `--mode implement` |
+| `--mode implement` | Single implement competency via `sp:code-implementation` | Re-launch the full pipeline, `spur workflow run …task-pipeline…`, `/sp:dev-run` **without** `--mode implement`, or accept `--worktree` (rejected) |
 
 The pipeline's `implement` step invokes this command **only** as:
 

package/plugins/sp/lib/artifact-digest.generated.d.mts

@@ -0,0 +1,7 @@
+/**
+ * GENERATED by scripts/commands/bundle-plugin-lib.ts — do not edit.
+ * Source of truth: packages/domain/src/analytics/artifact-digest.ts (task 0669).
+ */
+export declare const ARTIFACT_ARRAY_CLASSIFICATION: Readonly<Record<string, 'ranked' | 'set'>>;
+export declare const RANKED_ARTIFACT_KEYS: ReadonlySet<string>;
+export declare function semanticArtifactDigest(artifactJson: unknown): string;