arkgate 4.8.23 → 4.8.25

package/bin/lib/install-migrate.mjs

@@ -10,6 +10,7 @@ import {
   execRunner,
   presentLockfiles,
 } from '../ark-shared.mjs';
+import { npxArkgatePrefixLength } from './package-manager.mjs';
 import {
   codexPromptsDir,
   codexSkillsDir,
@@ -29,6 +30,7 @@ import {
   grokHooks,
   grokProjectConfig,
   mergeAntigravityArkHook,
+  mergeClaudeStyleArkHooks,
   mergeCursorArkHook,
   mergeOpencodeArkMcp,
   opencodeProjectConfig,
@@ -39,6 +41,7 @@ import {
   compactRouterHost,
   mergeArkMcpJson,
   MCP_JSON_GATE_FILES,
+  CLAUDE_STYLE_HOOK_FILES,
   writeTemplate,
 } from './gate-files.mjs';
 import {
@@ -119,7 +122,10 @@ export function staleRunnerGateFiles(root) {
       continue;
     }
     const ark = json?.mcpServers?.ark;
-    if (ark && ark.command && ark.command !== want.split(' ')[0]) stale.push(rel);
+    if (!ark || !ark.command) continue;
+    // Unpinned project: a bare `npx <bin>` MCP entry 404s the same way a text command does.
+    const barePinnedNpx = want.startsWith('npx ') && npxArkgatePrefixLength(ark.args) === 0;
+    if (ark.command !== want.split(' ')[0] || barePinnedNpx) stale.push(rel);
   }
   return stale;
 }
@@ -341,6 +347,18 @@ export function runMigrateCommands(root) {
   warnLockfileConflict(root);
 }
 
+/** Shared host files Ark merges into (keeps sibling servers / hooks / keys). */
+function mergeableGateFile(relativePath) {
+  if (relativePath === 'opencode.json') return { fn: mergeOpencodeArkMcp, forceReplaces: false };
+  if (relativePath === '.cursor/hooks.json') return { fn: mergeCursorArkHook, forceReplaces: false };
+  if (relativePath === '.agents/hooks.json') return { fn: mergeAntigravityArkHook, forceReplaces: false };
+  if (CLAUDE_STYLE_HOOK_FILES.includes(relativePath)) {
+    return { fn: mergeClaudeStyleArkHooks, forceReplaces: true };
+  }
+  if (MCP_JSON_GATE_FILES.includes(relativePath)) return { fn: mergeArkMcpJson, forceReplaces: true };
+  return null;
+}
+
 export function runInstallAgentGates(args) {
   const root = args.root;
   if (args.migrateCommands) {
@@ -454,6 +472,11 @@ export function runInstallAgentGates(args) {
         `Added package.json script "typecheck": "${typecheckBootstrap.script}" (tsconfig present; local/CI parity).`
       );
     }
+    if (typecheckBootstrap.reason === 'no-typescript' && !args.compact && !args.json) {
+      console.log(
+        'tsconfig/jsconfig found but typescript is not a dependency — skipped the "typecheck" script and CI step (add typescript as a devDependency, then "typecheck": "tsc --noEmit").'
+      );
+    }
   }
   const catalog = buildManagedAssetCatalog({
     root,
@@ -518,81 +541,24 @@ 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 === '.cursor/hooks.json') {
-      const fullPath = path.join(root, relativePath);
-      let existing = '';
-      try {
-        existing = fs.readFileSync(fullPath, 'utf8');
-      } catch {
-        // Missing hooks file → write generated Cursor preToolUse gate.
-      }
-      if (!existing) {
-        return writeTemplate(root, relativePath, content, true);
-      }
-      const merged = mergeCursorArkHook(existing, content);
-      if (merged == null) {
-        return { relativePath, status: 'skipped-non-ark' };
-      }
-      if (merged === existing) return { relativePath, status: 'skipped' };
-      // Upsert Ark preToolUse without requiring --force; never wipe sibling hooks.
-      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);
-    }
-    if (MCP_JSON_GATE_FILES.includes(relativePath)) {
-      const fullPath = path.join(root, relativePath);
+    const merge = mergeableGateFile(relativePath);
+    if (merge) {
+      // Upsert Ark's entry into a shared host file without --force; never wipe sibling keys.
       let existing = '';
       try {
-        existing = fs.readFileSync(fullPath, 'utf8');
+        existing = fs.readFileSync(path.join(root, relativePath), 'utf8');
       } catch {
-        // Missing MCP JSON → write generated ark server.
-      }
-      if (!existing) {
-        return writeTemplate(root, relativePath, content, true);
+        // Missing file → write the generated Ark template.
       }
-      const merged = mergeArkMcpJson(existing, content);
+      if (!existing) return writeTemplate(root, relativePath, content, true);
+      const merged = merge.fn(existing, content);
       if (merged == null) {
-        return args.force
+        // Unmergeable file: never guess. --force replaces it only where that is explicit consent.
+        return merge.forceReplaces && args.force
           ? writeTemplate(root, relativePath, content, true)
           : { relativePath, status: 'skipped-non-ark' };
       }
       if (merged === existing) return { relativePath, status: 'skipped' };
-      // Upsert mcpServers.ark without requiring --force; never wipe sibling servers.
       return writeTemplate(root, relativePath, merged, true);
     }
     return writeTemplate(
@@ -794,14 +760,25 @@ export function runInstallAgentGates(args) {
     }
     if (tools.has('codex') && !args.compact) {
       console.log('  Codex write path (honest):');
-      console.log('    - Local: advisory MCP + best-effort .codex/hooks.json (not a hard boundary).');
-      console.log('    - Hard merge backstop: CI --strict-merge + required status check.');
-      console.log('    - Not equivalent to Claude/Grok PreToolUse hard-write + repair.');
+      console.log('    - Local: .codex/hooks.json PreToolUse hard-blocks a complete local apply_patch (Codex CLI / local Desktop) once the project is trusted and a hook run is runtime-observed; on disk it is configured, not verified.');
+      console.log('    - Outside that claim (hosted tools, hook opt-out, shell writes, incomplete patch reconstruction): CI --strict-merge + required status check.');
+      console.log('    - Repair envelopes may emit, but Codex reinjection is not guaranteed (unlike Claude/Grok hard-write + repair).');
     }
     if (args.codexHome) {
-      console.log(
-        `  Codex: refreshed home skills under ${codexSkillsDir()}/<name>/SKILL.md (Codex skill catalog).`
-      );
+      // Report what the home write actually did (it is skipped when the project catalog exists).
+      if (homeResults.some((r) => r.status === 'written')) {
+        console.log(
+          `  Codex: refreshed home skills under ${codexSkillsDir()}/<name>/SKILL.md (Codex skill catalog).`
+        );
+      } else if (homeResults.some((r) => r.status === 'failed')) {
+        console.log(`  Codex: home skills NOT written under ${codexSkillsDir()} (see failures above).`);
+      } else if (homeResults.length === 0) {
+        console.log(
+          '  Codex: home skills not written — project .agents/skills is the catalog (Codex reads repo scope).'
+        );
+      } else {
+        console.log(`  Codex: home skills under ${codexSkillsDir()} already current (no changes).`);
+      }
     } else if (tools.has('codex') && skills.length > 0 && !args.compact) {
       console.log(
         '  Codex: project skills at `.agents/skills/<name>/SKILL.md` (Agent Skills REPO scope).'

package/bin/lib/invariant-coverage-io.mjs

@@ -10,7 +10,7 @@ const DEFAULT_TEST_NAME_RE =
   /\.(test|spec)\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$|\/__tests__\/|\/tests?\//i;
 
 /** Default max files to load for coverage evidence (budget). Config: `coverage.maxFiles`. */
-export const DEFAULT_MAX_COVERAGE_FILES = 400;
+const DEFAULT_MAX_COVERAGE_FILES = 400;
 /**
  * Hard ceiling on `coverage.maxFiles`. The config validator implements no
  * `maximum` keyword for integers, so a schema bound would be accepted and then
@@ -38,11 +38,12 @@ function isPathInsideRoot(root, absolute) {
 }
 
 /**
- * Minimal glob match for testGlobs (double-star slash = zero path segments).
+ * Minimal glob match for testGlobs and ArkRules `appliesTo` fileHints
+ * (double-star slash = zero path segments).
  * @param {string} glob
  * @param {string} file
  */
-function matchSimpleGlob(glob, file) {
+export function matchSimpleGlob(glob, file) {
   const pattern = String(glob || '').replace(/\\/g, '/');
   const target = String(file || '').replace(/\\/g, '/');
   if (!pattern) return false;

package/bin/lib/invariant-coverage.mjs

@@ -8,6 +8,8 @@
  * Pure CLI helper (bin/lib/invariant-coverage.mjs). Zero Node I/O.
  */
 
+import { findClassDeclarations, findMemberContainers, objectLiteralMemberNames, scanClassMembers, } from './class-source-scan.mjs';
+import { probeRefusalReason, verdictRefusesPromotion } from './invariant-probe.mjs';
 /** Adopted + catalogued invariants, but no declared tests path (P2 §10). */
 export const INVARIANT_TESTS_PATH_RULE_ID = 'INVARIANT_TESTS_PATH_MISSING';
 export const INVARIANT_TESTS_PATH_MESSAGE = 'This project is adopted and has domain invariants, but ark.config.json does not name a real tests path. Add coverage.testGlobs or coverage.coverageRoots pointing at the folder where those tests live, then re-run. Without that path, coverage is an empty checkbox.';
@@ -185,6 +187,38 @@ function declarationShape(content, name) {
     }
     return undefined;
 }
+/**
+ * `Name.member` coverage: the member must be declared inside the body of
+ * `class Name` (exported, default-exported, abstract, or local), a
+ * `const Name = class { … }` expression, a `namespace Name { … }` (function or
+ * const member), or a `const Name = { … }` object literal, in this file. A
+ * member of another container, a free function, or a file that merely mentions
+ * the name does not count.
+ */
+function classMemberShape(content, className, member) {
+    const hasClassMethod = (body) => scanClassMembers(body).members.some((m) => m.kind === 'method' && m.name === member);
+    for (const decl of findClassDeclarations(content)) {
+        if (decl.name !== className || decl.bodyStart == null)
+            continue;
+        if (hasClassMethod(content.slice(decl.bodyStart, decl.bodyEnd ?? content.length))) {
+            return 'method';
+        }
+    }
+    for (const container of findMemberContainers(content, className)) {
+        const body = content.slice(container.bodyStart, container.bodyEnd);
+        if (container.kind === 'class-expression' && hasClassMethod(body))
+            return 'method';
+        if (container.kind === 'object' && objectLiteralMemberNames(body).includes(member)) {
+            return 'method';
+        }
+        if (container.kind === 'namespace') {
+            const shape = declarationShape(body, member);
+            if (shape === 'function' || shape === 'const')
+                return shape;
+        }
+    }
+    return undefined;
+}
 function lineAt(content, index) {
     const start = content.lastIndexOf('\n', index - 1) + 1;
     const end = content.indexOf('\n', index);
@@ -298,7 +332,8 @@ function symbolNeedle(symbol) {
     const name = parts[parts.length - 1] ?? '';
     if (!name)
         return undefined;
-    const className = parts.length > 1 ? (parts[0] ?? null) : null;
+    // `Aggregate.method` (or `ns.Aggregate.method`): the segment before the member names the class.
+    const className = parts.length > 1 ? (parts[parts.length - 2] || null) : null;
     return { className, name };
 }
 function declaredLabel(invariant) {
@@ -344,9 +379,9 @@ function rankCoverage(invariant, files, scanTests = true) {
             const content = files.fileContents[file];
             if (!content)
                 continue;
-            if (needle.className && !content.includes(needle.className))
-                continue;
-            const shape = declarationShape(content, needle.name);
+            const shape = needle.className
+                ? classMemberShape(content, needle.className, needle.name)
+                : declarationShape(content, needle.name);
             if (!shape)
                 continue;
             declaration = { file, shape };
@@ -513,10 +548,14 @@ export function evaluateInvariantCoverage(input) {
         // Covered if the policy says this verdict counts.
         // When coverage declares neither test nor symbol, require at least description-only advisory presence = not covered.
         const requiresEvidence = inv.coverage?.test === true || Boolean(symbol) || inv.coverage === undefined;
+        // `coverage.test: false` without a symbol declares zero evidence. That opt-out is
+        // advisory-only: on an enforced invariant it is reported uncovered (never a false
+        // green), not refused at load, so the rest of the contract still evaluates.
+        const zeroEvidenceOptOut = inv.coverage?.test === false && !symbol;
         const covered = requiresEvidence && counts
             ? true
-            : inv.coverage?.test === false && !symbol
-                ? true // explicitly no coverage requirements
+            : zeroEvidenceOptOut && inv.mode !== 'enforced'
+                ? true // explicitly no coverage requirements (advisory-only opt-out)
                 : counts;
         // Partial only when tests are missing *and* no other evidence (e.g. symbol) completed coverage.
         const partial = testGlobsMissing && wantsTest && !counts;
@@ -562,11 +601,13 @@ export function evaluateInvariantCoverage(input) {
                     ? coverageBudgetExhausted
                         ? `Invariant ${inv.id} coverage cannot be proven (${budgetDetail}); reporting partial, not covered.`
                         : `Invariant ${inv.id} coverage cannot be proven (test globs missing or empty); reporting partial, not covered (never-had-tests).`
-                    : // The sentence is the verdict. It names a title, a declaration
-                        // shape, a bare mention, or silence — it does not re-scan.
-                        `Invariant ${inv.id}: ${describeCoverage(inv, ev)} (${kind === 'tests-disappeared'
-                            ? 'tests-disappeared — a suite exists'
-                            : 'never-had-tests — the scan found no tests at all'}). ArkGate matches declared text; it never executes tests.`) +
+                    : zeroEvidenceOptOut
+                        ? `Invariant ${inv.id} is enforced but declares no evidence (coverage.test is false and no coverage.symbol); set coverage.symbol, drop test:false, or keep mode "advisory".`
+                        : // The sentence is the verdict. It names a title, a declaration
+                            // shape, a bare mention, or silence — it does not re-scan.
+                            `Invariant ${inv.id}: ${describeCoverage(inv, ev)} (${kind === 'tests-disappeared'
+                                ? 'tests-disappeared — a suite exists'
+                                : 'never-had-tests — the scan found no tests at all'}). ArkGate matches declared text; it never executes tests.`) +
                     (partial && coverageBudgetExhausted ? budgetExhaustedTail : discardTail),
                 file: inv.provenance.sourceFile,
                 line: 1,
@@ -608,6 +649,14 @@ export function canPromoteInvariant(coverage) {
             reason: `Invariant ${coverage.invariantId} is uncovered; add a test title or symbol before promoting to enforced.`,
         };
     }
+    // A `coverage.test: false` opt-out without a symbol reports covered with no
+    // evidence at all. That is fine while advisory; it is not a basis for enforcing.
+    if (Array.isArray(coverage.evidence) && coverage.evidence.length === 0) {
+        return {
+            ok: false,
+            reason: `Invariant ${coverage.invariantId} declares no evidence (coverage.test:false and no symbol); add coverage.symbol or a test title before promoting to enforced.`,
+        };
+    }
     // Promotion is the moment coverage stops being advice, so an evidence file
     // the project itself says its runner does not walk cannot carry it.
     if (coverage.outsideDeclaredRoots === true) {
@@ -624,6 +673,15 @@ export function canPromoteInvariant(coverage) {
             reason: `Declare coverage.coverageRoots in ark.config.json before promoting ${coverage.invariantId} to enforced. Without that, ArkGate cannot tell whether a covering test is one the runner executes.`,
         };
     }
+    // ADR 0039 D2: probe evidence can only subtract. A fresh survived or
+    // not-reached row refuses; stale, killed, inconclusive or absent changes nothing.
+    if (coverage.probe?.fresh === true && verdictRefusesPromotion(coverage.probe.verdict)) {
+        return {
+            ok: false,
+            reason: probeRefusalReason(coverage.invariantId, coverage.probe),
+            blocker: 'probe-survived',
+        };
+    }
     return { ok: true, reason: `Invariant ${coverage.invariantId} has coverage evidence.` };
 }
 function nonEmptyPathStrings(value) {
@@ -732,3 +790,19 @@ export function collectMissingCoverageRootsFindings(input) {
         },
     ];
 }
+/**
+ * Test files whose describe/it/test/context title names `invariant.id` — the
+ * same title matcher coverage uses. Sorted, deduplicated. The probe (ADR 0039)
+ * runs these as covering tests; coverage itself never runs anything.
+ */
+export function testFilesNamingInvariant(invariant, files) {
+    const out = new Set();
+    for (const file of files.testFiles ?? []) {
+        const content = files.fileContents[file];
+        if (!content)
+            continue;
+        if (matchTestTitle(content, invariant.id) !== undefined)
+            out.add(normalizePath(file));
+    }
+    return [...out].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}