@smartmemory/compose 0.2.57-beta → 0.3.0

package/lib/escalation.js

@@ -0,0 +1,69 @@
+/**
+ * escalation.js — Pure escalation decision for the triage lane ladder.
+ *
+ * COMP-TRIAGE-5 / S03 (see docs/features/COMP-TRIAGE-5/plan.md, blueprint.md C3).
+ *
+ * `escalate` is a PURE decision function: no file I/O, no imports of build.js
+ * or the vision store. The caller (lib/build.js's escalation observer) reads
+ * currentPhase from the vision store itself and performs all side effects
+ * (un-skipping phases, re-entering, writing checkpoints, human handoff).
+ */
+
+/** Lane ladder, low → high. Exported so callers/tests (and S04) share one order. */
+export const LANE_ORDER = ['trivial', 'standard', 'complex'];
+
+/** Bound on escalation attempts before forcing a human handoff (STOP). */
+const MAX_ESCALATIONS = 2;
+
+/** Earliest phase to re-enter for each escalated-to lane. */
+const RE_ENTRY_PHASE_BY_LANE = {
+  standard: 'blueprint',
+  complex: 'design',
+};
+
+/**
+ * Decide whether/how to escalate the current build lane in response to a
+ * normalized gate result.
+ *
+ * @param {{gate: 'review'|'test', passed: boolean}} normalizedGate - normalized gate signal.
+ * @param {'trivial'|'standard'|'complex'} currentLane - current lane on the ladder.
+ * @param {number} escalationCount - number of escalations already performed for this feature.
+ * @param {string} [currentPhase] - caller-supplied current phase (from the vision store).
+ *   Not read or fetched here — the caller owns all I/O. Reserved for future use to avoid
+ *   re-entering a phase later than necessary than the lane's default reEntryPhase; ignored
+ *   in this implementation (see Deviation note below).
+ * @returns {null|'STOP'|{nextLane: string, reEntryPhase: string}}
+ *   - `null` — gate passed, no escalation needed.
+ *   - `'STOP'` — bounded out (escalationCount >= 2) or already at the top lane ('complex')
+ *     and the gate failed; caller performs human handoff.
+ *   - `{nextLane, reEntryPhase}` — escalate one rung up the ladder and re-enter at the
+ *     earliest phase the new lane requires.
+ */
+export function escalate(normalizedGate, currentLane, escalationCount, currentPhase) {
+  // currentPhase is intentionally unused: the design instructs "if unsure, ignore it and
+  // document that" (docs/features/COMP-TRIAGE-5/plan.md S03). Accepted as a parameter so
+  // the caller's signature is stable for S04, but the reEntryPhase returned here is always
+  // the ladder default for the target lane, not narrowed by currentPhase.
+  void currentPhase;
+
+  if (normalizedGate.passed === true) {
+    return null;
+  }
+
+  if (escalationCount >= MAX_ESCALATIONS) {
+    return 'STOP';
+  }
+
+  const currentIndex = LANE_ORDER.indexOf(currentLane);
+  const nextIndex = currentIndex + 1;
+
+  if (currentIndex === -1 || nextIndex >= LANE_ORDER.length) {
+    // Unknown lane or already at the top rung ('complex') — cannot escalate further.
+    return 'STOP';
+  }
+
+  const nextLane = LANE_ORDER[nextIndex];
+  const reEntryPhase = RE_ENTRY_PHASE_BY_LANE[nextLane];
+
+  return { nextLane, reEntryPhase };
+}

package/lib/feature-validator.js

@@ -572,14 +572,16 @@ function runArtifactLinkChecks(fctx, ctx, findings) {
     }
     // PLANNED / SUPERSEDED / KILLED / PARKED — no finding (expected baseline)
   }
-  // MISSING_COMPLETION_REPORT (warning, COMPLETE)
+  // MISSING_COMPLETION_REPORT (info, COMPLETE)
+  // The report phase is OPTIONAL/skippable (small features legitimately never
+  // write one), so a missing report.md is informational, not warning-level debt.
   // COMP-BUILD-QUICK-1: the quick lifecycle (compose build --quick) omits the
   // report phase by design and stamps built_via:'build-quick' on feature.json at
-  // ship. Exempt those features — a missing report.md is expected, not debt.
+  // ship — those stay fully exempt (no finding at all).
   if (status === 'COMPLETE' && !folder.files.has('report.md') &&
       featureJson?.built_via !== 'build-quick') {
-    findings.push(finding('warning', 'MISSING_COMPLETION_REPORT', code,
-      `Feature is COMPLETE but report.md is missing (current writers do not enforce this; warning only)`));
+    findings.push(finding('info', 'MISSING_COMPLETION_REPORT', code,
+      `Feature is COMPLETE without report.md — the report phase is optional (skippable for small features); informational only`));
   }
 
   // DANGLING_ARTIFACT_LINK + ARTIFACT_OUTSIDE_FEATURE_FOLDER

package/lib/feature-writer.js

@@ -63,6 +63,52 @@ const COMPLEXITIES = new Set(['S', 'M', 'L', 'XL']);
 // produced feature.json. Same vocab the ideabox uses (low|medium|high).
 const IMPACTS = new Set(['low', 'medium', 'high']);
 
+// COMP-TRIAGE-5: front-of-pipeline scope-estimation vocab. `lane` drives which
+// phases get skipped; `estimateSource` records whether the lane came from the
+// front estimator, the doc-reading refinement, or an escalation bump.
+const LANES = new Set(['trivial', 'standard', 'complex']);
+const ESTIMATE_SOURCES = new Set(['front', 'refined', 'escalated']);
+
+// ---------------------------------------------------------------------------
+// validateFeatureFields — shared field-shape guard
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate the subset of feature.json fields that carry a fixed vocabulary or
+ * range. Called from both addRoadmapEntry (below) and the build write path
+ * (lib/build.js) so neither can bypass the guard the way the old inline
+ * `COMPLEXITIES.has` check — scoped only to addRoadmapEntry — allowed
+ * `complexity: String(triageResult.tier)` (e.g. "0".."4") to reach disk via a
+ * raw provider write.
+ *
+ * Every field is optional; only fields present on `fields` are checked.
+ * Throws a plain Error (matching addRoadmapEntry's existing signaling) on the
+ * first violation found.
+ *
+ * @param {object} fields
+ * @param {string} [fields.complexity]     one of S|M|L|XL
+ * @param {number} [fields.triageTier]     integer 0-4
+ * @param {string} [fields.lane]           one of trivial|standard|complex
+ * @param {string} [fields.estimateSource] one of front|refined|escalated
+ */
+export function validateFeatureFields(fields) {
+  if (fields.complexity !== undefined && !COMPLEXITIES.has(fields.complexity)) {
+    throw new Error(`feature-writer: invalid complexity "${fields.complexity}"`);
+  }
+  if (fields.triageTier !== undefined &&
+      (!Number.isInteger(fields.triageTier) || fields.triageTier < 0 || fields.triageTier > 4)) {
+    throw new Error(`feature-writer: invalid triageTier "${fields.triageTier}" — must be an integer 0-4`);
+  }
+  if (fields.lane !== undefined && !LANES.has(fields.lane)) {
+    throw new Error(`feature-writer: invalid lane "${fields.lane}" — must be one of ${[...LANES].join(', ')}`);
+  }
+  if (fields.estimateSource !== undefined && !ESTIMATE_SOURCES.has(fields.estimateSource)) {
+    throw new Error(
+      `feature-writer: invalid estimateSource "${fields.estimateSource}" — must be one of ${[...ESTIMATE_SOURCES].join(', ')}`
+    );
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -115,6 +161,9 @@ function maybeIdempotent(args, fn) {
  * @param {string} [args.triageTimestamp]  COMP-ROADMAP-PLAN: triage cache stamp
  * @param {string} [args.plannedBy]        COMP-ROADMAP-PLAN: originating plan session
  * @param {string} [args.impact]           COMP-ROADMAP-PLAN: low | medium | high
+ * @param {string} [args.lane]             COMP-TRIAGE-5: trivial | standard | complex
+ * @param {number} [args.triageTier]       COMP-TRIAGE-5: integer 0-4
+ * @param {string} [args.estimateSource]   COMP-TRIAGE-5: front | refined | escalated
  * @param {boolean} [args.force]
  * @param {string} [args.idempotency_key]
  */
@@ -127,9 +176,11 @@ export async function addRoadmapEntry(cwd, args) {
   validateCode(args.code);
   if (!args.description) throw new Error('feature-writer: description is required');
   if (!args.phase) throw new Error('feature-writer: phase is required');
-  if (args.complexity && !COMPLEXITIES.has(args.complexity)) {
-    throw new Error(`feature-writer: invalid complexity "${args.complexity}"`);
-  }
+  // COMP-TRIAGE-5: complexity/triageTier/lane/estimateSource shape validation
+  // lives in the shared validateFeatureFields guard so the build write path
+  // (lib/build.js) can call the same check and can't bypass it the way the
+  // old inline `COMPLEXITIES.has` (scoped only to this function) allowed.
+  validateFeatureFields(args);
   const status = args.status ?? 'PLANNED';
   if (!STATUSES.has(status)) {
     throw new Error(`feature-writer: invalid status "${status}"`);
@@ -180,6 +231,10 @@ export async function addRoadmapEntry(cwd, args) {
     if (args.triageTimestamp !== undefined) feature.triageTimestamp = args.triageTimestamp;
     if (args.plannedBy !== undefined) feature.plannedBy = args.plannedBy;
     if (args.impact !== undefined) feature.impact = args.impact;
+    // COMP-TRIAGE-5: front-of-pipeline scope-estimation fields.
+    if (args.lane !== undefined) feature.lane = args.lane;
+    if (args.triageTier !== undefined) feature.triageTier = args.triageTier;
+    if (args.estimateSource !== undefined) feature.estimateSource = args.estimateSource;
 
     let roundtrip = null;
     if (isLocalProvider(provider)) {

package/lib/flow-state.js

@@ -1,6 +1,8 @@
 /**
- * flow-state.js — small read-only helpers over the persisted Stratum flow state
- * (`~/.stratum/flows/<flowId>.json`).
+ * flow-state.js — small read-only helpers over persisted Stratum flow state.
+ *
+ * Reads the TS store (`STRATUM_STATE_ROOT/<flowId>.json` when configured,
+ * otherwise `~/.stratum/ts/flows/<flowId>.json`).
  *
  * Shared by the gate handlers in build.js and new.js so the gate id can be made
  * round-aware (COMP-PLAN-GATE-LOOP).
@@ -10,27 +12,26 @@ import { join } from 'node:path';
 import { homedir } from 'node:os';
 
 /**
- * Read Stratum's current round for a flow from its persisted state file.
+ * Read Stratum's current round for a flow from its persisted state files.
  *
- * The await_gate dispatch Stratum returns does not carry the round, but the
- * persisted flow file does. Threading the round into the gate id
+ * The TS running response does not carry the round, but the persisted flow
+ * file does. Threading the round into the gate id
  * (`<flowId>:<stepId>:<round>`) makes each gate re-entry after a `revise` a
  * fresh, pending gate rather than colliding with the prior resolved gate and
  * replaying its stale outcome.
  *
- * Fail-open: returns 1 (the legacy default) if the file is missing, unreadable,
- * or lacks an integer round — a read failure must never block a gate.
+ * Fresh TS runs have no `rounds` field and use round 0. A read failure must
+ * never block a gate.
  *
  * @param {string} flowId
  * @returns {number}
  */
 export function readFlowRound(flowId) {
+  // TS store — STRATUM_STATE_ROOT-aware; flows are stored flat at the root.
   try {
-    const flowFile = join(homedir(), '.stratum', 'flows', `${flowId}.json`);
-    const state = JSON.parse(readFileSync(flowFile, 'utf-8'));
-    const r = state?.round;
-    return Number.isInteger(r) && r >= 0 ? r : 1;
-  } catch {
-    return 1;
-  }
+    const tsRoot = process.env.STRATUM_STATE_ROOT || join(homedir(), '.stratum', 'ts', 'flows');
+    const state = JSON.parse(readFileSync(join(tsRoot, `${flowId}.json`), 'utf-8'));
+    const r = state?.rounds;
+    return Number.isInteger(r) && r >= 0 ? r : 0;
+  } catch { return 0; }
 }

package/lib/gsd-budget.js

@@ -62,8 +62,8 @@ export function buildBudgetBlock(cfg = {}) {
   if (Object.keys(budget).length > 0) out.budget = budget;
 
   if (cfg.per_task_ms != null) {
-    // stratum parallel_dispatch per-task timeout is `task_timeout` in SECONDS
-    // (spec.py:145, schema minimum 1). Convert from ms, floor at 1s.
+    // Compose's per-consumer timeout is carried in seconds. Convert from ms and
+    // floor at 1s.
     out.taskTimeoutSec = Math.max(1, Math.ceil(cfg.per_task_ms / 1000));
   }
 
@@ -91,8 +91,13 @@ export function buildBudgetBlock(cfg = {}) {
  */
 export function injectBudget(specYaml, cfg = {}) {
   const built = buildBudgetBlock(cfg);
-  if (!built.budget && built.taskTimeoutSec == null) {
-    return specYaml; // identity — nothing to inject
+  // D2(a): per_task_ms is a PER-ITEM wall-clock ceiling enforced compose-side
+  // (runConsumerIssuance runs each agent), NOT an engine step budget — a step
+  // budget on the fanout cannot be per-item (the engine can't know N). So only
+  // the honest flow-wide budget is injected here; per_task_ms is threaded to the
+  // consumer loop via gsd.budget.per_task_ms.
+  if (!built.budget) {
+    return specYaml; // identity — nothing to inject into the spec
   }
 
   const parsed = YAML.parse(specYaml);
@@ -102,16 +107,49 @@ export function injectBudget(specYaml, cfg = {}) {
     throw new Error('injectBudget: spec has no flows.gsd to attach a budget to');
   }
 
-  if (built.budget) flow.budget = built.budget;
-
-  if (built.taskTimeoutSec != null && Array.isArray(flow.steps)) {
-    const execute = flow.steps.find((s) => s && s.id === 'execute');
-    if (execute) execute.task_timeout = built.taskTimeoutSec;
-  }
+  flow.budget = parsed.version === 1
+    ? {
+        ...(built.budget.max_tokens != null ? { tokens: built.budget.max_tokens } : {}),
+        ...(built.budget.max_agent_dispatches != null ? { dispatches: built.budget.max_agent_dispatches } : {}),
+        ...(built.budget.usd != null ? { usd: built.budget.usd } : {}),
+        ...(built.budget.ms != null ? { ms: built.budget.ms } : {}),
+      }
+    : built.budget;
 
   return YAML.stringify(parsed);
 }
 
+/**
+ * D2(c): adapt the TS engine's terminal `ledger` ({spent, budget}) into the
+ * legacy `budget_state` ({caps, consumed}) shape the GSD diagnostics/recording
+ * helpers consume. The python terminal envelope carried `budget_state`
+ * directly; the TS engine returns a `ledger` with the Budget key names
+ * (usd/tokens/dispatches/ms). Returns null for a missing/empty ledger so
+ * callers can `response.budget_state ?? budgetStateFromLedger(response.ledger)`.
+ *
+ * @param {{ spent?: object, budget?: object, limits?: object }} ledger
+ * @returns {{ caps: object, consumed: object } | null}
+ */
+export function budgetStateFromLedger(ledger) {
+  if (!ledger || typeof ledger !== 'object') return null;
+  const spent = ledger.spent ?? {};
+  const caps = ledger.budget ?? ledger.limits ?? {};
+  return {
+    caps: {
+      ...(caps.tokens != null ? { max_tokens: caps.tokens } : {}),
+      ...(caps.dispatches != null ? { max_agent_dispatches: caps.dispatches } : {}),
+      ...(caps.usd != null ? { usd: caps.usd } : {}),
+      ...(caps.ms != null ? { ms: caps.ms } : {}),
+    },
+    consumed: {
+      tokens: spent.tokens ?? 0,
+      dispatches: spent.dispatches ?? 0,
+      dollars: spent.usd ?? 0,
+      wall_s: (spent.ms ?? 0) / 1000,
+    },
+  };
+}
+
 // Maps a stratum budget axis → human label for diagnostics.
 const AXIS_LABEL = {
   max_tokens: 'tokens',

package/lib/gsd-prompt.js

@@ -2,10 +2,9 @@
 //
 // COMP-GSD-2 T4: buildTaskDescription — pure string assembly.
 //
-// Stratum's parallel_dispatch only interpolates {task.id|description|
-// files_owned|files_read|depends_on|index} and {input.<field>}. Every other
-// piece of context — the per-slice produces/consumes contract, the upstream
-// tasks summary, the gate commands — must be packed inside `task.description`.
+// TS consumer fanout renders each item, but richer per-slice context — the
+// produces/consumes contract, upstream summary, and gate commands — is packed
+// inside `task.description`.
 //
 // This module produces the rich `description` string. It is also used by
 // runGsd as a deterministic fallback when the decompose_gsd agent failed to

package/lib/gsd-stuck.js

@@ -15,7 +15,7 @@
  * no-progress are the only new bookkeeping.
  *
  * Consumes BuildStreamEvents from stratum.onEvent inside
- * executeParallelDispatchServer, keyed by event.task_id. gsd runs the execute
+ * the TS consumer runner, keyed by event.task_id. GSD runs the execute
  * step max_concurrent:1, so per-task state is unambiguous. Telemetry contract
  * (schema 0.2.7, STRAT-PAR-STREAM-TOOLDETAIL):
  *   tool_use_summary.metadata = { tool, summary, ok, duration_ms, input, tool_use_id }