mindforge-cc 11.3.1 → 11.5.0

package/.agent/hooks/mindforge-config-protection.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/**
+ * Config Protection Hook
+ *
+ * Blocks modifications to existing linter/formatter/tsconfig files. Agents
+ * frequently weaken these to make checks pass instead of fixing the actual code.
+ * This guard steers the agent back to fixing the source — directly reinforcing
+ * the repo's own "no gate weakening" posture (commit 10de9c1).
+ *
+ * Ported from ECC (scripts/hooks/config-protection.js). Already exports
+ * run(rawInput) so it runs in-process via run-with-flags.js. Pair with hook-flags
+ * so a `standard`/`strict` profile can disable it during legitimate config
+ * bootstrap (MINDFORGE_DISABLED_HOOKS=mindforge-config-protection).
+ *
+ * Exit codes:
+ *   0 = allow (not a config file, or first-time creation of one)
+ *   2 = block (existing config file modification attempted)
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const MAX_STDIN = 1024 * 1024;
+let raw = '';
+
+const PROTECTED_FILES = new Set([
+  // ESLint (legacy + v9 flat config, JS/TS/MJS/CJS)
+  '.eslintrc', '.eslintrc.js', '.eslintrc.cjs', '.eslintrc.json', '.eslintrc.yml', '.eslintrc.yaml',
+  'eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs', 'eslint.config.ts', 'eslint.config.mts', 'eslint.config.cts',
+  // Prettier
+  '.prettierrc', '.prettierrc.js', '.prettierrc.cjs', '.prettierrc.json', '.prettierrc.yml', '.prettierrc.yaml',
+  'prettier.config.js', 'prettier.config.cjs', 'prettier.config.mjs',
+  // Biome
+  'biome.json', 'biome.jsonc',
+  // Ruff (Python)
+  '.ruff.toml', 'ruff.toml',
+  // Note: pyproject.toml intentionally NOT included — it carries project metadata
+  // alongside linter config; blocking it would prevent legitimate dependency edits.
+  // TypeScript compiler config (agents weaken strictness to silence type errors)
+  'tsconfig.json', 'tsconfig.base.json',
+  // Shell / Style / Markdown
+  '.shellcheckrc', '.stylelintrc', '.stylelintrc.json', '.stylelintrc.yml',
+  '.markdownlint.json', '.markdownlint.yaml', '.markdownlintrc',
+  // MindForge governance configs — must never be silently weakened by an agent.
+  // commitlint guards conventional commits; .czrc the commit tooling.
+  'commitlint.config.js', '.czrc',
+]);
+
+function parseInput(inputOrRaw) {
+  if (typeof inputOrRaw === 'string') {
+    try {
+      return inputOrRaw.trim() ? JSON.parse(inputOrRaw) : {};
+    } catch {
+      return {};
+    }
+  }
+  return inputOrRaw && typeof inputOrRaw === 'object' ? inputOrRaw : {};
+}
+
+/**
+ * Exportable run() for in-process execution via run-with-flags.js.
+ */
+function run(inputOrRaw, options = {}) {
+  if (options.truncated) {
+    return {
+      exitCode: 2,
+      stderr:
+        `BLOCKED: Hook input exceeded ${options.maxStdin || MAX_STDIN} bytes. ` +
+        'Refusing to bypass config-protection on a truncated payload. ' +
+        'Retry with a smaller edit or disable the config-protection hook temporarily.'
+    };
+  }
+
+  const input = parseInput(inputOrRaw);
+  const filePath = input?.tool_input?.file_path || input?.tool_input?.file || '';
+  if (!filePath) return { exitCode: 0 };
+
+  const basename = path.basename(filePath);
+  if (PROTECTED_FILES.has(basename)) {
+    // Allow first-time creation — there's no existing config to weaken. Fail
+    // closed on any stat error other than ENOENT. lstatSync so a (possibly
+    // dangling) symlink at the protected path is treated as present.
+    let exists = true;
+    try {
+      fs.lstatSync(filePath);
+    } catch (err) {
+      if (err && err.code === 'ENOENT') {
+        exists = false;
+      }
+      // Any other error (EACCES, EPERM, ELOOP) leaves exists=true — never weaken.
+    }
+
+    if (!exists) {
+      return { exitCode: 0 };
+    }
+
+    return {
+      exitCode: 2,
+      stderr:
+        `BLOCKED: Modifying ${basename} is not allowed. ` +
+        'Fix the source code to satisfy linter/formatter/tsconfig rules instead ' +
+        'of weakening the config. If this is a legitimate config change, disable ' +
+        'the config-protection hook temporarily (MINDFORGE_DISABLED_HOOKS).'
+    };
+  }
+
+  return { exitCode: 0 };
+}
+
+module.exports = { run };
+
+// Stdin fallback for spawnSync execution (when invoked directly, not via require)
+if (require.main === module) {
+  let truncated = /^(1|true|yes)$/i.test(String(process.env.MINDFORGE_HOOK_INPUT_TRUNCATED || ''));
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => {
+    if (raw.length < MAX_STDIN) {
+      const remaining = MAX_STDIN - raw.length;
+      raw += chunk.substring(0, remaining);
+      if (chunk.length > remaining) truncated = true;
+    } else {
+      truncated = true;
+    }
+  });
+
+  process.stdin.on('end', () => {
+    const result = run(raw, {
+      truncated,
+      maxStdin: Number(process.env.MINDFORGE_HOOK_INPUT_MAX_BYTES) || MAX_STDIN
+    });
+
+    if (result.stderr) {
+      process.stderr.write(result.stderr + '\n');
+    }
+
+    if (result.exitCode === 2) {
+      process.exit(2);
+    }
+
+    process.stdout.write(raw);
+  });
+}

package/.agent/hooks/run-with-flags.js

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+/**
+ * Executes a MindForge hook script only when enabled by hook profile flags.
+ *
+ * Ported/adapted from ECC (scripts/hooks/run-with-flags.js):
+ * - env vars renamed ECC_* -> MINDFORGE_*
+ * - getHookRoot() resolves the MindForge .agent root (parent of hooks/) instead
+ *   of CLAUDE_PLUGIN_ROOT, with CLAUDE_PLUGIN_ROOT honored as an override for
+ *   plugin-install layouts.
+ *
+ * Hooks that export run(rawInput) are require()'d in-process (saves a process
+ * spawn). Legacy module-scope stdin hooks (most mindforge-* hooks) take the
+ * spawnSync path.
+ *
+ * Usage:
+ *   node .agent/hooks/run-with-flags.js <hookId> <scriptRelativePath> [profilesCsv]
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { isHookEnabled } = require('./lib/hook-flags');
+const { buildPreToolUseAdditionalContext } = require('./lib/pretooluse-visible-output');
+
+const MAX_STDIN = 1024 * 1024;
+
+function readStdinRaw() {
+  return new Promise(resolve => {
+    let raw = '';
+    let truncated = false;
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => {
+      if (raw.length < MAX_STDIN) {
+        const remaining = MAX_STDIN - raw.length;
+        raw += chunk.substring(0, remaining);
+        if (chunk.length > remaining) {
+          truncated = true;
+        }
+      } else {
+        truncated = true;
+      }
+    });
+    process.stdin.on('end', () => resolve({ raw, truncated }));
+    process.stdin.on('error', () => resolve({ raw, truncated }));
+  });
+}
+
+function writeStderr(stderr) {
+  if (typeof stderr !== 'string' || stderr.length === 0) {
+    return;
+  }
+
+  process.stderr.write(stderr.endsWith('\n') ? stderr : `${stderr}\n`);
+}
+
+function emitHookResult(raw, output) {
+  if (typeof output === 'string' || Buffer.isBuffer(output)) {
+    process.stdout.write(String(output));
+    return 0;
+  }
+
+  if (output && typeof output === 'object') {
+    writeStderr(output.stderr);
+
+    if (Object.prototype.hasOwnProperty.call(output, 'additionalContext')) {
+      process.stdout.write(buildPreToolUseAdditionalContext(output.additionalContext));
+    } else if (Object.prototype.hasOwnProperty.call(output, 'stdout')) {
+      process.stdout.write(String(output.stdout ?? ''));
+    } else if (!Number.isInteger(output.exitCode) || output.exitCode === 0) {
+      process.stdout.write(raw);
+    }
+
+    return Number.isInteger(output.exitCode) ? output.exitCode : 0;
+  }
+
+  process.stdout.write(raw);
+  return 0;
+}
+
+function writeLegacySpawnOutput(raw, result) {
+  const stdout = typeof result.stdout === 'string' ? result.stdout : '';
+  if (stdout) {
+    process.stdout.write(stdout);
+    return;
+  }
+
+  if (Number.isInteger(result.status) && result.status === 0) {
+    process.stdout.write(raw);
+  }
+}
+
+/**
+ * Resolve the MindForge install root. In a plugin-install layout CLAUDE_PLUGIN_ROOT
+ * points at the plugin root; otherwise we resolve the repo/.agent root from this
+ * file's location (.agent/hooks/ -> repo root two levels up).
+ */
+function getHookRoot() {
+  if (process.env.CLAUDE_PLUGIN_ROOT && process.env.CLAUDE_PLUGIN_ROOT.trim()) {
+    return process.env.CLAUDE_PLUGIN_ROOT;
+  }
+  // .agent/hooks/run-with-flags.js -> repo root is two dirs up.
+  return path.resolve(__dirname, '..', '..');
+}
+
+async function main() {
+  const [, , hookId, relScriptPath, profilesCsv] = process.argv;
+  const { raw, truncated } = await readStdinRaw();
+
+  if (!hookId || !relScriptPath) {
+    process.stdout.write(raw);
+    process.exit(0);
+  }
+
+  if (!isHookEnabled(hookId, { profiles: profilesCsv })) {
+    process.stdout.write(raw);
+    process.exit(0);
+  }
+
+  const hookRoot = getHookRoot();
+  const resolvedRoot = path.resolve(hookRoot);
+  const scriptPath = path.resolve(hookRoot, relScriptPath);
+
+  // Prevent path traversal outside the install root
+  if (!scriptPath.startsWith(resolvedRoot + path.sep)) {
+    process.stderr.write(`[Hook] Path traversal rejected for ${hookId}: ${scriptPath}\n`);
+    process.stdout.write(raw);
+    process.exit(0);
+  }
+
+  if (!fs.existsSync(scriptPath)) {
+    process.stderr.write(`[Hook] Script not found for ${hookId}: ${scriptPath}\n`);
+    process.stdout.write(raw);
+    process.exit(0);
+  }
+
+  // Prefer direct require() when the hook exports run(rawInput). Eliminates one
+  // Node process spawn (~50-100ms). Only require() hooks that export run();
+  // legacy hooks run side effects at module scope (stdin listeners, process.exit)
+  // which would interfere with the parent process.
+  let hookModule;
+  const src = fs.readFileSync(scriptPath, 'utf8');
+  const hasRunExport = /\bmodule\.exports\b/.test(src) && /\brun\b/.test(src);
+
+  if (hasRunExport) {
+    try {
+      hookModule = require(scriptPath);
+    } catch (requireErr) {
+      process.stderr.write(`[Hook] require() failed for ${hookId}: ${requireErr.message}\n`);
+      // Fall through to legacy spawnSync path
+    }
+  }
+
+  if (hookModule && typeof hookModule.run === 'function') {
+    try {
+      const output = hookModule.run(raw, {
+        hookId,
+        hookRoot,
+        scriptPath,
+        truncated,
+        maxStdin: MAX_STDIN
+      });
+      process.exit(emitHookResult(raw, output));
+    } catch (runErr) {
+      process.stderr.write(`[Hook] run() error for ${hookId}: ${runErr.message}\n`);
+      process.stdout.write(raw);
+    }
+    process.exit(0);
+  }
+
+  // Legacy path: spawn a child Node process for hooks without run() export
+  const result = spawnSync(process.execPath, [scriptPath], {
+    input: raw,
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      CLAUDE_PLUGIN_ROOT: hookRoot,
+      MINDFORGE_HOOK_ROOT: hookRoot,
+      MINDFORGE_HOOK_ID: hookId,
+      MINDFORGE_HOOK_INPUT_TRUNCATED: truncated ? '1' : '0',
+      MINDFORGE_HOOK_INPUT_MAX_BYTES: String(MAX_STDIN)
+    },
+    cwd: process.cwd(),
+    timeout: 30000
+  });
+
+  writeLegacySpawnOutput(raw, result);
+  if (result.stderr) process.stderr.write(result.stderr);
+
+  if (result.error || result.signal || result.status === null) {
+    const failureDetail = result.error
+      ? result.error.message
+      : result.signal
+        ? `terminated by signal ${result.signal}`
+        : 'missing exit status';
+    writeStderr(`[Hook] legacy hook execution failed for ${hookId}: ${failureDetail}`);
+    process.exit(1);
+  }
+
+  process.exit(Number.isInteger(result.status) ? result.status : 0);
+}
+
+main().catch(err => {
+  process.stderr.write(`[Hook] run-with-flags error: ${err.message}\n`);
+  process.exit(0);
+});

package/.agent/mindforge/checkpoint.md

@@ -0,0 +1,76 @@
+---
+description: "Create, verify, or list lightweight workflow checkpoints — name + timestamp + git SHA + a metrics delta between two points."
+---
+
+# MindForge — Checkpoint Command
+# Usage: /mindforge:checkpoint [create|verify|list|clear] [name]
+
+Lightweight progress markers for a work session. A checkpoint records a name,
+timestamp, git SHA, and a metrics snapshot (files changed, test pass-rate,
+coverage, build status), so you can measure forward progress and catch regressions
+between two points. Distinct from milestones (project lifecycle) — checkpoints are
+intra-session.
+
+## Create Checkpoint
+
+1. Run `/mindforge:verify-loop` (or `verify-phase`) to confirm current state is clean.
+2. Capture the marker:
+
+```bash
+echo "$(date +%Y-%m-%d-%H:%M) | $CHECKPOINT_NAME | $(git rev-parse --short HEAD)" >> .planning/CHECKPOINTS.log
+```
+
+3. Snapshot metrics: changed-file count, test pass-rate, coverage %, build status.
+4. Report checkpoint created.
+
+## Verify Checkpoint
+
+1. Read the named checkpoint from `.planning/CHECKPOINTS.log`.
+2. Compare current state to the checkpoint:
+
+```
+CHECKPOINT COMPARISON: $NAME
+============================
+Files changed:  X
+Tests:          +Y passed / -Z failed
+Coverage:       +X% / -Y%
+Build:          [PASS/FAIL]
+```
+
+3. If any metric regressed (tests down, coverage down, build broken), flag it loudly
+   — a checkpoint verify that shows regression is a stop signal.
+
+## List Checkpoints
+
+Show all checkpoints with name, timestamp, git SHA, and status (current / behind /
+ahead relative to HEAD).
+
+## Clear
+
+Remove old checkpoints, keeping the last 5.
+
+## Workflow
+
+```
+[Start]     -> /mindforge:checkpoint create "feature-start"
+[Implement] -> /mindforge:checkpoint create "core-done"
+[Test]      -> /mindforge:checkpoint verify "core-done"
+[Refactor]  -> /mindforge:checkpoint create "refactor-done"
+[PR]        -> /mindforge:checkpoint verify "feature-start"
+```
+
+## AUDIT linkage
+
+Each create/verify optionally writes a Merkle-linked AUDIT.jsonl entry:
+
+```json
+{ "event": "checkpoint_created", "name": "core-done", "sha": "abc1234", "tests_pass_rate": 1.0, "coverage": 0.0 }
+```
+
+## Arguments
+
+$ARGUMENTS:
+- `create <name>` — create a named checkpoint
+- `verify <name>` — verify current state against a named checkpoint
+- `list` — show all checkpoints
+- `clear` — remove old checkpoints (keeps last 5)

package/.agent/mindforge/harness-audit.md

@@ -0,0 +1,59 @@
+---
+description: "Run the deterministic harness-audit scorecard (0-10 per category) over the MindForge tree, with an optional LLM soft-signal layer."
+---
+
+# MindForge — Harness Audit Command
+# Usage: /mindforge:harness-audit [scope] [--format text|json]
+# Scopes: repo (default) | hooks | skills | commands | agents | security
+
+Two-layer harness health check. The DETERMINISTIC layer is `bin/harness-audit.js`
+(explicit file/config checks, reproducible, CI-gateable). The optional LLM layer
+adds soft signals the deterministic checks cannot see (quality, drift, coherence).
+
+## Step 1 — Run the deterministic scorecard
+
+```bash
+node bin/harness-audit.js              # text scorecard, repo scope
+node bin/harness-audit.js --format json # machine-readable (for CI / dashboards)
+node bin/harness-audit.js --scope security
+```
+
+The JSON contract is stable: `overall_score`, `max_score`, `categories`,
+`applicable_categories`, `rubric_version`, `checks[]`, `top_actions[]`. Categories:
+Tool Coverage, Context Efficiency, Quality Gates, Memory & Learning, Eval Coverage,
+Security Guardrails, Cost Efficiency, Governance & Identity.
+
+## Step 2 — (Optional) LLM soft-signal layer
+
+For each category scoring below 10/10, inspect the failing checks in `top_actions`
+and assess severity in context. The deterministic layer says *what* is missing; the
+LLM layer judges *whether it matters here* and proposes the highest-leverage fix.
+
+## Step 3 — Report + AUDIT entry
+
+Summarize the scorecard, then write a Merkle-linked AUDIT.jsonl entry:
+
+```json
+{
+  "event": "harness_audit_completed",
+  "scope": "repo",
+  "overall_score": 0,
+  "max_score": 0,
+  "rubric_version": "2026-06-10",
+  "failing_categories": [],
+  "top_actions": []
+}
+```
+
+## Relationship to /mindforge:health
+
+`/mindforge:health` calls this command as its deterministic layer. A regression
+(e.g. the `permissions.deny` baseline removed, the Gemini settings mirror desynced,
+the threat-model doc deleted) drops the Security Guardrails score and surfaces in
+`top_actions` — making harness drift visible and CI-blockable.
+
+## Related: cross-harness compliance
+
+`npm run harness:compliance` (`bin/installer/harness-adapter-compliance.js --check`)
+validates the per-harness support matrix and gates documentation drift — distinct
+from this scorecard, which audits the repo's own harness health.

package/.agent/mindforge/instinct.md

@@ -0,0 +1,46 @@
+---
+description: "Manage the instinct store via the deterministic instinct-CLI - list/projects/export/import/promote/prune. Usage - /mindforge:instinct <list|projects|export|import|promote|prune> [options]"
+---
+
+<objective>
+Inspect and maintain the project-scoped instinct store with the deterministic
+CLI (bin/learning/instinct-cli.js). Read-only views (list/projects) are always
+safe; mutating actions (import/promote/prune) require --force and support
+--dry-run. Promotion to a full skill stays with /mindforge:evolve-skills and
+/mindforge:cluster-instincts — this command only LISTS candidates.
+</objective>
+
+<execution_context>
+@.mindforge/engine/instincts/instinct-schema.md
+@.mindforge/skills/continuous-learning/SKILL.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. Parse the subcommand + flags from $ARGUMENTS and shell out to the CLI:
+   `node bin/learning/instinct-cli.js <subcommand> [flags]`
+   - `list [--project <id>|--all] [--status active|promoted|deprecated|pruned] [--json]`
+     — defaults to the current project's instincts plus `global`.
+   - `projects [--json]` — per-project counts, active count, avg confidence, last-applied.
+   - `export [--project <id>|--all] [--status <s>] [--min-confidence N] [-o file]`
+     — emits a JSONL subset (portable interchange) to stdout or a file.
+   - `import <file|https-url> [--scope project|global] [--min-confidence N] [--dry-run] [--force]`
+     — https-only + SSRF-guarded for URLs; dedups by id keeping higher confidence;
+       stamps project_id + source:imported. Default lists what WOULD import; --force writes.
+   - `promote [<id>] [--project <id>|--all] [--dry-run] [--force]`
+     — LISTS instincts meeting confidence ≥ threshold AND applied ≥ min; does NOT
+       create skills (run /mindforge:evolve-skills for that). --force only flags.
+   - `prune [--max-age <days>] [--dry-run] [--force]`
+     — flags low-confidence/high-applied or stale instincts as pruned; --force writes.
+2. Relay the CLI output. For mutating actions, prefer running --dry-run first and
+   showing the user the diff before re-running with --force.
+3. The CLI writes atomically under an advisory lock, so it is safe to run while
+   the capture hook is appending. It spawns no model and incurs no token cost.
+4. Optionally log an AUDIT entry for a mutating action (import/promote/prune).
+
+NOTE: this command and its .agent/mindforge/ mirror MUST be edited together —
+they are kept byte-identical.
+</process>

package/.agent/mindforge/orch-add-feature.md

@@ -0,0 +1,43 @@
+---
+description: Orchestrate building a brand-new feature end to end — research, plan, TDD, review, gated commit. Thin wrapper over the orch-pipeline skill.
+---
+
+# MindForge — Orch: Add Feature
+# Usage: /mindforge:orch-add-feature <what to add>
+
+Manually launch the **add-feature** orchestration: a gated
+Research → Plan → TDD → Review → Commit pipeline for net-new capability.
+
+## Usage
+
+```
+/mindforge:orch-add-feature <what to add>
+```
+
+Examples:
+
+```
+/mindforge:orch-add-feature add OAuth2 login to the auth service
+/mindforge:orch-add-feature support CSV export in the dashboard
+```
+
+## What It Does
+
+Activate the `orch-pipeline` skill (`.mindforge/skills/orch-pipeline/SKILL.md`)
+with `$ARGUMENTS` as the request and `operation = add-feature`. The engine will:
+
+1. **Step 0 — size classifier**: classify size on blast radius and state the tier
+   in one line (no floor; classify on the three signals). The user may override.
+2. Research existing libraries/patterns (Search-Before-Building), then plan a
+   MindForge XML `<action>` task_list under `.planning/` via
+   `/mindforge:plan-write`. → **GATE 1** (approve plan).
+3. TDD each task via `mindforge-tdd_extended` (new failing tests → green), then
+   `/mindforge:review` (+ the `quick.md` security auto-trigger / `security-reviewer`
+   if a security trigger is touched).
+4. Commit as conventional `feat(...)` commits, each writing a Merkle-linked
+   AUDIT.jsonl entry. → **GATE 2** (confirm before commit).
+
+Honor both gates — do not write implementation before Gate 1, do not commit
+before Gate 2.
+
+If `$ARGUMENTS` is empty, ask the user what capability to add.

package/.agent/mindforge/orch-build-mvp.md

@@ -0,0 +1,48 @@
+---
+description: Orchestrate bootstrapping a working MVP from a design/spec doc — ingest, slice, scaffold, TDD, review, gated commit. Thin wrapper over the orch-pipeline skill (build loop delegates to the swarm; GAN harness deferred).
+---
+
+# MindForge — Orch: Build MVP
+# Usage: /mindforge:orch-build-mvp <path to design/spec doc>
+
+Manually launch the **build-mvp** orchestration: turn an SDD/PRD/system-design
+document into a running vertical slice.
+
+## Usage
+
+```
+/mindforge:orch-build-mvp <path to design/spec doc>
+```
+
+Examples:
+
+```
+/mindforge:orch-build-mvp docs/SDD-v0.6.md
+/mindforge:orch-build-mvp .planning/REQUIREMENTS.md
+```
+
+## What It Does
+
+Activate the `orch-pipeline` skill (`.mindforge/skills/orch-pipeline/SKILL.md`)
+with `$ARGUMENTS` as the doc path and `operation = build-mvp` (default floor:
+**large**, full pipeline incl. Scaffold). The engine will:
+
+1. **Step 0 — size classifier** (floor large). Read the spec; extract scope,
+   locked decisions, and a feature list ordered as **thin vertical slices** (one
+   end-to-end path first), written as MindForge XML under `.planning/` via
+   `/mindforge:plan-write`. → **GATE 1** (approve slice plan).
+2. Scaffold the first end-to-end slice.
+3. **Build loop — delegate to the swarm.** Drive each vertical slice through
+   `WaveExecutor` / the `mindforge-swarm-execution` protocol
+   (`.mindforge/engine/wave-executor.md`), with `SwarmController`
+   (`.mindforge/engine/swarm-controller.md`) selecting the cluster, gated by
+   `mindforge-tdd_extended` (Red-Green) and `/mindforge:cross-review`.
+   > **GAN harness is deferred** — the ECC GAN generate/evaluate inner loop
+   > (`/gan-build`, generator → evaluator) is NOT ported. See the DESCOPE note in
+   > the orch-pipeline skill.
+4. `/mindforge:review` (+ the `quick.md` security auto-trigger / `security-reviewer`
+   on any security-trigger slice), then commit the scaffold and each slice as
+   separate conventional `feat(...)` commits, each writing a Merkle-linked
+   AUDIT.jsonl entry. → **GATE 2**.
+
+If `$ARGUMENTS` is empty, ask the user for the path to the design/spec doc.

package/.agent/mindforge/orch-change-feature.md

@@ -0,0 +1,45 @@
+---
+description: Orchestrate altering an existing, working feature to new desired behavior — update tests to the new spec, change impl, review, gated commit. Thin wrapper over the orch-pipeline skill.
+---
+
+# MindForge — Orch: Change Feature
+# Usage: /mindforge:orch-change-feature <the new desired behavior>
+
+Manually launch the **change-feature** orchestration: change behavior that
+already works to a new desired spec, tests-first.
+
+## Usage
+
+```
+/mindforge:orch-change-feature <the new desired behavior>
+```
+
+Examples:
+
+```
+/mindforge:orch-change-feature alert at 2 warnings instead of 3
+/mindforge:orch-change-feature instead of sorting by date, sort by priority
+```
+
+## What It Does
+
+Activate the `orch-pipeline` skill (`.mindforge/skills/orch-pipeline/SKILL.md`)
+with `$ARGUMENTS` as the request and `operation = change-feature`. The engine will:
+
+1. **Step 0 — size classifier**: classify size (default floor: **small**) and
+   state the tier in one line.
+2. Light plan only if the new behavior needs research, written as MindForge XML
+   under `.planning/` via `/mindforge:plan-write`. → **GATE 1** (approve
+   changed-test plan).
+3. **Update the existing tests** to express the new behavior, then change the
+   implementation until green via `mindforge-tdd_extended`. (Changing the tests
+   first is what makes this a tweak, not a fix.)
+4. `/mindforge:review` (+ the `quick.md` security auto-trigger / `security-reviewer`
+   on a security trigger), then commit as conventional `feat(...)` / `refactor(...)`
+   + Merkle-linked AUDIT.jsonl entry. → **GATE 2**.
+
+Use this only when the feature **works** but should behave differently — not for
+bugs (`/mindforge:orch-fix-defect`) or net-new capability
+(`/mindforge:orch-add-feature`).
+
+If `$ARGUMENTS` is empty, ask the user what behavior should change.