arkgate 4.8.18 → 4.8.19

package/bin/lib/doctor-plan.mjs

@@ -13,7 +13,7 @@ import * as arkShared from '../ark-shared.mjs';
 import { summarizeRulesUnderContract } from './rules-under-contract.mjs';
 import { describePackageVersionDualTruth } from './field-install.mjs';
 import { detectAgentHomeGaps } from './agent-homes.mjs';
-import { collectDoctorNextActions } from './doctor-next-actions.mjs';
+import { collectDoctorNextActions, preferredDoctorPrimaryNextAction } from './doctor-next-actions.mjs';
 import { printDoctorCompactHuman, printDoctorDetailsHuman } from './doctor-human.mjs';
 import { collectLayerOwnerResidual, layerGuidanceLine, placementDescriptionFields } from './layer-description.mjs';
 import { collectAdrPresenceResidual, printAdrPresenceHint } from './adr-presence.mjs';
@@ -653,6 +653,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   const statusTransitionCatalog = collectStatusTransitionCatalogResidual({ root, config, files, statesTransitions });
   const noDomainFrontend = collectNoDomainFrontendResidual({ config, coverage: cov, designSmells });
   const { invariantCoverageRoots, invariantTestsPath } = collectInvariantCoverageResiduals({ adopted: isAdopted(adopted) || options.requireGates === true, coverage: config?.coverage, config, root });
+  const selfHost = packageVersionTruth?.selfHost === true || packageVersionTruth?.code === 'PACKAGE_PIN_SELF_HOST';
   const { coverageHonesty, baselineHonesty, writePathHonesty, productHonesty } =
     computeDoctorEnforcementHonesty({
       governedPercent: cov.governed.percent,
@@ -681,13 +682,10 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
         : rulesUnderContract?.active === true || arkRun?.active === true || doctorAdvisories.arkOrder?.active === true
           ? { active: true, extraMergeTeeth: arkRun?.extraMergeTeeth === true || doctorAdvisories.arkOrder?.extraMergeTeeth === true }
           : null,
-      primaryNextAction:
-        adopted === 'not-adopted' ? NOT_ADOPTED_NEXT_ACTION : postGreenPath?.action ?? dualTruthNext,
+      primaryNextAction: preferredDoctorPrimaryNextAction({ adopted, packageInstalled, selfHost, packageVersionTruth, postGreenPath, dualTruthNext }),
       operatingMode,
       packageInstalled,
-      selfHost:
-        packageVersionTruth?.selfHost === true ||
-        packageVersionTruth?.code === 'PACKAGE_PIN_SELF_HOST',
+      selfHost,
       nativeFailClosed: writePath.nativeFailClosed,
       nativeFailClosedPolicy: writePath.nativeFailClosedPolicy,
       adopted,
@@ -752,7 +750,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             adoptionStance: adopted,
             ...(adopted === 'not-adopted'
               ? {
-                  primaryNextAction: NOT_ADOPTED_NEXT_ACTION,
+                  primaryNextAction: productHonesty.primaryNextAction || NOT_ADOPTED_NEXT_ACTION,
                   ...(postGreenPath ? DESIGN_WEAK_HONESTY_FLAGS : {}),
                 }
               : postGreenPath
@@ -908,7 +906,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     coverageHonesty,
     cov,
     packageVersionTruth,
-    dualTruthNext,
+    dualTruthNext, packageInstalled, selfHost,
     activeCount,
     writePath,
     gatesMissing,

package/bin/lib/gate-files.mjs

@@ -152,9 +152,30 @@ export function isCompactRouterAgentsContent(text) {
   return typeof text === 'string' && COMPACT_ROUTER.test(text);
 }
 
+function hasCursorFailClosedHook(root) {
+  try {
+    const parsed = readJson(path.join(root, '.cursor', 'hooks.json'));
+    const entries = Array.isArray(parsed?.hooks?.preToolUse) ? parsed.hooks.preToolUse : [];
+    return entries.some(
+      (entry) =>
+        entry &&
+        typeof entry === 'object' &&
+        entry.failClosed === true &&
+        typeof entry.command === 'string' &&
+        /(?:^|\s)--hook(?:\s|$)/.test(entry.command)
+    );
+  } catch {
+    return false;
+  }
+}
+
+function hasCursorCompactRegistration(root) {
+  return hasArkMcpRegistration(root, '.cursor/mcp.json') && hasCursorFailClosedHook(root);
+}
+
 function hasCompactHostRegistration(root, host) {
   if (host === 'none') return hasArkMcpRegistration(root);
-  if (host === 'cursor') return hasArkMcpRegistration(root, '.cursor/mcp.json');
+  if (host === 'cursor') return hasCursorCompactRegistration(root);
   if (host === 'codex') return hasCodexCompactRegistration(root);
   const files = COMPACT_HOST_FILES[host];
   return Boolean(files) && files.every((relativePath) => fs.existsSync(path.join(root, relativePath)));

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

@@ -197,7 +197,7 @@ Codex hard write covers only a complete local \`apply_patch\`; Cursor covers onl
 installed + trusted, while shell/direct
 filesystem writes, hosted or specialized opt-out paths, and human edits still rely on CI.
 
-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 **envelopes** may be emitted without reinjection being guaranteed; silent auto-apply never happens. Run \`arkgate-check --doctor\` (or \`ark-check --doctor\`) for the evidence actually detected in the current repository.`;
+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. **Write-gate order:** install and trust the host pre-hook first. MCP prepare is fallback when that path is missing or fail-open. 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 **envelopes** may be emitted without reinjection being guaranteed; silent auto-apply never happens. Run \`arkgate-check --doctor\` (or \`ark-check --doctor\`) for the evidence actually detected in the current repository.`;
 }
 
 /**

package/bin/lib/html-report-depth.mjs

@@ -224,7 +224,7 @@ export function writePathModeHint(mode) {
     case 'reject-only':
       return 'Hard write boundary without repair payload; edits can be blocked without guided re-entry.';
     case 'mcp-only':
-      return 'Advisory MCP only — prepare-write/autoPatch available, no hard PreToolUse for this host.';
+      return 'Fell back to MCP prepare — advisory prepare-write/autoPatch; no hard PreToolUse for this host.';
     case 'none':
       return 'No hard write boundary or advisory MCP for the active host (or host is unknown in this process).';
     default:

package/bin/lib/install-migrate.mjs

@@ -200,10 +200,9 @@ export function buildManagedAssetCatalog({ root, tools, compact = false, skillsO
       })
     );
     if (selectedTools.has('cursor')) {
-      add('.cursor/mcp.json', mcpJson(root));
-      // whole-file for managed upgrade/manifest (json-merge is install-time only via
-      // mergeCursorArkHook below — same pattern as Antigravity hooks).
+      // Write-gate order: pre-hook first, MCP prepare as fallback + identity.
       add('.cursor/hooks.json', cursorHooks(root));
+      add('.cursor/mcp.json', mcpJson(root));
       if (!compact) add('.cursor/rules/ark.mdc', cursorRule(root));
     }
     if (selectedTools.has('claude')) add('.claude/settings.json', claudeSettings(root));
@@ -213,8 +212,8 @@ export function buildManagedAssetCatalog({ root, tools, compact = false, skillsO
       if (!compact) add('docs/ark-codex-config.toml', codexTomlSnippet(root));
     }
     if (selectedTools.has('grok')) {
-      add('.grok/config.toml', grokProjectConfig(root));
       add('.grok/hooks/ark-write-gate.json', grokHooks(root));
+      add('.grok/config.toml', grokProjectConfig(root));
     }
     if (selectedTools.has('antigravity')) {
       add('.agents/hooks.json', antigravityHooks(root));

package/bin/lib/managed-upgrade.mjs

@@ -17,6 +17,7 @@ import {
   arkPackageVersion,
   detectActiveAgentHost,
   normalizeToolsList,
+  planSkillInstall,
   skillContentIdentity,
 } from './skill-install.mjs';
 
@@ -396,8 +397,11 @@ function summaryFor(assets, manifestChanged) {
   for (const asset of assets) states[asset.state] = (states[asset.state] ?? 0) + 1;
   const applying = assets.filter((asset) => asset.willApply);
   const wouldWrite = applying.length;
-  // Public-summary compatibility: stamp-only writes are no longer scheduled.
-  const metadataRefresh = 0;
+  // Same-body stamp drift (arkVersion / description prefix) stays state=current
+  // and is scheduled via planSkillInstall stamp-refresh — not a second pipeline.
+  const metadataRefresh = applying.filter(
+    (asset) => asset.state === 'current' && asset.reason === 'stamp-refresh'
+  ).length;
   const customizedPreserved = assets.filter((asset) => asset.state === 'customized').length;
   const fileChanges = applying.length;
   return {
@@ -477,9 +481,23 @@ export function planManagedUpgrade(root, options = {}) {
       refreshSkills &&
       catalogAsset.kind === 'skill' &&
       classified.state === 'customized';
+    // HS01 / #284: identity-current skill whose arkVersion / description prefix
+    // lagged the package — reuse planSkillInstall stamp-refresh, do not reclassify.
+    const stampRefresh =
+      !unparsedScope &&
+      catalogAsset.kind === 'skill' &&
+      classified.state === 'current' &&
+      currentScoped != null &&
+      planSkillInstall({
+        existingContent: currentScoped,
+        targetContent: desiredScoped,
+        packageVersion: catalog.version ?? arkPackageVersion(),
+        scope: 'repo',
+      }).reason === 'stamp-refresh';
     const canApply =
       classified.state === 'stale' ||
       skillRefresh ||
+      stampRefresh ||
       (classified.state === 'missing' && (!recorded || accepted)) ||
       (classified.state === 'conflicted' && accepted);
     const blocked = classified.requiresConsent && !accepted && !skillRefresh;
@@ -490,7 +508,11 @@ export function planManagedUpgrade(root, options = {}) {
       kind: catalogAsset.kind,
       scope: catalogAsset.scope,
       ...classified,
-      ...(unparsedScope ? { reason: 'unparsed managed TOML scope preserved' } : {}),
+      ...(unparsedScope
+        ? { reason: 'unparsed managed TOML scope preserved' }
+        : stampRefresh
+          ? { reason: 'stamp-refresh' }
+          : {}),
       action: canApply ? (currentScoped == null ? 'create' : 'update') : 'none',
       willApply: canApply,
       blocked,
@@ -970,8 +992,11 @@ export function renderManagedUpgrade(plan, options = {}) {
   const customizedPreserved = summary.customizedPreserved ?? summary.states?.customized ?? 0;
   const blocked = summary.blocked ?? 0;
   console.log(
-    `Managed assets: ${managedAssets}; would write: ${wouldWrite}; ` +
-      `customized preserved: ${customizedPreserved}; blocked conflicts/deletions: ${blocked}.`
+    `Managed assets: ${managedAssets}; would write: ${wouldWrite}` +
+      (summary.metadataRefresh
+        ? `; metadata refresh: ${summary.metadataRefresh}`
+        : '') +
+      `; customized preserved: ${customizedPreserved}; blocked conflicts/deletions: ${blocked}.`
   );
   const honesty =
     plan.selfService ??

package/bin/lib/mcp-adoption.mjs

@@ -191,7 +191,10 @@ export function collectAdoptionGaps(root, config, coverage) {
         host: 'cursor',
         dir: '.cursor',
         skill: (n) => path.join(root, '.cursor', 'commands', `${n}.md`),
-        extras: [['.cursor/mcp.json', 'MCP config']],
+        extras: [
+          ['.cursor/hooks.json', 'write-gate hook'],
+          ['.cursor/mcp.json', 'MCP config (fallback)'],
+        ],
         toolsFlag: 'cursor',
       },
       {

package/bin/lib/presets.mjs

@@ -10,6 +10,7 @@ import {
   DEFAULT_DOMAIN_FORBIDDEN_GLOBALS,
   discoverRepoUnits,
   DEFAULT_INTENT_PREFIXES,
+  monorepoRoleSourceGlobs,
   resolveIncludeRoots,
 } from '../ark-shared.mjs';
 import { withArkConfigMetadata } from './config-contract.mjs';
@@ -630,20 +631,18 @@ export const ARCHITECTURE_PRESETS = {
     // Turborepo: apps/ + packages/; Nx enterprise: apps/ + libs/ (+ packages/).
     if (include.length === 0) include = ['packages', 'apps', 'libs'];
     // Library Domain bags stay under packages/ or libs/ — never api/** or client/**.
-    const roleGlobs = (roles, domainScoped) =>
-      !root
-        ? []
-        : units
-            .filter((unit) => roles.includes(unit.role) && !(domainScoped && unit.root === '.'))
-            .flatMap((unit) =>
-              (unit.sourceRoots ?? []).map((sourceRoot) => {
-                const base = unit.root === '.' ? sourceRoot : sourceRoot === '.' ? unit.root : `${unit.root}/${sourceRoot}`;
-                return base === '.' ? null : `${base}/**`;
-              })
-            )
-            .filter((pattern) => pattern && (!domainScoped || /^(packages|libs)\//.test(pattern)));
-    const librarySourcePatterns = roleGlobs(['library'], true);
-    const applicationSourcePatterns = roleGlobs(['application', 'cli'], false);
+    const librarySourcePatterns = monorepoRoleSourceGlobs(units, ['library'], {
+      root,
+      domainScoped: true,
+    });
+    const applicationSourcePatterns = monorepoRoleSourceGlobs(units, ['application', 'cli'], {
+      root,
+      uiMode: 'not-ui',
+    });
+    const uiApplicationSourcePatterns = monorepoRoleSourceGlobs(units, ['application', 'cli'], {
+      root,
+      uiMode: 'ui',
+    });
     return presetWithOverlays(
       {
         include,
@@ -689,6 +688,7 @@ export const ARCHITECTURE_PRESETS = {
               '**/http/**',
               '**/routes/**',
               '**/hooks/**',
+              ...uiApplicationSourcePatterns,
               // No bare **/lib/** — NEW-ADOPT-LIB-AS-PRESENTATION / NEW-APP-VACUUM-LIB.
             ],
             optional: true,

package/bin/lib/scan-files.mjs

@@ -4,7 +4,9 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { isScanExcludedRelative } from '../ark-shared.mjs';
+import { isScanExcludedRelative, isSkippedSourceDir } from '../ark-shared.mjs';
+
+export { isSkippedSourceDir };
 
 export const SOURCE_FILE_NAME = /\.[cm]?[tj]sx?$/;
 
@@ -18,31 +20,6 @@ export function isGovernableSourceFile(name) {
   return SOURCE_FILE_NAME.test(name) && !name.endsWith('.d.ts') && !TEST_FILE_NAME.test(name);
 }
 
-export function isSkippedSourceDir(name) {
-  return (
-    name === 'node_modules' ||
-    name === 'dist' ||
-    name === 'coverage' ||
-    name === 'bench' ||
-    name === 'benches' ||
-    name === 'benchmark' ||
-    name === 'benchmarks' ||
-    name === 'docs' ||
-    name === 'documentation' ||
-    name === 'example' ||
-    name === 'examples' ||
-    name === 'fixture' ||
-    name === 'fixtures' ||
-    name === 'playground' ||
-    name === '__tests__' ||
-    name === '__mocks__' ||
-    name === 'e2e' ||
-    // Top-level style Nest/Jest folders (not "testing" helpers inside src)
-    name === 'test' ||
-    name === 'tests'
-  );
-}
-
 function isInsideRoot(root, target) {
   const rel = path.relative(root, target);
   return rel === '' || (!rel.startsWith(`..${path.sep}`) && rel !== '..' && !path.isAbsolute(rel));

package/bin/lib/skill-install.mjs

@@ -486,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,

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,
@@ -207,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');
 }
 
 /**
@@ -263,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}`);
@@ -503,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-BNxKdcN4.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.18";
+declare const version = "4.8.19";
 
 /**
  * AI Code Gate (basic).