@smartmemory/compose 0.1.29-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/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"],