@smartmemory/compose 0.2.7-beta → 0.2.9-beta

package/bin/compose.js

@@ -1968,23 +1968,132 @@ if (cmd === 'build') {
   // compose gsd <feature-code> — runs the per-task fresh-context dispatch
   // pipeline (pipelines/gsd.stratum.yaml). Hard-requires existing
   // docs/features/<code>/blueprint.md with a parseable Boundary Map.
+
+  // COMP-GSD-6: `compose gsd query <feature>` — instant read-only JSON snapshot
+  // (no LLM/server/Stratum). For status pollers + CI dashboards.
+  if (args[0] === 'query') {
+    const qCode = args.find((a, i) => i > 0 && !a.startsWith('-'))
+    if (!qCode) {
+      console.error('Usage: compose gsd query <feature-code> [--cwd <path>]')
+      process.exit(1)
+    }
+    const { root: qRoot } = resolveCwdWithWorkspace(args.slice(1))
+    const qCwdIdx = args.indexOf('--cwd')
+    const qCwd = qCwdIdx !== -1 ? resolve(args[qCwdIdx + 1]) : qRoot
+    const { buildGsdQuery } = await import('../lib/gsd-state.js')
+    const snapshot = buildGsdQuery(qCwd, qCode)
+    console.log(JSON.stringify(snapshot, null, 2))
+    process.exit(snapshot.status === 'absent' ? 3 : 0)
+  }
+
+  // COMP-GSD-7: `compose gsd report <feature>` — (re)generate the milestone HTML
+  // report from persisted run artifacts (auto-generated on completion; this is
+  // the retroactive/archival path). Writes docs/gsd-reports/<feature>.html.
+  if (args[0] === 'report') {
+    const rCwdIdx = args.indexOf('--cwd')
+    const rCwdValIdx = rCwdIdx !== -1 ? rCwdIdx + 1 : -1
+    const rCode = args.find((a, i) => i > 0 && i !== rCwdValIdx && !a.startsWith('-'))
+    if (!rCode) {
+      console.error('Usage: compose gsd report <feature-code> [--cwd <path>]')
+      process.exit(1)
+    }
+    const { root: rRoot } = resolveCwdWithWorkspace(args.slice(1))
+    const rCwd = rCwdIdx !== -1 ? resolve(args[rCwdIdx + 1]) : rRoot
+    const { generateGsdMilestoneReport } = await import('../lib/gsd-milestone-report.js')
+    const r = generateGsdMilestoneReport(rCode, rCwd)
+    if (!r.ok) {
+      console.error(`gsd report: ${r.error}`)
+      process.exit(1)
+    }
+    console.log(`Milestone report written: ${r.path}`)
+    process.exit(0)
+  }
+
   const gsdCode = args.find(a => !a.startsWith('-'))
+  const gsdResume = args.includes('--resume')
+  const gsdResetBudget = args.includes('--reset-budget')
+  const gsdHeadless = args.includes('--headless')
   if (!gsdCode) {
-    console.error('Usage: compose gsd <feature-code>')
+    console.error('Usage: compose gsd <feature-code> [--resume] [--reset-budget] [--headless]')
+    console.error('       compose gsd query <feature-code>   (instant JSON status snapshot)')
+    console.error('       compose gsd report <feature-code>  (generate milestone HTML report)')
     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('  --headless      Unattended supervisor (COMP-GSD-6): auto-resume on crash/stuck')
+    console.error('                  with backoff + crash recovery. Policy: gsd.headless.* in compose.json.')
+    console.error('  --cwd <path>    Working directory (defaults to current)')
     process.exit(1)
   }
   const { root: gsdCwd } = resolveCwdWithWorkspace(args)
   const cwdIdx = args.indexOf('--cwd')
   const gsdAgentCwd = cwdIdx !== -1 ? resolve(args[cwdIdx + 1]) : gsdCwd
+
+  // COMP-GSD-6: --headless hands off to the supervisor, which spawns plain
+  // `compose gsd` children and auto-resumes per policy. Exit 0 on completion,
+  // non-zero on a terminal stop (failed/fatal/budget/stuck-exhausted/aborted).
+  if (gsdHeadless) {
+    const { runGsdHeadless } = await import('../lib/gsd-supervisor.js')
+    try {
+      const r = await runGsdHeadless(gsdCode, { cwd: gsdAgentCwd, resume: gsdResume })
+      if (r.ok) {
+        console.log(`gsd headless: complete after ${r.attempts} attempt(s).`)
+        process.exit(0)
+      }
+      console.error(`gsd headless: stopped with status "${r.status}" after ${r.attempts} attempt(s).`)
+      console.error(`Query: compose gsd query ${gsdCode}`)
+      process.exit(r.status === 'failed' || r.status === 'fatal' ? 1 : 2)
+    } catch (err) {
+      console.error(`gsd headless failed: ${err.message}`)
+      process.exit(1)
+    }
+  }
+
   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)
+    }
+    if (result.status !== 'complete') {
+      // COMP-GSD-6: any non-complete terminal (e.g. a stratum 'killed') is a
+      // failure, not success — don't print "complete" or exit 0.
+      console.error(`gsd ${result.status}: run ended without completing.`)
+      console.error(`Inspect: compose gsd query ${gsdCode}`)
+      process.exit(1)
+    }
     console.log(`gsd complete: ${result.blackboardEntries} task results captured.`)
   } catch (err) {
     console.error(`gsd failed: ${err.message}`)

package/contracts/gsd-state.json

@@ -0,0 +1,140 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gsd-state.json",
+  "_source": "COMP-GSD-6",
+  "_also": "COMP-GSD-4",
+  "_roadmap": "COMP-GSD-6",
+  "title": "GsdStateContracts",
+  "description": "COMP-GSD-6 run-state artifacts. `state` is the continuously-flushed checkpoint at .compose/gsd/<feature>/state.json — written pre-plan (phase:planning, flowId:null), updated with flowId after stratum.plan, heartbeat-bumped per task event, marked resumeReady once decomposedTasks is populated, and terminally flushed (complete|stuck|budget|failed). A hard crash leaves status:running + a dead pid, which readers derive as 'crashed'. `query` is the read-only envelope emitted by `compose gsd query` — it adds the reader-only derived statuses 'crashed' and 'absent' to the runner taxonomy, plus the advisory heartbeatStale flag. decomposedTasks stores FULL enriched task objects (id/depends_on/description), not ids, so crash-recovery can synthesize a resume graph (it reuses the gsd-stuck.json#/definitions/pause decomposedTasks shape).",
+  "definitions": {
+    "state": {
+      "type": "object",
+      "title": "GsdRunState",
+      "description": "The continuously-flushed run checkpoint. Status is what the RUNNER writes; readers derive 'crashed'/'absent' from this via deriveRunStatus (lib/gsd-state.js).",
+      "required": ["feature", "pid", "mode", "phase", "status", "heartbeatAt"],
+      "additionalProperties": true,
+      "properties": {
+        "feature": {
+          "type": "string",
+          "description": "Feature code the gsd run is building (e.g. COMP-GSD-6)."
+        },
+        "flowId": {
+          "type": ["string", "null"],
+          "description": "Stratum flow id. null in the pre-plan 'planning' checkpoint; set after stratum.plan returns."
+        },
+        "pid": {
+          "type": "integer",
+          "description": "OS pid of the running process. The authoritative crash signal: status:running + a dead pid (process.kill(pid,0) ESRCH) ⇒ crashed."
+        },
+        "mode": {
+          "type": "string",
+          "const": "gsd",
+          "description": "Run mode. Always 'gsd'."
+        },
+        "phase": {
+          "type": "string",
+          "enum": ["planning", "decompose", "execute", "ship", "done"],
+          "description": "Coarse lifecycle phase. 'planning' is the pre-plan checkpoint (before stratum.plan); the failed-vs-fatal boundary is whether this checkpoint exists."
+        },
+        "status": {
+          "type": "string",
+          "enum": ["running", "complete", "stuck", "budget", "failed"],
+          "description": "Runner-written status. 'failed' = an orderly exception AFTER the planning checkpoint (the dispatch-try catch). 'running' persisted with a dead pid is derived as 'crashed' by readers (never self-written)."
+        },
+        "startedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO-8601 timestamp the run started."
+        },
+        "heartbeatAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO-8601 timestamp bumped on every flush AND from the per-task push-event path. A stale heartbeat on a LIVE pid is advisory only (heartbeatStale) — never a crash verdict."
+        },
+        "headless": {
+          "type": "boolean",
+          "description": "True if launched under the --headless supervisor."
+        },
+        "attempt": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Supervisor attempt counter (resume generation)."
+        },
+        "resumeReady": {
+          "type": "boolean",
+          "description": "True once decomposedTasks is flushed post-decompose. Gates the supervisor crash branch: --resume when true, fresh restart when false (crashed during plan/decompose — nothing merged yet)."
+        },
+        "decomposedTasks": {
+          "type": "array",
+          "description": "Full enriched task objects (id/depends_on/description, NOT bare ids), so the crash bridge can synthesize a resume graph. Empty until decompose completes.",
+          "items": { "type": "object" }
+        },
+        "completedTaskIds": {
+          "type": "array",
+          "description": "Task ids whose validated result is already merged/in the blackboard. Resume skips these.",
+          "items": { "type": "string" }
+        },
+        "lastTaskId": {
+          "type": ["string", "null"],
+          "description": "Most recently completed task id (progress hint)."
+        },
+        "lastStepId": {
+          "type": ["string", "null"],
+          "description": "Most recent stratum step id."
+        },
+        "budget": {
+          "type": "object",
+          "description": "Optional mirror of the live flow budget {caps,consumed} for query burn reporting.",
+          "additionalProperties": true
+        }
+      }
+    },
+    "query": {
+      "type": "object",
+      "title": "GsdQuerySnapshot",
+      "description": "Read-only envelope emitted by `compose gsd query <feature>`. Synthesized with a fixed source precedence (state.json → pause.json → budget.json → absent). One status vocabulary across query/supervisor/tests.",
+      "required": ["feature", "status"],
+      "additionalProperties": true,
+      "properties": {
+        "feature": { "type": "string", "description": "Feature code queried." },
+        "status": {
+          "type": "string",
+          "enum": ["running", "crashed", "complete", "stuck", "budget", "failed", "absent"],
+          "description": "Derived status. 'crashed' (running+dead-pid) and 'absent' (no run state anywhere) are reader-only; the rest mirror the runner taxonomy."
+        },
+        "phase": {
+          "type": ["string", "null"],
+          "enum": ["planning", "decompose", "execute", "ship", "done", null]
+        },
+        "heartbeatStale": {
+          "type": "boolean",
+          "description": "Advisory: status is 'running' on a live pid but the heartbeat exceeded the stale threshold (run may be wedged). Never implies crashed."
+        },
+        "progress": {
+          "type": "object",
+          "description": "Task progress.",
+          "properties": {
+            "completed": { "type": "integer", "minimum": 0 },
+            "total": { "type": "integer", "minimum": 0 }
+          },
+          "additionalProperties": false
+        },
+        "resumeReady": {
+          "type": "boolean",
+          "description": "Whether a crash here would --resume (true) or restart fresh (false)."
+        },
+        "pid": { "type": ["integer", "null"] },
+        "flowId": { "type": ["string", "null"] },
+        "pause": {
+          "type": ["object", "null"],
+          "description": "When paused: the pause kind + detail (from pause.json)."
+        },
+        "budget": {
+          "type": ["object", "null"],
+          "description": "Cumulative/flow budget info when available (from state.json or budget.json)."
+        },
+        "heartbeatAt": { "type": ["string", "null"], "format": "date-time" }
+      }
+    }
+  }
+}

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"]
+      }
+    }
+  }
+}