@thejoseki/clawform 0.0.1 → 2.2.1

package/src/aws/changeset.js

@@ -0,0 +1,231 @@
+import {
+  CreateChangeSetCommand,
+  DescribeChangeSetCommand,
+  DeleteChangeSetCommand,
+  DescribeStacksCommand,
+  DescribeStackEventsCommand,
+  ExecuteChangeSetCommand,
+} from '@aws-sdk/client-cloudformation';
+import { isDataResource } from '../lib/constants.js';
+
+const DEPLOYABLE_FROM_UPDATE = new Set([
+  'CREATE_COMPLETE',
+  'UPDATE_COMPLETE',
+  'UPDATE_ROLLBACK_COMPLETE',
+  'IMPORT_COMPLETE',
+  'IMPORT_ROLLBACK_COMPLETE',
+]);
+
+const TERMINAL_EXECUTE_STATUSES = new Set([
+  'CREATE_COMPLETE',
+  'UPDATE_COMPLETE',
+  'ROLLBACK_COMPLETE',
+  'UPDATE_ROLLBACK_COMPLETE',
+  'CREATE_FAILED',
+  'ROLLBACK_FAILED',
+  'UPDATE_ROLLBACK_FAILED',
+  'UPDATE_FAILED',
+  'DELETE_COMPLETE',
+  'DELETE_FAILED',
+]);
+
+const EMPTY_CHANGESET_RE = /didn'?t contain changes|no updates are to be performed/i;
+
+export async function stackStatus(client, stackName) {
+  try {
+    const out = await client.send(new DescribeStacksCommand({ StackName: stackName }));
+    const stack = out.Stacks?.[0];
+    if (!stack) return { exists: false };
+    return { exists: true, status: stack.StackStatus, stack };
+  } catch (err) {
+    if (err.name === 'ValidationError' && /does not exist/i.test(err.message ?? '')) {
+      return { exists: false };
+    }
+    throw err;
+  }
+}
+
+export function decideChangeSetType({ exists, status }) {
+  if (!exists) return 'CREATE';
+  if (status === 'REVIEW_IN_PROGRESS') return 'CREATE';
+  if (DEPLOYABLE_FROM_UPDATE.has(status)) return 'UPDATE';
+  if (/_IN_PROGRESS$/.test(status)) {
+    throw new Error(`Stack is ${status}; another operation is running. Wait or check the console.`);
+  }
+  throw new Error(`Stack is in ${status}; use /rollback to recover before deploying.`);
+}
+
+export function changeSetName(prefix = 'claude') {
+  const d = new Date();
+  const pad = (n) => String(n).padStart(2, '0');
+  const stamp = `${d.getUTCFullYear()}${pad(d.getUTCMonth() + 1)}${pad(d.getUTCDate())}-${pad(d.getUTCHours())}${pad(d.getUTCMinutes())}${pad(d.getUTCSeconds())}`;
+  return `${prefix}-${stamp}`;
+}
+
+export async function createAndWait(client, {
+  stackName,
+  changeSetType,
+  templateBody,
+  parameters = [],
+  tags = [],
+  capabilities = [],
+  name = changeSetName(),
+  pollIntervalMs = 2000,
+  timeoutMs = 5 * 60 * 1000,
+}) {
+  await client.send(new CreateChangeSetCommand({
+    StackName: stackName,
+    ChangeSetName: name,
+    ChangeSetType: changeSetType,
+    TemplateBody: templateBody,
+    Parameters: parameters,
+    Tags: tags,
+    Capabilities: capabilities,
+  }));
+
+  const started = Date.now();
+  while (true) {
+    const desc = await describeFull(client, stackName, name);
+    if (desc.Status === 'CREATE_COMPLETE') {
+      return {
+        name,
+        id: desc.ChangeSetId,
+        isEmpty: false,
+        changes: desc.Changes ?? [],
+        statusReason: desc.StatusReason ?? null,
+      };
+    }
+    if (desc.Status === 'FAILED') {
+      if (EMPTY_CHANGESET_RE.test(desc.StatusReason ?? '')) {
+        await safeDelete(client, stackName, name);
+        return { name, id: desc.ChangeSetId, isEmpty: true, changes: [], statusReason: desc.StatusReason };
+      }
+      throw new Error(`Change-set creation failed: ${desc.StatusReason ?? '(no reason)'}`);
+    }
+    if (Date.now() - started > timeoutMs) {
+      throw new Error(`Timed out after ${Math.round(timeoutMs / 1000)}s waiting for change-set ${name} to be ready (last status: ${desc.Status}).`);
+    }
+    await sleep(pollIntervalMs);
+  }
+}
+
+async function describeFull(client, stackName, name) {
+  const all = [];
+  let nextToken;
+  let first;
+  do {
+    const out = await client.send(new DescribeChangeSetCommand({
+      StackName: stackName,
+      ChangeSetName: name,
+      NextToken: nextToken,
+    }));
+    if (!first) first = out;
+    for (const c of out.Changes ?? []) all.push(c);
+    nextToken = out.NextToken;
+  } while (nextToken);
+  return { ...first, Changes: all };
+}
+
+async function safeDelete(client, stackName, name) {
+  try {
+    await client.send(new DeleteChangeSetCommand({ StackName: stackName, ChangeSetName: name }));
+  } catch {
+    // Empty change-sets sometimes auto-clean; ignore deletion errors here.
+  }
+}
+
+export function classifyChanges(changes) {
+  const buckets = { add: [], modify: [], replace: [], remove: [], dataResourceReplace: [] };
+  for (const c of changes) {
+    if (c.Type !== 'Resource' || !c.ResourceChange) continue;
+    const rc = c.ResourceChange;
+    const entry = {
+      logicalId: rc.LogicalResourceId,
+      physicalId: rc.PhysicalResourceId ?? null,
+      resourceType: rc.ResourceType,
+      replacement: rc.Replacement,
+      scope: rc.Scope ?? [],
+      detailsTargets: (rc.Details ?? []).map((d) => d.Target?.Attribute).filter(Boolean),
+    };
+    switch (rc.Action) {
+      case 'Add':
+        buckets.add.push(entry);
+        break;
+      case 'Remove':
+        buckets.remove.push(entry);
+        break;
+      case 'Modify':
+        if (rc.Replacement === 'True' || rc.Replacement === 'Conditional') {
+          buckets.replace.push(entry);
+          if (isDataResource(rc.ResourceType)) buckets.dataResourceReplace.push(entry);
+        } else {
+          buckets.modify.push(entry);
+        }
+        break;
+      default:
+        buckets.modify.push(entry);
+    }
+  }
+  return buckets;
+}
+
+export async function executeAndPoll(client, {
+  stackName,
+  changeSetName: name,
+  onEvent = () => {},
+  pollIntervalMs = 3000,
+  timeoutMs = 60 * 60 * 1000,
+}) {
+  await client.send(new ExecuteChangeSetCommand({ StackName: stackName, ChangeSetName: name }));
+
+  const seen = new Set();
+  const started = Date.now();
+  while (true) {
+    const events = await fetchEvents(client, stackName, seen);
+    for (const ev of events) {
+      if (seen.has(ev.EventId)) continue;
+      seen.add(ev.EventId);
+      onEvent(ev);
+    }
+
+    const { stack } = await stackStatus(client, stackName);
+    const status = stack?.StackStatus;
+    if (status && TERMINAL_EXECUTE_STATUSES.has(status)) {
+      return { stackStatus: status, stack };
+    }
+    if (Date.now() - started > timeoutMs) {
+      throw new Error(`Timed out after ${Math.round(timeoutMs / 60000)}m waiting for stack ${stackName} (last status: ${status}).`);
+    }
+    await sleep(pollIntervalMs);
+  }
+}
+
+// Paginate DescribeStackEvents until we encounter an event we've already narrated.
+// DescribeStackEvents returns newest-first within a page AND pages are newest-first,
+// so once we hit a known EventId every older event is also already in `seen` — safe
+// to stop. Without this, a poll window emitting >100 events (large stacks, nested-
+// stack expansion, rollback fan-out) silently drops the older end off page 1 and
+// onEvent is never called for them — the operator misses CREATE_FAILED rows that
+// scrolled off between polls. (Tracked as merged_bug_008 from ultrareview.)
+export async function fetchEvents(client, stackName, seen = new Set()) {
+  const events = [];
+  let nextToken;
+  do {
+    const resp = await client.send(new DescribeStackEventsCommand({
+      StackName: stackName,
+      NextToken: nextToken,
+    }));
+    let stopHere = false;
+    for (const ev of resp.StackEvents ?? []) {
+      if (seen.has(ev.EventId)) { stopHere = true; break; }
+      events.push(ev);
+    }
+    if (stopHere) break;
+    nextToken = resp.NextToken;
+  } while (nextToken);
+  return events.reverse(); // present oldest-first for narration
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}

package/src/aws/drift.js

@@ -0,0 +1,59 @@
+import {
+  DetectStackDriftCommand,
+  DescribeStackDriftDetectionStatusCommand,
+  DescribeStackResourceDriftsCommand,
+} from '@aws-sdk/client-cloudformation';
+
+const TERMINAL = new Set(['DETECTION_COMPLETE', 'DETECTION_FAILED']);
+
+export async function detectAndWait(client, {
+  stackName,
+  pollIntervalMs = 3000,
+  timeoutMs = 10 * 60 * 1000,
+}) {
+  const { StackDriftDetectionId } = await client.send(new DetectStackDriftCommand({ StackName: stackName }));
+
+  const started = Date.now();
+  while (true) {
+    const out = await client.send(new DescribeStackDriftDetectionStatusCommand({ StackDriftDetectionId }));
+    if (TERMINAL.has(out.DetectionStatus)) {
+      if (out.DetectionStatus === 'DETECTION_FAILED') {
+        throw new Error(`Drift detection failed for ${stackName}: ${out.DetectionStatusReason ?? '(no reason)'}`);
+      }
+      return {
+        stackDriftStatus: out.StackDriftStatus,
+        driftedResourceCount: out.DriftedStackResourceCount ?? 0,
+      };
+    }
+    if (Date.now() - started > timeoutMs) {
+      throw new Error(`Timed out after ${Math.round(timeoutMs / 60000)}m waiting for drift detection on ${stackName}.`);
+    }
+    await sleep(pollIntervalMs);
+  }
+}
+
+export async function listResourceDrifts(client, stackName, statusFilter = ['MODIFIED', 'DELETED']) {
+  const drifts = [];
+  let nextToken;
+  do {
+    const out = await client.send(new DescribeStackResourceDriftsCommand({
+      StackName: stackName,
+      StackResourceDriftStatusFilters: statusFilter,
+      NextToken: nextToken,
+    }));
+    for (const d of out.StackResourceDrifts ?? []) {
+      drifts.push({
+        logicalId: d.LogicalResourceId,
+        resourceType: d.ResourceType,
+        driftStatus: d.StackResourceDriftStatus,
+        propertyDifferences: d.PropertyDifferences ?? [],
+      });
+    }
+    nextToken = out.NextToken;
+  } while (nextToken);
+  return drifts;
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}

package/src/aws/exports.js

@@ -0,0 +1,213 @@
+// Pre-flight checks on a stack's CloudFormation exports.
+//
+// Two day-2 traps live here, both computed from the LIVE stack's Outputs (which
+// CloudFormation reports with resolved OutputKey + ExportName) so neither needs
+// to resolve template intrinsics:
+//
+//   1. Export-lock (C1) — removing or un-exporting an Output whose export is
+//      still imported by another stack. CloudFormation rejects this at execute
+//      time with "Export <name> ... in use by <stack>", AFTER partial work and a
+//      rollback. We detect it before the changeset so the operator gets the
+//      two-step migration guidance instead of a wedged stack. See rules/limits.md.
+//
+//   2. Frozen-export (C2) — a stack whose NAME doesn't match a legacy prefix but
+//      that emits legacy-prefixed EXPORT names (e.g. stack `d-cfn-aao-vpc`
+//      exporting `OLDNET-VPC`). The name-only legacy gate in the PreToolUse hook
+//      can't see this (it's pure, no AWS access); the CLI can, because it has
+//      already fetched the live Outputs. See rules/legacy-freeze.md.
+
+import { ListImportsCommand } from '@aws-sdk/client-cloudformation';
+import { logger } from '../lib/logger.js';
+import { readEnv, ENV_PREFIX } from '../lib/rename-compat.js';
+
+// --- C1: export-lock --------------------------------------------------------
+
+/**
+ * Live exports that the new template would remove.
+ *
+ * An export is "removed" when a live Output that carries an ExportName:
+ *   - has an OutputKey NOT in `templateExportingKeys` (the set of Output keys
+ *     the new template still exports — from extractExportingOutputKeys()), AND
+ *   - has an ExportName NOT in `templateLiteralExportNames` (the literal
+ *     Export.Name strings in the new template — from extractLiteralExportNames()).
+ *
+ * The second condition kills the OutputKey-rename false positive: renaming the
+ * logical key while keeping the same literal Export.Name moves the export, it
+ * doesn't remove it, and CloudFormation executes that fine. Intrinsic export
+ * names (`!Sub …`) can't be matched offline — an export moved to a key whose
+ * name became an intrinsic may still be flagged; ListImports then decides.
+ *
+ * Catches both "Output deleted entirely" and "Output kept but Export block
+ * dropped". NOT caught (documented in rules/limits.md): an in-place rename that
+ * keeps the OutputKey but changes Export.Name.
+ *
+ * @param liveOutputs               stack.Outputs from DescribeStacks: [{OutputKey, OutputValue, ExportName}]
+ * @param templateExportingKeys     Set<string> of OutputKeys the new template exports
+ * @param templateLiteralExportNames Set<string> of literal Export.Name strings in the new template
+ * @returns Array<{ outputKey, exportName }>
+ */
+export function findRemovedExports(liveOutputs, templateExportingKeys, templateLiteralExportNames = new Set()) {
+  const keys = templateExportingKeys instanceof Set ? templateExportingKeys : new Set(templateExportingKeys ?? []);
+  const out = [];
+  for (const o of liveOutputs ?? []) {
+    if (!o || !o.ExportName) continue; // only exported outputs can hit the lock
+    if (keys.has(o.OutputKey)) continue;                      // still exported under the same key
+    if (templateLiteralExportNames.has(o.ExportName)) continue; // moved to another key, same export name
+    out.push({ outputKey: o.OutputKey, exportName: o.ExportName });
+  }
+  return out;
+}
+
+/**
+ * Paginate ListImports for one export name. Importers found so far are pushed
+ * into `sink` page-by-page, so a caller that catches a mid-pagination error
+ * still sees the importers already confirmed — checkExportLock uses this to
+ * fail CLOSED on partial proof.
+ *
+ * Hand-rolled NextToken loop instead of the SDK's paginateListImports on
+ * purpose: the generated paginators hard-check `client instanceof
+ * CloudFormationClient`, which would break every mocked-client test at this
+ * seam (catalog.js/inventory.js can use them because they only ever run
+ * against the real client).
+ */
+export async function listImportsFor(client, exportName, sink = []) {
+  let nextToken;
+  do {
+    const resp = await client.send(new ListImportsCommand({ ExportName: exportName, NextToken: nextToken }));
+    for (const imp of resp.Imports ?? []) sink.push(imp);
+    nextToken = resp.NextToken;
+  } while (nextToken);
+  return sink;
+}
+
+/**
+ * For each removed export, ask CloudFormation who still imports it. The
+ * per-export checks are independent, so they run concurrently.
+ *
+ * Failure posture:
+ *   - A confirmed in-use export → fail CLOSED (caller blocks the deploy): the
+ *     changeset is guaranteed to fail, so blocking pre-flight strictly helps.
+ *     This includes PARTIAL proof — importers seen on page 1 before page 2
+ *     threw still block.
+ *   - Our own inability to check (ListImports throws with zero importers seen —
+ *     e.g. missing cloudformation:ListImports permission) → fail OPEN: record
+ *     the error and let the deploy proceed rather than block on a check we
+ *     couldn't run. CloudFormation still refuses a genuinely in-use removal.
+ *
+ * AWS quirk: ListImports throws a ValidationError ("Export ... is not imported
+ * by any stack") when an export has zero importers. That's a CLEAN result, not
+ * an error — treated as "no importers", not fail-open.
+ *
+ * @returns { blocked: Array<{exportName, importers}>, unchecked: Array<{exportName, error}> }
+ */
+export async function checkExportLock(client, removedExports) {
+  const results = await Promise.all((removedExports ?? []).map(async ({ exportName }) => {
+    const importers = [];
+    try {
+      await listImportsFor(client, exportName, importers);
+      return importers.length > 0 ? { blocked: { exportName, importers } } : {};
+    } catch (err) {
+      if (importers.length > 0) return { blocked: { exportName, importers } }; // partial proof → fail closed
+      if (isNotImportedError(err)) return {}; // zero importers — safe to remove
+      return { unchecked: { exportName, error: err?.message ?? String(err) } };
+    }
+  }));
+  return {
+    blocked: results.map((r) => r.blocked).filter(Boolean),
+    unchecked: results.map((r) => r.unchecked).filter(Boolean),
+  };
+}
+
+function isNotImportedError(err) {
+  const msg = err?.message ?? '';
+  return err?.name === 'ValidationError' && /is not imported by any stack/i.test(msg);
+}
+
+// --- C2: frozen-export ------------------------------------------------------
+
+/**
+ * Live export names matching the consumer's legacy prefixes.
+ *
+ * `legacyRe` must be the ANCHORED regex (buildAnchoredLegacyPrefixRegex) — the
+ * prefix has to be the export name's LEADING segment. The hook's unanchored
+ * command-line regex would false-positive on legacy tokens mid-name
+ * (`p-acme-pri-lmd-payroll-OLDAPP-arn`). Null regex = no gate (fresh consumer).
+ *
+ * @returns Array<{ outputKey, exportName }>
+ */
+export function findFrozenExports(liveOutputs, legacyRe) {
+  if (!legacyRe) return [];
+  const out = [];
+  for (const o of liveOutputs ?? []) {
+    if (!o || !o.ExportName) continue;
+    if (legacyRe.test(o.ExportName)) {
+      out.push({ outputKey: o.OutputKey, exportName: o.ExportName });
+    }
+  }
+  return out;
+}
+
+// Break-glass for the frozen-export gates (mirrors CLAWFORM_SKIP_ACCOUNT_CHECK):
+// intentionally a noisy env var, not a CLI flag. Needed because a frozen-named
+// export, once live, would otherwise also block the remediation deploy that
+// removes it — and unlike the stack-NAME freeze there is no `# FORCE LEGACY`
+// hook path here (the hook never sees export names).
+// Suffix for the lookup, full name for anything a human reads.
+const SKIP_FROZEN_SUFFIX = 'SKIP_FROZEN_EXPORT_CHECK';
+const SKIP_FROZEN_ENV = `${ENV_PREFIX}${SKIP_FROZEN_SUFFIX}`;
+
+export function frozenExportCheckSkipped(action) {
+  if (readEnv(SKIP_FROZEN_SUFFIX) !== '1') return false;
+  logger.warn(
+    `${SKIP_FROZEN_ENV}=1 — bypassing the frozen-export gate for this ${action}. ` +
+    `Break-glass only; unset to re-enable.`,
+  );
+  return true;
+}
+
+/**
+ * Shared C2 gate for deploy AND rollback: refuse a stack that EMITS
+ * legacy-prefixed export names, even when the stack NAME isn't frozen. Closes
+ * the "stack-name-only" gap in rules/legacy-freeze.md.
+ *
+ * @param action  'deploy' | 'recovery' — only changes the refusal wording.
+ * Throws on a frozen export. Returns void when clean / skipped via break-glass.
+ */
+export function assertNoFrozenExports({ liveOutputs, legacyRe, stackName, action = 'deploy' } = {}) {
+  const frozen = findFrozenExports(liveOutputs, legacyRe);
+  if (frozen.length === 0) return;
+  if (frozenExportCheckSkipped(action)) return;
+  const names = frozen.map((f) => f.exportName).join(', ');
+  throw new Error(
+    `Stack "${stackName}" emits export(s) matching a legacy prefix (${names}) from your clawform.config.json ` +
+    `legacy_prefixes — even though the stack NAME isn't frozen. Clawform treats legacy-named exports as frozen ` +
+    `too (rules/legacy-freeze.md). Refusing ${action === 'recovery' ? 'recovery' : 'to deploy'}.\n` +
+    `If this is intentional (e.g. retiring the legacy-named export itself), re-run with ` +
+    `${SKIP_FROZEN_ENV}=1, or use the raw aws cloudformation CLI.`,
+  );
+}
+
+/**
+ * C2 introduction gate: refuse a TEMPLATE whose literal Export.Name strings
+ * would CREATE a legacy-prefixed export. Without this, deploy would happily
+ * mint e.g. `OLDNET-NewThing` on a clean-named stack (the live-outputs gate only
+ * sees exports that already exist) — and the live gate would then freeze the
+ * stack against its own tooling. Intrinsic Export.Names can't be checked
+ * offline; legacy names are literal in practice.
+ *
+ * @param templateExportNames  Set<string> from extractLiteralExportNames()
+ * Throws when a frozen name would be introduced. Honors the same break-glass.
+ */
+export function assertNoFrozenTemplateExports({ templateExportNames, legacyRe, stackName } = {}) {
+  if (!legacyRe) return;
+  const frozen = [...(templateExportNames ?? [])].filter((n) => legacyRe.test(n));
+  if (frozen.length === 0) return;
+  if (frozenExportCheckSkipped('deploy')) return;
+  throw new Error(
+    `Template for stack "${stackName}" would CREATE export(s) named like a legacy prefix (${frozen.join(', ')}) ` +
+    `from your clawform.config.json legacy_prefixes. New exports must follow the going-forward convention ` +
+    `(rules/cfn-standards.md) — a legacy-prefixed export would immediately freeze this stack against ` +
+    `clawform deploy/rollback (rules/legacy-freeze.md). Rename the export. ` +
+    `Break-glass: ${SKIP_FROZEN_ENV}=1.`,
+  );
+}

package/src/aws/inventory.js

@@ -0,0 +1,156 @@
+import { paginateListStacks } from '@aws-sdk/client-cloudformation';
+
+export const STALE_DAYS = 180;
+
+const LIVE_STATUSES = [
+  'CREATE_COMPLETE',
+  'UPDATE_COMPLETE',
+  'UPDATE_ROLLBACK_COMPLETE',
+  'IMPORT_COMPLETE',
+];
+
+const hasLegacyPrefix = (name, prefixes) => prefixes.some((p) => name.startsWith(p + '-'));
+
+const SERVERLESS_DESC_RE = /Serverless application/i;
+
+export async function fetchStacks(client) {
+  const stacks = [];
+  for await (const page of paginateListStacks(
+    { client },
+    { StackStatusFilter: LIVE_STATUSES },
+  )) {
+    for (const s of page.StackSummaries ?? []) {
+      stacks.push({
+        name: s.StackName,
+        status: s.StackStatus,
+        templateDescription: s.TemplateDescription,
+        creationTime: s.CreationTime,
+        lastUpdatedTime: s.LastUpdatedTime,
+      });
+    }
+  }
+  return stacks;
+}
+
+export function classifyStacks(stacks, now = new Date(), legacyPrefixes = []) {
+  // legacyPrefixes comes from the consumer's clawform.config.json. Empty = a fresh
+  // consumer with no legacy stacks; nothing gets routed to the `legacy` bucket.
+  const result = { legacy: [], serverless: [], active: [], stale: [] };
+  const staleMs = STALE_DAYS * 24 * 60 * 60 * 1000;
+  for (const s of stacks) {
+    if (hasLegacyPrefix(s.name, legacyPrefixes)) {
+      result.legacy.push(s);
+      continue;
+    }
+    if (SERVERLESS_DESC_RE.test(s.templateDescription ?? '')) {
+      result.serverless.push(s);
+      continue;
+    }
+    const lastTouch = s.lastUpdatedTime ?? s.creationTime;
+    const ageMs = lastTouch ? now.getTime() - new Date(lastTouch).getTime() : 0;
+    if (ageMs > staleMs) result.stale.push(s);
+    else result.active.push(s);
+  }
+  return result;
+}
+
+function fmtDate(d) {
+  if (!d) return '';
+  return new Date(d).toISOString().slice(0, 10);
+}
+
+function escapePipe(s) {
+  return String(s ?? '').replace(/\|/g, '\\|');
+}
+
+function renderSection(lines, title, items, headers, fmtRow) {
+  lines.push(`## ${title} (${items.length})`, '');
+  if (items.length === 0) {
+    lines.push('_None_', '');
+    return;
+  }
+  lines.push('| ' + headers.join(' | ') + ' |');
+  lines.push('|' + headers.map(() => '---').join('|') + '|');
+  const sorted = [...items].sort((a, b) => a.name.localeCompare(b.name));
+  for (const it of sorted) {
+    lines.push('| ' + fmtRow(it).map((v) => `\`${escapePipe(v)}\``).join(' | ') + ' |');
+  }
+  lines.push('');
+}
+
+export function renderInventory(classified, meta) {
+  const lines = [
+    '# CloudFormation Stacks Inventory',
+    '',
+    `> Generated by \`clawform sync\` at ${meta.generatedAt}`,
+    `> Account: ${meta.account} · Region: ${meta.region}`,
+    '',
+  ];
+
+  renderSection(
+    lines,
+    '🔒 Legacy (refuse modify — see rules/legacy-freeze.md)',
+    classified.legacy,
+    ['Stack', 'Status', 'Last update'],
+    (s) => [s.name, s.status, fmtDate(s.lastUpdatedTime ?? s.creationTime)],
+  );
+
+  renderSection(
+    lines,
+    '🛠️ Serverless Framework (managed by `sls` tool — modify via serverless.yml)',
+    classified.serverless,
+    ['Stack', 'Status'],
+    (s) => [s.name, s.status],
+  );
+
+  renderSection(
+    lines,
+    '✅ Active (Clawform-modifiable)',
+    classified.active,
+    ['Stack', 'Status', 'Last update'],
+    (s) => [s.name, s.status, fmtDate(s.lastUpdatedTime ?? s.creationTime)],
+  );
+
+  renderSection(
+    lines,
+    `💤 Stale (≥${STALE_DAYS} days no update — review/decommission)`,
+    classified.stale,
+    ['Stack', 'Last update'],
+    (s) => [s.name, fmtDate(s.lastUpdatedTime ?? s.creationTime)],
+  );
+
+  return lines.join('\n');
+}
+
+const SECTION_KEY_BY_TITLE_FRAGMENT = [
+  ['Legacy', 'legacy'],
+  ['Serverless', 'serverless'],
+  ['Active', 'active'],
+  ['Stale', 'stale'],
+];
+
+function sectionKeyFromTitle(title) {
+  const hit = SECTION_KEY_BY_TITLE_FRAGMENT.find(([fragment]) => title.includes(fragment));
+  return hit ? hit[1] : null;
+}
+
+// Read-back counterpart to renderInventory — recovers the stack list from a
+// committed .clawform/catalog/stacks-inventory.md without a live AWS call. Used by the
+// project-audit workflow (Phase 3), which runs with no network access.
+export function parseInventory(markdown) {
+  const result = { legacy: [], serverless: [], active: [], stale: [] };
+  let currentKey = null;
+  for (const line of markdown.split(/\r?\n/)) {
+    const heading = line.match(/^## (.+?) \(\d+\)$/);
+    if (heading) {
+      currentKey = sectionKeyFromTitle(heading[1]);
+      continue;
+    }
+    if (!currentKey || !line.startsWith('| ')) continue;
+    const cells = line.split('|').map((c) => c.trim()).filter(Boolean);
+    if (cells.length === 0 || cells[0] === 'Stack') continue;
+    const name = cells[0].replace(/^`|`$/g, '');
+    result[currentKey].push(name);
+  }
+  return result;
+}