@geraldmaron/construct 1.1.1 → 1.2.0

package/lib/init-docs.mjs

@@ -27,6 +27,16 @@ import { suggestDocsLaneForFile } from './docs-routing.mjs';
 import { stampFrontmatter } from "./doc-stamp.mjs";
 import { multiSelect, selectOption } from './tty-prompts.mjs';
 import readline from "node:readline";
+import {
+  DOC_LANES,
+  DOC_PRESETS,
+  DEFAULT_LANES,
+  LANE_ORDER,
+  normalizeCustomLaneName,
+  normalizeLaneKey,
+  parseCsvList,
+  parseSelectableLanes,
+} from './init/doc-lanes.mjs';
 
 const __dirname = fileURLToPath(new URL(".", import.meta.url));
 const ROOT_DIR = path.join(__dirname, "..");
@@ -52,170 +62,40 @@ const docsDir = path.join(target, docsRootRelative);
 const created = [];
 const skipped = [];
 
-const DOC_LANES = {
-  adrs: {
-    title: "ADRs",
-    dir: "adr",
-    description: "Architecture decision records for decisions that have already been made.",
-    templates: ["adr.md"],
-  },
-  briefs: {
-    title: "Briefs",
-    dir: "briefs",
-    description: "Research, evidence, signal, and one-pager style documents.",
-    templates: [
-      "research-brief.md",
-      "evidence-brief.md",
-      "signal-brief.md",
-      "one-pager.md",
-      "customer-profile.md",
-      "product-intelligence-report.md",
-      "backlog-proposal.md",
-    ],
-  },
-  changelogs: {
-    title: "Changelogs",
-    dir: "changelogs",
-    description: "User-facing release notes and version history entries.",
-    templates: ["changelog-entry.md"],
-  },
-  intake: {
-    title: "Intake",
-    dir: "intake",
-    description: "Intake batch records that explain what arrived, why it matters, and how it should be ingested.",
-    templates: ["__intake-template__"],
-  },
-  memos: {
-    title: "Memos",
-    dir: "memos",
-    description: "Decision memos and internal arguments for alignment and approval.",
-    templates: ["memo.md"],
-  },
-  meetings: {
-    title: 'Meetings',
-    dir: 'meetings',
-    description: 'Meeting notes, minutes, retros, standups, planning sessions, and agendas.',
-    templates: ['__meeting-notes-template__'],
-  },
-  notes: {
-    title: "Notes",
-    dir: "notes",
-    description: "Working notes and lightweight durable context outside formal docs or meetings.",
-    templates: ["__notes-template__"],
-  },
-  onboarding: {
-    title: "Onboarding",
-    dir: "onboarding",
-    description: "Runnable setup guides and first-day workflows for engineers, product, or ops.",
-    templates: ["onboarding.md"],
-  },
-  postmortems: {
-    title: "Postmortems",
-    dir: "postmortems",
-    description: "Blameless incident reports: timeline, root cause, contributing factors, and corrective actions.",
-    templates: ["incident-report.md"],
-  },
-  prds: {
-    title: "PRDs",
-    dir: "prds",
-    description: "Product and capability requirement documents.",
-    templates: ["prd.md", "meta-prd.md", "prd-business.md", "prd-platform.md", "prfaq.md"],
-  },
-  rfcs: {
-    title: "RFCs",
-    dir: "rfcs",
-    description: "Architecture and implementation proposals that need review before a decision.",
-    templates: ["rfc.md", "rfc-platform.md"],
-  },
-  runbooks: {
-    title: "Runbooks",
-    dir: "runbooks",
-    description: "Operational procedures, diagnostics, remediation, and escalation paths.",
-    templates: ["runbook.md"],
-  },
-};
-
-const DOC_PRESETS = {
-  lean: ["adrs", "intake", "memos", "meetings", "notes", "prds"],
-  product: ["adrs", "intake", "memos", "meetings", "notes", "prds", "rfcs"],
-  full: ["adrs", "briefs", "changelogs", "intake", "memos", "meetings", "notes", "onboarding", "postmortems", "prds", "rfcs", "runbooks"],
-};
-
-const DEFAULT_LANES = DOC_PRESETS.lean;
-const LANE_ORDER = ["adrs", "briefs", "changelogs", "intake", "memos", "meetings", "notes", "onboarding", "postmortems", "prds", "rfcs", "runbooks"];
-const LANE_ALIASES = {
-  adr: "adrs",
-  adrs: "adrs",
-  brief: "briefs",
-  briefs: "briefs",
-  changelog: "changelogs",
-  changelogs: "changelogs",
-  releases: "changelogs",
-  release: "changelogs",
-  intake: "intake",
-  memo: "memos",
-  memos: "memos",
-  meeting: 'meetings',
-  meetings: 'meetings',
-  minutes: 'meetings',
-  retro: 'meetings',
-  note: "notes",
-  notes: "notes",
-  onboard: "onboarding",
-  onboarding: "onboarding",
-  postmortem: "postmortems",
-  postmortems: "postmortems",
-  incident: "postmortems",
-  incidents: "postmortems",
-  prd: "prds",
-  prds: "prds",
-  rfc: "rfcs",
-  rfcs: "rfcs",
-  runbook: "runbooks",
-  runbooks: "runbooks",
-};
-
 function inferProjectName(targetPath) {
-  const packageJsonPath = path.join(targetPath, "package.json");
+  const packageJsonPath = path.join(targetPath, 'package.json');
   if (fs.existsSync(packageJsonPath)) {
     try {
-      const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+      const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
       return pkg.name || path.basename(targetPath);
-    } catch {}
+    } catch { /* ignore */ }
   }
   return path.basename(targetPath);
 }
 
-function parseCsvList(value) {
-  return value
-    .split(",")
-    .map((entry) => entry.trim())
-    .filter(Boolean);
-}
-
 const NO_ANSWER_PATTERNS = new Set([
-  "",
-  "n",
-  "no",
-  "none",
-  "nope",
-  "nah",
-  "nothing",
-  "blank",
-  "skip",
-  "no thanks",
+  '',
+  'n',
+  'no',
+  'none',
+  'nope',
+  'nah',
+  'nothing',
+  'blank',
+  'skip',
+  'no thanks',
 ]);
 
 const ALL_ANSWER_PATTERNS = new Set([
-  "all",
-  "all of them",
-  "everything",
-  "default",
-  "defaults",
+  'all',
+  'all of them',
+  'everything',
+  'default',
+  'defaults',
 ]);
 
 function normalizeAnswer(value) {
-  return value.trim().toLowerCase().replace(/\s+/g, " ");
+  return value.trim().toLowerCase().replace(/\s+/g, ' ');
 }
 
 function isNegativeAnswer(value) {
@@ -241,41 +121,14 @@ function parseExtraLaneSelection(value) {
     .filter(Boolean);
 }
 
-function parseSelectableLanes(value) {
-  return value
-    .split(/[,\n]/)
-    .map((entry) => entry.trim())
-    .filter(Boolean)
-    .map((entry) => {
-      if (/^\d+$/.test(entry)) {
-        const lane = LANE_ORDER[Number(entry) - 1];
-        return lane ?? "";
-      }
-      return normalizeLaneKey(entry);
-    })
-    .filter((lane) => lane in DOC_LANES);
-}
-
 function parseBooleanAnswer(value, defaultValue = false) {
   if (!value.trim()) return defaultValue;
   const normalized = normalizeAnswer(value);
-  if (["y", "yes", "true"].includes(normalized)) return true;
-  if (["n", "no", "false", "nope", "nah"].includes(normalized)) return false;
+  if (['y', 'yes', 'true'].includes(normalized)) return true;
+  if (['n', 'no', 'false', 'nope', 'nah'].includes(normalized)) return false;
   return defaultValue;
 }
 
-function normalizeCustomLaneName(name) {
-  return name
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "");
-}
-
-function normalizeLaneKey(name) {
-  return LANE_ALIASES[name.trim().toLowerCase()] ?? name.trim().toLowerCase();
-}
-
 function repoHasAny(targetDir, candidates) {
   return candidates.some((candidate) => fs.existsSync(path.join(targetDir, candidate)));
 }

package/lib/init-unified.mjs

@@ -24,6 +24,8 @@ import { execSync, spawnSync } from 'node:child_process';
 import { stageProjectAdapters } from './install/stage-project.mjs';
 import { missingIgnorePatterns, isConstructPackageRepo } from './host-disposition.mjs';
 import { HOST_KEYS, displayNameToKey } from './platforms/capabilities.mjs';
+import { DOC_LANES, LANE_ORDER, DOC_PRESETS } from './init/doc-lanes.mjs';
+import { initWorkflow } from './workflow-state.mjs';
 
 const __dirname = fileURLToPath(new URL(".", import.meta.url));
 const ROOT_DIR = path.join(__dirname, "..");
@@ -133,92 +135,9 @@ async function checkPrerequisites() {
   return result.ok;
 }
 
-// Documentation system configuration
-const DOC_LANES = {
-  adrs: {
-    title: "ADRs",
-    dir: "adr",
-    description: "Architecture decision records for decisions that have already been made.",
-    templates: ["adr.md"],
-  },
-  briefs: {
-    title: "Briefs",
-    dir: "briefs",
-    description: "Research, evidence, signal, and one-pager style documents.",
-    templates: [
-      "research-brief.md",
-      "evidence-brief.md",
-      "signal-brief.md",
-      "one-pager.md",
-      "customer-profile.md",
-      "product-intelligence-report.md",
-      "backlog-proposal.md",
-    ],
-  },
-  changelogs: {
-    title: "Changelogs",
-    dir: "changelogs",
-    description: "User-facing release notes and version history entries.",
-    templates: ["changelog-entry.md"],
-  },
-  intake: {
-    title: "Intake",
-    dir: "intake",
-    description: "Intake batch records that explain what arrived, why it matters, and how it should be ingested.",
-    templates: ["__intake-template__"],
-  },
-  memos: {
-    title: "Memos",
-    dir: "memos",
-    description: "Decision memos and internal arguments for alignment and approval.",
-    templates: ["memo.md"],
-  },
-  meetings: {
-    title: 'Meetings',
-    dir: 'meetings',
-    description: 'Meeting notes, minutes, retros, standups, planning sessions, and agendas.',
-    templates: ['__meeting-notes-template__'],
-  },
-  notes: {
-    title: "Notes",
-    dir: "notes",
-    description: "Working notes and lightweight durable context outside formal docs or meetings.",
-    templates: ["__notes-template__"],
-  },
-  onboarding: {
-    title: "Onboarding",
-    dir: "onboarding",
-    description: "Runnable setup guides and first-day workflows for engineers, product, or ops.",
-    templates: ["onboarding.md"],
-  },
-  postmortems: {
-    title: "Postmortems",
-    dir: "postmortems",
-    description: "Blameless incident reports: timeline, root cause, contributing factors, and corrective actions.",
-    templates: ["incident-report.md"],
-  },
-  prds: {
-    title: "PRDs",
-    dir: "prds",
-    description: "Product and capability requirement documents.",
-    templates: ["prd.md", "meta-prd.md", "prd-business.md", "prd-platform.md", "prfaq.md"],
-  },
-  rfcs: {
-    title: "RFCs",
-    dir: "rfcs",
-    description: "Architecture and implementation proposals that need review before a decision.",
-    templates: ["rfc.md", "rfc-platform.md"],
-  },
-  runbooks: {
-    title: "Runbooks",
-    dir: "runbooks",
-    description: "Operational procedures, diagnostics, remediation, and escalation paths.",
-    templates: ["runbook.md"],
-  },
-};
-
-// Lane order for display (alphabetical by title)
-const LANE_ORDER = ["adrs", "briefs", "changelogs", "intake", "meetings", "memos", "notes", "onboarding", "postmortems", "prds", "rfcs", "runbooks"];
+const docsPresetArg = args.find((arg) => arg.startsWith('--docs-preset='));
+const docsLanesArg = args.find((arg) => arg.startsWith('--docs-lanes='));
+const docsPresetName = docsPresetArg ? docsPresetArg.split('=')[1].toLowerCase() : 'lean';
 
 // Project type detection
 function detectProjectType(targetPath) {
@@ -515,27 +434,32 @@ function copyLaneTemplates(laneKey) {
 }
 
 async function askDocumentationQuestions() {
-  // Non-interactive mode: use flags or defaults
+  // Non-interactive mode: use flags or defaults (lean preset by default)
   if (skipInteractive) {
     let lanes = [];
-    
-    // Build lanes from explicit flags
-    if (withAllDocsFlag) {
+
+    if (docsLanesArg) {
+      lanes = parseWithDocs(docsLanesArg.split('=')[1]);
+    } else if (withAllDocsFlag) {
       lanes = LANE_ORDER;
     } else if (withDocsFlag) {
-      lanes = parseWithDocs(withDocsFlag.split("=")[1]);
+      lanes = parseWithDocs(withDocsFlag.split('=')[1]);
     } else {
-      // Check individual flags
       if (withAdrsFlag) lanes.push('adrs');
       if (withRfcsFlag) lanes.push('rfcs');
       if (withRunbooksFlag) lanes.push('runbooks');
       if (withPostmortemsFlag) lanes.push('postmortems');
     }
-    
+
+    if (lanes.length === 0) {
+      lanes = DOC_PRESETS[docsPresetName] ?? DOC_PRESETS.lean;
+    }
+
     return {
-      lanes: [...new Set(lanes)], // dedupe
+      lanes: [...new Set(lanes)],
       withArchitecture: withArchitectureFlag,
       withReadme: withReadmeFlag || !fs.existsSync(path.join(target, "README.md")),
+      docsPreset: docsPresetName,
     };
   }
   
@@ -559,13 +483,16 @@ async function askDocumentationQuestions() {
   }
   
   // Build options for multi-select with suggestions pre-checked
-  const suggestedLaneNames = new Set(suggestions.map(s => s.lane));
+  const suggestedLaneNames = new Set([
+    ...(DOC_PRESETS[docsPresetName] ?? DOC_PRESETS.lean),
+    ...suggestions.filter((s) => s.recommended).map((s) => s.lane),
+  ]);
   const laneOptions = LANE_ORDER.map(lane => {
     const suggestion = suggestions.find(s => s.lane === lane);
     return {
       label: DOC_LANES[lane].title,
       value: lane,
-      checked: suggestion?.recommended ?? false,
+      checked: suggestion?.recommended ?? suggestedLaneNames.has(lane),
       description: DOC_LANES[lane].description,
       suggestion: suggestion?.reason,
     };
@@ -592,7 +519,7 @@ async function askDocumentationQuestions() {
     withArchitecture = archResponse;
   }
   
-  return { lanes: selectedLanes, withArchitecture, withReadme };
+  return { lanes: selectedLanes, withArchitecture, withReadme, docsPreset: docsPresetName };
 }
 
 // Intake collection — suggest directories to watch for context
@@ -930,6 +857,9 @@ async function main() {
     generator: "construct/init",
     attribution,
   });
+
+  const { created: workflowCreated } = initWorkflow(target, projectName || "Project workflow");
+  if (workflowCreated) created.push(".cx/workflow.json");
   
   // `.cx/` already exists from the context writes above and is gitignored in full
   // (ADR-0027), so a keep file there could never be tracked. No dead keep file is written.

package/lib/init-update-guide.mjs

@@ -0,0 +1,102 @@
+/**
+ * lib/init-update-guide.mjs — detect and migrate stale .cx/construct_guide.md copies.
+ *
+ * Older inits wrote R&D-specific language, fixed port URLs, or root-level guides.
+ * init:update proposes or applies the current templates/docs/construct_guide.md.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { constructDir } from './paths.mjs';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+const STALE_GUIDE_MARKERS = [
+  /R&D\s+(intake|classification)/i,
+  /review-queue/i,
+  /localhost:54330\b/,
+  /54329-54339/,
+  /construct init.*per.?machine/i,
+  /construct init.*machine setup/i,
+  /Welcome to Construct[\s\S]{0,400}repo root/i,
+];
+
+export function locateConstructGuide(targetDir) {
+  const cxGuide = path.join(targetDir, '.cx', 'construct_guide.md');
+  if (fs.existsSync(cxGuide)) return { path: cxGuide, location: '.cx' };
+  const rootGuide = path.join(targetDir, 'construct_guide.md');
+  if (fs.existsSync(rootGuide)) return { path: rootGuide, location: 'root' };
+  return null;
+}
+
+export function shippedConstructGuidePath() {
+  const fromInstall = path.join(constructDir(), 'templates', 'docs', 'construct_guide.md');
+  if (fs.existsSync(fromInstall)) return fromInstall;
+  return path.join(REPO_ROOT, 'templates', 'docs', 'construct_guide.md');
+}
+
+function sha256(content) {
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+export function isStaleConstructGuide(content) {
+  if (!content || !content.trim()) return false;
+  if (!content.includes('construct intake --help')) return true;
+  return STALE_GUIDE_MARKERS.some((re) => re.test(content));
+}
+
+export function needsConstructGuideUpdate(targetDir) {
+  const located = locateConstructGuide(targetDir);
+  if (!located) return { needed: false };
+  const content = fs.readFileSync(located.path, 'utf8');
+  const shippedPath = shippedConstructGuidePath();
+  if (!fs.existsSync(shippedPath)) return { needed: false };
+  const shipped = fs.readFileSync(shippedPath, 'utf8');
+  if (sha256(content) === sha256(shipped)) return { needed: false };
+  if (!isStaleConstructGuide(content)) return { needed: false };
+  return { needed: true, located, content, shipped };
+}
+
+export function writeConstructGuideProposal(targetDir, { located, shipped }) {
+  const proposalDir = path.join(targetDir, '.cx', 'proposals');
+  fs.mkdirSync(proposalDir, { recursive: true });
+  const proposalPath = path.join(proposalDir, 'construct_guide.construct-update.md');
+  const body = [
+    '# Proposed construct_guide.md update',
+    '',
+    'Your orientation guide predates current Construct branding and intake terminology.',
+    'Merge the sections you still need from your copy, then replace `.cx/construct_guide.md`',
+    'with the shipped template below (or run `construct init:update --apply-guide`).',
+    '',
+    located.location === 'root'
+      ? '**Note:** the guide still lives at repo root; relocate to `.cx/construct_guide.md` (gitignored).'
+      : '',
+    '',
+    '## Shipped template (current standard)',
+    '',
+    shipped.trimEnd(),
+    '',
+  ].filter(Boolean).join('\n');
+  fs.writeFileSync(proposalPath, body, 'utf8');
+  return proposalPath;
+}
+
+export function applyConstructGuideUpdate(targetDir, shippedContent) {
+  const cxDir = path.join(targetDir, '.cx');
+  fs.mkdirSync(cxDir, { recursive: true });
+  const dest = path.join(cxDir, 'construct_guide.md');
+  const rootLegacy = path.join(targetDir, 'construct_guide.md');
+
+  if (fs.existsSync(dest)) {
+    fs.copyFileSync(dest, `${dest}.bak`);
+  }
+  fs.writeFileSync(dest, shippedContent, 'utf8');
+
+  if (fs.existsSync(rootLegacy)) {
+    fs.rmSync(rootLegacy);
+  }
+
+  return dest;
+}

package/lib/init-update.mjs

@@ -4,7 +4,8 @@
  *
  * `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.
+ * manual review and merge. Stale `.cx/construct_guide.md` copies can be refreshed via
+ * `--apply-guide`.
  *
  * checkTemplateConflicts(targetDir) compares project templates against the construct install's
  * templates/docs/ directory. resolveTemplateConflict(conflict, resolution, targetDir) applies
@@ -15,9 +16,15 @@ import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
 import { constructDir } from "./paths.mjs";
+import {
+  applyConstructGuideUpdate,
+  needsConstructGuideUpdate,
+  writeConstructGuideProposal,
+} from "./init-update-guide.mjs";
 
 const args = process.argv.slice(2);
 const dryRun = args.includes("--dry-run");
+const applyGuide = args.includes("--apply-guide");
 const cwdArg = args.find((arg) => arg.startsWith("--cwd="));
 const cwd = cwdArg ? path.resolve(cwdArg.split("=")[1]) : process.cwd();
 
@@ -168,6 +175,18 @@ async function main() {
     }
   }
 
+  const guideState = needsConstructGuideUpdate(cwd);
+  if (guideState.needed) {
+    planned.push({
+      label: "construct_guide.md refresh (profile-neutral intake language)",
+      write() {
+        return writeConstructGuideProposal(cwd, guideState);
+      },
+      relativePath: path.join(".cx", "proposals", "construct_guide.construct-update.md"),
+      applyGuide: () => applyConstructGuideUpdate(cwd, guideState.shipped),
+    });
+  }
+
   if (planned.length === 0) {
     console.log("No proposals needed. The project already satisfies the current update checks.");
     return;
@@ -187,12 +206,24 @@ async function main() {
 
   console.log("");
   for (const item of planned) {
+    if (applyGuide && item.applyGuide) {
+      const dest = item.applyGuide();
+      console.log(`Applied construct_guide.md refresh: ${dest} (backup: ${dest}.bak when prior .cx copy existed)`);
+      continue;
+    }
     const proposalPath = item.write();
     console.log(`Wrote proposal: ${proposalPath}`);
   }
 
+  if (applyGuide) {
+    console.log("");
+    console.log("Guide refresh applied. Review .cx/construct_guide.md and restore any team-specific notes from .bak if needed.");
+    return;
+  }
+
   console.log("");
   console.log("Review the proposal files under .cx/proposals/ and merge the needed changes manually.");
+  console.log("To replace .cx/construct_guide.md with the shipped template: construct init:update --apply-guide");
 }
 
 if (import.meta.url === `file://${process.argv[1]}`) {

package/lib/init.mjs

@@ -69,6 +69,14 @@ function main() {
     content: buildContextMarkdown(),
     generator: "construct/init",
   });
+  writeStampedIfMissing({
+    targetRoot: target,
+    created,
+    skipped,
+    filePath: path.join(target, ".cx", "brand-voice.json"),
+    content: `${JSON.stringify({ version: 1, formality: 3, toneOverride: {}, audienceLexicon: { prefer: [], avoid: [] } }, null, 2)}\n`,
+    generator: "construct/init",
+  });
   // `.cx/` already exists from the context writes above and is gitignored in full
   // (ADR-0027), so a keep file there could never be tracked; `.cx/inbox/` is the local
   // intake drop zone the watcher polls. Create the directories; write no dead keep file.