@gobing-ai/spur 0.3.55 → 0.3.58

package/config/rules/strict/runtime-boundaries.yaml

@@ -57,6 +57,7 @@ rules:
 
             # Low-level system primitives (O_EXCL locks, FD byte-tailing, FS watcher, atomic registry, Vite glob fallback):
             - "packages/domain/src/planning/locks.ts" # POSIX atomic O_EXCL file locks
+            - "packages/domain/src/retention.ts" # recursive backup-dir reclamation + mtime stat (task 0622 R8); ts-runtime FileSystem seam has no recursive dir remove
             - "packages/app/src/services/token-ledger-service.ts" # FD byte-window log tailing
             - "packages/app/src/services/token-ledger-watcher.ts" # node:fs watch() live watcher
             - "packages/app/src/services/project-registry.ts" # atomic projects.json persistence
@@ -73,3 +74,5 @@ rules:
             # Synchronous template & workflow resolvers:
             - "apps/cli/src/commands/task.ts" # sync loadTemplateContent/Bodies callbacks
             - "apps/cli/src/workflow/make-lifecycle-adapter.ts" # sync resolveWorkflowPath lookup
+            - "packages/app/src/services/workflow-service.ts" # sync workflow-composition-baseline.json lookup (walk-up) for the validate composition advisory (task 0614); sync read inside the synchronous validate path
+            - "apps/cli/src/release-ops.ts" # sync manifest/workspace reads + Bun.write rewrites inside the git release flow (task 0617); mirrors task.ts sync-template exemption

package/config/rules/surface/check-cli-surface.yaml

@@ -11,6 +11,7 @@ include:
 
 exclude:
   - "apps/cli/src/commands/stubs.ts"
+  - "apps/cli/src/commands/shared-options.ts" # option registry, not a command module (consistency.test.ts excludes it too)
 
 rules:
   - id: cli-register-pattern

package/config/workflow-composition-baseline.json

@@ -114,7 +114,8 @@
                     "kind": "shell",
                     "invocation": "mkdir -p .spur/run && DOCTOR_FILE=\".spur/run/$__runId-idea-precheck-doctor.status\" && set +e && $spurBin agent doctor $agent; doctor_rc=$?; set -e && if [ \"$doctor_rc\" -eq 0 ] && test -n \"$idea\"; then\n  printf 'PASS\\n' > \"$DOCTOR_FILE\";\nelse\n  printf 'FAIL\\n' > \"$DOCTOR_FILE\";\nfi && exit 0",
                     "stateEffect": "read",
-                    "evidenceEffect": "write"
+                    "evidenceEffect": "write",
+                    "disposition": "GLUE"
                 },
                 "discovery:onEnter:0": {
                     "kind": "agent.run",
@@ -166,7 +167,8 @@
                     "kind": "shell",
                     "invocation": "if test -s .spur/run/$__runId-idea-ac-content.md; then\n  $spurBin feature update \"$featureId\" --section \"Acceptance Criteria\" --from-file .spur/run/$__runId-idea-ac-content.md && date -u +%Y-%m-%dT%H:%M:%SZ > .spur/run/$__runId-idea-ac-done.txt;\nelse\n  exit 0;\nfi",
                     "stateEffect": "write",
-                    "evidenceEffect": "none"
+                    "evidenceEffect": "none",
+                    "disposition": "GLUE"
                 },
                 "feature-check:onEnter:0": {
                     "kind": "hitl.confirm",
@@ -218,7 +220,8 @@
                     "kind": "shell",
                     "invocation": "BATCH=\".spur/run/$__runId-idea-task-batch.json\" && ORDER=\".spur/run/$__runId-idea-task-order.json\" && jq -e --slurpfile b \"$BATCH\" '\n  (type == \"array\") and\n  (($b[0] | map(.name) | length) == ($b[0] | map(.name) | unique | length)) and\n  ((map(.name) | length) == (map(.name) | unique | length)) and\n  ((map(.name) - ($b[0] | map(.name))) | length == 0) and\n  ((($b[0] | map(.name)) - map(.name)) | length == 0) and\n  (((map(.depends_on_names // []) | flatten | unique) - ($b[0] | map(.name))) | length == 0)\n' \"$ORDER\" >/dev/null",
                     "stateEffect": "read",
-                    "evidenceEffect": "none"
+                    "evidenceEffect": "none",
+                    "disposition": "GLUE"
                 },
                 "batch-create:onEnter:0": {
                     "kind": "hitl.confirm",
@@ -229,13 +232,15 @@
                     "kind": "shell",
                     "invocation": "if test -f .spur/run/$__runId-idea-batch-create.done; then exit 0; fi; rm -f .spur/run/$__runId-idea-batch-create.failed .spur/run/$__runId-idea-batch-create-result.json .spur/run/$__runId-idea-batch-create-result.json.tmp; if $spurBin task batch-create --file .spur/run/$__runId-idea-task-batch.json --json > .spur/run/$__runId-idea-batch-create-result.json.tmp && jq -e \".created == (.wbs | length)\" .spur/run/$__runId-idea-batch-create-result.json.tmp >/dev/null 2>&1; then\n  mv .spur/run/$__runId-idea-batch-create-result.json.tmp .spur/run/$__runId-idea-batch-create-result.json &&\n  date -u +%Y-%m-%dT%H:%M:%SZ > .spur/run/$__runId-idea-batch-create.done;\nelse\n  rm -f .spur/run/$__runId-idea-batch-create-result.json.tmp;\n  date -u +%Y-%m-%dT%H:%M:%SZ > .spur/run/$__runId-idea-batch-create.failed;\nfi",
                     "stateEffect": "write",
-                    "evidenceEffect": "write"
+                    "evidenceEffect": "write",
+                    "disposition": "GLUE"
                 },
                 "handoff-finalize:onEnter:0": {
                     "kind": "shell",
                     "invocation": "if [ -f packages/app/src/workflow/idea-handoff-cli.ts ]; then\n  bun packages/app/src/workflow/idea-handoff-cli.ts;\n  exit $?;\nfi; BATCH=\".spur/run/$__runId-idea-task-batch.json\" && RESULT=\".spur/run/$__runId-idea-batch-create-result.json\" && ORDER=\".spur/run/$__runId-idea-task-order.json\" && REPORT=\".spur/run/$__runId-idea-handoff.md\" && DEPMAP=\".spur/run/$__runId-idea-dep-map.tsv\" && CHECKS=\".spur/run/$__runId-idea-check-results.jsonl\" && rm -f \"$DEPMAP\" \"$CHECKS\" && jq -e --slurpfile b \"$BATCH\" '(.wbs | length) == ($b[0] | length) and (($b[0] | map(.name) | unique | length) == ($b[0] | length))' \"$RESULT\" >/dev/null && jq -r --slurpfile b \"$BATCH\" --slurpfile r \"$RESULT\" --slurpfile o \"$ORDER\" '\n  ($b[0] | map(.name)) as $names | ($r[0].wbs) as $wbs |\n  $o[0] | .[] |\n  (.name as $n | $names | index($n)) as $i |\n  (if $i == null or $wbs[$i] == null then \"MISSING\" else $wbs[$i] end) as $own |\n  ((.depends_on_names // []) | map(. as $dep | $names | index($dep) as $d | if $d == null then \"MISSING\" else $wbs[$d] end) | join(\" \")) as $deps |\n  [.name, $own, $deps] | @tsv\n' \"$ORDER\" > \"$DEPMAP\" && while IFS=\"$(printf '\\t')\" read -r name own deps; do\n  test \"$own\" != MISSING || exit 1;\n  if test -n \"$deps\"; then\n    for d in $deps; do test \"$d\" != MISSING || exit 1; done;\n    $spurBin task deps \"$own\" set $deps --json >/dev/null || exit 1;\n  fi;\ndone < \"$DEPMAP\" && $spurBin feature refresh --feature \"$featureId\" --json >/dev/null && WBS_LIST=$(jq -r '.wbs | join(\" \")' \"$RESULT\") && for wbs in $WBS_LIST; do\n  TMP=\".spur/run/$__runId-idea-check-$wbs.tmp\";\n  if $spurBin task check \"$wbs\" --json > \"$TMP\" 2>&1; then P=true; else P=false; fi;\n  jq -c --arg w \"$wbs\" --argjson p \"$P\" 'if (type == \"array\" and length > 0) then {wbs: $w, pass: $p, status: (.[0].status // \"unknown\")} else {wbs: $w, pass: $p, status: \"missing\"} end' \"$TMP\" >> \"$CHECKS\" || exit 1;\n  rm -f \"$TMP\";\ndone && CHECK_ROWS=$(wc -l < \"$CHECKS\" | tr -d ' ') && WBS_COUNT=$(printf '%s\\n' $WBS_LIST | wc -l | tr -d ' ') && test \"$CHECK_ROWS\" = \"$WBS_COUNT\" && NEXT=$(jq -r --arg feature \"$featureId\" --slurpfile c \"$CHECKS\" 'if ($c | any(.[]; .pass == false)) then \"/sp:dev-refineall --feature \\($feature) --auto --depth ready\" else \"/sp:dev-runall --feature \\($feature) --auto\" end' \"$RESULT\") && {\n  echo \"# Idea pipeline handoff report\";\n  echo;\n  echo \"Feature: $featureId\";\n  echo \"Run ID: $__runId\";\n  echo;\n  echo \"## Created tasks\";\n  printf '%s\\n' $WBS_LIST | sed 's/^/  - /';\n  echo;\n  echo \"## Per-task readiness (spur task check)\";\n  echo;\n  echo \"| WBS | Outcome |\";\n  echo \"|-----|---------|\";\n  while IFS= read -r line; do\n    w=$(printf '%s' \"$line\" | jq -r '.wbs');\n    o=$(printf '%s' \"$line\" | jq -r 'if .pass then \"PASS\" else \"FAIL\" end');\n    printf '| %s | %s |\\n' \"$w\" \"$o\";\n  done < \"$CHECKS\";\n  echo;\n  echo \"## Next command\";\n  echo;\n  echo \"$NEXT\";\n} > \"$REPORT\"",
                     "stateEffect": "write",
-                    "evidenceEffect": "write"
+                    "evidenceEffect": "write",
+                    "disposition": "DUAL"
                 },
                 "handoff:onEnter:0": {
                     "kind": "note",
@@ -274,7 +279,8 @@
                     "kind": "shell",
                     "invocation": "DIRTY=$(git status --porcelain -- . ':(exclude)docs/tasks*' ':(exclude)docs/features' 2>/dev/null); if [ -n \"$DIRTY\" ]; then\n  echo \"precheck: WARNING - working tree has uncommitted non-corpus changes; commit or stash before starting a new task:\";\n  echo \"$DIRTY\";\nfi; CORPUS_DIRTY=$(git status --porcelain -- ':(glob)docs/tasks*/**' 2>/dev/null); if [ -n \"$CORPUS_DIRTY\" ]; then\n  echo \"precheck: NOTE - task corpus has uncommitted changes; review before staging with this task:\";\n  echo \"$CORPUS_DIRTY\";\nfi; exit 0",
                     "stateEffect": "read",
-                    "evidenceEffect": "none"
+                    "evidenceEffect": "none",
+                    "disposition": "GLUE"
                 },
                 "precheck:onEnter:2": {
                     "kind": "note",
@@ -285,13 +291,15 @@
                     "kind": "shell",
                     "invocation": "if [ \"$profile\" = auto ]; then\n  FID=$($spurBin task show $wbs --json 2>/dev/null |\n  jq -r '.feature_id // .frontmatter.feature_id // empty' 2>/dev/null);\n  if [ -n \"$FID\" ]; then\n    $spurBin feature sync \"$FID\" --force --json 2>/dev/null ||\n    $spurBin feature update \"$FID\" active 2>/dev/null || true;\n  fi;\nfi; exit 0",
                     "stateEffect": "write",
-                    "evidenceEffect": "none"
+                    "evidenceEffect": "none",
+                    "disposition": "GLUE"
                 },
                 "precheck:onEnter:4": {
                     "kind": "shell",
                     "invocation": "SIZE_FILE=\".spur/run/$wbs-precheck-size.status\" && mkdir -p .spur/run && if [ -f plugins/sp/scripts/task-size-precheck.ts ]; then bun plugins/sp/scripts/task-size-precheck.ts \"$wbs\" --spur-bin \"$spurBin\" --max-reqs \"$maxImplementReqs\" --max-plan-items \"$maxImplementPlanItems\" --executor \"$implementAgent\"; else\n  echo \"task-size-precheck skipped — plugins/sp/scripts/task-size-precheck.ts not present in project.\" >&2 &&\n  echo \"PASS\" > \"$SIZE_FILE\";\nfi && exit 0",
                     "stateEffect": "read",
-                    "evidenceEffect": "write"
+                    "evidenceEffect": "write",
+                    "disposition": "EXT"
                 },
                 "implement:onEnter:0": {
                     "kind": "agent.run",
@@ -303,7 +311,8 @@
                     "kind": "shell",
                     "invocation": "retry_transient() {\n  RETRY_OUTPUT=$(\"$@\" 2>&1); RETRY_RC=$?;\n  printf '%s\\n' \"$RETRY_OUTPUT\";\n  if [ \"$RETRY_RC\" -eq 0 ]; then return 0; fi;\n  if ! printf '%s' \"$RETRY_OUTPUT\" | grep -Eq 'ENOENT|EBUSY|ENOTEMPTY|database is locked'; then return \"$RETRY_RC\"; fi;\n  sleep 2;\n  RETRY_SECOND_OUTPUT=$(\"$@\" 2>&1); RETRY_RC=$?;\n  printf '%s\\n' \"$RETRY_SECOND_OUTPUT\";\n  if [ \"$RETRY_RC\" -ne 0 ] && printf '%s\\n%s' \"$RETRY_OUTPUT\" \"$RETRY_SECOND_OUTPUT\" | grep -Eq 'ENOENT|EBUSY|ENOTEMPTY'; then\n    echo \"node_modules link/dependency broken — run bun install and retry\";\n  fi;\n  return \"$RETRY_RC\";\n}; retry_transient $spurBin task update \"$wbs\" wip --no-lifecycle",
                     "stateEffect": "write",
-                    "evidenceEffect": "none"
+                    "evidenceEffect": "none",
+                    "disposition": "GLUE"
                 },
                 "implement:onEnter:2": {
                     "kind": "shell",
@@ -315,7 +324,8 @@
                     "kind": "shell",
                     "invocation": "mkdir -p .spur/run && STATUS_FILE=\".spur/run/$wbs-test-gate.status\" && LOG_FILE=\".spur/run/$wbs-test-gate.log\" && ATTEMPT_FILE=\".spur/run/$wbs-test-fix-attempt\" && echo 0 > \"$ATTEMPT_FILE\" && : > \"$LOG_FILE\" && gate_attempt=1; while [ \"$gate_attempt\" -le 5 ]; do\n  ATTEMPT_LOG=\"$LOG_FILE.attempt-$gate_attempt\";\n  sh -c \"$qualityGateCmd\" > \"$ATTEMPT_LOG\" 2>&1; gate_rc=$?;\n  gate_locked=0;\n  grep -q 'SQLiteError: database is locked' \"$ATTEMPT_LOG\" && gate_locked=1;\n  cat \"$ATTEMPT_LOG\" >> \"$LOG_FILE\";\n  rm -f \"$ATTEMPT_LOG\";\n  if [ \"$gate_rc\" -eq 0 ] || [ \"$gate_locked\" -ne 1 ] || [ \"$gate_attempt\" -ge 5 ]; then break; fi;\n  printf 'quality gate: database is locked; retrying (%s/5) in 10s\\n' \"$gate_attempt\" | tee -a \"$LOG_FILE\";\n  sleep 10;\n  gate_attempt=$((gate_attempt + 1));\ndone && 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\n  printf 'PASS\\n' > \"$STATUS_FILE\";\nelse\n  printf 'FAIL\\n' > \"$STATUS_FILE\";\nfi && exit 0",
                     "stateEffect": "write",
-                    "evidenceEffect": "write"
+                    "evidenceEffect": "write",
+                    "disposition": "POLICY"
                 },
                 "test-fix:onEnter:0": {
                     "kind": "shell",
@@ -338,7 +348,8 @@
                     "kind": "shell",
                     "invocation": "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\" && probe_rc=0; if [ -n \"$gateProbeCmd\" ]; then\n  sh -c \"$gateProbeCmd\" > \"$LOG_FILE.probe\" 2>&1; probe_rc=$?;\n  cat \"$LOG_FILE.probe\" >> \"$LOG_FILE\";\n  rm -f \"$LOG_FILE.probe\";\nfi; if [ \"$probe_rc\" -ne 0 ]; then\n  gate_rc=$probe_rc;\nelse\n  gate_attempt=1;\n  while [ \"$gate_attempt\" -le 5 ]; do\n    ATTEMPT_LOG=\"$LOG_FILE.attempt-$gate_attempt\";\n    sh -c \"$qualityGateCmd\" > \"$ATTEMPT_LOG\" 2>&1; gate_rc=$?;\n    gate_locked=0;\n    grep -q 'SQLiteError: database is locked' \"$ATTEMPT_LOG\" && gate_locked=1;\n    cat \"$ATTEMPT_LOG\" >> \"$LOG_FILE\";\n    rm -f \"$ATTEMPT_LOG\";\n    if [ \"$gate_rc\" -eq 0 ] || [ \"$gate_locked\" -ne 1 ] || [ \"$gate_attempt\" -ge 5 ]; then break; fi;\n    printf 'quality gate: database is locked; retrying (%s/5) in 10s\\n' \"$gate_attempt\" | tee -a \"$LOG_FILE\";\n    sleep 10;\n    gate_attempt=$((gate_attempt + 1));\n  done;\nfi && cat \"$LOG_FILE\" && 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\n  printf 'PASS\\n' > \"$STATUS_FILE\";\nelse\n  printf 'FAIL\\n' > \"$STATUS_FILE\";\nfi && exit 0",
                     "stateEffect": "write",
-                    "evidenceEffect": "write"
+                    "evidenceEffect": "write",
+                    "disposition": "POLICY"
                 },
                 "review:onEnter:0": {
                     "kind": "agent.run",
@@ -394,19 +405,22 @@
                     "kind": "shell",
                     "invocation": "retry_transient() {\n  RETRY_OUTPUT=$(\"$@\" 2>&1); RETRY_RC=$?;\n  printf '%s\\n' \"$RETRY_OUTPUT\";\n  if [ \"$RETRY_RC\" -eq 0 ]; then return 0; fi;\n  if ! printf '%s' \"$RETRY_OUTPUT\" | grep -Eq 'ENOENT|EBUSY|ENOTEMPTY|database is locked'; then return \"$RETRY_RC\"; fi;\n  sleep 2;\n  RETRY_SECOND_OUTPUT=$(\"$@\" 2>&1); RETRY_RC=$?;\n  printf '%s\\n' \"$RETRY_SECOND_OUTPUT\";\n  if [ \"$RETRY_RC\" -ne 0 ] && printf '%s\\n%s' \"$RETRY_OUTPUT\" \"$RETRY_SECOND_OUTPUT\" | grep -Eq 'ENOENT|EBUSY|ENOTEMPTY'; then\n    echo \"node_modules link/dependency broken — run bun install and retry\";\n  fi;\n  return \"$RETRY_RC\";\n}; retry_transient $spurBin task record \"$wbs\" --solution-from-diff --transition testing",
                     "stateEffect": "write",
-                    "evidenceEffect": "write"
+                    "evidenceEffect": "write",
+                    "disposition": "GLUE"
                 },
                 "record:onEnter:2": {
                     "kind": "shell",
                     "invocation": "FID=$($spurBin task show $wbs --json 2>/dev/null | jq -r \".feature_id // .frontmatter.feature_id // empty\" 2>/dev/null); if [ -n \"$FID\" ]; then\n  if [ -f plugins/sp/scripts/feature-sync-bounded.ts ]; then\n    bun plugins/sp/scripts/feature-sync-bounded.ts \"$FID\" --spur-bin \"$spurBin\" --json;\n  else\n    $spurBin feature sync \"$FID\" --json;\n  fi;\nelse\n  echo \"Orphan task $wbs — no feature_id linked; proposal: consider linking to a parent feature.\" >> \".spur/run/$wbs-report.txt\";\nfi; exit 0",
                     "stateEffect": "write",
-                    "evidenceEffect": "none"
+                    "evidenceEffect": "none",
+                    "disposition": "EXT"
                 },
                 "done:onEnter:0": {
                     "kind": "shell",
                     "invocation": "retry_transient() {\n  RETRY_OUTPUT=$(\"$@\" 2>&1); RETRY_RC=$?;\n  printf '%s\\n' \"$RETRY_OUTPUT\";\n  if [ \"$RETRY_RC\" -eq 0 ]; then return 0; fi;\n  if ! printf '%s' \"$RETRY_OUTPUT\" | grep -Eq 'ENOENT|EBUSY|ENOTEMPTY|database is locked'; then return \"$RETRY_RC\"; fi;\n  sleep 2;\n  RETRY_SECOND_OUTPUT=$(\"$@\" 2>&1); RETRY_RC=$?;\n  printf '%s\\n' \"$RETRY_SECOND_OUTPUT\";\n  if [ \"$RETRY_RC\" -ne 0 ] && printf '%s\\n%s' \"$RETRY_OUTPUT\" \"$RETRY_SECOND_OUTPUT\" | grep -Eq 'ENOENT|EBUSY|ENOTEMPTY'; then\n    echo \"node_modules link/dependency broken — run bun install and retry\";\n  fi;\n  return \"$RETRY_RC\";\n}; retry_transient $spurBin task update \"$wbs\" done --no-lifecycle",
                     "stateEffect": "write",
-                    "evidenceEffect": "none"
+                    "evidenceEffect": "none",
+                    "disposition": "GLUE"
                 },
                 "done:onEnter:1": {
                     "kind": "run.artifact",
@@ -456,19 +470,22 @@
                     "kind": "shell",
                     "invocation": "mkdir -p .spur/memory && if test -s .spur/run/wrapup-learnings.md; then\n  cat .spur/run/wrapup-learnings.md >> .spur/memory/learnings.md &&\n  printf '\\n' >> .spur/memory/learnings.md;\nelse\n  echo \"wrapup: learning capture missing or empty at $PWD/.spur/run/wrapup-learnings.md - append skipped\" >&2;\nfi && exit 0",
                     "stateEffect": "write",
-                    "evidenceEffect": "write"
+                    "evidenceEffect": "write",
+                    "disposition": "GLUE"
                 },
                 "metrics-record:onEnter:0": {
                     "kind": "shell",
                     "invocation": "mkdir -p .spur/memory && printf '%s' \"$tasks\" | jq -r '(if type == \"string\" then (try fromjson catch .) else . end) | if type == \"array\" then .[] else empty end' | while IFS= read -r wbs; do\n  if [ -n \"$wbs\" ]; then\n    task_json=$($spurBin task show \"$wbs\" --json 2>/dev/null || true);\n    if [ -n \"$task_json\" ]; then\n      feat=$(printf '%s' \"$task_json\" | jq -r '.frontmatter.feature_id // .feature_id // empty' 2>/dev/null || true);\n      stat=$(printf '%s' \"$task_json\" | jq -r '.frontmatter.status // .status // \"unknown\"' 2>/dev/null || true);\n      verdict=\"UNKNOWN\";\n      if [ -f \".spur/run/$wbs-verdict.json\" ]; then\n        v=$(jq -r '.verdict // \"UNKNOWN\"' \".spur/run/$wbs-verdict.json\" 2>/dev/null || true);\n        if [ -n \"$v\" ]; then verdict=\"$v\"; fi;\n      fi;\n      ts=$(date -u +\"%Y-%m-%dT%H:%M:%SZ\");\n      printf '{\"wbs\":\"%s\",\"feature_id\":\"%s\",\"status\":\"%s\",\"verdict\":\"%s\",\"timestamp\":\"%s\"}\\n' \"$wbs\" \"$feat\" \"$stat\" \"$verdict\" \"$ts\" >> .spur/memory/wrapup-metrics.jsonl;\n    fi;\n  fi;\ndone && exit 0",
                     "stateEffect": "write",
-                    "evidenceEffect": "write"
+                    "evidenceEffect": "write",
+                    "disposition": "GLUE"
                 },
                 "feature-transition:onEnter:0": {
                     "kind": "shell",
-                    "invocation": "if [ -z \"$feature\" ]; then\n  echo \"feature-transition: vars.feature is empty — refusing no-op feature sync (mis-invocation, not a blocked sync)\" >&2;\n  exit 1;\nfi; if [ -f plugins/sp/scripts/feature-sync-bounded.ts ]; then\n  bun plugins/sp/scripts/feature-sync-bounded.ts \"$feature\" --spur-bin \"$spurBin\" --json;\nelse\n  $spurBin feature sync \"$feature\" --json;\nfi; exit 0",
+                    "invocation": "if [ -z \"$feature\" ]; then\n  echo \"feature-transition: vars.feature is empty — refusing no-op feature sync (mis-invocation, not a blocked sync)\" >&2;\n  exit 1;\nfi; SYNC_OUTPUT=$(if [ -f plugins/sp/scripts/feature-sync-bounded.ts ]; then\n  bun plugins/sp/scripts/feature-sync-bounded.ts \"$feature\" --spur-bin \"$spurBin\" --json;\nelse\n  $spurBin feature sync \"$feature\" --json;\nfi); SYNC_RC=$?; printf '%s\\n' \"$SYNC_OUTPUT\"; APPLIED=$(printf '%s' \"$SYNC_OUTPUT\" | jq -r '.applied // false' 2>/dev/null || echo false); if [ \"$APPLIED\" = \"true\" ] || [ \"$SYNC_RC\" -ne 0 ]; then\n  echo \"feature-transition: sync applied or failed after a possible partial transition for $feature — running corpus-aware gate: $featureGateCmd\";\n  if sh -c \"$featureGateCmd\"; then\n    echo \"feature-transition: corpus-aware gate PASS for feature $feature\";\n  else\n    echo \"feature-transition: corpus-aware gate FAIL for feature $feature — inspect findings before reporting the transition complete\" >&2;\n  fi;\nelse\n  echo \"feature-transition: sync did not apply a transition (rc=$SYNC_RC, applied=$APPLIED) — corpus-aware gate skipped\";\nfi; exit 0",
                     "stateEffect": "write",
-                    "evidenceEffect": "none"
+                    "evidenceEffect": "none",
+                    "disposition": "EXT"
                 },
                 "branch-cleanup:onEnter:0": {
                     "kind": "hitl.confirm",
@@ -511,7 +528,8 @@
                     "kind": "shell",
                     "invocation": "mkdir -p .spur/run && STATUS_FILE=\".spur/run/$__runId-pr-preflight.status\" && set +e && 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",
                     "stateEffect": "read",
-                    "evidenceEffect": "write"
+                    "evidenceEffect": "write",
+                    "disposition": "EXT"
                 },
                 "hygiene:onEnter:0": {
                     "kind": "shell",
@@ -523,7 +541,8 @@
                     "kind": "shell",
                     "invocation": "mkdir -p .spur/run && STATUS_FILE=\".spur/run/$__runId-pr-precheck.status\" && if [ -z \"$preReviewCmd\" ]; then\n  printf 'SKIP\\n' > \"$STATUS_FILE\";\nelse\n  set +e; sh -c \"$preReviewCmd\"; rc=$?; set -e;\n  if [ \"$rc\" -eq 0 ]; then printf 'PASS\\n' > \"$STATUS_FILE\"; else printf 'FAIL\\n' > \"$STATUS_FILE\"; fi;\nfi && exit 0",
                     "stateEffect": "read",
-                    "evidenceEffect": "write"
+                    "evidenceEffect": "write",
+                    "disposition": "POLICY"
                 },
                 "push:onEnter:0": {
                     "kind": "shell",
@@ -541,19 +560,219 @@
                     "kind": "shell",
                     "invocation": "mkdir -p .spur/run && STATUS_FILE=\".spur/run/$__runId-pr-request.status\" && FORCE_FLAG=\"\" && if [ \"$mode\" = \"rerun\" ]; then FORCE_FLAG=\"--force\"; fi && set +e && bun \"$(superskill script path sp pr-reviewing.ts)\" request --focus \"$focus\" $FORCE_FLAG --json --status-file \"$STATUS_FILE\" > \".spur/run/$__runId-pr-request.json\"; rc=$?; set -e && if [ ! -f \"$STATUS_FILE\" ]; then printf 'FAIL\\n' > \"$STATUS_FILE\"; fi && exit 0",
                     "stateEffect": "write",
-                    "evidenceEffect": "write"
+                    "evidenceEffect": "write",
+                    "disposition": "EXT"
                 },
                 "wait:onEnter:0": {
                     "kind": "shell",
                     "invocation": "mkdir -p .spur/run && STATUS_FILE=\".spur/run/$__runId-pr-wait.status\" && set +e && SINCE=\"$(bun -e 'const fs=require(\"node:fs\");const value=JSON.parse(fs.readFileSync(process.argv[1],\"utf8\")).requestedAt;process.stdout.write(value ?? \"\")' \".spur/run/$__runId-pr-request.json\")\" && REQUEST_HEAD=\"$(bun -e 'const fs=require(\"node:fs\");const value=JSON.parse(fs.readFileSync(process.argv[1],\"utf8\")).head;process.stdout.write(value ?? \"\")' \".spur/run/$__runId-pr-request.json\")\" && bun \"$(superskill script path sp pr-reviewing.ts)\" wait --since \"$SINCE\" --head \"$REQUEST_HEAD\" --timeout \"$waitTimeoutSec\" --interval \"$waitIntervalSec\" --json --status-file \"$STATUS_FILE\" > \".spur/run/$__runId-pr-wait.json\"; rc=$?; set -e && if [ ! -f \"$STATUS_FILE\" ]; then printf 'FAIL\\n' > \"$STATUS_FILE\"; fi && exit 0",
                     "stateEffect": "read",
-                    "evidenceEffect": "write"
+                    "evidenceEffect": "write",
+                    "disposition": "EXT"
                 },
                 "collect:onEnter:0": {
                     "kind": "shell",
                     "invocation": "mkdir -p .spur/run && STATUS_FILE=\".spur/run/$__runId-pr-collect.status\" && set +e && SINCE=\"$(bun -e 'const fs=require(\"node:fs\");const value=JSON.parse(fs.readFileSync(process.argv[1],\"utf8\")).requestedAt;process.stdout.write(value ?? \"\")' \".spur/run/$__runId-pr-request.json\")\" && REQUEST_HEAD=\"$(bun -e 'const fs=require(\"node:fs\");const value=JSON.parse(fs.readFileSync(process.argv[1],\"utf8\")).head;process.stdout.write(value ?? \"\")' \".spur/run/$__runId-pr-request.json\")\" && bun \"$(superskill script path sp pr-reviewing.ts)\" collect --since \"$SINCE\" --head \"$REQUEST_HEAD\" --json --status-file \"$STATUS_FILE\" > \".spur/run/$__runId-pr-findings.json\"; collect_rc=$?; bun \"$(superskill script path sp pr-reviewing.ts)\" status --since \"$SINCE\" --head \"$REQUEST_HEAD\" --json > \".spur/run/$__runId-pr-status.json\"; status_rc=$?; set -e && if [ \"$collect_rc\" -ne 0 ] || [ \"$status_rc\" -ne 0 ]; then printf 'FAIL\\n' > \"$STATUS_FILE\"; fi && if [ ! -f \"$STATUS_FILE\" ]; then printf 'FAIL\\n' > \"$STATUS_FILE\"; fi && { cat \".spur/run/$__runId-pr-findings.json\" 2>/dev/null || true; } && exit 0",
                     "stateEffect": "read",
-                    "evidenceEffect": "write"
+                    "evidenceEffect": "write",
+                    "disposition": "EXT"
+                }
+            }
+        },
+        "basic": {
+            "definition": "config/workflows/basic.yaml",
+            "boundary": "generic-execution",
+            "disposition": "keep",
+            "artifacts": ["fix-attempt-counter", "gate-status"],
+            "callers": ["spur workflow run"],
+            "terminalStates": ["done", "failed"],
+            "failurePolicy": "fail-closed",
+            "modelQueries": ["fix"],
+            "actions": {
+                "implement:onEnter:0": {
+                    "kind": "note",
+                    "stateEffect": "read",
+                    "evidenceEffect": "none"
+                },
+                "implement:onEnter:1": {
+                    "kind": "shell",
+                    "invocation": "mkdir -p .spur/run && printf '0\\n' > .spur/run/$__runId-basic-fix-attempt",
+                    "stateEffect": "write",
+                    "evidenceEffect": "write",
+                    "disposition": "GLUE"
+                },
+                "check:onEnter:0": {
+                    "kind": "shell",
+                    "invocation": "mkdir -p .spur/run && STATUS_FILE=\".spur/run/$__runId-basic-gate.status\" && set +e && ( $qualityGateCmd ); gate_rc=$?; set -e && if [ \"$gate_rc\" -eq 0 ]; then\n  printf 'PASS\\n' > \"$STATUS_FILE\";\nelse\n  printf 'FAIL\\n' > \"$STATUS_FILE\";\nfi && exit 0",
+                    "stateEffect": "write",
+                    "evidenceEffect": "write",
+                    "disposition": "POLICY"
+                },
+                "fix:onEnter:0": {
+                    "kind": "shell",
+                    "invocation": "mkdir -p .spur/run && ATTEMPT_FILE=\".spur/run/$__runId-basic-fix-attempt\" && n=$(cat \"$ATTEMPT_FILE\" 2>/dev/null || echo 0) && printf '%s\\n' \"$((n + 1))\" > \"$ATTEMPT_FILE\"",
+                    "stateEffect": "write",
+                    "evidenceEffect": "write",
+                    "disposition": "GLUE"
+                },
+                "fix:onEnter:1": {
+                    "kind": "agent.run",
+                    "invocation": "/sp:dev-fixall \"${vars.qualityGateCmd}\"",
+                    "stateEffect": "read",
+                    "evidenceEffect": "none"
+                }
+            }
+        },
+        "feature-dev": {
+            "definition": "config/workflows/feature-dev.yaml",
+            "boundary": "feature-umbrella",
+            "disposition": "keep",
+            "artifacts": ["feature-checkpoint"],
+            "callers": ["/sp:dev-runall --feature"],
+            "terminalStates": ["done", "failed"],
+            "failurePolicy": "fail-closed",
+            "modelQueries": ["brainstorm", "plan", "execute-tasks-auto", "execute-tasks"],
+            "actions": {
+                "precheck:onEnter:0": {
+                    "kind": "shell",
+                    "invocation": "mkdir -p .spur/run && set +e && test -n \"$featureId\"; id_rc=$?; $spurBin agent doctor $agent; doctor_rc=$?; set -e && if [ \"$id_rc\" -eq 0 ] && [ \"$doctor_rc\" -eq 0 ]; then\n  printf 'PASS\\n' > \".spur/run/$__runId-feature-dev-precheck.status\";\nelse\n  printf 'FAIL\\n' > \".spur/run/$__runId-feature-dev-precheck.status\";\nfi && exit 0",
+                    "stateEffect": "write",
+                    "evidenceEffect": "write",
+                    "disposition": "GLUE"
+                },
+                "precheck:onEnter:1": {
+                    "kind": "note",
+                    "stateEffect": "read",
+                    "evidenceEffect": "none"
+                },
+                "brainstorm:onEnter:0": {
+                    "kind": "agent.run",
+                    "invocation": "/sp:dev-brainstorm --feature ${vars.featureId}",
+                    "stateEffect": "read",
+                    "evidenceEffect": "none"
+                },
+                "plan:onEnter:0": {
+                    "kind": "agent.run",
+                    "invocation": "/sp:dev-plan --feature ${vars.featureId}",
+                    "stateEffect": "read",
+                    "evidenceEffect": "none"
+                },
+                "execute-tasks-auto:onEnter:0": {
+                    "kind": "agent.run",
+                    "invocation": "/sp:dev-runall --feature ${vars.featureId} --auto",
+                    "stateEffect": "read",
+                    "evidenceEffect": "none"
+                },
+                "execute-tasks:onEnter:0": {
+                    "kind": "agent.run",
+                    "invocation": "/sp:dev-runall --feature ${vars.featureId}",
+                    "stateEffect": "read",
+                    "evidenceEffect": "none"
+                },
+                "integration-review:onEnter:0": {
+                    "kind": "command.gate",
+                    "stateEffect": "read",
+                    "evidenceEffect": "none"
+                },
+                "integration-review:onEnter:1": {
+                    "kind": "note",
+                    "stateEffect": "read",
+                    "evidenceEffect": "none"
+                },
+                "done:onEnter:0": {
+                    "kind": "shell",
+                    "invocation": "mkdir -p .spur/memory/sessions && echo \"checkpoint: feature-dev done featureId=$featureId ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)\" > .spur/memory/sessions/$featureId-checkpoint.md",
+                    "stateEffect": "write",
+                    "evidenceEffect": "write",
+                    "disposition": "GLUE"
+                }
+            }
+        },
+        "wayfinder-resolution": {
+            "definition": "config/workflows/wayfinder-resolution.yaml",
+            "boundary": "wayfinder-resolution",
+            "disposition": "keep",
+            "artifacts": ["wayfinder-report", "resolution-status"],
+            "callers": ["spur workflow run"],
+            "terminalStates": ["done", "failed", "cancelled"],
+            "failurePolicy": "fail-closed",
+            "modelQueries": ["investigate", "verify"],
+            "actions": {
+                "precheck:onEnter:0": {
+                    "kind": "shell",
+                    "invocation": "mkdir -p .spur/run/wayfinder && set +e && $spurBin task check $wbs; check_rc=$?; $spurBin task show $wbs --json > .spur/run/wayfinder/$wbs-show.json; show_rc=$?; set -e && if [ \"$check_rc\" -eq 0 ] && [ \"$show_rc\" -eq 0 ]; then\n  printf 'PASS\\n' > .spur/run/wayfinder/$wbs-precheck.status;\nelse\n  printf 'FAIL\\n' > .spur/run/wayfinder/$wbs-precheck.status;\nfi && exit 0",
+                    "stateEffect": "write",
+                    "evidenceEffect": "write",
+                    "disposition": "GLUE"
+                },
+                "precheck:onEnter:1": {
+                    "kind": "note",
+                    "stateEffect": "read",
+                    "evidenceEffect": "none"
+                },
+                "collect:onEnter:0": {
+                    "kind": "shell",
+                    "invocation": "mkdir -p .spur/run/wayfinder && $spurBin task show $wbs --json > .spur/run/wayfinder/$wbs-input.json",
+                    "stateEffect": "read",
+                    "evidenceEffect": "write",
+                    "disposition": "GLUE"
+                },
+                "collect:onEnter:1": {
+                    "kind": "shell",
+                    "invocation": "$spurBin workflow validate .spur/workflows/wayfinder-resolution.yaml > .spur/run/wayfinder/$wbs-workflow-check.txt",
+                    "stateEffect": "read",
+                    "evidenceEffect": "write",
+                    "disposition": "SIMPLE"
+                },
+                "collect:onEnter:2": {
+                    "kind": "shell",
+                    "invocation": "$spurBin task check $wbs > .spur/run/wayfinder/$wbs-precheck.txt",
+                    "stateEffect": "read",
+                    "evidenceEffect": "write",
+                    "disposition": "SIMPLE"
+                },
+                "investigate:onEnter:0": {
+                    "kind": "agent.run",
+                    "invocation": "Resolve task ${vars.wbs} in resolution mode ${vars.resolutionMode} using the prepared local bundle `.spur/run/wayfinder/${vars.wbs}-input.json` and only local shell/file reads plus the `spur` CLI; do not use network search or MCP tools. Do not invoke task-pipeline.yaml, /sp:dev-run, /sp:dev-runall, or code implementation. Read the task file, map its existing Requirements and Acceptance Criteria to the existing Design/Plan/References, then author concise Solution, Testing, and Review sections through `spur task update --section --from-file`. Preserve the research boundary. Finish with a short summary and stop. Evidence policy: ${vars.evidencePolicy}.\nEvidence-anchor and content contract (mandatory — 0300 R1/R2): when the task's evidence lives in a shared evidence file (e.g. `.spur/run/wayfinder-O/implementation-evidence.md`), the `## <wbs>` section you author MUST (a) be substantive — more than 5 lines AND more than 60 words, covering the task's own requirements, not a generic 2–3 sentence placeholder; and (b) be anchored truthfully — after writing the section, resolve its real start line with `grep -n \"^## <wbs> \" <evidence-file>` and use that exact line number in every Solution/Testing `file:line` citation. NEVER copy a line number from another ticket's example (e.g. `:5` from an earlier WBS); each WBS anchors to its own section. Before finishing, re-read each cited line and confirm it names the requirement's subject (0299 R1 line-anchor rule).",
+                    "stateEffect": "read",
+                    "evidenceEffect": "none"
+                },
+                "verify:onEnter:0": {
+                    "kind": "shell",
+                    "invocation": "rm -f .spur/run/wayfinder/$wbs-resolution-verdict.txt",
+                    "stateEffect": "read",
+                    "evidenceEffect": "write",
+                    "disposition": "GLUE"
+                },
+                "verify:onEnter:1": {
+                    "kind": "agent.run",
+                    "invocation": "Verify resolved task ${vars.wbs} using only local reads and `spur` CLI. Check its requirements, acceptance scenarios, Solution, Testing, and Review. Confirm workflow orchestration uses `spur workflow` and execution uses `spur` CLI by default. Run `spur task check ${vars.wbs}` and update Testing/Review via the CLI only if needed. Do not implement plugin code. Write the final verdict word (exactly PASS, PARTIAL, or FAIL, nothing else) to `.spur/run/wayfinder/${vars.wbs}-resolution-verdict.txt`, then finish with the same verdict and stop.",
+                    "stateEffect": "read",
+                    "evidenceEffect": "none"
+                },
+                "approve:onEnter:0": {
+                    "kind": "hitl.confirm",
+                    "stateEffect": "read",
+                    "evidenceEffect": "none"
+                },
+                "record:onEnter:0": {
+                    "kind": "shell",
+                    "invocation": "$spurBin task check $wbs ; exit 0",
+                    "stateEffect": "read",
+                    "evidenceEffect": "none",
+                    "disposition": "GLUE"
+                },
+                "record:onEnter:1": {
+                    "kind": "shell",
+                    "invocation": "$spurBin task update $wbs done ; exit 0",
+                    "stateEffect": "write",
+                    "evidenceEffect": "none",
+                    "disposition": "GLUE"
+                },
+                "done:onEnter:0": {
+                    "kind": "note",
+                    "stateEffect": "read",
+                    "evidenceEffect": "none"
                 }
             }
         }

package/config/workflows/wrapup-pipeline.yaml

@@ -51,6 +51,15 @@ vars:
   spurBin: "spur"
   agent: "omp"
   stepTimeoutMs: "1800000"
+  # Corpus-aware quality gate for the feature-transition hop (R1, task 0625).
+  # The per-task gate (`spur-check`) deliberately excludes corpus-check — the only
+  # sweep that observes feature-level findings — so a transition that arms one
+  # would go green. A feature transition happens once per feature, so the ~41 s
+  # corpus sweep is paid once here. Soft by design: the gate reports PASS/FAIL
+  # and lets the operator decide; it never hard-fails the wrap-up shell.
+  # TRUSTED CONFIG ONLY — this string is executed via `sh -c` (same surface as
+  # task-pipeline's qualityGateCmd). Never interpolate untrusted input into it.
+  featureGateCmd: "bun run spur-check-new"
   __hitlAnswer: ""
 
 states:
@@ -152,6 +161,14 @@ states:
       # description promises against). `feature-sync-bounded.ts` is a Spur-monorepo
       # path (`spur init` does not scaffold `plugins/sp/`), so seeded projects fall
       # back to the plain `spur feature sync` verb.
+      # R1 (0625): a feature transition that changed state may have armed a
+      # feature-level finding the per-task fast gate (spur-check) never sees.
+      # Run the corpus-aware gate after an applied sync OR a non-zero exit that
+      # may follow a partial multi-hop transition, then report PASS/FAIL. Soft
+      # by design: the operator decides, and wrap-up never hard-fails here.
+      # NOTE: do not add
+      # `#` comments INSIDE the folded shell string — YAML `>-` folds them onto
+      # the following statement line and comments it out.
       - kind: shell
         options:
           command: >-
@@ -159,10 +176,23 @@ states:
               echo "feature-transition: vars.feature is empty — refusing no-op feature sync (mis-invocation, not a blocked sync)" >&2;
               exit 1;
             fi;
-            if [ -f plugins/sp/scripts/feature-sync-bounded.ts ]; then
+            SYNC_OUTPUT=$(if [ -f plugins/sp/scripts/feature-sync-bounded.ts ]; then
               bun plugins/sp/scripts/feature-sync-bounded.ts "$feature" --spur-bin "$spurBin" --json;
             else
               $spurBin feature sync "$feature" --json;
+            fi);
+            SYNC_RC=$?;
+            printf '%s\n' "$SYNC_OUTPUT";
+            APPLIED=$(printf '%s' "$SYNC_OUTPUT" | jq -r '.applied // false' 2>/dev/null || echo false);
+            if [ "$APPLIED" = "true" ] || [ "$SYNC_RC" -ne 0 ]; then
+              echo "feature-transition: sync applied or failed after a possible partial transition for $feature — running corpus-aware gate: $featureGateCmd";
+              if sh -c "$featureGateCmd"; then
+                echo "feature-transition: corpus-aware gate PASS for feature $feature";
+              else
+                echo "feature-transition: corpus-aware gate FAIL for feature $feature — inspect findings before reporting the transition complete" >&2;
+              fi;
+            else
+              echo "feature-transition: sync did not apply a transition (rc=$SYNC_RC, applied=$APPLIED) — corpus-aware gate skipped";
             fi;
             exit 0
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.3.55",
+    "version": "0.3.58",
     "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.39",
-        "@gobing-ai/ts-ai-runner": "^0.4.39",
-        "@gobing-ai/ts-dual-workflow-engine": "^0.4.39",
-        "@gobing-ai/ts-infra": "^0.4.39",
-        "@gobing-ai/ts-llm-jsonl-importer": "^0.4.39",
-        "@gobing-ai/ts-rule-engine": "^0.4.39",
-        "@gobing-ai/ts-runtime": "^0.4.39",
-        "@gobing-ai/ts-utils": "^0.4.39",
+        "@gobing-ai/ts-db": "^0.4.41",
+        "@gobing-ai/ts-ai-runner": "^0.4.41",
+        "@gobing-ai/ts-dual-workflow-engine": "^0.4.41",
+        "@gobing-ai/ts-infra": "^0.4.41",
+        "@gobing-ai/ts-llm-jsonl-importer": "^0.4.41",
+        "@gobing-ai/ts-rule-engine": "^0.4.41",
+        "@gobing-ai/ts-runtime": "^0.4.41",
+        "@gobing-ai/ts-utils": "^0.4.41",
         "@types/bun": "1.3.14",
         "@types/figlet": "^1.7.0",
         "@types/node-notifier": "8.0.5",

package/plugins/README.md

@@ -345,7 +345,7 @@ All planning entities (tasks and features) share a common lifecycle, managed by
 | **check**   | `spur task check`                   | `spur feature check`                | 4-layer readiness matrix (schema, sections, traceability, AC)                                        |
 | **update**  | `spur task update <wbs> [status]`   | `spur feature update <id> [status]` | Lifecycle transition or scalar field set                                                             |
 | **record**  | `spur task record <wbs>`            | —                                   | Write Testing/Review from a verify verdict; optional Solution backfill (never transitions to `done`) |
-| **refresh** | `spur task refresh`                 | `spur feature refresh`              | Index + feature-tree roll-up regeneration                                                            |
+| **refresh** | `spur task refresh`                 | `spur feature refresh --feature <id> \| --all` | Index + feature-tree roll-up regeneration                                                   |
 
 The **workflow** and **rule** engines have their own lifecycles (author → validate → run → trace / refine), documented in their respective `sp:spur-cli` references.
 

package/plugins/sp/README.md

@@ -601,7 +601,7 @@ All planning entities (tasks and features) share a common lifecycle, managed by
 | **check**   | `spur task check`                   | `spur feature check`                | 4-layer readiness matrix (schema, sections, traceability, AC)                                        |
 | **update**  | `spur task update <wbs> [status]`   | `spur feature update <id> [status]` | Lifecycle transition or scalar field set                                                             |
 | **record**  | `spur task record <wbs>`            | —                                   | Write Testing/Review from a verify verdict; optional Solution backfill (never transitions to `done`) |
-| **refresh** | `spur task refresh`                 | `spur feature refresh`              | Index + feature-tree roll-up regeneration                                                            |
+| **refresh** | `spur task refresh`                 | `spur feature refresh --feature <id> \| --all` | Index + feature-tree roll-up regeneration                                                   |
 
 The **workflow** and **rule** engines have their own lifecycles (author → validate → run → trace /
 refine), documented in their respective `sp:spur-cli` references.

package/plugins/sp/agents/expert-spur.md

@@ -46,6 +46,9 @@ guide and conventions before acting.
 - **Section-editing campaigns** — update the same section across multiple tasks.
 - **Rule-catalog work** — author, fine-tune, validate, or harden constraint rules across the catalog.
 - **Workflow work** — author, validate, dry-run, or refactor one or more workflows.
+  When authoring or refactoring, read the composition-measures section in
+  `sp:spur-cli` `references/workflows.md` and apply the advisory's fix-path map — findings are
+  advisory only; never block a run or edit an executing pipeline over them.
 - **Corpus health checks** — run `check`/`validate` across a batch and report findings.
 
 For a single operation, use the `spur` CLI directly. For the planning/execution lifecycle, use
@@ -68,7 +71,7 @@ Invoke `sp:spur-cli` for verb guidance and per-noun conventions:
 - [ ] Run the noun's `check`/`validate` verb before and after editing (e.g. `spur task check <wbs> --json`).
 - [ ] Run the corpus-wide sweep after batch edits: `spur task check --corpus --json` (fails on structural errors outside `config/corpus-baseline.json`).
 - [ ] Use `spur task update --section --from-file` for all task section edits.
-- [ ] Run the noun's `refresh` after batch operations where one exists (`spur task refresh`, `spur feature refresh`).
+- [ ] Run the noun's scoped `refresh` after batch operations where one exists (`spur task refresh`, `spur feature refresh --feature <id>` or `--all`).
 
 ### Never
 

package/plugins/sp/commands/dev-feature-change.md

@@ -62,7 +62,7 @@ Do **not** fire independent dry-runs that all claim the same next id. Walk rows
 3. After predicting `new_id`, add it to the occupancy set so the next sibling under the same parent gets the next free digit.
 4. Record `mapping` and `tasksUpdated[]` from each dry-run (with multi-folder scan, tasksUpdated should list every linked WBS).
 
-Plan `spur feature refresh` + `spur feature check --json` after apply.
+Plan `spur feature refresh --all` + `spur feature check --json` after apply.
 
 **Root docs/\*.md references (high-confidence only)**
 
@@ -95,7 +95,7 @@ spur feature move <old_id> --parent <new_parent> --json
 After all moves (or per wave):
 
 ```bash
-spur feature refresh --json
+spur feature refresh --all --json
 spur feature check --json
 ```