@smartmemory/compose 0.5.0 → 0.5.1

package/lib/wave-checkpoint.js

@@ -0,0 +1,100 @@
+/** Git object/ref plumbing. Never checks out a branch or changes the real index. */
+import { execFileSync } from 'node:child_process';
+import { withTemporaryIndex, snapshotWorkingTree } from './consumer-fanout.js';
+
+export class WaveCheckpointError extends Error {
+  constructor(code, message) { super(message); this.name = 'WaveCheckpointError'; this.code = code; }
+}
+const fail = (code, message) => { throw new WaveCheckpointError(code, message); };
+function git(cwd, args, opts = {}) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: 'pipe', maxBuffer: 512 * 1024 * 1024, ...opts }).trim();
+}
+function symbolicRef(cwd, ref) {
+  try { return git(cwd, ['symbolic-ref', '-q', ref]); }
+  catch (error) { if (error.status === 1) return null; throw error; }
+}
+function validateRef(cwd, ref) {
+  if (typeof ref !== 'string' || !ref.startsWith('refs/heads/compose/wave/')) fail('WAVE_CHECKPOINT_DIVERGED', 'Expected a Compose wave ref');
+  try { git(cwd, ['check-ref-format', ref]); }
+  catch { fail('WAVE_CHECKPOINT_DIVERGED', 'Invalid wave ref'); }
+  if (symbolicRef(cwd, ref)) fail('WAVE_CHECKPOINT_DIVERGED', 'Symbolic wave refs are not allowed');
+  // Include other linked worktrees: updating their checked-out branch moves HEAD too.
+  const worktrees = git(cwd, ['worktree', 'list', '--porcelain']);
+  if (worktrees.split('\n').includes(`branch ${ref}`)) fail('WAVE_CHECKPOINT_DIVERGED', 'Wave ref is checked out in a worktree');
+}
+export function readCheckpointRef({ cwd, ref }) {
+  validateRef(cwd, ref);
+  try { return git(cwd, ['show-ref', '--verify', '--hash', ref]); }
+  catch (error) { if (error.status === 1 || error.status === 128 && /not a valid ref/.test(error.stderr?.toString())) return null; throw error; }
+}
+export function prepareCheckpoint({ cwd, ref, parentCommit, tree, workingTree, message, commitMetadata }) {
+  validateRef(cwd, ref);
+  if (typeof parentCommit !== 'string' || !/^[a-f0-9]{40,64}$/.test(parentCommit)) fail('WAVE_CHECKPOINT_EVIDENCE_MISSING', 'Parent must be a commit OID');
+  const parent = git(cwd, ['rev-parse', '--verify', `${parentCommit}^{commit}`]);
+  const capturedTree = tree ?? (workingTree === true ? snapshotWorkingTree(cwd) : workingTree);
+  if (!capturedTree) fail('WAVE_CHECKPOINT_EVIDENCE_MISSING', 'Checkpoint needs a tree or workingTree:true');
+  const treeId = git(cwd, ['rev-parse', '--verify', `${capturedTree}^{tree}`]);
+  const metadata = structuredClone(commitMetadata ?? {
+    authorName: git(cwd, ['config', 'user.name']), authorEmail: git(cwd, ['config', 'user.email']),
+    date: new Date().toISOString(),
+  });
+  if (!metadata.authorName || !metadata.authorEmail || !Number.isFinite(Date.parse(metadata.date))) fail('WAVE_CHECKPOINT_EVIDENCE_MISSING', 'Invalid pinned commit metadata');
+  metadata.date = new Date(metadata.date).toISOString();
+  if (typeof message !== 'string' || !message) fail('WAVE_CHECKPOINT_EVIDENCE_MISSING', 'Checkpoint message is required');
+  const env = { ...process.env, GIT_AUTHOR_NAME: metadata.authorName, GIT_COMMITTER_NAME: metadata.authorName,
+    GIT_AUTHOR_EMAIL: metadata.authorEmail, GIT_COMMITTER_EMAIL: metadata.authorEmail,
+    GIT_AUTHOR_DATE: metadata.date, GIT_COMMITTER_DATE: metadata.date };
+  const commit = git(cwd, ['commit-tree', treeId, '-p', parent], { input: message, env });
+  return { ref, parentCommit: parent, tree: treeId, commit, message, commitMetadata: metadata };
+}
+export function publishCheckpoint({ cwd, ref, expected, commit }) {
+  validateRef(cwd, ref);
+  git(cwd, ['cat-file', '-e', `${commit}^{commit}`]);
+  const zero = '0'.repeat(git(cwd, ['rev-parse', 'HEAD']).length);
+  try { git(cwd, ['update-ref', ref, commit, expected ?? zero]); }
+  catch (error) { fail('WAVE_CHECKPOINT_DIVERGED', `Checkpoint compare-and-swap refused: ${error.message}`); }
+  return commit;
+}
+export function worktreeBaseFor({ journal, ref }) {
+  const wave = journal?.wave;
+  if (!wave) return null;
+  if (wave.checkpoints.some(checkpoint => checkpoint.state !== 'published')) fail('WAVE_CHECKPOINT_EVIDENCE_MISSING', 'Checkpoint publication is pending');
+  const expected = wave.checkpoints.at(-1)?.commit ?? null;
+  if (ref !== expected) fail('WAVE_CHECKPOINT_DIVERGED', 'Wave ref differs from the published journal tip');
+  return expected ?? wave.baseCommit;
+}
+export function squashOntoBase({ cwd, ref, base }) {
+  if (git(cwd, ['rev-parse', 'HEAD']) !== base) fail('WAVE_CHECKPOINT_DIVERGED', 'HEAD moved from the pinned base');
+  const tip = readCheckpointRef({ cwd, ref });
+  if (!tip) fail('WAVE_CHECKPOINT_EVIDENCE_MISSING', 'Wave ref is missing');
+  return withTemporaryIndex(cwd, env => {
+    git(cwd, ['read-tree', base], { env });
+    const diff = execFileSync('git', ['diff', '--binary', base, tip, '--'], { cwd, encoding: 'utf8', maxBuffer: 512 * 1024 * 1024 });
+    if (diff) git(cwd, ['apply', '--cached', '--binary', '-'], { env, input: diff });
+    const tree = git(cwd, ['write-tree'], { env });
+    if (tree !== git(cwd, ['rev-parse', `${tip}^{tree}`])) fail('WAVE_CHECKPOINT_DIVERGED', 'Squashed tree differs from checkpoint');
+    return tree;
+  });
+}
+export function removeCheckpointRef({ cwd, ref, expected }) {
+  validateRef(cwd, ref);
+  if (!expected) fail('WAVE_CHECKPOINT_EVIDENCE_MISSING', 'Deletion requires the expected tip');
+  git(cwd, ['update-ref', '-d', ref, expected]);
+}
+/** Pure resume-table classification; all supplied decisions are durable ordinal evidence. */
+export function reconcileCheckpoint({ journalEntry: entry, refValue }) {
+  if (!entry) return refValue == null ? 'ADMIT_FROM_BASE' : 'WAVE_CHECKPOINT_DIVERGED';
+  if (entry.evidenceMissing) return 'WAVE_CHECKPOINT_EVIDENCE_MISSING';
+  if (entry.diverged) return 'WAVE_CHECKPOINT_DIVERGED';
+  if (!entry.commit) {
+    if (refValue !== (entry.previousCommit ?? null)) return 'WAVE_CHECKPOINT_DIVERGED';
+    return entry.gateOutcome === 'approve' ? 'PREPARE_AND_PUBLISH' : 'RECOVER_WAITING_GATE';
+  }
+  if (refValue === entry.commit) {
+    if (entry.state === 'prepared') return 'MARK_PUBLISHED';
+    return entry.terminal ? 'PRESERVE_PUBLISHED' : 'ALREADY_PUBLISHED';
+  }
+  if (refValue === entry.parentCommit || refValue == null && entry.waveNumber === 1) return 'REPLAY_AND_PUBLISH';
+  if (entry.knownAncestorCommits?.includes(refValue)) return 'RECONCILE_IN_ORDER';
+  return 'WAVE_CHECKPOINT_DIVERGED';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartmemory/compose",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Structured AI dev pipeline: your agent writes the code, Compose makes it prove it. Gated design decisions, enforced postconditions, and independent review from goal to shipped code.",
   "author": "SmartMemory",
   "license": "MIT",
@@ -88,7 +88,7 @@
     "@radix-ui/react-toggle-group": "^1.1.11",
     "@radix-ui/react-tooltip": "^1.2.8",
     "@smartmemory/sdk-js": "^1.4.60",
-    "@smartmemory/stratum": "^0.5.0",
+    "@smartmemory/stratum": "^0.5.2",
     "@tanstack/react-virtual": "^3.13.23",
     "ajv": "^8.18.0",
     "ajv-formats": "^3.0.1",

package/presets/team-fable-astra.profiles.json

@@ -0,0 +1,18 @@
+{
+  "plan": "claude:orchestrator:coordinator",
+  "execute": { "default": "codex:implementer:critical", "tier_from": "item.tier" },
+  "verify": "claude:orchestrator:standard",
+  "review": "codex:read-only-reviewer:critical",
+  "assess": "claude:orchestrator:coordinator",
+  "assess_gate": {
+    "decide_from": {
+      "step": "assess", "field": "action",
+      "approve": ["complete"], "revise": ["repair", "implement"], "kill": ["blocked"]
+    },
+    "validators": [{ "name": "WaveDecision", "review_step": "review", "tasks_field": "tasks" }]
+  },
+  "_consumer": {
+    "execute": { "ownership": "item.files_owned", "independent": true, "checkpoint_gate": "execute_merge" }
+  },
+  "_costCeiling": { "input": "cost_ceiling_usd", "default": 150, "gates": ["assess_gate"] }
+}

package/presets/team-fable-astra.stratum.yaml

@@ -0,0 +1,236 @@
+# TEAM PRESET: fable-astra
+#
+# Purpose:     Fable plans and assesses bounded waves; Astra implements and reviews.
+# Pattern:     Plan → parallel execute → merge → verify → fresh review → assess
+#              → repair/implement another wave, ship on complete, or kill on blocked.
+# Capability:  Per-task Codex tiers; fresh read-only Astra reviewer; Fable decisions.
+# Isolation:   worktree, literal file ownership; sequential merge and checkpoints.
+# Use with:    compose build <feature-code> --team fable-astra
+# Customize:   Copy BOTH team-fable-astra.stratum.yaml AND its .profiles.json
+#              sidecar into your project's pipelines/ and edit them together.
+# Ruling:      Concurrency is literal 3, customized by copying this preset, rather
+#              than an input as designed (TS schema accepts numeric literals only).
+#              cost_ceiling_usd remains an optional flow input, default 150 in the
+#              sidecar; compose build --cost-ceiling-usd overrides that ceiling.
+# Carry rules: References use ${} only, never when/set/ensure/iterate.until.
+#              Every wave consumer must descend from plan, be reset by the
+#              assess_gate revise closure, and precede that gate through after.
+#              execute_merge retries preserve wave; assess_gate replaces it.
+
+version: 1
+
+contracts:
+  Task:
+    id: string
+    description: string
+    files_owned: string[]
+    files_read: string[]
+    depends_on: string[]
+    tier: critical|standard|fast
+    tier_rationale: string
+  TaskGraph:
+    tasks: Task[]
+  Verification:
+    commands: string[]
+    outcomes: string[]
+  TaskResult:
+    outcome: string
+    summary: string
+    files_changed: string[]
+    verification: Verification
+  VerifyResult:
+    tests_pass: boolean
+    summary: string
+    verification: Verification
+    merged_diff: string
+  Finding:
+    severity: string
+    files: string[]
+    claim: string
+    evidence: string
+  ReviewFindings:
+    findings: Finding[]
+    blocking: boolean
+  WaveDecision:
+    action: repair|implement|complete|blocked
+    tasks: Task[]
+    rationale: string
+    addressed_findings: Finding[]
+    open_findings: Finding[]
+    blocking: boolean
+    open_count: integer
+  ShipResult:
+    phase: string
+    artifact: string
+    outcome: string
+    summary: string
+    files_changed: string[]?
+    commit_hash: string?
+
+flows:
+  entry: team_fable_astra
+  team_fable_astra:
+    input:
+      featureCode: string
+      description: string
+      # Accept the existing feature-build envelope; providers stay pinned below.
+      implementer_agent: string?
+      reviewer_agent: string?
+      pre_merge_gate: string[]?
+      cost_ceiling_usd: number?
+    output:
+      from: "${ship.output}"
+      contract: ShipResult
+    max_rounds: 4
+    carry:
+      wave:
+        initial: "${plan.output.tasks}"
+        on_revise:
+          assess_gate: "${assess.output.tasks}"
+    steps:
+      - id: plan
+        agent: claude
+        do: |
+          Plan wave 1 for ${input.featureCode}. Goal and acceptance criteria:
+          ${input.description}
+          Read the feature's design, brief, plan and acceptance criteria before planning.
+          MUST checklist:
+          - Return TaskGraph with 1..6 tasks, each with id, description, files_owned,
+            files_read, depends_on, tier and a one-line tier_rationale.
+          - Wave 1 must contain only mutually independent tasks: depends_on is empty
+            for every task. Waves carry dependencies; dependent work goes in later
+            waves after its prerequisite checkpoint, not into this wave.
+          - No two tasks may share files_owned. Redo the graph if ownership overlaps.
+          - files_owned must be literal repo-relative paths, never globs or directories.
+          - Use critical for tasks with design judgment or root-causing, standard
+            for brief-bounded implementation, fast for transcription-level edits; repair
+            waves default to the tier of the task being repaired or higher, never lower.
+          - Each task must fit one focused session; target 2-4 tasks for a typical feature.
+          Return the task graph only; do not implement or commit.
+        out: TaskGraph
+        ensure:
+          - expr: "len(result.tasks) >= 1"
+          - expr: "len(result.tasks) <= 6"
+        attempts: 3
+
+      - id: execute
+        after: [plan]
+        fanout:
+          over: "${wave}"
+          dispatch: consumer
+          concurrency: 3
+          isolation: worktree
+          require: all
+          merge: sequential
+          steps:
+            - agent: codex
+              do: |
+                Implement the task described by ${item} using TDD. Write the test
+                first, watch it fail, implement, and watch it pass. Honor the
+                item's id, description, files_owned (you may create/modify these)
+                and files_read (you may read but NOT modify these).
+                MUST touch only files_owned — anything else fails the task at merge.
+                MUST return {outcome, summary, files_changed, verification}, with
+                verification {commands, outcomes}: exact commands and corresponding
+                observed outcomes, including failures. Do not commit.
+              out: TaskResult
+
+      - id: execute_merge
+        after: [execute]
+        gate:
+          on_approve: verify
+          on_revise: execute
+          on_kill: null
+          max_rounds: 2
+
+      - id: verify
+        after: [execute_merge]
+        agent: claude
+        do: |
+          Verify the integrated tree for ${input.featureCode} against the goal and
+          acceptance criteria: ${input.description}
+          MUST run the project's relevant tests and integration checks on the merged
+          tree, check for merge conflicts, and record exact commands and outcomes.
+          MUST capture the full cumulative merged diff: git diff HEAD -- for tracked
+          files, plus git ls-files --others --exclude-standard and added-file diffs
+          using git diff --no-index -- /dev/null <path> for each new feature file
+          (exit 1 means differences). HEAD remains the build base until ship; new
+          merged files can still be untracked. Return VerifyResult with tests_pass,
+          summary, verification {commands, outcomes}, and merged_diff. Describe only
+          observed verification evidence; never copy worker summaries. Do not edit.
+          Report failures truthfully so review and assess can request a repair wave.
+        out: VerifyResult
+        ensure:
+          - expr: "len(result.summary) > 0"
+
+      - id: review
+        after: [verify]
+        agent: codex
+        do: |
+          Fresh independent read-only review of ${input.featureCode}.
+          Goal and acceptance criteria: ${input.description}
+          VerifyResult (including the cumulative merged diff): ${verify.output}
+          MUST checklist:
+          - Read the feature's design, brief and plan for its acceptance criteria.
+            Read the merged diff against the goal, those criteria and VerifyResult;
+            inspect the integrated source and affected callers.
+          - Probe cross-module wiring: a green unit suite is not evidence that the
+            user-facing path reaches the implementation. Cite the actual call path.
+          - Never read worker summaries, TaskResults, worker journals or transcripts.
+            Form your judgment from the diff, source, criteria and verification only.
+          - Return one finding per defect, with severity, files (literal repo-relative
+            paths), claim and concrete evidence. Include failed verification and unmet
+            criteria as findings; set blocking when any defect prevents completion.
+          - Return ReviewFindings {findings, blocking}. Do not edit or commit.
+        out: ReviewFindings
+
+      - id: assess
+        after: [review]
+        agent: claude
+        do: |
+          Assess ${input.featureCode} against its goal and acceptance criteria:
+          ${input.description}
+          Current tasks: ${wave}
+          TaskResults with verification evidence: ${execute.output}
+          VerifyResult and cumulative merged diff: ${verify.output}
+          Fresh ReviewFindings: ${review.output}
+          MUST checklist:
+          - Address every finding: reproduce its full finding object in exactly one
+            of addressed_findings or open_findings; justify dispositions in rationale.
+          - Copy blocking from review. Set open_count to len(open_findings).
+          - repair tasks must each own at least one file named by an open finding.
+            Dispatch only affected work; do not repeat accepted unaffected tasks.
+          - For repair or implement return 1..6 mutually independent tasks with empty
+            depends_on, disjoint literal repo-relative files_owned, and all Task fields.
+            Later waves start from the previous checkpoint containing prerequisites.
+          - Use critical for tasks with design judgment or root-causing, standard
+            for brief-bounded implementation, fast for transcription-level edits; repair
+            waves default to the tier of the task being repaired or higher, never lower.
+          - Choose implement when additional scoped work is needed; repair for defects.
+          - complete only when all acceptance criteria are met, verification passes,
+            there are zero open findings and blocking is false; return tasks: [].
+          - blocked when repair cannot proceed; retain the open findings (open_count
+            must be positive), explain why, and return tasks: [].
+          Return WaveDecision only. Do not edit or commit.
+        out: WaveDecision
+        ensure:
+          - expr: "result.action != 'complete' || (result.open_count == 0 && result.blocking == false)"
+          - expr: "result.action != 'blocked' || result.open_count > 0"
+          - expr: "result.open_count >= 0"
+
+      - id: assess_gate
+        after: [assess]
+        gate:
+          on_approve: ship
+          on_revise: execute
+          on_kill: null
+          max_rounds: 2
+
+      # Compose intercepts ship: squash the wave checkpoints and selectively commit.
+      - id: ship
+        after: [assess_gate]
+        agent: claude
+        do: |
+          Ship ${input.featureCode}: run final tests and squash the accepted wave
+          changes into one commit whose parent is the build base. Return ShipResult.
+        out: ShipResult

package/server/model-tiers.js

@@ -2,21 +2,26 @@
  * model-tiers.js — Model tier routing for STRAT-TIER.
  *
  * Maps symbolic tier names to provider-specific model IDs.
- * Tiers let pipeline specs declare intent (critical / standard / fast)
- * without hard-coding model strings — the map here is the single source of truth.
+ * Tiers let pipeline specs declare intent (critical / standard / fast / coordinator)
+ * without hard-coding model strings — the map here is the single source of truth,
+ * including the agent-string tier allow-list. Coordinator lets one preset role
+ * explicitly name Fable while critical stays Opus 5; other presets do not move
+ * silently to Fable.
  */
 
 /** @type {Record<string, string>} */
 export const MODEL_TIERS = {
-  critical: 'claude-opus-4-7',
-  standard: 'claude-sonnet-4-6',
+  critical: 'claude-opus-5',
+  standard: 'claude-sonnet-5',
   fast: 'claude-haiku-4-5-20251001',
+  coordinator: 'claude-fable-5-1',
 };
 
 export const CODEX_MODEL_TIERS = {
   critical: 'gpt-6-astra',
   standard: 'gpt-5.6-terra',
   fast: 'gpt-5.3-codex-spark',
+  coordinator: null,
 };
 
 // C12: codex efforts follow the routing convention — `low` is for trivial
@@ -26,11 +31,13 @@ const CODEX_TIER_THINKING = {
   critical: { mode: null, effort: 'high' },
   standard: { mode: null, effort: 'high' },
   fast: { mode: null, effort: 'medium' },
+  coordinator: null,
 };
 
 /**
  * Default thinking config per tier.
- * - Opus 4.7 / Sonnet 4.6 support adaptive thinking and the effort parameter.
+ * - Opus 5 / Sonnet 5 support adaptive thinking and the effort parameter.
+ * - Fable 5.1 thinking is always on; adaptive thinking uses effort to control depth.
  * - Haiku 4.5 doesn't accept the effort parameter (400 error), so fast tier stays off.
  *
  * @type {Record<string, { mode: 'adaptive'|'off', effort: 'low'|'medium'|'high'|'xhigh'|'max'|null }>}
@@ -39,13 +46,14 @@ export const TIER_THINKING = {
   critical: { mode: 'adaptive', effort: 'xhigh' },
   standard: { mode: 'adaptive', effort: 'high' },
   fast:     { mode: 'off',      effort: null   },
+  coordinator: { mode: 'adaptive', effort: 'high' },
 };
 
 /**
  * Resolve a tier name to a concrete model ID.
  *
  * @param {string|null|undefined} tier
- * @returns {string|null}  Model ID, or null if tier is unknown / not provided.
+ * @returns {string|null}  Model ID, or null if tier is unknown, unavailable for the provider, or not provided.
  */
 export function resolveTierModel(tier, provider = 'claude') {
   if (!tier) return null;