@smartmemory/compose 0.2.6-beta → 0.2.8-beta

package/bin/compose.js

@@ -1654,6 +1654,13 @@ Exit codes:
     else if (a === '--code') code = args[++i]
     else if (a.startsWith('--block-on=')) blockOn = a.slice('--block-on='.length)
     else if (a === '--block-on') blockOn = args[++i]
+    else if (a === '--workspace' || a.startsWith('--workspace=')) {
+      // --workspace is a valid global flag consumed by resolveCwdWithWorkspace(args)
+      // below; skip it here so the unknown-flag guard doesn't reject it. Don't
+      // consume the next token: a bare `--workspace <id>` leaves <id> as a
+      // positional (harmlessly ignored by this loop, parsed by resolveCwdWith-
+      // Workspace), so `--workspace --help` still resolves --help correctly.
+    }
     else if (a.startsWith('--')) {
       console.error(`Unknown flag: ${a}`)
       process.exit(2)
@@ -1962,14 +1969,22 @@ if (cmd === 'build') {
   // pipeline (pipelines/gsd.stratum.yaml). Hard-requires existing
   // docs/features/<code>/blueprint.md with a parseable Boundary Map.
   const gsdCode = args.find(a => !a.startsWith('-'))
+  const gsdResume = args.includes('--resume')
+  const gsdResetBudget = args.includes('--reset-budget')
   if (!gsdCode) {
-    console.error('Usage: compose gsd <feature-code>')
+    console.error('Usage: compose gsd <feature-code> [--resume] [--reset-budget]')
     console.error('')
     console.error('Runs the per-task fresh-context dispatch pipeline (COMP-GSD-2).')
     console.error('Hard-requires docs/features/<code>/blueprint.md with a valid Boundary Map.')
+    console.error('Detects stuck tasks (COMP-GSD-5) and halts with a structured diagnostic.')
+    console.error('Enforces budget ceilings (COMP-GSD-4) from .compose/compose.json gsd.budget.*')
     console.error('')
     console.error('Options:')
-    console.error('  --cwd <path>   Working directory (defaults to current)')
+    console.error('  --resume        Resume a halted run: re-dispatch the unfinished tasks')
+    console.error('                  from .compose/gsd/<code>/pause.json (skips completed tasks).')
+    console.error('  --reset-budget  Clear the feature\'s cumulative budget ledger before running')
+    console.error('                  (use after raising or removing a spent gsd.budget.cumulative cap).')
+    console.error('  --cwd <path>    Working directory (defaults to current)')
     process.exit(1)
   }
   const { root: gsdCwd } = resolveCwdWithWorkspace(args)
@@ -1977,7 +1992,34 @@ if (cmd === 'build') {
   const gsdAgentCwd = cwdIdx !== -1 ? resolve(args[cwdIdx + 1]) : gsdCwd
   const { runGsd } = await import('../lib/gsd.js')
   try {
-    const result = await runGsd(gsdCode, { cwd: gsdAgentCwd })
+    if (gsdResetBudget) {
+      // COMP-GSD-4: clear the cumulative ledger so a spent ceiling no longer
+      // refuses the run. Runs before dispatch; per-run windows reset anyway.
+      const { resetGsdUsage } = await import('../lib/budget-ledger.js')
+      resetGsdUsage(resolve(gsdAgentCwd, '.compose'), gsdCode)
+      console.log(`gsd: cleared cumulative budget ledger for ${gsdCode}.`)
+    }
+    const result = await runGsd(gsdCode, { cwd: gsdAgentCwd, resume: gsdResume })
+    if (result.status === 'stuck') {
+      // COMP-GSD-5: a stuck halt is a clean, recoverable stop — not a crash.
+      console.error(`gsd stuck: task ${result.stuckTaskId} tripped the ${result.signal} detector.`)
+      console.error(`Diagnostic: .compose/gsd/${gsdCode}/stuck.md`)
+      console.error(`Resume with: compose gsd ${gsdCode} --resume`)
+      process.exit(2)
+    }
+    if (result.status === 'budget') {
+      // COMP-GSD-4: a budget halt is a clean, recoverable stop — not a crash.
+      if (result.axis === 'cumulative') {
+        console.error(`gsd budget: cumulative ceiling for ${gsdCode} is already spent.`)
+        console.error(`Diagnostic: .compose/gsd/${gsdCode}/budget.md`)
+        console.error(`Raise gsd.budget.cumulative.* or clear it: compose gsd ${gsdCode} --reset-budget`)
+      } else {
+        console.error(`gsd budget: the ${result.axis} ceiling tripped mid-run.`)
+        console.error(`Diagnostic: .compose/gsd/${gsdCode}/budget.md`)
+        console.error(`Raise gsd.budget.* and resume: compose gsd ${gsdCode} --resume`)
+      }
+      process.exit(2)
+    }
     console.log(`gsd complete: ${result.blackboardEntries} task results captured.`)
   } catch (err) {
     console.error(`gsd failed: ${err.message}`)

package/bin/git-hooks/pre-push.template

@@ -1,7 +1,9 @@
 #!/usr/bin/env bash
-# Compose pre-push hook — runs `compose validate` and blocks the push on
-# any error-severity drift finding. Installed by `compose hooks install --pre-push`;
-# placeholders below are substituted at install time.
+# Compose pre-push hook — blocks the push on a red `npm test` suite (HARD gate) and
+# runs `compose validate` as an ADVISORY drift check (prints findings, does not
+# block — re-enable strict drift-blocking once the repo's drift backlog is
+# reconciled). Installed by `compose hooks install --pre-push`; placeholders
+# below are substituted at install time.
 #
 # External-reference (xref) resolution is OFF here by default: github xref:
 # citations / kind:"external" links emit XREF_RESOLUTION_SKIPPED (warning,
@@ -18,18 +20,44 @@ COMPOSE_WORKSPACE_ID="__COMPOSE_WORKSPACE_ID__"
 LOG="${COMPOSE_HOOK_LOG:-.compose/data/pre-push.log}"
 mkdir -p "$(dirname "$LOG")" 2>/dev/null || true
 
+# Drift check (ADVISORY — COMP-RESUME follow-up): print findings for visibility,
+# never block. The repo carries pre-existing error-severity drift (much from the
+# COMP-MCP-ENFORCE lifecycle-as-truth projection); hard-blocking on it would make
+# the whole hook unusable, so the TEST gate below is the hard blocker. Re-enable
+# strict drift-blocking once the backlog is reconciled (tracked separately).
 OUTPUT=$("$COMPOSE_NODE" "$COMPOSE_BIN" validate --scope=project --block-on=error --workspace="$COMPOSE_WORKSPACE_ID" 2>&1)
-EXIT_CODE=$?
-
-if [ "$EXIT_CODE" -ne 0 ]; then
-  echo "$OUTPUT" | tee -a "$LOG" >&2
+VALIDATE_EXIT=$?
+echo "$OUTPUT"
+if [ "$VALIDATE_EXIT" -ne 0 ]; then
   echo "" >&2
-  echo "compose validate found error-severity drift. Push aborted." >&2
-  echo "Run \`compose validate\` to see findings, then fix and retry." >&2
-  echo "Bypass at your own risk: git push --no-verify" >&2
-  exit "$EXIT_CODE"
+  echo "pre-push: compose validate reported drift (ADVISORY — not blocking). Review with \`compose validate\`." >&2
+fi
+
+# ── Test gate (COMP-RESUME follow-up) ───────────────────────────────────────
+# Block the push if the suite is red. This is the gate whose absence let a broken
+# integration test (and a stale-schema consumer bug) reach main — nothing ran the
+# suite before push. Heavy (full `npm test`) but authoritative. Auto-skips in a
+# repo with no npm `test` script. Emergency bypass (sparingly): git push --no-verify
+if [ -f package.json ]; then
+  # Probe scripts.test: exit 0 = present, 1 = definitively absent, anything else
+  # = could not read package.json. Skip ONLY on a definitive "absent" (1); on
+  # ambiguity run the suite anyway so a broken/unreadable package.json fails
+  # CLOSED (blocks), never open (silently skips the gate).
+  "$COMPOSE_NODE" -e "let s={};try{s=require(process.cwd()+'/package.json').scripts||{}}catch(e){process.exit(3)};process.exit(s.test?0:1)" 2>/dev/null
+  PROBE=$?
+  if [ "$PROBE" -ne 1 ]; then
+    echo "pre-push: running full test suite (npm test)…" >&2
+    PATH="$(dirname "$COMPOSE_NODE"):$PATH" npm test >> "$LOG" 2>&1
+    TEST_EXIT=$?
+    if [ "$TEST_EXIT" -ne 0 ]; then
+      tail -n 40 "$LOG" >&2
+      echo "" >&2
+      echo "npm test failed — push aborted (full log: $LOG)." >&2
+      echo "Bypass at your own risk: git push --no-verify" >&2
+      exit "$TEST_EXIT"
+    fi
+    echo "pre-push: test suite green." >&2
+  fi
 fi
 
-# Below-threshold findings (warnings/info) are still printed for visibility.
-echo "$OUTPUT"
 exit 0

package/contracts/gsd-stuck.json

@@ -0,0 +1,141 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gsd-stuck.json",
+  "_source": "COMP-GSD-5",
+  "_also": "COMP-GSD-4",
+  "_roadmap": "COMP-GSD-5",
+  "title": "GsdStuckContracts",
+  "description": "Artifacts written when a `compose gsd` run halts. A STUCK halt (COMP-GSD-5) writes stuck.json/stuck.md; a BUDGET halt (COMP-GSD-4) writes budget.json/budget.md. Both persist `pause.json` (machine-readable resume state); `compose gsd <feature> --resume` reads it, validates ownership/mode, and re-dispatches decomposedTasks minus completedTaskIds (completed results already live in the blackboard). The pause `kind` field (optional; absent ⇒ 'stuck' for back-compat) discriminates: a 'stuck' pause carries the stuck-specific fields, a 'budget' pause carries the `budget` block. GSD-6 reuses the `pause` shape for automatic crash-recovery.",
+  "definitions": {
+    "stuck": {
+      "type": "object",
+      "title": "GsdStuckDiagnostic",
+      "description": "Structured diagnostic emitted on the first stuck verdict for a task.",
+      "required": ["feature", "taskId", "signal", "detail", "attemptCounts", "ts"],
+      "additionalProperties": false,
+      "properties": {
+        "feature": {
+          "type": "string",
+          "description": "Feature code the gsd run is building (e.g. COMP-GSD-5)."
+        },
+        "taskId": {
+          "type": "string",
+          "description": "The decomposed task id that tripped the detector."
+        },
+        "signal": {
+          "type": "string",
+          "enum": ["same_file", "error_recurrence", "no_progress", "wall_clock"],
+          "description": "Which stuck pattern fired. same_file: one file edited >= sameFileEdits times. error_recurrence: a normalized error hash recurred >= errorRepeats. no_progress: >= noProgressCalls consecutive non-file-changing tool calls. wall_clock: task ran >= wallClockMs without finishing."
+        },
+        "detail": {
+          "type": "string",
+          "description": "Human-readable explanation of the offending file / error / stall."
+        },
+        "attemptCounts": {
+          "type": "object",
+          "description": "Snapshot of the per-task counters at the moment of the verdict.",
+          "properties": {
+            "sameFileEdits": { "type": "integer", "minimum": 0, "description": "Max edit count across files for this task." },
+            "errorRepeats": { "type": "integer", "minimum": 0, "description": "Max repeat count across normalized error hashes." },
+            "noProgressCalls": { "type": "integer", "minimum": 0, "description": "Current consecutive non-file-changing tool-call count." }
+          },
+          "additionalProperties": true
+        },
+        "partialDiff": {
+          "type": "string",
+          "description": "Optional unified diff of the stuck task's worktree at halt time, for triage."
+        },
+        "ts": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO-8601 timestamp of the verdict."
+        }
+      }
+    },
+    "pause": {
+      "type": "object",
+      "title": "GsdPauseState",
+      "description": "Resume state persisted on a stuck OR budget halt. Drives blackboard-driven re-dispatch on --resume — NOT mid-task re-entry. Base required fields are kind-agnostic; the `kind` field (optional; absent ⇒ stuck) selects which extra fields are required via the if/then/else at the end.",
+      "required": ["flowId", "stepId", "decomposedTasks", "completedTaskIds", "pid", "mode", "ts"],
+      "additionalProperties": false,
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": ["stuck", "budget"],
+          "description": "Halt kind. Optional for back-compat: an absent kind is interpreted as 'stuck'. Determines which extra fields are required (see if/then/else)."
+        },
+        "budget": {
+          "type": "object",
+          "description": "Present on a budget halt (kind='budget'). The enforced axis that tripped + the stratum budget_state snapshot.",
+          "required": ["axis", "caps", "consumed"],
+          "additionalProperties": true,
+          "properties": {
+            "axis": {
+              "type": ["string", "null"],
+              "enum": ["ms", "max_agent_dispatches", "max_tokens", "usd", null],
+              "description": "Which enforced stratum axis reached its cap (null if indeterminate)."
+            },
+            "caps": { "type": "object", "description": "The flow budget caps {ms?,max_agent_dispatches?,max_tokens?,usd?}." },
+            "consumed": { "type": "object", "description": "Consumed totals {tokens,dispatches,wall_s,dollars}." }
+          }
+        },
+        "flowId": {
+          "type": "string",
+          "description": "Stratum flow id of the halted run (informational; resume opens a fresh flow)."
+        },
+        "stepId": {
+          "type": "string",
+          "description": "The parallel_dispatch step id that was cancelled (e.g. execute)."
+        },
+        "stuckTaskId": {
+          "type": "string",
+          "description": "The task id that tripped the detector."
+        },
+        "signal": {
+          "type": "string",
+          "enum": ["same_file", "error_recurrence", "no_progress", "wall_clock"],
+          "description": "Which stuck pattern fired (mirrors stuck.signal)."
+        },
+        "detail": {
+          "type": "string",
+          "description": "Human-readable explanation (mirrors stuck.detail)."
+        },
+        "decomposedTasks": {
+          "type": "array",
+          "minItems": 1,
+          "description": "The full decomposed task list, persisted so --resume does NOT re-decompose (stable task ids).",
+          "items": { "type": "object" }
+        },
+        "completedTaskIds": {
+          "type": "array",
+          "description": "Task ids whose VALIDATED result is already in the blackboard. --resume skips these.",
+          "items": { "type": "string" }
+        },
+        "pid": {
+          "type": "integer",
+          "description": "OS pid of the process that wrote the pause file. --resume refuses if this pid is still alive (another owner)."
+        },
+        "mode": {
+          "type": "string",
+          "const": "gsd",
+          "description": "Run mode. --resume refuses if this is not 'gsd' (mirrors `compose fix --resume` mode guard)."
+        },
+        "ts": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO-8601 timestamp the pause file was written."
+        }
+      },
+      "if": {
+        "properties": { "kind": { "const": "budget" } },
+        "required": ["kind"]
+      },
+      "then": {
+        "required": ["budget"]
+      },
+      "else": {
+        "required": ["stuckTaskId", "signal", "detail"]
+      }
+    }
+  }
+}