@gobing-ai/spur 0.3.46 → 0.3.47

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
     },
     "plugins": [
         {
-            "version": "0.3.46",
+            "version": "0.3.47",
             "name": "sp",
             "source": "./plugins/sp",
             "description": "Spur - my harness toolkits"

package/config/templates/docs/99_PROJECT_CONSTITUTION.md

@@ -3,7 +3,7 @@ name: Project Constitution
 doc: 99_PROJECT_CONSTITUTION
 owns: PROCESS — how the key files are maintained
 authority: authoritative-on-process
-version: 1.3.0
+version: 1.4.0
 created_at: {{init-date}}
 updated_at: {{init-date}}
 edit_rules: 99 §6.8
@@ -148,6 +148,10 @@ Rules:
   same change.
 - `AGENTS.md` may **add** project facts; it may never **contradict** the numbered docs. On
   contradiction, the numbered doc wins — fix `AGENTS.md`.
+- In a monorepo, subdirectory `AGENTS.md` files merge with the root: the agent reads the root
+  first, then the file for the package it is working in. Each level carries only its own scope —
+  the root holds what spans packages, a package file holds what is true of that package alone.
+  Never restate one level's facts at another.
 
 ### 4.5 Index + satellite docs (`04`/`05` and their folders)
 
@@ -344,11 +348,19 @@ with raw file writes.
 1. Factual blocks that mirror code — the command surface, the workspace layout, tool versions —
    are **regenerated from code**, never edited from memory. Verify with the actual registrations
    (e.g. list the CLI's registered nouns/verbs) before writing the block.
-2. Keep it lean: link to the owning doc instead of restating its facts. `AGENTS.md` repeats only
+2. File structure is the most perishable thing you can write down: paths move, and a stale path
+   sends an agent confidently to a file that is not there. Prefer capabilities and domain
+   vocabulary — which outlive layout — over directory listings; where a concrete path is genuinely
+   needed, regenerate it from code per rule 1.
+3. Keep it lean: link to the owning doc instead of restating its facts. `AGENTS.md` repeats only
    what an agent needs in the first 30 seconds of a session.
-3. Surfaces that are decided-but-unbuilt are flagged as planned with their ADR pointer, and
+4. Keep the instruction count inside a budget: roughly 150–200 instructions, beyond which an agent
+   attends to them unevenly and the marginal rule buys nothing (MEDIUM confidence — secondary
+   citation, not measured here). Over budget, cut the rule or move it to its owning doc and link
+   per rule 3.
+5. Surfaces that are decided-but-unbuilt are flagged as planned with their ADR pointer, and
    marked "do not invoke as if they exist".
-4. Re-synced whenever this file changes the map or process (§4.4).
+6. Re-synced whenever this file changes the map or process (§4.4).
 
 ### 6.8 This file (`99`)
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.3.46",
+    "version": "0.3.47",
     "description": "Spur CLI — local-first harness for mainstream coding agents: constraint checking, workflow orchestration, agent health, and history analytics. Bun-native; exposes the `spur` command.",
     "keywords": [
         "spur",

package/plugins/sp/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "sp",
-    "version": "0.3.46",
+    "version": "0.3.47",
     "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/skills/issue-finding/SKILL.md

@@ -202,7 +202,7 @@ Before any ad-hoc verification SQL against `history_*` tables, follow the schema
 | `test-loop`       | Same test command run 3+ times with no source edit between runs           | (identical runs − 1) × ~2 min |
 | `guard`           | 3+ `spur task check` calls for the same task before pass                  | (extra checks) × ~3 min       |
 | `compaction`      | Compactions > 5 per session                                               | count × ~2.5 min              |
-| `section-write`   | `spur task update --section` calls > 2× task count                        | (extra writes) × ~2 min       |
+| `section-write`   | `spur task update --section` calls per task > 1.5× the canonical section count for the task's variant/status matrix entry (feature-impl ≈ 9 sections ⇒ flag > ~13 writes/task; one write per canonical section is correct behavior, not waste) | (extra writes) × ~2 min       |
 | `git-red-herring` | `git stash` / `git branch` / `git diff` between test failures             | ~5–20 min per incident        |
 | `verbose-output`  | Unfiltered test output flooding (e.g. bare `tail` without failure filter) | per-run × ~1500 tokens        |
 

package/plugins/sp/skills/issue-finding/references/session-formats.md

@@ -47,12 +47,18 @@ When parsing a line of JSONL, look for tool/function invocations under common sh
 
 | Source family | Typical tool block type / path | Bash/command field |
 |---------------|--------------------------------|--------------------|
-| OMP / omp-agent | `message.content[]` entries with `type: "toolCall"` | `input.command` |
+| OMP / omp-agent | `message.content[]` entries with `type: "toolCall"` | `arguments.command` |
 | Claude Code | `type: "tool_use"` (or nested message content) | `input.command` / `input` |
 | Codex / others | Importer-normalized or vendor-specific; search for `command`, `tool_name`, `name` | best-effort |
 
 Always record **what field path you used** in the inventory Notes so evidence is auditable.
 
+**Fail-loud rule:** a zero tool-command count across a **non-empty** session set means the field map
+is wrong, not that the sessions were idle. Report a probable field-map error instead of an
+idle-session / no-waste finding — a parser that matches nothing must never produce a clean verdict
+(0534 R3; the OMP shape is `arguments.command`, verified: a toolCall block's keys are
+`['arguments','id','intent','name','partialArgs','streamIndex','type']`).
+
 **Loop detection (all sources):** normalize the shell command string and count consecutive or
 near-consecutive identical invocations (≥3) without an intervening source-file edit tool call.
 
@@ -63,7 +69,8 @@ OMP/agent session logs are JSONL under `~/.omp/agent/sessions/-<project>/`:
 - Each line is a JSON object with a `type` field
 - Key event types: `session`, `message`, `compaction`, `title`, `title_change`, `custom`
 - Tool calls live in `message.content` as blocks with `type: "toolCall"` (**not** `tool_use`)
-- Bash tool calls expose `input.command`
+- Bash tool calls expose `arguments.command` (verified live against OMP JSONL: a toolCall block's
+  keys are `['arguments','id','intent','name','partialArgs','streamIndex','type']`)
 - Subagent sessions live in subdirectories (e.g. `Run0376/`, `Refine0378/`)
 - Subagents may have `*.log` beside the JSONL session file
 - Session start: `session.timestamp`

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

@@ -99,6 +99,9 @@ spur feature update H2 --section "Acceptance Criteria" --from-file /tmp/ac.md
 `--section` **requires** `--from-file` (exit `2` otherwise). Replaces the whole named section body.
 The `## Tasks` block is still rebuilt by `refresh` (files win for that region).
 
+Valid section names without a failed write: `spur task sections <wbs> list` (the same pointer
+`spur task update --help` carries).
+
 **Advance** (multi-hop forward walk):
 
 ```bash

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

@@ -24,6 +24,7 @@ Start from the WBS, not the corpus layout:
 
 ```bash
 spur task show <wbs> --json  # metadata + full content + filePath
+spur task get  <wbs> --json  # alias of `show` — same output, no separate code path
 spur task path <wbs> --json  # absolute path only
 ```
 
@@ -148,6 +149,8 @@ spur task update 0040 --section Review --from-file /tmp/review.md
   read from a file (this is what makes edits crash-safe and reviewable). Exit `2` otherwise.
 - Section names match the DD-08 task headings: `Background`, `Acceptance Criteria`, `Plan`,
   `Solution`, `Testing`, `Review`, `References`, `History`.
+- Valid section names without a failed write: `spur task sections <wbs> list` (the same
+  pointer `task update --help` carries).
 - The write replaces the **whole** named section body; assemble the full section in the temp file
   first, then point `--from-file` at it.
 

package/spur.js

@@ -67691,7 +67691,7 @@ class FeatureService {
     const current = await this.ctx.fs.readFile(ref.filePath);
     const doc2 = MarkdownDocument.parse(current, "feature");
     if (!doc2.sectionNames.includes(sectionName)) {
-      throw new Error(`Feature ${id} does not contain section "${sectionName}". Available sections: ${doc2.sectionNames.join(", ")}`);
+      throw new Error(`Feature ${id} does not contain section "${sectionName}". Available sections: ${doc2.sectionNames.join(", ")}. ` + "To list valid section names without a failed write: `spur task sections <wbs> list`.");
     }
     const raw = await this.ctx.fs.readFile(sourceFile);
     const body = stripLeadingSectionHeader(raw, sectionName);
@@ -84106,7 +84106,7 @@ function registerFeatureCommand(program2, context4) {
       context4.setExitCode(1);
     }
   });
-  feature.command("show").summary("Show a feature by ID.").argument("<id>", "Feature ID").option("--folder <path>", "Custom features folder").option("--json", "Output machine-readable JSON").action(async (id, options) => {
+  feature.command("show").alias("get").summary("Show a feature by ID.").argument("<id>", "Feature ID").option("--folder <path>", "Custom features folder").option("--json", "Output machine-readable JSON").action(async (id, options) => {
     const svc = await makeService(context4, options.folder);
     try {
       const result = await svc.show(id);
@@ -84126,7 +84126,12 @@ function registerFeatureCommand(program2, context4) {
       context4.setExitCode(1);
     }
   });
-  feature.command("update").summary("Update a feature status, scalar frontmatter field, or section body.").argument("<id>", "Feature ID").argument("[status]", "New lifecycle status").option("--field <key>", "Frontmatter field to set (e.g. priority)").option("--value <value>", "New value for --field").option("--section <name>", "Section name to replace").option("--from-file <path>", "File to read section body from (requires --section)").option("--folder <path>", "Custom features folder").option("--json", "Output machine-readable JSON").action(async (id, status, options) => {
+  feature.command("update").summary("Update a feature status, scalar frontmatter field, or section body.").argument("<id>", "Feature ID").argument("[status]", "New lifecycle status").addHelpText("after", [
+    "Section names are validated against the closed-world canonical set; a rejected",
+    "`--section` costs a failed write. List valid names first:",
+    "`spur task sections <wbs> list`."
+  ].join(`
+`)).option("--field <key>", "Frontmatter field to set (e.g. priority)").option("--value <value>", "New value for --field").option("--section <name>", "Section name to replace").option("--from-file <path>", "File to read section body from (requires --section)").option("--folder <path>", "Custom features folder").option("--json", "Output machine-readable JSON").action(async (id, status, options) => {
     const svc = await makeService(context4, options.folder);
     try {
       let result;
@@ -84462,7 +84467,7 @@ import { createRequire } from "module";
 var CLI_CONFIG = {
   binaryName: "spur",
   binaryLabel: "spur",
-  binaryVersion: "0.3.46",
+  binaryVersion: "0.3.47",
   configDir: ".spur",
   configFile: ".spur/config.yaml",
   databaseFile: ".spur/spur.db"
@@ -96308,7 +96313,7 @@ function registerTaskCommand(program2, context4) {
       }
     }
   });
-  task.command("show").summary("Show a task by WBS.").argument("<wbs>", "Task WBS number").option("--folder <path>", "Custom tasks folder").option("--json", "Output machine-readable JSON").action(async (wbs, options) => {
+  task.command("show").alias("get").summary("Show a task by WBS.").argument("<wbs>", "Task WBS number").option("--folder <path>", "Custom tasks folder").option("--json", "Output machine-readable JSON").action(async (wbs, options) => {
     const svc = await makeService2(context4, options.folder);
     try {
       const result = await svc.show(wbs);
@@ -96332,7 +96337,8 @@ ${result.content}`);
     "A GuardDeniedError on `testing \u2192 done` means no pipeline run is recorded for the",
     "task: run `/sp:dev-verify <wbs> --next` to PASS it, or record the audited bypass with",
     '`SPUR_PROVENANCE_OVERRIDE=1 spur task update <wbs> done --force-done --reason "\u2026"`.',
-    "See the gate checklist (spur-dev/references/gate-checklists.md)."
+    "See the gate checklist (spur-dev/references/gate-checklists.md).",
+    "Valid section names (no failed write): `spur task sections <wbs> list`."
   ].join(`
 `)).option("--section <name>", "Section name to replace").option("--from-file <path>", "File to read section body from (requires --section)").option("--feature <id>", "Set the feature_id frontmatter field (traceability edge)").option("--priority <p>", "Set the priority frontmatter field (P0\u2013P3)").option("--ac-numbering <mode>", "Set the ac_numbering frontmatter field (task-local) \u2014 opts the task into the Requirements\u2194AC coverage check").option("--no-lifecycle", "Suppress lifecycle workflow run creation (use during pipeline runs to avoid orphaned lifecycle runs)").option("--force-done", "Allow transitioning to `done` even when the verify verdict is not PASS; records an override (task 0292). Waives the verdict only \u2014 the FSM path still applies, so from an earlier status walk the hops first: `todo` \u2192 `wip` \u2192 `testing` \u2192 `done` (each hop runs the structural `spur task check`)").option("--reason <text>", "Rationale for a forced-done override (paired with --force-done; persisted as done_reason)").option("--verdict-dir <path>", "Directory holding <wbs>-verdict.json artifacts (default: .spur/run)").option("--folder <path>", "Custom tasks folder").option("--json", "Output machine-readable JSON").action(async (wbs, status, options) => {
     const svc = await makeService2(context4, options.folder, options.lifecycle === false);