@cgh567/agent 2.4.2 → 2.4.4

package/daemon/routes/project.js

@@ -107,35 +107,63 @@ function startSseKeepAlive(res) {
 
 // ── Route factory ─────────────────────────────────────────────────────────────
 
-module.exports = function createProjectRoute({ mgQuery, broadcast, invalidateContextCache, semanticUpdater, driftDetector } = {}) {
+module.exports = function createProjectRoute({ mgQuery, broadcast, invalidateContextCache, semanticUpdater, driftDetector, hboStore } = {}) {
 
   // ── POST /api/project ─────────────────────────────────────────────────────
   async function handleCreate(req, res, ctx) {
     const body = await readBody(req);
     if (!assertBody(body, res, req)) return;
     // D3: ctx.cid is authoritative - prevents cross-company project injection
-    const { pillarId, goalId, name } = body;
+    // P3-02: pillarId and goalId are now optional (defaults to null) so desktop
+    // users without Harada pillars can still create projects.
+    const { name } = body;
+    const pillarId  = body.pillarId  ? String(body.pillarId)  : null;
+    const goalId    = body.goalId    ? String(body.goalId)    : null;
     const companyId = ctx?.cid || body?.companyId || '';
-    if (!companyId || !pillarId || !goalId || !name) {
-      return jsonErr(res, 400, 'companyId, pillarId, goalId, name required', req);
+    if (!companyId || !name) {
+      return jsonErr(res, 400, 'companyId and name are required', req);
     }
     try {
-      const slug   = pillarId.replace(/[^a-z0-9]/gi, '-').toLowerCase().slice(0, 40);
-      const projId = `proj:${companyId}:${slug}`;
+      // projId is deterministic: use caller-supplied id (H-3: preserves desktop ID for reconciliation),
+      // then pillarId-slug, then UUID slug (P3-02: pillarId optional)
+      const slug   = pillarId
+        ? pillarId.replace(/[^a-z0-9]/gi, '-').toLowerCase().slice(0, 40)
+        : randomUUID().slice(0, 8);
+      const projId = body.id ? String(body.id) : `proj:${companyId}:${slug}`;
       const docId  = `pdoc:${projId}:main`;
-      await mgQuery(
-        `MERGE (p:HeliosProject {id: $projId})
-         ON CREATE SET p.companyId=$cid, p.goalId=$goalId, p.pillarId=$pillarId,
-           p.name=$name, p.status='planning', p.phase='planning', p.createdAt=datetime()`,
-        { projId, cid: companyId, goalId, pillarId, name }
-      );
-      await mgQuery(
-        `MERGE (d:ProjectDocument {id: $docId})
-         ON CREATE SET d.projectId=$projId, d.purpose='', d.approach='',
-           d.successCriteria='[]', d.intentAnchor='', d.exclusions='[]',
-           d.content='', d.version=toInteger(1), d.updatedAt=datetime()`,
-        { docId, projId }
-      );
+      if (mgQuery) {
+        await mgQuery(
+          `MERGE (p:HeliosProject {id: $projId})
+           ON CREATE SET p.companyId=$cid, p.goalId=$goalId, p.pillarId=$pillarId,
+             p.name=$name, p.status='planning', p.phase='planning', p.createdAt=datetime()`,
+          { projId, cid: companyId, goalId, pillarId, name }
+        );
+        // H-1 fix: SQLite write-through happens HERE (after first Memgraph write succeeds)
+        // so it executes even if the second Memgraph write (ProjectDocument) fails
+        if (hboStore?.upsertProject) {
+          try {
+            hboStore.upsertProject({ id: projId, companyId, name, pillarId, goalId, status: 'planning', phase: 'planning', createdAt: new Date().toISOString(), updated_at: Date.now() });
+          } catch (storeErr) {
+            process.stderr.write(`[project] hboStore.upsertProject failed (non-fatal): ${storeErr.message}\n`);
+          }
+        }
+        await mgQuery(
+          `MERGE (d:ProjectDocument {id: $docId})
+           ON CREATE SET d.projectId=$projId, d.purpose='', d.approach='',
+             d.successCriteria='[]', d.intentAnchor='', d.exclusions='[]',
+             d.content='', d.version=toInteger(1), d.updatedAt=datetime()`,
+          { docId, projId }
+        );
+      } else {
+        // Memgraph unavailable — write to SQLite only (C-2 / SQL-parity invariant)
+        if (hboStore?.upsertProject) {
+          try {
+            hboStore.upsertProject({ id: projId, companyId, name, pillarId, goalId, status: 'planning', phase: 'planning', createdAt: new Date().toISOString(), updated_at: Date.now() });
+          } catch (storeErr) {
+            process.stderr.write(`[project] hboStore.upsertProject (offline) failed (non-fatal): ${storeErr.message}\n`);
+          }
+        }
+      }
       jsonOk(res, { ok: true, projectId: projId }, req, 201);
     } catch (e) {
       jsonErr(res, 500, safeMsg(e), req);
@@ -148,41 +176,98 @@ module.exports = function createProjectRoute({ mgQuery, broadcast, invalidateCon
     const cid    = url.searchParams.get('companyId') || ctx?.cid || '';
     const pillar = url.searchParams.get('pillarId') || '';
     const status = url.searchParams.get('status') || '';
+    // P3-SQL: try Memgraph first; fall back to SQLite when unavailable
+    if (mgQuery) {
+      try {
+        let cypher = `MATCH (p:HeliosProject)`;
+        const params = {};
+        const where = [];
+        if (cid)    { where.push('p.companyId = $cid');    params.cid = cid; }
+        if (pillar) { where.push('p.pillarId  = $pillar'); params.pillar = pillar; }
+        if (status) { where.push('p.status    = $status'); params.status = status; }
+        if (where.length) cypher += ` WHERE ${where.join(' AND ')}`;
+        cypher += ` RETURN p.id, p.name, p.phase, p.status, p.pillarId, p.goalId, p.createdAt ORDER BY p.createdAt DESC LIMIT 100`;
+        const result = await mgQuery(cypher, params);
+        const keys = ['id','name','phase','status','pillarId','goalId','createdAt'];
+        const projects = parseRows(result).map(r => rowToObj(r, keys));
+        return jsonOk(res, { projects, count: projects.length }, req);
+      } catch (e) {
+        process.stderr.write(`[project] handleList Memgraph failed, falling back to SQLite: ${e.message}\n`);
+      }
+    }
+    // SQLite fallback
     try {
-      let cypher = `MATCH (p:HeliosProject)`;
-      const params = {};
-      const where = [];
-      if (cid)    { where.push('p.companyId = $cid');    params.cid = cid; }
-      if (pillar) { where.push('p.pillarId  = $pillar'); params.pillar = pillar; }
-      if (status) { where.push('p.status    = $status'); params.status = status; }
-      if (where.length) cypher += ` WHERE ${where.join(' AND ')}`;
-      cypher += ` RETURN p.id, p.name, p.phase, p.status, p.pillarId, p.goalId, p.createdAt ORDER BY p.createdAt DESC LIMIT 100`;
-      const result = await mgQuery(cypher, params);
-      const keys = ['id','name','phase','status','pillarId','goalId','createdAt'];
-      const projects = parseRows(result).map(r => rowToObj(r, keys));
-      jsonOk(res, { projects, count: projects.length }, req);
-    } catch (e) {
-      jsonErr(res, 500, safeMsg(e), req);
+      const all = hboStore?.getProjectsByCompany ? hboStore.getProjectsByCompany(cid) : [];
+      let projects = all || [];
+      if (pillar) projects = projects.filter(p => p.pillarId === pillar);
+      if (status) projects = projects.filter(p => p.status === status);
+      return jsonOk(res, { projects, count: projects.length, _source: 'sqlite' }, req);
+    } catch (storeErr) {
+      return jsonErr(res, 503, `Projects unavailable: Memgraph not connected and SQLite fallback failed: ${storeErr.message}`, req);
     }
   }
 
   // ── GET /api/project/:id ──────────────────────────────────────────────────
   async function handleGet(req, res, ctx, projectId) {
+    // P3-SQL: Memgraph-first, SQLite fallback
+    if (mgQuery) {
+      try {
+        const projRes = await mgQuery(
+          `MATCH (p:HeliosProject {id: $id, companyId: $cid})
+           OPTIONAL MATCH (d:ProjectDocument {projectId: p.id})
+           RETURN p.id, p.name, p.phase, p.status, p.pillarId, p.goalId, p.createdAt,
+                  d.purpose, d.approach, d.successCriteria, d.intentAnchor, d.exclusions, d.version, d.updatedAt, d.content`,
+          { id: projectId, cid: ctx.cid || ctx?.cid || '' }
+        );
+        const row = parseRows(projRes)[0];
+        if (!row) return jsonErr(res, 404, 'Project not found', req);
+        const keys = ['id','name','phase','status','pillarId','goalId','createdAt','purpose','approach','successCriteria','intentAnchor','exclusions','version','updatedAt','content'];
+        const proj = rowToObj(row, keys);
+        // P3-02: fetch standardWorkDocuments, questions, linkedTasks as supplemental arrays
+        const cid = ctx.cid || ctx?.cid || '';
+        const [swdRes, qRes, ltRes] = await Promise.all([
+          mgQuery(`MATCH (s:StandardWorkDocument {projectId: $id, companyId: $cid}) RETURN s.id, s.title, s.content, s.section, s.updatedAt`, { id: projectId, cid }).catch(() => null),
+          mgQuery(`MATCH (q:ProjectQuestion {projectId: $id, companyId: $cid}) RETURN q.id, q.question, q.answer, q.askedBy, q.createdAt`, { id: projectId, cid }).catch(() => null),
+          mgQuery(`MATCH (t:Task {companyId: $cid}) WHERE t.projectId = $id OR (t)-[:BELONGS_TO_PROJECT]->(:HeliosProject {id: $id}) RETURN t.id, t.title, t.status, t.assigneeAgentId`, { id: projectId, cid }).catch(() => null),
+        ]);
+        const swdKeys = ['id','title','content','section','updatedAt'];
+        const qKeys   = ['id','question','answer','askedBy','createdAt'];
+        const ltKeys  = ['id','title','status','assigneeAgentId'];
+        proj.standardWorkDocuments = parseRows(swdRes).map(r => rowToObj(r, swdKeys));
+        proj.questions              = parseRows(qRes).map(r => rowToObj(r, qKeys));
+        proj.linkedTasks            = parseRows(ltRes).map(r => rowToObj(r, ltKeys));
+        return jsonOk(res, proj, req);
+      } catch (e) {
+        process.stderr.write(`[project] handleGet Memgraph failed, falling back to SQLite: ${e.message}\n`);
+      }
+    }
+    // SQLite fallback
     try {
-      // D1: Add companyId to prevent cross-company project exfiltration
-      const projRes = await mgQuery(
-        `MATCH (p:HeliosProject {id: $id, companyId: $cid})
-         OPTIONAL MATCH (d:ProjectDocument {projectId: p.id})
-         RETURN p.id, p.name, p.phase, p.status, p.pillarId, p.goalId, p.createdAt,
-                d.purpose, d.approach, d.successCriteria, d.intentAnchor, d.exclusions, d.version, d.updatedAt, d.content`,
-        { id: projectId, cid: ctx.cid || ctx?.cid || '' }
-      );
-      const row = parseRows(projRes)[0];
-      if (!row) return jsonErr(res, 404, 'Project not found', req);
-      const keys = ['id','name','phase','status','pillarId','goalId','createdAt','purpose','approach','successCriteria','intentAnchor','exclusions','version','updatedAt','content'];
-      jsonOk(res, rowToObj(row, keys), req);
-    } catch (e) {
-      jsonErr(res, 500, safeMsg(e), req);
+      const p = hboStore?.getProject ? hboStore.getProject(projectId, ctx?.cid || '') : null;
+      if (!p) return jsonErr(res, 404, 'Project not found', req);
+      // M-2 fix: normalize response shape to match Memgraph path exactly
+      const doc = hboStore?.getProjectDocument ? hboStore.getProjectDocument(projectId) : null;
+      const createdAtMs = typeof p.created_at === 'number' ? p.created_at : (p.createdAt ? new Date(p.createdAt).getTime() : null);
+      return jsonOk(res, {
+        id: p.id,
+        name: p.name ?? null,
+        phase: p.phase ?? 'planning',
+        status: p.status ?? 'planning',
+        pillarId: p.pillarId ?? p.pillar_id ?? null,
+        goalId: p.goalId ?? p.goal_id ?? null,
+        createdAt: createdAtMs ? new Date(createdAtMs).toISOString() : null,
+        purpose: doc?.purpose ?? null,
+        approach: doc?.approach ?? null,
+        successCriteria: doc?.success_criteria ?? doc?.successCriteria ?? '[]',
+        intentAnchor: doc?.intent_anchor ?? doc?.intentAnchor ?? null,
+        exclusions: doc?.exclusions ?? '[]',
+        version: doc?.version ?? 1,
+        updatedAt: doc?.updated_at ? new Date(doc.updated_at).toISOString() : null,
+        content: doc?.content ?? null,
+        _source: 'sqlite',
+      }, req);
+    } catch (storeErr) {
+      return jsonErr(res, 503, `Project unavailable: ${storeErr.message}`, req);
     }
   }
 
@@ -202,6 +287,26 @@ module.exports = function createProjectRoute({ mgQuery, broadcast, invalidateCon
       const docId     = `pdoc:${projectId}:main`;
       const companyId  = bodyCompanyId || ctx?.cid || projectId.split(':')[1] || 'unknown';
 
+      // C-2 fix: SQLite-only path when Memgraph unavailable
+      if (!mgQuery) {
+        if (hboStore?.upsertProjectDocument) {
+          try {
+            const existing = hboStore.getProjectDocument ? hboStore.getProjectDocument(projectId) : null;
+            const update = {
+              id: docId, project_id: projectId, company_id: companyId,
+              ...(existing ? { purpose: existing.purpose, approach: existing.approach, intent_anchor: existing.intent_anchor, success_criteria: existing.success_criteria, exclusions: existing.exclusions, content: existing.content, version: existing.version ?? 1 } : {}),
+              [section === 'intentAnchor' ? 'intent_anchor' : section === 'successCriteria' ? 'success_criteria' : section]: String(value),
+              version: ((existing?.version ?? 0) + 1),
+              updated_at: Date.now(),
+            };
+            hboStore.upsertProjectDocument(update);
+          } catch (storeErr) {
+            process.stderr.write(`[project] hboStore.upsertProjectDocument (offline) failed: ${storeErr.message}\n`);
+          }
+        }
+        return jsonOk(res, { ok: true, section, _source: 'sqlite' }, req, 200);
+      }
+
       // ── content section: persist block tree + back-extract semantic fields ──
       // When the editor saves the full BlockNote block array, we:
       //   1. Store it as d.content (JSON string) — source of truth for the editor
@@ -260,6 +365,12 @@ module.exports = function createProjectRoute({ mgQuery, broadcast, invalidateCon
           { docId, content: String(value), purpose, approach, intentAnchor }
         );
         if (invalidateContextCache) invalidateContextCache(projectId);
+        // C-2: SQLite write-through for content section
+        if (hboStore?.upsertProjectDocument) {
+          try {
+            hboStore.upsertProjectDocument({ id: docId, project_id: projectId, company_id: companyId, content: String(value), purpose, approach, intent_anchor: intentAnchor, updated_at: Date.now() });
+          } catch (storeErr) { process.stderr.write(`[project] content write-through failed: ${storeErr.message}\n`); }
+        }
         return jsonOk(res, { ok: true, section: 'content' }, req, 200);
       }
 
@@ -296,6 +407,21 @@ module.exports = function createProjectRoute({ mgQuery, broadcast, invalidateCon
       // proposalId: internal LLM analysis task ID
       jsonOk(res, { ok: true, pduId, proposalId, message: 'Analyzing edit — check back shortly' }, req, 202);
 
+      // C-2: SQLite write-through for proposal/semantic edit sections
+      if (hboStore?.upsertProjectDocument) {
+        try {
+          const existing = hboStore.getProjectDocument ? hboStore.getProjectDocument(projectId) : null;
+          const colKey = section === 'intentAnchor' ? 'intent_anchor' : section === 'successCriteria' ? 'success_criteria' : section;
+          hboStore.upsertProjectDocument({
+            id: docId, project_id: projectId, company_id: companyId,
+            ...(existing ? { purpose: existing.purpose, approach: existing.approach, intent_anchor: existing.intent_anchor, success_criteria: existing.success_criteria, exclusions: existing.exclusions, content: existing.content, version: existing.version ?? 1 } : {}),
+            [colKey]: String(value),
+            version: ((existing?.version ?? 0) + 1),
+            updated_at: Date.now(),
+          });
+        } catch (storeErr) { process.stderr.write(`[project] proposal write-through failed: ${storeErr.message}\n`); }
+      }
+
       // Trigger semantic analysis asynchronously (non-blocking)
       if (semanticUpdater) {
         setImmediate(async () => {
@@ -374,11 +500,26 @@ module.exports = function createProjectRoute({ mgQuery, broadcast, invalidateCon
   async function handleConfirmUnderstanding(req, res, ctx, projectId) {
     const body = await readBody(req);
     if (!assertBody(body, res, req)) return;
-    const { proposalId, confirmed, correctionNote } = body;
-    if (!proposalId || confirmed === undefined) {
-      return jsonErr(res, 400, 'proposalId and confirmed required', req);
+    // Accept both pduId (desktop sends this) and proposalId (legacy) to fix the
+    // pduId/proposalId mismatch. When pduId is supplied, resolve proposalId from the
+    // PendingDocumentUpdate node so the daemon handler always has the correct proposalId.
+    let { proposalId, pduId, confirmed, correctionNote } = body;
+    if (!proposalId && !pduId) {
+      return jsonErr(res, 400, 'pduId or proposalId required', req);
     }
+    if (confirmed === undefined) return jsonErr(res, 400, 'confirmed required', req);
     try {
+      // Resolve proposalId from pduId if only pduId was provided
+      if (!proposalId && pduId) {
+        const pduRes = await mgQuery(
+          `MATCH (u:PendingDocumentUpdate {id: $pduId}) RETURN u.proposalId`,
+          { pduId }
+        );
+        const pduRow = parseRows(pduRes)[0];
+        proposalId = pduRow ? (pduRow[0] ?? pduRow['proposalId']) : null;
+        if (!proposalId) return jsonErr(res, 404, 'PendingDocumentUpdate not found for pduId', req);
+      }
+
       await mgQuery(
         `MATCH (pcp:PlanChangeProposal {id: $proposalId, targetId: $projId})
          SET pcp.confirmedAt=datetime(),
@@ -403,7 +544,7 @@ module.exports = function createProjectRoute({ mgQuery, broadcast, invalidateCon
               `MATCH (pcp:PlanChangeProposal {id: $proposalId}) SET pcp.impact=$impact, pcp.status='impact_ready'`,
               { proposalId, impact: JSON.stringify(impact) }
             ).catch(() => {});
-            broadcast({ type: 'project:impact:ready', payload: { projectId, proposalId, impact }, companyId: ctx?.cid || '' });
+            broadcast({ type: 'project:impact:ready', payload: { projectId, proposalId, pduId, impact }, companyId: ctx?.cid || '' });
           } catch (_) {}
         });
       }
@@ -418,10 +559,22 @@ module.exports = function createProjectRoute({ mgQuery, broadcast, invalidateCon
   async function handleApplyUpdate(req, res, ctx, projectId) {
     const body = await readBody(req);
     if (!assertBody(body, res, req)) return;
-    const { proposalId } = body;
-    if (!proposalId) return jsonErr(res, 400, 'proposalId required', req);
-    if (!projectId)  return jsonErr(res, 400, 'projectId required for project-scope proposals', req);
+    // Accept both pduId (desktop sends this) and proposalId (legacy) — same fix as confirm.
+    let { proposalId, pduId } = body;
+    if (!proposalId && !pduId) return jsonErr(res, 400, 'pduId or proposalId required', req);
+    if (!projectId) return jsonErr(res, 400, 'projectId required for project-scope proposals', req);
     try {
+      // Resolve proposalId from pduId if only pduId was provided
+      if (!proposalId && pduId) {
+        const pduRes = await mgQuery(
+          `MATCH (u:PendingDocumentUpdate {id: $pduId}) RETURN u.proposalId`,
+          { pduId }
+        );
+        const pduRow = parseRows(pduRes)[0];
+        proposalId = pduRow ? (pduRow[0] ?? pduRow['proposalId']) : null;
+        if (!proposalId) return jsonErr(res, 404, 'PendingDocumentUpdate not found for pduId', req);
+      }
+
       const pcpRes = await mgQuery(
         `MATCH (pcp:PlanChangeProposal {id: $proposalId, targetId: $projId})
          RETURN pcp.section, pcp.proposedChange`,
@@ -480,21 +633,34 @@ module.exports = function createProjectRoute({ mgQuery, broadcast, invalidateCon
 
   // ── GET /api/project/:id/state ────────────────────────────────────────────
   async function handleGetState(req, res, ctx, projectId) {
+    // C-1 fix: guard against Memgraph unavailability — return zero-state from SQLite
+    if (!mgQuery) {
+      try {
+        const p = hboStore?.getProject ? hboStore.getProject(projectId, ctx?.cid || '') : null;
+        const currentPhase = p?.phase ?? p?.status ?? 'planning';
+        return jsonOk(res, { totalCells: 0, closedCells: 0, activeTasks: 0, openDriftSignals: 0, currentPhase, hillProgress: 0, _source: 'sqlite' }, req);
+      } catch (storeErr) {
+        return jsonOk(res, { totalCells: 0, closedCells: 0, activeTasks: 0, openDriftSignals: 0, currentPhase: 'planning', hillProgress: 0, _source: 'sqlite' }, req);
+      }
+    }
     try {
       const [cellRes, taskRes, driftRes, docRes] = await Promise.all([
         mgQuery(
+          // P3-05: OPTIONAL MATCH so projects without GoalPillars return hillProgress:0 not an error
+          // H-6 fix: WHERE gp IS NOT NULL prevents null pillarId matching unrelated ActionCells
           `MATCH (p:HeliosProject {id: $id})
-           MATCH (gp:GoalPillar {id: p.pillarId})
-           MATCH (cell:ActionCell {pillarId: gp.id}) RETURN count(cell) AS total,
+           OPTIONAL MATCH (gp:GoalPillar {id: p.pillarId})
+           OPTIONAL MATCH (cell:ActionCell) WHERE cell.pillarId = gp.id AND gp IS NOT NULL
+           RETURN count(cell) AS total,
            count(CASE WHEN cell.status='closed' THEN 1 END) AS closed`,
-          { id: projectId, cid: ctx.cid || ctx?.cid || '' }
+          { id: projectId }
         ).catch(() => null),
         mgQuery(
           `MATCH (p:HeliosProject {id: $id})
            MATCH (t:Task {companyId: p.companyId}) WHERE t.task_metadata CONTAINS p.pillarId
              AND t.status IN ['todo','in_progress']
            RETURN count(t) AS active`,
-          { id: projectId, cid: ctx.cid || ctx?.cid || '' }
+          { id: projectId }
         ).catch(() => null),
         mgQuery(
           `MATCH (sig:AnomalySignal) WHERE sig.id STARTS WITH $prefix AND sig.status='open'
@@ -503,7 +669,7 @@ module.exports = function createProjectRoute({ mgQuery, broadcast, invalidateCon
         ).catch(() => null),
         mgQuery(
           `MATCH (p:HeliosProject {id: $id}) RETURN p.phase`,
-          { id: projectId, cid: ctx.cid || ctx?.cid || '' }
+          { id: projectId }
         ).catch(() => null),
       ]);
 
@@ -512,16 +678,22 @@ module.exports = function createProjectRoute({ mgQuery, broadcast, invalidateCon
       const driftRow = parseRows(driftRes)[0];
       const docRow   = parseRows(docRes)[0];
 
-      const totalCells      = Number(cellRow?.[0] ?? cellRow?.['total']      ?? 0);
-      const closedCells     = Number(cellRow?.[1] ?? cellRow?.['closed']     ?? 0);
-      const activeTasks     = Number(taskRow?.[0] ?? taskRow?.['active']     ?? 0);
-      const openDriftSignals = Number(driftRow?.[0] ?? driftRow?.['open']    ?? 0);
-      const currentPhase    = docRow?.[0] ?? docRow?.['phase']               ?? 'planning';
-      const hillProgress    = totalCells > 0 ? Math.round((closedCells / totalCells) * 100) : 0;
+      const totalCells       = Number(cellRow?.[0] ?? cellRow?.['total']       ?? 0);
+      const closedCells      = Number(cellRow?.[1] ?? cellRow?.['closed']      ?? 0);
+      const activeTasks      = Number(taskRow?.[0] ?? taskRow?.['active']      ?? 0);
+      const openDriftSignals = Number(driftRow?.[0] ?? driftRow?.['open']      ?? 0);
+      const currentPhase     = docRow?.[0]  ?? docRow?.['phase']               ?? 'planning';
+      const hillProgress     = totalCells > 0 ? Math.round((closedCells / totalCells) * 100) : 0;
 
       jsonOk(res, { totalCells, closedCells, activeTasks, openDriftSignals, currentPhase, hillProgress }, req);
     } catch (e) {
-      jsonErr(res, 500, safeMsg(e), req);
+      // Memgraph query failed mid-flight — degrade to SQLite zero-state
+      try {
+        const p = hboStore?.getProject ? hboStore.getProject(projectId, ctx?.cid || '') : null;
+        jsonOk(res, { totalCells: 0, closedCells: 0, activeTasks: 0, openDriftSignals: 0, currentPhase: p?.phase ?? 'planning', hillProgress: 0, _source: 'sqlite' }, req);
+      } catch (_) {
+        jsonErr(res, 500, safeMsg(e), req);
+      }
     }
   }
 
@@ -921,6 +1093,319 @@ module.exports = function createProjectRoute({ mgQuery, broadcast, invalidateCon
     }
   }
 
+  // ── GET /api/department/:dept/document ────────────────────────────────────
+  // Returns the DepartmentDocument node for a dept, or a null-content stub when
+  // no document exists yet (never 404 — callers show blank editor on null content).
+  async function handleGetDepartmentDocument(req, res, ctx, deptSlug) {
+    const url = new URL(req.url, 'http://localhost');
+    const companyId = url.searchParams.get('companyId') || ctx?.cid || '';
+    if (!companyId) return jsonErr(res, 400, 'companyId required', req);
+    const docId = `ddoc:${companyId}:${deptSlug}:main`;
+    try {
+      const result = await mgQuery(
+        `MATCH (d:DepartmentDocument {id: $docId}) RETURN d.id, d.companyId, d.department, d.content, d.charter, d.teamFocus, d.successCriteria, d.intentAnchor, d.version, toString(d.updatedAt) AS updatedAt`,
+        { docId }
+      );
+      const row = parseRows(result)[0];
+      if (!row) {
+        // No document yet — return stub (editor renders default blocks)
+        return jsonOk(res, { id: docId, companyId, department: deptSlug, content: null, charter: null, teamFocus: null, successCriteria: null, intentAnchor: null, version: 0, updatedAt: null }, req);
+      }
+      const keys = ['id','companyId','department','content','charter','teamFocus','successCriteria','intentAnchor','version','updatedAt'];
+      return jsonOk(res, rowToObj(row, keys), req);
+    } catch (e) {
+      jsonErr(res, 500, safeMsg(e), req);
+    }
+  }
+
+  // ── PATCH /api/department/:dept/document ──────────────────────────────────
+  // Accepts { section, value, companyId }. Creates node on first save via MERGE.
+  // Sections 'charter','teamFocus','successCriteria','intentAnchor' trigger LLM analysis.
+  // Section 'content' (full block tree) persists without LLM.
+  async function handlePatchDepartmentDocument(req, res, ctx, deptSlug) {
+    const body = await readBody(req);
+    if (!assertBody(body, res, req)) return;
+    const { section, value, companyId: bodyCompanyId } = body;
+    if (!section || value === undefined) return jsonErr(res, 400, 'section and value required', req);
+    const DEPT_ALLOWED_SECTIONS = ['charter', 'teamFocus', 'successCriteria', 'intentAnchor', 'content'];
+    if (!DEPT_ALLOWED_SECTIONS.includes(section)) {
+      return jsonErr(res, 400, `section must be one of: ${DEPT_ALLOWED_SECTIONS.join(', ')}`, req);
+    }
+    const companyId = bodyCompanyId || ctx?.cid || '';
+    if (!companyId) return jsonErr(res, 400, 'companyId required', req);
+    const docId = `ddoc:${companyId}:${deptSlug}:main`;
+
+    try {
+      // ── content section: persist block tree without LLM ───────────────────
+      if (section === 'content') {
+        let blocks;
+        try {
+          blocks = JSON.parse(String(value));
+          if (!Array.isArray(blocks)) throw new Error('content must be a JSON array');
+        } catch (pe) {
+          return jsonErr(res, 400, `content is not valid block JSON: ${pe.message}`, req);
+        }
+        // Back-extract semantic fields from block tree so LLM context stays current
+        let charter = '', teamFocus = '', intentAnchor = '';
+        let lastHeading = '';
+        const charterLines = [], teamFocusLines = [];
+        function visitDeptBlock(block) {
+          if (block.type === 'heading') {
+            const text = (block.content || []).filter(n => n.type === 'text').map(n => n.text || '').join('').toLowerCase();
+            if (text.includes('charter')) lastHeading = 'charter';
+            else if (text.includes('team focus')) lastHeading = 'teamFocus';
+            else lastHeading = text;
+          } else if (block.type === 'intentAnchor') {
+            intentAnchor = block.props?.value || '';
+          } else if (block.type === 'paragraph' || block.type === 'bulletListItem') {
+            const text = (block.content || []).filter(n => n.type === 'text').map(n => n.text || '').join('');
+            if (lastHeading === 'charter') charterLines.push(text);
+            else if (lastHeading === 'teamFocus') teamFocusLines.push(text);
+          }
+          if (Array.isArray(block.children)) block.children.forEach(visitDeptBlock);
+        }
+        blocks.forEach(visitDeptBlock);
+        charter   = charterLines.filter(Boolean).join('\n').slice(0, 2000);
+        teamFocus = teamFocusLines.filter(Boolean).join('\n').slice(0, 2000);
+
+        await mgQuery(
+          `MERGE (d:DepartmentDocument {id: $docId})
+           ON CREATE SET d.companyId=$companyId, d.department=$dept, d.version=1, d.createdAt=datetime()
+           ON MATCH  SET d.version=d.version+1
+           SET d.content=$content,
+               d.charter     = CASE WHEN $charter     <> '' THEN $charter     ELSE d.charter END,
+               d.teamFocus   = CASE WHEN $teamFocus   <> '' THEN $teamFocus   ELSE d.teamFocus END,
+               d.intentAnchor= CASE WHEN $intentAnchor<> '' THEN $intentAnchor ELSE d.intentAnchor END,
+               d.updatedAt=datetime()`,
+          { docId, companyId, dept: deptSlug, content: String(value), charter, teamFocus, intentAnchor }
+        );
+        return jsonOk(res, { ok: true, section: 'content' }, req, 200);
+      }
+
+      // ── Semantic section: create pduId, return 202, fire LLM async ────────
+      const proposalId = `dcpp:${deptSlug}:${companyId}:${Date.now()}`;
+      const pduId      = `dpdu:${docId}:${Date.now()}`;
+
+      // MERGE the DepartmentDocument first (auto-create on first semantic edit)
+      await mgQuery(
+        `MERGE (d:DepartmentDocument {id: $docId})
+         ON CREATE SET d.companyId=$companyId, d.department=$dept, d.version=0, d.createdAt=datetime(), d.updatedAt=datetime()`,
+        { docId, companyId, dept: deptSlug }
+      );
+
+      await mgQuery(
+        `MERGE (pdu:DeptPendingDocumentUpdate {id: $pduId})
+         ON CREATE SET pdu.companyId=$companyId, pdu.deptSlug=$deptSlug,
+           pdu.docId=$docId, pdu.section=$section,
+           pdu.newValue=$newValue, pdu.proposalId=$proposalId,
+           pdu.status='pending_review', pdu.createdAt=datetime()`,
+        { pduId, companyId, deptSlug, docId, section, newValue: String(value), proposalId }
+      );
+
+      await mgQuery(
+        `MERGE (pcp:DeptPlanChangeProposal {id: $proposalId})
+         ON CREATE SET pcp.companyId=$companyId, pcp.deptSlug=$deptSlug,
+           pcp.scope='department', pcp.section=$section,
+           pcp.proposedChange=$value, pcp.pduId=$pduId,
+           pcp.status='pending', pcp.createdAt=datetime()`,
+        { proposalId, companyId, deptSlug, section, value: String(value), pduId }
+      );
+
+      // Respond 202 immediately — LLM analysis fires asynchronously
+      jsonOk(res, { ok: true, pduId, proposalId, message: 'Analyzing edit — check back shortly' }, req, 202);
+
+      // Trigger semantic analysis asynchronously if semanticUpdater is available
+      if (semanticUpdater) {
+        setImmediate(async () => {
+          try {
+            // Fetch current document for context (charter = intentAnchor analog)
+            const docRes = await mgQuery(
+              `MATCH (d:DepartmentDocument {id: $docId}) RETURN d.charter, d.teamFocus, d.successCriteria, d.intentAnchor`,
+              { docId }
+            );
+            const docRow = parseRows(docRes)[0];
+            const currentDoc = docRow
+              ? {
+                  purpose: docRow[0] ?? docRow['charter'] ?? '',        // charter → purpose slot
+                  approach: docRow[1] ?? docRow['teamFocus'] ?? '',     // teamFocus → approach slot
+                  successCriteria: docRow[2] ?? docRow['successCriteria'] ?? '[]',
+                  intentAnchor: docRow[3] ?? docRow['intentAnchor'] ?? '',
+                }
+              : {};
+
+            let check;
+            if (typeof semanticUpdater.analyzeProposal === 'function') {
+              const proposal = { scope: 'department', targetId: deptSlug, section, proposedChange: String(value), companyId };
+              const context  = { purpose: currentDoc.purpose, approach: currentDoc.approach };
+              check = await semanticUpdater.analyzeProposal(proposal, context);
+            } else {
+              const raw = await semanticUpdater.analyzeEdit({
+                pduId,
+                projectId: deptSlug,
+                docId,
+                section,
+                newValue: String(value),
+                oldValue: currentDoc[section] || '',
+                intentAnchor: currentDoc.intentAnchor,
+                exclusions: '[]',
+              });
+              check = {
+                userIntentAsUnderstood: (raw && raw.userIntentAsUnderstood) ? raw.userIntentAsUnderstood : String(value).slice(0, 60),
+                confidenceScore: (raw && raw.confidenceScore != null) ? raw.confidenceScore : 0,
+                components: [],
+                affectedCells: [],
+                proposedChanges: [],
+                requiresApproval: false,
+              };
+            }
+
+            await mgQuery(
+              `MATCH (pcp:DeptPlanChangeProposal {id: $proposalId})
+               SET pcp.interpretation=$interp, pcp.confidenceScore=$score,
+                   pcp.status='ready'`,
+              {
+                proposalId,
+                interp: check.userIntentAsUnderstood || String(value).slice(0, 60),
+                score:  check.confidenceScore ?? 0,
+              }
+            ).catch(() => {});
+
+            await mgQuery(
+              `MATCH (pdu:DeptPendingDocumentUpdate {id: $pduId}) SET pdu.status='ready', pdu.updatedAt=datetime()`,
+              { pduId }
+            ).catch(() => {});
+
+            broadcast({ type: 'dept:understanding:ready', payload: { deptSlug, proposalId, pduId, check }, companyId });
+          } catch (_) {}
+        });
+      } else {
+        await mgQuery(
+          `MATCH (pcp:DeptPlanChangeProposal {id: $proposalId}) SET pcp.status='ready'`,
+          { proposalId }
+        ).catch(() => {});
+        broadcast({ type: 'dept:understanding:ready', payload: { deptSlug, proposalId, pduId, check: { userIntentAsUnderstood: value, confidenceScore: 1 } }, companyId });
+      }
+    } catch (e) {
+      jsonErr(res, 500, safeMsg(e), req);
+    }
+  }
+
+  // ── POST /api/department/:dept/document/confirm-understanding ─────────────
+  // Accepts { pduId, confirmed, correctionNote }. Looks up proposalId from
+  // DeptPendingDocumentUpdate (fixes pduId/proposalId mismatch pattern).
+  async function handleConfirmDeptUnderstanding(req, res, ctx, deptSlug) {
+    const body = await readBody(req);
+    if (!assertBody(body, res, req)) return;
+    const { pduId, confirmed, correctionNote } = body;
+    if (!pduId || confirmed === undefined) return jsonErr(res, 400, 'pduId and confirmed required', req);
+    try {
+      // Resolve proposalId from pduId — avoids the pduId/proposalId mismatch bug
+      const pduRes = await mgQuery(
+        `MATCH (pdu:DeptPendingDocumentUpdate {id: $pduId}) RETURN pdu.proposalId, pdu.companyId`,
+        { pduId }
+      );
+      const pduRow = parseRows(pduRes)[0];
+      if (!pduRow) return jsonErr(res, 404, 'DeptPendingDocumentUpdate not found', req);
+      const proposalId = pduRow[0] ?? pduRow['proposalId'];
+      const companyId  = (pduRow[1] ?? pduRow['companyId'] ?? ctx?.cid) || '';
+
+      await mgQuery(
+        `MATCH (pcp:DeptPlanChangeProposal {id: $proposalId})
+         SET pcp.confirmedAt=datetime(),
+             pcp.status = CASE WHEN $confirmed THEN 'confirmed' ELSE 'dismissed' END`,
+        { proposalId, confirmed: !!confirmed }
+      );
+
+      if (confirmed && semanticUpdater) {
+        setImmediate(async () => {
+          try {
+            const pcpRes = await mgQuery(
+              `MATCH (pcp:DeptPlanChangeProposal {id: $proposalId}) RETURN pcp.section, pcp.proposedChange, pcp.interpretation`,
+              { proposalId }
+            );
+            const pcpRow = parseRows(pcpRes)[0];
+            if (!pcpRow) return;
+            const section = pcpRow[0] ?? pcpRow['section'];
+            const interp  = pcpRow[2] ?? pcpRow['interpretation'];
+            // Build dept-scoped impact ctx (no real ActionCells — use empty set)
+            const impact = await semanticUpdater.extractImpact(
+              { section, proposedValue: pcpRow[1] ?? pcpRow['proposedChange'], interpretation: interp, companyId, actionCells: [] },
+              deptSlug
+            ).catch(() => null);
+            if (impact) {
+              await mgQuery(
+                `MATCH (pcp:DeptPlanChangeProposal {id: $proposalId}) SET pcp.impact=$impact, pcp.status='impact_ready'`,
+                { proposalId, impact: JSON.stringify(impact) }
+              ).catch(() => {});
+              broadcast({ type: 'dept:impact:ready', payload: { deptSlug, proposalId, pduId, impact }, companyId });
+            }
+          } catch (_) {}
+        });
+      }
+
+      jsonOk(res, { ok: true }, req);
+    } catch (e) {
+      jsonErr(res, 500, safeMsg(e), req);
+    }
+  }
+
+  // ── POST /api/department/:dept/document/apply-update ─────────────────────
+  // Accepts { pduId }. Looks up proposalId from DeptPendingDocumentUpdate.
+  async function handleApplyDeptUpdate(req, res, ctx, deptSlug) {
+    const body = await readBody(req);
+    if (!assertBody(body, res, req)) return;
+    const { pduId } = body;
+    if (!pduId) return jsonErr(res, 400, 'pduId required', req);
+    try {
+      // Resolve proposalId from pduId
+      const pduRes = await mgQuery(
+        `MATCH (pdu:DeptPendingDocumentUpdate {id: $pduId}) RETURN pdu.proposalId, pdu.companyId`,
+        { pduId }
+      );
+      const pduRow = parseRows(pduRes)[0];
+      if (!pduRow) return jsonErr(res, 404, 'DeptPendingDocumentUpdate not found', req);
+      const proposalId = pduRow[0] ?? pduRow['proposalId'];
+      const companyId  = (pduRow[1] ?? pduRow['companyId'] ?? ctx?.cid) || '';
+
+      const pcpRes = await mgQuery(
+        `MATCH (pcp:DeptPlanChangeProposal {id: $proposalId, deptSlug: $deptSlug})
+         RETURN pcp.section, pcp.proposedChange`,
+        { proposalId, deptSlug }
+      );
+      const pcpRow = parseRows(pcpRes)[0];
+      if (!pcpRow) return jsonErr(res, 404, 'DeptPlanChangeProposal not found', req);
+
+      const section = pcpRow[0] ?? pcpRow['section'];
+      const value   = pcpRow[1] ?? pcpRow['proposedChange'];
+      const docId   = `ddoc:${companyId}:${deptSlug}:main`;
+
+      const SAFE_DEPT_SECTIONS = ['charter', 'teamFocus', 'successCriteria', 'intentAnchor'];
+      if (!SAFE_DEPT_SECTIONS.includes(section)) return jsonErr(res, 400, `Invalid section: ${section}`, req);
+
+      await mgQuery(
+        `MATCH (d:DepartmentDocument {id: $docId})
+         SET d.${section} = $value, d.version = d.version + 1, d.updatedAt = datetime()`,
+        { docId, value: String(value) }
+      );
+
+      await mgQuery(
+        `MATCH (pcp:DeptPlanChangeProposal {id: $proposalId}) SET pcp.status='applied', pcp.resolvedAt=datetime()`,
+        { proposalId }
+      ).catch(() => {});
+
+      const verRes = await mgQuery(
+        `MATCH (d:DepartmentDocument {id: $docId}) RETURN d.version`,
+        { docId }
+      ).catch(() => null);
+      const documentVersion = parseRows(verRes)[0]?.[0] ?? null;
+
+      broadcast({ type: 'dept:document:applied', payload: { deptSlug, proposalId, pduId, section, documentVersion }, companyId });
+      jsonOk(res, { ok: true, documentVersion }, req);
+    } catch (e) {
+      jsonErr(res, 500, safeMsg(e), req);
+    }
+  }
+
   // ── Router ────────────────────────────────────────────────────────────────
 
   return async function projectRoute(req, res, ctx, pathname, method) {
@@ -940,6 +1425,35 @@ module.exports = function createProjectRoute({ mgQuery, broadcast, invalidateCon
       await handleGenerateDepartmentPage(req, res, ctx, deptGenMatch[1]);
       return true;
     }
+
+    // ── /api/department/:dept/document routes ─────────────────────────────────
+    // GET  /api/department/:dept/document?companyId=
+    // PATCH /api/department/:dept/document
+    // POST /api/department/:dept/document/confirm-understanding
+    // POST /api/department/:dept/document/apply-update
+    const deptDocMatch = pathname.match(/^\/api\/department\/([^/]+)\/document(\/.*)?$/);
+    if (deptDocMatch) {
+      const deptSlug = deptDocMatch[1];
+      const deptDocRest = deptDocMatch[2] || '';
+
+      if (method === 'GET' && deptDocRest === '') {
+        await handleGetDepartmentDocument(req, res, ctx, deptSlug);
+        return true;
+      }
+      if (method === 'PATCH' && deptDocRest === '') {
+        await handlePatchDepartmentDocument(req, res, ctx, deptSlug);
+        return true;
+      }
+      if (method === 'POST' && deptDocRest === '/confirm-understanding') {
+        await handleConfirmDeptUnderstanding(req, res, ctx, deptSlug);
+        return true;
+      }
+      if (method === 'POST' && deptDocRest === '/apply-update') {
+        await handleApplyDeptUpdate(req, res, ctx, deptSlug);
+        return true;
+      }
+    }
+
     // Return false for any other /api/department path (GET is handled by helios-api.js)
     if (pathname.startsWith('/api/department')) return false;