@gobing-ai/spur 0.3.47 → 0.3.49

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (148) hide show
  1. package/.claude-plugin/marketplace.json +1 -1
  2. package/config/config.example.yaml +94 -15
  3. package/config/transition-shims.json +33 -0
  4. package/config/workflows/basic.yaml +2 -0
  5. package/config/workflows/docs-pipeline.yaml +2 -0
  6. package/config/workflows/feature-dev.yaml +8 -0
  7. package/config/workflows/idea-pipeline.yaml +10 -0
  8. package/config/workflows/planning-pipeline.yaml +4 -0
  9. package/config/workflows/pr-review.yaml +338 -0
  10. package/config/workflows/task-pipeline.yaml +8 -0
  11. package/config/workflows/wayfinder-resolution.yaml +4 -0
  12. package/config/workflows/wrapup-pipeline.yaml +18 -1
  13. package/package.json +8 -8
  14. package/plugins/sp/README.md +9 -6
  15. package/plugins/sp/agents/expert-spur.md +1 -0
  16. package/plugins/sp/commands/dev-arch.md +2 -1
  17. package/plugins/sp/commands/dev-brainstorm.md +2 -1
  18. package/plugins/sp/commands/dev-changelog.md +1 -0
  19. package/plugins/sp/commands/dev-daily.md +1 -0
  20. package/plugins/sp/commands/dev-debug.md +2 -1
  21. package/plugins/sp/commands/dev-dogfood.md +2 -1
  22. package/plugins/sp/commands/{dev-featurechange.md → dev-feature-change.md} +8 -10
  23. package/plugins/sp/commands/dev-find-conflict.md +2 -1
  24. package/plugins/sp/commands/dev-find-issue.md +36 -43
  25. package/plugins/sp/commands/dev-find-next.md +5 -4
  26. package/plugins/sp/commands/dev-fixall.md +1 -0
  27. package/plugins/sp/commands/dev-gitmsg.md +1 -0
  28. package/plugins/sp/commands/dev-gtd.md +12 -12
  29. package/plugins/sp/commands/dev-handover.md +1 -0
  30. package/plugins/sp/commands/dev-history-load.md +63 -0
  31. package/plugins/sp/commands/dev-idea.md +1 -0
  32. package/plugins/sp/commands/dev-next.md +2 -1
  33. package/plugins/sp/commands/dev-parallel.md +2 -1
  34. package/plugins/sp/commands/dev-plan.md +2 -1
  35. package/plugins/sp/commands/dev-pr-review.md +39 -0
  36. package/plugins/sp/commands/dev-refine.md +5 -3
  37. package/plugins/sp/commands/dev-refineall.md +2 -1
  38. package/plugins/sp/commands/dev-refresh.md +2 -1
  39. package/plugins/sp/commands/dev-reverse.md +2 -1
  40. package/plugins/sp/commands/dev-review.md +2 -1
  41. package/plugins/sp/commands/dev-run.md +3 -2
  42. package/plugins/sp/commands/dev-runall.md +3 -2
  43. package/plugins/sp/commands/dev-simplify.md +2 -1
  44. package/plugins/sp/commands/dev-unit.md +2 -1
  45. package/plugins/sp/commands/dev-verify.md +2 -1
  46. package/plugins/sp/commands/dev-verifyall.md +2 -1
  47. package/plugins/sp/commands/dev-wrap.md +7 -5
  48. package/plugins/sp/commands/dev-wrapall.md +7 -5
  49. package/plugins/sp/commands/rule-add.md +1 -0
  50. package/plugins/sp/commands/rule-refine.md +1 -0
  51. package/plugins/sp/commands/rule-scan.md +1 -0
  52. package/plugins/sp/commands/spur-init.md +1 -0
  53. package/plugins/sp/commands/workflow-add.md +1 -0
  54. package/plugins/sp/commands/workflow-refine.md +1 -0
  55. package/plugins/sp/hooks/careful-guard.ts +5 -80
  56. package/plugins/sp/hooks/destructive-policy.ts +146 -0
  57. package/plugins/sp/hooks/pi/guard-extension.ts +33 -46
  58. package/plugins/sp/hooks/task-file-policy.ts +31 -0
  59. package/plugins/sp/hooks/task-write-guard.ts +4 -0
  60. package/plugins/sp/plugin.json +1 -1
  61. package/plugins/sp/references/roles.md +106 -0
  62. package/plugins/sp/scripts/feature-sync-bounded.ts +28 -2
  63. package/plugins/sp/scripts/history-load.ts +400 -0
  64. package/plugins/sp/scripts/pr-reviewing.ts +867 -0
  65. package/plugins/sp/scripts/stage-registry-adapter.ts +66 -31
  66. package/plugins/sp/scripts/surface-drift-inventory.ts +908 -0
  67. package/plugins/sp/scripts/task-size-precheck.ts +30 -4
  68. package/plugins/sp/scripts/transition-shim-check.ts +238 -0
  69. package/plugins/sp/scripts/validate-commands.ts +33 -2
  70. package/plugins/sp/scripts/validate-flag-contracts.ts +5 -2
  71. package/plugins/sp/skills/code-implementation/SKILL.md +9 -1
  72. package/plugins/sp/skills/code-verification/SKILL.md +29 -28
  73. package/plugins/sp/skills/issue-finding/SKILL.md +123 -141
  74. package/plugins/sp/skills/issue-finding/examples/expected-findings.json +1 -1
  75. package/plugins/sp/skills/issue-finding/references/session-formats.md +87 -90
  76. package/plugins/sp/skills/next-feature/SKILL.md +6 -6
  77. package/plugins/sp/skills/next-feature/references/handoff-routing.md +5 -5
  78. package/plugins/sp/skills/next-feature/references/signal-derivation.md +7 -2
  79. package/plugins/sp/skills/next-router/SKILL.md +1 -1
  80. package/plugins/sp/skills/parallel-execution/references/dispatch-surface.md +40 -2
  81. package/plugins/sp/skills/pr-reviewing/SKILL.md +285 -0
  82. package/plugins/sp/skills/spur-cli/SKILL.md +3 -0
  83. package/plugins/sp/skills/spur-cli/references/agent.md +12 -7
  84. package/plugins/sp/skills/spur-cli/references/features/hierarchy-mece.md +5 -5
  85. package/plugins/sp/skills/spur-cli/references/features.md +1 -1
  86. package/plugins/sp/skills/spur-cli/references/team.md +10 -3
  87. package/plugins/sp/skills/spur-dev/SKILL.md +2 -0
  88. package/plugins/sp/skills/spur-dev/references/ac-style-guide.md +17 -0
  89. package/plugins/sp/skills/spur-dev/references/cross-cutting.md +44 -23
  90. package/plugins/sp/skills/spur-dev/references/dev-operations.md +14 -11
  91. package/plugins/sp/skills/spur-dev/references/execution-workflow.md +14 -12
  92. package/plugins/sp/skills/spur-dev/references/flag-glossary.md +28 -7
  93. package/plugins/sp/skills/spur-dev/references/gate-checklists.md +2 -0
  94. package/plugins/sp/skills/spur-dev/references/inline-pipeline-driver.md +12 -2
  95. package/schemas/spur-config.schema.json +47 -3
  96. package/spur.js +12223 -7716
  97. package/web/_astro/BoardApp.8hiqShQn.js +1 -0
  98. package/web/_astro/{BoardApp.DKyrGxdo.js → BoardApp.BjQUNhuj.js} +74 -74
  99. package/web/_astro/{TaskDetail.6-27_LMa.js → TaskDetail.CVBuD6dF.js} +1 -1
  100. package/web/_astro/{arc.Df-9AQvS.js → arc.BMMjdODi.js} +1 -1
  101. package/web/_astro/{architectureDiagram-3BPJPVTR.VAI_-paS.js → architectureDiagram-3BPJPVTR.BU5ShzXf.js} +1 -1
  102. package/web/_astro/{blockDiagram-GPEHLZMM.DFpUY1ue.js → blockDiagram-GPEHLZMM.Bj1iEqPD.js} +1 -1
  103. package/web/_astro/{c4Diagram-AAUBKEIU.CF8doOpg.js → c4Diagram-AAUBKEIU.vX8wepCL.js} +1 -1
  104. package/web/_astro/channel.EwdSemIC.js +1 -0
  105. package/web/_astro/{chunk-2J33WTMH.BnjK3fjt.js → chunk-2J33WTMH.BKAipTym.js} +1 -1
  106. package/web/_astro/{chunk-4BX2VUAB.x6ZDnJKq.js → chunk-4BX2VUAB.B68XkPG7.js} +1 -1
  107. package/web/_astro/{chunk-55IACEB6.zY-0uu7w.js → chunk-55IACEB6.BmeDLcrc.js} +1 -1
  108. package/web/_astro/{chunk-727SXJPM.BZxKg_Vi.js → chunk-727SXJPM.PDuBA3Kw.js} +1 -1
  109. package/web/_astro/{chunk-AQP2D5EJ.Cpi9G9Td.js → chunk-AQP2D5EJ.C7A044za.js} +1 -1
  110. package/web/_astro/{chunk-FMBD7UC4.DWTB-Pif.js → chunk-FMBD7UC4.BtzKKFqR.js} +1 -1
  111. package/web/_astro/{chunk-ND2GUHAM.BPDQbiOG.js → chunk-ND2GUHAM.BJuDeeOy.js} +1 -1
  112. package/web/_astro/{chunk-QZHKN3VN.BRWIcuoM.js → chunk-QZHKN3VN.DSeMDgcQ.js} +1 -1
  113. package/web/_astro/{classDiagram-4FO5ZUOK.mGTCZsDO.js → classDiagram-4FO5ZUOK.D53Q4tCw.js} +1 -1
  114. package/web/_astro/{classDiagram-v2-Q7XG4LA2.mGTCZsDO.js → classDiagram-v2-Q7XG4LA2.D53Q4tCw.js} +1 -1
  115. package/web/_astro/{cose-bilkent-S5V4N54A.D1GEut-z.js → cose-bilkent-S5V4N54A.c712AFRH.js} +1 -1
  116. package/web/_astro/{dagre-BM42HDAG.BV0XG9Do.js → dagre-BM42HDAG.D-idisph.js} +1 -1
  117. package/web/_astro/{diagram-2AECGRRQ.DzpYxsjo.js → diagram-2AECGRRQ.DLgnsJCU.js} +1 -1
  118. package/web/_astro/{diagram-5GNKFQAL.Cm9YzJh4.js → diagram-5GNKFQAL.BiaxBVqx.js} +1 -1
  119. package/web/_astro/{diagram-KO2AKTUF.BjhottUj.js → diagram-KO2AKTUF.C8HX1vd8.js} +1 -1
  120. package/web/_astro/{diagram-LMA3HP47.BFsQW5kb.js → diagram-LMA3HP47.CfqDLLes.js} +1 -1
  121. package/web/_astro/{diagram-OG6HWLK6.8pdpzSWO.js → diagram-OG6HWLK6.15SDiEed.js} +1 -1
  122. package/web/_astro/{erDiagram-TEJ5UH35.Bd7KUJmJ.js → erDiagram-TEJ5UH35.DksYtOYM.js} +1 -1
  123. package/web/_astro/{flowDiagram-I6XJVG4X.7LWffkaE.js → flowDiagram-I6XJVG4X.DR_Au-HV.js} +1 -1
  124. package/web/_astro/{ganttDiagram-6RSMTGT7.BeDcO5tI.js → ganttDiagram-6RSMTGT7.CHhHrffI.js} +1 -1
  125. package/web/_astro/{gitGraphDiagram-PVQCEYII.Ca4n730A.js → gitGraphDiagram-PVQCEYII.B2Xehvam.js} +1 -1
  126. package/web/_astro/{index.Dbvuw6d4.css → index.DAxu50UF.css} +1 -1
  127. package/web/_astro/{infoDiagram-5YYISTIA.B0OakQYb.js → infoDiagram-5YYISTIA.C9c3CNNN.js} +1 -1
  128. package/web/_astro/{ishikawaDiagram-YF4QCWOH.DSmNQe-1.js → ishikawaDiagram-YF4QCWOH.BibUHkh8.js} +1 -1
  129. package/web/_astro/{journeyDiagram-JHISSGLW.Cy5ruEUu.js → journeyDiagram-JHISSGLW.BYoVHiyO.js} +1 -1
  130. package/web/_astro/{kanban-definition-UN3LZRKU.CUJXub0p.js → kanban-definition-UN3LZRKU.CM1K5wHE.js} +1 -1
  131. package/web/_astro/{linear.DC1jCCXn.js → linear.SPpjJUb-.js} +1 -1
  132. package/web/_astro/{mermaid.core.DxVP99Ab.js → mermaid.core.BAgx3nnb.js} +4 -4
  133. package/web/_astro/{mindmap-definition-RKZ34NQL.D0MaV6sJ.js → mindmap-definition-RKZ34NQL.D35oPG1R.js} +1 -1
  134. package/web/_astro/{pieDiagram-4H26LBE5.DCC6_q32.js → pieDiagram-4H26LBE5.DiWuRwk7.js} +1 -1
  135. package/web/_astro/{quadrantDiagram-W4KKPZXB.BeUOAM7C.js → quadrantDiagram-W4KKPZXB.B9PBzTWn.js} +1 -1
  136. package/web/_astro/{requirementDiagram-4Y6WPE33.Dbl4MASO.js → requirementDiagram-4Y6WPE33.CYuuamFN.js} +1 -1
  137. package/web/_astro/{sankeyDiagram-5OEKKPKP.HsLg0VS4.js → sankeyDiagram-5OEKKPKP.W24UhhtD.js} +1 -1
  138. package/web/_astro/{sequenceDiagram-3UESZ5HK.DT7DJTnZ.js → sequenceDiagram-3UESZ5HK.BpbNjA51.js} +1 -1
  139. package/web/_astro/{stateDiagram-AJRCARHV.d_ju1Vr1.js → stateDiagram-AJRCARHV.DqVsHudf.js} +1 -1
  140. package/web/_astro/{stateDiagram-v2-BHNVJYJU.DMCAjMJ4.js → stateDiagram-v2-BHNVJYJU.CzwHYX81.js} +1 -1
  141. package/web/_astro/{timeline-definition-PNZ67QCA.DNOHr62_.js → timeline-definition-PNZ67QCA.Bc3B6djw.js} +1 -1
  142. package/web/_astro/{vennDiagram-CIIHVFJN.B7dUy-1W.js → vennDiagram-CIIHVFJN.C-D5rh8O.js} +1 -1
  143. package/web/_astro/{wardley-L42UT6IY.DEqOXvBh.js → wardley-L42UT6IY.D7PdYCqn.js} +1 -1
  144. package/web/_astro/{wardleyDiagram-YWT4CUSO.BCRb2p6x.js → wardleyDiagram-YWT4CUSO.CwmJKXF3.js} +1 -1
  145. package/web/_astro/{xychartDiagram-2RQKCTM6.NxVQLdBh.js → xychartDiagram-2RQKCTM6.avDYnLsb.js} +1 -1
  146. package/web/index.html +2 -2
  147. package/web/_astro/BoardApp.Ce6zJYAH.js +0 -1
  148. package/web/_astro/channel.Uhm9O3UV.js +0 -1
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  name: issue-finding
3
- description: "Analyze agent session logs, find performance bottlenecks, propose fixes, and generate a structured task file. Triggers: find issues, post-mortem, session review, topic focus."
3
+ description: "Render the session forensics report, analyze agent session logs, find performance bottlenecks, propose fixes, and optionally create a structured task. Triggers: find issues, post-mortem, session review, topic focus."
4
4
  license: Apache-2.0
5
- version: 1.1.0
5
+ version: 2.0.0
6
6
  metadata:
7
7
  author: spur
8
8
  platforms: "claude-code,codex,openclaw,opencode,antigravity,pi"
@@ -11,8 +11,7 @@ metadata:
11
11
  - pipeline
12
12
  - inversion
13
13
  pipeline_steps:
14
- - discover
15
- - analyze
14
+ - report
16
15
  - identify
17
16
  - propose
18
17
  - generate
@@ -30,11 +29,13 @@ see_also:
30
29
 
31
30
  # sp:issue-finding — Session Log Issue Finder
32
31
 
33
- Review agent session logs, identify performance bottlenecks and behavioral anti-patterns, propose
34
- fixes, and generate a structured task file capturing findings for future execution.
32
+ Render the forensic report for agent session logs, identify performance bottlenecks and behavioral
33
+ anti-patterns, propose fixes, and only with `--create-task` create a structured task file.
35
34
 
36
- This skill codifies the forensic session-log analysis performed after the J4 batch execution
37
- (task 0379), making the process reusable for any set of agent sessions.
35
+ **Default output is a report, not a task** (task 0556): the typed data plane
36
+ (`spur history report --mode forensics`) renders the quantitative sections; this skill authors the
37
+ interpretation on top. It codifies the forensic analysis performed after the J4 batch execution
38
+ (task 0379), reusable for any set of agent sessions.
38
39
 
39
40
  **Honesty contract:** install-time skill packaging works on all declared platforms. **Native
40
41
  session forensics depth varies by agent** — OMP is the deepest documented adapter; other sources
@@ -61,23 +62,23 @@ bottlenecks", "post-mortem", "what went wrong", "why was this slow"
61
62
 
62
63
  ## Arguments
63
64
 
64
- | Argument | Description | Default |
65
- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
66
- | `[topic]` | Optional free-text focus or smart positional input (see below). Narrows IDENTIFY/PROPOSE/GENERATE; DISCOVER still inventories selected sessions. | (full taxonomy) |
67
- | `--sessions <glob>` | Session JSONL file(s) or directory to analyze. When omitted, uses the most recent sessions for the resolved source + current project. | (most recent) |
65
+ | Argument | Description | Default |
66
+ | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
67
+ | `[topic]` | Optional free-text focus or smart positional input (see below). Narrows IDENTIFY/PROPOSE/GENERATE; the report still covers all selected sessions. | (full taxonomy) |
68
+ | `--sessions <glob>` | Session JSONL file(s) or directory to analyze. When omitted, uses the most recent sessions for the resolved source + current project. Pins the raw-fallback path (below). | (most recent) |
68
69
  | `--source <name>` | Session log source: `auto`, `omp`, `claude`, `codex`, `gemini`, `opencode`, `antigravity`, `openclaw`, `pi`. `auto` = cwd agent when known, else `omp` if present, else first existing default root. | `auto` |
69
- | `--feature <id>` | Feature ID to link the generated task to (e.g., `H51`). | (none) |
70
- | `--template <name>` | Task template: `meta` (multi-fix umbrella), `issue` (single finding), or `standard`. | `meta` |
71
- | `--priority <P0\|P1\|P2\|P3>` | **Task** priority frontmatter (`spur task update --priority`). Not bottleneck severity. | `P2` |
72
- | `--severity <S0\|S1\|S2>` | Minimum **bottleneck** severity to keep after ranking (S0 most severe). | (all) |
73
- | `--category <list>` | Comma-separated bottleneck categories to keep (see IDENTIFY table ids). | `all` |
74
- | `--since <iso>` / `--until <iso>` | Optional wall-clock bounds on session start times (when timestamps are available). | (none) |
75
- | `--top <n>` | Cap the number of requirements / fixes written into the task. | (no cap) |
76
- | `--min-cost <duration>` | Drop bottlenecks whose estimated waste is below this floor (e.g. `30m`, `2h`). Applied after severity ranking. | (none) |
77
- | `--strict-topic` | When `[topic]` is set, drop off-topic bottlenecks even if they dominate wall time. | off |
78
- | `--use-history` | Optionally import/analyze via `spur history` for token/cost aggregates; raw JSONL remains authoritative for tool-loop forensics. | off |
79
- | `--no-task` | Markdown report to stdout only; do not create a task. | off |
80
- | `--json` | JSON findings to stdout only; do not create a task. Mutually exclusive with default task creation. | off |
70
+ | `--feature <id>` | Feature ID to link the generated task to (e.g., `H51`). | (none) |
71
+ | `--template <name>` | Task template: `meta` (multi-fix umbrella), `issue` (single finding), or `standard`. | `meta` |
72
+ | `--priority <P0\|P1\|P2\|P3>` | **Task** priority frontmatter (`spur task update --priority`). Not bottleneck severity. | `P2` |
73
+ | `--severity <S0\|S1\|S2>` | Minimum **bottleneck** severity to keep after ranking (S0 most severe). | (all) |
74
+ | `--category <list>` | Comma-separated bottleneck categories to keep (see IDENTIFY table ids). | `all` |
75
+ | `--since <iso>` / `--until <iso>` | Optional wall-clock bounds on session start times (when timestamps are available). | (none) |
76
+ | `--top <n>` | Cap the number of requirements / fixes written into the task. | (no cap) |
77
+ | `--min-cost <duration>` | Drop bottlenecks whose estimated waste is below this floor (e.g. `30m`, `2h`). Applied after severity ranking. | (none) |
78
+ | `--strict-topic` | When `[topic]` is set, drop off-topic bottlenecks even if they dominate wall time. | off |
79
+ | `--agent <name>` | Narrow sessions to one agent/subagent executor name. | (all agents) |
80
+ | `--create-task` | Opt **in** to task creation (GENERATE). Default mode stops after the report. | off |
81
+ | `--json` | JSON findings to stdout instead of the markdown report. Composable with `--create-task`. | off |
81
82
 
82
83
  ### Smart positional `[topic]`
83
84
 
@@ -104,54 +105,68 @@ Severity thresholds:
104
105
 
105
106
  ### Output mode matrix
106
107
 
107
- | Flags | Create task | Stdout |
108
- | ---------------------- | ----------- | --------------------- |
109
- | (default) | yes | short summary + WBS |
110
- | `--no-task` | no | markdown report |
111
- | `--json` | no | JSON only |
112
- | `--no-task` + `--json` | no | JSON only (json wins) |
108
+ | Flags | Create task | Stdout |
109
+ | ---------------------- | ----------- | ------------------------------- |
110
+ | (default) | no | markdown report |
111
+ | `--json` | no | JSON findings (`task: null`) |
112
+ | `--create-task` | yes | short summary + WBS |
113
+ | `--create-task --json` | yes | JSON findings with `task` block |
113
114
 
114
- Never invent a dual-write mode: either create a task **or** emit a report/JSON, not both.
115
+ Without `--create-task` the run is report-only never create a task unasked.
115
116
 
116
- ## The 5-Phase Protocol
117
+ ### Removed flags (task 0556)
118
+
119
+ | Removed flag | Old behavior | Replacement |
120
+ | --------------- | ------------------------------------ | ---------------------------------------------------------------------- |
121
+ | `--use-history` | Opt in to the `spur history` bridge | None — the typed data plane is now the default REPORT path |
122
+ | `--no-task` | Report to stdout, skip task creation | None — report-only is the default; pass `--create-task` to opt **in** |
123
+
124
+ If an invocation passes either removed flag, do not swallow it as generic unknown-option noise:
125
+ reject the invocation with a message naming the replacement above.
126
+
127
+ ## The 4-Phase Protocol
117
128
 
118
129
  ```
119
- sessions (JSONLsource-dependent roots; see session-formats.md)
120
- DISCOVER locate session logs; build session inventory with timestamps
121
- → ANALYZE extract metrics: tool calls, compactions, test runs, guard failures
130
+ sessions (typed ETL via `spur history` or raw JSONL under the three fallback conditions)
131
+ REPORT render the forensic report: 8 CLI-derivable sections; author analysis on top
122
132
  → IDENTIFY rank bottlenecks by time cost; filter by topic/category/severity
123
133
  → PROPOSE design fixes for in-scope root causes; estimate time savings
124
- → GENERATE create a structured task via `spur task create` (unless --no-task/--json)
134
+ → GENERATE create a structured task via `spur task create` (only with --create-task)
125
135
  ```
126
136
 
127
- ### Phase 1: DISCOVERSession Inventory
137
+ ### Phase 1: REPORTData plane first
128
138
 
129
- **Goal:** Locate and catalog the session logs to analyze.
139
+ **Primary path (typed sources):** `spur history report --mode forensics` (task 0555).
130
140
 
131
- **Steps:**
141
+ ```bash
142
+ # 0568 R4: SPUR_BIN env > local CLI > PATH — stale PATH spur fails history import.
143
+ SPUR_BIN="${SPUR_BIN:-$([ -f apps/cli/src/index.ts ] && echo 'bun apps/cli/src/index.ts' || echo spur)}"
132
144
 
133
- 1. Resolve `--source` (or `auto`) and default roots from
134
- [references/session-formats.md](references/session-formats.md).
135
- 2. If `[topic]` or `--sessions` already selects paths, use those files.
136
- 3. Otherwise list the source root for the current project slug and take the most recent
137
- timestamped session set (include subagent session files when the layout has them).
138
- 4. Apply `--since` / `--until` when session start timestamps are available.
139
- 5. Build a session inventory table:
145
+ $SPUR_BIN history import --source <source> --json # checkpoint resume
146
+ $SPUR_BIN history analyze --json # writes versioned artifact (0554)
147
+ $SPUR_BIN history report --mode forensics # pure renderer; latest artifact pointer
148
+ ```
140
149
 
141
- | Session | File | Start Time | End Time | Duration |
142
- | ------- | --------------------------- | ---------- | -------- | -------- |
143
- | Main | `…/*.jsonl` | … | … | … |
144
- | Run0376 | subdirectory / subagent log | … | … | … |
150
+ The forensics renderer emits **8 CLI-derivable sections**: Session Data Summary, Tool Breakdown,
151
+ Token Profile (tokens + cache-hit ratio never prices), Time Decomposition, Per-Phase, Per-Tool
152
+ Execution Time, Bottleneck Ranking, and the Raw Data appendix. The CLI does not write the
153
+ interpretation: IDENTIFY and PROPOSE below author the root-cause narrative, fix design, and
154
+ acceptance criteria on top of the rendered data — that analysis is why this skill exists.
145
155
 
146
- 6. Compute total wall time across all sessions. State the resolved source and confidence
147
- (High = known adapter + readable tool events; Medium = path found, format partial;
148
- Low = operator-supplied paths only).
156
+ **Raw JSONL fallback exactly three conditions** (0492 R7):
149
157
 
150
- ### Phase 2: ANALYZE Metric Extraction
158
+ 1. The resolved `--source` has **no typed mapper** in the importer.
159
+ 2. The operator passed **explicit `--sessions`** — respect the pin; do not reconcile the pinned
160
+ files against the database.
161
+ 3. You need a **primitive the typed tables do not retain** (e.g. identical-command loop strings) —
162
+ parse raw lines for just that primitive and keep the data plane for the rest.
151
163
 
152
- **Goal:** Extract quantitative metrics from each session's JSONL log.
164
+ A source with a typed mapper must **not** trigger wholesale raw parsing. If an import fails or the
165
+ DB is empty, note that aggregate data is unavailable and fall back strictly per the conditions
166
+ above.
153
167
 
154
- **Portable signals to count** (map field names per source — see session-formats.md):
168
+ **Fallback parser — portable signals to count** (map field names per source — see
169
+ [references/session-formats.md](references/session-formats.md)):
155
170
 
156
171
  | Signal | Metric |
157
172
  | --------------------------------------------------------------------- | -------------------------------- |
@@ -164,34 +179,11 @@ sessions (JSONL — source-dependent roots; see session-formats.md)
164
179
  | Identical command string repeated 3+ times | Loop candidate |
165
180
 
166
181
  **Extraction approach:** read each JSONL file line-by-line; parse tool name + command inputs;
167
- count identical commands for loop detection.
168
-
169
- Produce per-session metrics (duration, tools, compactions, test runs, spur calls, guard failures,
170
- key finding). Aggregate totals across sessions.
171
-
172
- When `--use-history` is set, the **selected-file history bridge** supplies ETL aggregates for the
173
- frozen session set (task 0507 R3):
174
-
175
- 1. **Freeze Phase 1's selected OMP JSONL files once** — the same inventory the raw analysis reads.
176
- Discovery roots: the normal OMP session root (`~/.omp/agent/sessions/`) **and**
177
- `.spur/run/<run-id>/agent-sessions/<omp-executor>/*.jsonl` for workflow subprocess sessions.
178
- Never import a broad `.spur/run` scan and never run a full/source-root reconciliation here.
179
- 2. **Import each frozen file once, through the source-local CLI**, with single-file `force-file`
180
- mode:
181
- `bun run apps/cli/src/index.ts history import --source omp --file <absolute-file> --mode force-file --json`.
182
- The importer derives the session key from the filename; use the same stem for analysis.
183
- 3. **Analyze scoped to that key**: `history analyze --session <filename-stem> --json`.
184
- 4. Use the artifact for the aggregates ETL can represent — tokens, cost, messages, tool calls,
185
- loops, and assistant response duration. **Continue parsing the same raw files** for command text,
186
- compactions, test/guard retries, tool execution duration/status/errors, and every other signal
187
- the ETL does not carry.
188
-
189
- ETL supplies normalized aggregates; it is **not** a substitute for raw tool-loop evidence. If an
190
- import fails or the DB is empty, continue with raw logs and note that cost data is unavailable.
191
- Before any ad-hoc verification SQL against `history_*` tables, follow the schema-first rule in
192
- [references/session-formats.md](references/session-formats.md) — inspect the live schema once.
193
-
194
- ### Phase 3: IDENTIFY — Root Cause Ranking
182
+ count identical commands for loop detection. Produce per-session metrics (duration, tools,
183
+ compactions, test runs, spur calls, guard failures, key finding) plus aggregate totals. Discovery
184
+ roots for the fallback path are in [references/session-formats.md](references/session-formats.md).
185
+
186
+ ### Phase 2: IDENTIFY — Root Cause Ranking
195
187
 
196
188
  **Goal:** Rank bottlenecks by estimated time cost; apply topic / category / severity filters.
197
189
 
@@ -223,7 +215,7 @@ Before any ad-hoc verification SQL against `history_*` tables, follow the schema
223
215
 
224
216
  Also note **what worked well** so efficient patterns are preserved.
225
217
 
226
- ### Phase 4: PROPOSE — Fix Design
218
+ ### Phase 3: PROPOSE — Fix Design
227
219
 
228
220
  **Goal:** Design a concrete fix for each **in-scope** root cause.
229
221
 
@@ -245,9 +237,10 @@ When the same anti-pattern appears across **≥2 independent sessions** (or the
245
237
  codify it), offer a handoff to **`/sp:rule-scan`** / rule authoring after GENERATE — do not invent
246
238
  rules inside this skill.
247
239
 
248
- ### Phase 5: GENERATE — Task File Creation
240
+ ### Phase 4: GENERATE — Task File Creation
249
241
 
250
- **Goal:** Create a structured task via CLI-gated corpus writes (unless `--no-task` / `--json`).
242
+ **Goal:** Create a structured task via CLI-gated corpus writes (`--create-task` only; default
243
+ mode stops after the report).
251
244
 
252
245
  **Task creation (correct CLI — do not invent flags):**
253
246
 
@@ -258,25 +251,15 @@ spur task create "Fix <context> performance bottlenecks: <top issues>" \
258
251
  --json
259
252
  ```
260
253
 
261
- Notes:
262
-
263
254
  - Title is the **positional** argument (there is no `--name`).
264
255
  - Template is space form `--template meta` (or `issue` / `standard`); never the dotted form.
256
+ - Single-finding tasks: prefer `--template issue`; multi-requirement umbrella: keep `meta`.
265
257
  - Priority is **not** available on create. After create:
266
258
 
267
259
  ```bash
268
260
  spur task update <wbs> --priority P2 --json
269
261
  ```
270
262
 
271
- - If `--feature` was omitted at create time and the operator later supplies one:
272
-
273
- ```bash
274
- spur task update <wbs> --feature <feature-id> --json
275
- ```
276
-
277
- - Single-finding tasks: prefer `--template issue` (aligned with `sp:sys-debugging`).
278
- - Multi-requirement umbrella: keep `--template meta` (default).
279
-
280
263
  **Section population** — write each section body to a temp file, then:
281
264
 
282
265
  ```bash
@@ -304,7 +287,7 @@ spur task update <wbs> --section Background --from-file /tmp/issue-bg.md --json
304
287
  **Section format rules** (from task 0379):
305
288
 
306
289
  1. **Solution `file:line` citations**: repo-relative `file:line` (e.g. `apps/web/src/components/SupervisorTab.tsx:17-20`), never bare `:line` or bare filename without path.
307
- 2. **Review P1–P4 table**: if a Review section exists, include a markdown table with a cell matching
290
+ 2. **Review P1–P4 table**: if a Review section exists, include a table with a cell matching
308
291
  `/^\s*P[1-4]\s*$/` and a non-placeholder content cell.
309
292
  3. **Meta template**: no `Root Cause` section — put analyses in `Notes`.
310
293
  4. **Canonical sections only**: `Background`, `Requirements`, `Acceptance Criteria`, `Q&A`,
@@ -324,10 +307,12 @@ Must return `pass: true` with 0 errors. Warnings may be acceptable on meta tasks
324
307
 
325
308
  ## Output
326
309
 
327
- **Default:** A task file under the configured tasks folder (`docs/tasks/`, `docs/tasks3/`, …) with
328
- WBS, optional feature link, and structured sections.
310
+ **Default:** markdown report on stdout the 8 CLI-derivable forensics sections (when the data
311
+ plane path applies) plus the model-authored IDENTIFY/PROPOSE analysis.
329
312
 
330
- **With `--no-task`:** Markdown findings report on stdout.
313
+ **With `--create-task`:** a task file under the configured tasks folder (`docs/tasks/`,
314
+ `docs/tasks3/`, …) with WBS, optional feature link, and structured sections, plus a short summary
315
+ with the WBS.
331
316
 
332
317
  **With `--json`:**
333
318
 
@@ -351,42 +336,36 @@ WBS, optional feature link, and structured sections.
351
336
  }
352
337
  ```
353
338
 
354
- When a task was created (default mode), include `"task": { "wbs": "…", "file": "…", "status": "…" }`
355
- in the short summary; JSON-only mode leaves `task` null.
339
+ With `--create-task`, include `"task": { "wbs": "…", "file": "…", "status": "…" }`; otherwise
340
+ `task` stays `null`.
356
341
 
357
342
  ## Integration
358
343
 
359
- - **Session log parsing** — manual JSONL analysis (no required external analyzer script)
344
+ - **Session forensics report** — `spur history report --mode forensics` (primary data plane)
360
345
  - **Multi-source roots / field maps** — [references/session-formats.md](references/session-formats.md)
361
- - **Optional** `spur history import` / `analyze` when `--use-history`
346
+ - **Raw JSONL fallback** only under the three conditions in Phase 1
362
347
  - **`spur task create` / `update` / `check`** — CLI-gated corpus only (never direct-write task files)
363
348
 
364
349
  ## Required Permissions
365
350
 
366
- | Capability | Purpose |
367
- | --------------- | ------------------------------------- |
368
- | `Read` | Session JSONL, skill/source files |
369
- | `Grep` / `Glob` | Pattern search and session discovery |
370
- | `Bash` | `spur task` / optional `spur history` |
371
- | `Write` | Temp files for section bodies |
351
+ | Capability | Purpose |
352
+ | --------------- | ------------------------------------ |
353
+ | `Read` | Session JSONL, skill/source files |
354
+ | `Grep` / `Glob` | Pattern search and session discovery |
355
+ | `Bash` | `spur history` + `spur task` CLI |
356
+ | `Write` | Temp files for section bodies |
372
357
 
373
358
  ## Platform Notes
374
359
 
375
- ### Claude Code
376
-
377
- - Invoke via `/sp:dev-find-issue …` or `Skill(skill="sp:issue-finding", args="…")`.
378
- - Prefer structured tools for file discovery; parse JSONL with Read/Grep.
379
-
380
- ### Codex / OpenClaw / OpenCode / Antigravity / Pi
381
-
382
- - Read this skill and follow the 5-phase protocol (slash commands may be adapted at install time).
383
- - Prefer `rg` for scanning large JSONL; expand globs carefully.
384
- - If the agent’s session root differs from the table in session-formats.md, require `--sessions`.
385
-
386
- ### Multi-agent reality
387
-
388
- - Packaging is portable; **forensic fidelity is source-dependent**.
389
- - When unsure of layout, ask once for a session path or use `--sessions` rather than guessing.
360
+ - **Claude Code** — invoke via `/sp:dev-find-issue …` or `Skill(skill="sp:issue-finding",
361
+ args="…")`. Prefer structured tools for file discovery; parse JSONL with Read/Grep only on the
362
+ fallback path.
363
+ - **Other platforms** (Codex / OpenClaw / OpenCode / Antigravity / Pi) — follow the 4-phase
364
+ protocol (slash commands may be adapted at install time); prefer `rg` for large JSONL on the
365
+ fallback path. If the agent's session root differs from the session-formats.md table, require
366
+ `--sessions`.
367
+ - **Multi-agent reality** packaging is portable; **forensic fidelity is source-dependent**. When
368
+ unsure of layout, ask once for a session path or use `--sessions` rather than guessing.
390
369
 
391
370
  ## Shipped command
392
371
 
@@ -398,38 +377,41 @@ Thin wrapper: `Skill(skill="sp:issue-finding", args="$ARGUMENTS")`.
398
377
  /sp:dev-find-issue
399
378
  /sp:dev-find-issue "test-loop spinning"
400
379
  /sp:dev-find-issue --sessions "~/.omp/agent/sessions/-xprojects-spur-new/2026-07-29T*" --feature H51
401
- /sp:dev-find-issue "L3 guard format discovery" --source omp --severity S1 --priority P1
402
- /sp:dev-find-issue --category test-loop,guard --no-task
380
+ /sp:dev-find-issue --category test-loop,guard
381
+ /sp:dev-find-issue --create-task "J4 batch bottlenecks" --template meta --priority P1
403
382
  /sp:dev-find-issue --json --source claude --since 2026-07-28
404
383
  ```
405
384
 
406
385
  ## Common rationalizations
407
386
 
408
- | Rationalization | Reality |
409
- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
410
- | "Sessions are huge — I'll sample randomly." | Prefer signal Grep first, then deep-read hot regions. Random samples invent severity. |
411
- | "I'll just write the task file with Write." | Corpus writes are CLI-gated (`spur task create` / `update`). Direct Write fails the harness contract. |
412
- | "OMP format everywhere." | Only OMP is High-fidelity documented. Other sources need portable field maps + `--sessions` when roots differ. |
413
- | "P0 severity means task priority P0." | Severity (S0–S2) ranks waste; `--priority` is separate task frontmatter (P0–P3). |
414
- | "History import replaces JSONL forensics." | History gives token/cost aggregates; tool-loop loops still need raw session lines. |
387
+ | Rationalization | Reality |
388
+ | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
389
+ | "Sessions are huge — I'll sample randomly." | Prefer signal Grep first, then deep-read hot regions. Random samples invent severity. |
390
+ | "I must hand-parse JSONL for everything." | The typed data plane renders 8 sections. Raw parsing is only for the three fallback conditions. |
391
+ | "I'll just write the task file with Write." | Corpus writes are CLI-gated (`spur task create` / `update`). Direct Write fails the harness contract. |
392
+ | "OMP format everywhere." | Only OMP is High-fidelity documented. Other sources need portable field maps + `--sessions` when roots differ. |
393
+ | "P0 severity means task priority P0." | Severity (S0–S2) ranks waste; `--priority` is separate task frontmatter (P0–P3). |
394
+ | "The CLI report is the whole deliverable." | The renderer emits data; the model-authored IDENTIFY/PROPOSE analysis makes it actionable. |
415
395
 
416
396
  ## Red flags
417
397
 
398
+ - Creating a task without `--create-task` (default mode is report-only).
399
+ - Wholesale raw JSONL parsing when the source has a typed mapper.
400
+ - Accepting `--use-history` or `--no-task` silently instead of naming their replacements.
418
401
  - GENERATE recipes inventing a title flag, dotted template forms, or quoted dotted section flags.
419
402
  - Claiming multi-agent forensics without stating source confidence (High/Medium/Low).
420
- - Creating a task when `--no-task` or `--json` was requested.
421
- - Skipping batch section writes + single `spur task check`.
403
+ - Skipping batch section writes + single `spur task check` (when generating).
422
404
  - Emitting empty findings without inventorying sessions first.
423
405
 
424
406
  ## Dogfood / self-check fixture
425
407
 
426
408
  A tiny synthetic OMP session lives under
427
409
  [examples/session-test-loop.jsonl](examples/session-test-loop.jsonl) with expected categories in
428
- [examples/expected-findings.json](examples/expected-findings.json). Use it to smoke-check IDENTIFY
429
- without real operator logs:
410
+ [examples/expected-findings.json](examples/expected-findings.json). Use it to smoke-check the
411
+ fallback parser without real operator logs (explicit `--sessions` is fallback condition 2):
430
412
 
431
413
  ```
432
- /sp:dev-find-issue --sessions plugins/sp/skills/issue-finding/examples/session-test-loop.jsonl --no-task
414
+ /sp:dev-find-issue --sessions plugins/sp/skills/issue-finding/examples/session-test-loop.jsonl
433
415
  ```
434
416
 
435
417
  Expect at least the `test-loop` category (and whatever else the expected-findings file lists).
@@ -23,5 +23,5 @@
23
23
  "minCompactions": 6
24
24
  }
25
25
  ],
26
- "smokeCommand": "/sp:dev-find-issue --sessions plugins/sp/skills/issue-finding/examples/session-test-loop.jsonl --no-task"
26
+ "smokeCommand": "/sp:dev-find-issue --sessions plugins/sp/skills/issue-finding/examples/session-test-loop.jsonl"
27
27
  }