arkgate 2.11.0 → 2.13.0

package/bin/ark.mjs

@@ -19,10 +19,37 @@ import {
   resolveOperatingMode,
 } from './ark-shared.mjs';
 import { pinArkgateDevDependency, FALSE_GREEN_GAP_ID } from './lib/field-install.mjs';
+import { validateHardWriteRequest } from './lib/enforcement-profiles.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const arkCheck = path.join(here, 'ark-check.mjs');
 
+/**
+ * Day-zero architecture picture: freeze origin under `.ark/reports/` as soon as
+ * `ark.config.json` exists — **before** agent docs, skills, CI templates, or cleanups.
+ * Idempotent: origin is written only once (`--report` archive semantics).
+ */
+function freezeDayZeroOrigin(root) {
+  const configPath = path.join(root, 'ark.config.json');
+  if (!fs.existsSync(configPath)) {
+    console.log(
+      `  Skip origin freeze — no ark.config.json yet. After init: ${arkCommand(root, 'ark-check', '--report ark-report.html')}`
+    );
+    return;
+  }
+  const originJson = path.join(root, '.ark', 'reports', 'origin.json');
+  const already = fs.existsSync(originJson);
+  console.log(
+    already
+      ? 'Architecture origin already frozen (.ark/reports/origin.*) — leaving it untouched.'
+      : 'Freezing day-zero architecture picture (origin) before agent docs / gates…'
+  );
+  runArkCheck(
+    ['--root', root, '--config', 'ark.config.json', '--report', 'ark-report.html'],
+    { cwd: root }
+  );
+}
+
 function parseArgs(argv) {
   const args = {
     command: undefined,
@@ -31,6 +58,7 @@ function parseArgs(argv) {
     force: false,
     strict: true,
     install: true,
+    requireWriteHook: undefined,
     help: false,
     version: false,
   };
@@ -55,6 +83,9 @@ function parseArgs(argv) {
     else if (arg === '--preset') args.preset = 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') {
+      args.requireWriteHook = requireValue(arg, i++).trim().toLowerCase();
+    }
     else if (arg === '--help' || arg === '-h' || arg === 'help') args.help = true;
     else if (arg === '--version' || arg === '-V') args.version = true;
     else if (!arg.startsWith('-') && args.command === undefined) args.command = arg;
@@ -66,9 +97,9 @@ function parseArgs(argv) {
 
 function usage() {
   return `Usage:
-  ark start   [--root <project>] [--yes]
+  ark start   [--root <project>] [--tools <list>] [--require-write-hook <host>] [--yes]
   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>] [--yes] [--force] [--no-strict]
+              [--archetype <playbook-id>] [--tools <list>] [--require-write-hook <host>] [--yes] [--force] [--no-strict]
   ark upgrade [--root <project>] [--no-install] [--no-strict]
 
 Commands:
@@ -93,6 +124,9 @@ Options:
                vertical-slice-product, ddd-bounded-contexts.
   --tools      Comma-separated agents to gate (claude,cursor,codex,grok,windsurf,cline,copilot,kiro,roo,continue,gemini).
                Omit to auto-detect from each tool's config dir, falling back to claude+cursor+codex+grok.
+  --require-write-hook <host>
+               Require and verify a hard local write hook for Claude or Grok. Cursor/Codex are
+               advisory-write plus hard CI merge only; impossible requests fail before any write.
 
 Interactive mode (TTY, no --yes): asks what application shape you are building and maps it to a preset.
 Non-interactive (no TTY): uses the same defaults as --yes — never calls readline on a null interface.
@@ -177,7 +211,7 @@ async function upgrade(args) {
   }
   console.log('\n4/4  Verifying architecture…');
   return runArkCheck(
-    ['--root', root, '--config', 'ark.config.json', '--strict-config'],
+    ['--root', root, '--config', 'ark.config.json', '--strict-merge'],
     { cwd: root }
   );
 }
@@ -330,11 +364,18 @@ async function init(args) {
       console.log('Skipped ark.config.json generation.');
     }
 
+    // Origin first: contract-on-tree picture before AGENTS.md / skills / CI templates.
+    console.log('');
+    freezeDayZeroOrigin(root);
+
     const installGates =
       nonInteractive || (await askYesNo(rl, 'Configure agent and CI gate templates?', true));
     if (installGates) {
       const gateArgs = ['--root', root, '--install-agent-gates'];
       if (args.tools) gateArgs.push('--tools', args.tools);
+      if (args.requireWriteHook) {
+        gateArgs.push('--require-write-hook', args.requireWriteHook);
+      }
       if (args.force) gateArgs.push('--force');
       const status = runArkCheck(gateArgs, { cwd: root });
       if (status !== 0) return status;
@@ -344,20 +385,21 @@ async function init(args) {
       args.strict &&
       (nonInteractive || (await askYesNo(rl, 'Run strict architecture check now?', true)));
     if (runStrict) {
-      return runArkCheck(
-        ['--root', root, '--config', 'ark.config.json', '--strict-config'],
-        { cwd: root }
-      );
+      const strictArgs = ['--root', root, '--config', 'ark.config.json', '--strict-merge'];
+      if (args.requireWriteHook) {
+        strictArgs.push('--require-write-hook', args.requireWriteHook);
+      }
+      return runArkCheck(strictArgs, { cwd: root });
     }
 
     console.log(
-      `Ark init complete. Run \`${arkCommand(root, 'ark-check', '--root . --config ark.config.json --strict-config')}\` before merging.`
+      `Ark init complete. Run \`${arkCommand(root, 'ark-check', '--root . --config ark.config.json --strict-merge')}\` before merging.`
     );
     if (archetype) {
       console.log(`Shape: ${archetype}. Plan: ${arkCommand(root, 'ark-check', '--recommend')}`);
     }
     console.log(
-      `Freeze day-one architecture snapshot: ${arkCommand(root, 'ark-check', '--report ark-report.html')} (writes .ark/reports/origin.* once).`
+      `Day-zero origin: .ark/reports/origin.* (frozen once; later --report shows evolution vs origin).`
     );
     console.log(`Adoption health: ${arkCommand(root, 'ark-check', '--doctor')}`);
     return 0;
@@ -381,9 +423,11 @@ async function start(args) {
   try {
     console.log("Let's set up Ark for your project.");
     console.log(
-      "I'll look at your code, suggest a shape, set up the guardrails, and show you a plan."
+      "I'll walk the tree, freeze a day-zero architecture picture, then set up guardrails and show a plan."
+    );
+    console.log(
+      'Nothing in your product code is changed — only Ark config, then origin snapshot, then agent/CI templates.'
     );
-    console.log('Nothing in your code is changed — this only adds Ark configuration.');
     if (nonInteractive && !args.yes) {
       console.log(
         'Non-interactive session (no TTY) — using guided defaults (same as --yes). Pass flags to override.'
@@ -440,10 +484,10 @@ async function start(args) {
       console.log('  Skipping arkgate package pin (--no-install).');
     }
 
-    // 3) Set up config + gates. Greenfield → the shape's preset; an established repo → detection,
-    // so the contract anchors to the directories you already have instead of aspirational globs.
+    // 3) Contract first (config only). Greenfield → shape preset; established repo → detection,
+    // so the contract anchors to directories you already have instead of aspirational globs.
     console.log('');
-    console.log('Setting up Ark…');
+    console.log('Setting up Ark contract…');
     const configPath = path.join(root, 'ark.config.json');
     if (!fs.existsSync(configPath)) {
       const initArgs = ['--root', root, '--init'];
@@ -482,14 +526,27 @@ async function start(args) {
     } else {
       console.log('  Found an existing ark.config.json — keeping it.');
     }
+
+    // 4) Day-zero origin — freeze the architecture picture *before* agent docs / CI / skills.
+    // Later --report runs show evolution vs this snapshot. Idempotent (origin once).
+    console.log('');
+    freezeDayZeroOrigin(root);
+
+    // 5) Agent + CI gate templates (docs, hooks, skills) — after origin is frozen.
+    console.log('');
+    console.log('Installing agent and CI gate templates…');
     {
       const gateArgs = ['--root', root, '--install-agent-gates'];
       if (args.tools) gateArgs.push('--tools', args.tools);
+      if (args.requireWriteHook) {
+        gateArgs.push('--require-write-hook', args.requireWriteHook);
+      }
       if (args.force) gateArgs.push('--force');
-      runArkCheck(gateArgs, { cwd: root });
+      const status = runArkCheck(gateArgs, { cwd: root });
+      if (status !== 0) return status;
     }
 
-    // 4) Show the plan: what's safe to auto-fix vs what needs a decision.
+    // 6) Show the plan: what's safe to auto-fix vs what needs a decision.
     console.log('');
     console.log('Your architecture plan:');
     runArkCheck(['--root', root, '--config', 'ark.config.json', '--plan'], { cwd: root });
@@ -571,7 +628,7 @@ async function start(args) {
       planOk = false;
     }
 
-    // 5) Plain-language wrap-up — one next step, status light only.
+    // 7) Plain-language wrap-up — one next step, status light only.
     // Modes are detected (Suggest/Adapt/Enforce), not user-picked settings.
     // Soft-block false-green using the same doctor adoption gap (no second detector).
     let falseGreenGap = null;
@@ -620,26 +677,18 @@ async function start(args) {
       console.log('     → reclassify I/O dirs out of Application; then /ark-autopilot for residual debt.');
     } else {
       console.log('  1. In your agent:  /ark-autopilot');
-      console.log('     → origin report, adoption, plan, safe fixes, leave gates on.');
+      console.log('     → explore first, dual plan (remediation + pattern bets), safe fixes, leave gates on.');
     }
     console.log(`  2. Status anytime: ${arkCommand(root, 'ark-check', '--doctor')}`);
-    console.log(`  3. After edits:    ${arkCommand(root, 'ark-check', '--root . --config ark.config.json --strict-config')}`);
+    console.log(`  3. After edits:    ${arkCommand(root, 'ark-check', '--root . --config ark.config.json --strict-merge')}`);
     if (mode === 'adapt' && planOk && !falseGreenGap) {
       console.log(
         `  4. When green but cores still optional: ${arkCommand(root, 'ark-check', '--ratchet-cores')} → honest ENFORCE`
       );
     }
     console.log('');
-    console.log('Optional later: --plan · --coverage · /ark-fix · /ark-place · ark upgrade');
-
-    // 6) First architecture report — freezes an origin snapshot under .ark/reports/
-    // so later --report runs can show evolution. Idempotent: origin is written only once.
-    console.log('');
-    console.log('Capturing architecture report (origin snapshot on first run)…');
-    runArkCheck(
-      ['--root', root, '--config', 'ark.config.json', '--report', 'ark-report.html'],
-      { cwd: root }
-    );
+    console.log('Day-zero origin is under .ark/reports/origin.* — re-run --report later for evolution.');
+    console.log('Optional later: --plan · --coverage · /ark-explore · /ark-fix · /ark-place · ark upgrade');
     return 0;
   } finally {
     rl?.close();
@@ -663,6 +712,25 @@ async function main() {
     return 0;
   }
 
+  if (args.requireWriteHook && !['start', 'init'].includes(args.command)) {
+    console.error('--require-write-hook is supported by ark start and ark init.');
+    return 2;
+  }
+  const enforcement = validateHardWriteRequest({
+    root: args.root,
+    host: args.requireWriteHook,
+    tools: args.tools,
+    force: args.force,
+  });
+  if (!enforcement.ok) {
+    console.error(enforcement.error);
+    return 2;
+  }
+  if (enforcement.host) {
+    args.requireWriteHook = enforcement.host;
+    if (!args.tools) args.tools = enforcement.tools.join(',');
+  }
+
   if (args.command === 'start') {
     try {
       return await start(args);