@thejoseki/clawform 0.0.1 → 2.2.0

package/src/hooks/cfn-lint-after-edit.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/**
+ * Clawform PostToolUse hook — CLI entry. Spawns cfn-lint after Edit/Write/MultiEdit
+ * on YAML files under cfn/ or templates/. Surfaces ERRORS back to Claude (exit 2 +
+ * stderr) so it can self-correct; WARNINGS go to stderr at exit 0 (advisory). When
+ * cfn-lint isn't installed, exits 0 silently — the hook is opt-in, not a gate.
+ *
+ * The pure decision logic lives in cfn-lint-after-edit-eval.js (unit-tested
+ * separately).
+ */
+
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { shouldLint } from './cfn-lint-after-edit-eval.js';
+
+let event;
+try {
+  event = JSON.parse(readFileSync(0, 'utf8'));
+} catch (err) {
+  // Fail-LOUD on parse error (allow the tool result through, but visibly warn).
+  process.stderr.write(`[clawform cfn-lint hook] event parse failed (skipping lint): ${err.message}\n`);
+  process.exit(0);
+}
+
+const decision = shouldLint(event);
+if (!decision.lint) process.exit(0);
+
+const r = spawnSync('cfn-lint', ['--format', 'json', decision.file], { encoding: 'utf8' });
+
+// cfn-lint not installed → silent skip. Hook stays opt-in for boxes without Python.
+if (r.error && (r.error.code === 'ENOENT' || r.error.errno === -2)) {
+  process.exit(0);
+}
+
+const stdout = (r.stdout ?? '').trim();
+if (!stdout) {
+  // No findings — clean lint pass. Exit 0 quietly.
+  process.exit(0);
+}
+
+let findings;
+try {
+  findings = JSON.parse(stdout);
+} catch {
+  process.stderr.write(`[clawform cfn-lint hook] could not parse cfn-lint output for ${decision.file} (skipping)\n`);
+  process.exit(0);
+}
+
+let errors = 0;
+let warnings = 0;
+const lines = [];
+for (const f of findings) {
+  const id = f.Rule?.Id ?? '?';
+  const loc = f.Location?.Start ? `L${f.Location.Start.LineNumber}` : '';
+  const msg = f.Message ?? '';
+  if (f.Level === 'Error') {
+    errors++;
+    lines.push(`  ✖ ${id} ${loc}: ${msg}`);
+  } else if (f.Level === 'Warning') {
+    warnings++;
+    lines.push(`  ⚠ ${id} ${loc}: ${msg}`);
+  }
+}
+
+if (errors > 0) {
+  // Errors get exit 2 + stderr so Claude sees them in the next turn and self-corrects.
+  process.stderr.write(
+    `[clawform cfn-lint hook] ${errors} error(s), ${warnings} warning(s) in ${decision.file}:\n` +
+      lines.join('\n') +
+      '\n',
+  );
+  process.exit(2);
+}
+
+if (warnings > 0) {
+  // Warnings stay advisory — user-visible, not blocking.
+  process.stderr.write(
+    `[clawform cfn-lint hook] ${warnings} warning(s) in ${decision.file}:\n` + lines.join('\n') + '\n',
+  );
+  process.exit(0);
+}

package/src/hooks/check-catalog-fresh-eval.js

@@ -0,0 +1,63 @@
+// Pure decision logic for the PreToolUse `clawform deploy` catalog-freshness hook.
+// Returns { warn|block, reason? } so the CLI shim handles all I/O.
+//
+// Rule:
+//   - If the command is `clawform deploy ...`, the consumer is about to import live exports.
+//     Block (exit 2) if `.clawform/catalog/outputs-catalog.md` doesn't exist — the user has never
+//     run `clawform sync`, so every Fn::ImportValue is unverifiable and changeset failure
+//     at deploy time is the predictable next step.
+//   - If the catalog file exists but is stale (>STALE_HOURS), warn (advisory) — the export
+//     set probably changed underneath. User decides.
+//   - Otherwise let it pass.
+//
+// Stays pure: takes (event, {cwd, now, stat}) and returns a verdict. The shim
+// supplies real `cwd`, `Date.now()`, and `node:fs.statSync` — tests substitute fakes.
+
+import { CATALOG_DIR_REL } from '../lib/constants.js';
+
+const DEPLOY_RE = /(^|\s|;|&&|\|\|)clawform\s+deploy\b/;
+// Derived, not restated: the gate must read exactly where `sync` writes, or it
+// blocks every deploy with "run sync" even right after a successful sync.
+export const CATALOG_REL = `${CATALOG_DIR_REL}/outputs-catalog.md`;
+export const STALE_HOURS = 24;
+
+// Resolve catalog path relative to a working directory. The path module's
+// join is platform-aware; we accept either separator on input. Exported so
+// other hooks (session-context-eval.js) can reuse the same resolution
+// instead of re-deriving it (DRY — session-context reports the same
+// freshness signal this hook gates on).
+export function resolveCatalogPath(cwd) {
+  return cwd.endsWith('/') || cwd.endsWith('\\') ? cwd + CATALOG_REL : cwd + '/' + CATALOG_REL;
+}
+
+export function checkCatalog(event, { cwd, now, statSync }) {
+  if (event?.tool_name !== 'Bash') return { ok: true };
+  const cmd = event?.tool_input?.command;
+  if (typeof cmd !== 'string' || !DEPLOY_RE.test(cmd)) return { ok: true };
+
+  const path = resolveCatalogPath(cwd);
+
+  let stat;
+  try {
+    stat = statSync(path);
+  } catch {
+    return {
+      block: true,
+      reason:
+        `Catalog ${CATALOG_REL} is missing — run \`clawform sync\` before deploying so Fn::ImportValue references can be verified against live exports.`,
+    };
+  }
+
+  const ageMs = now - new Date(stat.mtime).getTime();
+  const ageHours = ageMs / 3_600_000;
+  if (ageHours > STALE_HOURS) {
+    return {
+      warn: true,
+      reason:
+        `Catalog ${CATALOG_REL} is ${Math.round(ageHours)}h old (>${STALE_HOURS}h). ` +
+        'Consider `clawform sync` before deploy if any upstream stack changed recently.',
+    };
+  }
+
+  return { ok: true };
+}

package/src/hooks/check-catalog-fresh.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/**
+ * Clawform PreToolUse hook — catalog-freshness guard for `clawform deploy`.
+ * Reads JSON event from stdin, delegates to pure `checkCatalog`, and:
+ *   - exit 2 + stderr  → catalog missing (blocks deploy until clawform sync runs)
+ *   - exit 0 + stderr  → catalog stale (>24h) — advisory only
+ *   - exit 0 silent    → no deploy command, or catalog fresh
+ *
+ * Fail-LOUD on parse error so a buggy hook never silently disables the guard.
+ */
+
+import { readFileSync, statSync } from 'node:fs';
+import { checkCatalog } from './check-catalog-fresh-eval.js';
+
+let event;
+try {
+  event = JSON.parse(readFileSync(0, 'utf8'));
+} catch (err) {
+  process.stderr.write(`[clawform catalog hook] event parse failed (allowing tool call): ${err.message}\n`);
+  process.exit(0);
+}
+
+const verdict = checkCatalog(event, { cwd: process.cwd(), now: Date.now(), statSync });
+
+if (verdict.block) {
+  process.stderr.write(`[clawform catalog hook] ${verdict.reason}\n`);
+  process.exit(2);
+}
+
+if (verdict.warn) {
+  process.stderr.write(`[clawform catalog hook] ${verdict.reason}\n`);
+  process.exit(0);
+}

package/src/hooks/session-context-eval.js

@@ -0,0 +1,81 @@
+// Pure decision logic for the SessionStart context hook. Emits a single terse
+// block (customer, envs, region, legacy-prefix count, catalog freshness) when
+// the current project resolves an clawform.config.json; silent otherwise, so
+// a non-clawform project never sees noise.
+//
+// Never includes account IDs or AWS profile — CLAUDE.md's identity rule says
+// "Never echo the resolved values back in chat", and those live in
+// clawform.config.json `accounts` / .claude/settings.local.json, not here.
+//
+// Stays pure: takes (deps) and returns { shouldEmit, text }. The shim
+// supplies real findConfigPath/loadProjectConfig/statSync; tests inject fakes.
+
+import { STALE_HOURS, resolveCatalogPath } from './check-catalog-fresh-eval.js';
+import { STALE_CHANGESET_DAYS } from '../lib/session-state.js';
+
+// readState defaults to a no-op empty state so existing callers/tests that
+// don't care about in-flight state keep working; the shim injects the real one.
+export function evaluate({
+  cwd,
+  now,
+  findConfigPath,
+  loadProjectConfig,
+  statSync,
+  readState = () => ({ pendingChangesets: [] }),
+}) {
+  const configPath = findConfigPath(cwd);
+  if (!configPath) return { shouldEmit: false, text: '' };
+
+  const cfg = loadProjectConfig({ projectDir: cwd });
+  const customer = cfg.customer || '(unset)';
+  const envs = Array.isArray(cfg.envs) && cfg.envs.length ? cfg.envs.join(',') : '(none)';
+  const region = cfg.region || '(unset)';
+  const legacyCount = Array.isArray(cfg.legacy_prefixes) ? cfg.legacy_prefixes.length : 0;
+
+  const parts = [
+    `customer=${customer}`,
+    `envs=${envs}`,
+    `region=${region}`,
+    `legacy-prefixes=${legacyCount}`,
+    catalogFreshnessPart(cwd, now, statSync),
+  ];
+
+  const pending = pendingChangesetPart(cwd, now, readState);
+  if (pending) parts.push(pending);
+
+  return { shouldEmit: true, text: `[clawform] ${parts.join(' ')}` };
+}
+
+// Warn about any changeset created but not executed (survives /clear) — the
+// next operator sees it and can execute or clean it up. Fail-open: a bad
+// state file yields no line, never an exception.
+function pendingChangesetPart(cwd, now, readState) {
+  let state;
+  try {
+    state = readState(cwd);
+  } catch {
+    return '';
+  }
+  const pending = Array.isArray(state?.pendingChangesets) ? state.pendingChangesets : [];
+  if (pending.length === 0) return '';
+  const descs = pending.map((e) => {
+    const ageDays = (now - new Date(e.createdAt).getTime()) / 86_400_000;
+    // A corrupt/hand-edited createdAt yields NaN — show it as stale rather than
+    // "(NaNd)" so the operator still gets a "clean this up" signal.
+    if (!Number.isFinite(ageDays)) return `${e.stack}/${e.changeSetName}(?!stale)`;
+    const stale = ageDays > STALE_CHANGESET_DAYS ? '!stale' : '';
+    return `${e.stack}/${e.changeSetName}(${Math.max(0, Math.round(ageDays))}d${stale})`;
+  });
+  return `pending-changesets=${descs.join(',')}`;
+}
+
+function catalogFreshnessPart(cwd, now, statSync) {
+  let stat;
+  try {
+    stat = statSync(resolveCatalogPath(cwd));
+  } catch {
+    return 'catalog=missing';
+  }
+  const ageHours = (now - new Date(stat.mtime).getTime()) / 3_600_000;
+  return ageHours > STALE_HOURS ? `catalog=stale(${Math.round(ageHours)}h)` : 'catalog=fresh';
+}

package/src/hooks/session-context.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * Clawform SessionStart hook — prints a terse config+catalog context block
+ * when the current project resolves an clawform.config.json; silent (exit 0,
+ * no output) for any other project, so a bare dir sees nothing.
+ *
+ * Resolves the project dir the same way block-dangerous.js does: prefer the
+ * hook event's own `cwd`, then CLAUDE_PROJECT_DIR, then process.cwd().
+ *
+ * Fail-LOUD on event-parse error, and on consumer-config load error (bad
+ * JSON / wrong-shaped keys — project-config.js throws loudly on both), both
+ * stderr + exit 0 — never blocks the session; SessionStart output is
+ * advisory only.
+ */
+
+import { readFileSync, statSync } from 'node:fs';
+import { evaluate } from './session-context-eval.js';
+import { findConfigPath, loadProjectConfig } from '../lib/project-config.js';
+import { readState } from '../lib/session-state.js';
+
+let event;
+try {
+  event = JSON.parse(readFileSync(0, 'utf8'));
+} catch (err) {
+  process.stderr.write(`[clawform session-context] event parse failed (silent): ${err.message}\n`);
+  process.exit(0);
+}
+
+const cwd = (typeof event?.cwd === 'string' && event.cwd) || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+let shouldEmit = false;
+let text = '';
+try {
+  ({ shouldEmit, text } = evaluate({ cwd, now: Date.now(), findConfigPath, loadProjectConfig, statSync, readState }));
+} catch (err) {
+  process.stderr.write(`[clawform session-context] consumer config load failed at ${cwd} (silent): ${err.message}\n`);
+}
+
+if (shouldEmit) {
+  console.log(text);
+}

package/src/hooks/subagent-context-eval.js

@@ -0,0 +1,44 @@
+// Pure decision logic for the SubagentStart rule-injection hook. When the
+// current project resolves an clawform.config.json, every spawned subagent
+// receives Clawform's 6 hard rules + naming convention as injected context —
+// so a subagent generating or reviewing CloudFormation inherits the same
+// invariants the main session operates under, WITHOUT each workflow having to
+// embed them in every prompt by hand.
+//
+// Silent when no config resolves (a non-clawform project's subagents see
+// nothing). Never emits account IDs, AWS profile, or raw legacy-prefix values
+// (per CLAUDE.md identity rule) — only the customer shortname, which is
+// already public in every stack name.
+//
+// Stays pure: takes injected findConfigPath/loadProjectConfig; the shim
+// supplies the real implementations, tests supply fakes.
+
+// The 6 hard rules from CLAUDE.md, compressed to one line each. This is the
+// canonical terse copy; workflows/audit-all-stacks.js keeps its own embedded
+// copy as a defense-in-depth fallback (the hook can be disabled) — keep the
+// two in rough sync, but this one is what subagents actually receive.
+export const HARD_RULES_TERSE = `Clawform hard rules — all subagent work must comply:
+1. Never modify legacy stacks (frozen prefixes in clawform.config.json legacy_prefixes) without a "# FORCE LEGACY: <reason>" line.
+2. Never hardcode credentials in CFN Parameters — use {{resolve:secretsmanager:<name>:SecretString:<key>}}.
+3. Never "!ImportValue !Sub" (invalid YAML) — use long form Fn::ImportValue: !Sub "\${EnvName}-...".
+4. Stateful resources (RDS/S3/DynamoDB/EFS/ElastiCache/Logs::LogGroup/SecretsManager::Secret/KMS::Key/Cognito) need DeletionPolicy + UpdateReplacePolicy set to a non-destroy value.
+5. No direct deploy — CreateChangeSet -> describe -> confirm -> ExecuteChangeSet.
+6. No "aws cloudformation delete-stack" outside the /rollback command.
+Full rules: CLAUDE.md.`;
+
+function namingLine(customer, envs) {
+  const c = customer || '<customer>';
+  // Emit the consumer's actual env list (matching session-context's fidelity)
+  // so a subagent doesn't propose an env the consumer narrowed away.
+  const envList = Array.isArray(envs) && envs.length ? envs.join('/') : 'd/stg/p';
+  return `Naming: <env>-${c}-<pri|pub>-<service>-<project>-<feature>-[zone] (env ${envList}; service shortnames in rules/cfn-standards.md).`;
+}
+
+export function evaluate({ cwd, findConfigPath, loadProjectConfig }) {
+  const configPath = findConfigPath(cwd);
+  if (!configPath) return { shouldEmit: false, text: '' };
+
+  const cfg = loadProjectConfig({ projectDir: cwd });
+  const text = `${HARD_RULES_TERSE}\n${namingLine(cfg.customer, cfg.envs)}`;
+  return { shouldEmit: true, text };
+}

package/src/hooks/subagent-context.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * Clawform SubagentStart hook — injects the 6 hard rules + naming convention
+ * into every subagent when the current project resolves an clawform.config.json;
+ * silent (exit 0, no output) for any other project.
+ *
+ * SubagentStart requires the structured envelope
+ *   { hookSpecificOutput: { hookEventName: "SubagentStart", additionalContext } }
+ * on stdout — plain stdout (as SessionStart accepts) is NOT injected here.
+ *
+ * Resolves the project dir like the other hooks: prefer the event's own `cwd`,
+ * then CLAUDE_PROJECT_DIR, then process.cwd().
+ *
+ * Fail-LOUD on event-parse error, and on consumer-config load error (bad JSON /
+ * wrong-shaped keys — project-config.js throws on both), both stderr + exit 0 —
+ * never blocks the subagent; injected context is advisory only.
+ */
+
+import { readFileSync } from 'node:fs';
+import { evaluate } from './subagent-context-eval.js';
+import { findConfigPath, loadProjectConfig } from '../lib/project-config.js';
+
+let event;
+try {
+  event = JSON.parse(readFileSync(0, 'utf8'));
+} catch (err) {
+  process.stderr.write(`[clawform subagent-context] event parse failed (silent): ${err.message}\n`);
+  process.exit(0);
+}
+
+const cwd = (typeof event?.cwd === 'string' && event.cwd) || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+let shouldEmit = false;
+let text = '';
+try {
+  ({ shouldEmit, text } = evaluate({ cwd, findConfigPath, loadProjectConfig }));
+} catch (err) {
+  process.stderr.write(`[clawform subagent-context] consumer config load failed at ${cwd} (silent): ${err.message}\n`);
+}
+
+if (shouldEmit) {
+  console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'SubagentStart',
+      additionalContext: text,
+    },
+  }));
+}

package/src/lib/audit-synthesis.js

@@ -0,0 +1,24 @@
+// Pure merge/rank logic for the project-audit workflow (workflows/audit-all-stacks.js).
+// Kept separate from the workflow body because agent-call orchestration isn't
+// unit-testable — this is. Each stack's review-stack / iam-audit / cost-guard
+// verdict rolls up to that resource's worst finding, matching the existing
+// iam-audit convention ("Score the whole resource at its worst finding").
+
+const SEVERITY_RANK = { '🔴': 3, '🟡': 2, '✅': 1 };
+
+export function rollupStackSeverity(perStack) {
+  const severities = [perStack.review?.severity, perStack.iam?.severity, perStack.cost?.severity].filter(Boolean);
+  if (severities.length === 0) return '✅';
+  return severities.reduce((worst, s) => (SEVERITY_RANK[s] > SEVERITY_RANK[worst] ? s : worst), '✅');
+}
+
+export function synthesizeAudit(perStackResults) {
+  const stacks = perStackResults
+    .map((r) => ({ ...r, severity: rollupStackSeverity(r) }))
+    .sort((a, b) => SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity] || a.stack.localeCompare(b.stack));
+
+  const summary = { total: stacks.length, '🔴': 0, '🟡': 0, '✅': 0 };
+  for (const s of stacks) summary[s.severity] += 1;
+
+  return { summary, stacks };
+}

package/src/lib/aws-client.js

@@ -0,0 +1,15 @@
+import { CloudFormationClient } from '@aws-sdk/client-cloudformation';
+import { loadConfig } from './config.js';
+
+/**
+ * Return a CloudFormation client bound to the user's profile & region.
+ * Profile is propagated via `AWS_PROFILE` env var so both the SDK's default
+ * credential chain AND any `execa`-spawned `aws` CLI child inherit it.
+ */
+export function cfnClient(cliOverrides = {}) {
+  const cfg = loadConfig(cliOverrides);
+  // Mutate process.env so any execa-spawned `aws` CLI child inherits the same profile.
+  // Last-write-wins across callers; acceptable for a short-lived CLI process.
+  if (cfg.AWS_PROFILE) process.env.AWS_PROFILE = cfg.AWS_PROFILE;
+  return new CloudFormationClient({ region: cfg.AWS_REGION });
+}

package/src/lib/cfn-yaml.js

@@ -0,0 +1,92 @@
+// Shared CloudFormation-YAML helpers.
+//
+// CloudFormation templates use short-tag intrinsics (`!Ref`, `!Sub`, `!GetAtt`,
+// …) that stock js-yaml rejects. This module owns the one CFN-aware schema and
+// the small extractors built on it, so every caller parses templates the same
+// way instead of re-declaring tag tables.
+//
+// The schema is construct-only: `!Sub "x"` becomes `{ 'Fn::Sub': 'x' }`. We only
+// ever READ the parsed shape (we never dump back through it here), so the long
+// form is convenient and lossless for our purposes.
+//
+// Used by:
+//   - src/lib/lint-overrides.js   (inject / detect cfn-guard suppressions)
+//   - src/aws/exports.js          (export-lock + frozen-export pre-checks)
+
+import yaml from 'js-yaml';
+
+const CFN_TAGS = {
+  '!Ref': 'Ref', '!Sub': 'Fn::Sub', '!GetAtt': 'Fn::GetAtt',
+  '!ImportValue': 'Fn::ImportValue', '!Join': 'Fn::Join',
+  '!Select': 'Fn::Select', '!Split': 'Fn::Split',
+  '!FindInMap': 'Fn::FindInMap', '!If': 'Fn::If',
+  '!Equals': 'Fn::Equals', '!And': 'Fn::And', '!Or': 'Fn::Or',
+  '!Not': 'Fn::Not', '!Base64': 'Fn::Base64', '!Cidr': 'Fn::Cidr',
+  '!GetAZs': 'Fn::GetAZs', '!Condition': 'Condition',
+  '!Transform': 'Fn::Transform',
+};
+
+export const CFN_SCHEMA = yaml.DEFAULT_SCHEMA.extend(
+  Object.entries(CFN_TAGS).flatMap(([tag, long]) =>
+    ['scalar', 'sequence', 'mapping'].map(
+      (kind) => new yaml.Type(tag, { kind, construct: (data) => ({ [long]: data }) }),
+    ),
+  ),
+);
+
+// Best-effort parse of a CloudFormation template body. Returns the parsed doc,
+// or null on any parse error (unknown short tag, malformed YAML). Callers treat
+// null as "couldn't inspect" and fail open — the real linters / changeset still
+// run against the original file and surface the parse problem with their own
+// diagnostics. Mirrors the contract in lint-overrides.js.
+export function loadCfnTemplate(body) {
+  try {
+    const doc = yaml.load(body, { schema: CFN_SCHEMA });
+    return doc && typeof doc === 'object' ? doc : null;
+  } catch {
+    return null;
+  }
+}
+
+// Set of Output logical keys (OutputKey) that still declare an `Export.Name`.
+//
+// Why keys, not export-name values: an Output's logical key is a plain YAML map
+// key — exact string, intrinsic-free. The export *value* (`Export.Name`) is
+// frequently an intrinsic (`!Sub "${EnvName}-..."`) we can't resolve offline.
+// Live stack Outputs report both the OutputKey AND the resolved ExportName, so
+// matching live→template by OutputKey lets us detect an export removal with zero
+// false positives — see findRemovedExports() in src/aws/exports.js.
+export function extractExportingOutputKeys(doc) {
+  const keys = new Set();
+  const outputs = doc && typeof doc === 'object' ? doc.Outputs : null;
+  if (!outputs || typeof outputs !== 'object') return keys;
+  for (const [key, out] of Object.entries(outputs)) {
+    if (!out || typeof out !== 'object') continue;
+    const exp = out.Export;
+    // Export.Name truthy → this output still exports. The Name may be a string
+    // or an intrinsic object (e.g. { 'Fn::Sub': '...' }); presence is all we need.
+    if (exp && typeof exp === 'object' && exp.Name != null && exp.Name !== '') {
+      keys.add(key);
+    }
+  }
+  return keys;
+}
+
+// Set of Export.Name values that are plain string literals (intrinsics like
+// `!Sub "${EnvName}-…"` can't be resolved offline and are skipped). Two users:
+//   - export-lock pre-check: a live export whose name still appears as a literal
+//     Export.Name in the new template was merely moved to a different OutputKey,
+//     not removed — skipping it kills the false positive on OutputKey renames.
+//   - frozen-export introduction gate: a literal Export.Name matching a legacy
+//     prefix is refused before it ever goes live.
+export function extractLiteralExportNames(doc) {
+  const names = new Set();
+  const outputs = doc && typeof doc === 'object' ? doc.Outputs : null;
+  if (!outputs || typeof outputs !== 'object') return names;
+  for (const out of Object.values(outputs)) {
+    if (!out || typeof out !== 'object') continue;
+    const name = out.Export?.Name;
+    if (typeof name === 'string' && name !== '') names.add(name);
+  }
+  return names;
+}

package/src/lib/config.js

@@ -0,0 +1,76 @@
+const ENV_KEYS = ['AWS_PROFILE', 'AWS_REGION', 'ACCOUNT_DEV', 'ACCOUNT_STG', 'ACCOUNT_PROD', 'MCP_AWS_SERVER', 'OWNER', 'COST_CENTER'];
+const REQUIRED = ['AWS_PROFILE', 'AWS_REGION'];
+
+export function loadConfig(cliOverrides = {}) {
+  const fromEnv = {};
+  for (const key of ENV_KEYS) {
+    if (process.env[key]) fromEnv[key] = process.env[key];
+  }
+
+  const merged = { ...fromEnv, ...cliOverrides };
+
+  const missing = REQUIRED.filter((k) => !merged[k]);
+  if (missing.length) {
+    throw new Error(
+      `Missing required config: ${missing.join(', ')}. ` +
+      `Set via .claude/settings.local.json "env" block (copy .claude/settings.local.json.example) ` +
+      `or shell env vars (e.g. AWS_PROFILE=acme-admin AWS_REGION=ap-northeast-1).`
+    );
+  }
+
+  return merged;
+}
+
+// Resolve the per-stack tag values. Owner / CostCenter come from a two-source
+// chain: shell env var (per-user, gitignored settings.local.json) wins over
+// clawform.config.json tags_defaults (per-project, committed). Either source
+// alone is sufficient; both unset is a hard error pointing at both options.
+//
+// Why env wins: a developer running locally with their own handle should not
+// have to edit the committed project config. tags_defaults is the team default
+// for CI / CodePipeline / any context without per-user env.
+//
+// Args:
+//   projectConfig — result of loadProjectConfig(). Reads .customer and
+//                   .tags_defaults. Pure data, no I/O.
+//   envName       — the env string ('d' | 'stg' | 'p') passed to deploy().
+//                   Used as the Environment value only.
+//
+// Returns: { Owner, CostCenter, Environment, ManagedBy, Customer }.
+// Callers map this into the stack-level Tags array; the key spelling there
+// (Env vs Environment) is the caller's choice — rules/tagging.md pins it to "Env".
+export function resolveStackTags(projectConfig, envName) {
+  const defaults = (projectConfig && projectConfig.tags_defaults) || {};
+  const envOwner = (process.env.OWNER || '').trim();
+  const envCost = (process.env.COST_CENTER || '').trim();
+  const cfgOwner = typeof defaults.Owner === 'string' ? defaults.Owner.trim() : '';
+  const cfgCost = typeof defaults.CostCenter === 'string' ? defaults.CostCenter.trim() : '';
+
+  const Owner = envOwner || cfgOwner;
+  if (!Owner) {
+    throw new Error(
+      'Owner tag is unset. Set one of:\n' +
+      '  1. OWNER env var (e.g. .claude/settings.local.json "env" block) — per-user override, wins.\n' +
+      '  2. tags_defaults.Owner in clawform.config.json — per-project team default.\n' +
+      'See docs/config-schema.md and rules/tagging.md.'
+    );
+  }
+
+  const CostCenter = envCost || cfgCost;
+  if (!CostCenter) {
+    throw new Error(
+      'CostCenter tag is unset. Set one of:\n' +
+      '  1. COST_CENTER env var (e.g. .claude/settings.local.json "env" block) — per-user override, wins.\n' +
+      '  2. tags_defaults.CostCenter in clawform.config.json — per-project team default.\n' +
+      'See docs/config-schema.md and rules/tagging.md.'
+    );
+  }
+
+  return {
+    Owner,
+    CostCenter,
+    Environment: envName,
+    ManagedBy: 'CloudFormation',
+    Customer: (projectConfig && projectConfig.customer) || '',
+  };
+}