arkgate 3.8.2 → 3.9.0

package/bin/lib/doctor-plan.mjs

@@ -36,6 +36,7 @@ import {
   mergePostGreenTopActions,
   isDoctorHealthyNothingToDo,
 } from './post-green-path.mjs';
+import { doctorWritePathHonestyMessage } from './host-support-matrix.mjs';
 import {
   computePureLayerOptInNudge,
   loadGoldenPattern,
@@ -578,14 +579,20 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   console.log('');
   console.log(color.bold('Operating mode'));
   // Modes are detected states, not user-picked settings. Plain-language "what you do next".
-  const modeMark = mode === 'enforce' ? ok : mode === 'adapt' ? warn : warn;
+  // Never paint green (ok) under design residual — edges clean ≠ design done (product-voice).
+  const modeMark =
+    mode === 'enforce' && !designFitness.designWeak
+      ? ok
+      : warn;
+  // Status lights are detected states, not user-picked settings (see docs/product-voice.md).
+  // modeTitle alone names the light — bodies must not re-prefix Suggest/Adapt/Enforce.
   const modeHelp = {
     suggest:
-      'Setup — Ark proposes a starting architecture shape. You do not pick this mode; it means the tree is thin or new. Next: accept the shape (ark start / ark init) and add real layers as you grow.',
+      'thin or new tree; the contract is not yet the control plane. You do not pick this light. Next: ark start (preview), then ark start --apply; re-check with --doctor.',
     adapt:
-      'Align — contract and folders still disagree, or coverage is weak / debt is open. You do not pick this mode. Next: classify ungoverned dirs (/ark-contract, /ark-adopt), run the plan (/ark-autopilot or /ark-loop). Gates do not fully protect you yet.',
+      'contract and tree still disagree, or debt is open. Write path does not fully protect you yet. You do not pick this light. Next: do doctor top action #1 (often /ark-adopt, /ark-contract, or /ark-autopilot).',
     enforce:
-      'Guard — contract coverage is honest and checked edges are clean. You do not pick this mode; you arrived here. Next: keep the host-appropriate write path and CI check on; only NEW violations should fail.',
+      'honest coverage and clean checked edges. You arrived here; you never turn Enforce on. Next: keep the host write path and CI check; only NEW violations should fail.',
   };
   const modeTitle =
     mode === 'enforce' && designFitness.designWeak
@@ -595,7 +602,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     modeMark,
     `${modeTitle} — ${
       designFitness.designWeak
-        ? 'Guard on edges is honest, but design smells remain (Shape residual). You do not pick this mode. Next: single path — /ark-explore shape-focus → dual-plan B, then /ark-autopilot only to apply B with your OK. Never empty plan A = done.'
+        ? 'checked edges are honest; design smells remain. Green is not elegant design. You do not pick this light. Next: one Shape door — /ark-explore shape-focus → dual-plan B; apply B only with /ark-autopilot and your OK. Empty plan A is not done.'
         : modeHelp[mode]
     }`
   );
@@ -692,34 +699,25 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   if (showNewHere) {
     console.log('');
     console.log(color.bold('New here?'));
+    // Suggest residual: start → doctor only (not a competing recommend/architect curriculum).
+    line(ok, `Primary path: ${arkCommand(root, 'ark', 'start')} (preview) → ${arkCommand(root, 'ark', 'start --apply')} → re-run --doctor`);
     if (recommendation) {
-      line(warn, `Suggested application shape: ${recommendation.archetype} — ${recommendation.label} (preset ${recommendation.preset})`);
-      if (recommendation.galleryStarter) {
-        line(ok, `Gallery starter: ${recommendation.galleryStarter}`);
-      }
+      line(warn, `Sensor shape hint (not a second curriculum): ${recommendation.archetype} — ${recommendation.label} (preset ${recommendation.preset})`);
+      if (recommendation.galleryStarter) line(ok, `Gallery starter (optional): ${recommendation.galleryStarter}`);
       if (recommendation.policyPack) {
-        line(ok, `Policy pack: ${arkCommand(root, 'ark-check', `--apply-policy-pack ${recommendation.policyPack}`)}`);
+        line(ok, `Policy pack (optional expert): ${arkCommand(root, 'ark-check', `--apply-policy-pack ${recommendation.policyPack}`)}`);
       }
       if (recommendation.signals?.nestFramework) {
-        line(
-          ok,
-          'Nest modular monolith → prefer hexagonal (or ddd-bounded-contexts if you have src/contexts/*)'
-        );
+        line(ok, 'Nest modular monolith → prefer hexagonal (or ddd-bounded-contexts if you have src/contexts/*)');
       }
       if (recommendation.signals?.monorepoTooling?.length) {
-        line(
-          ok,
-          `Monorepo tooling (${recommendation.signals.monorepoTooling.join(', ')}) → preset monorepo (apps/packages/libs)`
-        );
+        line(ok, `Monorepo tooling (${recommendation.signals.monorepoTooling.join(', ')}) → preset monorepo (apps/packages/libs)`);
       }
     } else {
-      line(warn, 'Low governed coverage or fresh config — pick an application shape before adding code.');
-    }
-    line(ok, `See the plan: ${arkCommand(root, 'ark-check', '--recommend')}`);
-    if (recommendation?.archetype) {
-      line(ok, `Quick setup: ${arkCommand(root, 'ark', `init --archetype ${recommendation.archetype} --yes`)}`);
+      line(warn, 'Low governed coverage or fresh config — finish start, then re-run doctor before adding layers of code.');
     }
-    actions.unshift('run ark-check --recommend or /ark-architect to choose your application shape');
+    line(ok, `Optional sensor detail: ${arkCommand(root, 'ark-check', '--recommend')}`);
+    actions.unshift('finish ark start (preview + --apply), then re-run --doctor');
   }
 
   console.log('');
@@ -731,8 +729,10 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
         warn,
         'No active violations — coverage is still thin, so green is not yet honest enforcement'
       );
+    } else if (designFitness.designWeak) {
+      line(warn, 'None on checked edges — edges match the contract; design residual remains (ENFORCE · design-weak). Not healthy finished.');
     } else {
-      line(ok, 'None — the code matches the contract');
+      line(ok, 'None — the code matches the contract on checked edges');
     }
   } else {
     const typeNote = summary.typeOnlyCount > 0 ? ` (${summary.valueCount} value · ${summary.typeOnlyCount} type-only)` : '';
@@ -770,6 +770,8 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   line(' ', `Active host: ${writePath.activeHost}`);
   line(' ', `Supported profile: ${writePath.supportSummary}`);
   line(wpMark, `Mode: ${writePath.mode} — ${writePathLabels[writePath.mode] || writePath.mode}`);
+  const honestyLine = doctorWritePathHonestyMessage(writePath.activeHost, capabilities['hard-write']);
+  if (honestyLine) line(warn, honestyLine);
   if (writePath.sessionNote) {
     line(warn, writePath.sessionNote);
   }
@@ -932,18 +934,25 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   const uniqueActions = mergePostGreenTopActions(actions, postGreenPath);
   if (isDoctorHealthyNothingToDo(designFitness, uniqueActions)) {
     console.log(color.green('✔ Healthy — nothing to do.'));
+    console.log(color.dim('  Contract edges and design residual are clear. Keep write path + CI.'));
   } else {
     if (designFitness.designWeak && uniqueActions.length === 0 && postGreenPath) {
       uniqueActions.push(postGreenPath.action);
     }
-    console.log(color.bold(`Top actions (${uniqueActions.length}):`));
-    uniqueActions.forEach((action, index) => console.log(`  ${index + 1}. ${action}`));
+    console.log(color.bold(`Primary next action`));
+    console.log(`  1. ${uniqueActions[0]}`);
+    if (uniqueActions.length > 1) {
+      console.log(color.bold(`Also (${uniqueActions.length - 1}):`));
+      uniqueActions.slice(1).forEach((action, index) => console.log(`  ${index + 2}. ${action}`));
+    }
     if (postGreenPath) {
       console.log(
         color.dim(
-          '  (post-green path is primary when ENFORCE · design-weak — do not skill-shop explore vs coverage vs think)'
+          '  Shape residual is the primary door under ENFORCE · design-weak — do not skill-shop explore vs coverage vs think.'
         )
       );
+    } else {
+      console.log(color.dim('  Doctor is the control plane: do #1 first, then re-run --doctor.'));
     }
   }
 }

package/bin/lib/hook-templates.mjs

@@ -1,15 +1,19 @@
 // Generated from hook-templates.source.mjs — run npm run generate:packaged-tooling.
-import{execCommandParts as i,execRunner as a}from"../ark-shared.mjs";const r="arkgate-mcp";function g(e){const o=a(e);return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",command:`${o} ${r} --session-context --root "$CLAUDE_PROJECT_DIR" --config ark.config.json`}]}],PreToolUse:[{matcher:"Write|Edit|MultiEdit",hooks:[{type:"command",command:`${o} ${r} --hook --hook-repair --fail-on-new-smells --root "$CLAUDE_PROJECT_DIR" --config ark.config.json`}]}]}},null,2)}
-`}function l(e){const o=a(e),n="${CODEX_PROJECT_DIR:-${PWD:-.}}";return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",timeout:30,command:`${o} ${r} --session-context --root "${n}" --config ark.config.json`}]}],PreToolUse:[{matcher:"ApplyPatch|apply_patch|Write|Edit|MultiEdit",hooks:[{type:"command",timeout:30,command:`${o} ${r} --hook --hook-repair --fail-on-new-smells --root "${n}" --config ark.config.json`}]}]}},null,2)}
-`}function p(e){const{command:o,args:n}=i(e,r,["--root",".","--config","ark.config.json"]),t=c=>c.replace(/\\/g,"\\\\").replace(/"/g,'\\"'),s=n.map(c=>`"${t(c)}"`).join(", ");return`# Generated by ark-check --install-agent-gates (Codex project scope).
+import{execCommandParts as i,execRunner as s}from"../ark-shared.mjs";const c="arkgate-mcp";function l(e){const r=s(e);return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",command:`${r} ${c} --session-context --root "$CLAUDE_PROJECT_DIR" --config ark.config.json`}]}],PreToolUse:[{matcher:"Write|Edit|MultiEdit",hooks:[{type:"command",command:`${r} ${c} --hook --hook-repair --fail-on-new-smells --root "$CLAUDE_PROJECT_DIR" --config ark.config.json`}]}]}},null,2)}
+`}function p(e){const r=s(e),o="${CODEX_PROJECT_DIR:-${PWD:-.}}";return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",timeout:30,command:`${r} ${c} --session-context --root "${o}" --config ark.config.json`}]}],PreToolUse:[{matcher:"ApplyPatch|apply_patch|Write|Edit|MultiEdit",hooks:[{type:"command",timeout:30,command:`${r} ${c} --hook --hook-repair --fail-on-new-smells --root "${o}" --config ark.config.json`}]}]}},null,2)}
+`}function g(e){const{command:r,args:o}=i(e,c,["--root",".","--config","ark.config.json"]),t=a=>a.replace(/\\/g,"\\\\").replace(/"/g,'\\"'),n=o.map(a=>`"${t(a)}"`).join(", ");return`# Generated by ark-check --install-agent-gates (Codex project scope).
 # Restart Codex after changes; MCP servers are loaded when the project session starts.
 [mcp_servers.ark]
-command = "${t(o)}"
-args = [${s}]
-`}function k(e){const{command:o,args:n}=i(e,r,["--root",".","--config","ark.config.json"]),t=n.map(s=>`"${s.replace(/\\/g,"\\\\").replace(/"/g,'\\"')}"`).join(", ");return`# Generated by ark-check --install-agent-gates (Grok Build project scope).
+command = "${t(r)}"
+args = [${n}]
+`}function f(e){const{command:r,args:o}=i(e,c,["--root",".","--config","ark.config.json"]),t=o.map(n=>`"${n.replace(/\\/g,"\\\\").replace(/"/g,'\\"')}"`).join(", ");return`# Generated by ark-check --install-agent-gates (Grok Build project scope).
 # Restart Grok (or /mcps \u2192 refresh) after changes. Also loads repo-root .mcp.json.
 [mcp_servers.ark]
-command = "${o.replace(/\\/g,"\\\\").replace(/"/g,'\\"')}"
+command = "${r.replace(/\\/g,"\\\\").replace(/"/g,'\\"')}"
 args = [${t}]
-`}function d(e){const o=a(e),n="${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}";return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",timeout:30,command:`${o} ${r} --session-context --root "${n}" --config ark.config.json`}]}],PreToolUse:[{matcher:"Write|Edit|MultiEdit|write|search_replace",hooks:[{type:"command",timeout:30,command:`${o} ${r} --hook --hook-repair --fail-on-new-smells --root "${n}" --config ark.config.json`}]}]}},null,2)}
-`}export{r as PREFERRED_MCP_BIN,g as claudeSettings,l as codexHooks,p as codexProjectConfig,d as grokHooks,k as grokProjectConfig};
+`}function u(e){const r=s(e),o="${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}";return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",timeout:30,command:`${r} ${c} --session-context --root "${o}" --config ark.config.json`}]}],PreToolUse:[{matcher:"Write|Edit|MultiEdit|write|search_replace",hooks:[{type:"command",timeout:30,command:`${r} ${c} --hook --hook-repair --fail-on-new-smells --root "${o}" --config ark.config.json`}]}]}},null,2)}
+`}function k(e){const r=s(e);return`${JSON.stringify({"ark-write-gate":{PreToolUse:[{matcher:"write_to_file|replace_file_content|multi_replace_file_content",hooks:[{type:"command",timeout:30,command:`${r} ${c} --hook --hook-repair --fail-on-new-smells --root "\${PWD:-.}" --config ark.config.json`}]}]}},null,2)}
+`}function d(e){const{command:r,args:o}=i(e,c,["--root",".","--config","ark.config.json"]);return`${JSON.stringify({$schema:"https://opencode.ai/config.json",mcp:{ark:{type:"local",command:[r,...o],enabled:!0}}},null,2)}
+`}function $(e,r){let o,t;try{o=e&&e.trim()?JSON.parse(e):{},t=JSON.parse(r)}catch{return null}if(!o||typeof o!="object"||Array.isArray(o)||!t||typeof t!="object"||Array.isArray(t))return null;const n=t["ark-write-gate"];if(!n||typeof n!="object")return null;const a={...o,"ark-write-gate":n};return`${JSON.stringify(a,null,2)}
+`}function h(e,r){let o,t;try{o=e&&e.trim()?JSON.parse(e):{},t=JSON.parse(r)}catch{return null}if(!o||typeof o!="object"||Array.isArray(o))return null;const n={...o};!n.$schema&&t.$schema&&(n.$schema=t.$schema);const a=o.mcp&&typeof o.mcp=="object"&&!Array.isArray(o.mcp)?{...o.mcp}:{};return a.ark=t.mcp.ark,n.mcp=a,`${JSON.stringify(n,null,2)}
+`}export{c as PREFERRED_MCP_BIN,k as antigravityHooks,l as claudeSettings,p as codexHooks,g as codexProjectConfig,u as grokHooks,f as grokProjectConfig,$ as mergeAntigravityArkHook,h as mergeOpencodeArkMcp,d as opencodeProjectConfig};

package/bin/lib/host-support-matrix.mjs

@@ -38,6 +38,16 @@ export const HOST_SUPPORT_MATRIX = Object.freeze({
     true,
     true
   ),
+  // Google Antigravity: official PreToolUse deny is a hard block. Claim hard only when
+  // installed + trusted and the listed write tools are covered by the adapter.
+  antigravity: hostProfile(
+    'Google Antigravity',
+    '.agents/hooks.json',
+    'PreToolUse `write_to_file` / `replace_file_content` / `multi_replace_file_content`',
+    ['write_to_file', 'replace_file_content', 'multi_replace_file_content'],
+    true,
+    true
+  ),
   cursor: hostProfile('Cursor', null, null, [], false, false),
   codex: hostProfile(
     'OpenAI Codex',
@@ -47,6 +57,16 @@ export const HOST_SUPPORT_MATRIX = Object.freeze({
     false,
     false
   ),
+  // OpenCode: first-class MCP + permissions; plugin tool.execute.before is incomplete
+  // (subagent holes). Never claim hard write.
+  opencode: hostProfile(
+    'OpenCode',
+    null,
+    'Advisory MCP + optional experimental plugin (`tool.execute.before`); not a hard boundary',
+    [],
+    false,
+    false
+  ),
 });
 
 export const HOST_SUPPORT_HOSTS = Object.freeze(Object.keys(HOST_SUPPORT_MATRIX));
@@ -70,18 +90,58 @@ export function renderHostSupportMatrixMarkdown() {
   const rows = HOST_SUPPORT_HOSTS.map((host) => {
     const profile = HOST_SUPPORT_MATRIX[host];
     const capabilities = profile.capabilities;
-    const local = capabilities['hard-write']
-      ? `Hard block for ${profile.hookSurface}`
-      : 'No hard hook; MCP/rules are advisory';
+    // Fail-closed honesty: Cursor/Codex/OpenCode never claim hard write; CI is required-status.
+    // hookSurface already includes "PreToolUse …" — do not prefix PreToolUse again.
+    let local;
+    if (capabilities['hard-write']) {
+      local = `**Hard** block for listed ops (${profile.hookSurface}) when installed + trusted`;
+    } else if (host === 'codex') {
+      local =
+        '**Advisory / best-effort** at write (not equivalent to Claude/Grok hard block)';
+    } else if (host === 'opencode') {
+      local =
+        '**Advisory / best-effort** at write (MCP + optional plugin; not a hard boundary)';
+    } else {
+      local = '**Advisory only** at write (no hard hook)';
+    }
     const repair = capabilities['repair-payload']
       ? 'Emitted on hook deny; host must re-inject'
       : 'No hard-boundary payload';
-    return `| ${profile.label} | ${local} | Advisory; the agent must call it | Available \`arkgate-check --strict-merge\` check | ${repair} |`;
+    const merge = capabilities['hard-write']
+      ? '**Required status** = hard merge boundary (`arkgate-check --strict-merge`)'
+      : '**Required status** = hard merge boundary (same CI)';
+    return `| ${profile.label} | ${local} | Advisory; the agent must call it | ${merge} | ${repair} |`;
   }).join('\n');
 
   return `| Host | Local write boundary | MCP validation | CI / merge path | Repair payload |
 |------|----------------------|----------------|-----------------|----------------|
 ${rows}
 
+**Read the CI column:** for every host, the repository-wide hard guarantee is a **required**
+merge check — not “CI file present.” Cursor/Codex/OpenCode never get a fake hard write claim.
+
 This table describes the supported profile **after its files are installed and the host loads/trusts them**. A hard local boundary covers only the listed hook operations; alternate tools, direct filesystem writes, and human edits still rely on CI. MCP validation is advisory because the agent must call it. The CI check blocks a merge only when the repository makes that status required. Repair payloads never write code silently: the host must re-inject the candidate and ArkGate revalidates it. Run \`arkgate-check --doctor\` for the evidence actually detected in the current repository.`;
 }
+
+/**
+ * Doctor human one-liner for active-host write honesty (fail-closed).
+ * @returns {string|null}
+ */
+export function doctorWritePathHonestyMessage(activeHost, hardWriteActive) {
+  const host = typeof activeHost === 'string' ? activeHost.trim().toLowerCase() : '';
+  if (host === 'cursor') {
+    return 'Cursor: write path is advisory (MCP/rules; no hard PreToolUse). Required CI status (arkgate-check --strict-merge) is the hard merge boundary.';
+  }
+  if (host === 'codex') {
+    return 'Codex: write path is advisory / best-effort at write (not Claude/Grok hard). Required CI status (arkgate-check --strict-merge) is the hard merge boundary.';
+  }
+  if (host === 'opencode') {
+    return 'OpenCode: write path is advisory / best-effort (MCP + optional plugin; not Claude/Grok/Antigravity hard). Required CI status (arkgate-check --strict-merge) is the hard merge boundary.';
+  }
+  if ((host === 'claude' || host === 'grok' || host === 'antigravity') && !hardWriteActive) {
+    const label =
+      host === 'claude' ? 'Claude' : host === 'grok' ? 'Grok' : 'Antigravity';
+    return `${label}: hard PreToolUse is supported for listed ops when installed + trusted; without runtime-observed hook evidence, hard is unverified. Required CI remains the merge hard boundary.`;
+  }
+  return null;
+}

package/bin/lib/install-migrate.mjs

@@ -21,11 +21,15 @@ import {
 } from './codex-home.mjs';
 import {
   PREFERRED_MCP_BIN,
+  antigravityHooks,
   claudeSettings,
   codexHooks,
   codexProjectConfig,
   grokHooks,
   grokProjectConfig,
+  mergeAntigravityArkHook,
+  mergeOpencodeArkMcp,
+  opencodeProjectConfig,
 } from './hook-templates.mjs';
 import {
   hasCheckArchitectureScript,
@@ -60,6 +64,7 @@ import {
 import { detectDeployPathQuality } from './deploy-path.mjs';
 import {
   stripMcpServerArgs,
+  stripOpencodeMcpCommand,
   COMMAND_GATE_TEXT_FILES,
   COMMAND_GATE_JSON_FILES,
   PREFERRED_CHECK_BIN,
@@ -149,7 +154,10 @@ export function buildManagedAssetCatalog({ root, tools, compact = false, skillsO
       'AGENTS.md',
       compact ? compactAgentInstructions(root, compactHost) : agentInstructions(root)
     );
-    if (!compact || !compactHost || compactHost === 'claude') add('.mcp.json', mcpJson(root));
+    // Always write project MCP registration — compact hosts other than Claude still need
+    // ark://manifest for agents (field: compact grok start left doctor reporting Missing .mcp.json
+    // when AGENTS lost compact markers or hosts were mixed).
+    add('.mcp.json', mcpJson(root));
     const deploy = detectDeployPathQuality(root);
     add(
       '.github/workflows/ark-check.yml',
@@ -172,6 +180,14 @@ export function buildManagedAssetCatalog({ root, tools, compact = false, skillsO
       add('.grok/config.toml', grokProjectConfig(root));
       add('.grok/hooks/ark-write-gate.json', grokHooks(root));
     }
+    if (selectedTools.has('antigravity')) {
+      add('.agents/hooks.json', antigravityHooks(root));
+      // Still useful for Gemini CLI / legacy Gemini consumers sharing the tree.
+      add('GEMINI.md', instructionRule(root));
+    }
+    if (selectedTools.has('opencode')) {
+      add('opencode.json', opencodeProjectConfig(root), 'gate', 'json-merge');
+    }
     if (selectedTools.has('windsurf')) add('.windsurf/rules/ark.md', instructionRule(root));
     if (selectedTools.has('cline')) add('.clinerules/ark.md', instructionRule(root));
     if (selectedTools.has('copilot')) {
@@ -235,6 +251,27 @@ export function runMigrateCommands(root) {
     } catch {
       continue;
     }
+    // OpenCode: mcp.ark.command is a single argv array (type: local), not mcpServers.ark.args.
+    if (rel === 'opencode.json') {
+      const ark = json?.mcp?.ark;
+      if (!ark || typeof ark !== 'object' || !Array.isArray(ark.command)) continue;
+      const argv = ark.command.filter((entry) => typeof entry === 'string');
+      if (argv.length === 0) continue;
+      // Drop runners + any ark* bin names; keep only server flags (e.g. --root .).
+      const binArgs = stripOpencodeMcpCommand(argv);
+      const parts = execCommandParts(root, PREFERRED_MCP_BIN, binArgs);
+      const preferredArgv = [parts.command, ...parts.args];
+      if (JSON.stringify(argv) === JSON.stringify(preferredArgv)) continue;
+      json.mcp.ark = {
+        ...ark,
+        type: ark.type ?? 'local',
+        command: preferredArgv,
+        enabled: ark.enabled !== false,
+      };
+      fs.writeFileSync(full, `${JSON.stringify(json, null, 2)}\n`);
+      changed.push(rel);
+      continue;
+    }
     const ark = json?.mcpServers?.ark;
     if (!ark) continue;
     const binArgs = stripMcpServerArgs(ark.args);
@@ -313,6 +350,14 @@ export function runInstallAgentGates(args) {
           ? 'no active host detected'
         : 'default set — no agent config dirs found';
   console.log(`Agent gates for: ${[...tools].sort().join(', ')} (${toolSource})`);
+  // Progressive disclosure (3.9.0): compact = router; skills-only = expert pack.
+  if (!args.json) {
+    const host = [...tools][0];
+    const later = host ? ` --tools ${host}` : '';
+    if (args.compact) console.log(`Profile: compact router. Expert skills later: ${arkCommand(root, 'ark-check', `--install-agent-gates --skills-only${later} --force`)}`);
+    else if (args.skillsOnly) console.log('Profile: expert skill pack only (refreshes /ark-*; leaves customized gates).');
+    else console.log('Profile: full agent gates. Compact-only onboarding: ark start.');
+  }
   // --skills-only refreshes just the canonical /ark-* skills, which are safe to
   // overwrite (they track the package). The gate/instruction files (AGENTS.md,
   // settings.json, CI workflow, rules) are the ones users customize, so a plain
@@ -364,6 +409,43 @@ export function runInstallAgentGates(args) {
       if (merged === existing) return { relativePath, status: 'skipped' };
       return writeTemplate(root, relativePath, merged, true);
     }
+    if (relativePath === 'opencode.json') {
+      const fullPath = path.join(root, relativePath);
+      let existing = '';
+      try {
+        existing = fs.readFileSync(fullPath, 'utf8');
+      } catch {
+        // Missing project config → write the generated Ark MCP block.
+      }
+      if (!existing) {
+        return writeTemplate(root, relativePath, content, true);
+      }
+      const merged = mergeOpencodeArkMcp(existing, content);
+      if (merged == null) {
+        return { relativePath, status: 'skipped-non-ark' };
+      }
+      if (merged === existing) return { relativePath, status: 'skipped' };
+      return writeTemplate(root, relativePath, merged, true);
+    }
+    if (relativePath === '.agents/hooks.json') {
+      const fullPath = path.join(root, relativePath);
+      let existing = '';
+      try {
+        existing = fs.readFileSync(fullPath, 'utf8');
+      } catch {
+        // Missing hooks file → write generated ark-write-gate map.
+      }
+      if (!existing) {
+        return writeTemplate(root, relativePath, content, true);
+      }
+      const merged = mergeAntigravityArkHook(existing, content);
+      if (merged == null) {
+        return { relativePath, status: 'skipped-non-ark' };
+      }
+      if (merged === existing) return { relativePath, status: 'skipped' };
+      // Upsert ark-write-gate without requiring --force; never wipe sibling named hooks.
+      return writeTemplate(root, relativePath, merged, true);
+    }
     return writeTemplate(
       root,
       relativePath,
@@ -513,6 +595,19 @@ export function runInstallAgentGates(args) {
     console.log('  3. Add the package.json alias if you want `run check:architecture`:');
     console.log(`     ${checkArchitectureScriptSnippet(root)}`);
   }
+  if (tools.has('antigravity') && !args.compact) {
+    console.log('');
+    console.log('  Antigravity: PreToolUse deny is hard for listed write tools when hooks are trusted.');
+    console.log('    - Install path: `.agents/hooks.json` (+ GEMINI.md for legacy Gemini consumers).');
+    console.log('    - Trust project hooks in the host; pair with required CI --strict-merge.');
+  }
+  if (tools.has('opencode') && !args.compact) {
+    console.log('');
+    console.log('  OpenCode write path (honest):');
+    console.log('    - Local: advisory MCP in opencode.json (optional experimental plugin only).');
+    console.log('    - Hard merge backstop: CI --strict-merge + required status check.');
+    console.log('    - Not equivalent to Claude/Grok/Antigravity PreToolUse hard-write.');
+  }
   if ((tools.has('codex') || args.codexHome)) {
     console.log('');
     if (codexMcp && codexMcp.status !== 'failed') {

package/bin/lib/managed-upgrade.mjs

@@ -110,6 +110,8 @@ const HOST_SIGNALS = {
   cursor: ['.cursor/mcp.json', '.cursor/rules/ark.mdc', '.cursor/commands/ark-upgrade.md'],
   codex: ['.codex/hooks.json', '.codex/config.toml', '.agents/skills/ark-upgrade/SKILL.md'],
   grok: ['.grok/config.toml', '.grok/hooks/ark-write-gate.json', '.grok/skills/ark-upgrade/SKILL.md'],
+  antigravity: ['.agents/hooks.json', '.agents/skills/ark-upgrade/SKILL.md'],
+  opencode: ['opencode.json', '.opencode/skills/ark-upgrade/SKILL.md'],
   windsurf: ['.windsurf/rules/ark.md', '.windsurf/workflows/ark-upgrade.md'],
   cline: ['.clinerules/ark.md', '.clinerules/workflows/ark-upgrade.md'],
   copilot: ['.github/copilot-instructions.md', '.github/prompts/ark-upgrade.prompt.md'],
@@ -513,7 +515,20 @@ export function applyManagedUpgrade(root, plan, expectedPlanDigest) {
   const resolvedRoot = path.resolve(root);
   if (resolvedRoot !== plan.root) throw new Error('managed upgrade plan root mismatch');
   if (plan.summary.blocked > 0) return publicPlan(plan, { blocked: true });
+  const wouldWrite = plan.summary.wouldWrite ?? 0;
+  const metadataRefresh = plan.summary.metadataRefresh ?? 0;
+  // Content already matches: unbound --apply is a no-op (exit success), not a digest error.
+  // Optional stamp-only refresh still requires the preview's exact --plan-digest.
   if (!expectedPlanDigest || expectedPlanDigest !== plan.planDigest) {
+    if (wouldWrite === 0 && (plan.summary.blocked ?? 0) === 0 && !expectedPlanDigest) {
+      return publicPlan(plan, {
+        readOnly: true,
+        applied: false,
+        blocked: false,
+        nothingToApply: true,
+        optionalStampRefresh: metadataRefresh,
+      });
+    }
     throw new Error('managed upgrade plan digest mismatch; run a new preview and use its exact nextCommand');
   }
 
@@ -637,7 +652,21 @@ export function renderManagedUpgrade(plan, options = {}) {
       '.'
   );
   if (plan.applied) {
-    console.log(`Applied changes: ${summary.changed}.`);
+    // Distinguish content writes from optional stamp/metadata bookkeeping.
+    if (wouldWrite === 0 && metadataRefresh > 0) {
+      console.log(
+        `Refreshed ${metadataRefresh} version stamp(s)` +
+          (summary.manifestChanged ? ' and managed manifest' : '') +
+          ' (no content body changes).'
+      );
+    } else {
+      console.log(
+        `Applied ${wouldWrite} content write(s)` +
+          (metadataRefresh > 0 ? `, ${metadataRefresh} stamp refresh(es)` : '') +
+          (summary.manifestChanged ? ', managed manifest' : '') +
+          '.'
+      );
+    }
     return;
   }
   // Content already matches package templates — do not urge --apply as the primary next step.

package/bin/lib/mcp-adoption.mjs

@@ -25,8 +25,9 @@ export const COMMAND_GATE_TEXT_FILES = [
   '.clinerules/ark.md', '.github/copilot-instructions.md', '.kiro/steering/ark.md',
   '.roo/rules/ark.md', '.continue/rules/ark.md', 'GEMINI.md', 'package.json',
   '.grok/hooks/ark-write-gate.json', '.grok/config.toml', '.codex/config.toml',
+  '.agents/hooks.json',
 ];
-export const COMMAND_GATE_JSON_FILES = ['.mcp.json', '.cursor/mcp.json'];
+export const COMMAND_GATE_JSON_FILES = ['.mcp.json', '.cursor/mcp.json', 'opencode.json'];
 // Primary CLI names (product) + one-major aliases. migrate-commands must strip ALL of these
 // before re-emitting a single preferred bin — otherwise a partial rename leaves
 // args: ["ark-mcp", "arkgate-mcp", ...] which breaks stdio MCP hosts.
@@ -61,6 +62,34 @@ export function stripMcpServerArgs(args) {
   return kept.length > 0 ? kept : ['--root', '.', '--config', 'ark.config.json'];
 }
 
+/**
+ * OpenCode `mcp.ark.command` is a full argv (runner + bin + flags).
+ * Strip runners and any ark* bin names so migrate can re-emit preferred command+args.
+ */
+export function stripOpencodeMcpCommand(command) {
+  if (!Array.isArray(command) || command.length === 0) {
+    return ['--root', '.', '--config', 'ark.config.json'];
+  }
+  const runners = new Set(['npx', 'yarn', 'pnpm', 'node', 'bun']);
+  const kept = [];
+  for (const entry of command) {
+    if (typeof entry !== 'string') continue;
+    const base = path.basename(entry.replace(/\\/g, '/'));
+    if (
+      runners.has(base) ||
+      MCP_RUNNER_ARGV.has(entry) ||
+      ARK_MCP_BINS.has(base) ||
+      ARK_MCP_BINS.has(entry) ||
+      ARK_CHECK_BINS.has(base) ||
+      ARK_CLI_BINS.has(base)
+    ) {
+      continue;
+    }
+    kept.push(entry);
+  }
+  return kept.length > 0 ? kept : ['--root', '.', '--config', 'ark.config.json'];
+}
+
 /** True when mcpServers.ark.args list more than one Ark MCP bin (broken dual rename). */
 export function mcpArgsHaveDuplicateBins(args) {
   if (!Array.isArray(args)) return false;
@@ -77,6 +106,12 @@ export function brokenMcpGateFiles(root) {
     } catch {
       continue;
     }
+    // OpenCode uses mcp.ark.command[] (single argv); Claude/Cursor use mcpServers.ark.args.
+    if (rel === 'opencode.json') {
+      const command = json?.mcp?.ark?.command;
+      if (Array.isArray(command) && mcpArgsHaveDuplicateBins(command)) bad.push(rel);
+      continue;
+    }
     const ark = json?.mcpServers?.ark;
     if (ark && mcpArgsHaveDuplicateBins(ark.args)) bad.push(rel);
   }
@@ -159,9 +194,32 @@ export function collectAdoptionGaps(root, config, coverage) {
         ],
         toolsFlag: 'codex',
       },
+      {
+        host: 'antigravity',
+        dir: '.agents',
+        skill: (n) => path.join(root, '.agents', 'skills', n, 'SKILL.md'),
+        extras: [['.agents/hooks.json', 'write-gate hook']],
+        toolsFlag: 'antigravity',
+        // Only when hooks.json is present — `.agents/skills` alone is Codex scope.
+        presentIf: () => fs.existsSync(path.join(root, '.agents', 'hooks.json')),
+      },
+      {
+        host: 'opencode',
+        dir: '.opencode',
+        skill: (n) => path.join(root, '.opencode', 'skills', n, 'SKILL.md'),
+        extras: [['opencode.json', 'project MCP config']],
+        toolsFlag: 'opencode',
+        presentIf: () =>
+          fs.existsSync(path.join(root, 'opencode.json')) ||
+          fs.existsSync(path.join(root, '.opencode')),
+      },
     ];
     for (const h of hostChecks) {
-      if (!fs.existsSync(path.join(root, h.dir))) continue;
+      const present =
+        typeof h.presentIf === 'function'
+          ? h.presentIf()
+          : fs.existsSync(path.join(root, h.dir));
+      if (!present) continue;
       const missingSkills = skillNames.filter((n) => !fs.existsSync(h.skill(n)));
       const missingExtras = h.extras.filter(([rel]) => !fs.existsSync(path.join(root, rel)));
       const complete = missingSkills.length === 0 && missingExtras.length === 0;

package/bin/lib/post-green-path.mjs

@@ -17,11 +17,11 @@ export const POST_GREEN_PRIMARY_SKILL = '/ark-explore';
  * Chained: explore shape-focus then autopilot only to apply B with user OK.
  */
 export const POST_GREEN_PRIMARY_ACTION =
-  'Clarify for AI (Shape): /ark-explore shape-focus → dual-plan B, then /ark-autopilot only to apply B with your OK — never empty plan A = done; patternBets never mechanical-safe';
+  'Shape residual (design-weak): edges are clean, design is not finished. Map with /ark-explore shape-focus → dual-plan B; apply B only via /ark-autopilot with your OK. Empty plan A is not done; pattern bets are never mechanical-safe.';
 
 /** Short label for tables / metrics. */
 export const POST_GREEN_PRIMARY_SHORT =
-  '/ark-explore shape-focus → /ark-autopilot (apply B with OK)  # clarify for AI';
+  '/ark-explore shape-focus → /ark-autopilot (apply B with OK)  # Shape residual';
 
 /**
  * @param {{ designWeak?: boolean } | null | undefined} designFitness