agent-method 1.5.12

package/lib/cli/casestudy.js

@@ -0,0 +1,1000 @@
+/** wwa casestudy — extract a structured case study from project methodology files. */
+
+import { readFileSync, existsSync, mkdirSync } from "node:fs";
+import { resolve, join, basename, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  findEntryPoint,
+  findSessionLog,
+  safeWriteFile,
+  readMethodVersion,
+  packageRoot,
+} from "./helpers.js";
+import { resolveTokensPath, resolveDocsMapPath } from "../boundaries.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export function register(program) {
+  program
+    .command("casestudy [directory]")
+    .description(
+      "Extract a structured case study from SESSION-LOG.md and project files"
+    )
+    .option("-o, --output <path>", "Output file path")
+    .option("--name <name>", "Project name override")
+    .option("--json", "Output as JSON")
+    .option(
+      "--yaml-only",
+      "Write a .yaml case study (no markdown file; all aspects in YAML)"
+    )
+    .option("--internal-registry", "Include docs/internal/doc-registry.yaml data in output")
+    .action(async (directory, opts) => {
+      directory = directory || ".";
+      const d = resolve(directory);
+
+      // Gather all project data
+      const data = await gatherProjectData(d, opts.name);
+
+      // Load internal registry if requested
+      if (opts.internalRegistry) {
+        const { loadInternalRegistry } = await import("./doc-review.js");
+        const registry = await loadInternalRegistry(d);
+        if (registry) {
+          data.internalRegistry = registry;
+        } else {
+          data.warnings.push(
+            "No docs/internal/doc-registry.yaml found — run `wwa doc-review` to generate it"
+          );
+        }
+      }
+
+      if (data.errors.length > 0 && data.sessions.length === 0) {
+        console.error("Cannot generate case study:");
+        for (const e of data.errors) console.error(`  - ${e}`);
+        process.exit(1);
+      }
+
+      if (opts.json) {
+        const output = opts.output;
+        const result = JSON.stringify(data, null, 2);
+        if (output) {
+          safeWriteFile(output, result);
+          console.log(`Case study data written to ${output}`);
+        } else {
+          console.log(result);
+        }
+        return;
+      }
+
+      // YAML-only mode: write a single .yaml artifact with all structured data.
+      if (opts.yamlOnly) {
+        const baseDir = join(d, "case-studies");
+        const baseSlug = slugify(data.projectName);
+        let yamlOutputPath = opts.output || join(baseDir, `${baseSlug}.yaml`);
+
+        // Avoid overwriting existing case studies when using the default path.
+        if (!opts.output) {
+          let counter = 1;
+          while (existsSync(yamlOutputPath)) {
+            yamlOutputPath = join(baseDir, `${baseSlug}-${counter}.yaml`);
+            counter += 1;
+          }
+        }
+
+        const yamlDir = resolve(yamlOutputPath, "..");
+        if (!existsSync(yamlDir)) {
+          mkdirSync(yamlDir, { recursive: true });
+        }
+
+        const ok = await writeCaseStudyYaml(yamlOutputPath, data);
+        if (ok) {
+          console.log(
+            `Case study YAML written to ${yamlOutputPath} (${data.sessions.length} sessions)`
+          );
+        } else {
+          console.error("Failed to write YAML case study.");
+          process.exit(1);
+        }
+      } else {
+        // Default: write markdown case study plus companion YAML.
+        const baseDir = join(d, "case-studies");
+        const baseSlug = slugify(data.projectName);
+        let markdownPath = opts.output || join(baseDir, `${baseSlug}.md`);
+
+        // Avoid overwriting existing case studies when using the default path.
+        if (!opts.output) {
+          let counter = 1;
+          while (existsSync(markdownPath)) {
+            markdownPath = join(baseDir, `${baseSlug}-${counter}.md`);
+            counter += 1;
+          }
+        }
+
+        const outputDir = resolve(markdownPath, "..");
+        if (!existsSync(outputDir)) {
+          mkdirSync(outputDir, { recursive: true });
+        }
+
+        const caseStudy = generateCaseStudy(data);
+        safeWriteFile(markdownPath, caseStudy);
+        console.log(
+          `Case study written to ${markdownPath} (${data.sessions.length} sessions)`
+        );
+
+        const yamlPath = markdownPath.replace(/\.md$/, ".yaml");
+        const yamlResult = await writeCaseStudyYaml(yamlPath, data);
+        if (yamlResult) {
+          console.log(`Case study YAML written to ${yamlPath}`);
+        }
+      }
+
+      if (data.warnings.length > 0) {
+        console.log("\nWarnings:");
+        for (const w of data.warnings) console.log(`  - ${w}`);
+      }
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Data gathering
+// ---------------------------------------------------------------------------
+
+async function gatherProjectData(dir, nameOverride) {
+  const data = {
+    projectName: nameOverride || "Unknown Project",
+    projectType: "unknown",
+    lifecycleStart: "unknown",
+    lifecycleEnd: "unknown",
+    templateTier: "unknown",
+    extensions: "none",
+    entryPointFile: null,
+    integrationProfile: "unknown",
+    modelTier: "unknown",
+    methodVersion: null,
+    projectDescription: "",
+    studyGoals: "",
+    sessions: [],
+    decisions: [],
+    workflows: new Set(),
+    features: new Set(),
+    frictionPoints: [],
+    findings: [],
+    agentWorkflows: null,
+    tokenRegistry: null,
+    nameMappings: null,
+    docsMap: null,
+    errors: [],
+    warnings: [],
+  };
+
+  // --- Entry point ---
+  const entryPoint = findEntryPoint(dir);
+  if (entryPoint) {
+    data.entryPointFile = basename(entryPoint);
+    data.methodVersion = readMethodVersion(entryPoint);
+    const epContent = readFileSync(entryPoint, "utf-8");
+    const tierMatch = epContent.match(/tier:\s*(\S+)/);
+    if (tierMatch) data.templateTier = tierMatch[1];
+    const modeMatch = epContent.match(/mode:\s*(\S+)/);
+    if (modeMatch) data.integrationProfile = modeMatch[1];
+  } else {
+    data.warnings.push("No entry point found (CLAUDE.md / .cursorrules / AGENT.md)");
+  }
+
+  // --- PROJECT.md ---
+  const projectPath = join(dir, "PROJECT.md");
+  if (existsSync(projectPath)) {
+    const content = readFileSync(projectPath, "utf-8");
+    const titleMatch = content.match(/^#\s+(.+)/m);
+    if (titleMatch && !nameOverride) {
+      data.projectName = titleMatch[1].trim();
+    }
+    // Extract description (first paragraph after the title)
+    const descMatch = content.match(/^#[^\n]+\n+(.+?)(?:\n\n|\n##)/s);
+    if (descMatch) {
+      data.projectDescription = descMatch[1].trim();
+    }
+  } else {
+    data.warnings.push("No PROJECT.md found — project name and description may be incomplete");
+  }
+
+  // --- PROJECT-PROFILE.md ---
+  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) data.projectType = typeMatch[1].toLowerCase();
+    const stageMatch = content.match(/lifecycle.?stage[:\s|]+(\S+)/i);
+    if (stageMatch) data.lifecycleStart = stageMatch[1].toLowerCase();
+    const extMatch = content.match(/extension[s]?[:\s|]+([^\n|]+)/i);
+    if (extMatch) data.extensions = extMatch[1].trim();
+  }
+
+  // --- STATE.md (decisions) ---
+  const statePath = join(dir, "STATE.md");
+  if (existsSync(statePath)) {
+    const content = readFileSync(statePath, "utf-8");
+    // Extract decisions from table rows
+    const decisionSection = content.match(
+      /##\s*Decisions?\s*\n([\s\S]*?)(?=\n##|\n$|$)/i
+    );
+    if (decisionSection) {
+      const rows = decisionSection[1].match(/\|[^|\n]+\|[^|\n]+\|/g) || [];
+      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")) {
+          data.decisions.push({ date: cols[0], decision: cols.slice(1).join(" — ") });
+        }
+      }
+    }
+  }
+
+  // --- SESSION-LOG.md ---
+  const sessionLog = findSessionLog(dir);
+  if (sessionLog) {
+    const content = readFileSync(sessionLog, "utf-8");
+    data.sessions = parseSessionEntries(content);
+
+    // Extract project context header
+    const ctxMatch = content.match(
+      /## Project context\s*\n\s*\|[^\n]+\n\s*\|[-| ]+\n((?:\|[^\n]+\n)*)/
+    );
+    if (ctxMatch) {
+      for (const row of ctxMatch[1].trim().split("\n")) {
+        const cols = row
+          .split("|")
+          .map((c) => c.trim())
+          .filter((c) => c);
+        if (cols.length >= 2) {
+          const key = cols[0].toLowerCase();
+          if (key.includes("project name") && !nameOverride) {
+            data.projectName = cols[1];
+          }
+          if (key.includes("project type")) data.projectType = cols[1].toLowerCase();
+          if (key.includes("profile")) data.integrationProfile = cols[1];
+          if (key.includes("extension")) data.extensions = cols[1];
+          if (key.includes("model")) data.modelTier = cols[1];
+        }
+      }
+    }
+
+    // Aggregate workflows and features
+    for (const s of data.sessions) {
+      if (s.workflow) data.workflows.add(s.workflow);
+      if (s.features) {
+        for (const f of s.features.split(",").map((x) => x.trim())) {
+          if (f) data.features.add(f);
+        }
+      }
+      if (s.friction && s.friction.toLowerCase() !== "none") {
+        data.frictionPoints.push({ session: s.session, date: s.date, text: s.friction });
+      }
+      if (s.finding && s.finding.toLowerCase() !== "none") {
+        data.findings.push({ session: s.session, date: s.date, text: s.finding });
+      }
+    }
+  } else {
+    data.errors.push("No SESSION-LOG.md found — session data is required for case study extraction");
+  }
+
+  // --- agentWorkflows/INDEX.md ---
+  const wfPath = join(dir, "agentWorkflows", "INDEX.md");
+  if (existsSync(wfPath)) {
+    data.agentWorkflows = readFileSync(wfPath, "utf-8");
+  }
+
+  // --- SUMMARY.md ---
+  const summaryPath = join(dir, "SUMMARY.md");
+  if (existsSync(summaryPath)) {
+    const content = readFileSync(summaryPath, "utf-8");
+    // Count summary entries
+    const entryCount = (content.match(/^##\s+/gm) || []).length;
+    if (entryCount > 0) {
+      data.warnings.push(
+        `SUMMARY.md has ${entryCount} entries — cross-reference with session log for completeness`
+      );
+    }
+  }
+
+  // --- Token registry ---
+  // Priority: project tokens (configured path) > package docs/internal/doc-tokens.yaml
+  const projectTokensPath = await resolveTokensPath(dir);
+  const packageTokensPath = join(packageRoot, "docs", "internal", "doc-tokens.yaml");
+  try {
+    const yaml = (await import("js-yaml")).default;
+    // Load project-specific tokens (populated by wwa close)
+    if (existsSync(projectTokensPath)) {
+      const raw = readFileSync(projectTokensPath, "utf-8");
+      const parsed = yaml.load(raw);
+      if (parsed && parsed.tokens) data.tokenRegistry = parsed.tokens;
+    }
+    // Load methodology name mappings from package (always available)
+    if (existsSync(packageTokensPath)) {
+      const raw = readFileSync(packageTokensPath, "utf-8");
+      const parsed = yaml.load(raw);
+      if (parsed && parsed.names) data.nameMappings = parsed.names;
+      // If no project tokens, fall back to package tokens
+      if (!data.tokenRegistry && parsed && parsed.tokens) data.tokenRegistry = parsed.tokens;
+    }
+  } catch (_) {
+    data.warnings.push("Could not parse doc-tokens.yaml — token registry omitted");
+  }
+
+  // --- DOCS-MAP.md (from project) ---
+  const docsMapPath = await resolveDocsMapPath(dir);
+  if (existsSync(docsMapPath)) {
+    const content = readFileSync(docsMapPath, "utf-8");
+    data.docsMap = parseDocsMapForCaseStudy(content);
+  }
+
+  // Convert sets to arrays for serialization
+  data.workflows = [...data.workflows];
+  data.features = [...data.features];
+  data.lifecycleEnd = data.lifecycleStart; // default; override if detectable
+
+  return data;
+}
+
+// ---------------------------------------------------------------------------
+// Session log parsing (aligned with SESSION-LOG.md Entry format — Phase 7r §5.6)
+// ---------------------------------------------------------------------------
+
+/** Map SESSION-LOG.md field labels to canonical keys used by case study output. */
+const SESSION_LOG_KEY_MAP = {
+  "llm tokens": "tokens",
+  "wall time": "time",
+  "tool calls": "tool_calls",
+  "delta notes": "delta_notes",
+};
+
+/** Known session entry keys (Entry format); ignore parsed key:value from checklist/bullets. */
+const SESSION_ENTRY_KEYS = new Set([
+  "model", "profile", "workflow", "effort", "ambiguity", "context", "tokens", "tool_calls", "time",
+  "queries", "features", "cascades", "decisions", "response", "revisions", "magnitude", "delta",
+  "survival", "delta_notes", "friction", "finding",
+]);
+
+function parseSessionEntries(content) {
+  const entries = [];
+  // Normalize line endings and allow em dash (—) or " - " between session number, date, and title
+  const normalized = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  // Body: from the line after the title until the next "### S" session header or end of string.
+  // Use (?![\s\S]) for end-of-string so we don't stop at newlines (.(?!.) matches before \n).
+  const entryPattern =
+    /###\s+S(\d+)\s*(?:\u2014|-\s*-?)\s*(\S+)\s*(?:\u2014|-\s*-?)\s*(.+?)\n([\s\S]*?)(?=###\s+S\d+\s|(?![\s\S]))/gm;
+  let m;
+  while ((m = entryPattern.exec(normalized)) !== null) {
+    const [, num, date, title, body] = m;
+    const entry = {
+      session: parseInt(num, 10),
+      date,
+      title: title.trim(),
+    };
+
+    for (const line of body.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      // Parse pipe-delimited key: value pairs (SESSION-LOG Entry format)
+      const segments = trimmed.split("|").map((s) => s.trim());
+      for (const seg of segments) {
+        if (seg.includes(":")) {
+          const idx = seg.indexOf(":");
+          const rawKey = seg.slice(0, idx).trim().toLowerCase();
+          const val = seg.slice(idx + 1).trim();
+          if (!rawKey || !val) continue;
+          const key = SESSION_LOG_KEY_MAP[rawKey] ?? rawKey;
+          if (SESSION_ENTRY_KEYS.has(key)) entry[key] = val;
+        }
+      }
+    }
+    entries.push(entry);
+  }
+  return entries;
+}
+
+// ---------------------------------------------------------------------------
+// Case study generation
+// ---------------------------------------------------------------------------
+
+function generateCaseStudy(data) {
+  const lines = [];
+
+  // Section 1: Overview
+  lines.push(
+    `# Case Study: ${data.projectName}`,
+    "",
+    "## Overview",
+    "",
+    "| Field | Value |",
+    "|-------|-------|",
+    `| Project name | ${data.projectName} |`,
+    `| Project type | ${data.projectType} |`,
+    `| Lifecycle stage at start | ${data.lifecycleStart} |`,
+    `| Lifecycle stage at end | ${data.lifecycleEnd} |`,
+    `| Template tier | ${data.templateTier} |`,
+    `| Extensions applied | ${data.extensions} |`,
+    `| Entry point | ${data.entryPointFile || "unknown"} |`,
+    `| Integration profile | ${data.integrationProfile} |`,
+    `| Model tier | ${data.modelTier} |`,
+    `| Sessions documented | ${data.sessions.length} |`,
+    `| Method version | ${data.methodVersion || "unknown"} |`,
+    ""
+  );
+
+  if (data.projectDescription) {
+    lines.push("## Project description", "", data.projectDescription, "");
+  }
+
+  lines.push(
+    "## Study goals",
+    "",
+    "<!-- Fill in: what this case study specifically aims to validate -->",
+    ""
+  );
+
+  // Section 2: Setup
+  lines.push(
+    "---",
+    "",
+    "## Setup",
+    "",
+    "### Bootstrap experience",
+    "",
+    "| Step | Time | Friction | Notes |",
+    "|------|------|----------|-------|"
+  );
+
+  if (data.sessions.length > 0) {
+    const first = data.sessions[0];
+    lines.push(
+      `| First session (S${first.session}) | ${first.time || "unknown"} | ${first.friction || "none"} | ${first.title} |`
+    );
+  }
+
+  lines.push("");
+
+  // Section 3: Feature activation
+  lines.push(
+    "---",
+    "",
+    "## Feature activation",
+    "",
+    "### Features activated",
+    "",
+    "| Feature | Sessions | Evidence |",
+    "|---------|:--------:|----------|"
+  );
+
+  if (data.features.length > 0) {
+    for (const f of data.features.sort()) {
+      // Find which sessions activated this feature
+      const activeSessions = data.sessions
+        .filter((s) => s.features && s.features.includes(f))
+        .map((s) => `S${s.session}`)
+        .join(", ");
+      lines.push(`| ${f} | ${activeSessions} | Observed in session log |`);
+    }
+  } else {
+    lines.push("| (no features recorded) | -- | -- |");
+  }
+
+  lines.push("");
+
+  lines.push("### Workflow usage", "", "| Workflow | Sessions | Completed? |", "|---------|:--------:|:----------:|");
+  if (data.workflows.length > 0) {
+    for (const wf of data.workflows.sort()) {
+      const wfSessions = data.sessions
+        .filter((s) => s.workflow === wf)
+        .map((s) => `S${s.session}`)
+        .join(", ");
+      lines.push(`| ${wf} | ${wfSessions} | yes |`);
+    }
+  } else {
+    lines.push("| (no workflows recorded) | -- | -- |");
+  }
+  lines.push("");
+
+  // Section 4: Session log
+  lines.push("---", "", "## Session log", "");
+
+  for (const s of data.sessions) {
+    lines.push(
+      `### Session ${s.session}: ${s.title}`,
+      "",
+      "| Field | Value |",
+      "|-------|-------|",
+      `| Date | ${s.date} |`,
+      `| Model | ${s.model || "unknown"} |`,
+      `| Profile | ${s.profile || "unknown"} |`,
+      `| Effort | ${s.effort || "unknown"} |`,
+      `| Ambiguity | ${s.ambiguity || "unknown"} |`,
+      `| Context | ${s.context || "unknown"} |`,
+      `| Tokens | ${s.tokens || "unknown"} |`,
+      `| Time | ${s.time || "unknown"} |`,
+      `| Tool calls | ${s.tool_calls ?? "—"} |`,
+      `| Workflow | ${s.workflow || "unknown"} |`,
+      `| Features | ${s.features || "none"} |`,
+      `| Cascades | ${s.cascades || "unknown"} |`,
+      `| Decisions | ${s.decisions || "0"} |`,
+      `| Response | ${s.response || "unknown"} |`,
+      `| Revisions | ${s.revisions ?? "—"} |`,
+      `| Magnitude | ${s.magnitude ?? "—"} |`,
+      `| Delta | ${s.delta ?? "n/a"} |`,
+      `| Survival | ${s.survival ?? "—"} |`,
+      `| Delta notes | ${s.delta_notes ?? "n/a"} |`,
+      `| Friction | ${s.friction || "none"} |`,
+      `| Finding | ${s.finding || "none"} |`
+    );
+
+    lines.push("");
+  }
+
+  // Section 5: Scoring rubric
+  lines.push(
+    "---",
+    "",
+    "## Methodology effectiveness scoring",
+    "",
+    "Rate each dimension 1-5 with specific evidence.",
+    "",
+    "| Dimension | Score | Evidence | Notes |",
+    "|-----------|:-----:|----------|-------|"
+  );
+
+  const dimensions = [
+    "Context quality",
+    "Decision preservation",
+    "Scope discipline",
+    "Cascade coverage",
+    "Audit completeness",
+    "Bootstrap speed",
+    "Lifecycle fit",
+    "Model adequacy",
+  ];
+
+  for (const dim of dimensions) {
+    lines.push(`| ${dim} | -- | | |`);
+  }
+  lines.push("| **Overall** | -- | | |", "");
+
+  // Section 6: Findings
+  lines.push("---", "", "## Findings", "", "### What worked", "");
+
+  if (data.findings.length > 0) {
+    lines.push("| # | Finding | Session | Evidence |", "|---|---------|---------|----------|");
+    let wn = 1;
+    for (const f of data.findings) {
+      lines.push(`| W${wn} | ${f.text} | S${f.session} (${f.date}) | Session log |`);
+      wn++;
+    }
+  } else {
+    lines.push("<!-- Fill in findings from session review -->");
+  }
+
+  lines.push("", "### What needs improvement", "");
+
+  if (data.frictionPoints.length > 0) {
+    lines.push(
+      "| # | Finding | Session | Severity | Suggested change |",
+      "|---|---------|---------|----------|-----------------|"
+    );
+    let fn = 1;
+    for (const f of data.frictionPoints) {
+      lines.push(
+        `| I${fn} | ${f.text} | S${f.session} (${f.date}) | -- | <!-- suggest fix --> |`
+      );
+      fn++;
+    }
+  } else {
+    lines.push("<!-- Fill in improvement findings from session review -->");
+  }
+
+  lines.push("", "### What's missing", "", "<!-- Fill in gaps discovered during the study -->", "");
+
+  // Section 7: Refinement recommendations
+  lines.push(
+    "---",
+    "",
+    "## Refinement recommendations",
+    "",
+    "| # | Finding ref | Target | Change type | Specific change | Validation |",
+    "|---|------------|--------|-------------|-----------------|------------|"
+  );
+
+  if (data.frictionPoints.length > 0) {
+    let rn = 1;
+    for (let i = 0; i < data.frictionPoints.length; i++) {
+      lines.push(
+        `| R${rn} | I${i + 1} | <!-- target --> | <!-- type --> | <!-- change --> | <!-- validation --> |`
+      );
+      rn++;
+    }
+  } else {
+    lines.push("| R1 | -- | -- | -- | -- | -- |");
+  }
+
+  lines.push("");
+
+  // Agent workflow annotations
+  if (data.agentWorkflows) {
+    lines.push(
+      "---",
+      "",
+      "## Agent workflow annotations",
+      "",
+      "Extracted from agentWorkflows/INDEX.md:",
+      "",
+      data.agentWorkflows,
+      ""
+    );
+  }
+
+  // Statistics summary
+  lines.push(
+    "---",
+    "",
+    "## Statistics",
+    "",
+    `- **Total sessions**: ${data.sessions.length}`,
+    `- **Workflows used**: ${data.workflows.join(", ") || "none recorded"}`,
+    `- **Features observed**: ${data.features.length}`,
+    `- **Decisions recorded**: ${data.decisions.length}`,
+    `- **Friction points**: ${data.frictionPoints.length}`,
+    `- **Findings**: ${data.findings.length}`,
+    ""
+  );
+
+  // Methodology reference data
+  if (data.tokenRegistry || data.nameMappings || data.docsMap) {
+    lines.push("---", "", "## Methodology reference data", "");
+  }
+
+  if (data.tokenRegistry) {
+    lines.push("### Token registry snapshot", "");
+    lines.push("| Token | Value |", "|-------|-------|");
+    const keySubset = [
+      "registry_version", "feature_count", "domain_count", "directive_count",
+      "workflow_count", "query_pattern_count", "starter_file_count", "full_file_count",
+      "max_file_lines", "cli_command", "npm_package", "pip_package",
+      "developer_cmd_count", "pipeline_cmd_count", "total_cmd_count",
+    ];
+    for (const key of keySubset) {
+      if (data.tokenRegistry[key] !== undefined) {
+        lines.push(`| ${key} | ${data.tokenRegistry[key]} |`);
+      }
+    }
+    lines.push("");
+  }
+
+  if (data.nameMappings) {
+    lines.push("### Name mappings", "");
+
+    if (data.nameMappings.project_types) {
+      lines.push("**Project types**", "", "| Canonical | CLI alias |", "|-----------|-----------|");
+      for (const t of data.nameMappings.project_types) {
+        lines.push(`| ${t.canonical} | ${t.cli_alias || "—"} |`);
+      }
+      lines.push("");
+    }
+
+    if (data.nameMappings.guided_workflows) {
+      lines.push("**Workflows**", "", "| ID | Name | Stages |", "|----|------|--------|");
+      for (const wf of data.nameMappings.guided_workflows) {
+        lines.push(`| ${wf.id} | ${wf.display} | ${wf.context || ""} |`);
+      }
+      lines.push("");
+    }
+
+    if (data.nameMappings.feature_domains) {
+      lines.push("**Feature domains**", "", "| ID | Domain | Range |", "|----|--------|-------|");
+      for (const d of data.nameMappings.feature_domains) {
+        lines.push(`| ${d.id} | ${d.canonical} | ${d.feature_range} |`);
+      }
+      lines.push("");
+    }
+
+    if (data.nameMappings.protocol_directives) {
+      lines.push("**Protocol directives**", "", "| ID | Name | Rule |", "|----|------|------|");
+      for (const p of data.nameMappings.protocol_directives) {
+        lines.push(`| ${p.id} | ${p.canonical} | ${p.short} |`);
+      }
+      lines.push("");
+    }
+  }
+
+  if (data.docsMap) {
+    lines.push("### Docs dependency map", "");
+    if (data.docsMap.inventory.length > 0) {
+      lines.push("**Docs inventory**", "", "| Path | Purpose | Status |", "|------|---------|--------|");
+      for (const item of data.docsMap.inventory) {
+        lines.push(`| ${item.path} | ${item.purpose} | ${item.status} |`);
+      }
+      lines.push("");
+    }
+    if (data.docsMap.mappings.length > 0) {
+      lines.push("**Component mappings**", "", "| Component | Documented in | Trigger |", "|-----------|--------------|---------|");
+      for (const m of data.docsMap.mappings) {
+        lines.push(`| ${m.component} | ${m.documentedIn} | ${m.trigger} |`);
+      }
+      lines.push("");
+    }
+    lines.push(`**Scaffolding rules**: ${data.docsMap.scaffolding.length} active`, "");
+  }
+
+  // Internal document registry (when --internal-registry is used)
+  if (data.internalRegistry) {
+    lines.push("---", "", "## Internal document registry", "");
+    const reg = data.internalRegistry;
+
+    if (reg.health) {
+      lines.push(
+        "### Registry health",
+        "",
+        "| Metric | Value |",
+        "|--------|-------|",
+        `| Total nodes | ${reg.health.totalDocs ?? reg.health.total_docs ?? "—"} |`,
+        `| Nodes on disk | ${reg.health.docsOnDisk ?? reg.health.docs_on_disk ?? "—"} |`,
+        `| Orphan nodes | ${reg.health.orphanNodes ?? reg.health.orphan_nodes ?? "—"} |`,
+        `| Dependency coverage | ${reg.health.dependencyCoverage ?? reg.health.dependency_coverage ?? "—"} |`,
+        ""
+      );
+    }
+
+    if (reg.dependency_graph?.read_order?.length > 0) {
+      lines.push("### Dependency read order", "");
+      for (let i = 0; i < reg.dependency_graph.read_order.length; i++) {
+        lines.push(`${i + 1}. \`${reg.dependency_graph.read_order[i]}\``);
+      }
+      lines.push("");
+    }
+
+    if (reg.terminology) {
+      const t = reg.terminology;
+      const termCount =
+        (t.modules?.length || 0) +
+        (t.apis?.length || 0) +
+        (t.entities?.length || 0) +
+        (t.conventions?.length || 0);
+      lines.push(`### Terminology snapshot`, "", `${termCount} term(s) captured across modules, APIs, entities, and conventions.`, "");
+    }
+  }
+
+  // Synthesized analysis — agent-level understanding from session metrics
+  lines.push("---", "", "## Synthesized analysis", "");
+  lines.push(generateSynthesizedAnalysis(data), "");
+
+  lines.push("---", "", "*Generated by `wwa casestudy` from project methodology files.*", "");
+
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+
+function generateSynthesizedAnalysis(data) {
+  const lines = [];
+
+  // Effort distribution
+  const effortDist = {};
+  const ambiguityDist = {};
+  const responseDist = {};
+  let totalCascades = 0;
+  let highEffortCount = 0;
+
+  for (const s of data.sessions) {
+    if (s.effort) effortDist[s.effort] = (effortDist[s.effort] || 0) + 1;
+    if (s.ambiguity) ambiguityDist[s.ambiguity] = (ambiguityDist[s.ambiguity] || 0) + 1;
+    if (s.response) responseDist[s.response] = (responseDist[s.response] || 0) + 1;
+    if (s.cascades) totalCascades += parseInt(s.cascades, 10) || 0;
+    if (s.effort === "high") highEffortCount++;
+  }
+
+  lines.push("### Session profile");
+  lines.push("");
+  lines.push(`- **${data.sessions.length} sessions** across ${data.workflows.length} workflow type(s)`);
+
+  const effortSummary = Object.entries(effortDist).map(([k, v]) => `${k}: ${v}`).join(", ");
+  if (effortSummary) lines.push(`- Effort distribution: ${effortSummary}`);
+
+  const ambiguitySummary = Object.entries(ambiguityDist).map(([k, v]) => `${k}: ${v}`).join(", ");
+  if (ambiguitySummary) lines.push(`- Ambiguity distribution: ${ambiguitySummary}`);
+
+  const responseSummary = Object.entries(responseDist).map(([k, v]) => `${k}: ${v}`).join(", ");
+  if (responseSummary) lines.push(`- Response outcomes: ${responseSummary}`);
+
+  lines.push(`- Total cascades triggered: ${totalCascades}`);
+  lines.push(`- High-effort sessions: ${highEffortCount}/${data.sessions.length}`);
+  lines.push("");
+
+  // Feature coverage
+  lines.push("### Feature coverage");
+  lines.push("");
+  if (data.features.length > 0) {
+    lines.push(`${data.features.length} features activated: ${data.features.join(", ")}`);
+  } else {
+    lines.push("No features explicitly tracked in session log.");
+  }
+  lines.push("");
+
+  // Methodology health
+  lines.push("### Methodology health signals");
+  lines.push("");
+
+  const acceptedCount = responseDist["accepted"] || 0;
+  const totalResponses = Object.values(responseDist).reduce((a, b) => a + b, 0);
+  if (totalResponses > 0) {
+    const acceptRate = Math.round((acceptedCount / totalResponses) * 100);
+    lines.push(`- Acceptance rate: ${acceptRate}% (${acceptedCount}/${totalResponses} sessions)`);
+  }
+
+  if (data.frictionPoints.length > 0) {
+    lines.push(`- Friction points: ${data.frictionPoints.length} recorded`);
+    const frictionSessions = data.frictionPoints.map(f => `S${f.session}`).join(", ");
+    lines.push(`  - Sessions with friction: ${frictionSessions}`);
+  } else {
+    lines.push("- No friction points recorded — either smooth workflow or under-reporting");
+  }
+
+  if (data.findings.length > 0) {
+    lines.push(`- Findings: ${data.findings.length} methodology-relevant observations`);
+  }
+
+  lines.push(`- Decisions logged: ${data.decisions.length}`);
+  lines.push("");
+
+  // Lifecycle assessment
+  lines.push("### Lifecycle assessment");
+  lines.push("");
+  lines.push(`Project type \`${data.projectType}\` at lifecycle stage \`${data.lifecycleStart}\` using \`${data.templateTier}\` tier.`);
+
+  if (data.templateTier === "standard" && highEffortCount > 5) {
+    lines.push("Consider upgrading to **full** tier — high-effort session count suggests complex project needing REQUIREMENTS.md and REGISTRY.md.");
+  }
+  if (data.templateTier === "full" && data.sessions.length > 0 && highEffortCount === 0) {
+    lines.push("Full tier may be over-provisioned — no high-effort sessions recorded. Standard tier may suffice.");
+  }
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+function parseDocsMapForCaseStudy(content) {
+  const result = { inventory: [], mappings: [], scaffolding: [] };
+
+  const parseTable = (sectionName) => {
+    const re = new RegExp(
+      `## ${sectionName}[ \\t]*\\n\\n?\\|[^\\n]+\\n\\|[-| :]+\\n((?:\\|[^\\n]+\\n)*)`,
+    );
+    const m = content.match(re);
+    if (!m) return [];
+    return m[1].trim().split("\n").map((row) => {
+      const cols = row.split("|").map((c) => c.trim()).filter((c) => c && !c.startsWith("<!--"));
+      return cols;
+    }).filter((cols) => cols.length >= 2);
+  };
+
+  for (const cols of parseTable("Docs inventory")) {
+    result.inventory.push({ path: cols[0], purpose: cols[1], sources: cols[2] || "", status: cols[3] || "" });
+  }
+  for (const cols of parseTable("Component-to-docs mapping")) {
+    result.mappings.push({ component: cols[0], documentedIn: cols[1], trigger: cols[2] || "" });
+  }
+  for (const cols of parseTable("Scaffolding rules")) {
+    result.scaffolding.push({ condition: cols[0], proposedDoc: cols[1], seedFrom: cols[2] || "" });
+  }
+
+  return result;
+}
+
+async function writeCaseStudyYaml(yamlPath, data) {
+  try {
+    const yaml = (await import("js-yaml")).default;
+    const today = new Date().toISOString().slice(0, 10);
+
+    // Compute session metrics summary
+    const effortDist = {};
+    const ambiguityDist = {};
+    const responseDist = {};
+    let totalCascades = 0;
+    let totalDecisionsSessions = 0;
+
+    for (const s of data.sessions) {
+      if (s.effort) effortDist[s.effort] = (effortDist[s.effort] || 0) + 1;
+      if (s.ambiguity) ambiguityDist[s.ambiguity] = (ambiguityDist[s.ambiguity] || 0) + 1;
+      if (s.response) responseDist[s.response] = (responseDist[s.response] || 0) + 1;
+      if (s.cascades) totalCascades += parseInt(s.cascades, 10) || 0;
+      if (s.decisions) totalDecisionsSessions += parseInt(s.decisions, 10) || 0;
+    }
+
+    const structured = {
+      generated: today,
+      generator: "wwa casestudy",
+      overview: {
+        project_name: data.projectName,
+        project_type: data.projectType,
+        lifecycle_start: data.lifecycleStart,
+        lifecycle_end: data.lifecycleEnd,
+        template_tier: data.templateTier,
+        extensions: data.extensions,
+        entry_point: data.entryPointFile,
+        integration_profile: data.integrationProfile,
+        model_tier: data.modelTier,
+        method_version: data.methodVersion,
+      },
+      session_metrics: {
+        total_sessions: data.sessions.length,
+        effort_distribution: effortDist,
+        ambiguity_distribution: ambiguityDist,
+        response_distribution: responseDist,
+        total_cascades: totalCascades,
+        total_decisions_in_sessions: totalDecisionsSessions,
+        workflows_used: data.workflows,
+        features_activated: data.features,
+      },
+      sessions: data.sessions.map(s => ({
+        session: s.session,
+        date: s.date,
+        title: s.title,
+        model: s.model || null,
+        profile: s.profile || null,
+        effort: s.effort || null,
+        ambiguity: s.ambiguity || null,
+        context: s.context || null,
+        tokens: s.tokens || null,
+        tool_calls: s.tool_calls || null,
+        time: s.time || null,
+        workflow: s.workflow || null,
+        features: s.features || null,
+        cascades: s.cascades || null,
+        decisions: s.decisions || null,
+        response: s.response || null,
+        revisions: s.revisions || null,
+        magnitude: s.magnitude || null,
+        delta: s.delta || null,
+        survival: s.survival || null,
+        delta_notes: s.delta_notes || null,
+        friction: s.friction || null,
+        finding: s.finding || null,
+      })),
+      decisions: data.decisions,
+      friction_points: data.frictionPoints,
+      findings: data.findings,
+      token_registry: data.tokenRegistry,
+      name_mappings: data.nameMappings ? {
+        project_types: data.nameMappings.project_types || null,
+        guided_workflows: data.nameMappings.guided_workflows || null,
+        feature_domains: data.nameMappings.feature_domains || null,
+        protocol_directives: data.nameMappings.protocol_directives || null,
+      } : null,
+      docs_map: data.docsMap,
+      internal_registry: data.internalRegistry || null,
+    };
+
+    const yamlOutput = yaml.dump(structured, { lineWidth: 120, noRefs: true, quotingType: '"' });
+    const header = [
+      "# Case Study — structured session metrics and methodology data",
+      `# Project: ${data.projectName}`,
+      `# Generated: ${today} by wwa casestudy`,
+      "# Companion to: " + yamlPath.replace(/\.yaml$/, ".md"),
+      "",
+    ].join("\n");
+
+    safeWriteFile(yamlPath, header + yamlOutput, "utf-8");
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+function slugify(name) {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    || "project";
+}