@smartmemory/compose 0.3.6-beta → 0.3.7

package/.claude/skills/compose/SKILL.md

@@ -391,111 +391,65 @@ If Stratum unavailable, continue with flat prompt chain.
 
 Triage is implicit on entry (severity, scope, path) — it gates which steps to run, not a Stratum step itself. Phases 6 (plan), 9 (docs) are folded into `fix` and `ship` respectively.
 
-### Spec Template
+### Spec Template (TS engine grammar, post-cutover)
+
+The TS engine's spec IR (validated by `stratum/ts/src/ir/validate.js`) differs
+from the retired python grammar: `version` is the number `1`, contracts use
+string shorthand, `flows.entry` names the entry flow, and steps use
+`do`/`out`/`after`/`ensure`/`attempts` (NOT `function`/`inputs`/`depends_on`).
+MCP `stratum_plan` currently reports grammar violations as a bare
+"spec validation failed" (smartmemory/stratum#26) — get the template right.
 
 ```yaml
-version: "0.1"
+version: 1
 contracts:
-  ResearchResult:
-    findings: {type: array}
-    relevant_files: {type: array}
   DesignResult:
-    path: {type: string}
-    word_count: {type: integer}
+    path: string
+    words: number
   BlueprintResult:
-    path: {type: string}
+    path: string
   ImplementResult:
-    files_changed: {type: array}
-    tests_pass: {type: boolean}
-
-functions:
-  research:
-    mode: compute
-    intent: "Explore the codebase with compose-explorer agents and surface patterns relevant to the feature."
-    input: {description: {type: string}}
-    output: ResearchResult
-    ensure:
-      - "len(result.findings) > 0"
-    retries: 2
-
-  write_design:
-    mode: compute
-    intent: "Run Phase 1 (and optional Phases 2-3) — explore, gate, write design.md."
-    input: {description: {type: string}}
-    output: DesignResult
-    ensure:
-      - "file_exists(result.path)"
-      - "result.word_count > 200"
-    retries: 2
-
-  write_blueprint:
-    mode: compute
-    intent: "Run Phases 4-5 — blueprint, verification. Gate before returning."
-    input: {description: {type: string}}
-    output: BlueprintResult
-    ensure:
-      - "file_exists(result.path)"
-    retries: 2
-
-  implement:
-    mode: compute
-    intent: "Run Phase 7 — TDD, E2E, review loop, coverage sweep."
-    input: {description: {type: string}}
-    output: ImplementResult
-    ensure:
-      - "result.tests_pass == True"
-      - "len(result.files_changed) > 0"
-    retries: 2
+    files_changed: string
+    tests_pass: boolean
 
 flows:
+  entry: compose_feature
   compose_feature:
-    input: {description: {type: string}}
-    output: ImplementResult
+    input:
+      goal: string
+    output:
+      from: "${implement.output}"
+      contract: ImplementResult
     steps:
-      - id: research
-        function: research
-        inputs: {description: "$.input.description"}
-        output_schema:
-          type: object
-          required: [findings]
-          properties:
-            findings: {type: array, items: {type: string}}
-            relevant_files: {type: array, items: {type: string}}
-
       - id: write_design
-        function: write_design
-        inputs: {description: "$.input.description"}
-        depends_on: [research]
-        output_schema:
-          type: object
-          required: [path, word_count]
-          properties:
-            path: {type: string}
-            word_count: {type: integer}
+        do: "Run Phase 1 (and optional 2-3) — explore, gate, write design.md. Codex design gate to REVIEW CLEAN."
+        out: DesignResult
+        ensure:
+          - file_contains: {path: "docs/features/<code>/design.md", text: "Design"}
+        attempts: 3
 
       - id: write_blueprint
-        function: write_blueprint
-        inputs: {description: "$.input.description"}
-        depends_on: [write_design]
-        output_schema:
-          type: object
-          required: [path]
-          properties:
-            path: {type: string}
+        after: [write_design]
+        do: "Run Phases 4-5 — blueprint grounded in real code, corrections table, verify every file:line ref."
+        out: BlueprintResult
+        ensure:
+          - file_contains: {path: "docs/features/<code>/blueprint.md", text: "Corrections"}
+        attempts: 3
 
       - id: implement
-        function: implement
-        inputs: {description: "$.input.description"}
-        depends_on: [write_blueprint]
-        output_schema:
-          type: object
-          required: [files_changed, tests_pass]
-          properties:
-            files_changed: {type: array, items: {type: string}}
-            tests_pass: {type: boolean}
-
+        after: [write_blueprint]
+        do: "Run Phase 7 — TDD, E2E, review loop, coverage sweep."
+        out: ImplementResult
+        ensure:
+          - file_exists: "docs/features/<code>/design.md"
+        attempts: 3
 ```
 
+Step results are reported via `stratum_step_done` with the step's `dispatchToken`;
+`result.output` must match the step's `out` contract exactly (string shorthand
+means scalar fields — e.g. `files_changed` is one string, not an array; extra
+keys are rejected).
+
 The bugfix flow lives in `compose/pipelines/bug-fix.stratum.yaml` (8 steps + bisect, ships with compose). The CLI entry `compose fix <bug-code>` (in `bin/compose.js`) reads `docs/bugs/<code>/description.md` (scaffolds and exits if missing) and dispatches `runBuild(code, { mode: 'bug', template: 'bug-fix', description })`.
 
 ### Hard-bug machinery (COMP-FIX-HARD, 2026-05-01)

package/bin/compose.js

@@ -137,6 +137,7 @@ if (!cmd || cmd === '--help' || cmd === '-h') {
   console.log('  items              List vision items from local state (no server)')
   console.log('  items show <id>    Show detail for a specific vision item')
   console.log('  triage    Analyze a feature and recommend build profile')
+  console.log('  metrics [--since <duration|ISO>] [--feature <code>] [--json]  Report dispatch, settlement, and triage metrics')
   console.log('  qa-scope  Show affected routes from a feature\'s changed files')
   console.log('  context decisions  Show the build decision log (--feature <FC>, --format text|json)')
   console.log('  gate list          List pending gates (--item <id>, --status pending|all|resolved)')
@@ -146,6 +147,7 @@ if (!cmd || cmd === '--help' || cmd === '-h') {
   console.log('  sync      Re-sync global skills from this install (alias of setup)')
   console.log('  update    Pull latest compose, reinstall deps, refresh global skill')
   console.log('  doctor    Check external skill dependencies')
+  console.log('  guard     Manage the canon guard and drift detection (install|uninstall|status|init|verify [--fix])')
   console.log('  --version Print compose version, git SHA, and install root')
   process.exit(0)
 }
@@ -738,6 +740,17 @@ async function runUpdate(flags) {
     } else {
       console.log('Stratum MCP wiring already current')
     }
+
+    // Healing .mcp.json only fixes what the NEXT client launch reads. An MCP
+    // server the agent already spawned keeps serving the old Stratum build for
+    // the rest of the session, so an update can look applied while every
+    // stratum_* tool still runs pre-update code. Say so explicitly — this has
+    // bitten us before (stale tool contracts surviving a "successful" upgrade).
+    if (!wiring.skipped) {
+      console.log('')
+      console.log('⚠ Restart your MCP client (e.g. /mcp reconnect, or restart Claude Code)')
+      console.log('  to pick up the new Stratum server — a running one keeps serving the old build.')
+    }
   }
 
   console.log('')
@@ -1898,6 +1911,245 @@ if (cmd === 'hooks') {
   process.exit(1)
 }
 
+if (cmd === 'guard') {
+  // compose guard {install,uninstall,status,verify} — COMP-CANON-GUARD S4/S5.
+  // Manages the write-time PreToolUse hook registration in .claude/settings.json.
+  // Scoped to compose's own checkout (dogfooding): the hook script uses a
+  // relative import into lib/, so it only works where .claude/ and lib/ are
+  // siblings — this repo. Cross-project install is design Open Question 2.
+  const sub = args[0] || 'status'
+  const { readFileSync: rfSync, writeFileSync: wfSync, existsSync: exSync, mkdirSync: mkSync } = await import('fs')
+  const { join: pjoin } = await import('path')
+  const { installGuardHook, uninstallGuardHook, guardHookStatus, HOOK_COMMAND, HOOK_MATCHER } =
+    await import('../lib/canon-guard.js')
+
+  const projectRoot = PACKAGE_ROOT
+  const claudeDir = pjoin(projectRoot, '.claude')
+  const settingsPath = pjoin(claudeDir, 'settings.json')
+  const hookScript = pjoin(claudeDir, 'hooks', 'canon-guard.mjs')
+
+  function readSettings() {
+    if (!exSync(settingsPath)) return {}
+    try {
+      return JSON.parse(rfSync(settingsPath, 'utf-8'))
+    } catch (e) {
+      console.error(`Error: ${settingsPath} is not valid JSON: ${e.message}`)
+      process.exit(1)
+    }
+  }
+  function writeSettings(obj) {
+    mkSync(claudeDir, { recursive: true })
+    wfSync(settingsPath, JSON.stringify(obj, null, 2) + '\n')
+  }
+
+  if (sub === 'init') {
+    // Establish the first record baseline (trust-on-first-use). This exists
+    // BECAUSE `verify --fix` correctly refuses to stamp records: without a
+    // separate, deliberate bootstrap there would be no way to create the very
+    // first manifest, and drift detection would report every record as `added`
+    // forever. Kept distinct so the one-time act of trusting the current records
+    // is explicit and auditable rather than a side effect of a repair flag.
+    // Reject unrecognised args rather than silently ignoring them: `init` WRITES
+    // a baseline, so a mistyped or unsupported scope flag must never quietly
+    // baseline the wrong workspace.
+    const initExtra = args.slice(1).filter((a) => a !== '--cwd' && !a.startsWith('--cwd='))
+    if (args.slice(1).length > 0) {
+      console.error('Usage: compose guard init')
+      console.error('`guard init` baselines the workspace it is run IN — cd there instead of passing a scope flag.')
+      if (initExtra.length !== args.slice(1).length) {
+        console.error('(--cwd is not supported here: it would write the baseline to a different repo than the one you named.)')
+      }
+      process.exit(1)
+    }
+
+    const { root: cwd } = resolveCwdWithWorkspace(args)
+    const { computeRecordHashes, initManifestExclusive, manifestPathFor, recordFileSet } =
+      await import('../lib/judgment-attest.js')
+
+    // `init` WRITES trust, so be explicit about the destination. The shared
+    // resolver honours COMPOSE_TARGET, which can point somewhere other than the
+    // shell's cwd — never let that be silent for this command.
+    if (resolve(cwd) !== resolve(process.cwd())) {
+      console.log(`Baselining resolved workspace: ${cwd}`)
+      console.log('(resolved via COMPOSE_TARGET / workspace config, not your current directory)')
+    }
+
+    const records = recordFileSet(cwd)
+    if (records.length === 0) {
+      console.log('No judgment records found — nothing to baseline.')
+      process.exit(0)
+    }
+
+    // Existence is decided by the FILESYSTEM and the write is exclusive (O_EXCL).
+    // A parsed-value check was wrong twice over: a manifest whose contents are
+    // literally `null` parses to null and would read as "absent" (overwriting a
+    // real baseline), and a check-then-write race let two initializers both pass
+    // the check. Re-baselining over an existing manifest is the laundering step,
+    // so it must fail on the write itself, not on an advisory look.
+    let hashes
+    try {
+      hashes = computeRecordHashes(cwd)
+    } catch (e) {
+      if (e?.code === 'JUDGMENT_RECORD_MALFORMED') {
+        console.error(`Refusing to baseline: ${e.message}`)
+        console.error('A malformed record cannot be trusted as-is — fix or remove it, then re-run.')
+        process.exit(1)
+      }
+      throw e
+    }
+
+    try {
+      initManifestExclusive(cwd, hashes)
+    } catch (e) {
+      if (e?.code === 'EEXIST') {
+        console.error(`A judgment record baseline already exists: ${manifestPathFor(cwd)}`)
+        console.error('`guard init` will not overwrite it — that would launder any raw record edit.')
+        console.error('Use `compose guard verify --fix` for projection drift, or the judgment_* tools to change records.')
+        process.exit(1)
+      }
+      throw e
+    }
+
+    console.log(`Baselined ${records.length} judgment record${records.length === 1 ? '' : 's'}.`)
+    console.log('These records are trusted AS-IS: there is no prior attestation to verify them against.')
+    console.log('From here, drift detection reports any careless change that does not go through the judgment tools.')
+    console.log(`Commit ${manifestPathFor(cwd)} so the baseline travels with the repo and re-baselining shows up as a reviewable diff.`)
+    process.exit(0)
+  }
+
+  if (sub === 'verify') {
+    const { root: cwd } = resolveCwdWithWorkspace(args)
+    const verifyArgs = args.slice(1)
+    const fix = verifyArgs.includes('--fix')
+    if (verifyArgs.some((arg) => arg !== '--fix') || verifyArgs.filter((arg) => arg === '--fix').length > 1) {
+      console.error('Usage: compose guard verify [--fix]')
+      process.exit(1)
+    }
+
+    const { verifyJudgmentCanon } = await import('../lib/judgment-verify.js')
+    const { regenerateProjections } = await import('../lib/judgment-gen.js')
+    const { computeRecordHashes, writeManifest } = await import('../lib/judgment-attest.js')
+
+    function formatProjectionFinding(finding) {
+      const match = /^(.*) \(([^)]+)\)$/.exec(finding)
+      return match ? `${match[1]} [${match[2]}]` : finding
+    }
+
+    function printDrift(result) {
+      console.error('Judgment canon drift detected:')
+      if (result.treeDrift.length > 0) {
+        console.error('  Tree drift (records-anchored file set):')
+        for (const finding of result.treeDrift) {
+          console.error(`    - ${finding.path} [${finding.kind}]`)
+        }
+      }
+      if (result.projectionDrift.length > 0) {
+        console.error('  Projection drift (records-anchored):')
+        for (const finding of result.projectionDrift) {
+          console.error(`    - ${formatProjectionFinding(finding)}`)
+        }
+      }
+      if (result.recordDrift.length > 0) {
+        console.error('  Record drift detection (careless changes only):')
+        for (const finding of result.recordDrift) {
+          console.error(`    - ${finding.path} [${finding.kind}]`)
+        }
+      }
+    }
+
+    let result = await verifyJudgmentCanon(cwd)
+
+    if (fix) {
+      const projectionDriftBefore = result.projectionDrift
+      if (projectionDriftBefore.length > 0) {
+        regenerateProjections(cwd)
+
+        // `--fix` NEVER writes the record manifest. The earlier "refresh it when
+        // records already passed" branch was both unnecessary and unsafe:
+        // unnecessary because a passing record set already matches the manifest,
+        // and unsafe because verifyJudgmentCanon releases the judgment lock when
+        // it returns, so a raw edit landing between that verdict and the rewrite
+        // would be stamped — laundering a hand-edit through the repair flag,
+        // exactly what R1 forbids. Projections are derived and safe to
+        // regenerate; records are not, so `--fix` simply does not touch them.
+        if (result.recordDrift.length > 0) {
+          console.log('Record drift was deliberately not fixed: --fix cannot bless record edits; use the judgment tools to make record changes.')
+        }
+
+        result = await verifyJudgmentCanon(cwd)
+        const remainingProjectionDrift = new Set(result.projectionDrift)
+        const repaired = projectionDriftBefore.filter((finding) => !remainingProjectionDrift.has(finding))
+        if (repaired.length > 0) {
+          console.log('Fixed projection drift:')
+          for (const finding of repaired) {
+            console.log(`  - ${formatProjectionFinding(finding)}`)
+          }
+        }
+      } else {
+        console.log('No projection drift to fix.')
+        if (result.recordDrift.length > 0) {
+          console.log('Record drift was deliberately not fixed: --fix cannot bless record edits; use the judgment tools to make record changes.')
+        }
+      }
+
+      if (result.treeDrift.length > 0) {
+        console.log('Tree drift was not fixed: --fix only regenerates derived projections.')
+      }
+    }
+
+    if (result.ok) {
+      console.log('Judgment canon drift detection passed.')
+      process.exit(0)
+    }
+
+    printDrift(result)
+    process.exit(1)
+  }
+
+  if (sub === 'install') {
+    if (!exSync(hookScript)) {
+      console.error(`Error: hook script missing at ${hookScript}`)
+      console.error('It is a tracked source file — ensure your checkout includes .claude/hooks/canon-guard.mjs')
+      process.exit(1)
+    }
+    const { settings, changed } = installGuardHook(readSettings())
+    if (changed) {
+      writeSettings(settings)
+      console.log('Installed canon-guard PreToolUse hook in .claude/settings.json')
+    } else {
+      console.log('canon-guard hook already installed (current).')
+    }
+    console.log(`  matcher: ${HOOK_MATCHER}`)
+    console.log(`  command: ${HOOK_COMMAND}`)
+    process.exit(0)
+  }
+
+  if (sub === 'uninstall') {
+    const { settings, changed } = uninstallGuardHook(readSettings())
+    if (changed) {
+      writeSettings(settings)
+      console.log('Removed canon-guard hook from .claude/settings.json')
+    } else {
+      console.log('No canon-guard hook installed.')
+    }
+    process.exit(0)
+  }
+
+  if (!sub || sub === 'status') {
+    const st = guardHookStatus(readSettings())
+    const scriptState = exSync(hookScript) ? 'present' : 'MISSING'
+    if (st.state === 'installed') console.log('canon-guard: installed (current)')
+    else if (st.state === 'stale') console.log('canon-guard: installed (stale — re-run `compose guard install`)')
+    else console.log('canon-guard: absent — run `compose guard install`')
+    console.log(`  hook script: ${scriptState} (${hookScript})`)
+    console.log(`  guards: docs/judgment/** (Write|Edit|NotebookEdit) — Claude-runtime only`)
+    process.exit(0)
+  }
+
+  console.error(`Unknown guard subcommand: "${sub}". Use: install | uninstall | status | init | verify [--fix]`)
+  process.exit(1)
+}
+
 if (cmd === 'validate') {
   // compose validate [--scope=feature|project] [--code=CODE] [--block-on=error|warning|info] [--json]
   let scope = 'project'
@@ -3822,6 +4074,42 @@ if (cmd === 'build') {
   console.error('  compose smartmemory sync [--dry-run] [--feature <CODE>]')
   process.exit(1)
 
+} else if (cmd === 'metrics') {
+  // ---------------------------------------------------------------------------
+  // compose metrics [--since <duration|ISO>] [--feature <code>] [--json]
+  // ---------------------------------------------------------------------------
+  const { root: cwd } = resolveCwdWithWorkspace(args)
+  let since = null
+  let feature = null
+  let json = false
+
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index]
+    if (arg === '--json') {
+      json = true
+      continue
+    }
+    if (arg === '--since' || arg === '--feature') {
+      const value = args[index + 1]
+      if (!value || value.startsWith('--')) {
+        console.error(`compose metrics: ${arg} requires a value`)
+        process.exit(1)
+      }
+      if (arg === '--since') since = value
+      else feature = value
+      index++
+      continue
+    }
+    console.error(`compose metrics: unknown flag ${arg}`)
+    process.exit(1)
+  }
+
+  const { collectDispatchMetrics, renderDispatchMetrics } = await import('../lib/dispatch-metrics.js')
+  const report = collectDispatchMetrics(cwd, { since, feature })
+  if (json) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+  else process.stdout.write(renderDispatchMetrics(report))
+  process.exit(0)
+
 } else {
   console.error(`Unknown command: ${cmd}`)
   process.exit(1)

package/bin/git-hooks/pre-push.template

@@ -14,12 +14,25 @@
 # (no flag change needed below). XREF_TARGET_MISSING stays error and blocks.
 
 set -u
+HOOK_VERSION="1"
 COMPOSE_NODE="__COMPOSE_NODE__"
 COMPOSE_BIN="__COMPOSE_BIN__"
 COMPOSE_WORKSPACE_ID="__COMPOSE_WORKSPACE_ID__"
 LOG="${COMPOSE_HOOK_LOG:-.compose/data/pre-push.log}"
 mkdir -p "$(dirname "$LOG")" 2>/dev/null || true
 
+# EAGAIN guard: git can hand hooks nonblocking stdout/stderr fds; a large echo
+# (the validate output below) then dies mid-write with "echo: write error:
+# Resource temporarily unavailable" and makes a successful push look failed.
+# O_NONBLOCK lives on the open file description (shared across processes), so a
+# child clearing it fixes the shell's own fds too.
+command -v perl >/dev/null 2>&1 && perl -MFcntl -e '
+  for my $fd (1, 2) {
+    open(my $fh, ">&=", $fd) or next;
+    my $flags = fcntl($fh, F_GETFL, 0) // next;
+    fcntl($fh, F_SETFL, $flags & ~O_NONBLOCK);
+  }' 2>/dev/null || true
+
 # ── Docs-only detection ──────────────────────────────────────────────────────
 # Parse the ref updates git feeds on stdin (this MUST run before anything else
 # touches stdin). If every pushed commit touches only docs/** or *.md, the test
@@ -61,6 +74,22 @@ if [ "$VALIDATE_EXIT" -ne 0 ]; then
   echo "pre-push: compose validate reported drift (ADVISORY — not blocking). Review with \`compose validate\`." >&2
 fi
 
+# ── Judgment drift-detection gate (COMP-CANON-GUARD S5) ─────────────────────
+# This runs for every push, including docs-only pushes: judgment canon is under
+# docs/judgment/**, so placing it inside the test-gate skip would miss the most
+# relevant push type. Accepted residual: git push --no-verify bypasses this hook.
+echo "pre-push: checking judgment canon for drift…" >&2
+"$COMPOSE_NODE" "$COMPOSE_BIN" guard verify >> "$LOG" 2>&1
+GUARD_EXIT=$?
+if [ "$GUARD_EXIT" -ne 0 ]; then
+  tail -n 40 "$LOG" >&2
+  echo "" >&2
+  echo "pre-push: judgment drift detected — push aborted (full log: $LOG)." >&2
+  echo "Run \`compose guard verify\` for details." >&2
+  exit "$GUARD_EXIT"
+fi
+echo "pre-push: judgment canon drift check green." >&2
+
 # ── Test gate (COMP-RESUME follow-up) ───────────────────────────────────────
 # Block the push if the suite is red. This is the gate whose absence let a broken
 # integration test (and a stale-schema consumer bug) reach main — nothing ran the

package/bin/judgment-import.js

@@ -29,6 +29,10 @@ import {
   judgmentJointAdd,
   judgmentLedgerAppend,
 } from '../lib/judgment-writer.js';
+import {
+  computeRecordHashes,
+  writeManifest,
+} from '../lib/judgment-attest.js';
 import { getJudgmentValidator } from '../lib/judgment/schema.js';
 
 const METHODS = ['EXT', 'INT', 'CONSTRUCT', 'ASSERT', 'STRADDLE'];
@@ -538,6 +542,9 @@ export async function runJudgmentImport(cwd, { dryRun = false } = {}) {
     cpSync(join(staging, 'docs', 'judgment', 'records'), tmpDst, { recursive: true });
     rename(tmpDst, dst);
     regenerateProjections(cwd);
+    // Trust-on-first-use baseline for the promoted TARGET records. Never use
+    // the staging manifest here: its workspace paths are disposable.
+    writeManifest(cwd, computeRecordHashes(cwd));
   }
 
   return {

package/contracts/feature-json.schema.json

@@ -40,6 +40,11 @@
       "maximum": 4,
       "description": "COMP-TRIAGE-5: raw machine tier (0-4) from the front estimator/refinement. Maps to `complexity` via tierToComplexity."
     },
+    "triageConfidence": {
+      "type": "string",
+      "enum": ["high", "medium", "low"],
+      "description": "COMP-TRIAGE-6: confidence from the front scope estimate."
+    },
     "estimateSource": {
       "type": "string",
       "enum": ["front", "refined", "escalated"],