@smartmemory/compose 0.2.8-beta → 0.2.10-beta

package/bin/compose.js

@@ -1968,11 +1968,55 @@ 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> [--resume] [--reset-budget]')
+    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.')
@@ -1984,12 +2028,35 @@ if (cmd === 'build') {
     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 {
     if (gsdResetBudget) {
@@ -2020,6 +2087,13 @@ if (cmd === 'build') {
       }
       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/par-merge-bounce.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "par-merge-bounce.json",
+  "_source": "docs/features/COMP-PAR-MERGE-QUEUE/design.md",
+  "_roadmap": "COMP-PAR-MERGE-QUEUE",
+  "title": "ParMergeBounce",
+  "description": "A single bounce record produced by parallel_dispatch's post-dispatch merge gate. Unifies both failure kinds (a failed pre-merge verify gate, or a merge conflict during diff apply) into one structured contract. It is surfaced on the ensure_failed.bounced_tasks[] envelope AND persisted onto the failed task's state so that when the step is re-dispatched, Stratum's ParallelExecutor._render_prompt injects the failure context into the re-run task's prompt (server-side, because the server re-resolves the task list on each re-dispatch). Convention: _source = design doc origin, _roadmap = feature code.",
+  "type": "object",
+  "required": ["task_id", "reason", "files", "excerpt"],
+  "properties": {
+    "task_id": {
+      "type": "string",
+      "description": "Which task to bounce / re-dispatch."
+    },
+    "reason": {
+      "type": "string",
+      "enum": ["gate_failed", "merge_conflict"],
+      "description": "Why the task bounced. 'gate_failed' = a pre_merge_verify command exited non-zero in the task worktree; 'merge_conflict' = git apply --check/apply failed when merging the task diff onto base."
+    },
+    "files": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Files involved. gate_failed: from `git diff --name-only HEAD` in the worktree. merge_conflict: parsed from the git-apply error, falling back to the task's owned files."
+    },
+    "command": {
+      "type": ["string", "null"],
+      "description": "The gate command that failed, e.g. 'pnpm build'. Populated for gate_failed only; null for merge_conflict."
+    },
+    "exit_code": {
+      "type": ["integer", "null"],
+      "description": "Exit code of the failed gate command. Populated for gate_failed only; null for merge_conflict."
+    },
+    "excerpt": {
+      "type": "string",
+      "description": "Bounded (~2KB) tail of the gate stdout+stderr (gate_failed) OR the git-apply error text (merge_conflict). Bounded to avoid unbounded prompt growth and to limit credential leakage; do not echo environment."
+    }
+  },
+  "additionalProperties": true
+}