@smartmemory/compose 0.2.52-beta → 0.2.54-beta

package/lib/vision-writer.js

@@ -14,6 +14,7 @@ import crypto from 'node:crypto';
 import { resolvePort } from './resolve-port.js';
 import { probeServer } from './server-probe.js';
 import { migrateVisionItemFeatureCode, normalizeGateOutcome } from './state-migrations.js';
+import { resolveMode } from './lifecycle-modes.js';
 
 const EMPTY_STATE = () => ({ items: [], connections: [], gates: [] });
 
@@ -171,9 +172,12 @@ export class VisionWriter {
       // featureCode) but no lifecycle — start lifecycle so the next CLI run
       // finds it by lifecycle.featureCode (#31).
       if (!existing.lifecycle?.featureCode) {
+        // COMP-ROADMAP-PLAN: forward `mode` so a repaired (e.g. UI-created) plan
+        // item starts as plan, not build. store.createItem drops unknown fields,
+        // so mode must travel on the start body (not item-create).
         await this._fetch(`/api/vision/items/${existing.id}/lifecycle/start`, {
           method: 'POST',
-          body: JSON.stringify({ featureCode }),
+          body: JSON.stringify({ featureCode, mode }),
         });
       }
       return existing.id;
@@ -188,9 +192,12 @@ export class VisionWriter {
         phase: 'planning',
       }),
     });
+    // COMP-ROADMAP-PLAN: forward `mode` on the post-create start so the lifecycle
+    // is stamped with the right mode (the item-create body can't carry it —
+    // store.createItem has no `mode` field).
     await this._fetch(`/api/vision/items/${item.id}/lifecycle/start`, {
       method: 'POST',
-      body: JSON.stringify({ featureCode }),
+      body: JSON.stringify({ featureCode, mode }),
     });
     return item.id;
   }
@@ -261,7 +268,16 @@ export class VisionWriter {
       // lifecycle yet — seed lifecycle.featureCode so the next CLI run binds by
       // the canonical key (#31).
       if (!existing.lifecycle?.featureCode) {
-        existing.lifecycle = { ...(existing.lifecycle || {}), featureCode, currentPhase: existing.lifecycle?.currentPhase || 'explore_design' };
+        existing.lifecycle = {
+          ...(existing.lifecycle || {}),
+          featureCode,
+          // currentPhase stays 'explore_design' (byte-identical to pre-MODES for
+          // build AND bug; it is transient — the runner overwrites it with the
+          // first stepId). Per-mode genesis-at-creation is deferred with the
+          // fix/plan UI phase wiring.
+          currentPhase: existing.lifecycle?.currentPhase || 'explore_design',
+          mode: existing.lifecycle?.mode || resolveMode(mode),
+        };
         this._atomicWrite(state);
       }
       return existing.id;
@@ -278,7 +294,10 @@ export class VisionWriter {
       status: 'planned',
       phase: 'planning',
       group,
-      lifecycle: { featureCode, currentPhase: 'explore_design' },
+      // currentPhase stays 'explore_design' (byte-identical for build AND bug;
+      // transient — overwritten by the runner's first stepId). mode is the new
+      // additive field; per-mode genesis-at-creation is a deferred follow-up.
+      lifecycle: { featureCode, currentPhase: 'explore_design', mode: resolveMode(mode) },
       slug: featureCode.toLowerCase().replace(/[^a-z0-9]+/g, '-'),
       confidence: null,
       createdAt: new Date().toISOString(),
@@ -327,10 +346,15 @@ export class VisionWriter {
       status: 'pending',
       createdAt: new Date().toISOString(),
     };
-    // Dedupe by full gate ID or by pending itemId+stepId to prevent duplicates
+    // Dedupe by full gate ID, or by a pending gate for the same item+step
+    // WITHIN THE SAME FLOW. The flowId guard is essential: without it, a fresh
+    // build (new flowId) would reuse a stale pending gate left behind by a prior
+    // crashed/aborted run for the same feature — that gate is never resolved, so
+    // the new build polls it until the 30-min server TTL expires it and then
+    // errors. Scoping to flowId mints a fresh per-run gate instead.
     const existingIdx = state.gates.findIndex(g =>
       g.id === gate.id ||
-      (g.itemId === gate.itemId && g.stepId === gate.stepId && g.status === 'pending')
+      (g.flowId === gate.flowId && g.itemId === gate.itemId && g.stepId === gate.stepId && g.status === 'pending')
     );
     if (existingIdx !== -1) {
       return state.gates[existingIdx].id;

package/package.json

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

package/pipelines/plan.stratum.yaml

@@ -0,0 +1,161 @@
+version: "0.3"
+
+# COMP-ROADMAP-PLAN — the `plan` product-planning lifecycle (peer to build/fix).
+# Front half of goal-to-product: frame → research → ideate → converge → estimate
+# → build-handshake. Top-level step IDs MUST equal the plan-mode phaseOrder
+# (explore_design / plan / ship) because phase tracking keys off the raw step_id
+# (lib/build.js). Flow input is {projectName, intent} to match the plan-mode
+# planInputs envelope (lib/lifecycle-modes.js plan.runner.planInputs == 'plan').
+# Absorbs `compose new`: ideation routes to the ideabox, output is canonical
+# feature.json (not hand-authored ROADMAP rows or design.md-only seeds).
+
+workflow:
+  name: plan
+  description: "Product-planning lifecycle — frame, research, ideate, converge to build-ready feature specs"
+  input:
+    projectName:
+      type: string
+      required: true
+    intent:
+      type: string
+      required: true
+
+contracts:
+  PlanDesignResult:
+    artifact:   {type: string}
+    features:   {type: array}
+    summary:    {type: string}
+
+  PlanConvergeResult:
+    artifact:   {type: string}
+    created:    {type: array}
+    summary:    {type: string}
+
+  PlanHandoffResult:
+    handed_off: {type: array}
+    summary:    {type: string}
+
+functions:
+  plan_design_gate:
+    mode: gate
+    timeout: 7200
+
+  plan_converge_gate:
+    mode: gate
+    timeout: 7200
+
+flows:
+  plan:
+    input:
+      projectName: {type: string}
+      intent: {type: string}
+    output: PlanHandoffResult
+    steps:
+      # Phase: explore_design — frame, research, ideate
+      - id: explore_design
+        agent: claude
+        intent: >
+          You are running the PRODUCT-PLANNING front half for this intent: {intent}
+
+          Do three things, then write the result to docs/plans/{projectName}/design.md:
+          1. FRAME — restate the goal, the problem it solves, who it is for, and the
+             scope boundaries (what is in v1, what is explicitly out).
+          2. RESEARCH — search the web and the codebase for prior art, existing
+             tools, architectural patterns, and risks. Summarize what is relevant.
+          3. IDEATE — propose candidate features (each with a short code and a
+             one-line description, ordered by dependency). Capture each idea in the
+             ideabox funnel (append to docs/product/ideabox.md, or run
+             `compose ideabox add`) so ideation lives in the funnel, not here. Then
+             shortlist the features you recommend building first.
+
+          Write docs/plans/{projectName}/design.md containing FRAME, RESEARCH, and
+          the shortlist (with feature codes). Return its path in "artifact" and the
+          shortlisted feature codes in "features".
+        inputs:
+          projectName: "$.input.projectName"
+          intent: "$.input.intent"
+        output_contract: PlanDesignResult
+        ensure:
+          - "file_exists(result.artifact)"
+          - "len(result.features) > 0"
+        retries: 2
+
+      # Gate: human reviews the framing + research + shortlist
+      - id: plan_design_gate
+        function: plan_design_gate
+        on_approve: plan
+        on_revise: explore_design
+        on_kill: null
+        depends_on: [explore_design]
+
+      # Phase: plan — converge, estimate, write build-ready specs
+      - id: plan
+        agent: claude
+        intent: >
+          Converge the shortlist in docs/plans/{projectName}/design.md into
+          build-ready feature specs. For EACH feature you commit to building:
+          1. ESTIMATE — assign a complexity (S | M | L | XL) and a triage build
+             profile (which lifecycle phases it needs, e.g.
+             {{"needs_prd": false, "needs_architecture": false}}).
+          2. SPEC — first write the per-feature design to <CODE>/design.md inside the
+             project features dir (docs/features/<CODE>/design.md by default, or the
+             paths.features root in .compose/compose.json). This is a real
+             product/feature design the build lifecycle will ratify. THEN create the
+             canonical feature.json by RUNNING this command from the project root
+             (it writes feature.json via the canonical writer, regenerates ROADMAP.md,
+             and auto-stamps triageTimestamp — works from any agent runtime, no MCP
+             needed):
+
+               compose roadmap add <CODE> --description "<one-line>" --phase "<phase>" \
+                 --status PLANNED --complexity <S|M|L|XL> \
+                 --profile '{"needs_prd":<bool>,"needs_architecture":<bool>,"needs_verification":<bool>,"needs_report":<bool>}' \
+                 --planned-by "{projectName}" [--impact <low|medium|high>]
+
+             Write design.md BEFORE running it (the command verifies design.md exists
+             and refuses otherwise). Do NOT hand-author ROADMAP rows or write
+             feature.json by hand.
+
+          Then write the planning narrative (decisions, estimates, sequencing) to
+          docs/plans/{projectName}/plan.md. Return plan.md in "artifact" and the
+          created feature codes in "created".
+        inputs:
+          projectName: "$.input.projectName"
+          intent: "$.input.intent"
+        output_contract: PlanConvergeResult
+        ensure:
+          - "file_exists(result.artifact)"
+          - "len(result.created) > 0"
+        retries: 2
+        depends_on: [plan_design_gate]
+
+      # Gate: human approves the converged plan + build-ready specs
+      - id: plan_converge_gate
+        function: plan_converge_gate
+        on_approve: ship
+        on_revise: plan
+        on_kill: null
+        depends_on: [plan]
+
+      # Phase: ship — handoff / verify build-readiness (plan mode does NOT git-commit
+      # here; runBuild's ship interception is gated off for mode=plan).
+      - id: ship
+        agent: claude
+        intent: >
+          Finalize the plan→build handoff. For EACH feature code in the provided
+          "created" list (the features the plan phase produced), verify its folder
+          under the project features dir (docs/features/<CODE>/ by default, or the
+          paths.features root in .compose/compose.json) has a feature.json (status
+          PLANNED, with plannedBy "{projectName}", complexity, profile,
+          triageTimestamp) and a design.md. Produce a short handoff summary listing
+          each build-ready feature and the exact `compose build <CODE>` command to
+          start it. Do NOT git-commit here — just verify and summarize. Return the
+          verified feature codes in "handed_off".
+        inputs:
+          projectName: "$.input.projectName"
+          intent: "$.input.intent"
+          created: "$.steps.plan.output.created"
+        output_contract: PlanHandoffResult
+        ensure:
+          - "len(result.handed_off) > 0"
+        retries: 1
+        depends_on: [plan_converge_gate]

package/server/artifact-manager.js

@@ -9,6 +9,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { resolveMode, artifactsOf } from '../lib/lifecycle-modes.js';
 /** Phases that produce named artifacts (derived from contracts/lifecycle.json). */
 const PHASE_ARTIFACTS = {
   explore_design: 'design.md',
@@ -139,20 +140,46 @@ function _matchSections(foundHeadings, schema) {
   return { found, missing, optional };
 }
 
+// ---------------------------------------------------------------------------
+// Mode-scoped artifact key set (shared by ArtifactManager + the MCP tools so
+// the populated and empty-root paths can never diverge). A mode that declares a
+// non-empty phaseArtifacts is scoped to that subset (global key order preserved);
+// a mode that declares none falls back to ALL keys (today's build/bug behavior).
+// ---------------------------------------------------------------------------
+
+export function artifactKeysForMode(mode = 'build') {
+  const all = Object.keys(ARTIFACT_SCHEMAS);
+  const wanted = artifactsOf(resolveMode(mode));
+  return wanted && wanted.length ? all.filter((k) => wanted.includes(k)) : all;
+}
+
 // ---------------------------------------------------------------------------
 // ArtifactManager
 // ---------------------------------------------------------------------------
 
 export class ArtifactManager {
   #featureRoot;
+  #mode;
 
-  constructor(featureRoot) {
+  constructor(featureRoot, mode = 'build') {
     this.#featureRoot = featureRoot;
+    this.#mode = resolveMode(mode);
+  }
+
+  /**
+   * The artifact filenames this mode assesses/scaffolds. A mode that declares a
+   * non-empty `phaseArtifacts` is scoped to that subset (intersected with the
+   * global schema map, preserving global key order); a mode that declares NONE
+   * (build's full set is explicit; fix declares []) falls back to ALL global
+   * keys — which is exactly today's behavior for build and bug items.
+   */
+  #artifactKeys() {
+    return artifactKeysForMode(this.#mode);
   }
 
   assess(featureCode) {
     const artifacts = {};
-    for (const filename of Object.keys(ARTIFACT_SCHEMAS)) {
+    for (const filename of this.#artifactKeys()) {
       artifacts[filename] = this.assessOne(featureCode, filename);
     }
     return { artifacts };
@@ -214,7 +241,7 @@ export class ArtifactManager {
     fs.mkdirSync(dir, { recursive: true });
     fs.mkdirSync(path.join(dir, 'sessions'), { recursive: true });
 
-    for (const filename of Object.keys(ARTIFACT_SCHEMAS)) {
+    for (const filename of this.#artifactKeys()) {
       if (options?.only && !options.only.includes(filename)) continue;
 
       const filePath = path.join(dir, filename);

package/server/compose-mcp-tools.js

@@ -8,7 +8,7 @@
 import fs from 'node:fs';
 import http from 'node:http';
 import path from 'node:path';
-import { ArtifactManager, ARTIFACT_SCHEMAS } from './artifact-manager.js';
+import { ArtifactManager, artifactKeysForMode } from './artifact-manager.js';
 import { getTargetRoot, getDataDir, resolveProjectPath, switchProject, setCurrentWorkspaceId, loadProjectConfig, isLifecycleEnabled } from './project-root.js';
 import { resolveProfile, isToolAllowed } from './mcp-tool-policy.js';
 import { getRoadmap } from '../lib/get-roadmap.js';
@@ -549,7 +549,7 @@ export async function toolValidateProject(args = {}) {
 // Returns small summaries only (counts + warning/dangling lists) — never the
 // HTML body, which would blow the MCP response token cap.
 export async function toolRoadmapGraph({ project, out } = {}) {
-  const { generateRoadmapGraph } = await import('../lib/roadmap-graph/index.js');
+  const { generateRoadmapGraph } = await import('./roadmap-graph-vision.js');
   const cwd = project || getTargetRoot();
   try {
     const r = generateRoadmapGraph(cwd, { out });
@@ -582,7 +582,7 @@ export async function toolRoadmapXrefPush({ project, apply } = {}) {
 }
 
 export async function toolRoadmapGraphCheck({ project, out } = {}) {
-  const { checkRoadmapGraph } = await import('../lib/roadmap-graph/index.js');
+  const { checkRoadmapGraph } = await import('./roadmap-graph-vision.js');
   const cwd = project || getTargetRoot();
   try {
     const r = checkRoadmapGraph(cwd, { out });
@@ -741,23 +741,25 @@ export async function toolIterationAbort({ id, reason }) {
 // Artifact tools — read/write directly (no REST delegation needed)
 // ---------------------------------------------------------------------------
 
-export function toolAssessFeatureArtifacts({ featureCode }) {
+export function toolAssessFeatureArtifacts({ featureCode, mode = 'build' }) {
   const featureRoot = resolveProjectPath('features');
   if (!fs.existsSync(featureRoot)) {
-    // Return empty assessments — feature root hasn't been created yet
+    // Return empty assessments — feature root hasn't been created yet. Iterate
+    // the SAME mode-scoped key set the populated path would, so the two paths
+    // never return a different artifact key set for the same mode.
     const empty = {};
-    for (const filename of Object.keys(ARTIFACT_SCHEMAS)) {
+    for (const filename of artifactKeysForMode(mode)) {
       empty[filename] = { exists: false, wordCount: 0, meetsMinWordCount: false, sections: { found: [], missing: [], optional: [] }, completeness: 0, lastModified: null };
     }
     return { artifacts: empty };
   }
-  const manager = new ArtifactManager(featureRoot);
+  const manager = new ArtifactManager(featureRoot, mode);
   return manager.assess(featureCode);
 }
 
-export function toolScaffoldFeature({ featureCode, only }) {
+export function toolScaffoldFeature({ featureCode, only, mode = 'build' }) {
   const featureRoot = resolveProjectPath('features');
-  const manager = new ArtifactManager(featureRoot);
+  const manager = new ArtifactManager(featureRoot, mode);
   return manager.scaffold(featureCode, only ? { only } : undefined);
 }
 

package/server/compose-mcp.js

@@ -329,6 +329,10 @@ const TOOLS = [
         position: { type: 'number', description: 'Sort order within phase' },
         parent: { type: 'string', description: 'Parent feature code, for cross-references' },
         tags: { type: 'array', items: { type: 'string' } },
+        profile: { type: 'object', description: 'Triage build profile (needs_prd/needs_architecture/etc.). Set by the plan lifecycle so build can skip fresh triage.' },
+        triageTimestamp: { type: 'string', description: 'Triage cache stamp (ISO 8601). Set AFTER design.md is written so build treats triage as a cached no-op.' },
+        plannedBy: { type: 'string', description: 'Originating plan session code (e.g. "PLAN-WIDGET"). Marks a plan-authored, build-ready feature.' },
+        impact: { type: 'string', enum: ['low', 'medium', 'high'], description: 'Estimated impact, carried from the plan/ideabox estimation step.' },
         force: { type: 'boolean', description: 'Bypass the pre-commit roundtrip guard (commit even if ROADMAP.md would not be a generation fixed point).' },
         idempotency_key: { type: 'string', description: 'Optional caller-provided key. Same key replays return the cached result without re-mutating.' },
       },