@geraldmaron/construct 1.0.2 → 1.0.4

package/lib/init-update.mjs

@@ -1,168 +1,283 @@
 #!/usr/bin/env node
 /**
- * lib/init-update.mjs — update existing projects with latest AGENTS.md template.
- * 
- * For projects that already have AGENTS.md but need to sync with the latest
- * Construct operating rules and CI enforcement.
- * 
- * Usage:
- *   node lib/init-update.mjs [--dry-run] [--cwd=path]
- *   construct init:update [--dry-run]
+ * lib/init-update.mjs — non-destructive project-standard updates and template conflict resolution.
+ *
+ * `construct init:update` helps projects adopt current Construct standards without replacing
+ * user-managed instruction files. Proposed updates are written under .cx/proposals/ for
+ * manual review and merge.
+ *
+ * checkTemplateConflicts(targetDir) compares project templates against the construct install's
+ * templates/docs/ directory. resolveTemplateConflict(conflict, resolution, targetDir) applies
+ * one of three resolutions: keep-project, use-construct, or move-to-cx-override.
  */
 
 import fs from "node:fs";
 import path from "node:path";
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import crypto from "node:crypto";
+import { constructDir } from "./paths.mjs";
 
 const args = process.argv.slice(2);
 const dryRun = args.includes("--dry-run");
-const cwdArg = args.find(arg => arg.startsWith("--cwd="));
+const cwdArg = args.find((arg) => arg.startsWith("--cwd="));
 const cwd = cwdArg ? path.resolve(cwdArg.split("=")[1]) : process.cwd();
 
-console.log(`📝 Updating project documentation in ${cwd}`);
+const REQUIRED_AGENT_SECTIONS = [
+  "Operating hierarchy",
+  "Start-of-session rules",
+  "Maintenance rules",
+  "End-of-session rules",
+  "Verification rules",
+];
 
-// Load the AGENTS.md template from project-init-shared
 async function loadAgentsTemplate(projectName) {
-  const modulePath = path.join(import.meta.dirname, 'project-init-shared.mjs');
-  try {
-    // Import the module and call the buildAgentsGuide function
-    const module = await import(modulePath);
-    if (module.buildAgentsGuide) {
-      return module.buildAgentsGuide(projectName);
-    }
-    throw new Error('Could not find buildAgentsGuide function in project-init-shared.mjs');
-  } catch (error) {
-    console.error(`❌ Failed to load AGENTS.md template: ${error.message}`);
-    process.exit(1);
+  const modulePath = path.join(import.meta.dirname, "project-init-shared.mjs");
+  const module = await import(modulePath);
+  if (!module.buildAgentsGuide) {
+    throw new Error("buildAgentsGuide not available from project-init-shared.mjs");
   }
+  return module.buildAgentsGuide(projectName);
 }
 
-function updateAgentsMd(existingContent, newTemplate) {
-  // We'll do a simple replacement for now
-  // In a real implementation, we'd parse the existing file and merge sections
-  
-  console.log(`🔄 Updating AGENTS.md`);
-  
-  if (dryRun) {
-    console.log(`📋 Dry run - would update AGENTS.md`);
-    console.log(`--- Current AGENTS.md (first 200 chars) ---`);
-    console.log(existingContent.substring(0, 200) + '...');
-    console.log(`--- New AGENTS.md (first 200 chars) ---`);
-    console.log(newTemplate.substring(0, 200) + '...');
-    return null;
+function inferProjectName(targetDir) {
+  const packagePath = path.join(targetDir, "package.json");
+  if (fs.existsSync(packagePath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(packagePath, "utf8"));
+      if (pkg.name) return pkg.name;
+    } catch { /* fall through */ }
   }
-  
-  // Backup existing file
-  const backupPath = path.join(cwd, 'AGENTS.md.backup');
-  writeFileSync(backupPath, existingContent, 'utf8');
-  console.log(`📦 Created backup at ${backupPath}`);
-  
-  // Write new template
-  const agentsPath = path.join(cwd, 'AGENTS.md');
-  writeFileSync(agentsPath, newTemplate, 'utf8');
-  console.log(`✅ Updated AGENTS.md`);
-  
-  return newTemplate;
+  return path.basename(targetDir);
 }
 
-function updateCiWorkflow(cwd) {
-  const workflowPath = path.join(cwd, '.github', 'workflows', 'ci.yml');
-  if (!existsSync(workflowPath)) {
-    console.log(`⚠️  No CI workflow found at ${workflowPath}`);
-    return false;
-  }
-  
-  let content = readFileSync(workflowPath, 'utf8');
-  
-  // Check if docs:verify is already in the workflow
-  if (content.includes('construct docs:verify')) {
-    console.log(`✅ CI workflow already has docs:verify check`);
-    return false;
+function findMissingAgentsSections(content) {
+  return REQUIRED_AGENT_SECTIONS.filter((section) => !content.toLowerCase().includes(section.toLowerCase()));
+}
+
+function ensureProposalDir(targetDir) {
+  const dir = path.join(targetDir, ".cx", "proposals");
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function writeProposal(targetDir, fileName, content) {
+  const proposalDir = ensureProposalDir(targetDir);
+  const proposalPath = path.join(proposalDir, fileName);
+  fs.writeFileSync(proposalPath, content, "utf8");
+  return proposalPath;
+}
+
+function buildAgentsProposal(existingContent, template, missingSections) {
+  const missingList = missingSections.map((section) => `- ${section}`).join("\n");
+  return [
+    "<!--",
+    "Construct init:update proposal",
+    "Review this file and merge the needed sections into AGENTS.md manually.",
+    "The original AGENTS.md was not modified.",
+    "-->",
+    "",
+    "# Proposed AGENTS.md Update",
+    "",
+    "## Why this proposal exists",
+    "",
+    "Your current `AGENTS.md` is missing these required sections:",
+    missingList,
+    "",
+    "## Current AGENTS.md",
+    "",
+    "```md",
+    existingContent.trimEnd(),
+    "```",
+    "",
+    "## Current Construct template",
+    "",
+    "```md",
+    template.trimEnd(),
+    "```",
+    "",
+  ].join("\n");
+}
+
+function buildWorkflowProposal(existingContent) {
+  const updatedContent = existingContent.replace(
+    /(\s+- run: node bin\/construct doctor\s*\n)/,
+    "$1      - run: node bin/construct docs:verify\n",
+  );
+  if (updatedContent === existingContent) return null;
+  return [
+    "# Proposed CI Workflow Update",
+    "",
+    "Add `construct docs:verify` next to the existing doctor check.",
+    "",
+    "```yaml",
+    updatedContent.trimEnd(),
+    "```",
+    "",
+  ].join("\n");
+}
+
+// ── Template conflict detection ───────────────────────────────────────────────
+
+function sha256File(filePath) {
+  const buf = fs.readFileSync(filePath);
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+/**
+ * Compare project templates against the construct install's templates/docs/ directory.
+ *
+ * @param {string} targetDir — project root to inspect
+ * @returns {{ conflicts: Array<{ name, constructPath, projectPath, constructSha, projectSha }>, identical: string[], missing: string[] }}
+ */
+export function checkTemplateConflicts(targetDir) {
+  const constructTemplatesDir = path.join(constructDir(), 'templates', 'docs');
+  const projectTemplatesDir = path.join(targetDir, 'templates', 'docs');
+
+  const conflicts = [];
+  const identical = [];
+  const missing = [];
+
+  if (!fs.existsSync(constructTemplatesDir)) {
+    return { conflicts, identical, missing };
   }
-  
-  // Find the test job and add docs:verify after doctor
-  if (content.includes('node bin/construct doctor')) {
-    const updatedContent = content.replace(
-      /(\s+- run: node bin\/construct doctor\s*)/,
-      '$1      - run: node bin/construct docs:verify\n'
-    );
-    
-    if (dryRun) {
-      console.log(`📋 Dry run - would update CI workflow to include docs:verify`);
-      return true;
+
+  const constructFiles = fs.readdirSync(constructTemplatesDir).filter((f) => f.endsWith('.md'));
+
+  for (const name of constructFiles) {
+    const constructPath = path.join(constructTemplatesDir, name);
+    const projectPath = path.join(projectTemplatesDir, name);
+
+    if (!fs.existsSync(projectPath)) {
+      missing.push(name);
+      continue;
     }
-    
-    const backupPath = workflowPath + '.backup';
-    writeFileSync(backupPath, content, 'utf8');
-    writeFileSync(workflowPath, updatedContent, 'utf8');
-    console.log(`✅ Updated CI workflow to include docs:verify check`);
-    return true;
+
+    const constructSha = sha256File(constructPath);
+    const projectSha = sha256File(projectPath);
+
+    if (constructSha === projectSha) {
+      identical.push(name);
+    } else {
+      conflicts.push({ name, constructPath, projectPath, constructSha, projectSha });
+    }
+  }
+
+  return { conflicts, identical, missing };
+}
+
+/**
+ * Apply a resolution to a single template conflict.
+ *
+ * Resolutions:
+ *   'keep-project'       — do nothing; leave the project template as-is
+ *   'use-construct'      — overwrite project template with construct's version; backup original to <name>.bak
+ *   'move-to-cx-override' — copy project template to .cx/templates/docs/<name>,
+ *                           then write construct's template to templates/docs/<name>
+ *
+ * @param {{ name, constructPath, projectPath, constructSha, projectSha }} conflict
+ * @param {'keep-project'|'use-construct'|'move-to-cx-override'} resolution
+ * @param {string} targetDir
+ */
+export function resolveTemplateConflict(conflict, resolution, targetDir) {
+  const { name, constructPath, projectPath } = conflict;
+
+  if (resolution === 'keep-project') {
+    return;
+  }
+
+  if (resolution === 'use-construct') {
+    const backupPath = `${projectPath}.bak`;
+    fs.copyFileSync(projectPath, backupPath);
+    fs.copyFileSync(constructPath, projectPath);
+    return;
   }
-  
-  console.log(`⚠️  Could not find 'construct doctor' in CI workflow to add docs:verify`);
-  return false;
+
+  if (resolution === 'move-to-cx-override') {
+    const cxOverrideDir = path.join(targetDir, '.cx', 'templates', 'docs');
+    fs.mkdirSync(cxOverrideDir, { recursive: true });
+    fs.copyFileSync(projectPath, path.join(cxOverrideDir, name));
+    fs.copyFileSync(constructPath, projectPath);
+    return;
+  }
+
+  throw new Error(`Unknown resolution: ${resolution}. Expected keep-project, use-construct, or move-to-cx-override.`);
 }
 
+// ── Init update workflow ──────────────────────────────────────────────────────
+
 async function main() {
-  console.log(`\n🔍 Checking project structure...`);
-  
-  // Check for AGENTS.md
-  const agentsPath = path.join(cwd, 'AGENTS.md');
-  if (!existsSync(agentsPath)) {
-    console.log(`❌ AGENTS.md not found. Run 'construct init' first.`);
+  console.log(`Preparing Construct standards update for ${cwd}`);
+
+  const agentsPath = path.join(cwd, "AGENTS.md");
+  if (!fs.existsSync(agentsPath)) {
+    console.error("AGENTS.md not found. Run `construct init` first.");
     process.exit(1);
   }
-  
-  const existingAgents = readFileSync(agentsPath, 'utf8');
-  
-  // Get project name from package.json or directory name
-  let projectName = path.basename(cwd);
-  const packagePath = path.join(cwd, 'package.json');
-  if (existsSync(packagePath)) {
-    try {
-      const pkg = JSON.parse(readFileSync(packagePath, 'utf8'));
-      if (pkg.name) projectName = pkg.name;
-    } catch (error) {
-      console.log(`⚠️  Could not read package.json: ${error.message}`);
+
+  const projectName = inferProjectName(cwd);
+  const existingAgents = fs.readFileSync(agentsPath, "utf8");
+  const template = await loadAgentsTemplate(projectName);
+  const missingSections = findMissingAgentsSections(existingAgents);
+
+  const planned = [];
+
+  if (missingSections.length > 0) {
+    const proposalPath = path.join(".cx", "proposals", "AGENTS.md.construct-update.md");
+    planned.push({
+      label: `AGENTS.md proposal (${missingSections.length} missing section${missingSections.length === 1 ? "" : "s"})`,
+      write() {
+        return writeProposal(cwd, "AGENTS.md.construct-update.md", buildAgentsProposal(existingAgents, template, missingSections));
+      },
+      relativePath: proposalPath,
+    });
+  }
+
+  const workflowPath = path.join(cwd, ".github", "workflows", "ci.yml");
+  if (fs.existsSync(workflowPath)) {
+    const workflowContent = fs.readFileSync(workflowPath, "utf8");
+    if (!workflowContent.includes("node bin/construct docs:verify")) {
+      const proposal = buildWorkflowProposal(workflowContent);
+      if (proposal) {
+        planned.push({
+          label: "CI workflow proposal (add docs:verify)",
+          write() {
+            return writeProposal(cwd, "ci.yml.construct-update.md", proposal);
+          },
+          relativePath: path.join(".cx", "proposals", "ci.yml.construct-update.md"),
+        });
+      }
     }
   }
-  
-  const template = await loadAgentsTemplate(projectName);
-  
-  console.log(`\n📊 Analysis:`);
-  console.log(`   • AGENTS.md found (${existingAgents.length} chars)`);
-  console.log(`   • Latest template loaded (${template.length} chars)`);
-  console.log(`   • Project name: ${projectName}`);
-  
-  // Check if AGENTS.md has documentation enforcement section
-  const hasDocEnforcement = existingAgents.includes('Documentation Rules');
-  console.log(`   • Has documentation enforcement: ${hasDocEnforcement ? '✅' : '❌'}`);
-  
-  // Check for CI workflow
-  const ciUpdated = updateCiWorkflow(cwd);
-  
-  // Update AGENTS.md if it doesn't have the latest sections
-  if (!hasDocEnforcement) {
-    updateAgentsMd(existingAgents, template);
-  } else {
-    console.log(`✅ AGENTS.md already has documentation enforcement rules`);
+
+  if (planned.length === 0) {
+    console.log("No proposals needed. The project already satisfies the current update checks.");
+    return;
   }
-  
-  console.log(`\n🎉 Update complete!`);
-  console.log(`\nNext steps:`);
-  console.log(`   1. Review the updated AGENTS.md`);
-  console.log(`   2. Run 'construct docs:verify' to test documentation checks`);
-  console.log(`   3. Commit changes: git add AGENTS.md .github/workflows/ci.yml`);
-  console.log(`   4. Push and verify CI passes`);
-  
+
+  console.log("");
+  console.log("Planned proposals:");
+  for (const item of planned) {
+    console.log(`  - ${item.label} -> ${item.relativePath}`);
+  }
+
   if (dryRun) {
-    console.log(`\n⚠️  This was a dry run. Use 'construct init:update' without --dry-run to apply changes.`);
+    console.log("");
+    console.log("Dry run only. No files were written.");
+    return;
   }
+
+  console.log("");
+  for (const item of planned) {
+    const proposalPath = item.write();
+    console.log(`Wrote proposal: ${proposalPath}`);
+  }
+
+  console.log("");
+  console.log("Review the proposal files under .cx/proposals/ and merge the needed changes manually.");
 }
 
 if (import.meta.url === `file://${process.argv[1]}`) {
-  main().catch(error => {
-    console.error(`❌ Error: ${error.message}`);
+  main().catch((error) => {
+    console.error(`Error: ${error.message}`);
     process.exit(1);
   });
-}
+}

package/lib/install/first-invocation.mjs

@@ -10,7 +10,7 @@
  *   2. Otherwise, run `probeAll()` from lib/bootstrap/resources.mjs.
  *   3. If everything's healthy → silent, set BOOTSTRAP_CHECKED=1.
  *   4. If anything's missing → print the status table to stderr; on TTY,
- *      prompt to run `construct setup` now. Always set BOOTSTRAP_CHECKED=1
+ *      prompt to run `construct init` now. Always set BOOTSTRAP_CHECKED=1
  *      so we don't re-prompt on subsequent commands.
  *
  * Skipped entirely for hook invocations (would corrupt hook output), for
@@ -71,14 +71,14 @@ export async function maybeFirstInvocationProbe({
   for (const probe of probes) stdout.write(formatProbeFn(probe) + '\n');
 
   if (missingRequired.length > 0) {
-    stdout.write(`\n[construct] ${missingRequired.length} required resource(s) missing. Run \`construct setup\` to install.\n\n`);
+    stdout.write(`\n[construct] ${missingRequired.length} required resource(s) missing. Run \`construct init\` to install.\n\n`);
   } else {
-    stdout.write(`\n[construct] ${missingOptional.length} optional resource(s) missing. Run \`construct setup\` to install (Postgres, telemetry, embedding model), or continue in degraded mode.\n\n`);
+    stdout.write(`\n[construct] ${missingOptional.length} optional resource(s) missing. Run \`construct init\` to install (Postgres, telemetry, embedding model), or continue in degraded mode.\n\n`);
   }
 
   if (stdin.isTTY && stdout.isTTY !== false) {
     const wants = await promptYesNo({
-      question: 'Run `construct setup` now?',
+      question: 'Run `construct init` now?',
       defaultYes: missingRequired.length > 0,
       readlineModule,
       stdin,

package/lib/intake/queue.mjs

@@ -73,7 +73,7 @@ export function createIntakeQueue(rootDir, env = process.env, opts = {}) {
   if (backend === 'postgres') {
     const sql = opts.sql ?? createSqlClient(env);
     if (!sql) {
-      throw new Error('Postgres intake queue requires a configured DATABASE_URL (or sql client). Run `construct setup` or set CONSTRUCT_INTAKE_QUEUE_BACKEND=filesystem.');
+      throw new Error('Postgres intake queue requires a configured DATABASE_URL (or sql client). Run `construct init` or set CONSTRUCT_INTAKE_QUEUE_BACKEND=filesystem.');
     }
     const project = opts.project ?? resolveProject(rootDir, env);
     const tenantId = opts.tenantId ?? env?.[INTAKE_TENANT_ENV_KEY] ?? null;

package/lib/integrations/intake-integrations.mjs

@@ -222,7 +222,7 @@ function buildLabels(t) {
 // ── Jira ─────────────────────────────────────────────────────────────────
 
 /**
- * Create a Jira ticket from an intake packet.
+ * Create a Jira work item from an intake packet.
  *
  * @param {object} packet - Intake packet with triage, excerpt
  * @param {object} [opts]
@@ -276,8 +276,7 @@ export async function createJiraTicket(packet, { host, email, token, project, is
 
     const json = await res.json();
 
-    // We don't have the browse URL directly from the create response,
-    // so construct it from the host + issue key
+    // Browse URL is absent from the create response — construct from host + issue key
     const issueKey = json.key;
     const browseUrl = `${resolvedHost.replace(/\/$/, '')}/browse/${issueKey}`;
 
@@ -474,8 +473,8 @@ async function updateConfluencePage(artifact, { host, email, token, space, fetch
 }
 
 /**
- * Minimal markdown to Confluence storage format conversion.
- * Handles the subset of markdown used by Construct artifacts.
+ * Converts the subset of markdown common to Construct artifacts into
+ * Confluence storage format.
  */
 function markdownToConfluenceStorage(md) {
   if (!md) return '';

package/lib/intent-classifier.mjs

@@ -209,6 +209,7 @@ export async function verifyIntent({ request, specialist, flavor, matchedKeyword
 // Kept here (not in orchestration-policy) so the classifier module stays
 // the canonical source of "what does verified mean for this role."
 const ROLE_PROMPT_KEYWORDS = {
+  engineer: ['ai', 'platform', 'data', 'prompt', 'pipeline', 'deploy'],
   productManager: ['platform', 'enterprise', 'ai-product', 'growth', 'go-to-market'],
   architect: ['ai-systems', 'integration', 'data model', 'enterprise', 'platform'],
   qa: ['ai-eval', 'api-contract', 'data-pipeline', 'web-ui'],

package/lib/knowledge/layout.mjs

@@ -19,6 +19,8 @@
  */
 
 export const KNOWLEDGE_ROOT = '.cx/knowledge';
+export const KNOWLEDGE_INTERNAL_ROOT = `${KNOWLEDGE_ROOT}/internal`;
+export const KNOWLEDGE_REFERENCE_ROOT = `${KNOWLEDGE_ROOT}/reference`;
 
 /**
  * All valid knowledge subdirectory names.
@@ -70,3 +72,11 @@ export function inferKnowledgeTarget(filePath) {
   if (/\bpost.?mortem\b|\bincident\b|\brca\b/.test(name))             return 'internal';
   return 'internal';
 }
+
+export function knowledgeInternalStore(...segments) {
+  return ['knowledge', 'internal', ...segments].join('/');
+}
+
+export function knowledgeReferenceStore(...segments) {
+  return ['knowledge', 'reference', ...segments].join('/');
+}

package/lib/knowledge/rag.mjs

@@ -155,6 +155,21 @@ function loadSnapshotChunks(rootDir) {
   return chunks;
 }
 
+/**
+ * Load ingested knowledge files from .cx/knowledge/ subdirectories.
+ */
+function loadKnowledgeChunks(rootDir) {
+  const knowledgeRoot = path.resolve(rootDir, '.cx/knowledge');
+  const subdirs = ['internal', 'external', 'decisions', 'how-tos', 'reference'];
+  const chunks = [];
+  for (const subdir of subdirs) {
+    const full = path.join(knowledgeRoot, subdir);
+    if (!fs.existsSync(full)) continue;
+    chunks.push(...loadMarkdownChunks(full, 'knowledge'));
+  }
+  return chunks;
+}
+
 // ── Index builder ──────────────────────────────────────────────────────────
 
 /**
@@ -166,6 +181,7 @@ export function buildCorpus(rootDir = process.cwd()) {
     ...loadObservationChunks(rootDir),
     ...loadArtifactChunks(rootDir),
     ...loadSnapshotChunks(rootDir),
+    ...loadKnowledgeChunks(rootDir),
   ];
 
   // Embed each chunk