arkgate 2.9.2 → 2.10.0

package/bin/lib/agent-gates.mjs

@@ -702,7 +702,9 @@ export function claudeSettings(root) {
           hooks: [
             {
               type: 'command',
-              command: `${runner} ${PREFERRED_MCP_BIN} --hook --root "$CLAUDE_PROJECT_DIR" --config ark.config.json`,
+              // W4: --hook-repair emits ARK_REPAIR_JSON / ARK_AUTOPATCH_JSON on deny
+              // (still exit 2 — never silent write). Omit --hook-repair for reject-only prose.
+              command: `${runner} ${PREFERRED_MCP_BIN} --hook --hook-repair --root "$CLAUDE_PROJECT_DIR" --config ark.config.json`,
             },
           ],
         },
@@ -758,7 +760,8 @@ export function grokHooks(root) {
             {
               type: 'command',
               timeout: 30,
-              command: `${runner} ${PREFERRED_MCP_BIN} --hook --root "${grokRoot}" --config ark.config.json`,
+              // W4: --hook-repair → structured autoPatch on deny (hard block still).
+              command: `${runner} ${PREFERRED_MCP_BIN} --hook --hook-repair --root "${grokRoot}" --config ark.config.json`,
             },
           ],
         },
@@ -1284,15 +1287,160 @@ function collectCiWorkflowTexts(root) {
   return texts;
 }
 
+/**
+ * W5 — Write-path capability surface for doctor (stable additive JSON).
+ *
+ * Detects whether installed agent gates expose:
+ *   - MCP prepare-write / validate_code (autoPatch) tools
+ *   - PreToolUse hook in reject-only vs repair mode (--hook-repair / ARK_HOOK_REPAIR)
+ *
+ * Never claims silent apply; "repair" means host can re-inject a patch after hard deny.
+ *
+ * @returns {{
+ *   mode: 'repair' | 'reject-only' | 'mcp-only' | 'none',
+ *   prepareWrite: boolean,
+ *   autoPatch: boolean,
+ *   hookPresent: boolean,
+ *   hookRepair: boolean,
+ *   mcpPresent: boolean,
+ *   evidence: string[],
+ *   gap: null | { id: string, severity: string, message: string, fix: string },
+ * }}
+ */
+export function detectWritePathCapabilities(root) {
+  const evidence = [];
+  let hookPresent = false;
+  let hookRepair = false;
+
+  const hookFiles = [
+    '.claude/settings.json',
+    '.grok/hooks/ark-write-gate.json',
+  ];
+  for (const rel of hookFiles) {
+    const abs = path.join(root, rel);
+    if (!fs.existsSync(abs)) continue;
+    let text = '';
+    try {
+      text = fs.readFileSync(abs, 'utf8');
+    } catch {
+      continue;
+    }
+    // PreToolUse / write-gate command referencing ark(-gate)?-mcp --hook
+    if (
+      /--hook\b/.test(text) ||
+      /\b(ark|arkgate)-mcp\b[\s\S]{0,80}--hook\b/.test(text) ||
+      /\b--hook\b[\s\S]{0,80}\b(ark|arkgate)-mcp\b/.test(text)
+    ) {
+      hookPresent = true;
+      evidence.push(rel);
+    }
+    if (
+      /--hook-repair\b/.test(text) ||
+      /ARK_HOOK_REPAIR\s*=\s*['"]?(1|true|yes|on)/i.test(text)
+    ) {
+      hookRepair = true;
+      if (!evidence.includes(rel)) evidence.push(rel);
+    }
+  }
+
+  let mcpPresent = false;
+  const mcpFiles = ['.mcp.json', '.cursor/mcp.json', '.grok/config.toml'];
+  for (const rel of mcpFiles) {
+    const abs = path.join(root, rel);
+    if (!fs.existsSync(abs)) continue;
+    let text = '';
+    try {
+      text = fs.readFileSync(abs, 'utf8');
+    } catch {
+      continue;
+    }
+    if (
+      /\b(ark|arkgate)-mcp\b/.test(text) ||
+      /mcp_servers\.ark\b/.test(text) ||
+      /"ark"\s*:\s*\{/.test(text) ||
+      /mcpServers[\s\S]*\bark\b/.test(text)
+    ) {
+      mcpPresent = true;
+      evidence.push(rel);
+    }
+  }
+
+  // Package tools when MCP is wired: ark_prepare_write + validate_code(autoPatch).
+  // Hook repair emits machine-readable autoPatch without silent write.
+  const prepareWrite = mcpPresent;
+  const autoPatch = mcpPresent || hookRepair;
+
+  /** @type {'repair' | 'reject-only' | 'mcp-only' | 'none'} */
+  let mode = 'none';
+  if (hookPresent && hookRepair) mode = 'repair';
+  else if (hookPresent && !hookRepair) mode = 'reject-only';
+  else if (mcpPresent) mode = 'mcp-only';
+
+  let gap = null;
+  if (mode === 'none') {
+    gap = {
+      id: 'write-path-none',
+      severity: 'warn',
+      message:
+        'Write path is not installed — no PreToolUse hook and no Ark MCP. Agents write without architecture gate or prepare-write.',
+      fix: arkCommand(root, 'ark-check', '--install-agent-gates'),
+    };
+  } else if (mode === 'reject-only') {
+    gap = {
+      id: 'write-path-reject-only',
+      severity: 'info',
+      message: mcpPresent
+        ? 'PreToolUse hook is reject-only (hard block, no ARK_REPAIR_JSON). MCP still exposes prepare-write/autoPatch — enable --hook-repair so the write boundary itself can re-inject patches.'
+        : 'Write path is reject-only (hard block with prose; no repair payload). Enable --hook-repair or ARK_HOOK_REPAIR=1 so hosts can re-inject patches without full re-draft.',
+      fix: arkCommand(
+        root,
+        'ark-check',
+        '--install-agent-gates --tools claude,grok --force'
+      ),
+    };
+  } else if (mode === 'mcp-only') {
+    gap = {
+      id: 'write-path-mcp-only',
+      severity: 'info',
+      message:
+        'MCP exposes prepare-write / autoPatch tools, but no PreToolUse write hook is installed — enforcement is advisory unless the agent calls tools.',
+      fix: arkCommand(root, 'ark-check', '--install-agent-gates --tools claude,grok'),
+    };
+  }
+
+  return {
+    mode,
+    prepareWrite,
+    autoPatch,
+    hookPresent,
+    hookRepair,
+    mcpPresent,
+    evidence: [...new Set(evidence)],
+    gap,
+  };
+}
+
 /**
  * Adoption completeness (separate from 0–100 fitness). Pure-ish: filesystem + config.
- * @returns {{ gaps: object[], hosts: object[], mcp: object, codexHome: object|null, coreOptional: object[], originReport: object, baseline: object, layerBalance: object|null, deployPath: object|null }}
+ * @returns {{ gaps: object[], hosts: object[], mcp: object, codexHome: object|null, coreOptional: object[], originReport: object, baseline: object, layerBalance: object|null, deployPath: object|null, writePath: object }}
  */
 export function collectAdoptionGaps(root, config, coverage) {
   const gaps = [];
   const adopted = fs.existsSync(path.join(root, 'AGENTS.md'));
   const isProducer = fs.existsSync(path.join(root, 'templates', 'skills'));
 
+  // --- Write path: prepare-write / autoPatch / reject-only (W5) ---
+  const writePath = detectWritePathCapabilities(root);
+  // Only surface write-path gaps when the project has adopted gates (or has partial install).
+  // Producer package tree always has templates — still report capability for dogfood honesty.
+  if (writePath.gap && (adopted || writePath.hookPresent || writePath.mcpPresent || isProducer)) {
+    // Producer may be repair-capable via own templates; still useful. Skip "none" on pure
+    // consumer repos with zero Ark files? missingGates already covers that.
+    if (!(writePath.mode === 'none' && !adopted && !isProducer)) {
+      gaps.push(writePath.gap);
+    }
+  }
+
   // --- Repo MCP dual-bin ---
   const dualMcp = brokenMcpGateFiles(root);
   const mcp = {
@@ -1609,6 +1757,7 @@ export function collectAdoptionGaps(root, config, coverage) {
     layerBalance,
     deployPath,
     contractFalseGreen,
+    writePath,
   };
 }
 

package/bin/lib/architecture-scan.mjs

@@ -25,6 +25,7 @@ import {
   textOfModuleSpecifier,
   typeOnlyExportNames,
 } from './ast-scan.mjs';
+import { provePortProofInject } from './port-proof.mjs';
 import {
   intentLayersFromManifest,
   layerForIntent,
@@ -264,6 +265,23 @@ export function runArchitectureScan({ root, config, manifest, rules, files, ts,
           !targetCached?.hasTopLevelSideEffects &&
           named.every((n) => targetTypeNames.has(n));
         const peerIsolation = Boolean(rule.peerIsolation);
+        // W6: port-proof eligibility (value import only; fail-closed static proof).
+        let portProofEligible = false;
+        if (
+          !edge.typeOnly &&
+          !peerIsolation &&
+          edge.kind === 'import' &&
+          !targetTypeOnlyExports &&
+          !namedBindingsTypeOnly
+        ) {
+          try {
+            const srcText = fs.readFileSync(file, 'utf8');
+            const proof = provePortProofInject(ts, srcText, { filePath: file });
+            portProofEligible = Boolean(proof.eligible);
+          } catch {
+            portProofEligible = false;
+          }
+        }
         violations.push({
           ruleId: 'LAYER_IMPORT_VIOLATION',
           file: relFile,
@@ -275,6 +293,7 @@ export function runArchitectureScan({ root, config, manifest, rules, files, ts,
           ...(targetTypeOnlyExports ? { targetTypeOnlyExports: true } : {}),
           ...(sourcePureTypeModule ? { sourcePureTypeModule: true } : {}),
           ...(namedBindingsTypeOnly ? { namedBindingsTypeOnly: true } : {}),
+          ...(portProofEligible ? { portProofEligible: true } : {}),
           ...(edge.kind ? { edgeKind: edge.kind } : {}),
           ...(peerIsolation ? { peerIsolation: true } : {}),
           message:

package/bin/lib/auto-patch.mjs

@@ -0,0 +1,264 @@
+/**
+ * W1 — Write-boundary autoPatch for mechanical-safe kinds that can be fixed
+ * by rewriting only the file being written (import type conversions).
+ *
+ * Multi-file kinds (type-only-import-move, pure-type-file-relocate) are classified
+ * but do not emit a single-file autoPatch — they need agent judgment / multi-file moves.
+ *
+ * Trust: post-patch revalidation must be green or the patch is discarded.
+ * Never invents new mechanical-safe kinds beyond classifyRemediation.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  isTypeOnlyModuleReference,
+  namedModuleBindings,
+  sourceFileExportsOnlyTypes,
+  sourceFileHasTopLevelSideEffects,
+  typeOnlyExportNames,
+} from './ast-scan.mjs';
+import { classifyRemediation } from './remediation.mjs';
+
+const EXT_CANDIDATES = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs', ''];
+
+/**
+ * True when abs stays under root (no path.relative escape).
+ * Empty relative path (abs === root) counts as inside.
+ * @param {string} root
+ * @param {string} abs
+ */
+function isUnderRoot(root, abs) {
+  if (!root || !abs) return false;
+  const rel = path.relative(path.resolve(root), path.resolve(abs));
+  return !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+export function resolveImportFileAbs(root, fromFilePath, specifier) {
+  if (typeof specifier !== 'string' || !specifier) return null;
+  if (!specifier.startsWith('./') && !specifier.startsWith('../')) return null;
+  if (!fromFilePath || !root) return null;
+  const rootAbs = path.resolve(root);
+  const fromAbs = path.isAbsolute(fromFilePath)
+    ? path.resolve(fromFilePath)
+    : path.resolve(rootAbs, fromFilePath);
+  // Refuse resolution when the importer itself is outside the project root.
+  if (!isUnderRoot(rootAbs, fromAbs)) return null;
+  const base = path.resolve(path.dirname(fromAbs), specifier);
+  const tryFile = (candidate) => {
+    try {
+      if (!isUnderRoot(rootAbs, candidate)) return null;
+      if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) return candidate;
+    } catch {
+      /* continue */
+    }
+    return null;
+  };
+  for (const ext of EXT_CANDIDATES) {
+    const hit = tryFile(base + ext);
+    if (hit) return hit;
+  }
+  for (const ext of EXT_CANDIDATES) {
+    if (!ext) continue;
+    const hit = tryFile(path.join(base, `index${ext}`));
+    if (hit) return hit;
+  }
+  return null;
+}
+
+/**
+ * Classify a target module for import-type conversion eligibility.
+ * @returns {{ pureTypeModule: boolean, typeOnlyNames: Set<string>, hasTopLevelSideEffects: boolean } | null}
+ */
+export function inspectTargetModule(ts, targetSource) {
+  if (!ts || typeof targetSource !== 'string') return null;
+  const sf = ts.createSourceFile('target.ts', targetSource, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  const pureTypeModule = sourceFileExportsOnlyTypes(ts, sf);
+  const typeOnlyNames = new Set(typeOnlyExportNames(ts, sf));
+  const hasTopLevelSideEffects = sourceFileHasTopLevelSideEffects(ts, sf);
+  return { pureTypeModule, typeOnlyNames, hasTopLevelSideEffects };
+}
+
+/**
+ * Decide remediation kind for converting a non-type-only import of `specifier`
+ * with named bindings `bindingNames` (or null for non-named).
+ * @returns {{ kind: string, confidence: number } | null}
+ */
+export function classifyImportTypeConversion(inspect, bindingNames) {
+  if (!inspect) return null;
+  if (inspect.pureTypeModule) {
+    return {
+      kind: 'import-type-from-pure-type-module',
+      confidence: 0.85,
+    };
+  }
+  // R6 parity with architecture-scan: refuse import-type convert when target has
+  // top-level side effects (would skip runtime init after import type).
+  if (inspect.hasTopLevelSideEffects) return null;
+  if (Array.isArray(bindingNames) && bindingNames.length > 0) {
+    if (bindingNames.every((n) => inspect.typeOnlyNames.has(n))) {
+      return {
+        kind: 'import-type-of-type-exports',
+        confidence: 0.86,
+      };
+    }
+  }
+  return null;
+}
+
+/**
+ * Rewrite eligible static imports/exports to type-only form.
+ * @returns {{ source: string, remediationKind: string, confidence: number } | null}
+ */
+export function applyImportTypeAutoPatch(ts, source, opts = {}) {
+  if (!ts || typeof source !== 'string') return null;
+  const { root, filePath, resolveTargetAbs = resolveImportFileAbs } = opts;
+  const sf = ts.createSourceFile(
+    filePath || 'file.ts',
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS
+  );
+
+  /** @type {Array<{ start: number, end: number, text: string }>} */
+  const replacements = [];
+  let bestKind = null;
+  let bestConfidence = 0;
+
+  for (const stmt of sf.statements) {
+    if (!ts.isImportDeclaration(stmt) && !ts.isExportDeclaration(stmt)) continue;
+    if (isTypeOnlyModuleReference(ts, stmt)) continue;
+    const specNode = stmt.moduleSpecifier;
+    if (!specNode || !ts.isStringLiteralLike(specNode)) continue;
+    const specifier = specNode.text;
+    const abs = resolveTargetAbs(root, filePath, specifier);
+    if (!abs) continue;
+    let targetText;
+    try {
+      targetText = fs.readFileSync(abs, 'utf8');
+    } catch {
+      continue;
+    }
+    const inspect = inspectTargetModule(ts, targetText);
+    const bindings = namedModuleBindings(ts, stmt);
+    // Named imports/re-exports only. Default, namespace, and side-effect imports stay
+    // judgment (never auto-convert to import type).
+    const conversion = classifyImportTypeConversion(inspect, bindings);
+    if (ts.isImportDeclaration(stmt)) {
+      const clause = stmt.importClause;
+      if (!clause) continue; // side-effect
+      if (clause.name) continue; // default import — judgment
+      if (clause.namedBindings && ts.isNamespaceImport(clause.namedBindings)) continue;
+    }
+    if (!conversion) continue;
+
+    const full = source.slice(stmt.getStart(sf), stmt.getEnd());
+    let next = full;
+    if (ts.isImportDeclaration(stmt)) {
+      // `import { A } from 'x'` → `import type { A } from 'x'`
+      // `import { type A, B }` partial already type-only per binding — only full convert
+      if (/^\s*import\s+type\b/.test(full)) continue;
+      next = full.replace(/^(\s*import)(\s+)/, '$1 type$2');
+    } else if (ts.isExportDeclaration(stmt) && stmt.moduleSpecifier) {
+      if (/^\s*export\s+type\b/.test(full)) continue;
+      next = full.replace(/^(\s*export)(\s+)/, '$1 type$2');
+    }
+    if (next === full) continue;
+    replacements.push({ start: stmt.getStart(sf), end: stmt.getEnd(), text: next });
+    if (conversion.confidence >= bestConfidence) {
+      bestConfidence = conversion.confidence;
+      bestKind = conversion.kind;
+    }
+  }
+
+  if (replacements.length === 0 || !bestKind) return null;
+  // Apply from end so offsets stay valid
+  replacements.sort((a, b) => b.start - a.start);
+  let out = source;
+  for (const r of replacements) {
+    out = out.slice(0, r.start) + r.text + out.slice(r.end);
+  }
+  if (out === source) return null;
+  return {
+    source: out,
+    remediationKind: bestKind,
+    confidence: bestConfidence,
+  };
+}
+
+/**
+ * Run gate validation, try mechanical-safe single-file autoPatch, re-validate.
+ *
+ * @param {{
+ *   source: string,
+ *   filePath?: string,
+ *   root: string,
+ *   ts: object,
+ *   validate: (source: string) => { valid: boolean, violations?: any[] },
+ *   resolveTargetAbs?: Function,
+ * }} opts
+ */
+export function validateWithAutoPatch(opts) {
+  const { source, filePath, root, ts, validate, resolveTargetAbs } = opts;
+  const result = validate(source);
+  const base = {
+    valid: Boolean(result.valid),
+    violations: Array.isArray(result.violations) ? result.violations : [],
+  };
+
+  // Attach remediation classification for LAYER_IMPORT violations when flags known
+  const violations = base.violations.map((v) => {
+    const verdict = classifyRemediation({
+      ruleId: v.ruleId || v.code,
+      typeOnly: v.typeOnly,
+      sourcePureTypeModule: v.sourcePureTypeModule,
+      targetTypeOnlyExports: v.targetTypeOnlyExports,
+      namedBindingsTypeOnly: v.namedBindingsTypeOnly,
+      portProofEligible: v.portProofEligible ?? v.details?.portProofEligible,
+      peerIsolation: v.peerIsolation ?? v.details?.peerIsolation,
+      edgeKind: v.edgeKind ?? v.details?.importKind,
+      fromLayer: v.fromLayer,
+      toLayer: v.toLayer,
+      target: v.target,
+    });
+    return {
+      ...v,
+      remediationClass: verdict.class,
+      remediationKind: verdict.remediationKind,
+      remediationConfidence: verdict.confidence,
+    };
+  });
+
+  if (base.valid) {
+    return { valid: true, violations: [], autoPatch: null };
+  }
+
+  // Write-path autoPatch: import-type mechanical-safe only (W1).
+  // W6 port-proof inject is judgment (signature change) — never re-inject on write path.
+  const attempt = applyImportTypeAutoPatch(ts, source, {
+    root,
+    filePath,
+    resolveTargetAbs: resolveTargetAbs || resolveImportFileAbs,
+  });
+
+  if (!attempt) {
+    return { valid: false, violations, autoPatch: null };
+  }
+
+  const after = validate(attempt.source);
+  if (!after.valid) {
+    // Discard — never return an unvalidated patch
+    return { valid: false, violations, autoPatch: null };
+  }
+
+  return {
+    valid: false,
+    violations,
+    autoPatch: {
+      source: attempt.source,
+      remediationKind: attempt.remediationKind,
+      confidence: attempt.confidence,
+      valid: true,
+    },
+  };
+}

package/bin/lib/doctor-plan.mjs

@@ -14,6 +14,7 @@ import {
 import {
   collectAdoptionGaps,
   detectSkillGaps,
+  detectWritePathCapabilities,
   missingGates,
   staleRunnerGateFiles,
 } from './agent-gates.mjs';
@@ -268,6 +269,8 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   const skillGaps = detectSkillGaps(root);
   const staleRunners = staleRunnerGateFiles(root);
   const adoption = collectAdoptionGaps(root, config, cov);
+  // Prefer writePath from adoption (same detector); recompute only if missing (tests/stubs).
+  const writePath = adoption.writePath ?? detectWritePathCapabilities(root);
   const baseline = readBaseline(root, '.ark-baseline.json');
   const currentKeys = new Set(violations.map(baselineKey));
   const suppressed = baseline.exists
@@ -323,6 +326,26 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             gatesMissing,
             skillGaps,
             staleRunnerFiles: staleRunners,
+            // W5 — prepare-write / autoPatch / reject-only awareness (stable additive)
+            writePath: {
+              mode: writePath.mode,
+              prepareWrite: writePath.prepareWrite,
+              autoPatch: writePath.autoPatch,
+              hookPresent: writePath.hookPresent,
+              hookRepair: writePath.hookRepair,
+              mcpPresent: writePath.mcpPresent,
+              evidence: writePath.evidence,
+              ...(writePath.gap
+                ? {
+                    gap: {
+                      id: writePath.gap.id,
+                      severity: writePath.gap.severity,
+                      message: writePath.gap.message,
+                      fix: writePath.gap.fix,
+                    },
+                  }
+                : { gap: null }),
+            },
             adoption,
             newHere: showNewHere
               ? {
@@ -469,6 +492,37 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     }
   }
 
+  console.log('');
+  console.log(color.bold('Write path (agent)'));
+  const writePathLabels = {
+    repair: 'repair-capable — hard block + machine-readable autoPatch / ARK_REPAIR_JSON',
+    'reject-only': 'reject-only — hard block with prose; no repair payload',
+    'mcp-only': 'MCP tools only — prepare-write/autoPatch available; no PreToolUse hook',
+    none: 'none — no write gate hook and no Ark MCP',
+  };
+  const wpMark =
+    writePath.mode === 'repair'
+      ? ok
+      : writePath.mode === 'none'
+        ? bad
+        : warn;
+  line(wpMark, `Mode: ${writePath.mode} — ${writePathLabels[writePath.mode] || writePath.mode}`);
+  line(
+    writePath.prepareWrite ? ok : warn,
+    `prepare-write (MCP): ${writePath.prepareWrite ? 'yes' : 'no'}`
+  );
+  line(
+    writePath.autoPatch ? ok : warn,
+    `autoPatch surface: ${writePath.autoPatch ? 'yes' : 'no'}`
+  );
+  if (writePath.gap) {
+    line(writePath.gap.severity === 'warn' ? warn : warn, writePath.gap.message);
+    if (writePath.gap.fix) {
+      line(' ', color.dim(`Fix: ${writePath.gap.fix}`));
+      actions.push(writePath.gap.fix);
+    }
+  }
+
   console.log('');
   console.log(color.bold('Gates & skills'));
   if (gatesMissing.length === 0) line(ok, 'Gate files present (AGENTS.md, .mcp.json, CI, write gate)');