@smartmemory/compose 0.2.57-beta → 0.2.58-beta

package/lib/lane-gate.js

@@ -0,0 +1,200 @@
+// lib/lane-gate.js
+//
+// COMP-TRIAGE-5 — E3 (Estimate → Execute → Expand) front-of-pipeline scope
+// estimation + verification-gated escalation. Two entry points, extracted from
+// build.js runBuild/executeShipStep so they are unit-testable in isolation:
+//
+//   applyFrontTriage()  — E3 "Estimate": derive the lane from the RAW REQUEST
+//                         before any design/plan/blueprint doc is read, and
+//                         persist validated feature fields (closing the
+//                         complexity: String(tier) bypass at build.js:997/1006).
+//
+//   maybeEscalateLane() — E3 "Expand": on a failed ship-time test gate, escalate
+//                         the lane so the NEXT build runs wider — persist the
+//                         escalated lane + a widened profile + a bounded counter
+//                         and drop a resume checkpoint. STOP → human handoff.
+//                         Re-entry is via re-invocation reading the escalated
+//                         lane, NOT inline runBuild surgery.
+
+import { writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import {
+  estimateScope,
+  tierToComplexity,
+  floorProfileToLane,
+  runTriage,
+  tierToLane,
+  narrowerLane,
+} from './triage.js';
+import { validateFeatureFields } from './feature-writer.js';
+import { escalate } from './escalation.js';
+
+// Docs that make a doc-reading refinement meaningful. Absent all three, runTriage
+// would see zero files and return tier 0 ('trivial') — which is "no signal", not
+// "confirmed simple", and must NOT be allowed to narrow away the front safety clamp.
+const REFINEMENT_DOCS = ['design.md', 'plan.md', 'blueprint.md'];
+
+/**
+ * E3 Estimate. Runs before spec load. Derives {tier, profile, lane} from the raw
+ * request (doc-free) and persists validated fields through the shared validator
+ * (so the tier can no longer be stringified into `complexity`). Returns the
+ * values runBuild needs to toggle skip_if.
+ *
+ * @param {object} a
+ * @param {string} a.featureCode
+ * @param {string} [a.request]        raw task text (opts.description); falls back to the code
+ * @param {object} a.provider         build provider (getFeature/createFeature/putFeature)
+ * @param {object|null} a.cachedFeature  already-fetched feature.json, or null
+ * @returns {Promise<{buildProfile:object, tier:number, lane:string, tierLabel:string, rationale:string, cachedFeature:object}>}
+ */
+export async function applyFrontTriage({ featureCode, request, provider, cachedFeature, cwd, featuresDir }) {
+  // The CLI build path does not thread a description into opts, so fall back to
+  // the feature's own persisted description before the (signal-free) code string —
+  // otherwise every CLI build would classify the code and land low-confidence.
+  const req = request ?? cachedFeature?.description ?? featureCode;
+  const front = estimateScope(req);
+  let tier = front.tier;
+  let lane = front.lane;
+  let buildProfile = front.profile;
+  let estimateSource = 'front';
+
+  // E3 refinement (narrow-only): once design/plan/blueprint docs exist, a
+  // doc-reading pass may CONFIRM a smaller scope than the raw request implied —
+  // but it may only narrow the front lane, never widen it (widening is the
+  // escalation path's job). Gated on doc existence so a doc-less tier-0 read
+  // cannot undo the front safety clamp.
+  if (cwd && featuresDir) {
+    const dir = resolve(cwd, featuresDir, featureCode);
+    const hasDocs = REFINEMENT_DOCS.some((f) => existsSync(join(dir, f)));
+    if (hasDocs) {
+      try {
+        const refined = await runTriage(featureCode, { cwd, featuresDir });
+        const narrowed = narrowerLane(lane, tierToLane(refined.tier));
+        if (narrowed !== lane) {
+          lane = narrowed;
+          tier = refined.tier;
+          buildProfile = floorProfileToLane(refined.profile, narrowed);
+          estimateSource = 'refined';
+        }
+      } catch {
+        /* triage read failed — keep the front estimate */
+      }
+    }
+  }
+
+  const fields = {
+    complexity: tierToComplexity(tier),
+    triageTier: tier,
+    lane,
+    estimateSource,
+    profile: buildProfile,
+    triageTimestamp: new Date().toISOString(),
+  };
+  // Throws on any invalid field — this is the guard the raw provider write bypassed.
+  validateFeatureFields(fields);
+
+  let updated;
+  if (!cachedFeature) {
+    updated = await provider.createFeature(featureCode, {
+      code: featureCode,
+      description: req,
+      status: 'PLANNED',
+      ...fields,
+    });
+  } else {
+    updated = await provider.putFeature(featureCode, { ...cachedFeature, ...fields });
+  }
+
+  return {
+    buildProfile,
+    tier,
+    lane,
+    tierLabel: fields.complexity,
+    rationale: front.rationale,
+    cachedFeature: updated,
+  };
+}
+
+/**
+ * E3 Expand. On a failed ship-time test gate, escalate the lane so the next build
+ * runs wider. Bounded via escalationCount; on STOP or exhausted ladder, writes a
+ * checkpoint and hands off to a human. Best-effort — the caller never blocks ship
+ * on this. Only acts on features that went through front triage (have a `lane`).
+ *
+ * @param {object} a
+ * @param {string} a.featureCode
+ * @param {object} a.provider        build provider
+ * @param {string} [a.featureDir]    dir to write the escalation checkpoint into
+ * @param {string|null} [a.currentPhase]  optional live phase (unused for reEntry today; see escalation.js)
+ * @returns {Promise<{action:'none'|'escalate'|'stop', [from]:string, [to]:string, [reEntryPhase]:string, [escalationCount]:number}>}
+ */
+export async function maybeEscalateLane({ featureCode, provider, featureDir, currentPhase = null }) {
+  const feature = await provider.getFeature(featureCode);
+  // Only features that went through the front seam carry a lane — never escalate
+  // a feature that never opted into lane-based execution.
+  if (!feature?.lane) return { action: 'none' };
+
+  const lane = feature.lane;
+  const escalationCount = feature.escalationCount ?? 0;
+  const decision = escalate({ gate: 'test', passed: false }, lane, escalationCount, currentPhase);
+
+  if (decision === 'STOP') {
+    writeCheckpoint(featureDir, { featureCode, lane, decision: 'STOP', reEntryPhase: null, escalationCount });
+    return { action: 'stop', lane, escalationCount };
+  }
+  if (!decision) return { action: 'none' };
+
+  // Widen the profile to match the ESCALATED lane (not always full) so lane and
+  // profile stay consistent and each rung actually adds phases.
+  const widenedProfile = floorProfileToLane(feature.profile ?? {}, decision.nextLane);
+  validateFeatureFields({ lane: decision.nextLane, estimateSource: 'escalated' });
+  // Write the checkpoint BEFORE stamping triageTimestamp so the checkpoint file's
+  // mtime is older than the stamp — otherwise isTriageStale would treat the just-
+  // escalated feature as stale on the next build and overwrite the escalation.
+  writeCheckpoint(featureDir, {
+    featureCode,
+    lane: decision.nextLane,
+    decision: 'escalate',
+    reEntryPhase: decision.reEntryPhase,
+    escalationCount: escalationCount + 1,
+  });
+  await provider.putFeature(featureCode, {
+    ...feature,
+    lane: decision.nextLane,
+    estimateSource: 'escalated',
+    escalationCount: escalationCount + 1,
+    profile: widenedProfile,
+    triageTimestamp: new Date().toISOString(),
+  });
+  return {
+    action: 'escalate',
+    from: lane,
+    to: decision.nextLane,
+    reEntryPhase: decision.reEntryPhase,
+    escalationCount: escalationCount + 1,
+  };
+}
+
+function writeCheckpoint(featureDir, { featureCode, lane, decision, reEntryPhase, escalationCount }) {
+  if (!featureDir) return;
+  try {
+    mkdirSync(featureDir, { recursive: true });
+    const lines = [
+      `# COMP-TRIAGE-5 Escalation Checkpoint — ${featureCode}`,
+      '',
+      `- Decision: ${decision}`,
+      `- Lane: ${lane}`,
+      reEntryPhase ? `- Re-enter at phase: ${reEntryPhase}` : '- Re-enter: n/a (STOP — human handoff)',
+      `- Escalation count: ${escalationCount}`,
+      '- Trigger: ship-time test gate failed (E3 Expand)',
+      '',
+      decision === 'STOP'
+        ? 'Escalation bound reached. A human should investigate before re-running.'
+        : `Re-run \`compose build ${featureCode}\` — it reads the escalated lane and runs the heavier phases.`,
+      '',
+    ];
+    writeFileSync(join(featureDir, 'escalation-checkpoint.md'), lines.join('\n'), 'utf-8');
+  } catch {
+    /* best-effort — a checkpoint failure must never break the build */
+  }
+}

package/lib/triage.js

@@ -174,6 +174,150 @@ function deriveProfile(signals) {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Front-seam scope estimation (doc-free)
+// ---------------------------------------------------------------------------
+
+// Lane order, smaller index = smaller scope / more conservative.
+const LANE_ORDER = { trivial: 0, standard: 1, complex: 2 };
+
+// Verbs that denote a single, well-defined action. Presence (+ an explicit
+// file path) is what earns 'high' confidence; absence (+ no path) is what
+// earns 'low' confidence and triggers the safety clamp.
+const UNAMBIGUOUS_VERB_RE =
+  /\b(fix(?:e[ds]|ing)?|renam(?:e[ds]?|ing)|add(?:ed|s|ing)?|remov(?:e[ds]?|ing)|delet(?:e[ds]?|ing)|updat(?:e[ds]?|ing)|creat(?:e[ds]?|ing)|implement(?:ed|s|ing)?|refactor(?:ed|s|ing)?|bump(?:ed|s|ing)?|patch(?:ed|es|ing)?|mov(?:e[ds]?|ing)|extract(?:ed|s|ing)?|replac(?:e[ds]?|ing)|revert(?:ed|s|ing)?|rewrit(?:e|es|ing)|rewrote)\b/i;
+
+/**
+ * Map a triage tier (0-4) to a coarse lane.
+ *
+ * @param {number} tier
+ * @returns {'trivial'|'standard'|'complex'}
+ */
+export function tierToLane(tier) {
+  if (tier <= 1) return 'trivial';
+  if (tier === 2) return 'standard';
+  return 'complex';
+}
+
+/**
+ * Clamp a lane up to at least `minimum` (never narrows).
+ *
+ * @param {string} lane
+ * @param {string} minimum
+ * @returns {string}
+ */
+function clampLaneMin(lane, minimum) {
+  return LANE_ORDER[lane] < LANE_ORDER[minimum] ? minimum : lane;
+}
+
+/**
+ * Estimate scope from request text alone — the DOC-FREE front seam.
+ *
+ * Unlike `runTriage`, this never reads plan.md/blueprint.md/design.md (or
+ * any file at all). It derives the same `signals` shape `deriveProfile`
+ * expects purely from the request text and caller-supplied repo-signal
+ * hints, so it can run before any design doc exists — before the genesis
+ * phase, at feature-creation time.
+ *
+ * @param {string} request - Free-text feature/bug request description.
+ * @param {{ files?: string[] }} [repoSignals] - Candidate file paths the
+ *   request plausibly touches (caller-supplied, e.g. from a git-diff or
+ *   grep hint). Minimal shape: `{ files: string[] }`.
+ * @returns {{ tier: number, profile: object, lane: 'trivial'|'standard'|'complex', confidence: 'high'|'medium'|'low', rationale: string }}
+ */
+// Reconcile the tier-derived profile with the (possibly clamped) lane so the two
+// never disagree. The safety clamp raises the LANE, but skip_if is driven by the
+// PROFILE — without this floor a clamped-to-standard lane would still skip
+// verification, defeating the clamp. Standard keeps verification; complex keeps
+// every phase; trivial is left as deriveProfile set it.
+export function floorProfileToLane(profile, lane) {
+  if (lane === 'complex') {
+    return { needs_prd: true, needs_architecture: true, needs_verification: true, needs_report: true };
+  }
+  if (lane === 'standard') {
+    return { ...profile, needs_verification: true };
+  }
+  return { ...profile };
+}
+
+export function estimateScope(request, repoSignals = {}) {
+  const text = request ?? '';
+  const hintedFiles = Array.isArray(repoSignals?.files) ? repoSignals.files : [];
+
+  const textPaths = extractFilePaths(text);
+  const uniquePaths = new Set([...textPaths, ...hintedFiles]);
+  const pathList = [...uniquePaths];
+
+  const taskCount = countTasks(text);
+  const securityPaths = anyMatch(pathList, SECURITY_PATTERNS);
+  const corePaths = anyMatch(pathList, CORE_PATTERNS);
+
+  const signals = {
+    fileCount: uniquePaths.size,
+    securityPaths,
+    corePaths,
+    taskCount,
+    hasDesignDoc: false,
+  };
+
+  const { tier, profile, rationale } = deriveProfile(signals);
+
+  let lane = tierToLane(tier);
+  // Belt-and-suspenders: a security/core path hit must never resolve below
+  // 'standard', independent of how deriveProfile's own tier logic evolves.
+  if (securityPaths || corePaths) {
+    lane = clampLaneMin(lane, 'standard');
+  }
+
+  const hasPaths = uniquePaths.size > 0;
+  const hasUnambiguousVerb = UNAMBIGUOUS_VERB_RE.test(text);
+  let confidence;
+  if (hasPaths && hasUnambiguousVerb) {
+    confidence = 'high';
+  } else if (!hasPaths && !hasUnambiguousVerb) {
+    confidence = 'low';
+  } else {
+    confidence = 'medium';
+  }
+
+  // Safety clamp: under-scoping is the only dangerous error. Low confidence
+  // (no named paths, no clear verb) can never resolve to 'trivial'.
+  if (confidence === 'low') {
+    lane = clampLaneMin(lane, 'standard');
+  }
+
+  return { tier, profile: floorProfileToLane(profile, lane), lane, confidence, rationale };
+}
+
+/**
+ * Map a triage tier to a persisted complexity label.
+ *
+ * @param {number} tier - 0-4
+ * @returns {'S'|'M'|'L'|'XL'}
+ */
+export function tierToComplexity(tier) {
+  if (tier <= 1) return 'S';
+  if (tier === 2) return 'M';
+  if (tier === 3) return 'L';
+  return 'XL';
+}
+
+/**
+ * Return the more conservative (smaller-scope) of two lanes.
+ * Order: trivial < standard < complex.
+ *
+ * Used by refinement/escalation call sites to enforce "narrow-only" — a
+ * later pass may only shrink scope, never widen it (widening is
+ * escalation's job, via `lib/escalation.js`, not refinement's).
+ *
+ * @param {'trivial'|'standard'|'complex'} a
+ * @param {'trivial'|'standard'|'complex'} b
+ * @returns {'trivial'|'standard'|'complex'}
+ */
+export function narrowerLane(a, b) {
+  return LANE_ORDER[a] <= LANE_ORDER[b] ? a : b;
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartmemory/compose",
-  "version": "0.2.57-beta",
+  "version": "0.2.58-beta",
   "description": "Structured AI dev pipeline — goal-to-product orchestration with gates, iteration loops, and feature lifecycle management.",
   "author": "SmartMemory",
   "license": "MIT",

package/dist/assets/channel-CYErfopw.js

@@ -1 +0,0 @@
-import{ag as o,ah as n}from"./App-BmhlHOXF.js";const t=(a,r)=>o.lang.round(n.parse(a)[r]);export{t as c};

package/dist/assets/classDiagram-OUVF2IWQ-qCC_hnXu.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-V7JOEXUC-DrPIj6XI.js";import{_ as i}from"./App-BmhlHOXF.js";import"./chunk-5VM5RSS4-DTdG5JnR.js";import"./chunk-XXDRQBXY-BEIiZ6gS.js";import"./chunk-VR4S4FIN-BBUOVC5W.js";import"./chunk-32BRIVSS-DpImULWy.js";import"./mobile-PV1zQVwv.js";import"./index-CKfOVv2N.js";import"./graph--wGAvskB.js";var b={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{b as diagram};

package/dist/assets/classDiagram-v2-EOCWNBFH-qCC_hnXu.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-V7JOEXUC-DrPIj6XI.js";import{_ as i}from"./App-BmhlHOXF.js";import"./chunk-5VM5RSS4-DTdG5JnR.js";import"./chunk-XXDRQBXY-BEIiZ6gS.js";import"./chunk-VR4S4FIN-BBUOVC5W.js";import"./chunk-32BRIVSS-DpImULWy.js";import"./mobile-PV1zQVwv.js";import"./index-CKfOVv2N.js";import"./graph--wGAvskB.js";var b={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{b as diagram};

package/dist/assets/stateDiagram-v2-6OUMAXLB-BWqk_9py.js

@@ -1 +0,0 @@
-import{s as r,b as e,a,S as s}from"./chunk-EX3LRPZG-Cj1jNuKY.js";import{_ as i}from"./App-BmhlHOXF.js";import"./chunk-XXDRQBXY-BEIiZ6gS.js";import"./chunk-VR4S4FIN-BBUOVC5W.js";import"./chunk-32BRIVSS-DpImULWy.js";import"./mobile-PV1zQVwv.js";import"./index-CKfOVv2N.js";import"./graph--wGAvskB.js";var b={parser:a,get db(){return new s(2)},renderer:e,styles:r,init:i(t=>{t.state||(t.state={}),t.state.arrowMarkerAbsolute=t.arrowMarkerAbsolute},"init")};export{b as diagram};

package/dist/assets/swimlanesDiagram-G3AALYLV-C60ICdks.js

@@ -1,8 +0,0 @@
-import{c as r,s as e}from"./flowDiagram-23GEKE2U-C_sotK-k.js";import{_ as a}from"./App-BmhlHOXF.js";import"./chunk-5VM5RSS4-DTdG5JnR.js";import"./chunk-XXDRQBXY-BEIiZ6gS.js";import"./chunk-VR4S4FIN-BBUOVC5W.js";import"./chunk-32BRIVSS-DpImULWy.js";import"./channel-CYErfopw.js";import"./mobile-PV1zQVwv.js";import"./index-CKfOVv2N.js";import"./graph--wGAvskB.js";var o=a(t=>`${e(t)}
-  .swimlane.cluster rect {
-    stroke: ${t.clusterBorder} !important;
-  }
-  [data-look="neo"].cluster rect {
-    filter: none;
-  }
-`,"getStyles"),m=o,_=r({defaultLayout:"swimlane",styles:m});export{_ as diagram};