@geraldmaron/construct 1.0.0 → 1.0.1

package/lib/storage/vector-client.mjs

@@ -0,0 +1,286 @@
+/**
+ * lib/storage/vector-client.mjs — Unified vector storage client for pgvector.
+ *
+ * Hides whether we're using local Postgres, managed Postgres, or (future) external vector DB.
+ * All callers use: store(id, embedding, metadata) and search(queryEmbedding, filters).
+ *
+ * Works with any Postgres that has the pgvector extension installed.
+ * Connection string (DATABASE_URL) determines the target.
+ *
+ * Dimensionality is resolved from the embedding engine at construction time
+ * via `getEmbeddingModelInfo()`. The legacy `PGVECTOR_DIMENSIONS = 384` constant
+ * is retained as a fallback only when the engine cannot be reached. When
+ * `assertSchemaDimensions()` runs, the actual `embedding` column declared
+ * dimension is read from `pg_attribute` and compared against the engine; a
+ * mismatch surfaces a precise error so the operator can either rerun a
+ * compatible migration or change `CONSTRUCT_EMBEDDING_MODEL`.
+ *
+ * NOTE: `postgres` package is imported lazily to avoid ERR_MODULE_NOT_FOUND
+ * when this module is loaded in environments where `postgres` is not installed.
+ */
+
+import { getEmbeddingModelInfo } from './embeddings-engine.mjs';
+
+const DEFAULT_POOL = { max: 10, idle_timeout: 20, connect_timeout: 10 };
+const FALLBACK_DIMENSIONS = 384;
+
+export const PGVECTOR_DIMENSIONS = FALLBACK_DIMENSIONS;
+
+export function floatArrayToPgVector(arr) {
+  if (!arr) return null;
+  const values = arr instanceof Float32Array ? Array.from(arr) : arr;
+  return `[${values.join(',')}]`;
+}
+
+export function assertPgvectorDimensions(embedding, { expected = FALLBACK_DIMENSIONS, label = 'embedding' } = {}) {
+  const length = embedding?.length;
+  if (length !== expected) {
+    throw new Error(`${label} has ${length ?? 0} dimensions; pgvector schema expects ${expected}. Configure a ${expected}d embedding model or run a compatible migration before indexing.`);
+  }
+}
+
+export class VectorClient {
+  constructor({ databaseUrl, env } = {}) {
+    this.url = databaseUrl || process.env.DATABASE_URL || null;
+    this.env = env || process.env;
+    this._sql = null;
+    this._pgModule = null;
+    this._engineDim = null;
+  }
+
+  /**
+   * Lazily resolve the active embedding engine's dimensionality. Cached for
+   * the life of the client. If engine resolution fails, falls back to
+   * FALLBACK_DIMENSIONS (384) and the caller surfaces the dim-mismatch error
+   * at insert/search time.
+   */
+  async getEngineDimensions() {
+    if (this._engineDim != null) return this._engineDim;
+    try {
+      const info = await getEmbeddingModelInfo({ env: this.env });
+      this._engineDim = info.dimensions;
+    } catch {
+      this._engineDim = FALLBACK_DIMENSIONS;
+    }
+    return this._engineDim;
+  }
+
+  /**
+   * Read the actual declared dimensionality of `construct_embeddings.embedding`
+   * from `pg_attribute` and compare against the engine. Throws a precise
+   * error on mismatch. Returns the matched dimension on success.
+   */
+  async assertSchemaDimensions() {
+    const sql = await this._getSql();
+    if (!sql) throw new Error('No DATABASE_URL configured; cannot verify pgvector schema');
+    const engineDim = await this.getEngineDimensions();
+
+    const rows = await sql`
+      SELECT format_type(atttypid, atttypmod) AS pg_type
+      FROM pg_attribute
+      WHERE attrelid = 'construct_embeddings'::regclass
+        AND attname = 'embedding'
+        AND NOT attisdropped
+    `;
+    const declared = rows?.[0]?.pg_type || '';
+    const match = declared.match(/vector\((\d+)\)/);
+    if (!match) {
+      throw new Error(
+        `construct_embeddings.embedding column has unexpected type '${declared}'. ` +
+        `Recreate the column with 'ALTER TABLE construct_embeddings ALTER COLUMN embedding TYPE vector(${engineDim})' ` +
+        `(truncate first; vectors do not survive a dim change).`
+      );
+    }
+    const schemaDim = Number(match[1]);
+    if (schemaDim !== engineDim) {
+      throw new Error(
+        `pgvector dimension mismatch: schema declares vector(${schemaDim}) but engine model produces ${engineDim}d. ` +
+        `Either set CONSTRUCT_EMBEDDING_MODEL to a ${schemaDim}d model, or recreate the column with ` +
+        `'ALTER TABLE construct_embeddings ALTER COLUMN embedding TYPE vector(${engineDim})' (truncate first).`
+      );
+    }
+    return schemaDim;
+  }
+
+  /**
+   * Lazily load the `postgres` module and create the connection.
+   */
+  async _getSql() {
+    if (!this.url) return null;
+    if (this._sql) return this._sql;
+
+    if (!this._pgModule) {
+      try {
+        const m = await import('postgres');
+        this._pgModule = m.default || m;
+      } catch (err) {
+        // Re-throw with a clearer message so callers understand why
+        throw new Error(
+          `Failed to load 'postgres' module: ${err.message}. ` +
+          `Ensure 'postgres' is installed (npm install postgres).`
+        );
+      }
+    }
+
+    this._sql = this._pgModule(this.url, DEFAULT_POOL);
+    return this._sql;
+  }
+
+  /**
+   * Check if the SQL backend is available and healthy.
+   */
+  async isHealthy() {
+    const sql = await this._getSql();
+    if (!sql) return false;
+    try {
+      const result = await sql`SELECT 1 AS health`;
+      return result?.[0]?.health === 1;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Check if pgvector extension is enabled.
+   */
+  async isPgvectorEnabled() {
+    const sql = await this._getSql();
+    if (!sql) return false;
+    try {
+      const result = await sql`
+        SELECT EXISTS (
+          SELECT 1 FROM pg_extension WHERE extname = 'vector'
+        ) AS enabled
+      `;
+      return result?.[0]?.enabled === true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Store an observation with its embedding.
+   */
+  async storeObservation({ id, project, role, category, summary, content, tags, confidence, source, embedding, gitSha }) {
+    const sql = await this._getSql();
+    if (!sql) return { mode: 'file', reason: 'no_sql' };
+    const expected = await this.getEngineDimensions();
+    assertPgvectorDimensions(embedding, { expected, label: 'observation embedding' });
+
+    const embeddingVec = floatArrayToPgVector(embedding);
+    await sql`
+      INSERT INTO construct_observations (id, project, role, category, summary, content, tags, confidence, source, git_sha, embedding)
+      VALUES (${id}, ${project}, ${role}, ${category}, ${summary}, ${content}, ${JSON.stringify(tags || [])}, ${confidence || 0.8}, ${source || null}, ${gitSha || null}, ${embeddingVec})
+      ON CONFLICT (id) DO UPDATE SET
+        summary = EXCLUDED.summary,
+        content = EXCLUDED.content,
+        tags = EXCLUDED.tags,
+        confidence = EXCLUDED.confidence,
+        source = EXCLUDED.source,
+        git_sha = EXCLUDED.git_sha,
+        embedding = EXCLUDED.embedding,
+        updated_at = now()
+    `;
+    return { mode: 'sql', id };
+  }
+
+  /**
+   * Search observations by vector similarity.
+   */
+  async searchObservations({ project, queryEmbedding, limit = 10, minSimilarity = 0.3, role, category }) {
+    const sql = await this._getSql();
+    if (!sql) return [];
+    const expected = await this.getEngineDimensions();
+    assertPgvectorDimensions(queryEmbedding, { expected, label: 'observation query embedding' });
+
+    const queryVec = floatArrayToPgVector(queryEmbedding);
+    const conditions = [sql`project = ${project}`];
+    if (role) conditions.push(sql`role = ${role}`);
+    if (category) conditions.push(sql`category = ${category}`);
+    conditions.push(sql`1 - (embedding <=> ${queryVec}) > ${minSimilarity}`);
+
+    const results = await sql`
+      SELECT 
+        id, role, category, summary, content, tags, confidence, source, git_sha, created_at,
+        1 - (embedding <=> ${queryVec}) AS similarity
+      FROM construct_observations
+      WHERE ${sql.join(conditions, ' AND ')}
+      ORDER BY embedding <=> ${queryVec}
+      LIMIT ${limit}
+    `;
+    return results;
+  }
+
+  /**
+   * Store a document with its embedding.
+   */
+  async storeDocument({ id, project, kind, title, summary, body, sourcePath, tags, contentHash, embedding, model }) {
+    const sql = await this._getSql();
+    if (!sql) return { mode: 'file', reason: 'no_sql' };
+    const expected = await this.getEngineDimensions();
+    assertPgvectorDimensions(embedding, { expected, label: 'document embedding' });
+    if (!model) {
+      const info = await getEmbeddingModelInfo({ env: this.env });
+      model = info.model;
+    }
+
+    const embeddingVec = floatArrayToPgVector(embedding);
+    await sql`
+      INSERT INTO construct_documents (id, project, kind, title, summary, body, source_path, tags, content_hash)
+      VALUES (${id}, ${project}, ${kind}, ${title}, ${summary || ''}, ${body}, ${sourcePath || ''}, ${JSON.stringify(tags || [])}, ${contentHash || ''})
+      ON CONFLICT (id) DO UPDATE SET
+        title = EXCLUDED.title,
+        summary = EXCLUDED.summary,
+        body = EXCLUDED.body,
+        source_path = EXCLUDED.source_path,
+        tags = EXCLUDED.tags,
+        content_hash = EXCLUDED.content_hash,
+        updated_at = now()
+    `;
+
+    await sql`
+      INSERT INTO construct_embeddings (document_id, model, embedding, content_hash)
+      VALUES (${id}, ${model}, ${embeddingVec}, ${contentHash || ''})
+      ON CONFLICT (document_id) DO UPDATE SET
+        model = EXCLUDED.model,
+        embedding = EXCLUDED.embedding,
+        content_hash = EXCLUDED.content_hash,
+        updated_at = now()
+    `;
+    return { mode: 'sql', id };
+  }
+
+  /**
+   * Search documents by vector similarity.
+   */
+  async searchDocuments({ project, queryEmbedding, limit = 10, minSimilarity = 0.3 }) {
+    const sql = await this._getSql();
+    if (!sql) return [];
+    const expected = await this.getEngineDimensions();
+    assertPgvectorDimensions(queryEmbedding, { expected, label: 'document query embedding' });
+
+    const queryVec = floatArrayToPgVector(queryEmbedding);
+    const results = await sql`
+      SELECT 
+        d.id, d.title, d.summary, d.body, d.source_path, d.tags, d.kind,
+        1 - (e.embedding <=> ${queryVec}) AS similarity
+      FROM construct_documents d
+      JOIN construct_embeddings e ON d.id = e.document_id
+      WHERE d.project = ${project}
+        AND 1 - (e.embedding <=> ${queryVec}) > ${minSimilarity}
+      ORDER BY e.embedding <=> ${queryVec}
+      LIMIT ${limit}
+    `;
+    return results;
+  }
+
+  /**
+   * Close the connection pool.
+   */
+  async close() {
+    if (this._sql) {
+      await this._sql.end();
+      this._sql = null;
+    }
+  }
+}

package/lib/storage/vector-store.mjs

@@ -1,7 +1,19 @@
 #!/usr/bin/env node
 /**
- * lib/storage/vector-store.mjs — derived semantic retrieval facade.
+ * lib/storage/vector-store.mjs — Local JSON vector index facade.
+ *
+ * Stores vector records on disk for fallback retrieval when no SQL backend is
+ * available. The model field is metadata supplied by the caller — this module
+ * does not embed; it only persists what the engine produces.
+ *
+ * Search APIs accept a pre-computed query embedding so the embedding model is
+ * the caller's choice and there is no implicit dependency on a specific model
+ * inside this module.
  */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { scoreByEmbedding, rankByBm25 } from './embeddings.mjs';
+import { embedSync } from './embeddings-legacy.mjs';
 
 export function vectorStoreMode(env = process.env) {
   if (env.CONSTRUCT_VECTOR_URL) return 'remote';
@@ -22,38 +34,67 @@ export function describeVectorStore(env = process.env) {
   };
 }
 
-function normalizeTerms(input) {
-  return String(input || '')
-    .toLowerCase()
-    .split(/[^a-z0-9]+/)
-    .filter((term) => term.length >= 3);
-}
+export function readLocalVectorIndex(indexPath) {
+  const resolvedPath = resolve(String(indexPath || ''));
+  if (!resolvedPath || !existsSync(resolvedPath)) {
+    return { version: 1, model: null, updatedAt: null, records: [] };
+  }
 
-export function scoreSemanticText(text, query) {
-  const terms = normalizeTerms(query);
-  if (terms.length === 0) return 0;
-  const haystack = String(text || '').toLowerCase();
-  let score = 0;
-  for (const term of terms) {
-    if (haystack.includes(term)) score += 1;
+  try {
+    const parsed = JSON.parse(readFileSync(resolvedPath, 'utf8'));
+    return {
+      version: parsed.version ?? 1,
+      model: parsed.model || null,
+      updatedAt: parsed.updatedAt || null,
+      records: Array.isArray(parsed.records) ? parsed.records : [],
+    };
+  } catch {
+    return { version: 1, model: null, updatedAt: null, records: [] };
   }
-  return score;
+}
+
+export function writeLocalVectorIndex(indexPath, records = [], { model } = {}) {
+  const resolvedPath = resolve(String(indexPath || ''));
+  if (!resolvedPath) throw new Error('Missing local vector index path');
+  if (!model) throw new Error('writeLocalVectorIndex requires an explicit model id (caller must supply)');
+  mkdirSync(dirname(resolvedPath), { recursive: true });
+  const payload = {
+    version: 1,
+    model,
+    updatedAt: new Date().toISOString(),
+    records,
+  };
+  writeFileSync(resolvedPath, `${JSON.stringify(payload, null, 2)}\n`);
+  return payload;
+}
+
+/**
+ * Search the local vector index. Accepts either a query string (which is
+ * embedded via the legacy hashing adapter inline — fast, deterministic, no
+ * engine init) or a pre-computed query embedding for engine-aligned callers.
+ *
+ * The hashing path matches what `addObservation` and `syncFileStateToSql`
+ * write to disk when no SQL backend is configured, so dimensions agree.
+ * Callers that store engine-dim vectors should pass an explicit Float32Array.
+ */
+export function searchLocalVectorIndex(indexPath, query, { limit = 10 } = {}) {
+  const index = readLocalVectorIndex(indexPath);
+  const queryEmbedding = typeof query === 'string'
+    ? embedSync(query)
+    : (query instanceof Float32Array ? Array.from(query) : (query || []));
+  return scoreByEmbedding(index.records, queryEmbedding, { limit });
 }
 
 export function vectorSearchLocal(records = [], query = '', { limit = 10 } = {}) {
-  return records
-    .map((record) => ({
-      record,
-      score: scoreSemanticText([
-        record.title,
-        record.summary,
-        record.body,
-        record.text,
-        Array.isArray(record.tags) ? record.tags.join(' ') : '',
-      ].filter(Boolean).join('\n'), query),
-    }))
-    .filter(({ score }) => score > 0)
-    .sort((a, b) => b.score - a.score || String(a.record.id || '').localeCompare(String(b.record.id || '')))
-    .slice(0, limit)
-    .map(({ record, score }) => ({ ...record, score }));
+  const bm25Docs = records.map((record) => ({
+    ...record,
+    text: [
+      record.title,
+      record.summary,
+      record.body,
+      record.text,
+      Array.isArray(record.tags) ? record.tags.join(' ') : '',
+    ].filter(Boolean).join('\n'),
+  }));
+  return rankByBm25(bm25Docs, query, { limit });
 }

package/lib/task-graph/generate.mjs

@@ -0,0 +1,135 @@
+/**
+ * lib/task-graph/generate.mjs — derive a task graph from an R&D triage packet.
+ *
+ * The triage's recommendedChain is the workflow template: one node per
+ * persona in the chain, with depends_on edges linking each node to its
+ * predecessor. Node types align with rdStage (implementation, design,
+ * evaluation, …). Acceptance criteria are seeded from the triage stage;
+ * verification requirements ride alongside the workflow contract.
+ */
+
+let counter = 0;
+function uniqueSuffix() {
+  counter = (counter + 1) % 1000;
+  return String(counter).padStart(3, '0');
+}
+
+function timestamp() {
+  return `${new Date().toISOString().replace(/[:.]/g, '-').slice(0, 23)}-${uniqueSuffix()}`;
+}
+
+const NODE_TYPE_BY_STAGE = {
+  signal: 'framing',
+  framing: 'framing',
+  hypothesis: 'hypothesis',
+  research: 'research',
+  artifact: 'design',
+  design: 'design',
+  implementation: 'implementation',
+  evaluation: 'evaluation',
+  release: 'release',
+  operations: 'runbook',
+  unknown: 'framing',
+};
+
+const OWNER_NODE_TYPE_OVERRIDE = {
+  qa: 'verification',
+  reviewer: 'review',
+  evaluator: 'evaluation',
+  'trace-reviewer': 'evaluation',
+  debugger: 'diagnosis',
+  'docs-keeper': 'release',
+  'legal-compliance': 'compliance-review',
+  security: 'review',
+};
+
+const ACCEPTANCE_BY_STAGE = {
+  framing: ['problem statement is explicit', 'success metric named', 'scope boundaries documented'],
+  hypothesis: ['hypothesis is falsifiable', 'success / failure threshold named', 'evaluation method chosen'],
+  research: ['three or more sources cited', 'date coverage stated', 'claim → source mapping recorded'],
+  design: ['interface contract documented', 'tradeoffs called out', 'reversibility note attached'],
+  implementation: ['tests pass locally', 'lint clean', 'diff scoped to the change'],
+  evaluation: ['baseline metric recorded', 'failure cases enumerated', 'regression criterion explicit'],
+  release: ['changelog entry drafted', 'docs cross-checked', 'rollback path stated'],
+  operations: ['runbook step list complete', 'on-call notified', 'monitoring confirmed'],
+  unknown: ['define acceptance criteria for this work'],
+};
+
+const VERIFICATION_BY_STAGE = {
+  implementation: ['npm test', 'lint:comments'],
+  evaluation: ['construct evals retrieval'],
+  release: ['release:check'],
+  operations: ['service health probe'],
+};
+
+function pickNodeType({ owner, rdStage }) {
+  if (OWNER_NODE_TYPE_OVERRIDE[owner]) return OWNER_NODE_TYPE_OVERRIDE[owner];
+  return NODE_TYPE_BY_STAGE[rdStage] || 'framing';
+}
+
+function pickNodeTitle({ owner, recommendedAction, request }) {
+  const action = recommendedAction || 'work';
+  const shortRequest = (request || '').trim().slice(0, 80);
+  return shortRequest
+    ? `${owner}: ${action} — ${shortRequest}`
+    : `${owner}: ${action}`;
+}
+
+/**
+ * Produce a task graph from a triage packet.
+ *
+ * @param {object} opts
+ * @param {object} opts.triage — output of classifyRdIntake
+ * @param {string} [opts.project]
+ * @param {string} [opts.request] — original signal text, used for node titles
+ * @param {object} [opts.intake] — intake metadata, persisted on node 1 for traceability
+ * @returns {{ id, project, createdAt, triage, intake, nodes, edges, verificationRequirements }}
+ */
+export function generateTaskGraphFromTriage({ triage, project = 'construct', request = '', intake = null } = {}) {
+  if (!triage) throw new Error('generateTaskGraphFromTriage: triage is required');
+  const chain = Array.isArray(triage.recommendedChain) && triage.recommendedChain.length > 0
+    ? triage.recommendedChain
+    : [triage.primaryOwner || 'orchestrator'];
+
+  const ts = timestamp();
+  const graphId = `task-graph-${ts}`;
+  const createdAt = new Date().toISOString();
+
+  const nodes = chain.map((owner, idx) => {
+    const nodeId = `${graphId}-${String(idx + 1).padStart(2, '0')}-${owner}`;
+    const dependsOn = idx === 0 ? [] : [`${graphId}-${String(idx).padStart(2, '0')}-${chain[idx - 1]}`];
+    return {
+      id: nodeId,
+      project,
+      title: pickNodeTitle({ owner, recommendedAction: triage.recommendedAction, request }),
+      type: pickNodeType({ owner, rdStage: triage.rdStage }),
+      owner,
+      status: 'pending',
+      dependsOn,
+      inputs: idx === 0 && intake ? [{ kind: 'intake', sourcePath: intake.sourcePath }] : [],
+      outputs: [],
+      acceptanceCriteria: ACCEPTANCE_BY_STAGE[triage.rdStage] || ACCEPTANCE_BY_STAGE.unknown,
+      evidence: [],
+      risk: triage.risk || 'low',
+      createdAt,
+      updatedAt: createdAt,
+    };
+  });
+
+  const edges = [];
+  for (let i = 1; i < nodes.length; i++) {
+    edges.push({ from: nodes[i - 1].id, to: nodes[i].id, type: 'handoff_to' });
+    edges.push({ from: nodes[i].id, to: nodes[i - 1].id, type: 'depends_on' });
+  }
+
+  return {
+    id: graphId,
+    project,
+    createdAt,
+    triage,
+    intake,
+    nodes,
+    edges,
+    verificationRequirements: VERIFICATION_BY_STAGE[triage.rdStage] || [],
+  };
+}

package/lib/task-graph/schema.mjs

@@ -0,0 +1,81 @@
+/**
+ * lib/task-graph/schema.mjs — task graph node + edge schema and validation.
+ *
+ * A task graph is the deterministic plan-of-work derived from an R&D
+ * intake triage. Each node represents a unit of work owned by a persona;
+ * edges encode ordering (depends_on, blocks, handoff_to), validation
+ * (validates), and history (supersedes, derived_from).
+ *
+ * Node schema:
+ *   {
+ *     id, project, title, type, owner, status,
+ *     dependsOn[], inputs[], outputs[], acceptanceCriteria[],
+ *     evidence[], risk, createdAt, updatedAt
+ *   }
+ *
+ * Status moves through: pending → claimed → in-progress → done | blocked |
+ * needs-input | skipped. Evidence is appended as each verification step
+ * produces output (see PR 8 worker sandbox).
+ */
+
+export const EDGE_TYPES = ['depends_on', 'blocks', 'handoff_to', 'validates', 'supersedes', 'derived_from'];
+
+export const NODE_STATUSES = ['pending', 'claimed', 'in-progress', 'done', 'blocked', 'needs-input', 'skipped'];
+
+export const NODE_TYPES = [
+  'diagnosis',
+  'implementation',
+  'verification',
+  'review',
+  'research',
+  'framing',
+  'design',
+  'hypothesis',
+  'evaluation',
+  'release',
+  'runbook',
+  'compliance-review',
+];
+
+export function isValidStatus(status) {
+  return NODE_STATUSES.includes(status);
+}
+
+export function isValidEdgeType(type) {
+  return EDGE_TYPES.includes(type);
+}
+
+const REQUIRED_NODE_FIELDS = ['id', 'project', 'title', 'type', 'owner', 'status'];
+
+export function validateNode(node) {
+  const errors = [];
+  if (!node || typeof node !== 'object') {
+    errors.push('node must be an object');
+    return errors;
+  }
+  for (const field of REQUIRED_NODE_FIELDS) {
+    if (!node[field]) errors.push(`missing required field: ${field}`);
+  }
+  if (node.status && !isValidStatus(node.status)) errors.push(`invalid status: ${node.status}`);
+  if (node.dependsOn && !Array.isArray(node.dependsOn)) errors.push('dependsOn must be an array');
+  return errors;
+}
+
+export function validateGraph(graph) {
+  const errors = [];
+  if (!graph?.id) errors.push('graph.id is required');
+  if (!Array.isArray(graph?.nodes) || graph.nodes.length === 0) errors.push('graph.nodes must be a non-empty array');
+  const ids = new Set();
+  for (const node of graph?.nodes || []) {
+    const nodeErrors = validateNode(node);
+    for (const err of nodeErrors) errors.push(`node ${node?.id || '(unknown)'}: ${err}`);
+    if (ids.has(node?.id)) errors.push(`duplicate node id: ${node.id}`);
+    ids.add(node?.id);
+  }
+  for (const node of graph?.nodes || []) {
+    for (const dep of node.dependsOn || []) {
+      if (!ids.has(dep)) errors.push(`node ${node.id}: dependsOn references unknown node ${dep}`);
+    }
+  }
+  return errors;
+}

package/lib/task-graph/store.mjs

@@ -0,0 +1,71 @@
+/**
+ * lib/task-graph/store.mjs — task graph persistence (filesystem adapter).
+ *
+ * Stores generated graphs under `.cx/task-graphs/<graph-id>.json`. The
+ * shape mirrors the in-memory graph from generate.mjs end-to-end so a
+ * graph round-trips without lossy field handling. team / enterprise mode
+ * will add a Postgres adapter alongside this; both implement the same
+ * read / write surface.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+const STORE_SUBDIR = '.cx/task-graphs';
+
+export function storeDir(rootDir) {
+  return path.join(rootDir, STORE_SUBDIR);
+}
+
+export class FilesystemTaskGraphStore {
+  constructor(rootDir) {
+    if (!rootDir) throw new Error('FilesystemTaskGraphStore: rootDir is required');
+    this.rootDir = rootDir;
+  }
+
+  save(graph) {
+    if (!graph?.id) throw new Error('save: graph.id is required');
+    const dir = storeDir(this.rootDir);
+    mkdirSync(dir, { recursive: true });
+    const filePath = path.join(dir, `${graph.id}.json`);
+    writeFileSync(filePath, JSON.stringify(graph, null, 2) + '\n', 'utf8');
+    return { id: graph.id, filePath };
+  }
+
+  read(id) {
+    const filePath = path.join(storeDir(this.rootDir), `${id}.json`);
+    if (!existsSync(filePath)) return null;
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  }
+
+  list() {
+    const dir = storeDir(this.rootDir);
+    if (!existsSync(dir)) return [];
+    return readdirSync(dir)
+      .filter((name) => name.endsWith('.json'))
+      .map((name) => path.join(dir, name))
+      .map((filePath) => {
+        try {
+          return JSON.parse(readFileSync(filePath, 'utf8'));
+        } catch {
+          return null;
+        }
+      })
+      .filter(Boolean)
+      .sort((a, b) => (a.createdAt || '').localeCompare(b.createdAt || ''));
+  }
+
+  updateNodeStatus(graphId, nodeId, status, patch = {}) {
+    const graph = this.read(graphId);
+    if (!graph) throw new Error(`updateNodeStatus: graph ${graphId} not found`);
+    const node = graph.nodes.find((n) => n.id === nodeId);
+    if (!node) throw new Error(`updateNodeStatus: node ${nodeId} not found in ${graphId}`);
+    if (status !== undefined) node.status = status;
+    node.updatedAt = new Date().toISOString();
+    if (patch.addEvidence) {
+      node.evidence = [...(node.evidence || []), patch.addEvidence];
+    }
+    this.save(graph);
+    return node;
+  }
+}