@mutmutco/opencode-mmi 2.48.0

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+type Config = {
+    skills?: {
+        paths?: string[];
+        urls?: string[];
+    };
+    command?: Record<string, {
+        template: string;
+        description?: string;
+        agent?: string;
+    }>;
+    permission?: Record<string, unknown> | string;
+};
+type HookOutput = {
+    env?: Record<string, string>;
+    args?: Record<string, unknown>;
+    context?: string[];
+};
+type ToolInput = {
+    tool?: string;
+};
+type MmiOptions = {
+    skillsPath?: string;
+    commandAgent?: string;
+};
+declare function beforeTool(input: ToolInput, output: HookOutput): Promise<void>;
+declare function shellEnv(_input: unknown, output: HookOutput): Promise<void>;
+declare function compacting(_input: unknown, output: HookOutput): Promise<void>;
+declare function MmiOpenCodePlugin(_ctx: unknown, rawOptions?: MmiOptions): Promise<{
+    config: (cfg: Config) => void;
+    'shell.env': typeof shellEnv;
+    'tool.execute.before': typeof beforeTool;
+    'experimental.session.compacting': typeof compacting;
+}>;
+export default MmiOpenCodePlugin;
+export { MmiOpenCodePlugin };

package/dist/index.js

@@ -0,0 +1,194 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+const WORKFLOW_SKILLS = [
+    'mmi',
+    'secrets',
+    'stage',
+    'rcand',
+    'release',
+    'hotfix',
+    'bootstrap',
+    'grind',
+    'build',
+    'handoff',
+    'coop',
+    'browser-automation',
+];
+const DEFAULT_SKILLS_PATH = fileURLToPath(new URL('../skills', import.meta.url));
+const DEFAULT_COMMAND_AGENT = 'build';
+// The adapter knows its own version at load (it IS the installed npm package), which is the reliable
+// "installed opencode plugin version" signal doctor reads back via MMI_OPENCODE_PLUGIN_VERSION. Resolve
+// the package's own package.json relative to this compiled module; on any failure return undefined so the
+// stamp is simply omitted — the guardrail hooks must never throw.
+function readPluginVersion() {
+    try {
+        const pkgUrl = new URL('../package.json', import.meta.url);
+        const pkg = JSON.parse(readFileSync(pkgUrl, 'utf8'));
+        return typeof pkg.version === 'string' ? pkg.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function addSkillPermission(cfg) {
+    if (cfg.permission === undefined) {
+        cfg.permission = { skill: { '*': 'allow' } };
+        return;
+    }
+    if (cfg.permission && typeof cfg.permission === 'object' && !Array.isArray(cfg.permission)) {
+        cfg.permission.skill = cfg.permission.skill ?? { '*': 'allow' };
+    }
+}
+function uniqueAppend(values, value) {
+    return Array.from(new Set([...(values ?? []), value]));
+}
+function commandDescription(skill) {
+    if (skill === 'mmi')
+        return 'Run the MMI work-board workflow.';
+    if (skill === 'browser-automation')
+        return 'Run the MMI browser automation workflow.';
+    return `Run the MMI ${skill} workflow.`;
+}
+function commandTemplate(skill) {
+    return [
+        `Use the \`${skill}\` skill and follow it exactly.`,
+        '',
+        '$ARGUMENTS',
+    ].join('\n');
+}
+function ensureConfig(cfg, options) {
+    cfg.skills = cfg.skills ?? {};
+    cfg.skills.paths = uniqueAppend(cfg.skills.paths, options.skillsPath);
+    cfg.command = cfg.command ?? {};
+    for (const skill of WORKFLOW_SKILLS) {
+        cfg.command[skill] = cfg.command[skill] ?? {
+            template: commandTemplate(skill),
+            description: commandDescription(skill),
+            agent: options.commandAgent,
+        };
+    }
+    addSkillPermission(cfg);
+}
+function normalizeToolName(name) {
+    return String(name ?? '').trim().toLowerCase();
+}
+function toolFilePath(args) {
+    return String(args.filePath ?? args.file_path ?? args.path ?? args.target_file ?? '').trim();
+}
+function isRealEnvPath(filePath) {
+    const normalized = filePath.replace(/\\/g, '/');
+    const base = normalized.split('/').pop() ?? '';
+    if (!base.startsWith('.env'))
+        return false;
+    if (base === '.env.example' || base.endsWith('.example') || base.includes('.template'))
+        return false;
+    return true;
+}
+function stripQuoted(command) {
+    return command.replace(/'[^']*'/g, ' ').replace(/"[^"]*"/g, ' ');
+}
+function gitSubcommandRest(command, subcommand) {
+    const re = new RegExp(`\\bgit(?:\\s+(?:-C\\s+\\S+|--no-pager|-c\\s+\\S+))*\\s+${subcommand}\\b(.*)$`, 'is');
+    const match = re.exec(command);
+    return match ? match[1] : null;
+}
+function hasNonFlagToken(rest, skip = new Set()) {
+    for (const token of rest.trim().split(/\s+/).filter(Boolean)) {
+        if (token.startsWith('-') || skip.has(token))
+            continue;
+        return true;
+    }
+    return false;
+}
+function hasGitBounds(subcommand, rest) {
+    if (subcommand === 'diff') {
+        return /--stat\b/i.test(rest) || /--name-only\b/i.test(rest) || /--numstat\b/i.test(rest) || /-U\d+/i.test(rest) || /\s--\s+\S/.test(rest) || hasNonFlagToken(rest);
+    }
+    if (subcommand === 'show') {
+        return /--stat\b/i.test(rest) || /--name-only\b/i.test(rest) || /-U\d+/i.test(rest) || /\S+:\S+/.test(rest);
+    }
+    if (subcommand === 'log') {
+        return /-n\s*\d+/i.test(rest) || /--max-count\b/i.test(rest) || /\s-\d+\b/.test(rest) || hasNonFlagToken(rest, new Set(['--oneline']));
+    }
+    return false;
+}
+function boundedLogCommand(command) {
+    if (/\bGet-Content\b/i.test(command)) {
+        if (/-(?:Tail|TotalCount)\s+\d+/i.test(command))
+            return true;
+        if (/\|\s*Select-Object\s+-(?:Last|First)\s+\d+/i.test(command))
+            return true;
+    }
+    if (/\b(cat|type)\s+[^\s|;&]+\.(log|txt)\b/i.test(command)) {
+        if (/\|\s*tail\s+/i.test(command))
+            return true;
+        if (/\|\s*head\s+/i.test(command))
+            return true;
+        if (/\|\s*Select-Object\s+-(?:Last|First)\s+\d+/i.test(command))
+            return true;
+    }
+    return false;
+}
+function shellBlockReason(command) {
+    const cmd = stripQuoted(command).trim();
+    const diffRest = gitSubcommandRest(cmd, 'diff');
+    if (diffRest != null && !hasGitBounds('diff', diffRest)) {
+        return 'Unbounded `git diff` floods context. Re-run with `git diff --stat` first, then `git diff -U20 -- <path>` on the file you will edit.';
+    }
+    const showRest = gitSubcommandRest(cmd, 'show');
+    if (showRest != null && !hasGitBounds('show', showRest)) {
+        return 'Unbounded `git show` floods context. Re-run with `git show --stat <ref>`, `-U20`, or `<ref>:<path>`.';
+    }
+    const logRest = gitSubcommandRest(cmd, 'log');
+    if (logRest != null && !hasGitBounds('log', logRest)) {
+        return 'Unbounded `git log` floods context. Re-run with `git log -n 20 --oneline`, `git log -5`, or a path-scoped log.';
+    }
+    if (/\bdocker\s+logs\b/i.test(cmd) && !/--tail\b/i.test(cmd)) {
+        return 'Unbounded `docker logs` floods context. Re-run with `docker logs --tail 100 <container>`.';
+    }
+    if (/\bjournalctl\b/i.test(cmd) && !/-n\s*\d+/i.test(cmd) && !/--lines\b/i.test(cmd)) {
+        return 'Unbounded `journalctl` floods context. Re-run with `journalctl -n 100` or `-u <unit> -n 50`.';
+    }
+    const logDump = /\b(cat|type)\s+[^\s|;&]+\.(log|txt)\b/i.test(cmd) || /\bGet-Content\b[^\n|;&]*\.(log|txt)\b/i.test(cmd);
+    if (logDump && !boundedLogCommand(cmd)) {
+        return 'Full log dumps flood context. Re-run with `Get-Content file.log -Tail 80`, `... | Select-Object -Last 80` (PowerShell), or `tail -n 80 file.log` (Bash).';
+    }
+    return undefined;
+}
+async function beforeTool(input, output) {
+    const args = (output.args ?? {});
+    const tool = normalizeToolName(input.tool);
+    if ((tool === 'write' || tool === 'edit' || tool === 'apply_patch') && isRealEnvPath(toolFilePath(args))) {
+        throw new Error('Vault only: do not edit or write .env files. Use /secrets for runtime config.');
+    }
+    if (tool === 'bash') {
+        const reason = shellBlockReason(String(args.command ?? ''));
+        if (reason)
+            throw new Error(reason);
+    }
+}
+async function shellEnv(_input, output) {
+    output.env = output.env ?? {};
+    output.env.MMI_AGENT_SURFACE = 'opencode';
+    const version = readPluginVersion();
+    if (version)
+        output.env.MMI_OPENCODE_PLUGIN_VERSION = version;
+}
+async function compacting(_input, output) {
+    output.context = output.context ?? [];
+    output.context.push('MMI continuity: preserve issue/PR refs, saga and North Star anchors, blockers, decisions, verification state, and NEXT.');
+}
+async function MmiOpenCodePlugin(_ctx, rawOptions) {
+    const options = {
+        skillsPath: rawOptions?.skillsPath ?? DEFAULT_SKILLS_PATH,
+        commandAgent: rawOptions?.commandAgent ?? DEFAULT_COMMAND_AGENT,
+    };
+    return {
+        config: (cfg) => ensureConfig(cfg, options),
+        'shell.env': shellEnv,
+        'tool.execute.before': beforeTool,
+        'experimental.session.compacting': compacting,
+    };
+}
+export default MmiOpenCodePlugin;
+export { MmiOpenCodePlugin };

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@mutmutco/opencode-mmi",
+  "version": "2.48.0",
+  "description": "MMI Future OpenCode adapter — registers mmi, secrets, stage, rcand, release, hotfix, bootstrap, grind, build, handoff, coop, and browser-automation skills, workflow commands, and deterministic guardrail hooks.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "author": {
+    "name": "MMI Future",
+    "email": "suphi@mutatismutandis.co"
+  },
+  "homepage": "https://github.com/mutmutco/MMI-Hub#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mutmutco/MMI-Hub.git",
+    "directory": "plugins/opencode-mmi"
+  },
+  "bugs": {
+    "url": "https://github.com/mutmutco/MMI-Hub/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/skills/_shared/doctrine.md

@@ -0,0 +1,238 @@
+# Shared build/grind doctrine
+
+Single source for doctrine shared by `/grind` and `/build`. Both skills reference this file — do not duplicate these blocks in `SKILL.md`.
+
+## Fusion doctrine
+
+**Fusion** is one shape used everywhere — planning, exploration, and verification:
+
+> **2–3 cross-vendor agents tackle the same hard problem in parallel → a judge synthesizes the best parts into one outcome.**
+
+- **Planning / explore:** N parallel planner sub-agents → verifier-tier **judge** fuses approaches into one plan + criteria.
+- **Verification:** N parallel lenses on the same diff → **synthesizer** reconciles into one `PanelReport`.
+
+Fusion is **not** assigning different models to different pipeline steps (builder on step 1, verifier on step 2 as a workflow handoff). It is **parallel independent work on the same artifact, then reconcile**.
+
+Hard rules:
+
+- Fusion is **planner-judge with vendor diversity**, not "different models for different steps".
+- **Verifier (or judge) is never the builder.** Hard lenses run at verifier tier minimum.
+- When the host exposes multiple vendors, prefer maximum spread on each fusion round. Document any gap honestly — never claim fusion ran cross-vendor when only one vendor was available.
+- Invoking `/grind`, `/grind --auto`, or `/build` authorizes the planner, verifier, judge, and synthesizer panels those skills require, within their normal bounds. On Codex, use `multi_agent_v1` for standard panels when that tool is available.
+- A single-vendor host degrades gracefully: different temperatures or repeat passes; still run the synthesizer. Note degradation in saga and halt/end-of-grind reports.
+
+Use fusion on the hard parts — plan choices, ambiguous specs, security-critical surfaces, verification rounds at checkpoints. Do not spend fusion tokens on trivial slices.
+
+## Panel evidence contract
+
+- Use the host's multi-agent panel mechanism when it is available. Degrade only when the tool is unavailable, a spawn is denied/null, or the user explicitly disables delegation/panels.
+- State degraded fallback explicitly in saga notes and final reports. A degraded round is evidence with a ceiling, not a normal clean panel.
+- `mmi-cli verify synthesize` is a reconciliation helper for real verifier lane JSON. It must not replace an available host panel, and it must not be fed empty input or controller-authored all-pass stubs.
+- Two stable clean rounds count only when the required verifier process actually produced the lens outputs. Empty, missing, or self-authored pass JSON is invalid fresh-eyes evidence.
+
+## Parallelism doctrine
+
+**Maximum parallelism is the default.** Fan out independent planners, lenses, sub-agents, sites, and research concurrently. Serialize only where work shares seams (same files, ordering dependencies, shared generated artifacts such as `cli/dist/*`).
+
+- **Independent sites / issues** → parallel loops in separate worktrees, each its own PR.
+- **Planners on one hard part** → parallel fan-out, then judge fuses.
+- **Verification lenses** → always parallel; synthesizer runs once after.
+- **Research spikes** → parallel sub-agents when more than one angle needs grounding.
+
+When parallel work collides on a generated artifact at merge time, the second-mover **rebases, rebuilds the artifact, re-verifies**, then merges — never resolve the artifact conflict by hand.
+
+**Batch by default.** Each tier's `parallelSitesCap` (`build-policy.ts`) is a ceiling to fill, not a number to stay under. When independent slices exist, **batch them up to the cap** rather than serializing one at a time — group same-shaped edits, fan out side-issue fixes, and claim several board refs in one `board claim` call. Serialize only where work shares seams. Lean toward more batching whenever the slices are genuinely independent.
+
+## Effort tiers (shared)
+
+Both `/grind` and `/build` self-select one of four effort tiers — **`light` · `standard` · `deep` · `ultra`** — encoded in `build-policy.ts` (`pickEffortTier`, `getTierBudgets`). The tier scales agent count, planner/fusion count, `parallelSitesCap`, verification depth, and reasoning effort together.
+
+- Tiers are auto-selected from signals (scope, risk, ambiguity, blast radius, foundational depth). When unsure, default `standard`.
+- **Explicit flags force a tier on either skill:** `--light`, `--standard`, `--deep`, `--ultra`. An explicit flag always wins over auto-selection.
+- `--ultra` is the top tier = whole-loop YOLO (max planners, fusion on hard parts, deepest verification, highest reasoning). It is **distinct from auto-ultra** (the automatic verify-panel uplift, which raises verification only).
+- Inspect a tier: `mmi-cli build tier [--scope … --risk …] [--explicit <tier>]`.
+
+## Model economy
+
+**Prefer the lightest model that clears the bar.** Reach for a heavier model only when the work needs it — a hard plan, an ambiguous spec, a security-critical lens, a failing verify round. Routine builder turns, mechanical edits, and light-tier slices run on a lighter model. Reserve top-tier models for fusion planners, hard lenses, and `ultra`-tier sites. Spending a frontier model on a one-liner is waste, not rigor.
+
+**Fusion single-API models (opencode `fugu` / `fugu-ultra`, `codex-fugu`):** these already integrate multiple models behind one API, so the cross-vendor panel the skills would otherwise spawn is **built into the model**. On a fusion model:
+
+- **Cap the tier at `light`** — never run higher (`capTierForModel` in `build-policy.ts`). For now only `fugu`, `fugu-ultra` (opencode) and `codex-fugu` are fusion models.
+- **Give them the most straightforward method** — single straight-through pass, **no** multi-agent planner/lens fan-out. The fusion is internal; an external panel is redundant cost.
+- Detect by active model id, or let the opencode plugin pass the signal explicitly when it lands.
+
+## Subagent depth cap (flat fan-out)
+
+Claude Code **2.1.181** hard-caps subagents at **5 levels of nesting depth**; foreground subagents respect the same limit.
+
+**Flat fan-out rule:**
+
+- The **orchestrator** spawns planners, lenses, research spikes, and side-issue fixes as **siblings** — never nested chains (child spawns grandchild spawns great-grandchild).
+- Keep fan-out **wide, not deep** — never let nesting approach 5 levels.
+- If a panel member is missing because depth truncated the fan-out, treat that as **degraded evidence** (see classifier-denied handling below), not a clean round.
+
+Concrete ownership: only the top-level orchestrator (the skill invoker) launches fusion planners and verify lenses. Sub-agents return JSON or markdown; they do **not** spawn their own sub-panels unless the skill explicitly says otherwise for that one role.
+
+**Sub-agent continuation is host-scoped (#1943/#1956).** `SendMessage` can continue a previously-spawned agent only on hosts that expose it to the top-level orchestrator; it is **not** in a sub-agent's toolset, and Claude Code has surfaced misleading Agent-tool footers for a continuation tool that is not callable there. So a sub-agent never messages or continues a peer. It **returns its result** and the orchestrator either uses a host-exposed continuation tool or re-spawns a fresh sub-agent with a compact handoff packet: issue/PR refs, branch/worktree, changed files, objective, what passed/failed, and exact NEXT. Cross-agent / cross-PC coordination is **`/coop`**, never `SendMessage` or ad-hoc messaging. Keep this narration out of user-facing output — a one-line `saga note` at most.
+
+## Classifier-denied spawn handling
+
+Claude Code **2.1.178**: in auto mode, subagent spawns are evaluated by a classifier before launch. A spawn can return **denied** or **null**.
+
+**Degraded round — not clean:**
+
+- A denied, null, or missing planner/lens/research sub-agent is a **gap**, not a pass.
+- Log the gap: `mmi-cli saga note "spawn-denied role=<planner|lens|research> round=<n>"`.
+- Surface gaps in halt reports, end-of-grind summaries, and build halt reports.
+- A round with any denied/null spawn does **not** count toward **two synthesis-stable clean rounds**.
+- When aggregating parallel results, use explicit null handling — `.filter(Boolean)` alone is insufficient unless paired with a gap count check; a denied spawn must never inflate a clean count.
+- Retry once with a narrower scope (fewer parallel spawns, smaller diff pin) when useful; if still denied, proceed with fewer lenses and document the ceiling.
+
+## Panel economics
+
+Why panel + synthesize beats solo self-review: parallel lenses produce independent JSON; synthesis **reconciles** (dedupes blockers, surfaces contradictions) into a `PanelReport` — **synthesize-and-reconcile**, not majority vote or debate. Cross-vendor pairs beat same-model self-fusion — hence verifier **≠** builder.
+
+**Routine default (no explicit `--ultra`, auto-ultra false):** **2 models** — builder + verifier (synthesizer = verifier).
+
+**Relative verify cost (qualitative):** `Budget` < `Balanced` < `Paranoid` < `Ultra`.
+
+**Variance:** a single clean verify round can miss blockers. Loops require **2 consecutive synthesis-stable clean rounds** (identical blocker `id` sets; empty counts as stable).
+
+**Measure-first / cost ceiling.** Before unsupervised running, print worst-case **agent-call proxy** via `mmi-cli grind estimate` (includes **2 stable-round** minimum; not a dollar promise). On projected exceed → ask human (cap/stuck path); honor `GRIND_COST_CEILING` from `grind-policy.ts`.
+
+**Terminal done hierarchy** (ordered — never skip a lower layer):
+
+1. Repo checks / CI green (objective gate)
+2. Two synthesis-stable clean rounds (quality layer)
+3. Human merge authority (grind Gate 2; `--auto` / build auto-merge into `development` only)
+
+"Two clean rounds" alone is never sufficient without layer 1.
+
+**Single-model host:** lenses may share one model; **still run the synthesizer** — self-fusion uplift remains.
+
+## Verify tiers
+
+Local verify and CI gate serve different jobs — don't clone the full CI matrix on every edit.
+
+**While editing (loop):**
+
+- Scope to the touched package and files (`vitest run <paths>`, `tsc --noEmit` in one package).
+- Apply the same path filters as the repo's `gate.yml` jobs — don't run `infra` for a `cli`-only diff (and vice versa).
+- Grind/build checkpoints: **light verify only** (targeted tests, requirement slice, single lens when stakes are high).
+
+**Before PR / claiming done (final):**
+
+- Run the **full gate mirror once** for every `gate.yml` job your diff would trigger — read each job's `relevant-pattern`.
+- Include artifact-parity checks the gate enforces (e.g. committed `cli/dist/` must match `npm run build`).
+- After the PR's CI is green, **do not** re-run the full local suite unless code changed again — CI is merge authority (layer 1 above).
+
+**Humans:** may push and watch CI instead of a local full mirror when willing to trade slower feedback for less duplicate work; agents still owe the once-before-PR mirror unless the repo defines a lighter contract.
+
+## Blocker tiers
+
+Every blocker is classified before action. **When unsure: treat as hard.** Never guess.
+
+- **Solvable** — clear fix, in scope, within authority. File, `board claim --for <login>`, fix, PR, merge into `development`, continue.
+- **Hard-decision** — needs a call the loop cannot make alone (auth model, schema migration, public API shape, vendor choice, prod-touching change, master-gated ops). File with full context and options; **park** the site/slice; keep the frontier moving.
+- **Genuinely-not-grindable** — privileged master-only ops, pure coordination with no PR deliverable, work outside authority. Surface in halt report; do not fake a PR.
+
+Build encodes classification signals in `build-policy.ts`; grind uses the same vocabulary.
+
+## Worktree + node_modules hygiene
+
+Org-wide session doctrine lives in **`AGENTS.md` § Session workflow** — grind/build own git + memory; `mmi-cli wave status` for visibility. This block covers grind/build-specific hygiene only.
+
+- **Trivial-task escape hatch.** A genuinely tiny, low-risk change — a one-line edit, a typo, a string tweak — does **not** need a worktree or even a feature branch. Spinning a full worktree for a ten-letter one-liner is waste. Edit on a normal branch (or directly where the user is working), verify, PR. Use a worktree once the change has real scope, parallel sites, or `/stage` needs. When unsure whether it's trivial, use a worktree.
+- Branch from latest `origin/development` into `../mmi-worktrees/<branch>` — **never edit the main checkout** during grind/build runs.
+- One worktree per grind/build run until integration boundary; multi-worktree waves merge via `mmi-cli wave land`.
+- Return to the main checkout mid-run only for a new unrelated branch, real base drift, final integrated validation, cleanup after merge, explicit user request, or a broken/unsafe worktree. Otherwise keep implementation, verification, commits, PR prep, saga, and North Star updates in the active worktree.
+- A local `/stage` belongs to the active worktree that started it. Do not disrupt a running stage for git bookkeeping alone. Before moving to a different worktree, stop/destroy the stage and recreate it from the new worktree, or warn first when the user's intent is unclear. Linked worktrees share stage state through the git common dir, so a new worktree can still stop the previous local stage.
+- Give each worktree its **own** `node_modules` via clean `npm ci` — never symlink/junction into the main checkout's `node_modules` (junctions can be followed by teardown and destroy the main checkout).
+- **Cross-platform lockfile — validate on the CI OS, not the build OS (#1840).** When a build/grind on **Windows** regenerates `package-lock.json` (any `npm install` — e.g. adding a workspace or devDep), npm 11 **prunes Linux-only optional deps** (`@emnapi/*`, the `@node-rs/argon2` / `@tailwindcss/oxide` `*-wasm32-wasi` fallbacks). Local `npm ci` + the gate then pass on Windows while the Linux CI runner's `npm ci` dies `EUSAGE` (`Missing: @emnapi/core@… from lock file`) in ~11s — **local-OS green never proves a cross-platform lockfile.** Before merge, regenerate **and** validate the lock in a Linux container matching CI's Node (`node:24` at present): `docker run --rm -v "${PWD}:/app" -w /app node:<ci-node> npm install --package-lock-only --ignore-scripts`, then validate with `node_modules`-shadowed anonymous volumes — `docker run --rm -v "${PWD}:/app" -v /app/node_modules -w /app node:<ci-node> sh -c "npm ci && npm run check"`. The container lock is a win32+linux+wasm **superset** that satisfies Linux CI (local Windows `npm ci` may then reject it on an npm-minor mismatch — CI is the gate).
+- Remove the worktree's `node_modules` **before** ordinary `pr merge`; run `git status` on the main checkout immediately **after** every merge. If `pr land/merge --preserve-worktree` is used for an explicit active batch, leave the worktree/stage in place and do that cleanup at the batch boundary (#1888).
+- **Worktree tests run from the worktree cwd.** A subagent's green run is not reproducible evidence unless `cwd` is that worktree. The orchestrator must independently reproduce subagent green from the same worktree cwd before merge.
+- **Worktree base freshness (#1906):** Before `pr create`, and at long-run Phase 1 checkpoints when the base may have moved: `git -C <wt> fetch origin && git -C <wt> merge-base --is-ancestor origin/<base> HEAD`. If false, rebase onto the updated base, rebuild checked-in artifacts if the diff touches them, re-run repo checks, then push/PR. Cross-repo grinds: each worktree checks independently.
+
+## Delegated verify+commit (#1595)
+
+**Re-test status (2026-06-19, #1705):** Reviewed against Claude Code CHANGELOG **2.1.178** ("backgrounding no longer restarts from scratch") and **2.1.183** (teammate background-task kill fix). **No live Claude Code repro in this session** (Cursor host). Rule **confirmed in force** pending live repro on Claude Code — see #1705.
+
+Until repro proves otherwise:
+
+- When delegating verify-then-commit to a sub-agent on **Claude Code**, run the authoritative merge-gate suite **in the foreground** and **not return** until committed and pushed — or report a concrete failure.
+- Never background the full test suite inside a sub-agent whose turn can end before results arrive; that strand leaves an uncommitted worktree.
+- **(Recommended)** the orchestrator owns the final verify+commit on the worktree rather than delegating both.
+- On surfaces without Claude's background-strand fixes, treat foreground-only as the floor regardless of changelog.
+
+## Saga snapshot / resume
+
+Loop memory composes with saga HEAD — enforced via **`mmi-cli saga snapshot`**.
+
+- **Read-first on resume:** `mmi-cli saga snapshot show --kind <grind|build>` (`--json` for machine use). Reconcile with diff + `PanelReport` — never collapsed chat.
+- **Write-last each phase:** one-line `mmi-cli saga note "<audit>"` **plus** `mmi-cli saga snapshot set --kind <grind|build>` (or `--json-file`).
+- **Hygiene:** bounded summary only; one-line phase notes = append-only trail beneath HEAD.
+
+Grind schema: `skills/grind/templates/saga-snapshot.md`. Build uses `--kind build`.
+
+## Autonomy ladder (shared vocabulary)
+
+| Level | Grind | Build |
+|-------|-------|-------|
+| **L1** suggest only | rare | rare |
+| **L2** draft for human | — | — |
+| **L3** apply + human merges | interactive default (Gate 2) | — |
+| **L4** apply + auto-complete + audit log | `--auto` | auto by default (Phase 0 authorization) |
+
+L4 audit expectation: silent clean-run retro; cap/stuck terminate-and-report.
+
+## Epistemic honesty
+
+Not knowing is fine; **pretending is banned**.
+
+- Never claim cross-vendor fusion when only one vendor was available — name the gap.
+- Never claim "live-verified" when only "built + tested" or "CI green" is true.
+- Never invent sources, paths, line numbers, or API contracts.
+- Every halt/round report states the **verification ceiling** (what was actually checked vs assumed).
+
+**Verification ceiling ladder:**
+
+| Rung | Means | Loop can reach? |
+|------|-------|-----------------|
+| **built** | compiles / typechecks on the worktree | yes |
+| **tested** | repo local tests + lints pass | yes |
+| **CI green** | full gate green on the PR | yes |
+| **merged** | landed into `development` | yes (auto paths) |
+| **live-verified** | real deployed environment | **no** — outside grind/build ceiling |
+
+## No shortcuts
+
+Hold the quality bar. Re-tackle and rebuild rather than patch to green.
+
+- If verification keeps failing on the same root cause, **rebuild the design**, do not stack patches.
+- If a test had to be loosened to pass, that is a blocker.
+- Patch-to-green costs the next orient its evidence and the milestone its quality.
+
+## Self-learning + retro
+
+Both skills file process uplifts via `mmi-cli skill-lesson --skill <grind|build>` — at most **one** lesson per run; lands on Hub board; fixed only via reviewed PR — never edit a skill live.
+
+**Retro** (after PR / halt / cap-stuck): did the **loop itself** misfire? Process failures only — not code bugs the panel caught. Clean run → skip silently.
+
+## Enforcement matrix (harness vs skill)
+
+Some floors are **harness-enforced** on Claude Code; others remain **skill-enforced** on all surfaces.
+
+| Rule | Claude Code harness | Skill text (all surfaces) |
+|------|---------------------|---------------------------|
+| No edit/write real `.env` | `scripts/vault-edit-gate.mjs` PreToolUse on `Edit\|Write` | Vault only — `/secrets` |
+| Destructive git (`add -A`, amend pushed, etc.) | Native blocking since **2.1.183** | Keep one-line pointer; do not duplicate full prose |
+| Worktree-only edits during run | **Deferred** — needs reliable session marker (#1706 residual) | Skill-enforced: edit worktree only |
+| Read/Shell throttle | `throttle-gate.mjs` | Tool-economy rule |
+| Shell dialect mismatch | `shell-redirect-lint.mjs` | AGENTS naming/shell |
+
+Trim skill prose that re-asserts harness-owned git guardrails; point at this matrix instead.
+
+## Cross-surface note
+
+These skills are host-agnostic. Each surface (Claude Code, Codex, Cursor Composer) spawns sub-agents with its own mechanism and model list. Fusion, gates, tier engine, and CLI calls are identical everywhere. All behavior runs through `mmi-cli`; no surface-specific plumbing beyond hook availability noted in the enforcement matrix.