@smartmemory/compose 0.1.28-beta → 0.1.30-beta

package/README.md

@@ -95,6 +95,7 @@ Topic-scoped reference:
 - [docs/configuration.md](docs/configuration.md) — `.compose/*.json`, pipeline specs, `.mcp.json`, `ROADMAP.md`, environment variables.
 - [docs/mcp.md](docs/mcp.md) — MCP server tool list (vision, lifecycle, gates, iteration loops).
 - [docs/examples.md](docs/examples.md) — worked workflows and the full `compose pipeline` editing reference.
+- [docs/command-flows.md](docs/command-flows.md) — mermaid flow diagrams for every CLI verb (`build`, `fix`, `gsd`, `new`, `import`, `feature`, `roadmap`, `triage`, `qa-scope`, `pipeline`, `init`/`setup`/`update`/`doctor`).
 
 ### Specs and design
 

package/bin/compose.js

@@ -112,6 +112,7 @@ if (!cmd || cmd === '--help' || cmd === '-h') {
   console.log('  feature   Add a single feature (folder, design seed, ROADMAP entry)')
   console.log('  build     Run a feature through the headless lifecycle')
   console.log('  fix       Run a bug through the headless bug-fix lifecycle')
+  console.log('  gsd       Per-task fresh-context dispatch from existing blueprint+Boundary Map')
   console.log('  pipeline  View and edit the build pipeline')
   console.log('  roadmap            Show roadmap status and next buildable features')
   console.log('  roadmap generate   Regenerate ROADMAP.md from feature.json files')
@@ -1913,6 +1914,32 @@ if (cmd === 'build') {
       process.exit(1)
     })
   })
+} else if (cmd === 'gsd') {
+  // 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.
+  const gsdCode = args.find(a => !a.startsWith('-'))
+  if (!gsdCode) {
+    console.error('Usage: compose gsd <feature-code>')
+    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('')
+    console.error('Options:')
+    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
+  const { runGsd } = await import('../lib/gsd.js')
+  try {
+    const result = await runGsd(gsdCode, { cwd: gsdAgentCwd })
+    console.log(`gsd complete: ${result.blackboardEntries} task results captured.`)
+  } catch (err) {
+    console.error(`gsd failed: ${err.message}`)
+    process.exit(1)
+  }
 } else if (cmd === 'triage') {
   const triageCode = args.find(a => !a.startsWith('-'))
   if (!triageCode) {

package/contracts/goal-result.json

@@ -0,0 +1,128 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "goal-result.json",
+  "_source": "docs/features/STRAT-GOAL/design.md",
+  "_roadmap": "STRAT-GOAL",
+  "title": "GoalResult",
+  "description": "Output of stratum_goal — superset of JudgeResult (judge-result.json). Adds goal-orchestrator top-level fields: goal_id, goal_version, mode, status, turns_run, worker_runs, round, predicate_outcomes, and the optional would_have_decided. Invariant inherited: clean == met.",
+  "allOf": [
+    { "$ref": "judge-result.json" },
+    {
+      "type": "object",
+      "required": [
+        "goal_id",
+        "goal_version",
+        "mode",
+        "status",
+        "turns_run",
+        "worker_runs",
+        "round",
+        "predicate_outcomes"
+      ],
+      "properties": {
+        "goal_id": {
+          "type": "string",
+          "description": "Caller-supplied stable goal identifier. Immutable after first call."
+        },
+        "goal_version": {
+          "type": "string",
+          "const": "1.0",
+          "description": "Schema version for forward compatibility."
+        },
+        "mode": {
+          "enum": ["shadow", "advisory", "autonomous"],
+          "description": "Orchestration mode for this goal."
+        },
+        "status": {
+          "enum": [
+            "met",
+            "not_met",
+            "awaiting_decision",
+            "budget_exhausted",
+            "killed",
+            "in_progress"
+          ],
+          "description": "Current goal status. Derived from FlowState on every read — not a sticky sentinel. 'awaiting_decision' means a met claim is pending human review (advisory / non-whitelisted autonomous class). 'budget_exhausted' means max_turns reached before all predicates met. 'in_progress' is emitted only by stratum_goal_status for an in-flight goal that has not yet reached a terminal step or awaiting_decision — it is never produced by the orchestrator's GoalResult."
+        },
+        "turns_run": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Total number of judge-evaluated turns (worker-dispatch failures that never reached the judge are not counted)."
+        },
+        "worker_runs": {
+          "type": "array",
+          "description": "Per-turn worker dispatch record. Length may exceed turns_run when worker failures occurred before a judge call.",
+          "items": {
+            "type": "object",
+            "required": ["turn", "agent_correlation_id", "duration_ms"],
+            "properties": {
+              "turn": { "type": "integer", "minimum": 1 },
+              "agent_correlation_id": { "type": "string" },
+              "duration_ms": { "type": "integer", "minimum": 0 }
+            }
+          }
+        },
+        "round": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Current synthetic-flow round index. Used to address the goal_decision gate step as (goal_id, 'goal_decision')."
+        },
+        "predicate_outcomes": {
+          "type": "array",
+          "description": "Per-predicate outcome after autonomy partition. One entry per predicate in the goal's predicate list. MAY be empty for zero-turn results (e.g. budget exhausted before any judge call).",
+          "items": {
+            "type": "object",
+            "required": [
+              "id",
+              "type",
+              "verdict",
+              "confidence",
+              "applied_gate",
+              "judge_verdict",
+              "bound_autonomously",
+              "awaiting_human"
+            ],
+            "properties": {
+              "id": { "type": "string" },
+              "type": {
+                "enum": ["deterministic", "verified", "judged"],
+                "description": "Predicate type — determines autonomy eligibility."
+              },
+              "verdict": {
+                "enum": ["met", "not_met", "ambiguous"],
+                "description": "Post-normalization verdict — same as JudgeResult.predicates[].verdict."
+              },
+              "confidence": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 10
+              },
+              "applied_gate": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 10
+              },
+              "judge_verdict": {
+                "enum": ["met", "not_met", "ambiguous"],
+                "description": "Raw kernel verdict before autonomy partition (same as verdict in v1; separate field reserved for v2 mixed-mode where autonomy can override)."
+              },
+              "bound_autonomously": {
+                "type": "boolean",
+                "description": "True iff this predicate class was on the autonomy allow-list AND the verdict was met. Only ever true in autonomous mode."
+              },
+              "awaiting_human": {
+                "type": "boolean",
+                "description": "True iff verdict was met but this predicate class is NOT on the autonomy allow-list (advisory mode, or autonomous mode with non-whitelisted class). The goal pauses for human review."
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "would_have_decided": {
+          "enum": ["met", "not_met", "ambiguous"],
+          "description": "Shadow-mode only. Reflects what the loop would have decided if it were binding. Derived from the last turn's overall verdict. Present iff mode == 'shadow' AND at least one judge-evaluated turn ran. Omitted in the zero-turn edge case (e.g. all worker failures consumed budget)."
+        }
+      }
+    }
+  ]
+}

package/contracts/judge-result.json

@@ -0,0 +1,152 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "judge-result.json",
+  "_source": "docs/features/STRAT-JUDGE/design.md",
+  "_roadmap": "STRAT-JUDGE",
+  "title": "JudgeResult",
+  "description": "Output of stratum_judge — strict superset of CrossModelReviewResult. Adds judge-specific top-level fields (met, stakes, predicates, tier_disagreements, budget_consumed, judge_kernel_meta); inherits findings/clean/consensus/claude_only/codex_only/meta/summary unchanged. Invariant: clean == met. Findings are emitted only for not_met or ambiguous predicates; met predicates contribute zero findings.",
+  "allOf": [
+    { "$ref": "cross-model-review-result.json" },
+    {
+      "type": "object",
+      "required": [
+        "judge_version",
+        "met",
+        "stakes",
+        "predicates",
+        "budget_consumed",
+        "judge_kernel_meta"
+      ],
+      "properties": {
+        "judge_version": {
+          "type": "string",
+          "const": "1.0",
+          "description": "Schema version for forward compatibility."
+        },
+        "met": {
+          "type": "boolean",
+          "description": "Top-level goal verdict. Defined as all(p.verdict == 'met' for p in predicates) after per-predicate normalization. Identical to inherited `clean` by invariant."
+        },
+        "stakes": {
+          "enum": ["cheap", "default", "paranoid"],
+          "description": "Depth class set by caller. v1: cheap (T1 only), default (T1+T2). paranoid raises StakesNotAvailableError until v2."
+        },
+        "predicates": {
+          "type": "array",
+          "description": "Per-predicate verdicts. MAY be empty for zero-turn results (e.g. budget exhausted before any judge call). Non-empty results are validated at the kernel boundary (EmptyPredicateListError) to prevent vacuous-pass gate bypass.",
+          "items": {
+            "type": "object",
+            "required": [
+              "id",
+              "type",
+              "statement",
+              "verdict",
+              "confidence",
+              "applied_gate",
+              "evidence",
+              "tier_history"
+            ],
+            "properties": {
+              "id": { "type": "string" },
+              "type": {
+                "enum": ["deterministic", "verified", "judged"],
+                "description": "Predicate type sets the tier ceiling. deterministic = T1 only. verified = T2. judged = T3 in v2, downgraded to T2 in v1."
+              },
+              "statement": { "type": "string" },
+              "verdict": {
+                "enum": ["met", "not_met", "ambiguous"],
+                "description": "Post-normalization verdict. A raw 'met' with confidence < applied_gate is downgraded to 'ambiguous' before this is written."
+              },
+              "confidence": { "type": "integer", "minimum": 1, "maximum": 10 },
+              "applied_gate": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 10,
+                "description": "Per-predicate confidence threshold. Defaults to 7 (mirrors review-finding convention)."
+              },
+              "evidence": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": ["source", "quote", "tier"],
+                  "properties": {
+                    "source": {
+                      "type": "string",
+                      "pattern": "^(artifacts|modified)/[^:]+:[0-9]+$",
+                      "description": "Canonical citation format <bucket>/<path>:<line>. bucket must be 'artifacts' or 'modified'. Validated at the kernel boundary; path must resolve under the current turn's staging tree."
+                    },
+                    "quote": { "type": "string" },
+                    "tier": { "enum": ["T1", "T1.5", "T2", "T3", "T4"] }
+                  }
+                }
+              },
+              "tier_history": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": ["tier", "verdict", "confidence", "reason"],
+                  "properties": {
+                    "tier": { "enum": ["T1", "T1.5", "T2", "T3", "T4"] },
+                    "verdict": { "enum": ["met", "not_met", "ambiguous", "n/a"] },
+                    "confidence": {
+                      "type": ["integer", "null"],
+                      "minimum": 1,
+                      "maximum": 10,
+                      "description": "Null for T1 'n/a' verdicts (no LLM tier ran)."
+                    },
+                    "reason": { "type": "string" }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "tier_disagreements": {
+          "type": "array",
+          "description": "Cross-tier disagreements within a single judge call. Empty in v1 (single-tier-per-predicate after T1). Reserved for v2+ T2/T3 quorum resolution.",
+          "items": {
+            "type": "object",
+            "required": ["predicate", "tiers", "resolution"],
+            "properties": {
+              "predicate": { "type": "string" },
+              "tiers": { "type": "array", "items": { "type": "string" } },
+              "resolution": { "type": "string" }
+            }
+          }
+        },
+        "budget_consumed": {
+          "type": "object",
+          "required": ["turns", "dollars", "wall_clock_s"],
+          "properties": {
+            "turns": { "type": "integer", "minimum": 0 },
+            "dollars": {
+              "type": "number",
+              "minimum": 0,
+              "description": "Recorded but NOT enforced in v1 (no token-cost accounting yet)."
+            },
+            "wall_clock_s": { "type": "number", "minimum": 0 }
+          }
+        },
+        "judge_kernel_meta": {
+          "type": "object",
+          "required": ["decomposer_mode"],
+          "properties": {
+            "decomposer_mode": {
+              "enum": ["user", "auto", "hybrid", "ask"],
+              "description": "v1 ships 'user' only; auto/hybrid/ask are v2."
+            },
+            "smartmemory_priors_consulted": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Always 0 in v1 (SmartMemory wiring is v2)."
+            },
+            "degraded_judged": {
+              "type": "boolean",
+              "description": "True when a 'judged' predicate was downgraded to T2 because T3 is unavailable in v1."
+            }
+          }
+        }
+      }
+    }
+  ]
+}

package/contracts/review-result.json

@@ -68,8 +68,8 @@
       "required": ["agent_type", "model_id"],
       "properties": {
         "agent_type": {
-          "enum": ["claude", "codex"],
-          "description": "Which model type produced this result."
+          "enum": ["claude", "codex", "judge"],
+          "description": "Which model type produced this result. 'judge' is used by stratum_judge for T1-only paths (no LLM dispatched); when T2 fires, agent_type reflects the actual model invoked."
         },
         "model_id": {
           "type": ["string", "null"],

package/contracts/task-result.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "task-result.json",
+  "_source": "docs/features/COMP-GSD-2/blueprint.md",
+  "_roadmap": "COMP-GSD-2",
+  "title": "TaskResult",
+  "description": "Per-task post-execution capture written by the task agent at .compose/gsd/<featureCode>/results/<task_id>.json and committed as part of its diff. After execute step completion, runGsd walks the merged base cwd, reads each per-task file, and writes the consolidated blackboard.json. This schema is the post-execution audit/retro substrate (consumed by GSD-7 milestone reports), NOT a runtime channel between tasks.",
+  "type": "object",
+  "required": ["status", "files_changed", "summary", "produces", "gates", "attempts"],
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["passed", "failed"],
+      "description": "Whether the agent considered the task complete with all gates green."
+    },
+    "files_changed": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Repo-relative paths the agent touched in its worktree."
+    },
+    "summary": {
+      "type": "string",
+      "description": "One- or two-paragraph machine-readable summary of what was done."
+    },
+    "produces": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "Realized symbol map: { symbolName: signature-or-shape-string }. Mirrors the task's declared produces but with the actually-implemented signatures."
+    },
+    "gates": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/GateRun" },
+      "description": "One entry per gate command run. Array (not lint/build/test object) so arbitrary project-configured gateCommands are supported."
+    },
+    "attempts": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Number of internal TDD-loop iterations the agent took before declaring done."
+    }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "GateRun": {
+      "type": "object",
+      "required": ["command", "status", "output"],
+      "properties": {
+        "command": { "type": "string", "minLength": 1 },
+        "status": {
+          "type": "string",
+          "enum": ["pass", "fail"]
+        },
+        "output": {
+          "type": "string",
+          "description": "Truncated stdout/stderr from the gate run (e.g., last 2000 chars)."
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/contracts/taskgraph-gsd.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "taskgraph-gsd.json",
+  "_source": "docs/features/COMP-GSD-2/blueprint.md",
+  "_roadmap": "COMP-GSD-2",
+  "title": "TaskGraphGsd",
+  "description": "Output of the gsd pipeline's decompose_gsd step. Extends the bare TaskGraph (from build.stratum.yaml's decompose) with required produces/consumes per task, sourced from the blueprint's Boundary Map. Each task carries a rich `description` string pre-baked with the spec context that Stratum's parallel_dispatch interpolation cannot carry on its own.",
+  "type": "object",
+  "required": ["tasks"],
+  "properties": {
+    "tasks": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/definitions/Task" }
+    }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "Task": {
+      "type": "object",
+      "required": ["id", "files_owned", "files_read", "depends_on", "description", "produces", "consumes"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "files_owned": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Files this task may write. Must not overlap with other tasks' files_owned (enforced by no_file_conflicts ensure)."
+        },
+        "files_read": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Files this task may read but not write."
+        },
+        "depends_on": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Task ids that must complete before this one."
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Rich prompt fragment containing the per-task spec context (produces/consumes/slice/upstream summary/gates). Packed at decompose time because Stratum's parallel_dispatch only interpolates a fixed set of tokens."
+        },
+        "produces": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/ProducesEntry" },
+          "description": "Symbols this task lands. Sourced from the matching Boundary Map slice."
+        },
+        "consumes": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/ConsumesEntry" },
+          "description": "Symbols this task may import from upstream tasks (resolved at end-of-step merge in topological order)."
+        }
+      },
+      "additionalProperties": true
+    },
+    "ProducesEntry": {
+      "type": "object",
+      "required": ["file", "symbols", "kind"],
+      "properties": {
+        "file": { "type": "string", "minLength": 1 },
+        "symbols": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string" }
+        },
+        "kind": {
+          "type": "string",
+          "enum": ["interface", "type", "function", "class", "const", "hook", "component"],
+          "description": "Symbol kind. Mirrors lib/boundary-map.js KIND_ALLOWLIST."
+        }
+      },
+      "additionalProperties": false
+    },
+    "ConsumesEntry": {
+      "type": "object",
+      "required": ["from", "file", "symbols"],
+      "properties": {
+        "from": {
+          "type": "string",
+          "pattern": "^S\\d{2,}$",
+          "description": "Upstream slice id (S01, S02, ...)."
+        },
+        "file": { "type": "string", "minLength": 1 },
+        "symbols": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}