@gobing-ai/spur 0.3.49 → 0.3.51

package/config/rules/quality/coverage-gate.yaml

@@ -2,8 +2,9 @@ $schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
 # Coverage gate — per-file line coverage meets threshold from Bun's lcov output.
 # Absorbed from ts-libs/.spur/rules/quality/coverage-gate.yaml, re-scoped to
 # Spur's monorepo layout:
-#   - lcovPath kept at .coverage/lcov.info (Spur's `bun run test` writes
-#     coverage there via --coverage-dir=.coverage)
+#   - lcovPath kept at .coverage/lcov.info (Spur's `bun run test:coverage` —
+#     what `bun run check` and the `*:full` chains run — writes coverage there
+#     via --coverage-dir=.coverage; plain `bun run test` skips coverage)
 #   - include expanded to apps/** + packages/** (Spur tests cover both;
 #     ts-libs only covers packages/**)
 #   - threshold kept at 90 matching bunfig.toml coverageThreshold

package/config/workflows/pr-review.yaml

@@ -43,19 +43,21 @@ terminalStates:
 failureStates:
   - failed
 vars:
-  mode: 'full'
-  baseBranch: ''
-  focus: ''
-  noWait: 'false'
-  waitTimeoutSec: '600'
-  waitIntervalSec: '30'
-  preReviewCmd: ''
-  __runId: ''
+  mode: "full"
+  baseBranch: ""
+  focus: ""
+  noWait: "false"
+  waitTimeoutSec: "600"
+  waitIntervalSec: "30"
+  preReviewCmd: ""
+  __runId: ""
 
 states:
   - id: preflight
     description: >
-      Soft probe: git/gh/repo checks (detached HEAD, dirty tree, gh auth, GitHub remote).
+      Soft probe: git/gh/repo checks (detached HEAD, dirty tree, gh auth, GitHub remote,
+      base-branch refusal — preflight refuses when the current branch IS the resolved base,
+      before any push can publish it).
       Writes PASS|FAIL to .spur/run/${vars.__runId}-pr-preflight.status; always exit 0.
     onEnter:
       - kind: shell
@@ -64,7 +66,7 @@ states:
             mkdir -p .spur/run &&
             STATUS_FILE=".spur/run/$__runId-pr-preflight.status" &&
             set +e &&
-            bun "$(superskill script path sp pr-reviewing.ts)" preflight --json > ".spur/run/$__runId-pr-context.json";
+            bun "$(superskill script path sp pr-reviewing.ts)" preflight --base "$baseBranch" --json > ".spur/run/$__runId-pr-context.json";
             rc=$?; set -e &&
             if [ "$rc" -eq 0 ]; then printf 'PASS\n' > "$STATUS_FILE"; else printf 'FAIL\n' > "$STATUS_FILE"; fi &&
             exit 0
@@ -212,7 +214,7 @@ transitions:
         command: 'test "$(cat .spur/run/$__runId-pr-preflight.status 2>/dev/null)" = PASS'
   - from: preflight
     to: failed
-    description: Preflight red (detached HEAD, dirty tree, gh auth, no GitHub remote) — stop before any publishing
+    description: Preflight red (detached HEAD, dirty tree, gh auth, no GitHub remote, or the current branch being the base branch) — stop before any publishing
     guard:
       kind: always
 

package/config/workflows/task-pipeline.yaml

@@ -85,6 +85,12 @@ vars:
   # TRUSTED CONFIG ONLY — this string is executed via `sh -c` (see test/test-recheck). Never
   # interpolate untrusted operator/LLM input into qualityGateCmd (task 0436 SECUA residual).
   qualityGateCmd: "bun run format && bun run spur-check"
+  # Cheap red-detector run before the full gate on **recheck only**; empty ⇒ no probe
+  # (full gate every recheck — the pre-0587 behavior). A project overriding qualityGateCmd
+  # should override this too. TRUSTED CONFIG ONLY — executed via `sh -c` (same surface as
+  # qualityGateCmd). Invariant: `review` is only ever entered through a full green
+  # qualityGateCmd — only the full gate writes PASS to <wbs>-test-gate.status.
+  gateProbeCmd: "bun run lint"
   # Max /sp:dev-fixall attempts after a red quality-gate probe/recheck (bounded; no thrash).
   # Attempt counter: .spur/run/<wbs>-test-fix-attempt. Default 2 = two fixall hops before failed.
   qualityGateMaxFixAttempts: "2"
@@ -300,7 +306,7 @@ states:
       # `${vars.qualityGateCmd}` at `test` is the gate that actually decides.
       - kind: shell
         options:
-          command: '$formatCmd ; exit 0'
+          command: "$formatCmd ; exit 0"
 
   # ── test hop (quality gate + bounded auto-fix) ─────────────────────────────
   # NOT /sp:dev-unit. That command (sp:code-testing) *extends/generates* tests toward
@@ -389,28 +395,43 @@ states:
       or the pipeline `failed` state (FAIL and attempts exhausted) — never a
       raw lifecycle abort that skips the terminal `failed` state.
     onEnter:
+      # 0587 R3: probe-then-full recheck. A red gateProbeCmd records FAIL and skips the full
+      # gate (the measured waste is re-running a 110–140s gate to learn the tree is still red);
+      # a green probe (or empty gateProbeCmd) falls through to the full-gate loop unchanged.
+      # Only the full gate writes PASS, so the `test-recheck → review` guard (reads PASS)
+      # still means a full green qualityGateCmd ran — invariant preserved by construction.
       - kind: shell
         options:
           command: >-
             mkdir -p .spur/run &&
             STATUS_FILE=".spur/run/$wbs-test-gate.status" &&
             LOG_FILE=".spur/run/$wbs-test-gate.log" &&
+            FINDINGS_FILE=".spur/run/$wbs-test-gate.findings" &&
             : > "$LOG_FILE" &&
-            gate_attempt=1;
-            while [ "$gate_attempt" -le 5 ]; do
-              ATTEMPT_LOG="$LOG_FILE.attempt-$gate_attempt";
-              sh -c "$qualityGateCmd" > "$ATTEMPT_LOG" 2>&1; gate_rc=$?;
-              gate_locked=0;
-              grep -q 'SQLiteError: database is locked' "$ATTEMPT_LOG" && gate_locked=1;
-              cat "$ATTEMPT_LOG" >> "$LOG_FILE";
-              rm -f "$ATTEMPT_LOG";
-              if [ "$gate_rc" -eq 0 ] || [ "$gate_locked" -ne 1 ] || [ "$gate_attempt" -ge 5 ]; then break; fi;
-              printf 'quality gate: database is locked; retrying (%s/5) in 10s\n' "$gate_attempt" | tee -a "$LOG_FILE";
-              sleep 10;
-              gate_attempt=$((gate_attempt + 1));
-            done &&
+            probe_rc=0;
+            if [ -n "$gateProbeCmd" ]; then
+              sh -c "$gateProbeCmd" > "$LOG_FILE.probe" 2>&1; probe_rc=$?;
+              cat "$LOG_FILE.probe" >> "$LOG_FILE";
+              rm -f "$LOG_FILE.probe";
+            fi;
+            if [ "$probe_rc" -ne 0 ]; then
+              gate_rc=$probe_rc;
+            else
+              gate_attempt=1;
+              while [ "$gate_attempt" -le 5 ]; do
+                ATTEMPT_LOG="$LOG_FILE.attempt-$gate_attempt";
+                sh -c "$qualityGateCmd" > "$ATTEMPT_LOG" 2>&1; gate_rc=$?;
+                gate_locked=0;
+                grep -q 'SQLiteError: database is locked' "$ATTEMPT_LOG" && gate_locked=1;
+                cat "$ATTEMPT_LOG" >> "$LOG_FILE";
+                rm -f "$ATTEMPT_LOG";
+                if [ "$gate_rc" -eq 0 ] || [ "$gate_locked" -ne 1 ] || [ "$gate_attempt" -ge 5 ]; then break; fi;
+                printf 'quality gate: database is locked; retrying (%s/5) in 10s\n' "$gate_attempt" | tee -a "$LOG_FILE";
+                sleep 10;
+                gate_attempt=$((gate_attempt + 1));
+              done;
+            fi &&
             cat "$LOG_FILE" &&
-            FINDINGS_FILE=".spur/run/$wbs-test-gate.findings" &&
             set +e; grep -oE '[A-Za-z0-9_./-]+\.[A-Za-z]+:[0-9]+' "$LOG_FILE" | sort -u | head -20 | tr '\n' ' ' > "$FINDINGS_FILE"; set -e &&
             if [ "$gate_rc" -eq 0 ]; then
               printf 'PASS\n' > "$STATUS_FILE";
@@ -709,4 +730,4 @@ transitions:
     guard:
       kind: shell
       options:
-        command: '! $spurBin task check $wbs'
+        command: "! $spurBin task check $wbs"

package/package.json

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

package/plugins/sp/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "sp",
-    "version": "0.3.49",
+    "version": "0.3.51",
     "description": "Spur — a local-first harness engineering toolkit that wraps mainstream coding agents with constraint checking, workflow orchestration, and history analytics.",
     "extensions": {
         "pi": ["./hooks/pi/guard-extension.ts"]

package/plugins/sp/scripts/pr-reviewing.ts

@@ -88,6 +88,12 @@ interface PreflightContext {
     defaultBranch: string;
 }
 
+interface Upstream {
+    ref: string;
+    ahead: number;
+    behind: number;
+}
+
 interface Finding {
     kind: 'review' | 'inline' | 'comment';
     severity: string;
@@ -433,6 +439,22 @@ function preflightContext(): PreflightContext {
     };
 }
 
+/** Upstream divergence, non-fatal: a missing upstream is a normal state, not an error. */
+function resolveUpstream(): Upstream | null {
+    const refRes = run(['git', 'rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}']);
+    if (refRes.code !== 0) return null;
+    const ref = refRes.stdout.trim();
+    const count = (res: CmdResult): number => {
+        const n = Number(res.stdout.trim());
+        return res.code === 0 && Number.isFinite(n) ? n : 0;
+    };
+    return {
+        ref,
+        ahead: count(run(['git', 'rev-list', '--count', '@{u}..HEAD'])),
+        behind: count(run(['git', 'rev-list', '--count', 'HEAD..@{u}'])),
+    };
+}
+
 function viewPr(): GhPr | null {
     const res = run([
         'gh',
@@ -507,15 +529,27 @@ function cmdPreflight(args: ParsedArgs): void {
             2,
         );
     }
+    const base = (args.flags.get('--base') ?? '').trim() || ctx.defaultBranch;
+    const upstream = resolveUpstream();
+    if (ctx.branch === base) {
+        writeStatus(args, 'FAIL');
+        fail(
+            args,
+            `current branch is the base branch (${base}) — a PR reviews a feature branch against it; ` +
+                'check out a feature branch (nothing on the base branch is reviewable)',
+            2,
+        );
+    }
     writeStatus(args, 'PASS');
     emit(
         args,
-        { ok: true, ...ctx },
+        { ok: true, ...ctx, upstream },
         [
             `Repository: ${ctx.nameWithOwner}`,
             `Branch:     ${ctx.branch}`,
             `HEAD:       ${ctx.shortHead}`,
             `Default:    ${ctx.defaultBranch}`,
+            `Upstream:   ${upstream ? `${upstream.ref} (ahead ${upstream.ahead}, behind ${upstream.behind})` : `none (publishing would create origin/${ctx.branch})`}`,
             'Local:      clean',
         ].join('\n'),
     );

package/plugins/sp/skills/code-verification/SKILL.md

@@ -127,6 +127,20 @@ heading/comment unrelated to the requirement fails the row to UNMET and surfaces
 a finding (severity >= P2). This closes the gap where a verify run certified a task `done` citing
 `evidence:134` that was actually a sibling ticket's telemetry text (0299 R1, from the 0282 re-audit).
 
+**External evidence (task 0584 / ADR-062) — legal citation form.** Evidence that lives OUTSIDE this
+repository has a frozen non-anchor form: a named origin plus a backticked path with the line number
+**outside** the backticks.
+
+```
+Evidence: @gobing-ai/ts-llm-jsonl-importer `src/mappers.ts` line 481 — omp call_id write
+```
+
+Use this form ONLY when the evidence genuinely lives outside `spur`'s working tree (a `@gobing-ai/ts-*`
+source under `~/xprojects/ts-libs`, or a gitignored `.spur/run/**` artifact). `checkLineAnchors`
+classifies it as external and never raises `L4.stale-line-anchor` for it (R1). Do NOT use it for a file
+that lives in this repo — in-repo evidence MUST use the repo-relative backtick form
+`` `path:line` `` / `` `path:start-end` ``, and citing it in the external form still reports (R2).
+
 ### Step 5 — Acceptance Criteria guard
 
 If the task has a non-empty Acceptance Criteria section, evaluate every checklist item and every

package/plugins/sp/skills/pr-reviewing/SKILL.md

@@ -135,9 +135,12 @@ bun "$(superskill script path sp pr-reviewing.ts)" <subcommand> [flags]
 Installed targets resolve the staged TypeScript source and execute it with Bun, matching the rest
 of `plugins/sp/scripts`.
 
-1. **Preflight** — `<script> preflight --json`. Hard-fails on a
-   detached HEAD, missing `gh` auth, no GitHub remote, or a dirty tree. On a dirty tree, triage
-   with the user (commit/stash/exclude) before continuing — the workflow refuses to guess.
+1. **Preflight** — `<script> preflight --base "$base" --json`. Hard-fails on a
+   detached HEAD, missing `gh` auth, no GitHub remote, a dirty tree, or the current branch
+   being the base branch (a PR reviews a feature branch against the base; nothing on the
+   base branch is reviewable, and the guard runs before any push can publish it). On a
+   dirty tree, triage with the user (commit/stash/exclude) before continuing — the
+   workflow refuses to guess.
 2. **Hygiene** — `<script> hygiene --base "$base" --json`. `BLOCK` (secrets, `.env`, conflict markers,
    private keys) stops the run — never submit a tainted diff. `WARN` (debug residue) rides along
    into the report. This is a submission sanity check, not a second local review.

package/plugins/sp/skills/spur-cli/references/tasks.md

@@ -46,6 +46,7 @@ re-reading or re-tokenizing the task.
 | `list` | List tasks, filtered | `--status <s>` `--phase <p>` `--parent <wbs>` `--feature <id>` `--folder` `--json` |
 | `refresh` | Re-scan the corpus and report counts (**`kanban.md` retired** — web Task Kanban is SSOT) | `--folder` `--json` |
 | `migrate` | One-time A17 corpus normalization pass | `--dry-run` `--folder` `--json` |
+| `migrate-anchors` | Qualify in-repo evidence anchors to repo-relative paths (0583 R1–R3) | `--dry-run` `--json` |
 | `refresh-roster <wbs>` | Regenerate a parent task's sub-task roster block in `## Plan` | `--folder` `--json` |
 | `batch-create` | Create many tasks from a validated JSON array | `--file <path>` `--folder` `--json` |
 | `record <wbs>` | Write Testing/Review from a verify verdict; optional Solution + transition | `--verdict-file <path>` `--solution-from-diff` `--transition <status>` `--folder` `--json` |

package/plugins/sp/skills/spur-dev/references/ac-style-guide.md

@@ -103,7 +103,7 @@ omission is now reported as an `ac-row-dropped` check naming the row and the unr
 `rowMatchesScenario` accepts any of these as naming the feature scenario `R3 — Foo`:
 
 | Form | Example |
-|------|---------|
+| ------ | --------- |
 | Exact title | `R3 — Foo` |
 | Bare title (R-prefix dropped) | `Foo` |
 | `Scenario:` prefix | `Scenario: R3 — Foo` |
@@ -201,7 +201,7 @@ regenerates the `## Tasks` block.
 Each resolved decision from a grilling interview (Phase 1) becomes one or more Gherkin scenarios:
 
 | Decision-tree element | Becomes |
-|-----------------------|---------|
+| ----------------------- | --------- |
 | A **locked decision** (a capability the feature commits to) | A `@core` scenario — the must-ship behavior it enables |
 | The decision's **observable outcome** (why it was chosen) | The scenario's `Then` — assert the observable, not the mechanism |
 | A decision's **preconditions / constraints** | The scenario's `Given` |
@@ -211,3 +211,19 @@ Each resolved decision from a grilling interview (Phase 1) becomes one or more G
 
 Number scenarios `R1, R2, …` sequentially, stable forever (the title is the traceability identity
 key). Use the Gherkin template at `.spur/templates/bdd/gherkin.md`.
+
+## AC altitude (task 0584 / ADR-062)
+
+A task must declare, via the `ac_altitude` frontmatter field, whether its AC scenarios are the
+feature's ship contract or a finer-grained local contract. The field is the **only** input — it is
+never inferred from `template`, `status`, or whether the AC uses Gherkin (R4).
+
+| `ac_altitude` | Meaning | DD-09 subset rule |
+| --- | --- | --- |
+| `graduating` (or absent) | Task scenarios are ship-contract criteria that graduate the feature's AC | Enforced — every task scenario must match a linked-feature scenario by normalized title. Drifted titles still report (R5). |
+| `task-local` | Task criteria sit at a finer altitude than the feature's ship contract (fix-task regression criteria, per-defect cases) | Skipped — no uncovered-scenario findings regardless of title drift (R3) |
+
+Use `task-local` for a fix/refactor task whose regression criteria are not the feature's ship
+contract. Keep a `graduating` task's scenario titles identical to the feature's so DD-09 stays
+satisfied. Absent-altitude is `graduating` — set `task-local` explicitly only where the subset rule
+truly does not apply (do not silently default new tasks to it).

package/plugins/sp/skills/spur-dev/references/cross-cutting.md

@@ -24,7 +24,6 @@ not redefine it.
 > does not restate the contract. The value table below is authoritative; parity with it is
 > enforced by `validate-flag-contracts.ts` (C3a/C3b).
 
-
 ### The one rule
 
 > **`--agent <value>` names *who* does the model-bearing work. The execution surface is derived from
@@ -49,7 +48,7 @@ selects the zero-dispatch carve-out below.
 > fallback.**
 
 | Value | Who does the work | Derived surface |
-|---|---|---|
+| --- | --- | --- |
 | `(omitted)` | The agent running this session | Host session — host-controlled; eligible model stages may use a native subagent (0508) |
 | `inline` | The agent running this session | Host session — hard guarantee: zero dispatch, never a subprocess, never a workflow hop; headless surfaces reject `inline` (exit 2, stable special error) |
 | `auto` | The role the caller declared — this command's `role:` frontmatter or the workflow step's `role:` (Layer 1, `plugins/sp/references/roles.md`); with nothing declared, `agent.default`'s role (0542) | Subprocess — a tier-resolved executor pins a specific agent/model, which the host session cannot supply |
@@ -219,7 +218,7 @@ stage is required, select the subprocess path (`--agent auto` or `--agent <name>
 Never edit a task or feature file directly. Every mutation goes through:
 
 | Intent | CLI verb |
-|--------|----------|
+| -------- | ---------- |
 | Create a task | `spur task create` |
 | Change status | `spur task update <wbs> <status>` |
 | Edit a section | `spur task update <wbs> --section <name> --from-file <path>` |
@@ -329,6 +328,15 @@ loop?**
   operator, and the *answer* is recorded where the decision belongs — the feature body, an ADR
   (`docs/00_ADR.md`), or the design doc. A task may then be created for the work the answer implies.
 
+**Authoring-contract decisions (task 0584 / ADR-062).** Two fields a task author must get right:
+
+- **External evidence** — evidence that lives outside `spur`'s working tree uses the frozen non-anchor
+  form `origin`path`line N` (line OUTSIDE the backticks), e.g.
+  `@gobing-ai/ts-llm-jsonl-importer`src/mappers.ts`line 481`. It is classified external, never
+  `L4.stale-line-anchor`. In-repo evidence MUST use the repo-relative backtick form `path:line` —
+  citing an in-repo file in the external form still reports (R1/R2). See `ac-style-guide.md` and the
+  `code-verification` skill for when each applies.
+
 **Why this is a rule and not a preference.** A decision filed as a task sits in `spur task list` and
 in a feature's Tasks table looking like queued work. It gets handed to an implementing agent, which
 either stalls or invents the decision and calls it done. It also inflates task counts, which is how
@@ -432,7 +440,7 @@ line is a claim to re-verify, not evidence to forward. Re-run and paste.
 **Red Flags — an unverified claim is usually hiding behind one of these:**
 
 | Red flag | What it usually means |
-|---|---|
+| --- | --- |
 | "This should work" / "this will pass" / "probably fine" | You are predicting, not reporting. Run it and paste the result. |
 | Expressing satisfaction ("great, that's done!") before any check ran | Relief is not evidence — the check has not been run this turn. |
 | Forwarding a subagent's "success" without re-running its gate | You are trusting a claim, not verifying it. Re-run the check yourself. |
@@ -529,7 +537,7 @@ invariants that keep the pipeline set coherent as new ones are added.
 ### Pipeline phase table
 
 | Pipeline | Lifecycle phase | Entry point | Terminal states |
-|---|---|---|---|
+| --- | --- | --- | --- |
 | `idea-pipeline.yaml` | Ideation (vague idea → feature + AC + task batch) | `/sp:dev-idea` | `handoff`, `cancelled` |
 | `planning-pipeline.yaml` | Design (known slug/task → design handoff) | `/sp:dev-plan` | `handoff`, `cancelled` |
 | `task-pipeline.yaml` | Execution (one task → done) | `/sp:dev-run` | `done`, `failed` |
@@ -691,7 +699,7 @@ The signal is emitted by the `discovery` state's brainstorm dispatch and written
 determine routing:
 
 | `design` var | `needs_design` signal | Route |
-|---|---|---|
+| --- | --- | --- |
 | `skip` | (ignored) | `decompose` (skip system-design; brainstorm summary still recorded) |
 | `auto` | `true` | `system-design` -> `design-approval` -> `decompose` |
 | `auto` | `false` | `decompose` (skip system-design) |