arkgate 3.0.4 → 3.1.0

package/bin/ark-mcp.mjs

@@ -18,6 +18,9 @@
  *                                 discarded if post-patch still invalid.
  *   - tool      ark_prepare_write — W2: place + constrain + validate + autoPatch + judgmentBrief
  *                                 + contentHash (composes ark_place + write gate; not a second contract).
+ *   - tool      ark_prepare_change — atomically preflights a create/update/delete batch without writes.
+ *   - tool      ark_policy_delta — classifies a base/candidate ark.config.json transition and
+ *                                 rejects weakening without an exact hash-bound acknowledgement.
  *   - tool      ark_recommend   — deterministic application-shape plan (same as
  *                                 ark-check --recommend --json)
  *
@@ -61,6 +64,8 @@ import { composePrepareWrite } from './lib/prepare-write.mjs';
 import { loadArkConfigContract } from './lib/config-contract.mjs';
 import { ARK_ANALYSIS_RESULT_SCHEMA, createAdapterResult } from './lib/adapter-contract.mjs';
 import { loadGoldenPattern, attachGoldenToPlacement } from './lib/golden-pattern.mjs';
+import { prepareChangeFromRoot } from './lib/prepare-change.mjs';
+import { detectWritePathCapabilities } from './lib/write-path-detect.mjs';
 
 const arkCheckBin = fileURLToPath(new URL('./ark-check.mjs', import.meta.url));
 
@@ -201,17 +206,23 @@ function applyCodexUpdatePatch(current, lines) {
   let source = current.split('\n');
   let cursor = 0;
   const hunks = [];
-  let hunk = [];
+  let hunk = null;
   for (const line of lines) {
     if (line.startsWith('@@')) {
-      if (hunk.length > 0) hunks.push(hunk);
-      hunk = [];
+      if (hunk) hunks.push(hunk);
+      hunk = { anchor: line.slice(2).trim(), entries: [] };
     } else if (/^[ +\-]/.test(line)) {
-      hunk.push(line);
+      if (!hunk) return null;
+      hunk.entries.push(line);
     }
   }
-  if (hunk.length > 0) hunks.push(hunk);
-  for (const entries of hunks) {
+  if (hunk) hunks.push(hunk);
+  for (const { anchor, entries } of hunks) {
+    if (anchor) {
+      const anchorAt = source.findIndex((line, index) => index >= cursor && line === anchor);
+      if (anchorAt < 0) return null;
+      cursor = anchorAt + 1;
+    }
     const oldLines = entries.filter((line) => !line.startsWith('+')).map((line) => line.slice(1));
     const newLines = entries.filter((line) => !line.startsWith('-')).map((line) => line.slice(1));
     let found = -1;
@@ -229,36 +240,94 @@ function applyCodexUpdatePatch(current, lines) {
 }
 
 function codexPatchWrites(patch, root) {
-  if (typeof patch !== 'string' || !patch.includes('*** Begin Patch')) return [];
+  if (typeof patch !== 'string') {
+    return { writes: [], complete: false };
+  }
   const lines = patch.split('\n');
+  const begin = lines.indexOf('*** Begin Patch');
+  const end = lines.indexOf('*** End Patch', begin + 1);
+  if (begin < 0 || end <= begin) return { writes: [], complete: false };
   const writes = [];
-  for (let index = 0; index < lines.length; index += 1) {
+  const seenPaths = new Set();
+  let complete = [
+    ...lines.slice(0, begin),
+    ...lines.slice(end + 1),
+  ].every((line) => line.trim() === '');
+  let sawFileDirective = false;
+  for (let index = begin + 1; index < end; index += 1) {
     const match = lines[index].match(/^\*\*\* (Add|Update|Delete) File: (.+)$/);
-    if (!match) continue;
+    if (!match) {
+      if (lines[index].trim() !== '') complete = false;
+      continue;
+    }
+    sawFileDirective = true;
     const [, action, relativePath] = match;
     const body = [];
-    for (index += 1; index < lines.length && !lines[index].startsWith('*** '); index += 1) {
+    for (index += 1; index < end && !lines[index].startsWith('*** '); index += 1) {
       body.push(lines[index]);
     }
     index -= 1;
-    if (action === 'Delete') continue;
     const filePath = path.resolve(root, relativePath);
+    const rel = path.relative(root, filePath);
+    if (
+      seenPaths.has(filePath) ||
+      rel.startsWith(`..${path.sep}`) ||
+      rel === '..' ||
+      path.isAbsolute(rel)
+    ) {
+      complete = false;
+      continue;
+    }
+    seenPaths.add(filePath);
+    if (action === 'Delete') {
+      if (body.some((line) => line.trim() !== '') || !fs.existsSync(filePath)) {
+        complete = false;
+        continue;
+      }
+      writes.push({ path: relativePath, delete: true });
+      continue;
+    }
     let content;
     if (action === 'Add') {
+      if (
+        body.length === 0 ||
+        fs.existsSync(filePath) ||
+        body.some((line) => !line.startsWith('+'))
+      ) {
+        complete = false;
+        continue;
+      }
       content = body.filter((line) => line.startsWith('+')).map((line) => line.slice(1)).join('\n');
       if (body.some((line) => line.startsWith('+'))) content += '\n';
     } else {
+      if (
+        !body.some((line) => line.startsWith('@@')) ||
+        body.some((line) => !line.startsWith('@@') && !/^[ +\-]/.test(line))
+      ) {
+        complete = false;
+        continue;
+      }
       let current;
       try {
         current = fs.readFileSync(filePath, 'utf8');
       } catch {
+        complete = false;
         continue;
       }
       content = applyCodexUpdatePatch(current, body);
+      if (content === null) complete = false;
     }
-    if (typeof content === 'string') writes.push({ filePath, content });
+    if (typeof content === 'string') writes.push({ path: relativePath, filePath, content });
   }
-  return writes;
+  return { writes, complete: complete && sawFileDirective };
+}
+
+function hookEnforcement(root, host, operation, completePatch = false) {
+  return detectWritePathCapabilities(root, host, {
+    boundary: 'pre-tool',
+    operation,
+    completePatch,
+  }).enforcementLadder;
 }
 
 /**
@@ -308,22 +377,75 @@ function runHook(gate, config, args, ts) {
   runHookPayload(payload, gate, config, args, ts);
 }
 
-function runHookPayload(payload, gate, config, args, ts) {
+function runHookPayload(payload, gate, config, args, ts, attemptContext) {
   const { toolName, toolInput, grokStyle } = normalizeHookPayload(payload);
   if (toolName === 'ApplyPatch') {
     const patch = toolInput.patch ?? toolInput.input ?? toolInput.content;
-    for (const write of codexPatchWrites(patch, args.root)) {
-      runHookPayload(
-        {
-          tool_name: 'Write',
-          tool_input: { file_path: write.filePath, content: write.content },
-        },
-        gate,
+    const parsedPatch = codexPatchWrites(patch, args.root);
+    // Codex ApplyPatch is only preflighted when Ark can reconstruct every file operation.
+    // An incomplete reconstruction must not be mislabeled as atomic or hard enforcement.
+    if (!parsedPatch.complete) return;
+    const patchWrites = parsedPatch.writes;
+    const governedWrites = patchWrites.filter((change) => {
+      const relative = String(change.path).replace(/\\/g, '/');
+      if (!SOURCE_FILE.test(relative) || relative.endsWith('.d.ts')) return false;
+      return Boolean(inferLayer(path.resolve(args.root, relative), config, args.root));
+    });
+    const changes = governedWrites.map(({ path: relativePath, content, delete: deleted }) =>
+      deleted ? { path: relativePath, delete: true } : { path: relativePath, content }
+    );
+    if (changes.length === 0) return;
+    let result;
+    try {
+      result = prepareChangeFromRoot({
+        root: args.root,
         config,
-        args,
-        ts
+        configSource: path.isAbsolute(args.config)
+          ? args.config
+          : path.join(args.root, args.config),
+        changes,
+      });
+    } catch {
+      return;
+    }
+    if (result.valid) {
+      for (const write of governedWrites) {
+        if (typeof write.content !== 'string') continue;
+        runHookPayload(
+          {
+            tool_name: 'Write',
+            tool_input: { file_path: write.filePath, content: write.content },
+          },
+          gate,
+          config,
+          args,
+          ts,
+          { host: 'codex', operation: 'apply_patch', completePatch: true }
+        );
+      }
+      return;
+    }
+    const message = [
+      `Ark architecture gate blocked this complete ${toolName} (${changes.length} governed file(s)):`,
+      ...result.diagnostics.map(
+        (diagnostic) =>
+          `- [${diagnostic.ruleId}] ${diagnostic.message}\n  Next action: ${diagnostic.nextAction}`
+      ),
+      'No project file was written. Fix the complete patch and retry.',
+    ].join('\n');
+    process.stderr.write(`${message}\n`);
+    if (args.hookRepair) {
+      process.stderr.write(
+        `ARK_REPAIR_JSON:${JSON.stringify({
+          ...result,
+          mode: 'repair',
+          decision: 'deny',
+          enforcement: hookEnforcement(args.root, 'codex', 'apply_patch', true),
+          autoPatch: null,
+        })}\n`
       );
     }
+    process.exitCode = 2;
     return;
   }
   const filePath = toolInput.file_path;
@@ -392,9 +514,9 @@ function runHookPayload(payload, gate, config, args, ts) {
     violations: newViolations.map((violation) => ({ ...violation, file: normalizedRel })),
   });
 
-  const lines = newViolations.map(
-    (violation) =>
-      `- [${violation.ruleId}] ${violation.message}${violation.line ? ` (line ${violation.line})` : ''}`
+  const lines = adapterResult.diagnostics.map(
+    (diagnostic) =>
+      `- [${diagnostic.ruleId}] ${diagnostic.message}${diagnostic.location.line ? ` (line ${diagnostic.location.line})` : ''}\n  Next action: ${diagnostic.nextAction}`
   );
   // Surface the per-violation fix hints (the gate carries them in `suggestion`,
   // but the hook was dropping them). Dedupe so two infra violations sharing one
@@ -436,6 +558,13 @@ function runHookPayload(payload, gate, config, args, ts) {
       mode: 'repair',
       decision: 'deny',
       filePath: normalizedRel,
+      enforcement: hookEnforcement(
+        args.root,
+        attemptContext?.host ?? (grokStyle ? 'grok' : 'claude'),
+        attemptContext?.operation ??
+          (grokStyle ? (toolName === 'Edit' ? 'search_replace' : 'write') : toolName),
+        Boolean(attemptContext?.completePatch)
+      ),
       ...(layer ? { layer } : {}),
       ...(autoPatch
         ? {
@@ -736,6 +865,34 @@ async function main() {
       },
       outputSchema: ARK_ANALYSIS_RESULT_SCHEMA,
     },
+    {
+      name: 'ark_policy_delta',
+      description:
+        'Classify a complete ark.config.json transition as strengthening, neutral, ' +
+        'judgment-required, or weakening. Pass the previous baseConfig and optional ' +
+        'candidateConfig (defaults to this project contract). Weakening and judgment-required ' +
+        'results set isError unless acknowledgement exactly matches both policy hashes and all ' +
+        'blocking finding ids. Read-only; never edits the contract.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          baseConfig: {
+            type: 'object',
+            description: 'Previous complete ark.config.json object.',
+          },
+          candidateConfig: {
+            type: 'object',
+            description: 'Candidate complete config; defaults to the current project contract.',
+          },
+          acknowledgement: {
+            type: 'object',
+            description:
+              'Optional schemaVersion/basePolicyHash/candidatePolicyHash/findingIds/reason object.',
+          },
+        },
+        required: ['baseConfig'],
+      },
+    },
     {
       name: 'ark_coverage',
       description:
@@ -797,6 +954,38 @@ async function main() {
         required: ['source'],
       },
     },
+    {
+      name: 'ark_prepare_change',
+      description:
+        'Validate one complete governed-source create/update/delete batch as an atomic in-memory candidate. ' +
+        'Catches cross-file forbidden edges and cycles before any host write, and returns ' +
+        'per-file content hashes plus base/candidate tree and policy hashes. Never writes files.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          changes: {
+            type: 'array',
+            description:
+              'Full candidate batch. Each item is {path, content} for create/update or {path, delete:true}.',
+            items: {
+              type: 'object',
+              properties: {
+                path: { type: 'string' },
+                content: { type: 'string' },
+                delete: { type: 'boolean' },
+              },
+              required: ['path'],
+            },
+          },
+          changeMap: {
+            type: 'object',
+            description:
+              'Optional strict schema 1.0 architecture change map. Omit it to use ordinary atomic preflight.',
+          },
+        },
+        required: ['changes'],
+      },
+    },
     {
       name: 'ark_recommend',
       description:
@@ -993,6 +1182,33 @@ async function main() {
     return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }], isError: false };
   }
 
+  function runPolicyDeltaTool(params) {
+    const baseConfig = params?.arguments?.baseConfig;
+    if (!baseConfig || typeof baseConfig !== 'object' || Array.isArray(baseConfig)) {
+      return {
+        content: [{ type: 'text', text: 'ark_policy_delta requires baseConfig (object).' }],
+        isError: true,
+      };
+    }
+    try {
+      const result = ark.analyzePolicyDelta({
+        baseConfig,
+        candidateConfig: params?.arguments?.candidateConfig ?? config,
+        acknowledgement: params?.arguments?.acknowledgement,
+      });
+      return {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        structuredContent: result,
+        isError: !result.valid,
+      };
+    } catch (error) {
+      return {
+        content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }],
+        isError: true,
+      };
+    }
+  }
+
   function runRecommendTool() {
     const { data, raw } = runArkCheckJson(['--recommend']);
     if (!data) {
@@ -1153,6 +1369,29 @@ async function main() {
     };
   }
 
+  function runPrepareChange(params) {
+    try {
+      const result = prepareChangeFromRoot({
+        root: args.root,
+        config,
+        configSource: configPath,
+        changes: params?.arguments?.changes,
+        changeMap: params?.arguments?.changeMap,
+        changeMapSource: 'ark_prepare_change.changeMap',
+      });
+      return {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        structuredContent: result,
+        isError: !result.valid,
+      };
+    } catch (error) {
+      return {
+        content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }],
+        isError: true,
+      };
+    }
+  }
+
   function runSuggestIncludeTool() {
     try {
       const workspaces = detectWorkspaces(args.root);
@@ -1193,9 +1432,11 @@ async function main() {
   const TOOL_HANDLERS = {
     validate_code: runValidate,
     ark_check: runCheckTool,
+    ark_policy_delta: runPolicyDeltaTool,
     ark_coverage: runCoverageTool,
     ark_place: runPlace,
     ark_prepare_write: runPrepareWrite,
+    ark_prepare_change: runPrepareChange,
     ark_recommend: runRecommendTool,
     ark_suggest_include: runSuggestIncludeTool,
   };

package/bin/ark.mjs

@@ -22,6 +22,13 @@ import { pinArkgateDevDependency, FALSE_GREEN_GAP_ID } from './lib/field-install
 import { validateHardWriteRequest } from './lib/enforcement-profiles.mjs';
 import { applyStartPreview, planStart, renderStartPreview } from './lib/start-preview.mjs';
 import { detectActiveAgentHost } from './lib/skill-install.mjs';
+import { loadArkConfigContract } from './lib/config-contract.mjs';
+import {
+  prepareChangeFromRoot,
+  readChangeMapFile,
+  readChangeSetFile,
+  renderChangePreflight,
+} from './lib/prepare-change.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const arkCheck = path.join(here, 'ark-check.mjs');
@@ -56,6 +63,7 @@ function parseArgs(argv) {
   const args = {
     command: undefined,
     root: process.cwd(),
+    config: 'ark.config.json',
     yes: false,
     force: false,
     strict: true,
@@ -101,6 +109,9 @@ function parseArgs(argv) {
     else if (arg === '--skip-package-manager') args.skipPackageManager = true;
     else if (arg === '--remove-host') args.removeHost = requireValue(arg, i++).trim().toLowerCase();
     else if (arg === '--preset') args.preset = requireValue(arg, i++);
+    else if (arg === '--config') args.config = requireValue(arg, i++);
+    else if (arg === '--changes') args.changes = requireValue(arg, i++);
+    else if (arg === '--change-map') args.changeMap = requireValue(arg, i++);
     else if (arg === '--archetype') args.archetype = requireValue(arg, i++);
     else if (arg === '--tools') args.tools = requireValue(arg, i++);
     else if (arg === '--require-write-hook') {
@@ -121,6 +132,7 @@ function usage() {
   ark init    [--root <project>] [--preset hexagonal|layered|feature-sliced|monorepo|ui-surface|vertical-slice|ddd-bounded-contexts|clean-architecture|onion-architecture]
               [--archetype <playbook-id>] [--tools <list>] [--require-write-hook <host>] [--yes] [--force] [--no-strict]
   ark upgrade [--root <project>] [--no-install] [--no-strict]
+  ark preflight --changes <change-set.json> [--change-map <map.json>] [--root <project>] [--config ark.config.json] [--json]
 
 Commands:
   start     New here? Analyze and preview the complete setup. Read-only unless --apply.
@@ -128,6 +140,7 @@ Commands:
   upgrade   One command to update Ark: bump the package to @latest, refresh gate
             templates + /ark-* skills (and Codex home prompts), migrate command
             runners to this project's package manager, then run the strict check.
+  preflight Validate one atomic create/update/delete set without writing project files.
             (alias: ark update)
 
 Options:
@@ -213,9 +226,9 @@ async function upgrade(args) {
   let status = runArkCheck(['--root', root, '--install-agent-gates'], { cwd: root });
   if (status !== 0) return status;
 
-  // Codex loads slash-command prompts from $CODEX_HOME/prompts, not the repo — refresh those
-  // when a Codex home exists. --force rewrites temp/upgrade MCP roots to this project + arkgate-mcp.
-  // Non-fatal: a permission error (e.g. sandbox) shouldn't fail the whole upgrade.
+  // Codex home skill catalog is $CODEX_HOME/skills/<name>/SKILL.md (repo uses .agents/skills/).
+  // Refresh home when a Codex home exists. --force rewrites temp/upgrade MCP roots to this
+  // project + arkgate-mcp. Non-fatal: a permission error (e.g. sandbox) shouldn't fail upgrade.
   const codexHomeBase = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
   if (fs.existsSync(codexHomeBase)) {
     console.log(`\n     Refreshing Codex home (${codexHomeBase})…`);
@@ -775,6 +788,13 @@ async function main() {
     console.error('--require-write-hook is supported by ark start and ark init.');
     return 2;
   }
+  if (
+    args.command !== 'preflight' &&
+    (args.changes || args.changeMap || args.config !== 'ark.config.json')
+  ) {
+    console.error('--changes, --change-map, and --config are supported by ark preflight.');
+    return 2;
+  }
   const enforcement = validateHardWriteRequest({
     root: args.root,
     host: args.requireWriteHook,
@@ -817,6 +837,33 @@ async function main() {
     }
   }
 
+  if (args.command === 'preflight') {
+    try {
+      if (!args.changes) throw new Error('ark preflight requires --changes <change-set.json>.');
+      const configPath = path.isAbsolute(args.config)
+        ? args.config
+        : path.join(args.root, args.config);
+      const config = loadArkConfigContract(
+        JSON.parse(fs.readFileSync(configPath, 'utf8')),
+        configPath
+      ).config;
+      const changeMap = args.changeMap ? readChangeMapFile(args.root, args.changeMap) : undefined;
+      const result = prepareChangeFromRoot({
+        root: args.root,
+        config,
+        configSource: configPath,
+        changes: readChangeSetFile(args.root, args.changes),
+        ...(changeMap ? { changeMap: changeMap.input, changeMapSource: changeMap.source } : {}),
+      });
+      if (args.json) console.log(JSON.stringify(result, null, 2));
+      else renderChangePreflight(result);
+      return result.valid ? 0 : 1;
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      return 2;
+    }
+  }
+
   console.error(`Unknown command: ${args.command}`);
   console.error(usage());
   return 2;

package/bin/lib/adapter-contract.mjs

@@ -8,13 +8,37 @@
  * Pure CLI helper (bin/lib/adapter-contract.mjs). Zero Node I/O.
  */
 
-export const ARK_ANALYSIS_RESULT_SCHEMA_VERSION = '1.0';
+export const ARK_ANALYSIS_RESULT_SCHEMA_VERSION = '1.1';
 function text(value) {
     return typeof value === 'string' && value.length > 0 ? value : undefined;
 }
 function positiveInteger(value, fallback) {
     return Number.isInteger(value) && Number(value) > 0 ? Number(value) : fallback;
 }
+function nextActionForDiagnostic(ruleId, evidence, violation) {
+    if (ruleId === 'LAYER_IMPORT_VIOLATION') {
+        if (evidence.typeOnly ||
+            violation.targetTypeOnlyExports === true ||
+            violation.namedBindingsTypeOnly === true) {
+            return 'Move the referenced type to a mutually allowed layer, use `import type`, then preflight again.';
+        }
+        if (violation.peerIsolation === true) {
+            return 'Extract the shared dependency to a shared layer, then preflight again.';
+        }
+        return `Define a port in ${evidence.fromLayer ?? 'the source layer'}, inject the ${evidence.toLayer ?? 'outer-layer'} implementation, then preflight again.`;
+    }
+    if (ruleId === 'FORBIDDEN_GLOBAL') {
+        return `Inject ${evidence.target ?? 'the capability'} through a port, then preflight again.`;
+    }
+    if (ruleId === 'CIRCULAR_DEPENDENCY') {
+        return 'Extract the shared dependency into a third module, then preflight again.';
+    }
+    if (ruleId === 'RAW_EVENT_PUBLISH')
+        return 'Publish through a registered intent creator, then run Ark again.';
+    if (ruleId === 'PUBLISH_MISSING_SOURCE')
+        return 'Add metadata.source to the publish call, then run Ark again.';
+    return `Resolve ${ruleId} without weakening ark.config.json, then run Ark again.`;
+}
 export function toAdapterDiagnostic(violation, fallbackSeverity = 'error') {
     const ruleId = text(violation.ruleId) ?? text(violation.code) ?? 'ARK_UNKNOWN';
     const severity = violation.severity === 'warning' ? 'warning' : fallbackSeverity;
@@ -34,6 +58,7 @@ export function toAdapterDiagnostic(violation, fallbackSeverity = 'error') {
             column: positiveInteger(violation.column, 1),
         },
         evidence,
+        nextAction: text(violation.nextAction) ?? nextActionForDiagnostic(ruleId, evidence, violation),
     };
 }
 export function createAdapterResult(input) {
@@ -86,6 +111,7 @@ export const ARK_ANALYSIS_RESULT_SCHEMA = {
                             typeOnly: { type: 'boolean' },
                         },
                     },
+                    nextAction: { type: 'string', minLength: 1 },
                 },
             },
         },

package/bin/lib/agent-gates.mjs

@@ -10,6 +10,7 @@ export {
   codexPrimaryTable,
   codexProjectSlug,
   codexPromptsDir,
+  codexSkillsDir,
   codexScopedTableForRoot,
   extractCodexArkRootFromToml,
   extractCodexRootFromBlock,
@@ -77,6 +78,7 @@ export {
   normalizeToolsList,
   resolveTools,
   KNOWN_TOOLS,
+  SKILL_TOOL_TARGETS,
   detectActiveAgentHost,
   codexConcernIsActive,
   arkPackageVersion,
@@ -86,7 +88,13 @@ export {
   skillTemplates,
   skillTemplateNames,
   detectCodexHomeGap,
+  detectCodexRepoSkillGap,
+  assessCodexSkillParity,
+  assessSkillCatalogParity,
   detectSkillGaps,
+  agentsMdSkillRefs,
+  verifyHostSkillCatalog,
+  printSkillAndCodexGapHints,
 } from './skill-install.mjs';
 
 export { detectDeployPathQuality } from './deploy-path.mjs';
@@ -101,6 +109,7 @@ export {
 export {
   detectPreCommitArk,
   detectCiEnforcement,
+  classifyArkCheckFlags,
   detectConfigGateDrift,
   jobIdsThatRunArkCheck,
   isArkRequiredStatusCheck,