mindforge-cc 11.2.1 → 11.3.1

package/CHANGELOG.md

@@ -1,5 +1,85 @@
 # Changelog
 
+## [11.3.1] - 2026-06-05 — Packaging hotfix (commands, skills & framework now ship)
+
+Critical fix for v11.3.0, where a too-narrow npm `files` allowlist silently dropped
+most of the product from the published tarball. Users who ran `npx mindforge-cc` got
+only hooks, personas, subagents, and three `.mindforge/` folders — **no slash commands,
+no skills, and an incomplete framework** — with no error (the installer skips any source
+absent from the tarball). v11.3.1 restores the full payload and adds a regression test
+so this class of bug cannot ship silently again.
+
+### Fixed
+
+- **npm `files` allowlist** (`package.json`) widened to ship what the installer reads:
+  `.claude/commands/` (174 slash commands), `.agent/mindforge/` + `.agent/forge/`,
+  `.agent/skills/` (73 skills), the entry `.claude/CLAUDE.md`, and the full `.mindforge/`
+  framework (`governance`, `integrations`, `intelligence`, `memory`, `metrics`, `models`,
+  `org`, `plugins`, `team` — previously only `engine`/`personas`/`skills` reached users).
+  Runtime state is explicitly **excluded** (`celestial.db`, `metrics/token-usage.jsonl`,
+  `memory/pattern-library.jsonl`) — `files` overrides `.npmignore`, so these are negated
+  in the allowlist itself.
+- **`.planning/` scaffolding now ships and installs** — sourced from the clean, generic
+  `examples/starter-project/.planning/` (never the framework repo's own live `.planning/`,
+  which holds dev state: `AUDIT.jsonl`, `slack-threads.json`, `jira-sync.json`). Added the
+  four missing starter templates (`ROADMAP.md`, `REQUIREMENTS.md`, `ARCHITECTURE.md`,
+  `RELEASE-CHECKLIST.md`) so the autonomous engine (`/mindforge:auto`, `:next`) has the
+  files it expects.
+- **`docs/References` / `docs/Templates` case-sensitivity bug** — the installer read
+  lowercase `docs/references`/`templates`, which "worked" on case-insensitive macOS but
+  silently missed on case-sensitive Linux/npm (manifest showed `REFERENCES 0 / TEMPLATES 0`).
+  Installer now reads the exact on-disk case and both dirs are allowlisted.
+
+### Added
+
+- **`tests/packaging-allowlist.test.js`** — packs the real tarball (`npm pack --dry-run
+  --json`) and asserts commands, skills, subagents, entry files, the full `.mindforge/`
+  framework, and `.planning/` templates all ship, while runtime DBs/telemetry do not.
+  Proven to fail under the broken v11.3.0 allowlist. Skips loudly if npm is unavailable.
+
+## [11.3.0] - 2026-06-04 — "Legion" (154-subagent expansion)
+
+Imports the full VoltAgent `awesome-claude-code-subagents` collection (154 Claude-Code-native
+subagents across 10 categories) into MindForge, fully rebranded. Additive and
+backward-compatible — no existing persona, skill, or command changed behavior.
+
+### Added
+
+- **`subagents/` tree** — 154 specialized subagent definitions in 10 categories
+  (`01-core-development` … `10-research-analysis`), kept verbatim from upstream except
+  the rebrand and collision/functional fixes below. Agent bodies are unmodified prose.
+- **`.mindforge/imported-agents.jsonl`** — generated index (name → path → category → model →
+  description) and **`scripts/build-subagent-index.js`** to regenerate it deterministically.
+- **`bin/spawn-agent.js subagent <name>`** — third loader mode that resolves an imported
+  subagent via the index. Hardened with a strict name allowlist (`[A-Za-z0-9-_]`), exact
+  index-match resolution (never builds a path from input), and a `subagents/` containment
+  check — defense-in-depth path-traversal guards consistent with `BLOCK_ON_SECURITY`.
+- **Installer delivery** — `bin/installer-core.js` now installs the 154 subagents into the
+  runtime's native agents directory (`.claude/agents/`, via the new `agentsSubdir` runtime
+  config + `installSubagents()`), flattening the category tree (READMEs excluded) so Claude
+  Code auto-discovers them. Runs for both global and local scope; mirrored to `.claude/agents/`
+  for non-claude local runtimes. Shown in `--dry-run` and the payload manifest; `--uninstall`
+  removes only the imported set, never the user's own agents. The `.mindforge/imported-agents.jsonl`
+  index ships with `.mindforge/`, so the `subagent` loader mode also works post-install.
+- **`tests/subagent-import.test.js`** — asserts 154 indexed, every path exists, all 16
+  collisions renamed, no bare-name clash with personas, and the loader's traversal guards.
+
+### Changed (rebrand — VoltAgent → MindForge)
+
+- Plugin/marketplace metadata (`subagents/.claude-plugin/marketplace.json` + 10 category
+  `plugin.json`) renamed `voltagent-*` → `mindforge-*`, author → MindForge Team, URLs →
+  `github.com/sairam0424/MindForge`. Per-plugin versions preserved for upstream re-sync.
+  No live marketplace is published — metadata only.
+- 16 name collisions with existing hand-authored MindForge personas resolved with a `-cc`
+  suffix (`api-designer-cc`, `debugger-cc`, …); the original personas remain authoritative
+  for the bare names.
+- **agent-installer** fetch URLs repointed to `sairam0424/MindForge` under `subagents/`.
+- **design-bridge** VoltAgent design-md dependency replaced with a `<DESIGN_MD_SOURCE>`
+  placeholder + a needs-configuration notice (MindForge ships no design-md repo yet).
+- Dead VoltAgent Discord/sponsor links removed (no MindForge equivalent).
+- `package.json` `files` allowlist now ships `subagents/` + the index; README capability
+  line notes the 154 subagents.
+
 ## [11.2.1] - 2026-05-31 — "Hardening" (security & integrity audit remediation)
 
 Post-v11.2.0 audit remediation. Closes every exploitable security defect and

package/MINDFORGE.md

@@ -1,12 +1,12 @@
-# MINDFORGE.md — Parameter Registry (v11.2.1)
+# MINDFORGE.md — Parameter Registry (v11.3.1)
 
 ## 1. IDENTITY & VERSIONING
 
 [NAME]    = MindForge
-[VERSION] = 11.2.1
+[VERSION] = 11.3.1
 [STABLE]  = true
 [MODE]    = "Platform Sovereign"
-[REQUIRED_CORE_VERSION] = 11.2.1
+[REQUIRED_CORE_VERSION] = 11.3.1
 [SOVEREIGN_IDENTITY] = true
 [SRE_LAYER_ENABLED]  = true
 

package/README.md

@@ -15,7 +15,7 @@ MindForge v11.0.0 "Sovereign Stability" is a production-hardening release focuse
 - **Production observability** — `/api/v1/system` health endpoint, P95 latency tracking, heap health monitoring, and real EIS client with retry logic.
 - **Graduated intelligence** — Adaptive tier escalation (+1/+2/MAX) with cost-awareness, 3-tier stuck detection, and adaptive context windows.
 
-This release ships 200+ skills, 400+ personas, 18 pillars, and 49 swarm templates across 12 engineering domains.
+This release ships 200+ skills, 400+ personas, 154 specialized subagents, 18 pillars, and 49 swarm templates across 12 engineering domains.
 
 
 ## Installation & Setup

package/bin/installer-core.js

@@ -28,6 +28,7 @@ const RUNTIMES = {
     docsSubdir:     'docs',
     memorySubdir:   'memory',
     pluginsSubdir:  'plugins',
+    agentsSubdir:   'agents',
   },
   antigravity: {
     displayName:    'Antigravity',
@@ -203,6 +204,50 @@ const fsu = {
   },
 };
 
+/**
+ * Flatten-copy the imported Claude-Code subagents into a runtime's native agents
+ * directory. The 154 source files live under subagents/categories/NN-name/*.md;
+ * Claude Code auto-discovers agents from the top level of .claude/agents/, so we
+ * flatten (basenames are already collision-free after the -cc renames) and skip
+ * the per-category README.md index files. Returns the count installed.
+ * @param {string} agentsDir - Destination agents directory (absolute).
+ * @param {object} options - { noOverwrite }.
+ * @returns {number} number of agent files copied.
+ */
+function installSubagents(agentsDir, options = {}) {
+  const { noOverwrite = false } = options;
+  const sourceDir = src('subagents', 'categories');
+  if (!fsu.exists(sourceDir)) return 0;
+
+  fsu.ensureDir(agentsDir);
+  let count = 0;
+  for (const file of fsu.listFilesRecursive(sourceDir, '.md')) {
+    if (path.basename(file) === 'README.md') continue;
+    const dst = path.join(agentsDir, path.basename(file));
+    if (noOverwrite && fsu.exists(dst)) continue;
+    fsu.copy(file, dst);
+    count++;
+  }
+  return count;
+}
+
+/**
+ * The set of imported-subagent basenames (e.g. 'api-designer-cc.md'). Used by
+ * uninstall to remove ONLY our agents from a runtime's agents/ dir, never the
+ * user's own hand-authored agents that may live alongside them.
+ * @returns {Set<string>}
+ */
+function importedSubagentBasenames() {
+  const sourceDir = src('subagents', 'categories');
+  const names = new Set();
+  if (!fsu.exists(sourceDir)) return names;
+  for (const file of fsu.listFilesRecursive(sourceDir, '.md')) {
+    const base = path.basename(file);
+    if (base !== 'README.md') names.add(base);
+  }
+  return names;
+}
+
 // ── Registry Management ────────────────────────────────────────────────────────
 const RegistryManager = {
   getRegistryPath: () => path.join(os.homedir(), '.mindforge', 'registry.json'),
@@ -399,8 +444,11 @@ async function install(runtime, scope, options = {}) {
       { key: 'skillsSubdir',   src: src('.agent', 'skills'),      label: 'skills' },
       { key: 'hooksSubdir',    src: src('.agent', 'hooks'),       label: 'hooks' },
       { key: 'personasSubdir', src: src('.mindforge', 'personas'), label: 'personas' },
-      { key: 'docsSubdir',     src: src('docs', 'references'),    label: 'references' },
-      { key: 'docsSubdir',     src: src('docs', 'templates'),     label: 'templates' }
+      // NB: on-disk dirs are capitalized (docs/References, docs/Templates). macOS is
+      // case-insensitive so lowercase used to "work" locally, but npm/Linux is
+      // case-sensitive — the lookup silently missed in production (UC: REFERENCES 0).
+      { key: 'docsSubdir',     src: src('docs', 'References'),    label: 'references' },
+      { key: 'docsSubdir',     src: src('docs', 'Templates'),     label: 'templates' }
     ];
 
     assetMappings.forEach(asset => {
@@ -415,6 +463,13 @@ async function install(runtime, scope, options = {}) {
         }
       }
     });
+
+    if (cfg.agentsSubdir && fsu.exists(src('subagents', 'categories'))) {
+      const agentCount = fsu.listFilesRecursive(src('subagents', 'categories'), '.md')
+        .filter(f => path.basename(f) !== 'README.md').length;
+      const countStr = `${agentCount} subagents`.padEnd(12);
+      console.log(`    ${countStr} → ${path.join(baseDir, cfg.agentsSubdir)}`);
+    }
     return;
   }
 
@@ -528,8 +583,8 @@ async function install(runtime, scope, options = {}) {
       { key: 'skillsSubdir',   src: src('.agent', 'skills'),      label: 'skills' },
       { key: 'hooksSubdir',    src: src('.agent', 'hooks'),       label: 'hooks' },
       { key: 'personasSubdir', src: src('.mindforge', 'personas'), label: 'personas' },
-      { key: 'docsSubdir',     src: src('docs', 'references'),    label: 'references' },
-      { key: 'docsSubdir',     src: src('docs', 'templates'),     label: 'templates' },
+      { key: 'docsSubdir',     src: src('docs', 'References'),    label: 'references' },
+      { key: 'docsSubdir',     src: src('docs', 'Templates'),     label: 'templates' },
       { key: 'memorySubdir',   src: src('.mindforge', 'memory'),   label: 'memory' },
       { key: 'pluginsSubdir',  src: src('.mindforge', 'plugins'),  label: 'plugins' }
     ];
@@ -550,6 +605,21 @@ async function install(runtime, scope, options = {}) {
     });
   }
 
+  // ── 2.2 Install Subagents (native Claude-Code agents, both scopes) ──────────
+  // The 154 imported subagents are Claude-Code-native .md files; Claude Code
+  // auto-discovers them from <runtime>/agents/. Installed for BOTH scopes so a
+  // global install also exposes them. Mirrored to .claude/agents/ for non-claude
+  // local runtimes (same cross-IDE rationale as the command mirror above).
+  if (cfg.agentsSubdir && !selfInstall) {
+    const agentsDir = path.join(baseDir, cfg.agentsSubdir);
+    const count = installSubagents(agentsDir, { noOverwrite: !force });
+    if (count > 0) Theme.printResolved(`${c.bold(`${count} subagents`)} (native agents)`);
+  }
+  if (scope === 'local' && runtime !== 'claude' && !selfInstall) {
+    const mirrorDir = path.join(process.cwd(), '.claude', 'agents');
+    installSubagents(mirrorDir, { noOverwrite: !force });
+  }
+
   // ── 3. Framework files (local scope only, non-self-install) ─────────────────
   if (scope === 'local' && !selfInstall) {
     // .mindforge/ — framework engine files
@@ -591,9 +661,12 @@ async function install(runtime, scope, options = {}) {
       }
     }
 
-    // .planning/ — merge templates but preserve existing state
+    // .planning/ — merge templates but preserve existing state.
+    // Source from examples/starter-project/.planning (clean, generic, always shipped)
+    // — NEVER from the framework repo's own .planning/, which holds live dev state
+    // (AUDIT.jsonl, slack-threads.json, jira-sync.json) that must not reach users.
     const planningDst = path.join(process.cwd(), '.planning');
-    const planningSrc = src('.planning');
+    const planningSrc = src('examples', 'starter-project', '.planning');
     if (fsu.exists(planningSrc)) {
       fsu.ensureDir(planningDst);
       
@@ -633,7 +706,7 @@ async function install(runtime, scope, options = {}) {
 
     // AGENTS_LEARNING.md — create only if it doesn't already exist
     const learningDst = path.join(process.cwd(), 'AGENTS_LEARNING.md');
-    const learningSrc = src('docs', 'templates', 'Project', 'AGENTS_LEARNING.md');
+    const learningSrc = src('docs', 'Templates', 'Project', 'AGENTS_LEARNING.md');
     if (!fsu.exists(learningDst) && fsu.exists(learningSrc)) {
       fsu.copy(learningSrc, learningDst);
       Theme.printResolved(`${c.bold('AGENTS_LEARNING.md')} (agentic memory)`);
@@ -641,7 +714,7 @@ async function install(runtime, scope, options = {}) {
 
     // WALKTHROUGH.md — update if exists
     const walkDst = path.join(process.cwd(), 'WALKTHROUGH.md');
-    const walkSrc = src('docs', 'templates', 'Project', 'WALKTHROUGH.md');
+    const walkSrc = src('docs', 'Templates', 'Project', 'WALKTHROUGH.md');
     if (fsu.exists(walkSrc)) {
       fsu.copy(walkSrc, walkDst);
       Theme.printResolved(`${c.bold('WALKTHROUGH.md')} (updated)`);
@@ -712,9 +785,16 @@ async function uninstall(runtime, scope, options = {}) {
   const cmdsDir = norm(path.join(baseDir, cfg.commandsSubdir));
   const entryFile = norm(path.join(baseDir, cfg.entryFile));
 
+  const agentsDir = cfg.agentsSubdir ? norm(path.join(baseDir, cfg.agentsSubdir)) : null;
+  const importedAgents = importedSubagentBasenames();
+
   console.log(`\n  Uninstalling MindForge (${runtime} / ${scope})...`);
   if (dryRun) {
     console.log(`  Would remove: ${cmdsDir}`);
+    if (agentsDir && fsu.exists(agentsDir)) {
+      const present = fsu.listFiles(agentsDir).filter(f => importedAgents.has(f)).length;
+      if (present > 0) console.log(`  Would remove: ${present} imported subagents from ${agentsDir}`);
+    }
     if (fsu.exists(entryFile) && fsu.read(entryFile).includes('MindForge'))
       console.log(`  Would remove: ${entryFile}`);
     return;
@@ -726,6 +806,18 @@ async function uninstall(runtime, scope, options = {}) {
     console.log(`  ✅  Removed: ${cmdsDir}`);
   }
 
+  // Remove ONLY our imported subagents — leave the user's own agents/ files intact.
+  if (agentsDir && fsu.exists(agentsDir)) {
+    let removed = 0;
+    for (const f of fsu.listFiles(agentsDir)) {
+      if (importedAgents.has(f)) {
+        fs.unlinkSync(path.join(agentsDir, f));
+        removed++;
+      }
+    }
+    if (removed > 0) console.log(`  ✅  Removed: ${removed} imported subagents from ${agentsDir}`);
+  }
+
   // Remove entry file only if it's a MindForge-generated file
   if (fsu.exists(entryFile) && fsu.read(entryFile).includes('MindForge')) {
     fs.unlinkSync(entryFile);
@@ -744,6 +836,7 @@ function collectManifestStats() {
   const stats = {
     personas: 0,
     skills: 0,
+    subagents: 0,
     governance: 0,
     integrations: 0,
     actions: 0,
@@ -760,9 +853,16 @@ function collectManifestStats() {
       stats.integrations = fsu.listFiles(path.join(forgeSrc, 'integrations')).filter(f => f.endsWith('.md')).length;
     }
 
-    // Docs & Templates count
-    const refSrc = src('docs', 'references');
-    const tmpSrc = src('docs', 'templates');
+    // Imported subagents (subagents/categories/**, excluding category READMEs)
+    const subagentsSrc = src('subagents', 'categories');
+    if (fsu.exists(subagentsSrc)) {
+      stats.subagents = fsu.listFilesRecursive(subagentsSrc, '.md')
+        .filter(f => path.basename(f) !== 'README.md').length;
+    }
+
+    // Docs & Templates count (on-disk dirs are capitalized — see assetMappings note)
+    const refSrc = src('docs', 'References');
+    const tmpSrc = src('docs', 'Templates');
     if (fsu.exists(refSrc)) stats.docs = fsu.listFiles(refSrc).filter(f => f.endsWith('.md')).length;
     if (fsu.exists(tmpSrc)) stats.templates = fsu.listFilesRecursive(tmpSrc).length;
     
@@ -777,7 +877,7 @@ function collectManifestStats() {
     }
   } catch (e) {
     // Fallback to default values if counting fails
-    return { personas: 117, skills: 20, governance: 4, integrations: 6, actions: 71, docs: 12, templates: 21 };
+    return { personas: 117, skills: 20, subagents: 154, governance: 4, integrations: 6, actions: 71, docs: 12, templates: 21 };
   }
 
   return stats;

package/bin/spawn-agent.js

@@ -10,17 +10,83 @@ const fs = require('fs');
 const path = require('path');
 
 const ARGS = process.argv.slice(2);
-const MODE = ARGS[0]; // 'spawn' or 'identity'
+const MODE = ARGS[0]; // 'spawn', 'identity', or 'subagent'
 const TARGET = ARGS[1];
 const IS_DRY_RUN = ARGS.includes('--dry-run');
 
 const ROOT = path.resolve(__dirname, '..');
+const SUBAGENTS_DIR = path.join(ROOT, 'subagents');
+const INDEX_PATH = path.join(ROOT, '.mindforge', 'imported-agents.jsonl');
+
+// Names are restricted to a strict allowlist: no path separators, no '..', and
+// only [A-Za-z0-9-_]. This is the first line of defense against path traversal
+// in the `subagent` mode — names that fail this never touch the filesystem.
+const SAFE_NAME_PATTERN = /^[A-Za-z0-9-_]+$/;
 
 if (!MODE || !TARGET) {
   console.error('❌ Usage: node bin/spawn-agent.js <mode> <target> [--dry-run]');
+  console.error('   modes: identity | spawn | subagent');
   process.exit(1);
 }
 
+/**
+ * Validate a user-supplied subagent name against the strict allowlist. Rejects
+ * path separators, parent-dir tokens, and any character outside [A-Za-z0-9-_].
+ * Exits the process on violation rather than returning, so no unsafe name can
+ * proceed to a filesystem lookup.
+ */
+function assertSafeName(name) {
+  if (!SAFE_NAME_PATTERN.test(name)) {
+    console.error(`❌ Invalid subagent name: "${name}" (allowed: A-Z a-z 0-9 - _)`);
+    process.exit(1);
+  }
+}
+
+/**
+ * Resolve a subagent name to its index entry by EXACT name match. Never builds
+ * a path from user input — only paths recorded in the trusted index are used.
+ * Returns the matching entry or null if no entry matches.
+ */
+function findIndexEntry(name) {
+  if (!fs.existsSync(INDEX_PATH)) {
+    console.error(`❌ Subagent index not found: ${INDEX_PATH}`);
+    console.error('   Run: node scripts/build-subagent-index.js');
+    process.exit(1);
+  }
+
+  const lines = fs.readFileSync(INDEX_PATH, 'utf8').split('\n');
+  for (const line of lines) {
+    if (!line.trim()) {
+      continue;
+    }
+    const entry = JSON.parse(line);
+    if (entry.name === name) {
+      return entry;
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve and verify the absolute path for an index entry. Confirms the
+ * resolved path stays within the repo's subagents/ directory before returning
+ * it (defense in depth against a tampered index). Exits on any violation.
+ */
+function resolveSubagentPath(entry) {
+  const absolutePath = path.resolve(ROOT, entry.path);
+  const containmentRoot = SUBAGENTS_DIR + path.sep;
+
+  if (!absolutePath.startsWith(containmentRoot)) {
+    console.error(`❌ Resolved path escapes subagents/: ${absolutePath}`);
+    process.exit(1);
+  }
+  if (!fs.existsSync(absolutePath)) {
+    console.error(`❌ Subagent file missing: ${absolutePath}`);
+    process.exit(1);
+  }
+  return absolutePath;
+}
+
 async function run() {
   let identityPath;
   let personaPath;
@@ -39,6 +105,19 @@ async function run() {
       process.exit(1);
     }
     console.log(`🌌 Spawning persona essence: ${TARGET}`);
+  } else if (MODE === 'subagent') {
+    assertSafeName(TARGET);
+    const entry = findIndexEntry(TARGET);
+    if (!entry) {
+      console.error(`❌ Subagent not found in index: ${TARGET}`);
+      process.exit(1);
+    }
+    const subagentPath = resolveSubagentPath(entry);
+    fs.readFileSync(subagentPath, 'utf8'); // verify readability before dispatch
+    console.log(`🧬 Loading imported subagent: ${TARGET} [${entry.category}/${entry.model}]`);
+  } else {
+    console.error(`❌ Unknown mode: ${MODE} (expected identity | spawn | subagent)`);
+    process.exit(1);
   }
 
   if (IS_DRY_RUN) {

package/bin/wizard/theme.js

@@ -125,14 +125,15 @@ const Theme = {
    * Print Manifest (Hardened for V2)
    */
   printManifest(stats = {}) {
-    const { personas = 117, skills = 20, governance = 4, integrations = 7, actions = 71, docs = 12, templates = 21 } = stats;
-    
+    const { personas = 117, skills = 20, subagents = 154, governance = 4, integrations = 7, actions = 71, docs = 12, templates = 21 } = stats;
+
     console.log(`  ${this.colors.bold('PAYLOAD MANIFEST')}`);
     console.log(`  ${this.colors.dim('┌' + '─'.repeat(74) + '┐')}`);
-    
+
     const rows = [
       ['PERSONAS', personas, 'The autonomous persona ecosystem'],
       ['SKILLS', skills, 'Enterprise-grade skill packs'],
+      ['SUBAGENTS', subagents, 'Specialized Claude Code subagents'],
       ['GOVERNANCE', governance, 'Compliance and safety modules'],
       ['INTEGRATIONS', integrations, 'Multi-platform connector suite'],
       ['REFERENCES', docs, 'Standardized architecture references'],

package/docs/References/audit-events.md

@@ -0,0 +1,59 @@
+# MindForge Audit Events — Reference (v1.0.0)
+
+## Overview
+`AUDIT.jsonl` is the append-only record of MindForge operations.
+Each line is a JSON object with a required `event` type and a `session_id`.
+
+## Location
+`.planning/AUDIT.jsonl`
+
+## Required fields (all events)
+- `id` (UUID v4)
+- `timestamp` (ISO-8601)
+- `event` (string)
+- `agent` (string)
+- `phase` (number or null)
+- `session_id` (string)
+- `trace_id` (string, v4.1+) - UUID linking multiple related spans.
+- `span_id` (string, v4.1+) - ID for the current execution unit.
+- `parent_span_id` (string, v4.1+) - Link to the calling span.
+
+## Common event types
+### `project_initialised`
+Fields: `project_name`, `tech_stack`, `compliance`
+
+### `phase_planned`
+Fields: `plan_count`, `wave_count`, `research_conducted`
+
+### `phase_execution_started`
+Fields: `plan_count`, `wave_count`, `dependency_graph_path`
+
+### `phase_execution_completed`
+Fields: `tasks_completed`, `tasks_failed`, `verify_status`, `verification_path`
+
+### `task_started`
+Fields: `plan`, `task_name`
+
+### `task_completed`
+Fields: `plan`, `commit_sha`, `verify_result`
+
+### `security_scan_completed`
+Fields: `critical`, `high`, `medium`, `low`, `findings_path`
+
+### `gate_result`
+Fields: `gate`, `status`, `detail`
+
+### `plugin_installed`
+Fields: `plugin_name`, `version`, `permissions`
+
+### `plugin_uninstalled`
+Fields: `plugin_name`
+
+### `reasoning_trace` (v4.1+)
+Fields: `trace_id`, `span_id`, `persona`, `thought_chain`, `decision_point`, `adversarial_critique` (optional)
+
+## Rotation
+Rotate when file exceeds 10,000 lines. Archive into `.planning/audit-archive/`.
+
+## Schema source
+See `.mindforge/audit/AUDIT-SCHEMA.md` for full examples and field definitions.