@gobing-ai/spur 0.4.8 → 0.4.10
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.
- package/.claude-plugin/marketplace.json +1 -1
- package/config/pipeline-budgets.json +2 -2
- package/config/rules/README.md +1 -1
- package/config/rules/boundary/config-loading-ownership.yaml +1 -0
- package/config/rules/boundary/env-var-hygiene.yaml +0 -1
- package/config/rules/boundary/sp-plugin-standalone.yaml +1 -1
- package/config/rules/boundary/sp-script-placement.yaml +3 -3
- package/config/rules/docs/sourced-api-claims.yaml +29 -64
- package/config/rules/strict/runtime-boundaries.yaml +40 -1
- package/config/rules/structure/protected-files.yaml +1 -1
- package/config/rules/surface/check-cli-surface.yaml +33 -0
- package/config/rules/typescript/no-debugger.yaml +3 -0
- package/config/workflow-candidates.json +2 -2
- package/config/workflows/feature-verification.yaml +6 -19
- package/config/workflows/history-anatomy.yaml +14 -28
- package/config/workflows/idea-pipeline.yaml +6 -19
- package/config/workflows/pr-review.yaml +9 -16
- package/config/workflows/task-pipeline.yaml +18 -25
- package/config/workflows/wrapup-pipeline.yaml +21 -63
- package/package.json +3 -3
- package/plugins/sp/README.md +70 -37
- package/plugins/sp/agents/expert-spur.md +0 -1
- package/plugins/sp/agents/super-planner.md +5 -5
- package/plugins/sp/agents/super-reviewer.md +2 -2
- package/plugins/sp/commands/dev-changelog.md +1 -1
- package/plugins/sp/commands/dev-daily.md +1 -1
- package/plugins/sp/commands/dev-pr-review.md +1 -1
- package/plugins/sp/commands/dev-review-session.md +1 -1
- package/plugins/sp/commands/dev-runall.md +4 -4
- package/plugins/sp/commands/dev-verify.md +4 -6
- package/plugins/sp/commands/dev-verifyall.md +4 -5
- package/plugins/sp/hooks/hooks.json +11 -1
- package/plugins/sp/lib/context-post-tool.ts +1 -1
- package/plugins/sp/lib/context-session-start.ts +1 -1
- package/plugins/sp/lib/context-session-stop.ts +1 -1
- package/plugins/sp/lib/destructive-policy.ts +65 -1
- package/plugins/sp/plugin.json +2 -5
- package/plugins/sp/{hooks → scripts/hooks}/agent-lifecycle.ts +1 -1
- package/plugins/sp/scripts/hooks/careful-guard.ts +94 -0
- package/plugins/sp/{hooks → scripts/hooks}/context-post-tool.ts +2 -2
- package/plugins/sp/{hooks → scripts/hooks}/context-session-start.ts +1 -1
- package/plugins/sp/{hooks → scripts/hooks}/context-session-stop.ts +1 -1
- package/plugins/sp/{hooks → scripts/hooks}/fleet-guest-stop.ts +6 -4
- package/plugins/sp/{hooks → scripts/hooks}/task-write-guard.ts +38 -21
- package/plugins/sp/skills/brainstorm/SKILL.md +12 -11
- package/plugins/sp/skills/brainstorm/agents/openai.yaml +1 -1
- package/plugins/sp/skills/brainstorm/examples/ideation-example.md +0 -4
- package/plugins/sp/skills/brainstorm/metadata.openclaw +1 -1
- package/plugins/sp/skills/brainstorm/references/workflows.md +4 -14
- package/plugins/sp/skills/code-implementation/SKILL.md +1 -1
- package/plugins/sp/skills/code-verification/SKILL.md +8 -8
- package/plugins/sp/skills/code-verification/references/secu-review.md +4 -4
- package/plugins/sp/skills/code-verification/references/verdict-schema.md +9 -1
- package/plugins/sp/skills/daily-summary/SKILL.md +4 -5
- package/plugins/sp/skills/dogfood-testing/SKILL.md +9 -9
- package/plugins/sp/skills/dogfood-testing/references/report-template.md +1 -1
- package/plugins/sp/skills/history-anatomy/references/modes.md +2 -2
- package/plugins/sp/skills/history-anatomy/references/operations.md +3 -4
- package/plugins/sp/skills/history-anatomy/references/report-contract.md +2 -3
- package/plugins/sp/skills/issue-finding/SKILL.md +1 -1
- package/plugins/sp/skills/next-router/references/routing-table.md +1 -1
- package/plugins/sp/skills/parallel-execution/SKILL.md +2 -2
- package/plugins/sp/skills/parallel-execution/references/result-synthesis.md +9 -10
- package/plugins/sp/skills/pr-reviewing/SKILL.md +14 -15
- package/plugins/sp/skills/reverse-engineering/SKILL.md +4 -6
- package/plugins/sp/skills/session-review/SKILL.md +13 -29
- package/plugins/sp/skills/source-driven-development/SKILL.md +26 -27
- package/plugins/sp/skills/spur-check/SKILL.md +14 -13
- package/plugins/sp/skills/spur-cli/SKILL.md +1 -1
- package/plugins/sp/skills/spur-cli/references/agent.md +17 -2
- package/plugins/sp/skills/spur-cli/references/builder.md +27 -6
- package/plugins/sp/skills/spur-cli/references/features.md +6 -1
- package/plugins/sp/skills/spur-cli/references/history.md +3 -0
- package/plugins/sp/skills/spur-cli/references/self.md +5 -3
- package/plugins/sp/skills/spur-cli/references/tasks/verbs.md +3 -0
- package/plugins/sp/skills/spur-cli/references/tasks.md +13 -3
- package/plugins/sp/skills/spur-cli/references/workflows/authoring-workflows.md +1 -1
- package/plugins/sp/skills/spur-cli/references/workflows.md +36 -1
- package/plugins/sp/skills/spur-dev/SKILL.md +1 -1
- package/plugins/sp/skills/spur-dev/references/cross-cutting.md +1 -1
- package/plugins/sp/skills/spur-dev/references/dev-operations.md +12 -13
- package/plugins/sp/skills/spur-dev/references/execution-batch-report.md +10 -11
- package/plugins/sp/skills/spur-dev/references/execution-batch.md +16 -17
- package/plugins/sp/skills/spur-dev/references/execution-parallel-isolation.md +1 -1
- package/plugins/sp/skills/spur-dev/references/execution-worktree-landing.md +9 -12
- package/plugins/sp/skills/spur-dev/references/execution-worktree-setup.md +6 -8
- package/plugins/sp/skills/spur-dev/references/gate-checklists.md +1 -1
- package/plugins/sp/skills/spur-dev/references/inline-pipeline-driver.md +33 -40
- package/plugins/sp/skills/spur-dev/references/structured-trace-emission.md +24 -24
- package/plugins/sp/skills/spur-doctor/SKILL.md +5 -4
- package/spur.js +12726 -1456
- package/web/_astro/{BoardApp.CaNvQBD_.js → BoardApp.B5rTVNd_.js} +1 -1
- package/web/_astro/{BoardApp.C5jnkkKP.js → BoardApp.BMprmPRc.js} +141 -141
- package/web/_astro/{TaskDetail.DGKndhI8.js → TaskDetail.Ddsur8qd.js} +1 -1
- package/web/_astro/{arc.DHrwdg3G.js → arc.DLqVVBxP.js} +1 -1
- package/web/_astro/{architectureDiagram-3BPJPVTR.pvKpK1s5.js → architectureDiagram-3BPJPVTR.C-Pk3uAi.js} +1 -1
- package/web/_astro/{blockDiagram-GPEHLZMM.BQmRcZsS.js → blockDiagram-GPEHLZMM.BRO1i_Nm.js} +1 -1
- package/web/_astro/{c4Diagram-AAUBKEIU.CCLjHeH1.js → c4Diagram-AAUBKEIU.BU_cWu6e.js} +1 -1
- package/web/_astro/channel.Bs3Illhy.js +1 -0
- package/web/_astro/{chunk-2J33WTMH.DL6Yuoma.js → chunk-2J33WTMH.D2VXiQ2t.js} +1 -1
- package/web/_astro/{chunk-4BX2VUAB.CzlyEI7l.js → chunk-4BX2VUAB.BcHT772J.js} +1 -1
- package/web/_astro/{chunk-55IACEB6.B60EWxp1.js → chunk-55IACEB6.DhDtICmo.js} +1 -1
- package/web/_astro/{chunk-727SXJPM.c7v_fRLo.js → chunk-727SXJPM.BoKHp7gV.js} +1 -1
- package/web/_astro/{chunk-AQP2D5EJ.8BxLWdDc.js → chunk-AQP2D5EJ.Chu4JRpE.js} +1 -1
- package/web/_astro/{chunk-FMBD7UC4.DmKuxGFT.js → chunk-FMBD7UC4.wHdwKPlq.js} +1 -1
- package/web/_astro/{chunk-ND2GUHAM.1Zwd4mqV.js → chunk-ND2GUHAM.ffN-M1JB.js} +1 -1
- package/web/_astro/{chunk-QZHKN3VN.BvYLu-A1.js → chunk-QZHKN3VN.FRubwg4S.js} +1 -1
- package/web/_astro/{classDiagram-4FO5ZUOK.CEqRt0WU.js → classDiagram-4FO5ZUOK.c22tQsc_.js} +1 -1
- package/web/_astro/{classDiagram-v2-Q7XG4LA2.CEqRt0WU.js → classDiagram-v2-Q7XG4LA2.c22tQsc_.js} +1 -1
- package/web/_astro/{cose-bilkent-S5V4N54A.C7JiUdj2.js → cose-bilkent-S5V4N54A.B9c6fiSj.js} +1 -1
- package/web/_astro/{cynefin-OW5HDTMX.B6mZ-1be.js → cynefin-OW5HDTMX.DrZsrUHl.js} +1 -1
- package/web/_astro/{dagre-BM42HDAG.BuryfDy6.js → dagre-BM42HDAG.DG1U4b3y.js} +1 -1
- package/web/_astro/{diagram-2AECGRRQ.dao39YQM.js → diagram-2AECGRRQ.CH15b-K3.js} +1 -1
- package/web/_astro/{diagram-5GNKFQAL.lnGZe4At.js → diagram-5GNKFQAL.BH1j7twR.js} +1 -1
- package/web/_astro/{diagram-KO2AKTUF.uWfhzEfT.js → diagram-KO2AKTUF.q2zCkbAj.js} +1 -1
- package/web/_astro/{diagram-LMA3HP47.ppq8-198.js → diagram-LMA3HP47.BLaaZnHV.js} +1 -1
- package/web/_astro/{diagram-OG6HWLK6.CKSCqDt5.js → diagram-OG6HWLK6.BcpRdQwI.js} +1 -1
- package/web/_astro/{erDiagram-TEJ5UH35.sFSf2yBN.js → erDiagram-TEJ5UH35.D7KBlqfM.js} +1 -1
- package/web/_astro/{flowDiagram-I6XJVG4X.BJQjKLbz.js → flowDiagram-I6XJVG4X.D_gmuRqg.js} +1 -1
- package/web/_astro/{ganttDiagram-6RSMTGT7.DAHKNj2N.js → ganttDiagram-6RSMTGT7.DzgWYniD.js} +1 -1
- package/web/_astro/{gitGraphDiagram-PVQCEYII.BlmzcW_O.js → gitGraphDiagram-PVQCEYII.576i3hm3.js} +1 -1
- package/web/_astro/index.DiC1a6lh.css +1 -0
- package/web/_astro/{infoDiagram-5YYISTIA.DGhjaqsi.js → infoDiagram-5YYISTIA.DMCclBiz.js} +1 -1
- package/web/_astro/{ishikawaDiagram-YF4QCWOH.gKIpgt6F.js → ishikawaDiagram-YF4QCWOH.9Kyca4SH.js} +1 -1
- package/web/_astro/{journeyDiagram-JHISSGLW.DG3tmP0R.js → journeyDiagram-JHISSGLW.chbdG-8q.js} +1 -1
- package/web/_astro/{kanban-definition-UN3LZRKU.CgHDSxkR.js → kanban-definition-UN3LZRKU.Bds54-e0.js} +1 -1
- package/web/_astro/{linear.BuGEpcuM.js → linear.D5ND9GN_.js} +1 -1
- package/web/_astro/{mermaid.core.DBVqkWBp.js → mermaid.core.D9N_PGbj.js} +4 -4
- package/web/_astro/{mindmap-definition-RKZ34NQL.D-kOcji9.js → mindmap-definition-RKZ34NQL.t0xop5vp.js} +1 -1
- package/web/_astro/{pieDiagram-4H26LBE5.BvGPwtZt.js → pieDiagram-4H26LBE5.DqgKh6hM.js} +1 -1
- package/web/_astro/{quadrantDiagram-W4KKPZXB.BKb_9FV6.js → quadrantDiagram-W4KKPZXB.DeuHVi2t.js} +1 -1
- package/web/_astro/{requirementDiagram-4Y6WPE33.Cx0fvD8v.js → requirementDiagram-4Y6WPE33.BdYFSG4W.js} +1 -1
- package/web/_astro/{sankeyDiagram-5OEKKPKP.fatULi0W.js → sankeyDiagram-5OEKKPKP.k1LPPETJ.js} +1 -1
- package/web/_astro/{sequenceDiagram-3UESZ5HK.ChHyKqco.js → sequenceDiagram-3UESZ5HK.DdyfpzoG.js} +1 -1
- package/web/_astro/{stateDiagram-AJRCARHV.BdUpKWyj.js → stateDiagram-AJRCARHV.DSEI8il0.js} +1 -1
- package/web/_astro/{stateDiagram-v2-BHNVJYJU.fmJxqIm5.js → stateDiagram-v2-BHNVJYJU.CoMnQRKo.js} +1 -1
- package/web/_astro/{timeline-definition-PNZ67QCA.BayDn5-V.js → timeline-definition-PNZ67QCA.DM1AHNm-.js} +1 -1
- package/web/_astro/{vennDiagram-CIIHVFJN.Bm2Aggwa.js → vennDiagram-CIIHVFJN.C-cJmVtl.js} +1 -1
- package/web/_astro/{wardleyDiagram-YWT4CUSO.DI75O-uG.js → wardleyDiagram-YWT4CUSO.D0xMzKPb.js} +1 -1
- package/web/_astro/{xychartDiagram-2RQKCTM6.DL90E7Q7.js → xychartDiagram-2RQKCTM6.BH5xJcEq.js} +1 -1
- package/web/index.html +2 -2
- package/config/plugin-scripts.json +0 -116
- package/config/script-placement-baseline.json +0 -33
- package/plugins/sp/hooks/careful-guard.ts +0 -74
- package/plugins/sp/hooks/pi/guard-extension.ts +0 -304
- package/plugins/sp/lib/dogfood-pipeline.ts +0 -265
- package/plugins/sp/lib/dogfood-report.ts +0 -278
- package/plugins/sp/lib/history-anatomy.generated.d.mts +0 -112
- package/plugins/sp/lib/history-anatomy.generated.mjs +0 -691
- package/plugins/sp/lib/idea-handoff.generated.d.mts +0 -17
- package/plugins/sp/lib/idea-handoff.generated.mjs +0 -1446
- package/plugins/sp/lib/inline-run-app.ts +0 -68
- package/plugins/sp/lib/inline-run.generated.d.mts +0 -37
- package/plugins/sp/lib/inline-run.generated.mjs +0 -3103
- package/plugins/sp/lib/plan-projection.generated.d.mts +0 -197
- package/plugins/sp/lib/plan-projection.generated.mjs +0 -982
- package/plugins/sp/lib/quality-gate.generated.d.mts +0 -139
- package/plugins/sp/lib/quality-gate.generated.mjs +0 -30510
- package/plugins/sp/lib/residual-scan.generated.d.mts +0 -93
- package/plugins/sp/lib/residual-scan.generated.mjs +0 -383
- package/plugins/sp/lib/run-summary-core.ts +0 -225
- package/plugins/sp/lib/spur-bin.ts +0 -36
- package/plugins/sp/lib/step-profile.generated.d.mts +0 -71
- package/plugins/sp/lib/step-profile.generated.mjs +0 -174
- package/plugins/sp/lib/transcript.ts +0 -112
- package/plugins/sp/scripts/batch-plan.mjs +0 -1096
- package/plugins/sp/scripts/batch-plan.ts +0 -145
- package/plugins/sp/scripts/batch-preflight.mjs +0 -423
- package/plugins/sp/scripts/batch-preflight.ts +0 -270
- package/plugins/sp/scripts/commit-guard.mjs +0 -226
- package/plugins/sp/scripts/commit-guard.ts +0 -248
- package/plugins/sp/scripts/daily-summary/daily-summary.mjs +0 -626
- package/plugins/sp/scripts/daily-summary/daily-summary.ts +0 -855
- package/plugins/sp/scripts/dogfood-testing/detect-pipeline-driving.mjs +0 -211
- package/plugins/sp/scripts/dogfood-testing/detect-pipeline-driving.ts +0 -110
- package/plugins/sp/scripts/dogfood-testing/validate-report.mjs +0 -282
- package/plugins/sp/scripts/dogfood-testing/validate-report.ts +0 -98
- package/plugins/sp/scripts/feature-verification-steps.mjs +0 -82
- package/plugins/sp/scripts/feature-verification-steps.ts +0 -164
- package/plugins/sp/scripts/history-anatomy-cache.mjs +0 -931
- package/plugins/sp/scripts/history-anatomy-cache.ts +0 -247
- package/plugins/sp/scripts/idea-handoff.mjs +0 -32
- package/plugins/sp/scripts/idea-handoff.ts +0 -47
- package/plugins/sp/scripts/inline-run-dispatch.mjs +0 -131
- package/plugins/sp/scripts/inline-run-dispatch.ts +0 -115
- package/plugins/sp/scripts/inline-run-setup.mjs +0 -746
- package/plugins/sp/scripts/inline-run-setup.ts +0 -198
- package/plugins/sp/scripts/persist-out-check.mjs +0 -217
- package/plugins/sp/scripts/persist-out-check.ts +0 -249
- package/plugins/sp/scripts/pr-reviewing.mjs +0 -712
- package/plugins/sp/scripts/pr-reviewing.ts +0 -952
- package/plugins/sp/scripts/quality-gate.mjs +0 -30491
- package/plugins/sp/scripts/quality-gate.ts +0 -80
- package/plugins/sp/scripts/residual-scan.mjs +0 -634
- package/plugins/sp/scripts/residual-scan.ts +0 -248
- package/plugins/sp/scripts/run-summary.mjs +0 -758
- package/plugins/sp/scripts/run-summary.ts +0 -107
- package/plugins/sp/scripts/script-root.mjs +0 -129
- package/plugins/sp/scripts/script-root.ts +0 -199
- package/plugins/sp/scripts/session-timeline.mjs +0 -359
- package/plugins/sp/scripts/session-timeline.ts +0 -190
- package/plugins/sp/scripts/task-diffstat.mjs +0 -181
- package/plugins/sp/scripts/task-diffstat.ts +0 -219
- package/plugins/sp/scripts/workflow-step-profile.mjs +0 -338
- package/plugins/sp/scripts/workflow-step-profile.ts +0 -165
- package/plugins/sp/scripts/wrapup-drift-probe.mjs +0 -190
- package/plugins/sp/scripts/wrapup-drift-probe.ts +0 -261
- package/plugins/sp/scripts/wrapup-steps.mjs +0 -627
- package/plugins/sp/scripts/wrapup-steps.ts +0 -891
- package/web/_astro/channel.C7wG9RxA.js +0 -1
- package/web/_astro/index.BCY1JJHd.css +0 -1
|
@@ -82,11 +82,11 @@ The command forwards these via `$ARGUMENTS`:
|
|
|
82
82
|
> <!-- pipeline-tokens:end -->
|
|
83
83
|
> matched as a **distinct hyphen-word**
|
|
84
84
|
> (machine-checked by
|
|
85
|
-
>
|
|
85
|
+
> `detectPipelineDriving` (`spur agent dogfood gate`);
|
|
86
86
|
> see [§Pipeline-driving word-boundary contract](#pipeline-driving-word-boundary-contract))
|
|
87
87
|
> → `⚠ pipeline-driving testee detected; pass --max-retry 0 (observe-only) or --max-retry N (fix mode, tree mutation acknowledged)`.
|
|
88
88
|
> - **Mutating `--fix` modes** — `--fix all` / `--fix blockers-first`, boundary-guarded via
|
|
89
|
-
>
|
|
89
|
+
> `hasMutatingFixMode` (`spur agent dogfood gate`) (never matches
|
|
90
90
|
> `--fix none` / `--focus all` / `--prefix all`). No pipeline token required: a verify/review leg
|
|
91
91
|
> with `--fix all` mutates the tree on its own (0280 dogfood P2, task 0293). Honesty note:
|
|
92
92
|
> `--max-retry 0` here bounds **the driver only** — the testee still mutates the tree — so the
|
|
@@ -100,7 +100,7 @@ The command forwards these via `$ARGUMENTS`:
|
|
|
100
100
|
in-agent):
|
|
101
101
|
|
|
102
102
|
```bash
|
|
103
|
-
|
|
103
|
+
spur agent dogfood gate \
|
|
104
104
|
--testee "<raw testee string>" \
|
|
105
105
|
[--max-retry-present]
|
|
106
106
|
```
|
|
@@ -109,7 +109,7 @@ The command forwards these via `$ARGUMENTS`:
|
|
|
109
109
|
of two independent mutation sources (task 0293); its two refuse lines are the ones quoted
|
|
110
110
|
verbatim in the repo-mutation warning above.
|
|
111
111
|
- Exit **0** → proceed. Do not auto-substitute `--max-retry 0`.
|
|
112
|
-
- The matcher contract is unit-checked by `tests/dogfood
|
|
112
|
+
- The matcher contract is unit-checked by `packages/app/tests/services/dogfood/pipeline-detect.test.ts`.
|
|
113
113
|
See [§Pipeline-driving word-boundary contract](#pipeline-driving-word-boundary-contract) and
|
|
114
114
|
[§Mutating `--fix` mode contract](#mutating---fix-mode-contract).
|
|
115
115
|
1. **Resolve + classify** the testee: slash command (`/sp:...`), agent skill (`Skill(...)`), or shell
|
|
@@ -121,7 +121,7 @@ The command forwards these via `$ARGUMENTS`:
|
|
|
121
121
|
re-run the gate with the derived step labels:
|
|
122
122
|
|
|
123
123
|
```bash
|
|
124
|
-
|
|
124
|
+
spur agent dogfood gate \
|
|
125
125
|
--testee "<raw testee string>" \
|
|
126
126
|
--max-retry-present \
|
|
127
127
|
--steps "step1 label||step2 label||..."
|
|
@@ -232,7 +232,7 @@ contract violation**.
|
|
|
232
232
|
**before** claiming `status: complete`:
|
|
233
233
|
|
|
234
234
|
```bash
|
|
235
|
-
|
|
235
|
+
spur agent dogfood validate-report --file <report-path>
|
|
236
236
|
```
|
|
237
237
|
|
|
238
238
|
Exit **0** → proceed. Exit **2** → set `status: aborted`, list every error code under §5
|
|
@@ -338,7 +338,7 @@ Do **not** use this skill for:
|
|
|
338
338
|
Pipeline-driving detection is **word-boundary**, not leading-space substring. The live gate is:
|
|
339
339
|
|
|
340
340
|
```bash
|
|
341
|
-
|
|
341
|
+
spur agent dogfood gate --testee "<testee>" [--max-retry-present] [--steps "…"] [--json]
|
|
342
342
|
```
|
|
343
343
|
|
|
344
344
|
| Token shape | Examples | Matches | Rejects |
|
|
@@ -347,9 +347,9 @@ node "$(superskill script path sp dogfood-testing/detect-pipeline-driving.mjs)"
|
|
|
347
347
|
| Bare noun | <!-- pipeline-tokens:start -->`run`, `runall`, `wrap`, `wrapall`, `idea`, `refineall`, `verifyall`<!-- pipeline-tokens:end --> | `task run 0042` | `runaway`, `wrapper`, `idealist` |
|
|
348
348
|
|
|
349
349
|
`-` is a **word character** for boundaries: a token must be a distinct hyphen-word. Contract tests:
|
|
350
|
-
`
|
|
350
|
+
`packages/app/tests/services/dogfood/pipeline-detect.test.ts`. Helpers:
|
|
351
351
|
`detectPipelineDriving`, `isImplementHeavyStep`, `detectImplementHeavy`, `evaluateDogfoodGate` in
|
|
352
|
-
|
|
352
|
+
`spur agent dogfood gate` (absorbed into the CLI; was `plugins/sp/scripts/dogfood-testing/detect-pipeline-driving.ts`).
|
|
353
353
|
|
|
354
354
|
## Mutating `--fix` mode contract
|
|
355
355
|
|
|
@@ -336,7 +336,7 @@ Before the skill may stop (success, partial, fail, observe-only end, or abort),
|
|
|
336
336
|
and mirror the footer block at the **end of the report file**. A report whose body lacks the
|
|
337
337
|
footer cannot set `status: complete`.
|
|
338
338
|
8. **Self-validate (task 0278 R6):** run
|
|
339
|
-
`
|
|
339
|
+
`spur agent dogfood validate-report --file <report-path>` before
|
|
340
340
|
claiming `status: complete`. Exit 2 → `status: aborted` + list error codes under
|
|
341
341
|
`#### Unresolved` (never force complete on a non-@1.2 shape).
|
|
342
342
|
9. **Refusal rule (@1.2):** when any check above fails, set `status: aborted` and list every
|
|
@@ -2,8 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
The skill resolves exactly two modes. Everything else fails loud. This matrix is the enforcement
|
|
4
4
|
surface the workflow (0660) and the skill share; keep the vocabulary frozen. Execution note
|
|
5
|
-
(0920): argument validation runs deterministically in
|
|
6
|
-
|
|
5
|
+
(0920): argument validation runs deterministically in `spur history anatomy paths`
|
|
6
|
+
(formerly the `history-anatomy-cache` helper) (logic core: `packages/app/src/services/history-anatomy.ts`, task 1005) before the
|
|
7
7
|
workflow starts; the model hop no longer performs it.
|
|
8
8
|
|
|
9
9
|
## Mode vocabulary (frozen)
|
|
@@ -31,10 +31,9 @@ Given the current and baseline artifacts, author the model half of the report. A
|
|
|
31
31
|
calendar day; ad-hoc → immediately preceding equal-duration window. If baseline coverage is
|
|
32
32
|
insufficient or materially different, emit `not comparable` and **no** trend/delta/percentage.
|
|
33
33
|
3. **Findings** — each with the full per-finding field set (key, category, impact, trend,
|
|
34
|
-
observation, inference,
|
|
34
|
+
observation, inference, contradictions, evidenceAnchor, severity, reproCommand,
|
|
35
35
|
ownerSurface). Categories from the closed vocabulary; stable keys of the form
|
|
36
|
-
`<category>:<owner-surface>:<signal>`. Severity is the closed P1/P2/P3 vocabulary
|
|
37
|
-
orthogonal to confidence; reproCommand reproduces the observation verbatim; ownerSurface names
|
|
36
|
+
`<category>:<owner-surface>:<signal>`. Severity is the closed P1/P2/P3 vocabulary; reproCommand reproduces the observation verbatim; ownerSurface names
|
|
38
37
|
the concrete owning surface (file/package/command), consistent with the key's middle segment.
|
|
39
38
|
4. **Recurrence ledger** — classify every finding against the baseline on the **stable key**.
|
|
40
39
|
5. **Telemetry gaps** — every dimension the artifact cannot support, rendered `not available`.
|
|
@@ -58,7 +57,7 @@ Given a candidate report and the artifacts, independently verify:
|
|
|
58
57
|
- **Twelve-section completeness and order** — all twelve section names present in the frozen
|
|
59
58
|
order; none renamed/omitted.
|
|
60
59
|
- **Per-finding fields** — every finding (problem and positive) carries key, category, impact,
|
|
61
|
-
trend, observation, inference,
|
|
60
|
+
trend, observation, inference, contradictions, evidenceAnchor, severity (P1/P2/P3),
|
|
62
61
|
reproCommand, ownerSurface; category in the closed vocabulary; stable-key grammar. A finding
|
|
63
62
|
missing any triage field FAILs (the deterministic gate enforces the same set).
|
|
64
63
|
- **Remediation handoff** — each accepted-proposal handoff carries a `spur task create`
|
|
@@ -62,10 +62,9 @@ Every finding — problem and positive alike — carries the full field set:
|
|
|
62
62
|
| `trend` | `new` / `recurring` / `regressed` / `improved` / `resolved` / `not-comparable` (see recurrence). |
|
|
63
63
|
| `observation` | What the artifacts show — evidence, not interpretation. |
|
|
64
64
|
| `inference` | What the observation is reasoned to mean; names its supporting observations. |
|
|
65
|
-
| `confidence` | Per-finding: `high` / `medium` / `low`. Never one blanket report-level score. |
|
|
66
65
|
| `contradictions` | Any contradicting signal shown beside the finding, not silently reconciled. |
|
|
67
66
|
| `evidenceAnchor` | At least one anchor to the forensics artifact or cited `file:line`. An entry with no anchor is invalid. |
|
|
68
|
-
| `severity` | Closed vocabulary `P1` / `P2` / `P3` — how much the finding matters.
|
|
67
|
+
| `severity` | Closed vocabulary `P1` / `P2` / `P3` — how much the finding matters. Severity orders work (0680 R1); how well a finding is supported lives in its `observation`, `inference`, `contradictions` and `evidenceAnchor`, never a confidence label (ADR-138). The structure gate fails a finding without one. |
|
|
69
68
|
| `reproCommand` | The invocation that reproduces the observation — one command a reader can run verbatim (0680 R2). Gate-enforced. |
|
|
70
69
|
| `ownerSurface` | The concrete surface that owns the fix (a file path, package, or command), consistent with the key's `<owner-surface>` segment but named as a target rather than a slug (0680 R3). Gate-enforced. |
|
|
71
70
|
|
|
@@ -114,7 +113,7 @@ reclassify a recurring finding as new.
|
|
|
114
113
|
## Positive patterns
|
|
115
114
|
|
|
116
115
|
Positive entries are held to the **same evidence standard as problems**: they carry observation,
|
|
117
|
-
inference,
|
|
116
|
+
inference, and at least one evidence anchor. An entry without an anchor is invalid. The
|
|
118
117
|
section renders successful workflows, resolved past issues that stay resolved, and healthy,
|
|
119
118
|
repeating behavior worth keeping.
|
|
120
119
|
|
|
@@ -411,7 +411,7 @@ Thin wrapper: `Skill(skill="sp:issue-finding", args="$ARGUMENTS")`.
|
|
|
411
411
|
- Wholesale raw JSONL parsing when the source has a typed mapper.
|
|
412
412
|
- Accepting `--use-history` or `--no-task` silently instead of naming their replacements.
|
|
413
413
|
- GENERATE recipes inventing a title flag, dotted template forms, or quoted dotted section flags.
|
|
414
|
-
- Claiming multi-agent forensics without
|
|
414
|
+
- Claiming multi-agent forensics without citing the session source each finding came from.
|
|
415
415
|
- Skipping batch section writes + single `spur task check` (when generating).
|
|
416
416
|
- Emitting empty findings without inventorying sessions first.
|
|
417
417
|
|
|
@@ -15,7 +15,7 @@ dispatcher: resolve target → load corpus → apply primary table → optional
|
|
|
15
15
|
|
|
16
16
|
`sp:super-planner` (via `/sp:dev-runall`) **reads** TABLE A STOP preconditions for:
|
|
17
17
|
|
|
18
|
-
1. **Preflight** — skip pipeline launch when A2/A7/A8/A9 would stop `dev-next` (`
|
|
18
|
+
1. **Preflight** — skip pipeline launch when A2/A7/A8/A9 would stop `dev-next` (`spur task preflight`).
|
|
19
19
|
2. **One-shot recovery** — after a failed pipeline, map status → primary hop (A1/A3/A5/A6/A7) at most once.
|
|
20
20
|
|
|
21
21
|
It does **not** reimplement TABLES or replace `task-pipeline.yaml` with a `dev-next` loop. Keep this
|
|
@@ -61,7 +61,7 @@ Parallel subagent outputs must be **synthesized**, not concatenated. The synthes
|
|
|
61
61
|
|
|
62
62
|
1. **Dedup** — merge findings with the same `file:line` anchor; keep the highest-severity version.
|
|
63
63
|
2. **Resolve conflicts** — when two subagents disagree on the same claim, surface the disagreement explicitly; don't silently pick one.
|
|
64
|
-
3. **Rank by
|
|
64
|
+
3. **Rank by evidence** — verified findings (executed check or cited source) first, unverified next, unresolved conflicts last; severity within each tier.
|
|
65
65
|
4. **Unified format** — emit one coherent output, not N raw dumps.
|
|
66
66
|
|
|
67
67
|
Full synthesis methodology: [result-synthesis.md](references/result-synthesis.md).
|
|
@@ -104,7 +104,7 @@ was meant to avoid. Let the reviewer reach its own conclusion.
|
|
|
104
104
|
|
|
105
105
|
- **`sp:spur-dev`** owns task selection and lifecycle. When a batch contains independent tasks, the spine consults this skill for the fan-out pattern.
|
|
106
106
|
- **`sp:super-planner`** is the orchestrator that executes the fan-out. Its parallel mode (documented in its agent definition) applies the patterns from this skill.
|
|
107
|
-
- **`/sp:dev-runall --mode parallel|auto`** is the task-batch entry point; its `batch-plan
|
|
107
|
+
- **`/sp:dev-runall --mode parallel|auto`** is the task-batch entry point; its `spur task batch-plan order` schedule applies this skill's dependency and file-overlap rows deterministically.
|
|
108
108
|
|
|
109
109
|
## When to use
|
|
110
110
|
|
|
@@ -41,13 +41,12 @@ Synthesis: ⚠ CONFLICT — Redis migration safety
|
|
|
41
41
|
|
|
42
42
|
**Rule:** conflicts are findings, not failures. Surface them with both positions stated; let the operator resolve.
|
|
43
43
|
|
|
44
|
-
### 3. Rank by
|
|
44
|
+
### 3. Rank by evidence
|
|
45
45
|
|
|
46
|
-
Sort synthesized results:
|
|
47
|
-
1.
|
|
48
|
-
2.
|
|
49
|
-
3.
|
|
50
|
-
4. Unresolved conflicts (both sides stated)
|
|
46
|
+
Sort synthesized results by what backs them, not a self-assigned confidence label (ADR-138):
|
|
47
|
+
1. Verified (an executed check or a cited `path:line` / URL)
|
|
48
|
+
2. Unverified (reasoned or pattern-matched; name the check that would ground it)
|
|
49
|
+
3. Unresolved conflicts (both sides stated)
|
|
51
50
|
|
|
52
51
|
Within each tier, sort by severity (P1 → P2 → P3 → P4).
|
|
53
52
|
|
|
@@ -58,11 +57,11 @@ Emit one coherent output. The unified report has:
|
|
|
58
57
|
```
|
|
59
58
|
## Synthesized Results
|
|
60
59
|
|
|
61
|
-
###
|
|
62
|
-
| # | Finding | Source | Severity | File:Line |
|
|
63
|
-
|
|
60
|
+
### Verified
|
|
61
|
+
| # | Finding | Source | Severity | File:Line | Evidence |
|
|
62
|
+
|---|---------|--------|----------|-----------|----------|
|
|
64
63
|
|
|
65
|
-
###
|
|
64
|
+
### Unverified
|
|
66
65
|
...
|
|
67
66
|
|
|
68
67
|
### Conflicts (unresolved)
|
|
@@ -40,9 +40,9 @@ sp:pr-reviewing (this skill — mode routing, triage, fix, rules)
|
|
|
40
40
|
│ deterministic spine, state order + guards:
|
|
41
41
|
▼
|
|
42
42
|
pr-review.yaml ← workflow SSOT (seeded by spur init; project-tunable)
|
|
43
|
-
│ every
|
|
43
|
+
│ every deterministic action shells out to:
|
|
44
44
|
▼
|
|
45
|
-
|
|
45
|
+
`spur builder pr` ← Bun entrypoint for the tested git/gh core
|
|
46
46
|
```
|
|
47
47
|
|
|
48
48
|
- **State order and guards** are defined once, in the workflow YAML. Do not re-derive them in
|
|
@@ -128,44 +128,43 @@ root causes rather than wording, prefer the smallest coherent patch, avoid drive
|
|
|
128
128
|
## Workflow-backed spine (`full`, `submit`, `rerun`)
|
|
129
129
|
|
|
130
130
|
Run the workflow YAML's declared states in order. Every deterministic state invokes the
|
|
131
|
-
|
|
131
|
+
`spur builder pr` operation below, supports `--json`, and must be parsed. Stop at the first red gate and
|
|
132
132
|
report its artifact. The canonical installed invocation is:
|
|
133
133
|
|
|
134
134
|
```sh
|
|
135
|
-
|
|
135
|
+
spur builder pr <subcommand> [flags]
|
|
136
136
|
```
|
|
137
137
|
|
|
138
|
-
|
|
139
|
-
superskill script contract.
|
|
138
|
+
The installed Spur CLI owns these operations; no staged script, Node twin or plugin resolver is used.
|
|
140
139
|
|
|
141
|
-
1. **Preflight** —
|
|
140
|
+
1. **Preflight** — `spur builder pr preflight --base "$base" --json`. Hard-fails on a
|
|
142
141
|
detached HEAD, missing `gh` auth, no GitHub remote, a dirty tree, or the current branch
|
|
143
142
|
being the base branch (a PR reviews a feature branch against the base; nothing on the
|
|
144
143
|
base branch is reviewable, and the guard runs before any push can publish it). On a
|
|
145
144
|
dirty tree, triage with the user (commit/stash/exclude) before continuing — the
|
|
146
145
|
workflow refuses to guess.
|
|
147
|
-
2. **Hygiene** —
|
|
146
|
+
2. **Hygiene** — `spur builder pr hygiene --base "$base" --json`. `BLOCK` (secrets, `.env`, conflict markers,
|
|
148
147
|
private keys) stops the run — never submit a tainted diff. `WARN` (debug residue) rides along
|
|
149
148
|
into the report. This is a submission sanity check, not a second local review.
|
|
150
149
|
3. **Precheck** — if the workflow YAML's `preReviewCmd` var is set, run it; a red check stops the
|
|
151
150
|
run (do not spend a review request on code that fails its own gate). When unset, report that
|
|
152
151
|
pre-review verification was not configured rather than inventing project commands.
|
|
153
|
-
4. **Push** —
|
|
154
|
-
5. **Ensure PR** —
|
|
152
|
+
4. **Push** — `spur builder pr push --json`. Normal push only; sets upstream when missing.
|
|
153
|
+
5. **Ensure PR** — `spur builder pr ensure-pr --base "$base" --json`. Reuses the branch's PR; creates with
|
|
155
154
|
`gh pr create --fill` only when absent. Never a duplicate PR.
|
|
156
|
-
6. **Request** —
|
|
155
|
+
6. **Request** — `spur builder pr request --focus "<focus>" --json` (`--force` in `rerun` mode). Dedupes when
|
|
157
156
|
Codex already reviewed the exact pushed HEAD (`ALREADY_REVIEWED` → skip to collect) or a marked
|
|
158
157
|
request by the current GitHub user is still in flight (`ALREADY_REQUESTED` → pending). The
|
|
159
158
|
request body is concise when the repo has `## Code Review Rules`, else carries the default
|
|
160
159
|
actionable-issues focus. Records PR, URL, HEAD, and request time.
|
|
161
160
|
7. **Wait** (full/rerun unless `--no-wait`; submit stops before it) —
|
|
162
|
-
|
|
161
|
+
`spur builder pr wait --since "$requestedAt" --head "$requestHead" --json`, using the request result so
|
|
163
162
|
a fast response is not missed, `rerun` cannot reuse the prior review, and a moved HEAD fails loud.
|
|
164
163
|
Polls every ~30s for up to
|
|
165
164
|
~10 minutes across the current HEAD's PR review and inline comments. Uncorrelated conversation
|
|
166
165
|
comments are ignored. A current-HEAD clean review is a completed `CLEAN` outcome; findings are
|
|
167
166
|
`FOUND`; timeout or no current-HEAD result is **pending, not failed** — collect later.
|
|
168
|
-
8. **Collect** —
|
|
167
|
+
8. **Collect** — `spur builder pr collect --since "$requestedAt" --head "$requestHead" --json`. Normalize
|
|
169
168
|
only the requested HEAD and request window; then invoke `status` with the same bounds for
|
|
170
169
|
PR/base/CI/local state. Never turn an absent, stale, or moved-HEAD result into `clean`.
|
|
171
170
|
`--head` is mandatory on wait/collect/status (0771): an empty or missing pin fails loud
|
|
@@ -288,7 +287,7 @@ or review requests.
|
|
|
288
287
|
|
|
289
288
|
- **Workflow SSOT:** `pr-review.yaml` (seeded by `spur init`; tune per project —
|
|
290
289
|
wait budget, `preReviewCmd`, dedupe policy)
|
|
291
|
-
- **Script source:**
|
|
292
|
-
- **Tests:**
|
|
290
|
+
- **Script source:** `spur builder pr` (absorbed; was `plugins/sp/scripts/pr-reviewing.ts`) — subcommand CLI
|
|
291
|
+
- **Tests:** `packages/app/tests/services/pr-review/pr-review.test.ts` — stubbed git/gh suites
|
|
293
292
|
- **Related skills:** `sp:code-verification` (local SECUA review), `sp:functional-review`
|
|
294
293
|
(requirements traceability) — complements, never substitutes, the independent Codex review
|
|
@@ -201,7 +201,6 @@ Audit categories:
|
|
|
201
201
|
| Analysis Date | YYYY-MM-DD |
|
|
202
202
|
| Target | `path` |
|
|
203
203
|
| Mode / Focus / Format | `briefing` / `[focus]` / `markdown` |
|
|
204
|
-
| Confidence | High / Medium / Low |
|
|
205
204
|
|
|
206
205
|
## Purpose Hypothesis
|
|
207
206
|
|
|
@@ -209,8 +208,8 @@ Audit categories:
|
|
|
209
208
|
|
|
210
209
|
## Tech Stack
|
|
211
210
|
|
|
212
|
-
| Layer | Technology | Evidence |
|
|
213
|
-
|
|
211
|
+
| Layer | Technology | Evidence |
|
|
212
|
+
|---|---|---|
|
|
214
213
|
|
|
215
214
|
## Entry Points
|
|
216
215
|
|
|
@@ -282,7 +281,6 @@ Use this shape for `--format json` or `--format both`. Omit fields only when the
|
|
|
282
281
|
"analysisDate": "YYYY-MM-DD",
|
|
283
282
|
"mode": "architecture",
|
|
284
283
|
"focus": "all",
|
|
285
|
-
"confidence": "high|medium|low",
|
|
286
284
|
"stack": [],
|
|
287
285
|
"entryPoints": [],
|
|
288
286
|
"components": [],
|
|
@@ -301,7 +299,7 @@ Use this shape for `--format json` or `--format both`. Omit fields only when the
|
|
|
301
299
|
- Cite `file/path:line` for claims derived from source files.
|
|
302
300
|
- Cite manifest paths for stack and package manager claims.
|
|
303
301
|
- Cite multiple files for architectural boundary claims when possible.
|
|
304
|
-
- Mark inferred claims
|
|
302
|
+
- Mark inferred claims `Inferred:` and name the evidence that would confirm them; no confidence label (ADR-138).
|
|
305
303
|
- Never invent services, databases, tables, endpoints, actors, diagrams, or business flows that are not supported by evidence.
|
|
306
304
|
- If line numbers are unavailable from a tool, cite the file path and state that line numbers were not available.
|
|
307
305
|
|
|
@@ -339,7 +337,7 @@ The indexed-context layer is optional and opportunistic.
|
|
|
339
337
|
|---|---|
|
|
340
338
|
| Empty/minimal codebase | Return `briefing` with "insufficient evidence", list missing artifacts, suggest next files needed. |
|
|
341
339
|
| Monorepo | Identify packages/apps; ask for scope unless `--auto` or requested mode can safely summarize all packages. |
|
|
342
|
-
| No clear entry point | List candidates with
|
|
340
|
+
| No clear entry point | List candidates with their evidence; do not choose one as definitive. |
|
|
343
341
|
| Binary-heavy repo | Focus on manifests, scripts, config, docs, and visible source. |
|
|
344
342
|
| Generated/vendor-heavy repo | Exclude generated/vendor paths from architecture conclusions unless directly relevant. |
|
|
345
343
|
| Framework convention over configuration | State inferred convention and cite framework-specific file patterns. |
|
|
@@ -90,15 +90,15 @@ issues with its evidence. Notes stay report-only.
|
|
|
90
90
|
|
|
91
91
|
1. **Resolve scope.** Review the active session from the operator's initiating request through the
|
|
92
92
|
latest result. Use `[focus]` only to rank relevant material. Measure it with
|
|
93
|
-
`
|
|
93
|
+
`spur history timeline --group "<ranges>"`: one segment per
|
|
94
94
|
operator prompt, read-only from the host transcript. Run it once without `--group` to list the
|
|
95
95
|
segments, then map them to stages (`"1-3,4,5-6"`). It splits each segment into `work` and
|
|
96
96
|
operator `wait` (idle before the next prompt plus AskUserQuestion answer time) and counts tokens
|
|
97
97
|
once per message id. On pi the transcript is `$PI_SESSION_FILE` (pass it as `--transcript` when
|
|
98
98
|
the run reports no host session id). **A measurement that returns `segments: []` with zero totals
|
|
99
99
|
while the session had operator prompts is an unreadable or stale adapter, not an empty session:**
|
|
100
|
-
|
|
101
|
-
|
|
100
|
+
check `spur --version` against this tree's release and upgrade the CLI before reporting
|
|
101
|
+
numbers; report `n/a` until then.
|
|
102
102
|
The transcript resolves from `--transcript`, else `CLAUDE_CODE_SESSION_ID`, else `PI_SESSION_FILE`
|
|
103
103
|
(the pi host sets it and no Claude session id); with none of them the measurement reports
|
|
104
104
|
`available:false` with a reason and the table renders `n/a` instead of guessing. A pi
|
|
@@ -149,39 +149,23 @@ step 4 excludes. Use `n/a` for any value not supported by the measurement.
|
|
|
149
149
|
|
|
150
150
|
### Resolved issues
|
|
151
151
|
|
|
152
|
-
| Issue | Root cause | Resolution | Evidence |
|
|
153
|
-
| --- | --- | --- | --- |
|
|
152
|
+
| Issue | Root cause | Resolution | Evidence |
|
|
153
|
+
| --- | --- | --- | --- |
|
|
154
154
|
|
|
155
155
|
Evidence names the tool result, verification command, or concrete repository state visible in the
|
|
156
156
|
session. Do not list ordinary implementation steps as issues.
|
|
157
157
|
|
|
158
|
-
**
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
| Level | Verifies when | Not this |
|
|
165
|
-
| --- | --- | --- |
|
|
166
|
-
| `HIGH` | An executed check in this session produced the result and its raw output is reachable (command + exit code, test counts, query row, gate log). Re-runnable now. | The code or change "looks correct"; a claim asserted only in prose. |
|
|
167
|
-
| `MEDIUM` | The claim is inferred from observed facts, rests on prior-session or delegated evidence, or names state that moved after the check (stale by construction). Name which of the three. | Presenting an inference as an observation. |
|
|
168
|
-
| `LOW` | No executable check was run. Name the missing evidence **and** the command that would ground it. | Dropping the row instead of marking it. |
|
|
169
|
-
|
|
170
|
-
Two guards against level inflation:
|
|
171
|
-
|
|
172
|
-
- Evidence that cannot be re-run, or that is only the agent's own summary, **caps the row at
|
|
173
|
-
`MEDIUM`** — a re-run is what promotes it.
|
|
174
|
-
- An all-`HIGH` multi-finding review is a signal the ladder was not applied, not a clean session.
|
|
175
|
-
Where every row genuinely is `HIGH`, the cells show distinct check results rather than repeated
|
|
176
|
-
phrasing.
|
|
177
|
-
|
|
178
|
-
Any API/library statement in a row cites the installed source as `path:line` or a URL, and a claim
|
|
179
|
-
the session could not ground is written `LOW` with the missing evidence named.
|
|
158
|
+
**Evidence is the check, not a grade** (ADR-138). A row resolved by an executed check this session
|
|
159
|
+
names the command and its result (e.g. `gate exit 0, /tmp/g0.log`). A row resting on inference,
|
|
160
|
+
prior-session or delegated evidence says so. A row with no check run names the missing evidence
|
|
161
|
+
**and** the command that would ground it — never drop the row instead. No HIGH/MEDIUM/LOW label:
|
|
162
|
+
a self-assigned level is as easy to write as the claim. Any API/library statement in a row cites
|
|
163
|
+
the installed source as `path:line` or a URL.
|
|
180
164
|
|
|
181
165
|
### Open issues and risks
|
|
182
166
|
|
|
183
|
-
| Issue or risk | State | Evidence or confirmation needed |
|
|
184
|
-
| --- | --- | --- |
|
|
167
|
+
| Issue or risk | State | Evidence or confirmation needed |
|
|
168
|
+
| --- | --- | --- |
|
|
185
169
|
|
|
186
170
|
### Process and environment improvements
|
|
187
171
|
|
|
@@ -55,27 +55,28 @@ Do **not** use this skill for:
|
|
|
55
55
|
|
|
56
56
|
- **Your own code's correctness** — that is `sp:code-verification` (requirements/AC) and `sp:code-review`.
|
|
57
57
|
- **Stress-testing a design decision** — that is `sp:doubt-driven-development` (artifact vs contract).
|
|
58
|
-
- **Well-known, version-stable stdlib** you
|
|
58
|
+
- **Well-known, version-stable stdlib** you have already checked — verification has a cost;
|
|
59
59
|
spend it where being wrong is likely and expensive.
|
|
60
60
|
|
|
61
61
|
## The process
|
|
62
62
|
|
|
63
|
-
### Step 1 —
|
|
63
|
+
### Step 1 — Know where each fact came from before you write
|
|
64
64
|
|
|
65
|
-
|
|
|
66
|
-
|
|
67
|
-
|
|
|
68
|
-
|
|
|
69
|
-
|
|
|
65
|
+
| Source in hand | Action |
|
|
66
|
+
|---|---|
|
|
67
|
+
| Checked against the pinned version's docs/source **this session** | Generate; cite the source inline |
|
|
68
|
+
| Recalled from a prior session; plausibly stale | Verify before relying on it |
|
|
69
|
+
| Memory only, no source in hand | Stop — verify first; never present as fact |
|
|
70
70
|
|
|
71
|
-
|
|
71
|
+
Do not grade the claim with a confidence label (ADR-138): a label is as easy to write as the claim.
|
|
72
|
+
The citation is the evidence.
|
|
72
73
|
|
|
73
74
|
### Step 2 — Go to the primary source, in priority order
|
|
74
75
|
|
|
75
76
|
1. The **type signature / source** in the installed, pinned dependency (the ground truth for *this* build).
|
|
76
77
|
2. The **official docs for the pinned version** (not the latest — the version in the lockfile).
|
|
77
78
|
3. Authoritative references when docs are thin.
|
|
78
|
-
4. Memory —
|
|
79
|
+
4. Memory — never the final authority; verify before relying on it.
|
|
79
80
|
|
|
80
81
|
State the **version** inline whenever behavior is version-specific.
|
|
81
82
|
|
|
@@ -91,37 +92,36 @@ Generate the code and **cite the source** (doc URL + date, or `pkg@version` + th
|
|
|
91
92
|
point of use or in the task's notes. A claim about external behavior without a citation is
|
|
92
93
|
unverified — flag it as such rather than presenting it as fact.
|
|
93
94
|
|
|
94
|
-
### Step 5 —
|
|
95
|
-
|
|
96
|
-
Before finishing, verify the citations for the API/library claims you emitted and close with one
|
|
97
|
-
line: `Verification: HIGH|MEDIUM|LOW — <first failing check and deviation, or 'all checks passed'>`.
|
|
95
|
+
### Step 5 — Check the citations before finishing
|
|
98
96
|
|
|
99
97
|
- **Citation coverage** — every API/library claim in the output carries a source citation (doc URL + date, or `pkg@version` + file/symbol); no uncited claim is asserted as fact.
|
|
100
98
|
- **Source authority** — each citation points at the pinned version's primary source (installed signature/source, or official docs for the lockfile version), not the latest docs or memory.
|
|
101
|
-
- **Honest confidence** — the stated HIGH/MEDIUM/LOW matches the evidence: HIGH requires a check against the pinned source this session; MEDIUM/LOW items are labeled, and LOW is never presented as fact.
|
|
102
|
-
- **HIGH** — all three checks pass. **MEDIUM** — coverage intact but some citations are off-version (latest docs for a pinned dependency) or secondary-source only. **LOW** — an API/library claim lacks any citation, or a LOW-confidence claim was asserted as fact.
|
|
103
99
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
100
|
+
Report the first failing check and its deviation, if any. Do not append a confidence verdict.
|
|
101
|
+
|
|
102
|
+
Deterministic backstop: the `cited-version-strings` and `cited-api-claims` rules
|
|
103
|
+
(`.spur/rules/docs/sourced-api-claims.yaml`) flag markdown lines that assert a version string or a
|
|
104
|
+
time- or version-anchored API claim (`deprecated since`, `removed in 0.9`, `fixers (since 0.3.4)`)
|
|
105
|
+
with no citation anchor on the same line. They are an info-severity advisory
|
|
106
|
+
backstop for this contract and are deliberately NOT wired into `recommended-pre-check` — run them ad
|
|
107
|
+
hoc with `spur rule run --file .spur/rules/docs/sourced-api-claims.yaml`. Dated working records
|
|
108
|
+
(`docs/report*`, `docs/dogfood`, `docs/plans`, `docs/analysis`) are excluded, as are the task
|
|
109
|
+
archives: a version measured by a past run is not an authorable claim. The checks above and the
|
|
110
|
+
SECUA checklist remain the enforcement points.
|
|
111
111
|
|
|
112
112
|
## Common Rationalizations
|
|
113
113
|
|
|
114
114
|
| Rationalization | Reality |
|
|
115
115
|
|---|---|
|
|
116
|
-
| "I've used this API a hundred times — I know the signature." | APIs change across versions and your memory is a silent cache. Verify against the *pinned* version; recall is
|
|
116
|
+
| "I've used this API a hundred times — I know the signature." | APIs change across versions and your memory is a silent cache. Verify against the *pinned* version; recall is not a source. |
|
|
117
117
|
| "It compiled, so I used it right." | Compiling proves existence and types, not contract. Ordering, preconditions, and error modes are not checked by the compiler. |
|
|
118
118
|
| "The latest docs say so." | You ship against the *pinned* version, not latest. Read the docs for the version in the lockfile. |
|
|
119
119
|
| "Close enough — I'll fix it if it breaks." | Guessing at an external contract moves the cost to runtime/production. Verify before generating; it is cheaper here. |
|
|
120
|
-
| "Verifying every call is too slow." | Verify what you
|
|
120
|
+
| "Verifying every call is too slow." | Verify what you have no source for. A fact checked this session needs no re-check; memory always does. |
|
|
121
121
|
|
|
122
122
|
## Red Flags
|
|
123
123
|
|
|
124
|
-
- Generating version-specific code
|
|
124
|
+
- Generating version-specific code from memory, without opening a source.
|
|
125
125
|
- Presenting an API claim as fact with no citation (doc + date, or `pkg@version` + symbol).
|
|
126
126
|
- Treating "it exists" as proof it is used correctly (the two questions collapsed into one).
|
|
127
127
|
- Reading the *latest* docs for a dependency pinned to an older version.
|
|
@@ -133,8 +133,7 @@ checklist remain the enforcement points.
|
|
|
133
133
|
- [ ] Every version-specific external behavior relied on was checked against the pinned version's source/docs **this session**.
|
|
134
134
|
- [ ] Both questions answered — the API exists **and** is called within its contract.
|
|
135
135
|
- [ ] Claims about external behavior carry a citation (source + date, or `pkg@version` + symbol); unverifiable ones are flagged, not asserted.
|
|
136
|
-
- [ ]
|
|
137
|
-
- [ ] Run closes with the Step 5 verdict line: `Verification: HIGH|MEDIUM|LOW — <first failing check and deviation, or 'all checks passed'>`.
|
|
136
|
+
- [ ] Nothing recalled from memory alone was presented as fact.
|
|
138
137
|
|
|
139
138
|
## See also
|
|
140
139
|
|
|
@@ -23,7 +23,7 @@ see_also:
|
|
|
23
23
|
|
|
24
24
|
# sp:spur-check — the two-tier check primitive (ADR-124)
|
|
25
25
|
|
|
26
|
-
One check primitive with two tiers behind
|
|
26
|
+
One check primitive with two tiers behind `spur task gate <wbs> <mode>`
|
|
27
27
|
([task 0939](../../../../docs/tasks5/0939_add-the-two-tier-spur-check-primitive-with-fingerprint-bound.md),
|
|
28
28
|
[workflow catalogue refactor §4](../../../../docs/design/workflow-catalogue-refactor.md)): light
|
|
29
29
|
checks accumulate during development, the full chain runs once at the quality boundary, and every
|
|
@@ -33,11 +33,13 @@ gate writes a fingerprint-bound receipt that downstream stages read instead of r
|
|
|
33
33
|
|
|
34
34
|
| Tier | Mode | When | Scope |
|
|
35
35
|
| --- | --- | --- | --- |
|
|
36
|
-
| `light` | `
|
|
37
|
-
| `full` | `
|
|
36
|
+
| `light` | `spur task gate <wbs> light` | after each implement/fix edit | `bunx biome check` on the changed files (`git diff --name-only HEAD` + untracked), `bun run typecheck` per touched workspace, and related tests (`<ws>/src/**/x.ts` → `<ws>/tests/**/x.test.ts` filename mapping) run via `cd <ws> && bun test …` — never from the repo root, whose bunfig preload does not apply inside the workspace |
|
|
37
|
+
| `full` | `spur task gate <wbs> run` | once at the task quality boundary (`test`) | today's chain: `bun run lint` + `bun run test-pre-check` + `bun run test` + `bun run test-post-check` (=`bun run spur-check`), with bounded findings, SQLite-busy retry, and the `recheck` probe |
|
|
38
38
|
|
|
39
|
-
|
|
40
|
-
|
|
39
|
+
Exit contract: `run` and `recheck` return 0 on PASS and 1 on FAIL; `deferred` returns 0 on
|
|
40
|
+
DEFERRED and 1 on FAIL. `light` and `status` return 0; invalid usage returns 2. The pipeline
|
|
41
|
+
wraps selected calls with `; exit 0` and branches on `*-test-gate.status` or receipt `status`;
|
|
42
|
+
that soft shell wrapper does not change the standalone CLI contract.
|
|
41
43
|
|
|
42
44
|
## Receipt
|
|
43
45
|
|
|
@@ -59,8 +61,8 @@ receipt `status`), never in the exit code.
|
|
|
59
61
|
- `inputDigest` is the shared `ProofInputFingerprint` (task markdown + git tree of tracked
|
|
60
62
|
sources). The plugin never computes it — the pipeline captures it with the `proof.fingerprint`
|
|
61
63
|
action into `env.proofDigest` (ADR-124: no second fingerprint, no `@gobing-ai/*` import);
|
|
62
|
-
standalone callers use `inline
|
|
63
|
-
-
|
|
64
|
+
standalone callers use `spur workflow inline fingerprint`.
|
|
65
|
+
- `run` and `recheck` write full-tier receipts; only a PASS at the current digest is reusable. Without a digest, `run` writes no receipt and says
|
|
64
66
|
so in the gate log. The gate executes `qualityGateCmd` as one unit, so the full receipt carries a
|
|
65
67
|
single `test` row for the whole chain; `lint`, `typecheck`, `test-pre-check`,
|
|
66
68
|
`test-post-check` name the chain steps the full tier covers.
|
|
@@ -70,12 +72,11 @@ receipt `status`), never in the exit code.
|
|
|
70
72
|
|
|
71
73
|
## Reuse rule
|
|
72
74
|
|
|
73
|
-
Check `status` mode before re-running a gate.
|
|
74
|
-
|
|
75
|
+
Check `status` mode before re-running a gate. The gate ships inside the CLI (no plugin script to
|
|
76
|
+
resolve):
|
|
75
77
|
|
|
76
78
|
```bash
|
|
77
|
-
|
|
78
|
-
bun "$QG" status # env: wbs, proofDigest → prints {"reuse":…,"reason":…}
|
|
79
|
+
spur task gate <wbs> status --proof-digest "$proofDigest" --no-logo # final stdout line: {"reuse":…,"reason":…}
|
|
79
80
|
```
|
|
80
81
|
|
|
81
82
|
`reuse: true` only when the receipt is `status: PASS`, `tier: full`, and `inputDigest` equals the
|
|
@@ -103,8 +104,8 @@ preserved by construction. `recheck` stays the no-progress probe path for fix lo
|
|
|
103
104
|
|
|
104
105
|
## Gotchas
|
|
105
106
|
|
|
106
|
-
1. **
|
|
107
|
-
|
|
107
|
+
1. **Keep gate logic in the CLI/application owner** — plugin skills invoke `spur task gate`;
|
|
108
|
+
they do not restore a script or bundle. The digest arrives via `--proof-digest` or `env.proofDigest`.
|
|
108
109
|
2. **Never run light tests from the repo root** — the workspace `bunfig.toml` preload (coverage,
|
|
109
110
|
thresholds) only applies inside the workspace; `cd <ws> && bun test …` is the contract.
|
|
110
111
|
3. **Light is a filter, not a boundary** — unmapped files (root-level scripts, non-src layouts)
|
|
@@ -44,7 +44,7 @@ Pick the noun, read its reference. Each Tier A and Tier B reference owns that no
|
|
|
44
44
|
| **Tier A** | **feature** | Feature tree: author with hierarchical IDs (DD-14), acceptance criteria (Gherkin), status lifecycle, move subtrees, `check --json` | [references/features.md](references/features.md) |
|
|
45
45
|
| **Tier A** | **rule** | Constraint quality gate: run presets, author rules, fine-tune, validate rule files/presets, extend engine | [references/rules.md](references/rules.md) |
|
|
46
46
|
| **Tier A** | **workflow** | Dual-mode workflow runtime: author state-machine / transition-flow workflows, validate, run, read traces | [references/workflows.md](references/workflows.md) |
|
|
47
|
-
| **Tier A** | **builder** | Release plumbing: bump
|
|
47
|
+
| **Tier A** | **builder** | Release/PR plumbing: `bump-ver` (including read-only `--check`), `drop-tags`, `publish`, and `pr` review operations | [references/builder.md](references/builder.md) |
|
|
48
48
|
| **Tier B** | **agent** | Coding-agent execution surface: run prompts via detected/named agents, list agent specs (incl. `agent.fleet` members), start/stop supervised processes, fleet `report`/`join`/`leave`/`wait`/`trace`, readiness check | [references/agent.md](references/agent.md) |
|
|
49
49
|
| **Tier B** | **message** | Durable inter-agent messaging: send, inbox, reply, watch | [references/message.md](references/message.md) |
|
|
50
50
|
| **Tier B** | **self** | Self-management verbs: scaffold (`init`), database maintenance (`maintain`), schema migrations (`migrate`), local web server (`serve`), status overview (`status`); `self init` runs post-scaffold validation probes & layout classification | [references/self.md](references/self.md) |
|