clawarmor 3.2.0 → 3.5.0

package/CHANGELOG.md

@@ -1,5 +1,94 @@
 # Changelog
 
+## [3.4.0] — 2026-03-08
+
+### New Features
+
+#### `clawarmor harden --report` — Structured Hardening Reports
+Export a portable, structured summary of every hardening run — what was hardened, what was
+skipped, why, and what was already good. The #1 feature gap for enterprise adoption.
+
+**Flags:**
+- `--report [path]` — Write JSON report (default: `~/.openclaw/clawarmor-harden-report-YYYY-MM-DD.json`)
+- `--report-format text` — Write Markdown report instead of JSON
+
+**JSON report structure:**
+```json
+{
+  "version": "3.4.0",
+  "timestamp": "...",
+  "system": { "os": "...", "openclaw_version": "..." },
+  "summary": { "total_checks": N, "hardened": N, "already_good": N, "skipped": N },
+  "items": [
+    { "check": "exec.ask.off", "status": "hardened", "before": "off", "after": "on-miss", "action": "..." },
+    { "check": "gateway.host.open", "status": "skipped", "skipped_reason": "Breaking fix..." }
+  ]
+}
+```
+
+**Examples:**
+```bash
+clawarmor harden --report
+clawarmor harden --report /tmp/my-report.json
+clawarmor harden --report /tmp/report.md --report-format text
+clawarmor harden --auto --report
+```
+
+Existing `clawarmor harden` behavior unchanged when `--report` is not passed.
+
+---
+
+## [3.3.0] — 2026-03-07
+
+### New Features
+
+#### `clawarmor invariant sync` — Invariant Deep Integration
+The Invariant integration in v3.0 detected presence of `invariant-ai`. v3.3.0 does the real work:
+it reads your latest audit findings and generates severity-tiered Invariant DSL policies that
+actually enforce behavioral guardrails at runtime.
+
+**Severity tiers:**
+- `CRITICAL`/`HIGH` findings → `raise "..."` hard enforcement rules (blocks the trace)
+- `MEDIUM` findings → `warn "..."` monitoring/alerting rules (logs but allows)
+- `LOW`/`INFO` findings → `# informational` comments (guidance only)
+
+**Policy mappings (finding → Invariant rule):**
+| Finding type | Generated policy |
+|---|---|
+| `exec.ask=off` / unrestricted exec | `raise` on any `exec` tool call |
+| Credential files world-readable | `raise` on `read_file` to sensitive paths (`.ssh`, `.aws`, `agent-accounts`, `.openclaw`) |
+| Open channel policy (no `allowFrom`) | `raise`/`warn` on `read_file → send_message` without channel restriction |
+| Elevated tool calls unrestricted | `raise`/`warn` on elevated calls with no `allowFrom_restricted` metadata |
+| Skill supply chain / unpinned | `raise`/`warn` on tool calls lacking `skill_verified` or `skill_pinned` metadata |
+| API key/secret in config files | `raise`/`warn` on `read_file` output containing secret patterns → `send_message` |
+| Baseline: prompt injection | `raise` on web content → outbound message (always included) |
+
+**New commands:**
+```
+clawarmor invariant sync                  # generate tiered policies from latest audit
+clawarmor invariant sync --dry-run        # preview without writing
+clawarmor invariant sync --push           # generate + validate + push to Invariant instance
+clawarmor invariant sync --push --host <host> --port <port>
+clawarmor invariant sync --json           # machine-readable output
+clawarmor invariant status                # show current policy file + last sync report
+```
+
+**Policy output:**
+- Policy file: `~/.clawarmor/invariant-policies/clawarmor.inv`
+- Sync report: `~/.clawarmor/invariant-policies/sync-report.json`
+
+**`--push` behavior:**
+1. Validates policy syntax via `LocalPolicy.from_file()` (requires `pip3 install invariant-ai`)
+2. If Invariant instance running on `localhost:8000` → live-reloads policy immediately
+3. If not running → policy written to disk, enforces on next Invariant start
+
+**Relationship to `clawarmor stack`:**
+- `stack deploy/sync` generates basic `.inv` rules in `~/.clawarmor/invariant-rules.inv`
+- `invariant sync` generates richer severity-tiered policies in `~/.clawarmor/invariant-policies/clawarmor.inv`
+- They are complementary; `invariant sync` is the recommended path for serious deployments
+
+---
+
 ## [3.2.0] — 2026-03-03
 
 ### New Features

package/README.md

@@ -51,9 +51,12 @@ ClawArmor sits at the foundation and orchestrates the layers above it:
 |---|---|
 | `audit` | Score your OpenClaw config (0–100), live gateway probes, plain-English verdict |
 | `scan` | Scan all installed skill files for malicious code and SKILL.md instructions |
+| `scan --json` | Machine-readable scan output — pipe to CI, scripts, or dashboards |
+| `scan --report` | Write structured JSON + Markdown reports after scanning (v3.5.0) |
 | `prescan <skill>` | Pre-scan a skill before installing — blocks on CRITICAL findings |
+| `skill verify <name>` | Deep-verify a specific installed skill — checks SKILL.md + all referenced scripts |
 | `fix` | Auto-apply safe fixes (--dry-run to preview, --apply to run) |
-| `harden` | Interactive hardening wizard (--dry-run, --auto, --monitor) |
+| `harden` | Interactive hardening wizard (--dry-run, --auto, --monitor, --report) |
 | `status` | One-screen security posture dashboard |
 | `verify` | Re-run only previously-failed checks (CI-friendly, exit 0 = all fixed) |
 
@@ -67,6 +70,31 @@ ClawArmor sits at the foundation and orchestrates the layers above it:
 | `stack sync` | Regenerate stack configs from latest audit — run after harden/fix |
 | `stack teardown` | Remove deployed stack components |
 
+### Invariant Deep Integration (v3.3.0)
+
+| Command | Description |
+|---|---|
+| `invariant sync` | Generate severity-tiered Invariant policies from latest audit findings |
+| `invariant sync --dry-run` | Preview policies without writing |
+| `invariant sync --push` | Generate + validate + push to running Invariant instance |
+| `invariant sync --json` | Machine-readable output for scripting |
+| `invariant status` | Show current policy file and last sync report |
+
+**Severity tiers:**
+- `CRITICAL`/`HIGH` findings → `raise "..."` (hard enforcement — blocks trace)
+- `MEDIUM` findings → `warn "..."` (monitoring/alerting — logged)
+- `LOW`/`INFO` findings → `# comment` (informational only)
+
+Policies are written to `~/.clawarmor/invariant-policies/clawarmor.inv`. With `--push`, ClawArmor validates the policy syntax via `invariant-ai` and live-reloads a running Invariant instance. If no instance is running, the policy is written to disk and enforces on next start.
+
+```bash
+pip3 install invariant-ai           # required for --push validation
+clawarmor audit                     # run audit to capture findings
+clawarmor invariant sync            # generate tiered policies
+clawarmor invariant sync --push     # push to running Invariant instance
+clawarmor invariant status          # check what's deployed
+```
+
 ### History & Monitoring
 
 | Command | Description |
@@ -76,6 +104,9 @@ ClawArmor sits at the foundation and orchestrates the layers above it:
 | `log` | View the audit event log |
 | `digest` | Show weekly security digest |
 | `watch` | Monitor config and skill changes in real time |
+| `baseline save` | Save current scan results as baseline |
+| `baseline diff` | Compare current scan against saved baseline — see what changed |
+| `incident create` | Log a security incident with timestamp, findings, and remediation notes |
 | `protect --install` | Install guard hook, shell intercept (zsh/bash/fish), and watch daemon |
 | `snapshot` | Save a config snapshot manually (auto-saved before every harden/fix) |
 | `rollback` | Restore config from auto-snapshot (--list, --id <id>) |
@@ -116,6 +147,52 @@ clawarmor harden --monitor-report # see what it observed
 clawarmor harden --monitor-off    # stop monitoring
 ```
 
+**Hardening reports** (v3.4.0) — Export a structured report after hardening:
+
+```bash
+# Write JSON report to default location (~/.openclaw/clawarmor-harden-report-YYYY-MM-DD.json)
+clawarmor harden --report
+
+# Write JSON report to a custom path
+clawarmor harden --report /path/to/report.json
+
+# Write Markdown report (human-readable, shareable)
+clawarmor harden --report /path/to/report.md --report-format text
+
+# Combine with auto mode
+clawarmor harden --auto --report
+```
+
+Report structure includes: version, timestamp, OS/OpenClaw info, summary counts (hardened/skipped/already-good), and per-check action details with before/after values.
+
+**Scan reports** (v3.5.0) — Export a structured report after scanning skills:
+
+```bash
+# Write JSON + Markdown reports (e.g. ~/.openclaw/clawarmor-scan-report-2025-03-08.json + .md)
+clawarmor scan --report
+```
+
+Two files are always written together:
+- `clawarmor-scan-report-YYYY-MM-DD.json` — machine-readable, includes per-skill status, severity, findings, and overall score
+- `clawarmor-scan-report-YYYY-MM-DD.md` — human-readable with executive summary table, findings detail, and remediation steps
+
+Example JSON structure:
+```json
+{
+  "version": "3.5.0",
+  "timestamp": "2025-03-08T12:00:00.000Z",
+  "system": { "hostname": "myhost", "platform": "darwin", "node_version": "v20.0.0", "openclaw_version": "1.2.0" },
+  "verdict": "PASS",
+  "score": 100,
+  "summary": { "total": 12, "passed": 12, "failed": 0, "warnings": 0, "critical_findings": 0, "high_findings": 0 },
+  "checks": [
+    { "name": "weather", "status": "pass", "severity": "NONE", "detail": "No findings", "type": "user" }
+  ]
+}
+```
+
+Terminal output is still shown when `--report` is used — the flag only adds file output on top.
+
 ## Philosophy
 
 ClawArmor runs entirely on your machine — no telemetry, no cloud, no accounts.

package/clawgear-skills/skill-security-scanner/SKILL.md

@@ -12,7 +12,7 @@ A security gate that sits between you and any skill you're about to install. Bef
 
 ## The problem it solves
 
-In early 2026, a malicious skill called `openclaw-web-search` was distributed on a third-party registry. It appeared functional but contained an obfuscated payload that exfiltrated session tokens via a DNS covert channel. It was installed by dozens of operators without inspection.
+In early 2026, a malicious skill called `openclaw-web-search` was distributed on a third-party registry. It appeared functional but contained an obfuscated payload that sent session tokens to an attacker-controlled DNS server. It was installed by dozens of operators without inspection.
 
 This scanner would have caught it. The obfuscation patterns and DNS module import are both CRITICAL-severity matches in ClawArmor's pattern library.
 

package/cli.js

@@ -3,7 +3,7 @@
 
 import { paint } from './lib/output/colors.js';
 
-const VERSION = '3.2.0';
+const VERSION = '3.5.0';
 const GATEWAY_PORT_DEFAULT = 18789;
 
 function isLocalhost(host) {
@@ -54,6 +54,7 @@ function usage() {
   console.log(`    ${paint.cyan('baseline')}      Save, list, and diff security baselines (save|list|diff)`);
   console.log(`    ${paint.cyan('incident')}      Log and manage security incidents (create|list)`);
   console.log(`    ${paint.cyan('stack')}         Security orchestrator — deploy Invariant + IronCurtain from audit data`);
+  console.log(`    ${paint.cyan('invariant')}      Invariant deep integration — sync findings → runtime policies (v3.3.0)`);
   console.log(`    ${paint.cyan('skill')}         Skill utilities — verify a skill directory (skill verify <dir>)`);
   console.log(`    ${paint.cyan('skill-report')}  Show post-install audit impact of last skill install`);
   console.log(`    ${paint.cyan('profile')}       Manage contextual hardening profiles`);
@@ -143,8 +144,13 @@ if (cmd === 'audit') {
 }
 
 if (cmd === 'scan') {
+  const scanReportIdx = args.indexOf('--report');
+  const scanFlags = {
+    json: flags.json,
+    report: scanReportIdx !== -1,
+  };
   const { runScan } = await import('./lib/scan.js');
-  process.exit(await runScan({ json: flags.json }));
+  process.exit(await runScan(scanFlags));
 }
 
 if (cmd === 'verify') {
@@ -211,6 +217,12 @@ if (cmd === 'log') {
 
 if (cmd === 'harden') {
   const hardenProfileIdx = args.indexOf('--profile');
+  const reportIdx = args.indexOf('--report');
+  const reportFormatIdx = args.indexOf('--report-format');
+  // --report can be a flag alone or --report <path>
+  const reportNext = reportIdx !== -1 ? args[reportIdx + 1] : null;
+  const reportPath = (reportNext && !reportNext.startsWith('--')) ? reportNext : null;
+  const reportFormat = reportFormatIdx !== -1 ? (args[reportFormatIdx + 1] || 'json') : 'json';
   const hardenFlags = {
     dryRun: args.includes('--dry-run'),
     auto: args.includes('--auto'),
@@ -219,6 +231,9 @@ if (cmd === 'harden') {
     monitorReport: args.includes('--monitor-report'),
     monitorOff: args.includes('--monitor-off'),
     profile: hardenProfileIdx !== -1 ? args[hardenProfileIdx + 1] : null,
+    report: reportIdx !== -1,
+    reportPath: reportPath,
+    reportFormat: reportFormat,
   };
   const { runHarden } = await import('./lib/harden.js');
   process.exit(await runHarden(hardenFlags));
@@ -285,5 +300,31 @@ if (cmd === 'skill') {
   process.exit(1);
 }
 
+
+if (cmd === 'invariant') {
+  const sub = args[1];
+  const invArgs = args.slice(2);
+
+  if (!sub || sub === 'status') {
+    const { runInvariantStatus } = await import('./lib/invariant-sync.js');
+    process.exit(await runInvariantStatus());
+  }
+
+  if (sub === 'sync') {
+    const { runInvariantSync } = await import('./lib/invariant-sync.js');
+    process.exit(await runInvariantSync(invArgs));
+  }
+
+  console.log('');
+  console.log(`  Invariant subcommands:`);
+  console.log(`    clawarmor invariant status              # show policy + last sync`);
+  console.log(`    clawarmor invariant sync                # generate policies from latest audit`);
+  console.log(`    clawarmor invariant sync --dry-run      # preview without writing`);
+  console.log(`    clawarmor invariant sync --push         # generate + push to Invariant instance`);
+  console.log(`    clawarmor invariant sync --push --host <host> --port <port>`);
+  console.log('');
+  process.exit(1);
+}
+
 console.log(`  ${paint.red('✗')} Unknown command: ${paint.bold(cmd)}`);
 usage(); process.exit(1);

package/lib/harden.js

@@ -4,10 +4,11 @@
 //   --dry-run:  show what WOULD be fixed, no writes
 //   --auto:     apply all safe + caution fixes without confirmation (skips breaking)
 //   --auto --force: apply ALL fixes including breaking ones
+//   --report [path]:  write a structured report (JSON or Markdown) after hardening
 
-import { existsSync, readdirSync, statSync, readFileSync } from 'fs';
-import { join } from 'path';
-import { homedir } from 'os';
+import { existsSync, readdirSync, statSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { homedir, platform, release } from 'os';
 import { execSync, spawnSync } from 'child_process';
 import { createInterface } from 'readline';
 import { paint } from './output/colors.js';
@@ -24,6 +25,8 @@ const HISTORY_FILE = join(CLAWARMOR_DIR, 'history.json');
 const CLI_PATH = new URL('../cli.js', import.meta.url).pathname;
 const SEP = paint.dim('─'.repeat(52));
 
+const VERSION = '3.4.0';
+
 // ── Impact levels ─────────────────────────────────────────────────────────────
 // SAFE:     No functionality impact. Pure security improvement.
 // CAUTION:  May change agent behavior. User should be aware.
@@ -83,8 +86,6 @@ function buildFixes(config) {
   // Fix 1: world/group-readable credential files — chmod 600
   const badFiles = findWorldReadableCredFiles();
   for (const f of badFiles) {
-    // Classify: credential files (tokens, keys) are safe to lock down.
-    // Config files that other tools might read need caution.
     const isSensitive = /\.(env|json|key|pem|token|secret)$/i.test(f.name) ||
                         f.name === 'agent-accounts.json' ||
                         f.name === 'openclaw.json';
@@ -101,6 +102,9 @@ function buildFixes(config) {
         ? 'Only restricts other system users. Scripts will still run as you.'
         : 'Only restricts other system users from reading this file. Your agent is unaffected.',
       manualNote: null,
+      // for report: capture before state
+      _reportBefore: f.mode,
+      _reportAfter: '600',
     });
   }
 
@@ -119,6 +123,8 @@ function buildFixes(config) {
         '     tablet, or another computer), those connections will be blocked.\n' +
         '     Only localhost access will work after this change.',
       manualNote: 'Restart gateway after applying: openclaw gateway restart',
+      _reportBefore: '0.0.0.0',
+      _reportAfter: '127.0.0.1',
     });
   }
 
@@ -137,6 +143,8 @@ function buildFixes(config) {
         '     shell commands may pause waiting for approval.\n' +
         '     You\'ll need to approve commands via the web UI or CLI.',
       manualNote: 'Restart gateway after applying: openclaw gateway restart',
+      _reportBefore: String(execAsk),
+      _reportAfter: 'on-miss',
     });
   }
 
@@ -236,6 +244,171 @@ function printImpactSummary(fixes) {
   return parts.join(paint.dim(' · '));
 }
 
+// ── Report support ────────────────────────────────────────────────────────────
+
+function getSystemInfo() {
+  let osInfo = `${platform()} ${release()}`;
+  let ocVersion = 'unknown';
+  try {
+    const r = spawnSync('openclaw', ['--version'], { encoding: 'utf8', timeout: 5000 });
+    if (r.stdout) ocVersion = r.stdout.trim().split('\n')[0] || 'unknown';
+  } catch { /* non-fatal */ }
+  return { os: osInfo, openclaw_version: ocVersion };
+}
+
+function defaultReportPath(format) {
+  const date = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
+  const ext = format === 'text' ? 'md' : 'json';
+  return join(HOME, '.openclaw', `clawarmor-harden-report-${date}.${ext}`);
+}
+
+function buildReportItems({ fixes, applied, skipped, failed, skippedBreaking, applyResults }) {
+  const items = [];
+  const appliedSet = new Set(applied);
+  const skippedSet = new Set(skipped);
+  const failedSet = new Set(failed);
+
+  for (const fix of fixes) {
+    if (failedSet.has(fix.id)) {
+      const res = applyResults[fix.id];
+      items.push({
+        check: fix.id,
+        status: 'failed',
+        action: fix.description,
+        error: res?.err || 'unknown error',
+      });
+    } else if (skippedSet.has(fix.id)) {
+      const isBreaking = fix.impact === IMPACT.BREAKING;
+      items.push({
+        check: fix.id,
+        status: 'skipped',
+        skipped_reason: isBreaking
+          ? 'Breaking fix — skipped in auto mode (use --auto --force to include)'
+          : 'User declined',
+      });
+    } else if (appliedSet.has(fix.id)) {
+      items.push({
+        check: fix.id,
+        status: 'hardened',
+        before: fix._reportBefore ?? null,
+        after: fix._reportAfter ?? null,
+        action: fix.description,
+      });
+    }
+  }
+  return items;
+}
+
+function writeJsonReport(reportPath, items) {
+  const sysInfo = getSystemInfo();
+  const hardened = items.filter(i => i.status === 'hardened').length;
+  const already_good = items.filter(i => i.status === 'already_good').length;
+  const skipped = items.filter(i => i.status === 'skipped').length;
+  const failed = items.filter(i => i.status === 'failed').length;
+
+  const report = {
+    version: VERSION,
+    timestamp: new Date().toISOString(),
+    system: sysInfo,
+    summary: {
+      total_checks: items.length,
+      hardened,
+      already_good,
+      skipped,
+      failed,
+    },
+    items,
+  };
+
+  try { mkdirSync(dirname(reportPath), { recursive: true }); } catch {}
+  writeFileSync(reportPath, JSON.stringify(report, null, 2), 'utf8');
+  return report;
+}
+
+function writeMarkdownReport(reportPath, items) {
+  const sysInfo = getSystemInfo();
+  const now = new Date();
+  const dateStr = now.toLocaleString('en-US', {
+    year: 'numeric', month: '2-digit', day: '2-digit',
+    hour: '2-digit', minute: '2-digit', hour12: false
+  });
+
+  const hardened = items.filter(i => i.status === 'hardened');
+  const alreadyGood = items.filter(i => i.status === 'already_good');
+  const skippedItems = items.filter(i => i.status === 'skipped');
+  const failedItems = items.filter(i => i.status === 'failed');
+
+  let md = `# ClawArmor Hardening Report
+Generated: ${dateStr}
+ClawArmor: v${VERSION} | OS: ${sysInfo.os} | OpenClaw: ${sysInfo.openclaw_version}
+
+## Summary
+- ✅ ${alreadyGood.length} check${alreadyGood.length !== 1 ? 's' : ''} already good
+- 🔧 ${hardened.length} hardened
+- ⚠️  ${skippedItems.length} skipped
+${failedItems.length ? `- ❌ ${failedItems.length} failed\n` : ''}`;
+
+  if (hardened.length) {
+    md += `
+## Actions Taken
+
+| Check | Before | After | Action |
+|-------|--------|-------|--------|
+`;
+    for (const item of hardened) {
+      md += `| ${item.check} | ${item.before ?? '—'} | ${item.after ?? '—'} | ${item.action ?? '—'} |\n`;
+    }
+  }
+
+  if (alreadyGood.length) {
+    md += `
+## Already Good
+
+`;
+    for (const item of alreadyGood) {
+      md += `- ${item.check}\n`;
+    }
+  }
+
+  if (skippedItems.length) {
+    md += `
+## Skipped
+
+`;
+    for (const item of skippedItems) {
+      md += `- **${item.check}**: ${item.skipped_reason || 'no reason given'}\n`;
+    }
+  }
+
+  if (failedItems.length) {
+    md += `
+## Failed
+
+`;
+    for (const item of failedItems) {
+      md += `- **${item.check}**: ${item.error || 'unknown error'}\n`;
+    }
+  }
+
+  try { mkdirSync(dirname(reportPath), { recursive: true }); } catch {}
+  writeFileSync(reportPath, md, 'utf8');
+}
+
+function printReportSummary(items, reportPath, format) {
+  const hardened = items.filter(i => i.status === 'hardened').length;
+  const alreadyGood = items.filter(i => i.status === 'already_good').length;
+  const skipped = items.filter(i => i.status === 'skipped').length;
+  const failed = items.filter(i => i.status === 'failed').length;
+
+  console.log('');
+  console.log(SEP);
+  console.log(`  ${paint.bold('Hardening Report')}`);
+  console.log(`  ${paint.green('✅')} ${alreadyGood} already good  ${paint.cyan('🔧')} ${hardened} hardened  ${paint.yellow('⚠️')}  ${skipped} skipped${failed ? `  ${paint.red('❌')} ${failed} failed` : ''}`);
+  console.log(`  ${paint.dim('Report written:')} ${reportPath}`);
+  console.log(`  ${paint.dim('Format:')} ${format === 'text' ? 'Markdown (.md)' : 'JSON'}`);
+  console.log('');
+}
+
 // ── Main export ───────────────────────────────────────────────────────────────
 
 export async function runHarden(flags = {}) {
@@ -285,12 +458,9 @@ export async function runHarden(flags = {}) {
     const overrideSev = getOverriddenSeverity(profile.name, fix.id);
     const expected = isExpectedFinding(profile.name, fix.id);
     if (expected) {
-      // Mark as expected — skip entirely from harden output
       return { ...fix, _skipForProfile: true };
     }
     if (overrideSev) {
-      // Upgrade to higher severity if unexpected for this profile
-      const currentWeight = { SAFE: 1, CAUTION: 2, BREAKING: 3 };
       const upgradeMap = { HIGH: IMPACT.BREAKING, MEDIUM: IMPACT.CAUTION, INFO: IMPACT.SAFE };
       const newImpact = upgradeMap[overrideSev] || fix.impact;
       return { ...fix, impact: newImpact, _profileOverride: overrideSev };
@@ -380,11 +550,24 @@ export async function runHarden(flags = {}) {
       console.log(`    ${paint.dim('•')} ${item}`);
     }
     console.log('');
+
+    // If report requested but nothing to harden, still write an empty/all-good report
+    if (flags.report) {
+      const format = flags.reportFormat || 'json';
+      const reportPath = flags.reportPath || defaultReportPath(format);
+      const items = []; // no fixes, no items (could add "already_good" items if we tracked checks)
+      if (format === 'text') {
+        writeMarkdownReport(reportPath, items);
+      } else {
+        writeJsonReport(reportPath, items);
+      }
+      printReportSummary(items, reportPath, format);
+    }
+
     return 0;
   }
 
   if (flags.auto) {
-    // --auto mode: apply safe + caution, SKIP breaking unless --force
     const autoLabel = flags.force
       ? paint.cyan('Auto mode (--force) — applying ALL fixes including breaking')
       : paint.cyan('Auto mode — applying safe + caution fixes (skipping breaking)');
@@ -406,6 +589,12 @@ export async function runHarden(flags = {}) {
   let applied = 0, skipped = 0, failed = 0, skippedBreaking = 0;
   const restartNotes = [];
 
+  // Report tracking
+  const appliedIds = [];
+  const skippedIds = [];
+  const failedIds = [];
+  const applyResults = {};
+
   for (const fix of fixes) {
     const badge = IMPACT_BADGE[fix.impact]();
 
@@ -420,17 +609,16 @@ export async function runHarden(flags = {}) {
     let doApply;
 
     if (flags.auto) {
-      // In auto mode: apply safe + caution, skip breaking unless --force
       if (fix.impact === IMPACT.BREAKING && !flags.force) {
         console.log(`  ${paint.red('⊘ Skipped')} ${paint.dim('(breaking — use --auto --force to include)')}`);
         skippedBreaking++;
         skipped++;
+        skippedIds.push(fix.id);
         console.log('');
         continue;
       }
       doApply = true;
     } else {
-      // Interactive mode: always ask, but warn about breaking
       if (fix.impact === IMPACT.BREAKING) {
         console.log(`  ${paint.red('⚠  This fix will change how your agent works.')}`);
         console.log(`  ${paint.red('   Read the impact above carefully before applying.')}`);
@@ -442,18 +630,22 @@ export async function runHarden(flags = {}) {
     if (!doApply) {
       console.log(`  ${paint.dim('✗ Skipped')}`);
       skipped++;
+      skippedIds.push(fix.id);
       console.log('');
       continue;
     }
 
     const result = applyFix(fix);
+    applyResults[fix.id] = result;
     if (result.ok) {
       console.log(`  ${paint.green('✓ Fixed')}`);
       applied++;
+      appliedIds.push(fix.id);
       if (fix.manualNote) restartNotes.push(fix.manualNote);
     } else {
       console.log(`  ${paint.red('✗ Failed:')} ${result.err}`);
       failed++;
+      failedIds.push(fix.id);
     }
     console.log('');
   }
@@ -505,6 +697,28 @@ export async function runHarden(flags = {}) {
     }
   }
 
+  // ── Write report if requested ──────────────────────────────────────────────
+  if (flags.report) {
+    const format = flags.reportFormat || 'json';
+    const reportPath = flags.reportPath || defaultReportPath(format);
+
+    const reportItems = buildReportItems({
+      fixes,
+      applied: appliedIds,
+      skipped: skippedIds,
+      failed: failedIds,
+      applyResults,
+    });
+
+    if (format === 'text') {
+      writeMarkdownReport(reportPath, reportItems);
+    } else {
+      writeJsonReport(reportPath, reportItems);
+    }
+
+    printReportSummary(reportItems, reportPath, format);
+  }
+
   console.log('');
   return failed > 0 ? 1 : 0;
 }