code-as-plan 2.0.0

package/cap/bin/lib/cap-feature-map.cjs

@@ -0,0 +1,506 @@
+// @gsd-context CAP v2.0 Feature Map reader/writer -- FEATURE-MAP.md is the single source of truth for all features, ACs, status, and dependencies.
+// @gsd-decision Markdown format for Feature Map (not JSON/YAML) -- human-readable, diffable in git, editable in any text editor. Machine-readable via regex parsing of structured table rows.
+// @gsd-decision Read and write are separate operations -- no in-memory mutation API. Read returns structured data, write takes structured data and serializes to markdown.
+// @gsd-constraint Zero external dependencies -- uses only Node.js built-ins (fs, path).
+// @gsd-pattern Feature Map is the bridge between all CAP workflows. Brainstorm writes entries, scan updates status, status reads for dashboard.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const FEATURE_MAP_FILE = 'FEATURE-MAP.md';
+
+// @gsd-todo(ref:AC-9) Feature state lifecycle: planned -> prototyped -> tested -> shipped
+const VALID_STATES = ['planned', 'prototyped', 'tested', 'shipped'];
+const STATE_TRANSITIONS = {
+  planned: ['prototyped'],
+  prototyped: ['tested'],
+  tested: ['shipped'],
+  shipped: [],
+};
+
+/**
+ * @typedef {Object} AcceptanceCriterion
+ * @property {string} id - AC identifier (e.g., "AC-1")
+ * @property {string} description - Imperative description text
+ * @property {'pending'|'implemented'|'tested'|'reviewed'} status - Current status
+ */
+
+/**
+ * @typedef {Object} Feature
+ * @property {string} id - Feature ID (e.g., "F-001")
+ * @property {string} title - Feature title (verb+object format)
+ * @property {'planned'|'prototyped'|'tested'|'shipped'} state - Feature lifecycle state
+ * @property {AcceptanceCriterion[]} acs - Acceptance criteria
+ * @property {string[]} files - File references linked to this feature
+ * @property {string[]} dependencies - Feature IDs this depends on
+ * @property {Object<string,string>} metadata - Additional key-value metadata
+ */
+
+/**
+ * @typedef {Object} FeatureMap
+ * @property {Feature[]} features - All features
+ * @property {string} lastScan - ISO timestamp of last scan
+ */
+
+// @gsd-todo(ref:AC-7) Feature Map is a single Markdown file at the project root named FEATURE-MAP.md
+
+// @gsd-todo(ref:AC-1) Generate empty FEATURE-MAP.md template with section headers (Features, Legend) and no feature entries
+/**
+ * Generate the empty FEATURE-MAP.md template for /cap:init.
+ * @returns {string}
+ */
+function generateTemplate() {
+  return `# Feature Map
+
+> Single source of truth for feature identity, state, acceptance criteria, and relationships.
+> Auto-enriched by \`@cap-feature\` tags and dependency analysis.
+
+## Features
+
+<!-- No features yet. Run /cap:brainstorm or add features with addFeature(). -->
+
+## Legend
+
+| State | Meaning |
+|-------|---------|
+| planned | Feature identified, not yet implemented |
+| prototyped | Initial implementation exists |
+| tested | Tests written and passing |
+| shipped | Deployed / merged to main |
+
+---
+*Last updated: ${new Date().toISOString()}*
+`;
+}
+
+// @gsd-api readFeatureMap(projectRoot) -- Reads and parses FEATURE-MAP.md from project root.
+// Returns: FeatureMap object with features and lastScan timestamp.
+// @gsd-todo(ref:AC-10) Feature Map is the single source of truth for feature identity, state, ACs, and relationships
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {FeatureMap}
+ */
+function readFeatureMap(projectRoot) {
+  const filePath = path.join(projectRoot, FEATURE_MAP_FILE);
+  if (!fs.existsSync(filePath)) {
+    return { features: [], lastScan: null };
+  }
+
+  const content = fs.readFileSync(filePath, 'utf8');
+  return parseFeatureMapContent(content);
+}
+
+// @gsd-todo(ref:AC-8) Each feature entry contains: feature ID, title, state, ACs, and file references
+// @gsd-todo(ref:AC-14) Feature Map scales to 80-120 features in a single file
+/**
+ * Parse FEATURE-MAP.md content into structured data.
+ * @param {string} content - Raw markdown content
+ * @returns {FeatureMap}
+ */
+function parseFeatureMapContent(content) {
+  const features = [];
+  const lines = content.split('\n');
+
+  // Match feature headers: ### F-001: Title text [state]
+  const featureHeaderRE = /^###\s+(F-\d{3}):\s+(.+?)\s+\[(\w+)\]\s*$/;
+  // Match AC rows: | AC-N | status | description |
+  const acRowRE = /^\|\s*(AC-\d+)\s*\|\s*(\w+)\s*\|\s*(.+?)\s*\|/;
+  // Match file refs: - `path/to/file`
+  const fileRefRE = /^-\s+`(.+?)`/;
+  // Match dependencies: **Depends on:** F-001, F-002
+  const depsRE = /^\*\*Depends on:\*\*\s*(.+)/;
+  // Match lastScan in footer
+  const lastScanRE = /^\*Last updated:\s*(.+?)\*$/;
+
+  let currentFeature = null;
+  let inAcTable = false;
+  let inFileRefs = false;
+  let lastScan = null;
+
+  for (const line of lines) {
+    const headerMatch = line.match(featureHeaderRE);
+    if (headerMatch) {
+      if (currentFeature) features.push(currentFeature);
+      currentFeature = {
+        id: headerMatch[1],
+        title: headerMatch[2],
+        state: headerMatch[3],
+        acs: [],
+        files: [],
+        dependencies: [],
+        metadata: {},
+      };
+      inAcTable = false;
+      inFileRefs = false;
+      continue;
+    }
+
+    if (!currentFeature) {
+      const scanMatch = line.match(lastScanRE);
+      if (scanMatch) lastScan = scanMatch[1].trim();
+      continue;
+    }
+
+    // Detect AC table start
+    if (line.startsWith('| AC') && line.includes('Status')) {
+      inAcTable = true;
+      inFileRefs = false;
+      continue;
+    }
+    // Skip table separator
+    if (line.match(/^\|[\s-]+\|/)) continue;
+
+    const acMatch = line.match(acRowRE);
+    if (acMatch && inAcTable) {
+      currentFeature.acs.push({
+        id: acMatch[1],
+        description: acMatch[3].trim(),
+        status: acMatch[2].toLowerCase(),
+      });
+      continue;
+    }
+
+    // File references section
+    if (line.startsWith('**Files:**')) {
+      inFileRefs = true;
+      inAcTable = false;
+      continue;
+    }
+
+    if (inFileRefs) {
+      const refMatch = line.match(fileRefRE);
+      if (refMatch) {
+        currentFeature.files.push(refMatch[1]);
+        continue;
+      } else if (line.trim() === '') {
+        inFileRefs = false;
+      }
+    }
+
+    // Dependencies
+    const depsMatch = line.match(depsRE);
+    if (depsMatch) {
+      currentFeature.dependencies = depsMatch[1].split(',').map(d => d.trim()).filter(Boolean);
+      continue;
+    }
+
+    const scanMatch = line.match(lastScanRE);
+    if (scanMatch) lastScan = scanMatch[1].trim();
+  }
+
+  if (currentFeature) features.push(currentFeature);
+
+  return { features, lastScan };
+}
+
+// @gsd-api writeFeatureMap(projectRoot, featureMap) -- Serializes FeatureMap to FEATURE-MAP.md.
+// Side effect: overwrites FEATURE-MAP.md at project root.
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {FeatureMap} featureMap - Structured feature map data
+ */
+function writeFeatureMap(projectRoot, featureMap) {
+  const filePath = path.join(projectRoot, FEATURE_MAP_FILE);
+  const content = serializeFeatureMap(featureMap);
+  fs.writeFileSync(filePath, content, 'utf8');
+}
+
+/**
+ * Serialize FeatureMap to markdown string.
+ * @param {FeatureMap} featureMap
+ * @returns {string}
+ */
+function serializeFeatureMap(featureMap) {
+  const lines = [
+    '# Feature Map',
+    '',
+    '> Single source of truth for feature identity, state, acceptance criteria, and relationships.',
+    '> Auto-enriched by `@cap-feature` tags and dependency analysis.',
+    '',
+    '## Features',
+    '',
+  ];
+
+  for (const feature of featureMap.features) {
+    lines.push(`### ${feature.id}: ${feature.title} [${feature.state}]`);
+    lines.push('');
+
+    if (feature.dependencies.length > 0) {
+      lines.push(`**Depends on:** ${feature.dependencies.join(', ')}`);
+      lines.push('');
+    }
+
+    if (feature.acs.length > 0) {
+      lines.push('| AC | Status | Description |');
+      lines.push('|----|--------|-------------|');
+      for (const ac of feature.acs) {
+        lines.push(`| ${ac.id} | ${ac.status} | ${ac.description} |`);
+      }
+      lines.push('');
+    }
+
+    if (feature.files.length > 0) {
+      lines.push('**Files:**');
+      for (const file of feature.files) {
+        lines.push(`- \`${file}\``);
+      }
+      lines.push('');
+    }
+  }
+
+  if (featureMap.features.length === 0) {
+    lines.push('<!-- No features yet. Run /cap:brainstorm or add features with addFeature(). -->');
+    lines.push('');
+  }
+
+  lines.push('## Legend');
+  lines.push('');
+  lines.push('| State | Meaning |');
+  lines.push('|-------|---------|');
+  lines.push('| planned | Feature identified, not yet implemented |');
+  lines.push('| prototyped | Initial implementation exists |');
+  lines.push('| tested | Tests written and passing |');
+  lines.push('| shipped | Deployed / merged to main |');
+  lines.push('');
+  lines.push('---');
+  lines.push(`*Last updated: ${new Date().toISOString()}*`);
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+// @gsd-api addFeature(projectRoot, feature) -- Add a new feature entry to FEATURE-MAP.md.
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {{ title: string, acs?: AcceptanceCriterion[], dependencies?: string[], metadata?: Object }} feature - Feature data (ID auto-generated)
+ * @returns {Feature} - The added feature with generated ID
+ */
+function addFeature(projectRoot, feature) {
+  const featureMap = readFeatureMap(projectRoot);
+  const id = getNextFeatureId(featureMap.features);
+  const newFeature = {
+    id,
+    title: feature.title,
+    state: 'planned',
+    acs: feature.acs || [],
+    files: [],
+    dependencies: feature.dependencies || [],
+    metadata: feature.metadata || {},
+  };
+  featureMap.features.push(newFeature);
+  writeFeatureMap(projectRoot, featureMap);
+  return newFeature;
+}
+
+// @gsd-api updateFeatureState(projectRoot, featureId, newState) -- Transition feature state.
+// @gsd-todo(ref:AC-9) Enforce valid state transitions: planned->prototyped->tested->shipped
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {string} featureId - Feature ID (e.g., "F-001")
+ * @param {string} newState - Target state
+ * @returns {boolean} - True if transition was valid and applied
+ */
+function updateFeatureState(projectRoot, featureId, newState) {
+  if (!VALID_STATES.includes(newState)) return false;
+
+  const featureMap = readFeatureMap(projectRoot);
+  const feature = featureMap.features.find(f => f.id === featureId);
+  if (!feature) return false;
+
+  const allowed = STATE_TRANSITIONS[feature.state];
+  if (!allowed || !allowed.includes(newState)) return false;
+
+  feature.state = newState;
+  writeFeatureMap(projectRoot, featureMap);
+  return true;
+}
+
+// @gsd-api enrichFromTags(projectRoot, scanResults) -- Update file references from tag scan.
+// @gsd-todo(ref:AC-12) Feature Map auto-enriched from @cap-feature tags found in source code
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {import('./cap-tag-scanner.cjs').CapTag[]} scanResults - Tags from cap-tag-scanner
+ * @returns {FeatureMap}
+ */
+function enrichFromTags(projectRoot, scanResults) {
+  const featureMap = readFeatureMap(projectRoot);
+
+  for (const tag of scanResults) {
+    if (tag.type !== 'feature') continue;
+    const featureId = tag.metadata.feature;
+    if (!featureId) continue;
+
+    const feature = featureMap.features.find(f => f.id === featureId);
+    if (!feature) continue;
+
+    // Add file reference if not already present
+    if (!feature.files.includes(tag.file)) {
+      feature.files.push(tag.file);
+    }
+  }
+
+  writeFeatureMap(projectRoot, featureMap);
+  return featureMap;
+}
+
+// @gsd-api enrichFromDeps(projectRoot) -- Read package.json, detect imports, add dependency info to features.
+// @gsd-todo(ref:AC-13) Feature Map auto-enriched from dependency graph analysis, env vars, package.json
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {{ dependencies: string[], devDependencies: string[], envVars: string[] }}
+ */
+function enrichFromDeps(projectRoot) {
+  const result = { dependencies: [], devDependencies: [], envVars: [] };
+
+  const pkgPath = path.join(projectRoot, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      if (pkg.dependencies) result.dependencies = Object.keys(pkg.dependencies);
+      if (pkg.devDependencies) result.devDependencies = Object.keys(pkg.devDependencies);
+    } catch (_e) {
+      // Malformed package.json
+    }
+  }
+
+  // Scan for .env file to detect environment variables
+  const envPath = path.join(projectRoot, '.env');
+  if (fs.existsSync(envPath)) {
+    try {
+      const envContent = fs.readFileSync(envPath, 'utf8');
+      const envRE = /^([A-Z_][A-Z0-9_]*)=/gm;
+      let match;
+      while ((match = envRE.exec(envContent)) !== null) {
+        result.envVars.push(match[1]);
+      }
+    } catch (_e) {
+      // Ignore
+    }
+  }
+
+  return result;
+}
+
+// @gsd-api getNextFeatureId(features) -- Generate next F-NNN ID.
+/**
+ * @param {Feature[]} features - Existing features
+ * @returns {string} - Next feature ID (e.g., "F-001")
+ */
+function getNextFeatureId(features) {
+  if (!features || features.length === 0) return 'F-001';
+
+  let maxNum = 0;
+  for (const f of features) {
+    const match = f.id.match(/^F-(\d+)$/);
+    if (match) {
+      const num = parseInt(match[1], 10);
+      if (num > maxNum) maxNum = num;
+    }
+  }
+
+  return `F-${String(maxNum + 1).padStart(3, '0')}`;
+}
+
+// @gsd-api enrichFromScan(featureMap, tags) -- Updates Feature Map status from tag scan results.
+// Returns: updated FeatureMap with AC statuses reflecting code annotations.
+/**
+ * @param {FeatureMap} featureMap - Current feature map data
+ * @param {import('./cap-tag-scanner.cjs').CapTag[]} tags - Tags from cap-tag-scanner
+ * @returns {FeatureMap}
+ */
+function enrichFromScan(featureMap, tags) {
+  for (const tag of tags) {
+    if (tag.type !== 'feature') continue;
+    const featureId = tag.metadata.feature;
+    if (!featureId) continue;
+
+    const feature = featureMap.features.find(f => f.id === featureId);
+    if (!feature) continue;
+
+    // Add file reference
+    if (!feature.files.includes(tag.file)) {
+      feature.files.push(tag.file);
+    }
+
+    // If AC reference in metadata, mark it as implemented
+    const acRef = tag.metadata.ac;
+    if (acRef) {
+      const ac = feature.acs.find(a => a.id === acRef);
+      if (ac && ac.status === 'pending') {
+        ac.status = 'implemented';
+      }
+    }
+  }
+
+  return featureMap;
+}
+
+// @gsd-api addFeatures(featureMap, newFeatures) -- Adds new features to an existing Feature Map (from brainstorm).
+// @gsd-todo(ref:AC-11) Feature Map supports auto-derivation from brainstorm output
+/**
+ * @param {FeatureMap} featureMap - Current feature map data
+ * @param {Feature[]} newFeatures - Features to add
+ * @returns {FeatureMap}
+ */
+function addFeatures(featureMap, newFeatures) {
+  const existingIds = new Set(featureMap.features.map(f => f.id));
+  const existingTitles = new Set(featureMap.features.map(f => f.title.toLowerCase()));
+
+  for (const nf of newFeatures) {
+    // Skip duplicates by ID or title
+    if (existingIds.has(nf.id)) continue;
+    if (existingTitles.has(nf.title.toLowerCase())) continue;
+
+    featureMap.features.push(nf);
+    existingIds.add(nf.id);
+    existingTitles.add(nf.title.toLowerCase());
+  }
+
+  return featureMap;
+}
+
+// @gsd-api getStatus(featureMap) -- Computes aggregate project status from Feature Map.
+/**
+ * @param {FeatureMap} featureMap
+ * @returns {{ totalFeatures: number, completedFeatures: number, totalACs: number, implementedACs: number, testedACs: number, reviewedACs: number }}
+ */
+function getStatus(featureMap) {
+  let totalFeatures = featureMap.features.length;
+  let completedFeatures = featureMap.features.filter(f => f.state === 'shipped').length;
+  let totalACs = 0;
+  let implementedACs = 0;
+  let testedACs = 0;
+  let reviewedACs = 0;
+
+  for (const f of featureMap.features) {
+    totalACs += f.acs.length;
+    for (const ac of f.acs) {
+      if (ac.status === 'implemented') implementedACs++;
+      if (ac.status === 'tested') testedACs++;
+      if (ac.status === 'reviewed') reviewedACs++;
+    }
+  }
+
+  return { totalFeatures, completedFeatures, totalACs, implementedACs, testedACs, reviewedACs };
+}
+
+module.exports = {
+  FEATURE_MAP_FILE,
+  VALID_STATES,
+  STATE_TRANSITIONS,
+  generateTemplate,
+  readFeatureMap,
+  writeFeatureMap,
+  parseFeatureMapContent,
+  serializeFeatureMap,
+  addFeature,
+  updateFeatureState,
+  enrichFromTags,
+  enrichFromDeps,
+  getNextFeatureId,
+  enrichFromScan,
+  addFeatures,
+  getStatus,
+};

package/cap/bin/lib/cap-session.cjs

@@ -0,0 +1,191 @@
+// @gsd-context CAP v2.0 session manager -- manages .cap/SESSION.json for cross-conversation workflow state.
+// @gsd-decision SESSION.json is ephemeral (gitignored) -- it tracks the current developer's workflow state, not project state. Project state lives in FEATURE-MAP.md.
+// @gsd-decision JSON format (not markdown) -- session state is machine-consumed, not human-read. JSON is faster to parse and type-safe.
+// @gsd-constraint Zero external dependencies -- uses only Node.js built-ins (fs, path).
+// @gsd-pattern All session reads/writes go through this module -- no direct fs.readFileSync of SESSION.json elsewhere.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// @gsd-decision Session schema is flat and extensible -- new workflow commands can add keys without schema migration.
+// @gsd-todo(ref:AC-16) SESSION.json tracks ephemeral workflow state: active feature ID, current workflow step, session timestamps
+/**
+ * @typedef {Object} CapSession
+ * @property {string} version - Session schema version (e.g., "2.0.0")
+ * @property {string|null} lastCommand - Last /cap: command executed
+ * @property {string|null} lastCommandTimestamp - ISO timestamp of last command
+ * @property {string|null} activeFeature - Currently focused feature ID
+ * @property {string|null} step - Current workflow step
+ * @property {string|null} startedAt - ISO timestamp of when session started
+ * @property {string|null} activeDebugSession - Active debug session ID
+ * @property {Object<string,string>} metadata - Extensible key-value metadata
+ */
+
+const CAP_DIR = '.cap';
+const SESSION_FILE = 'SESSION.json';
+
+// @gsd-todo(ref:AC-3) .cap/.gitignore ignores SESSION.json (ephemeral state shall not be committed)
+const GITIGNORE_CONTENT = `# CAP ephemeral state -- do not commit
+SESSION.json
+debug/
+`;
+
+// @gsd-api getDefaultSession() -- Returns a fresh default session object.
+// @gsd-todo(ref:AC-2) SESSION.json with valid JSON structure: { active_feature: null, step: null, started_at: null }
+/**
+ * @returns {CapSession}
+ */
+function getDefaultSession() {
+  return {
+    version: '2.0.0',
+    lastCommand: null,
+    lastCommandTimestamp: null,
+    activeFeature: null,
+    step: null,
+    startedAt: null,
+    activeDebugSession: null,
+    metadata: {},
+  };
+}
+
+// @gsd-api loadSession(projectRoot) -- Loads .cap/SESSION.json. Returns default session if file missing or corrupt.
+// @gsd-todo(ref:AC-19) SESSION.json is the only mutable session artifact
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {CapSession}
+ */
+function loadSession(projectRoot) {
+  const sessionPath = path.join(projectRoot, CAP_DIR, SESSION_FILE);
+  try {
+    if (!fs.existsSync(sessionPath)) return getDefaultSession();
+    const content = fs.readFileSync(sessionPath, 'utf8');
+    const parsed = JSON.parse(content);
+    // Merge with defaults to handle missing keys from older versions
+    return { ...getDefaultSession(), ...parsed };
+  } catch (_e) {
+    // Corrupt JSON -- return default
+    return getDefaultSession();
+  }
+}
+
+// @gsd-api saveSession(projectRoot, session) -- Writes .cap/SESSION.json. Creates .cap/ directory if needed.
+// @gsd-todo(ref:AC-18) SESSION.json shall not be committed to version control (enforced by .cap/.gitignore)
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {CapSession} session - Session data to persist
+ */
+function saveSession(projectRoot, session) {
+  const capDir = path.join(projectRoot, CAP_DIR);
+  if (!fs.existsSync(capDir)) {
+    fs.mkdirSync(capDir, { recursive: true });
+  }
+  const sessionPath = path.join(capDir, SESSION_FILE);
+  fs.writeFileSync(sessionPath, JSON.stringify(session, null, 2) + '\n', 'utf8');
+}
+
+// @gsd-api updateSession(projectRoot, updates) -- Partial update to session (merge, not overwrite).
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {Partial<CapSession>} updates - Fields to merge into current session
+ * @returns {CapSession} - The updated session
+ */
+function updateSession(projectRoot, updates) {
+  const session = loadSession(projectRoot);
+  // Shallow merge -- metadata gets replaced if present in updates
+  const updated = { ...session, ...updates };
+  saveSession(projectRoot, updated);
+  return updated;
+}
+
+// @gsd-api startSession(projectRoot, featureId, step) -- Set active feature and step with timestamp.
+// @gsd-todo(ref:AC-17) SESSION.json connects to FEATURE-MAP.md only via feature IDs (loose coupling)
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {string} featureId - Feature ID to focus on (e.g., "F-001")
+ * @param {string} step - Current workflow step name
+ * @returns {CapSession}
+ */
+function startSession(projectRoot, featureId, step) {
+  return updateSession(projectRoot, {
+    activeFeature: featureId,
+    step,
+    startedAt: new Date().toISOString(),
+  });
+}
+
+// @gsd-api updateStep(projectRoot, step) -- Update current workflow step.
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {string} step - New workflow step name
+ * @returns {CapSession}
+ */
+function updateStep(projectRoot, step) {
+  return updateSession(projectRoot, { step });
+}
+
+// @gsd-api endSession(projectRoot) -- Clear active feature and step.
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {CapSession}
+ */
+function endSession(projectRoot) {
+  return updateSession(projectRoot, {
+    activeFeature: null,
+    step: null,
+    startedAt: null,
+  });
+}
+
+// @gsd-api isInitialized(projectRoot) -- Check if .cap/ exists.
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {boolean}
+ */
+function isInitialized(projectRoot) {
+  return fs.existsSync(path.join(projectRoot, CAP_DIR));
+}
+
+// @gsd-api initCapDirectory(projectRoot) -- Creates .cap/ directory structure and .gitignore. Idempotent.
+// @gsd-todo(ref:AC-4) No prompts, questions, wizards, or configuration forms
+// @gsd-todo(ref:AC-5) Completes in a single invocation with no follow-up steps
+// @gsd-todo(ref:AC-6) Idempotent -- running on already-initialized project shall not overwrite existing content
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ */
+function initCapDirectory(projectRoot) {
+  const capDir = path.join(projectRoot, CAP_DIR);
+  const stackDocsDir = path.join(capDir, 'stack-docs');
+  const debugDir = path.join(capDir, 'debug');
+  const gitignorePath = path.join(capDir, '.gitignore');
+  const sessionPath = path.join(capDir, SESSION_FILE);
+
+  // Create directories (idempotent via recursive:true)
+  fs.mkdirSync(capDir, { recursive: true });
+  fs.mkdirSync(stackDocsDir, { recursive: true });
+  fs.mkdirSync(debugDir, { recursive: true });
+
+  // Write .gitignore (always overwrite -- it's infrastructure, not user content)
+  fs.writeFileSync(gitignorePath, GITIGNORE_CONTENT, 'utf8');
+
+  // Write SESSION.json only if it doesn't exist (preserve existing session)
+  if (!fs.existsSync(sessionPath)) {
+    saveSession(projectRoot, getDefaultSession());
+  }
+}
+
+module.exports = {
+  CAP_DIR,
+  SESSION_FILE,
+  GITIGNORE_CONTENT,
+  loadSession,
+  saveSession,
+  updateSession,
+  getDefaultSession,
+  startSession,
+  updateStep,
+  endSession,
+  isInitialized,
+  initCapDirectory,
+};