@smartmemory/compose 0.4.1 → 0.5.1

package/.claude/agents/compose-architect.md

@@ -0,0 +1,40 @@
+---
+name: compose-architect
+description: Architecture-proposal agent for Compose's Phase 3. Dispatched 2-3 in parallel, each under a different competing mandate (minimal-changes / clean-architecture / pragmatic-balance), to produce a candidate architecture for a feature. Returns a self-contained proposal with component boundaries, interfaces, and honest trade-offs, grounded in the real codebase. Proposes only — does not implement.
+tools: Read, Grep, Glob, Bash
+---
+
+You are compose-architect. You are dispatched with ONE explicit mandate and must produce the best
+architecture for the feature **under that mandate** — so the main agent can compare competing
+proposals and synthesize. You propose; you do not write production code.
+
+## Mandates (you will be given exactly one)
+- **minimal-changes** — smallest possible diff, maximum reuse of what exists. Bias to extending
+  current modules over adding new ones.
+- **clean-architecture** — maintainability first; elegant boundaries and abstractions even if it
+  means more moving parts.
+- **pragmatic-balance** — 80/20: good boundaries without over-engineering.
+
+## Your job
+1. Read the relevant existing code (Grep/Glob/Read; Bash read-only) so the proposal is grounded in
+   real modules, signatures, and patterns — cite `path:line`.
+2. Design the architecture under your mandate: components and their responsibilities, the
+   interfaces/contracts between them, data flow, and error/edge handling.
+3. Be honest about trade-offs — what your mandate buys and what it costs versus the alternatives.
+
+## Hard constraints
+- READ-ONLY. Do not Edit/Write or run mutating commands. The main agent writes `architecture.md`
+  and implements.
+- Ground every structural claim in the real codebase (file:line). Flag where the feature would
+  cut against existing patterns.
+- Honor your mandate even where you'd personally choose differently — the value is in the contrast.
+
+## Output
+Return a self-contained proposal:
+- **Approach (mandate)** — one line naming your mandate and the core idea.
+- **Components & boundaries** — each component, its responsibility, and its interface/contract.
+- **Data flow** — how a request moves through the components.
+- **Trade-offs** — strengths, weaknesses, and what this costs vs the other mandates.
+- **Reuse / new** — what existing code is reused (file:line) vs what's new.
+
+Your final message IS the deliverable — return the proposal itself.

package/.claude/agents/compose-explorer.md

@@ -0,0 +1,35 @@
+---
+name: compose-explorer
+description: Read-only codebase exploration for Compose's design (Phase 1) and blueprint (Phase 4) phases. Use to find features similar to a target, map the architecture and abstractions of an area, or trace how an existing feature is implemented — dispatched 2-3 in parallel with distinct mandates. Returns findings with concrete file:line references; never edits code.
+tools: Read, Grep, Glob, Bash
+---
+
+You are compose-explorer, a focused read-only research agent for the Compose lifecycle. You are
+dispatched to investigate ONE specific question about the codebase and return grounded findings —
+not to design, plan, or change anything.
+
+## Your job
+Given a research mandate (e.g. "find features similar to X and trace their implementation", "map
+the architecture and abstractions for area Y", "analyze how feature Z works today"):
+
+1. Locate the relevant code with Grep/Glob; read the specific files and lines that matter.
+2. Identify the patterns, abstractions, and conventions actually in use — with **file:line**
+   references for every claim. Prefer reading exact regions over whole files.
+3. Note anything that contradicts the assumption behind the mandate (a "spec vs reality" gap).
+4. Use Bash only for read-only inspection (`git log`, `git grep`, `ls`, `rg`). Never write.
+
+## Hard constraints
+- READ-ONLY. Do not use Edit/Write. Do not run mutating commands. You investigate; the main agent
+  decides and implements.
+- Every load-bearing claim cites `path:line`. If you can't verify it, say so explicitly.
+- Stay within your mandate — don't expand into adjacent areas unless they're load-bearing for it.
+
+## Output
+Return a concise structured summary:
+- **Findings** — bulleted, each with file:line evidence.
+- **Relevant files** — the files the main agent should read to act on this.
+- **Patterns to follow** — conventions/idioms observed (with refs).
+- **Mismatches / risks** — where reality diverges from the mandate's assumption, if any.
+
+Your final message IS the deliverable — return the structured findings, not a narrative of what
+you did.

package/.claude/hooks/canon-guard.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * canon-guard.mjs — COMP-CANON-GUARD S4 PreToolUse hook (runtime wrapper).
+ *
+ * Registered in .claude/settings.json by `compose guard install`. Claude Code
+ * runs it before every Write/Edit/NotebookEdit and pipes the tool call as JSON
+ * on stdin. All logic lives in lib/canon-guard.js (pure, tested); this wrapper
+ * only does I/O: read stdin → decide → emit the deny envelope.
+ *
+ * Deny protocol (verified against code.claude.com/docs/en/hooks 2026-07-24):
+ * exit 0 + stdout {"hookSpecificOutput":{"hookEventName":"PreToolUse",
+ * "permissionDecision":"deny","permissionDecisionReason":"..."}}. No output =
+ * allow. FAIL OPEN on any error — a guard that wedges the session is worse than
+ * one that misses.
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { decideCanonGuard, realpathCanonicalize } from '../../lib/canon-guard.js';
+
+function allow() { process.exit(0); }
+
+let payload;
+try {
+  payload = JSON.parse(readFileSync(0, 'utf-8'));
+} catch {
+  allow(); // unreadable/invalid stdin → don't block
+}
+
+try {
+  // The hook lives at <repo>/.claude/hooks/canon-guard.mjs → repo root is two up.
+  const projectRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+  const decision = decideCanonGuard({
+    toolName: payload?.tool_name,
+    toolInput: payload?.tool_input,
+    cwd: payload?.cwd,
+    projectRoot,
+    canonicalize: realpathCanonicalize,
+  });
+  if (decision.deny) {
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: decision.reason,
+      },
+    }));
+  }
+} catch {
+  // fall through to allow
+}
+process.exit(0);

package/README.md

@@ -74,6 +74,20 @@ compose plan "a tool that summarizes my team's standups"
 
 `compose build` then picks up a plan-authored feature and ratifies its design rather than rewriting it.
 
+Bundled [team presets](docs/team-presets.md): `feature` (parallel implementation),
+`research` (parallel exploration), `review` (parallel review), and `fable-astra`:
+
+```bash
+compose build FEAT-1 --team fable-astra
+```
+
+Fable plans independent tasks, Codex workers implement in isolated worktrees, and
+a fresh read-only Astra reviewer checks the merged result after verification.
+Fable then requests another implementation or repair wave, declares the work
+blocked, or approves ship into one base-parent commit. Concurrency is 3; the
+$150 cost ceiling is overridable with `--cost-ceiling-usd`. See the
+[loop and limits](docs/pipelines.md#fable-astra-wave-loop).
+
 ## Quick install
 
 Prerequisites: Node.js 18+. [Stratum](https://github.com/smartmemory/stratum) needs no separate install — `@smartmemory/stratum` is a dependency, and `compose init` registers the installed copy's MCP entrypoint automatically (a sibling `stratum/` checkout is a development convenience, not a requirement; the python `stratum-mcp` PyPI package is retired). Codex steps additionally need the OpenAI `codex` CLI. Full prereqs in [docs/install.md](docs/install.md).
@@ -198,7 +212,7 @@ Signed descriptors live in `.compose/guard-upgrades/<sha256>/` (immutable) with
 The mobile cockpit at `/m` can be reached from outside localhost — bring your own tunnel, compose handles auth and pairing:
 
 ```bash
-npm run build                                  # remote serves the built PWA from the API server
+npm run build                                  # source checkouts only; the npm package already ships dist/
 COMPOSE_REMOTE_AUTH=enabled compose start --host=0.0.0.0
 compose remote pair --public-host=https://your-tunnel-host   # prints a QR — scan it with your phone
 compose remote status                          # bind, devices, tunnel reachability

package/bin/compose.js

@@ -98,6 +98,8 @@ import {
   formatDriftNudge,
 } from '../lib/version-check.js';
 import { computeHooksStatus, formatHookStatusLines, HOOK_MARKERS } from '../lib/hooks-status.js';
+// COMP-BUILD-CANCEL S06-3: the CLI must not exit out from under a live teardown (C46).
+import { pendingTeardown } from '../lib/build-cancel.js';
 
 const [,, cmd, ...args] = process.argv
 
@@ -565,8 +567,9 @@ async function runInit(flags, cwdOverride) {
   // and then fails with "Lifecycle spec not found" because init never copied it —
   // so the command was unavailable in every fresh workspace independently of the
   // spec's dialect. Each spec's `<name>.profiles.json` sidecar travels WITH it:
-  // loadPipelineProfiles fails open, so a spec copied without its sidecar runs on
-  // bare defaults and silently drops the tool restrictions it declares.
+  // loadPipelineProfiles treats a missing string-only sidecar as bare defaults (the
+  // tool restrictions it declares silently vanish), and runBuild REFUSES a local copy
+  // of a preset whose sidecar configures execution (team-fable-astra) without it.
   const pipelinesDir = join(cwd, 'pipelines')
   mkdirSync(pipelinesDir, { recursive: true })
   const DEFAULT_PIPELINES = [
@@ -968,6 +971,16 @@ if (cmd === 'new') {
         console.warn(`--from-idea: idea not found: ${fromIdeaId}`)
       }
     } catch (err) {
+      // An unreadable ideabox is not a missing idea, and it must not be
+      // downgraded into a warning that the build then walks straight past.
+      // `--from-idea` is an explicit request for THAT idea's content; building
+      // the feature without it produces a plausible-looking design derived from
+      // nothing the user asked for, while the ideas sit unread on disk
+      // (COMP-IDEABOX-MIGRATE-DIALECT FU-2).
+      if (err?.code === 'IDEABOX_UNREADABLE') {
+        console.error(`--from-idea: ${err.message}`)
+        process.exit(1)
+      }
       console.warn(`--from-idea: could not load idea: ${err.message}`)
     }
   }
@@ -2313,7 +2326,8 @@ if (cmd === 'guard') {
   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')
+      console.error('npm install: reinstall with `npm install @smartmemory/compose@latest` (add `--global` for a global install).')
+      console.error('source checkout: update the checkout, or restore the tracked .claude/hooks/canon-guard.mjs file.')
       process.exit(1)
     }
     const { settings, changed } = installGuardHook(readSettings())
@@ -2346,10 +2360,10 @@ if (cmd === 'guard') {
     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})`)
-    // Derived from the registry, never hardcoded: a literal string here
-    // silently under-reported the guarded set as soon as COMP-CANON-OVERRIDE
-    // widened it. "Claude-runtime only" is not modesty — Bash and Codex writes
-    // never reach this hook (drift detection, not enforcement).
+    // Derived from the registry, never hardcoded, so registry changes cannot
+    // silently desynchronize status output. "Claude-runtime only" is not
+    // modesty — Bash and Codex writes never reach this hook (drift detection,
+    // not enforcement).
     const { guardedDisplaysFor } = await import('../lib/canon-registry.js')
     for (const pattern of guardedDisplaysFor('hook')) {
       console.log(`  guards: ${pattern} (Write|Edit|NotebookEdit) — Claude-runtime only`)
@@ -2606,6 +2620,20 @@ if (cmd === 'build') {
   }
   let filteredArgs = args.filter((a, i) => i !== cwdIdx && (cwdIdx === -1 || i !== cwdIdx + 1))
 
+  // Extract value-taking build flags before --team counts positional features.
+  // --cwd is already removed; leave --template for the explicit team conflict.
+  const ceilingIdx = filteredArgs.findIndex(a => a === '--cost-ceiling-usd' || a.startsWith('--cost-ceiling-usd='))
+  let costCeilingUsd
+  if (ceilingIdx !== -1) {
+    const inline = filteredArgs[ceilingIdx].includes('=')
+    costCeilingUsd = Number(inline ? filteredArgs[ceilingIdx].split('=')[1] : filteredArgs[ceilingIdx + 1])
+    if (!Number.isFinite(costCeilingUsd) || costCeilingUsd <= 0) {
+      console.error('--cost-ceiling-usd requires a finite positive USD amount')
+      process.exit(1)
+    }
+    filteredArgs.splice(ceilingIdx, inline ? 1 : 2)
+  }
+
   // --team flag (COMP-TEAMS)
   let teamTemplate = null
   try {
@@ -2654,7 +2682,7 @@ if (cmd === 'build') {
   if (teamTemplate && !templateName) {
     templateName = teamTemplate
   }
-  const filteredArgs2 = filteredArgs.filter((a, i) => i !== templateIdx && (templateIdx === -1 || i !== templateIdx + 1))
+  let filteredArgs2 = filteredArgs.filter((a, i) => i !== templateIdx && (templateIdx === -1 || i !== templateIdx + 1))
 
   const featureCodes = filteredArgs2.filter(a => !a.startsWith('-'))
   const featureCode = featureCodes[0]
@@ -2712,6 +2740,10 @@ if (cmd === 'build') {
     console.error('Error: --abort and --all/prefix/multi are mutually exclusive')
     process.exit(1)
   }
+  if (costCeilingUsd !== undefined && isBatch) {
+    console.error('--cost-ceiling-usd is single-build only; batch is not supported')
+    process.exit(1)
+  }
   if (resume && fresh) {
     console.error('--resume and --fresh are mutually exclusive')
     process.exit(1)
@@ -2767,6 +2799,7 @@ if (cmd === 'build') {
     console.error('  --abort        Abort the active build')
     console.error('  --resume       Resume the active build for <feature-code>')
     console.error('  --fresh        Start a fresh build, discarding stale failed/resumable state')
+    console.error('  --cost-ceiling-usd <amount>  Override a configured ceiling (single build; holds still require a human)')
     console.error('  --all          Build all PLANNED features in dependency order')
     console.error('  --dry-run      Print build order without executing')
     console.error('  --cwd <path>   Agent working directory (for cross-repo features)')
@@ -2843,12 +2876,15 @@ if (cmd === 'build') {
       if (implementerArg) singleOpts.implementer = implementerArg   // COMP-MODEL-AB
       if (reviewerArg) singleOpts.reviewer = reviewerArg             // COMP-MODEL-AB
       if (resume) singleOpts.resume = true
+      if (costCeilingUsd !== undefined) singleOpts.costCeilingUsd = costCeilingUsd
       if (fresh) singleOpts.fresh = true
       if (nonInteractiveBuild) singleOpts.gateOpts = { nonInteractive: true }
       if (resumeFlowId) singleOpts.resumeFlowId = resumeFlowId
-      runBuild(featureCode, singleOpts).then(() => {
-        process.exit(0)
-      }).catch((err) => {
+      runBuild(featureCode, singleOpts).then(async (result) => {
+        await pendingTeardown()
+        process.exit(abort && result?.ok === false ? 1 : 0)
+      }).catch(async (err) => {
+        await pendingTeardown()
         console.error(`Build failed: ${err.message}`)
         process.exit(1)
       })
@@ -2963,9 +2999,11 @@ if (cmd === 'build') {
     if (agentWorkDir) opts.workingDirectory = agentWorkDir
     if (bugDescription) opts.description = bugDescription
     if (resumeFlowId) opts.resumeFlowId = resumeFlowId
-    runBuild(bugCode, opts).then(() => {
-      process.exit(0)
-    }).catch((err) => {
+    runBuild(bugCode, opts).then(async (result) => {
+      await pendingTeardown()
+      process.exit(abort && result?.ok === false ? 1 : 0)
+    }).catch(async (err) => {
+      await pendingTeardown()
       console.error(`Fix failed: ${err.message}`)
       process.exit(1)
     })
@@ -3074,9 +3112,11 @@ if (cmd === 'build') {
     const opts = { abort, template: 'plan', mode: 'plan', description: intent }
     if (agentWorkDir) opts.workingDirectory = agentWorkDir
     if (resumeFlowId) opts.resumeFlowId = resumeFlowId
-    runBuild(planCode, opts).then(() => {
-      process.exit(0)
-    }).catch((err) => {
+    runBuild(planCode, opts).then(async (result) => {
+      await pendingTeardown()
+      process.exit(abort && result?.ok === false ? 1 : 0)
+    }).catch(async (err) => {
+      await pendingTeardown()
       console.error(`Plan failed: ${err.message}`)
       process.exit(1)
     })

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

@@ -42,12 +42,16 @@ command -v perl >/dev/null 2>&1 && perl -MFcntl -e '
 ZERO_SHA="0000000000000000000000000000000000000000"
 DOCS_ONLY=1
 SAW_RANGE=0
+RANGES=" "
 while read -r _local_ref local_sha _remote_ref remote_sha; do
   [ "$local_sha" = "$ZERO_SHA" ] && continue   # ref delete — no content pushed
   if [ "$remote_sha" = "$ZERO_SHA" ]; then
-    DOCS_ONLY=0; SAW_RANGE=1; continue          # new ref — range unbounded, fail closed
+    DOCS_ONLY=0; SAW_RANGE=1
+    RANGES="$RANGES $remote_sha:$local_sha"      # receipts gate bounds a new ref itself
+    continue                                     # new ref — range unbounded, fail closed
   fi
   SAW_RANGE=1
+  RANGES="$RANGES $remote_sha:$local_sha"
   CHANGED=$(git diff --name-only "$remote_sha".."$local_sha" 2>/dev/null) || { DOCS_ONLY=0; continue; }
   while IFS= read -r f; do
     [ -z "$f" ] && continue
@@ -90,6 +94,27 @@ if [ "$GUARD_EXIT" -ne 0 ]; then
 fi
 echo "pre-push: judgment canon drift check green." >&2
 
+# ── Receipts gate ────────────────────────────────────────────────────────────
+# A claim written as a fact must carry its receipt: a CHECKED box saying a test
+# pins something needs the test path; "flake"/"flaky" needs a measurement or a
+# RESOLVED @sha; a commit saying the suite is green needs the counts. Scans only
+# the ADDED lines of the pushed range, so it never blocks on history. Runs on
+# docs-only pushes too — that is where "known flake" notes get written, and one
+# of those sat on a live product defect for two months (12a357a). Quote a phrase
+# in backticks to talk about it without asserting it. Bypass: --no-verify.
+RECEIPTS_GATE="$(dirname "$COMPOSE_BIN")/receipts-gate.js"
+if [ -f "$RECEIPTS_GATE" ]; then
+  for pair in $RANGES; do
+    "$COMPOSE_NODE" "$RECEIPTS_GATE" "${pair%%:*}" "${pair##*:}" 2>&1 | tee -a "$LOG" >&2
+    RECEIPTS_EXIT=${PIPESTATUS[0]}
+    if [ "$RECEIPTS_EXIT" -ne 0 ]; then
+      echo "" >&2
+      echo "pre-push: a claim has no receipt beside it — push aborted (full log: $LOG)." >&2
+      exit "$RECEIPTS_EXIT"
+    fi
+  done
+fi
+
 # ── 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/receipts-gate.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+/**
+ * receipts-gate — pre-push runner. `node bin/receipts-gate.js <base> <head>`.
+ *
+ * `base` may be git's all-zeros sha (a new ref); then the range is bounded by
+ * the merge-base with origin/main, or head~1 when there is no origin/main —
+ * fail CLOSED (scan something) rather than open (scan nothing).
+ * Exit 1 on any violation. See lib/receipts-gate.js for what counts.
+ */
+import { execFileSync } from 'node:child_process';
+import { scanRange, formatViolations } from '../lib/receipts-gate.js';
+
+const ZERO = /^0{40}$/;
+const [, , baseArg, headArg = 'HEAD'] = process.argv;
+
+function git(args) {
+  return execFileSync('git', args, { encoding: 'utf8' }).trim();
+}
+
+let base = baseArg;
+if (!base || ZERO.test(base)) {
+  try { base = git(['merge-base', 'origin/main', headArg]); }
+  catch { base = `${headArg}~1`; }
+}
+
+let found;
+try {
+  found = scanRange(base, headArg);
+} catch (err) {
+  // A gate that cannot read its input must not pass silently.
+  console.error(`receipts-gate: could not scan ${base}..${headArg}: ${err.message}`);
+  process.exit(2);
+}
+
+if (found.length) {
+  console.error(formatViolations(found));
+  process.exit(1);
+}
+console.error(`receipts-gate: ${base.slice(0, 7)}..${headArg} carries no unreceipted claims.`);

package/contracts/fluid-record.schema.json

@@ -122,6 +122,11 @@
           "type": ["string", "null"],
           "description": "Where the idea came from, as free text."
         },
+        "extra_fields": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Hand-authored markdown field lines the ideabox parser did not recognise, kept verbatim in serializer order. Exists so migrating a markdown ideabox into records is lossless: this contract is closed and the record shape is an allowlist, so a custom field with nowhere to live is deleted from the user's file by the first render after the upgrade, silently. See COMP-IDEABOX-MIGRATE-DIALECT."
+        },
         "links": {
           "type": "array",
           "items": { "$ref": "#/definitions/link" }