agent-method 1.5.12

package/lib/cli/close.js

@@ -0,0 +1,838 @@
+/** wwa close — session close checklist, cascade reminders, and project snapshot. */
+
+import { readFileSync, existsSync, readdirSync, statSync, mkdirSync } from "node:fs";
+import { resolve, join, dirname, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { findEntryPoint, findSessionLog, readMethodVersion, packageRoot, safeWriteFile } from "./helpers.js";
+import { findOrphans, detectNewFiles, inferCategory } from "../dependencies.js";
+import { resolveTokensPath, resolveDocsMapPath, resolveIndexPath, resolveFeatureRegistryPath, loadBoundaries } from "../boundaries.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export function register(program) {
+  program
+    .command("close [directory]")
+    .description("Show session close checklist, cascade reminders, and project snapshot")
+    .option("--json", "Output as JSON")
+    .option("--internal-registry", "Include docs/internal/doc-registry.yaml health in management output")
+    .action(async (directory, opts) => {
+      directory = directory || ".";
+      const d = resolve(directory);
+
+      const checklist = [];
+      const warnings = [];
+
+      // 1. Check SESSION-LOG.md exists
+      const sessionLog = findSessionLog(directory);
+      if (sessionLog) {
+        checklist.push({ item: "SESSION-LOG.md exists", ok: true });
+      } else {
+        checklist.push({ item: "SESSION-LOG.md exists", ok: false });
+        warnings.push("No SESSION-LOG.md found — create one to track session metrics");
+      }
+
+      // 2. Check STATE.md exists and has current position
+      const statePath = join(d, "STATE.md");
+      if (existsSync(statePath)) {
+        checklist.push({ item: "STATE.md exists", ok: true });
+      } else {
+        checklist.push({ item: "STATE.md exists", ok: false });
+        warnings.push("No STATE.md found — decisions may be lost between sessions");
+      }
+
+      // 3. Check PLAN.md for incomplete steps
+      const planPath = join(d, "PLAN.md");
+      if (existsSync(planPath)) {
+        const planContent = readFileSync(planPath, "utf-8");
+        const todoSteps = (planContent.match(/\|\s*todo\s*\|/gi) || []).length;
+        if (todoSteps > 0) {
+          checklist.push({
+            item: `PLAN.md has ${todoSteps} incomplete step(s)`,
+            ok: false,
+          });
+        } else {
+          checklist.push({ item: "PLAN.md — all steps complete", ok: true });
+        }
+      }
+
+      // 4. Check Management files
+      const digestPath = join(d, "Management", "DIGEST.md");
+      if (existsSync(digestPath)) {
+        checklist.push({ item: "Management/DIGEST.md exists", ok: true });
+      }
+
+      // 5. Check SUMMARY.md
+      const summaryPath = join(d, "SUMMARY.md");
+      if (existsSync(summaryPath)) {
+        checklist.push({ item: "SUMMARY.md exists for audit entry", ok: true });
+      }
+
+      // Build cascade reminders from PROTOCOL.yaml or fallback to defaults.
+      // If PROTOCOL.yaml has an empty close_check list, fall back to defaults so
+      // the user always sees helpful reminders.
+      let cascadeReminders;
+      const protocolPath = join(d, ".context", "PROTOCOL.yaml");
+      if (existsSync(protocolPath)) {
+        try {
+          const yaml = (await import("js-yaml")).default;
+          let raw = readFileSync(protocolPath, "utf-8");
+          const parsed = yaml.load(raw);
+          cascadeReminders = parsed?.close_check || getDefaultReminders();
+          // Update last_verified timestamp (comment-preserving)
+          const today = new Date().toISOString().slice(0, 10);
+          const lvPattern = /^(last_verified:) .+$/m;
+          if (lvPattern.test(raw)) {
+            raw = raw.replace(lvPattern, `$1 "${today}"`);
+          } else {
+            const vLine = /^(version: .+)$/m;
+            raw = raw.replace(vLine, `$1\nlast_verified: "${today}"`);
+          }
+          safeWriteFile(protocolPath, raw, "utf-8");
+        } catch (_) {
+          cascadeReminders = getDefaultReminders();
+        }
+      } else {
+        cascadeReminders = getDefaultReminders();
+      }
+
+      // If we still have no reminders (empty array), use defaults.
+      if (!cascadeReminders || cascadeReminders.length === 0) {
+        cascadeReminders = getDefaultReminders();
+      }
+
+      // Compute project snapshot — methodology reference data
+      const snapshot = await computeProjectSnapshot(d);
+
+      // Update project doc-tokens.yaml regardless of output mode
+      const tokenUpdateResult = await updateProjectTokens(d, snapshot);
+
+      // Update INDEX.yaml metrics
+      const indexUpdateResult = await updateIndexMetrics(d, snapshot);
+
+      // Load internal registry if requested
+      let internalRegistry = null;
+      if (opts.internalRegistry) {
+        try {
+          const { loadInternalRegistry } = await import("./doc-review.js");
+          internalRegistry = await loadInternalRegistry(d);
+          if (!internalRegistry) {
+            console.log("  Note: No docs/internal/doc-registry.yaml found — run `wwa doc-review` to generate it.");
+          }
+        } catch {
+          // doc-review module not available — skip silently
+        }
+      }
+
+      // Always write management files (close-snapshot.yaml + STATUS.md) at close.
+      const writeResults = await writeManagementFiles(
+        d,
+        snapshot,
+        checklist,
+        cascadeReminders,
+        internalRegistry
+      );
+
+      if (opts.json) {
+        console.log(
+          JSON.stringify({ checklist, warnings, cascadeReminders, snapshot, tokensUpdated: !!tokenUpdateResult, indexUpdated: !!indexUpdateResult, writeResults }, null, 2)
+        );
+        return;
+      }
+
+      console.log("\n  Session Close Checklist\n");
+
+      for (const item of checklist) {
+        const icon = item.ok ? "[x]" : "[ ]";
+        console.log(`    ${icon} ${item.item}`);
+      }
+
+      if (warnings.length > 0) {
+        console.log("\n  Warnings:");
+        for (const w of warnings) {
+          console.log(`    ! ${w}`);
+        }
+      }
+
+      console.log("\n  Cascade reminders:");
+      for (const r of cascadeReminders) {
+        console.log(`    - ${r}`);
+      }
+
+      // Print project snapshot
+      printSnapshot(snapshot);
+
+      if (tokenUpdateResult) {
+        console.log("\n  Updated doc-tokens.yaml with current project metrics.");
+      }
+
+      if (indexUpdateResult) {
+        console.log("  Updated INDEX.yaml with current project metrics.");
+      }
+
+      if (writeResults) {
+        console.log("\n  Management files written:");
+        if (writeResults.snapshotYaml) console.log(`    - ${writeResults.snapshotYaml}`);
+        if (writeResults.statusMd) console.log(`    - ${writeResults.statusMd}`);
+      }
+
+      console.log("");
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Project snapshot — computed at close, chunked for large projects
+// ---------------------------------------------------------------------------
+
+async function computeProjectSnapshot(dir) {
+  const snapshot = {
+    project: {},
+    methodologyFiles: { present: [], missing: [] },
+    decisions: { count: 0, recent: [] },
+    sessions: { count: 0, latestDate: null },
+    features: [],
+    registry: null,
+    docsMap: null,
+    fileStats: {},
+  };
+
+  // --- Chunk 1: Project identity ---
+  const entryPoint = findEntryPoint(dir);
+  if (entryPoint) {
+    snapshot.project.entryPoint = relative(dir, entryPoint) || entryPoint;
+    snapshot.project.methodVersion = readMethodVersion(entryPoint);
+    const epContent = readFileSync(entryPoint, "utf-8");
+    const tierMatch = epContent.match(/tier:\s*(\S+)/);
+    if (tierMatch) snapshot.project.tier = tierMatch[1];
+    const modeMatch = epContent.match(/mode:\s*(\S+)/);
+    if (modeMatch) snapshot.project.interactionLevel = modeMatch[1];
+  }
+
+  const projectPath = join(dir, "PROJECT.md");
+  if (existsSync(projectPath)) {
+    const content = readFileSync(projectPath, "utf-8");
+    const titleMatch = content.match(/^#\s+(.+)/m);
+    if (titleMatch) snapshot.project.name = titleMatch[1].trim();
+  }
+
+  const profilePath = join(dir, "PROJECT-PROFILE.md");
+  if (existsSync(profilePath)) {
+    const content = readFileSync(profilePath, "utf-8");
+    const typeMatch = content.match(/project.?type[:\s|]+(\S+)/i);
+    if (typeMatch) snapshot.project.type = typeMatch[1].toLowerCase();
+    const stageMatch = content.match(/lifecycle.?stage[:\s|]+(\S+)/i);
+    if (stageMatch) snapshot.project.lifecycleStage = stageMatch[1].toLowerCase();
+  }
+
+  // --- Chunk 2: Methodology file inventory ---
+  const expectedFiles = [
+    "STATE.md", "PLAN.md", "ROADMAP.md", "SUMMARY.md",
+    "PROJECT.md", "PROJECT-PROFILE.md", "SESSION-LOG.md",
+    ".context/BASE.md", ".context/METHODOLOGY.md",
+    ".context/PROTOCOL.yaml", ".context/INDEX.yaml",
+  ];
+  for (const f of expectedFiles) {
+    const p = join(dir, f);
+    if (existsSync(p)) {
+      const stat = statSync(p);
+      const lines = readFileSync(p, "utf-8").split("\n").length;
+      snapshot.methodologyFiles.present.push({ file: f, lines, bytes: stat.size });
+      // Track files approaching 300-line threshold
+      if (lines > 250) {
+        snapshot.fileStats[f] = { lines, nearThreshold: lines >= 280 };
+      }
+    } else {
+      snapshot.methodologyFiles.missing.push(f);
+    }
+  }
+
+  // --- Chunk 3: Decisions from STATE.md ---
+  const statePath = join(dir, "STATE.md");
+  if (existsSync(statePath)) {
+    const content = readFileSync(statePath, "utf-8");
+    const decisionSection = content.match(
+      /##\s*Decisions?\s*\n([\s\S]*?)(?=\n##|\n$|$)/i
+    );
+    if (decisionSection) {
+      const rows = decisionSection[1].match(/\|[^|\n]+\|[^|\n]+\|/g) || [];
+      const decisions = [];
+      for (const row of rows) {
+        const cols = row.split("|").map((c) => c.trim()).filter((c) => c && !c.match(/^[-:]+$/));
+        if (cols.length >= 2 && !cols[0].toLowerCase().includes("date")) {
+          decisions.push({ date: cols[0], decision: cols.slice(1).join(" — ") });
+        }
+      }
+      snapshot.decisions.count = decisions.length;
+      snapshot.decisions.recent = decisions.slice(-5); // last 5
+    }
+  }
+
+  // --- Chunk 4: Session count from SESSION-LOG.md ---
+  const sessionLog = findSessionLog(dir);
+  if (sessionLog) {
+    const content = readFileSync(sessionLog, "utf-8");
+    const entries = content.match(/###\s+S\d+/g) || [];
+    snapshot.sessions.count = entries.length;
+    // Find the latest date
+    const dates = content.match(/###\s+S\d+\s*(?:—|--)\s*(\S+)/g) || [];
+    if (dates.length > 0) {
+      const lastDate = dates[dates.length - 1].match(/(\d{4}-\d{2}-\d{2})/);
+      if (lastDate) snapshot.sessions.latestDate = lastDate[1];
+    }
+  }
+
+  // --- Chunk 5: Feature registry (from project registry/ or installed package) ---
+  const resolvedRegistry = await resolveFeatureRegistryPath(dir);
+  const pkgRegistry = join(packageRoot, "docs", "internal", "feature-registry.yaml");
+  const registryPath = existsSync(resolvedRegistry) ? resolvedRegistry : (existsSync(pkgRegistry) ? pkgRegistry : null);
+
+  if (registryPath) {
+    try {
+      const yaml = (await import("js-yaml")).default;
+      const raw = readFileSync(registryPath, "utf-8");
+      const parsed = yaml.load(raw);
+      if (parsed) {
+        snapshot.registry = {
+          source: existsSync(localRegistry) ? "project" : "package",
+          version: parsed.version || null,
+          featureCount: parsed.features ? Object.keys(parsed.features).length : 0,
+          workflowCount: parsed.guided_workflows ? parsed.guided_workflows.length : 0,
+        };
+        // Collect active features from project entry point scoping
+        if (entryPoint) {
+          const epContent = readFileSync(entryPoint, "utf-8");
+          const featureRefs = epContent.match(/[A-Z]{2,5}-\d{2}/g) || [];
+          snapshot.features = [...new Set(featureRefs)].sort();
+        }
+      }
+    } catch (_) {
+      // Registry parse failed — skip silently
+    }
+  }
+
+  // --- Chunk 6: Docs map status ---
+  const docsMapPath = await resolveDocsMapPath(dir);
+  if (existsSync(docsMapPath)) {
+    const content = readFileSync(docsMapPath, "utf-8");
+    const inventoryRows = (content.match(/^\|[^|]+\|[^|]+\|[^|]+\|[^|]+\|$/gm) || [])
+      .filter((r) => !r.includes("---") && !r.includes("Path") && !r.includes("Purpose"));
+    const mappingRows = (content.match(/^\|[^|]+\|[^|]+\|[^|]+\|$/gm) || [])
+      .filter((r) => !r.includes("---") && !r.includes("Project component") && !r.includes("When this"));
+
+    // Check which docs actually exist on disk
+    let docsExist = 0;
+    let docsTotal = 0;
+    for (const row of inventoryRows) {
+      const cols = row.split("|").map((c) => c.trim()).filter((c) => c);
+      if (cols.length >= 1) {
+        docsTotal++;
+        if (existsSync(join(dir, cols[0]))) docsExist++;
+      }
+    }
+
+    snapshot.docsMap = {
+      inventoryCount: docsTotal,
+      docsOnDisk: docsExist,
+      docsMissing: docsTotal - docsExist,
+      componentMappings: mappingRows.length,
+    };
+  }
+
+  // --- Chunk 7: Dependency graph health ---
+  const docTokensPath = await resolveTokensPath(dir);
+  if (existsSync(docTokensPath)) {
+    try {
+      const yaml = (await import("js-yaml")).default;
+      const raw = readFileSync(docTokensPath, "utf-8");
+      const parsed = yaml.load(raw);
+      const docGraph = parsed?.doc_graph;
+      if (docGraph) {
+        const nodes = docGraph.nodes || [];
+        const edges = docGraph.edges || [];
+
+        // Scan for methodology files on disk that aren't in the graph
+        const currentFiles = snapshot.methodologyFiles.present.map((f) => f.file);
+        const newFiles = detectNewFiles(nodes, currentFiles);
+        const orphans = findOrphans(docGraph);
+
+        snapshot.dependencyHealth = {
+          nodeCount: nodes.length,
+          edgeCount: edges.length,
+          orphanCount: orphans.length,
+          newFiles,
+          lastScan: docGraph.last_scan || null,
+        };
+      }
+    } catch {
+      // doc-tokens.yaml parse error — skip dependency health
+    }
+  }
+
+  return snapshot;
+}
+
+// ---------------------------------------------------------------------------
+// Display
+// ---------------------------------------------------------------------------
+
+function printSnapshot(snapshot) {
+  console.log("\n  Project Snapshot\n");
+
+  // Project identity
+  if (snapshot.project.name) {
+    console.log(`    Project: ${snapshot.project.name}`);
+  }
+  if (snapshot.project.type) {
+    console.log(`    Type: ${snapshot.project.type} | Stage: ${snapshot.project.lifecycleStage || "unknown"}`);
+  }
+  if (snapshot.project.methodVersion) {
+    console.log(`    Method: v${snapshot.project.methodVersion} | Tier: ${snapshot.project.tier || "unknown"}`);
+  }
+
+  // File inventory
+  const present = snapshot.methodologyFiles.present.length;
+  const missing = snapshot.methodologyFiles.missing.length;
+  console.log(`\n    Methodology files: ${present} present, ${missing} missing`);
+  if (missing > 0) {
+    console.log(`    Missing: ${snapshot.methodologyFiles.missing.join(", ")}`);
+  }
+
+  // Threshold warnings
+  const nearThreshold = Object.entries(snapshot.fileStats)
+    .filter(([, s]) => s.nearThreshold);
+  if (nearThreshold.length > 0) {
+    console.log(`    Scale warnings:`);
+    for (const [file, stats] of nearThreshold) {
+      console.log(`      ! ${file}: ${stats.lines} lines (threshold: 300)`);
+    }
+  }
+
+  // Decisions
+  if (snapshot.decisions.count > 0) {
+    console.log(`\n    Decisions: ${snapshot.decisions.count} total`);
+    if (snapshot.decisions.recent.length > 0) {
+      console.log(`    Recent:`);
+      for (const d of snapshot.decisions.recent) {
+        const text = d.decision.length > 60 ? d.decision.slice(0, 57) + "..." : d.decision;
+        console.log(`      ${d.date}: ${text}`);
+      }
+    }
+  }
+
+  // Sessions
+  if (snapshot.sessions.count > 0) {
+    console.log(`\n    Sessions: ${snapshot.sessions.count} logged (latest: ${snapshot.sessions.latestDate || "unknown"})`);
+  }
+
+  // Registry
+  if (snapshot.registry) {
+    console.log(`\n    Registry: ${snapshot.registry.source} (${snapshot.registry.featureCount} features, ${snapshot.registry.workflowCount} workflows)`);
+  }
+  if (snapshot.features.length > 0) {
+    console.log(`    Features referenced: ${snapshot.features.length} (${snapshot.features.slice(0, 8).join(", ")}${snapshot.features.length > 8 ? "..." : ""})`);
+  }
+
+  // Docs
+  if (snapshot.docsMap) {
+    const dm = snapshot.docsMap;
+    console.log(`\n    Docs: ${dm.docsOnDisk}/${dm.inventoryCount} exist | ${dm.componentMappings} component mappings`);
+    if (dm.docsMissing > 0) {
+      console.log(`    Missing docs: ${dm.docsMissing} (run \`wwa docs\` for details)`);
+    }
+  }
+
+  // Dependencies
+  if (snapshot.dependencyHealth) {
+    const dh = snapshot.dependencyHealth;
+    console.log(`\n    Dependencies: ${dh.nodeCount} nodes, ${dh.edgeCount} edges, ${dh.orphanCount} orphans`);
+    if (dh.newFiles.length > 0) {
+      console.log(`    New files detected: ${dh.newFiles.join(", ")}`);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Comment-preserving YAML update helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Update scalar values in a named YAML section, preserving comments and structure.
+ * Existing keys are updated in-place; missing keys are appended at section end.
+ */
+function patchYamlSection(raw, sectionName, updates) {
+  let result = raw;
+  const newKeys = [];
+
+  for (const [key, value] of Object.entries(updates)) {
+    const formatted = typeof value === "number" ? String(value) : `"${value}"`;
+    const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const regex = new RegExp(`^(  ${escaped}:) .+$`, "m");
+    if (regex.test(result)) {
+      result = result.replace(regex, `$1 ${formatted}`);
+    } else {
+      newKeys.push(`  ${key}: ${formatted}`);
+    }
+  }
+
+  if (newKeys.length > 0) {
+    const sectionIdx = result.search(new RegExp(`^${sectionName}:`, "m"));
+    if (sectionIdx !== -1) {
+      const afterSection = result.slice(sectionIdx);
+      const lines = afterSection.split("\n");
+      let offset = sectionIdx;
+      let insertAt = -1;
+      for (let i = 1; i < lines.length; i++) {
+        offset += lines[i - 1].length + 1;
+        if (lines[i].length > 0 && !lines[i].startsWith(" ") && !lines[i].startsWith("#")) {
+          insertAt = offset;
+          break;
+        }
+      }
+      if (insertAt === -1) insertAt = result.length;
+      result = result.slice(0, insertAt) + newKeys.join("\n") + "\n" + result.slice(insertAt);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Append a node entry to doc_graph.nodes array, preserving existing content.
+ * Inserts before the "  edges:" line.
+ */
+function appendDocGraphNode(raw, node) {
+  const edgesIdx = raw.search(/^  edges:/m);
+  if (edgesIdx === -1) return raw;
+  const entry = `    - path: "${node.path}"\n      category: "${node.category}"\n      role: "${node.role}"\n`;
+  return raw.slice(0, edgesIdx) + entry + raw.slice(edgesIdx);
+}
+
+// ---------------------------------------------------------------------------
+// Update project doc-tokens.yaml
+// ---------------------------------------------------------------------------
+
+async function updateProjectTokens(dir, snapshot) {
+  const tokensPath = await resolveTokensPath(dir);
+  if (!existsSync(tokensPath)) return null;
+
+  try {
+    const yaml = (await import("js-yaml")).default;
+    let raw = readFileSync(tokensPath, "utf-8");
+    const parsed = yaml.load(raw) || {};
+    const tokens = parsed.tokens || {};
+
+    const today = new Date().toISOString().slice(0, 10);
+    tokens.last_close = today;
+
+    // File counts — count methodology files (.md/.yaml/.yml) in project
+    let methodologyCount = 0;
+    let docsCount = 0;
+    let contextCount = 0;
+    const countFiles = (base) => {
+      if (!existsSync(base)) return;
+      for (const entry of readdirSync(base, { withFileTypes: true })) {
+        const p = join(base, entry.name);
+        if (entry.isDirectory()) {
+          // Track docs/ and .context/ separately
+          if (entry.name === "docs" && base === dir) {
+            docsCount += countDir(p);
+          } else if (entry.name === ".context" && base === dir) {
+            contextCount += countDir(p);
+          } else {
+            countFiles(p);
+          }
+        } else if (/\.(md|yaml|yml)$/i.test(entry.name)) {
+          methodologyCount++;
+        }
+      }
+    };
+    const countDir = (d) => {
+      let c = 0;
+      if (!existsSync(d)) return c;
+      for (const entry of readdirSync(d, { withFileTypes: true })) {
+        if (entry.isDirectory()) c += countDir(join(d, entry.name));
+        else if (/\.(md|yaml|yml)$/i.test(entry.name)) c++;
+      }
+      return c;
+    };
+    countFiles(dir);
+    tokens.methodology_file_count = methodologyCount;
+    tokens.docs_file_count = docsCount;
+    tokens.context_file_count = contextCount;
+
+    // Session metrics
+    tokens.session_count = snapshot.sessions.count;
+    tokens.decision_count = snapshot.decisions.count;
+    tokens.total_features_referenced = snapshot.features.length;
+
+    // Scale indicators
+    let nearThreshold = 0;
+    let overThreshold = 0;
+    for (const f of snapshot.methodologyFiles.present) {
+      if (f.lines >= 300) overThreshold++;
+      else if (f.lines >= 250) nearThreshold++;
+    }
+    tokens.files_near_threshold = nearThreshold;
+    tokens.files_over_threshold = overThreshold;
+
+    // Docs coverage
+    if (snapshot.docsMap) {
+      tokens.docs_inventory_count = snapshot.docsMap.inventoryCount;
+      tokens.docs_on_disk = snapshot.docsMap.docsOnDisk;
+      tokens.docs_missing = snapshot.docsMap.docsMissing;
+      tokens.component_mappings = snapshot.docsMap.componentMappings;
+    }
+
+    // Update doc_graph.last_scan and add new file nodes (comment-preserving)
+    if (parsed.doc_graph && snapshot.dependencyHealth) {
+      const lsPattern = /^(  last_scan:) .+$/m;
+      if (lsPattern.test(raw)) {
+        raw = raw.replace(lsPattern, `$1 "${today}"`);
+      }
+      const newFiles = snapshot.dependencyHealth.newFiles || [];
+      // Filter against scan.include boundaries to avoid adding non-docs files (I3/R3)
+      const bounds = await loadBoundaries(dir);
+      const scanInclude = bounds.scan?.include || [];
+      const filteredNew = newFiles.filter((f) =>
+        scanInclude.some((prefix) => f.replace(/\\/g, "/").startsWith(prefix))
+      );
+      for (const f of filteredNew) {
+        raw = appendDocGraphNode(raw, {
+          path: f,
+          category: inferCategory(f),
+          role: "detected at close — review during next session",
+        });
+      }
+    }
+
+    // Apply token updates to raw YAML (comment-preserving — fixes I2/R2)
+    raw = patchYamlSection(raw, "tokens", tokens);
+
+    safeWriteFile(tokensPath, raw, "utf-8");
+    return tokens;
+  } catch (_) {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Write management files — YAML snapshot + STATUS.md update
+// ---------------------------------------------------------------------------
+
+async function writeManagementFiles(dir, snapshot, checklist, cascadeReminders, internalRegistry) {
+  const results = {};
+  const mgmtDir = join(dir, "Management");
+  if (!existsSync(mgmtDir)) mkdirSync(mgmtDir, { recursive: true });
+
+  const today = new Date().toISOString().slice(0, 10);
+
+  // --- 1. Write close-snapshot.yaml ---
+  try {
+    const yaml = (await import("js-yaml")).default;
+    const snapshotData = {
+      generated: today,
+      generator: "wwa close --write",
+      project: snapshot.project,
+      methodology_files: {
+        present: snapshot.methodologyFiles.present.map(f => f.file),
+        missing: snapshot.methodologyFiles.missing,
+        count: snapshot.methodologyFiles.present.length,
+      },
+      decisions: {
+        total: snapshot.decisions.count,
+        recent: snapshot.decisions.recent,
+      },
+      sessions: snapshot.sessions,
+      features: snapshot.features,
+      registry: snapshot.registry,
+      docs: snapshot.docsMap,
+      scale_warnings: Object.entries(snapshot.fileStats)
+        .filter(([, s]) => s.nearThreshold)
+        .map(([file, s]) => ({ file, lines: s.lines })),
+      checklist: checklist.map(c => ({ item: c.item, ok: c.ok })),
+      cascade_reminders: cascadeReminders,
+      dependency_health: snapshot.dependencyHealth || null,
+      internal_registry: internalRegistry ? {
+        generated: internalRegistry.generated || null,
+        health: internalRegistry.health || null,
+        node_count: internalRegistry.dependency_graph?.nodes?.length || 0,
+        edge_count: internalRegistry.dependency_graph?.edges?.length || 0,
+      } : null,
+    };
+
+    const yamlOutput = yaml.dump(snapshotData, { lineWidth: 120, noRefs: true, quotingType: '"' });
+    const header = [
+      "# Close Snapshot — structured session data for management and case studies",
+      `# Generated: ${today} by wwa close --write`,
+      "# Consumed by: wwa casestudy, agent close-check, management review",
+      "",
+    ].join("\n");
+
+    const snapshotPath = join(mgmtDir, "close-snapshot.yaml");
+    safeWriteFile(snapshotPath, header + yamlOutput, "utf-8");
+    results.snapshotYaml = "Management/close-snapshot.yaml";
+  } catch (_) {
+    // YAML write failed — continue with .md
+  }
+
+  // --- 2. Update STATUS.md with synthesized insights ---
+  try {
+    const statusPath = join(mgmtDir, "STATUS.md");
+    const status = generateStatusMd(snapshot, today, internalRegistry);
+    safeWriteFile(statusPath, status, "utf-8");
+    results.statusMd = "Management/STATUS.md";
+  } catch (_) {
+    // STATUS.md write failed
+  }
+
+  return results;
+}
+
+function generateStatusMd(snapshot, today, internalRegistry) {
+  const lines = [];
+  const p = snapshot.project;
+
+  lines.push(
+    "# Project Status",
+    "",
+    `<!-- Updated by wwa close --write on ${today} -->`,
+    "",
+    "## Current state",
+    "",
+    "| Field | Value |",
+    "|-------|-------|",
+    `| Phase | ${p.lifecycleStage || "unknown"} |`,
+    `| Status | active |`,
+    `| Active work | ${p.name || "unknown"} — ongoing |`,
+    `| Last milestone | Session ${snapshot.sessions.count} (${snapshot.sessions.latestDate || today}) |`,
+    `| Next milestone | — |`,
+    ""
+  );
+
+  // Recent decisions
+  lines.push("## Recent decisions", "");
+  if (snapshot.decisions.recent.length > 0) {
+    lines.push("| Date | Decision | Impact |", "|------|----------|--------|");
+    for (const d of snapshot.decisions.recent) {
+      const text = d.decision.length > 80 ? d.decision.slice(0, 77) + "..." : d.decision;
+      lines.push(`| ${d.date} | ${text} | — |`);
+    }
+  } else {
+    lines.push("No decisions recorded yet.");
+  }
+  lines.push("");
+
+  // Blockers & risks
+  lines.push(
+    "## Blockers & risks",
+    "",
+    "| Type | Description | Since | Severity |",
+    "|------|-------------|-------|----------|"
+  );
+
+  const nearThreshold = Object.entries(snapshot.fileStats).filter(([, s]) => s.nearThreshold);
+  if (nearThreshold.length > 0) {
+    for (const [file, stats] of nearThreshold) {
+      lines.push(`| risk | ${file} at ${stats.lines}/300 lines — approaching split threshold | ${today} | medium |`);
+    }
+  }
+  if (snapshot.methodologyFiles.missing.length > 0) {
+    lines.push(`| risk | Missing methodology files: ${snapshot.methodologyFiles.missing.join(", ")} | ${today} | low |`);
+  }
+  lines.push("");
+
+  // Health indicators
+  const present = snapshot.methodologyFiles.present.length;
+  const total = present + snapshot.methodologyFiles.missing.length;
+  const coverage = total > 0 ? Math.round((present / total) * 100) : 0;
+  const docsCoverage = snapshot.docsMap
+    ? `${snapshot.docsMap.docsOnDisk}/${snapshot.docsMap.inventoryCount} docs exist`
+    : "no docs map";
+
+  lines.push(
+    "## Health indicators",
+    "",
+    "| Indicator | Status | Notes |",
+    "|-----------|--------|-------|",
+    `| Methodology coverage | ${coverage}% | ${present}/${total} files present |`,
+    `| Sessions logged | ${snapshot.sessions.count} | Latest: ${snapshot.sessions.latestDate || "none"} |`,
+    `| Decisions tracked | ${snapshot.decisions.count} | Last 5 shown above |`,
+    `| Features active | ${snapshot.features.length} | ${snapshot.features.slice(0, 5).join(", ") || "none"} |`,
+    `| Docs coverage | ${docsCoverage} | ${snapshot.docsMap ? snapshot.docsMap.componentMappings + " component mappings" : "—"} |`,
+    `| Scale health | ${nearThreshold.length === 0 ? "good" : nearThreshold.length + " file(s) near threshold"} | Threshold: 300 lines |`,
+  );
+
+  if (internalRegistry?.health) {
+    const rh = internalRegistry.health;
+    const regAge = internalRegistry.generated
+      ? `generated ${internalRegistry.generated}`
+      : "unknown age";
+    lines.push(
+      `| Doc registry | ${rh.dependency_coverage || rh.dependencyCoverage || "—"} coverage | ${regAge} |`,
+    );
+  }
+
+  lines.push("");
+
+  lines.push(`---`, "", `*Updated by \`wwa close --write\` on ${today}.*`, "");
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Default cascade reminders (fallback when PROTOCOL.yaml not present)
+// ---------------------------------------------------------------------------
+
+function getDefaultReminders() {
+  return [
+    "Decision made? → STATE.md decisions table",
+    "File changed? → check cascade table",
+    "Phase complete? → SUMMARY.md + STATE.md + ROADMAP.md",
+    "High effort? → SESSION-LOG.md + Management/DIGEST.md",
+    "Structure changed? → .context/BASE.md",
+    "Milestone? → Management/STATUS.md",
+    "Docs changed? → .context/DOCS-MAP.md + docs/index.md",
+  ];
+}
+
+// ---------------------------------------------------------------------------
+// Update INDEX.yaml metrics
+// ---------------------------------------------------------------------------
+
+async function updateIndexMetrics(dir, snapshot) {
+  const indexPath = await resolveIndexPath(dir);
+  if (!existsSync(indexPath)) return null;
+
+  try {
+    const yaml = (await import("js-yaml")).default;
+    const raw = readFileSync(indexPath, "utf-8");
+    const parsed = yaml.load(raw) || {};
+    const metrics = parsed.metrics || {};
+
+    metrics.last_close = new Date().toISOString().slice(0, 10);
+    metrics.sessions = snapshot.sessions.count;
+    metrics.decisions = snapshot.decisions.count;
+
+    let nearThreshold = 0;
+    let overThreshold = 0;
+    for (const f of snapshot.methodologyFiles.present) {
+      if (f.lines >= 300) overThreshold++;
+      else if (f.lines >= 250) nearThreshold++;
+    }
+    metrics.files_near_threshold = nearThreshold;
+    metrics.files_over_threshold = overThreshold;
+
+    // Comment-preserving update of metrics section
+    if (/^metrics:/m.test(raw)) {
+      safeWriteFile(indexPath, patchYamlSection(raw, "metrics", metrics), "utf-8");
+    } else {
+      // First time — append metrics section
+      const metricsYaml = "\nmetrics:\n" + Object.entries(metrics)
+        .map(([k, v]) => `  ${k}: ${typeof v === "number" ? v : `"${v}"`}`)
+        .join("\n") + "\n";
+      safeWriteFile(indexPath, raw.trimEnd() + metricsYaml, "utf-8");
+    }
+    return metrics;
+  } catch (_) {
+    return null;
+  }
+}