arkgate 4.8.17 → 4.8.19

package/bin/lib/skill-install.mjs

@@ -261,8 +261,22 @@ export const SKILL_TOOL_TARGETS = {
   windsurf: (name) => `.windsurf/workflows/${name}.md`,
   cline: (name) => `.clinerules/workflows/${name}.md`,
   copilot: (name) => `.github/prompts/${name}.prompt.md`,
+  // Catalog-only gap: `.agents/skills` exists without a host marker that reads it.
+  agents: (name) => canonicalSkillPath(name),
 };
 
+/** Synthetic detectSkillGaps tool when only the canonical catalog is present. */
+export const SKILL_CANONICAL_TOOL = 'agents';
+
+export function skillGapToolLabel(tool) {
+  return tool === SKILL_CANONICAL_TOOL ? SKILL_CANONICAL_DIR : String(tool ?? '');
+}
+
+export function skillTargetIsCanonical(tool) {
+  const target = SKILL_TOOL_TARGETS[tool];
+  return typeof target === 'function' && target('ark-place') === canonicalSkillPath('ark-place');
+}
+
 /** Hosts whose catalog is the project `.agents/skills` tree (write once). */
 export function usesCanonicalSkillCatalog(tool) {
   return (
@@ -472,8 +486,9 @@ export function skillContentMatchesTemplate(installedContent, templateContent) {
  * Repo catalogs belong to that repo's installed package, so an explicit --force
  * may move them in either direction. Codex home is shared by every repo on the
  * machine: a package older than the installed home stamp must never win, even
- * under --force. In both scopes a version-stamp-only difference is a no-op; the
- * skill body is the capability contract.
+ * under --force. In both scopes a version-stamp-only difference is
+ * `stamp-refresh` (write without --force) so the picker shows this package;
+ * the skill body is the capability contract.
  *
  * @param {{
  *   existingContent?: string|null,
@@ -1086,10 +1101,32 @@ export function detectSkillGaps(root) {
   if (fs.existsSync(path.join(root, '.cursor'))) detected.push('cursor');
   if (fs.existsSync(path.join(root, '.codex'))) detected.push('codex');
   if (fs.existsSync(path.join(root, '.grok'))) detected.push('grok');
+  // Same markers as resolveTools — Antigravity/OpenCode read or link the catalog.
+  if (
+    fs.existsSync(path.join(root, '.agents', 'hooks.json')) ||
+    fs.existsSync(path.join(root, '.agents', 'mcp_config.json'))
+  ) {
+    detected.push('antigravity');
+  }
+  if (
+    fs.existsSync(path.join(root, 'opencode.json')) ||
+    fs.existsSync(path.join(root, 'opencode.jsonc')) ||
+    fs.existsSync(path.join(root, '.opencode'))
+  ) {
+    detected.push('opencode');
+  }
   if (fs.existsSync(path.join(root, '.windsurf'))) detected.push('windsurf');
   if (fs.statSync(path.join(root, '.clinerules'), { throwIfNoEntry: false })?.isDirectory()) {
     detected.push('cline');
   }
+  // One-catalog trees may have `.agents/skills` and no host marker dir.
+  // Without this, a colleague who `npm install`s a new pin keeps stale doors silently.
+  if (
+    fs.existsSync(path.join(root, SKILL_CANONICAL_DIR)) &&
+    !detected.some((tool) => skillTargetIsCanonical(tool))
+  ) {
+    detected.push(SKILL_CANONICAL_TOOL);
+  }
   const version = arkPackageVersion();
   const gaps = [];
   for (const tool of detected) {
@@ -1150,7 +1187,9 @@ export function detectSkillGaps(root) {
 export function skillGapsForActiveHost(skillGaps, env = process.env) {
   const activeHost = detectActiveAgentHost(env);
   if (!activeHost) return skillGaps ?? [];
-  return (skillGaps ?? []).filter((gap) => gap.tool === activeHost);
+  return (skillGaps ?? []).filter(
+    (gap) => gap.tool === activeHost || gap.tool === SKILL_CANONICAL_TOOL
+  );
 }
 
 /**
@@ -1174,7 +1213,7 @@ export function printSkillAndCodexGapHints(root, opts) {
     );
     const missingTotal = remaining.reduce((sum, gap) => sum + gap.missing, 0);
     const staleTotal = remaining.reduce((sum, gap) => sum + gap.stale, 0);
-    const tools = remaining.map((gap) => gap.tool).join(', ');
+    const tools = remaining.map((gap) => skillGapToolLabel(gap.tool)).join(', ');
     if (legacyCodex) {
       console.log(
         color.yellow(
@@ -1200,9 +1239,9 @@ export function printSkillAndCodexGapHints(root, opts) {
     }
     if (staleTotal > 0) {
       console.log(
-        color.dim(
+        color.yellow(
           `${staleTotal} /ark-* skill(s) content behind this Ark package for ${tools}. ` +
-            `Refresh: ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --force')}`
+            `Refresh skills only (do not re-adopt): ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --force')}`
         )
       );
     }

package/bin/lib/start-preview.mjs

@@ -40,8 +40,8 @@ const COMPACT_HOST_TEMPLATES = {
     ['.mcp.json', mcpJson(root)],
   ],
   cursor: (root) => [
-    ['.cursor/mcp.json', mcpJson(root)],
     ['.cursor/hooks.json', cursorHooks(root)],
+    ['.cursor/mcp.json', mcpJson(root)],
   ],
   codex: (root) => [
     ['.codex/hooks.json', codexHooks(root)],
@@ -83,6 +83,17 @@ function digest(content) {
   return `sha256:${crypto.createHash('sha256').update(content ?? Buffer.alloc(0)).digest('hex')}`;
 }
 
+function writeGateOrderGuarantee(tools) {
+  const host = typeof tools === 'string' ? tools.trim().toLowerCase() : '';
+  if (host === 'opencode') {
+    return 'Write gate: MCP prepare only (this host has no hard pre-hook). Required CI is the merge line.';
+  }
+  if (['claude', 'grok', 'antigravity', 'cursor', 'codex'].includes(host)) {
+    return 'Write gate: host pre-hook first; MCP prepare is fallback if that hook is missing or fail-open.';
+  }
+  return 'Write gate: host pre-hook first when the host has one; MCP prepare is fallback. Required CI is the merge line.';
+}
+
 function change(pathname, before, after) {
   return {
     path: pathname,
@@ -122,6 +133,73 @@ export function setupBudget(changes) {
   };
 }
 
+/** One next write when compact start is the wrong size. `--force` does not unlock. */
+export const START_SETUP_BUDGET_NEXT = 'arkgate-check --init';
+
+function formatSetupKb(bytes) {
+  return `${Math.max(1, Math.round(Number(bytes) / 1024))} KB`;
+}
+
+/**
+ * Compact-start size lock. `--force` unlocks coverage/shape only — never this.
+ * @param {object|null|undefined} setupBudget
+ * @param {{ force?: boolean }} [options]
+ */
+export function evaluateStartSetupBudgetGate(setupBudget, { force = false } = {}) {
+  if (!setupBudget || setupBudget.ok) {
+    return { ok: true, forceIgnored: Boolean(force) };
+  }
+  const reasons = [];
+  const maxFiles = setupBudget.maxFiles ?? 8;
+  const maxBytes = setupBudget.maxBytes ?? 32 * 1024;
+  const gateFiles =
+    typeof setupBudget.gateFiles === 'number' ? setupBudget.gateFiles : setupBudget.files;
+  if (typeof gateFiles === 'number' && gateFiles > maxFiles) {
+    reasons.push(`${gateFiles} gate files (max ${maxFiles})`);
+  }
+  if (typeof setupBudget.bytes === 'number' && setupBudget.bytes >= maxBytes) {
+    reasons.push(`${formatSetupKb(setupBudget.bytes)} (max ${formatSetupKb(maxBytes)})`);
+  }
+  if (reasons.length === 0) {
+    reasons.push('the planned write is larger than compact start allows');
+  }
+  return {
+    ok: false,
+    reasons,
+    nextAction: START_SETUP_BUDGET_NEXT,
+    forceBypasses: false,
+    setupBudget,
+  };
+}
+
+/**
+ * Human refuse / preview warning. Avoids the first-run phrase "Compact setup budget".
+ * @param {object|null|undefined} setupBudget
+ * @param {{ applying?: boolean }} [options]
+ */
+export function formatStartSetupBudgetRefuse(setupBudget, { applying = true } = {}) {
+  const gate = evaluateStartSetupBudgetGate(setupBudget);
+  if (gate.ok) return '';
+  const facts = gate.reasons.map((reason) => `  • ${reason}`).join('\n');
+  const next = `--force does not unlock this. Next: ${gate.nextAction}`;
+  if (applying) {
+    return `Refusing ark start --apply: this plan is too big for compact start.\n${facts}\n${next}`;
+  }
+  return `This plan is too big for compact start.\n${facts}\nApply will refuse. ${next}`;
+}
+
+/** Apply-path emit: JSON envelope or human refuse. Call before any “writing…” copy. */
+export function emitStartSetupBudgetRefuse(preview, json) {
+  const gate = evaluateStartSetupBudgetGate(preview.setupBudget);
+  if (json) {
+    console.log(
+      JSON.stringify({ ok: false, error: 'start-setup-budget-gate', ...gate, preview }, null, 2)
+    );
+    return;
+  }
+  console.error(formatStartSetupBudgetRefuse(preview.setupBudget, { applying: true }));
+}
+
 function commands(root, args, helpers) {
   if (args.removeHost) {
     return [`ark start --root ${root} --tools ${args.removeHost} --apply`];
@@ -140,18 +218,57 @@ function commands(root, args, helpers) {
   return result;
 }
 
+/**
+ * Plain one-liner for pnpm minimumReleaseAge / ERR_PNPM_NO_MATURE_MATCHING_VERSION.
+ * Host dumps stay out of the recovery — stranger needs one next step.
+ */
+export function explainPnpmMaturityBlock(hostOutput) {
+  const text = String(hostOutput ?? '');
+  if (!/ERR_PNPM_NO_MATURE_MATCHING_VERSION|minimumReleaseAge/i.test(text)) return null;
+  const days = text.match(/(\d+)\s*days?/i)?.[1];
+  const window = days ? `${days} days` : 'a cooling-off window';
+  return `This repo blocks packages younger than ${window} — pin an older release or exclude arkgate temporarily.`;
+}
+
+/** Pipe the package manager so recovery can hide maturity internals. */
+export function runStartPackageInstall(command, commandArgs, cwd) {
+  const result = spawnSync(command, commandArgs, {
+    cwd,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf8',
+  });
+  return {
+    status: result.status ?? 1,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+  };
+}
+
 /**
  * Red next-step when post-apply package install fails.
  * Host files may already be written; local bins may be missing.
  */
-export function formatStartPackageInstallFailure({ exitStatus, installCommand }) {
+export function formatStartPackageInstallFailure({ exitStatus, installCommand, hostOutput }) {
   const doctor = arkPackageRecoveryCommand('arkgate-check', '--doctor');
-  return [
+  const maturity = explainPnpmMaturityBlock(hostOutput);
+  const lines = [];
+  if (maturity) {
+    lines.push(maturity);
+  } else if (hostOutput && String(hostOutput).trim()) {
+    const tail = String(hostOutput)
+      .split('\n')
+      .map((line) => line.trimEnd())
+      .filter((line) => line.trim())
+      .slice(-6);
+    if (tail.length) lines.push(...tail);
+  }
+  lines.push(
     `Package install failed (exit ${exitStatus}). Setup files are written; the local command is not installed yet.`,
     `  ${installCommand}`,
     `  ${doctor}`,
-    '`arkgate-check` is a command in the arkgate package — not its own npm package.',
-  ].join('\n');
+    '`arkgate-check` is a command in the arkgate package — not its own npm package.'
+  );
+  return lines.join('\n');
 }
 
 /**
@@ -160,6 +277,7 @@ export function formatStartPackageInstallFailure({ exitStatus, installCommand })
  */
 export function renderStartPreview(preview, options = {}) {
   const applying = options.applying === true;
+  const budgetOk = preview.setupBudget?.ok !== false;
   if (applying) {
     console.log(
       preview.changes.length === 0
@@ -170,7 +288,11 @@ export function renderStartPreview(preview, options = {}) {
     console.log('Ark start preview — no files were changed.');
   }
   if (!applying) {
-    console.log('Apply this plan with: arkgate start --apply');
+    if (budgetOk) {
+      console.log('Apply this plan with: arkgate start --apply');
+    } else {
+      console.log(formatStartSetupBudgetRefuse(preview.setupBudget, { applying: false }));
+    }
   }
   if (preview.analysis) {
     console.log(`Your project looks like: ${preview.analysis.label}.`);
@@ -191,6 +313,10 @@ export function renderStartPreview(preview, options = {}) {
   if (preview.runtimeActivation) {
     console.log('Host: Codex is configured but not verified yet. Restart the host, then confirm this project.');
   }
+  const writeGateOrder = (preview.hostGuarantees || []).find((line) =>
+    String(line).startsWith('Write gate:')
+  );
+  if (writeGateOrder) console.log(writeGateOrder);
   if (preview.unresolvedDecisions.length > 0) {
     console.log('Unresolved decisions:');
     for (const decision of preview.unresolvedDecisions) console.log(`  ${decision}`);
@@ -208,8 +334,8 @@ export function renderStartPreview(preview, options = {}) {
 }
 
 export function applyStartPreview(root, preview) {
-  if (!preview.setupBudget?.ok) {
-    throw new Error('Refusing to apply a start plan that exceeds the compact setup budget.');
+  if (!evaluateStartSetupBudgetGate(preview.setupBudget).ok) {
+    throw new Error(formatStartSetupBudgetRefuse(preview.setupBudget, { applying: true }));
   }
   for (const change of preview.changes) {
     const target = path.join(root, change.path);
@@ -431,6 +557,7 @@ export async function planStart(args, helpers) {
       commands: commands(root, args, helpers),
       hostGuarantees: [
         args.requireWriteHook ? `Hard-write hook verified for ${args.requireWriteHook}` : 'shared CI merge gate will be installed',
+        writeGateOrderGuarantee(args.tools),
         'preview phase performs no writes in the target project',
         'apply writes the exact bytes identified by each afterHash',
         ...(codexSelected

package/bin/lib/write-path-detect.mjs

@@ -141,8 +141,9 @@ export function detectWritePathCapabilities(root, explicitHost, attempt) {
           ? 'OpenCode local write is advisory (MCP + optional experimental plugin — not a hard boundary; ' +
             'not equivalent to Claude/Grok/Antigravity PreToolUse hard-write). ' +
             'The hard merge backstop is a required GitHub status context running --strict-merge.'
-          : `Active host ${activeHost} has advisory prepare-write/autoPatch tools, ` +
-            'but no hard write boundary; CI can report failure, while merge blocking requires provider policy.';
+          : `Fell back to MCP prepare: active host ${activeHost} has no hard pre-hook. ` +
+            'Advisory prepare-write/autoPatch is the local write surface. ' +
+            'Next: install and trust the host write hook, or keep required CI as the merge line.';
     gap = {
       id: 'write-path-mcp-only',
       severity: 'info',

package/dist/{diagnosticCatalog-DVABouBV.d.ts → diagnosticCatalog-D2v0ASN2.d.ts}

@@ -392,7 +392,7 @@ declare function createAdapterResult(input: {
 }): CurrentAdapterResult;
 
 /** ArkGate library version — single source of truth. */
-declare const version = "4.8.17";
+declare const version = "4.8.19";
 
 /**
  * AI Code Gate (basic).