arkgate 4.6.0 → 4.6.2

package/bin/ark-mcp-runtime.mjs

@@ -73,6 +73,8 @@ import {
 } from './lib/prepare-change.mjs';
 import { detectWritePathCapabilities } from './lib/write-path-detect.mjs';
 import { collectGovernedFiles, isGovernableSourceFile } from './lib/scan-files.mjs';
+import { classifyChangeSet, evaluateTeamGate } from './lib/team-parliament.mjs';
+import { contractSessionFrom } from './lib/team-parliament-io.mjs';
 import {
   canonicalizeCandidateChanges,
   resolvedCompilerInputPaths,
@@ -641,6 +643,25 @@ function emitHostAllow(output, { antigravityStyle, cursorStyle }) {
   emitCursorAllow(output, cursorStyle);
 }
 
+/**
+ * Socket-style write-gate deny: two lines first. Pass/fail, no score.
+ * Rule id stays on a following line, not the first sentence.
+ */
+function formatWriteGateDeny({ file, reason, ruleId, nextAction, extraLines = [] }) {
+  const target = file || 'this write';
+  const why = String(reason || 'this change breaks the architecture layers').replace(/\s+/g, ' ').trim();
+  const next =
+    nextAction && /place|move|import|port/i.test(nextAction)
+      ? nextAction
+      : 'Move the import or run /ark-place. Do not weaken ark.config.json.';
+  const lines = [`blocked ${target} — ${why}`, `Next: ${next}`];
+  if (ruleId) lines.push(`[${ruleId}]`);
+  for (const extra of extraLines) {
+    if (extra) lines.push(extra);
+  }
+  return lines.join('\n');
+}
+
 function runHookPayload(payload, gate, config, args, ts, attemptContext, output = processHookOutput()) {
   const { toolName, toolInput, grokStyle, antigravityStyle, cursorStyle, operation } =
     normalizeHookPayload(
@@ -657,6 +678,20 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
       return;
     }
     const patchWrites = parsedPatch.writes;
+    const patchChangeSet = classifyChangeSet(patchWrites.map((change) => String(change.path)));
+    const patchLawGate = evaluateTeamGate({
+      changeSet: patchChangeSet,
+      contractSession: contractSessionFrom({}),
+    });
+    if (patchLawGate.deny && patchChangeSet.mixed) {
+      const message = patchLawGate.message;
+      output.stderr(`Ark architecture gate: ${message}\n`);
+      if (grokStyle) {
+        output.stdout(`${JSON.stringify({ decision: 'deny', reason: message })}\n`);
+      }
+      output.status(2);
+      return;
+    }
     const sourceWrites = patchWrites.filter((change) =>
       isGovernableSourceFile(path.basename(String(change.path)))
     );
@@ -780,17 +815,20 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
       emitHostAllow(output, { antigravityStyle, cursorStyle });
       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}`
-      ),
-      ...(designDelta && !designDelta.valid
-        ? formatDesignDeltaBlock(designDelta).split('\n').slice(1)
-        : []),
-      'No project file was written. Fix the complete patch and retry.',
-    ].join('\n');
+    const first = result.diagnostics[0];
+    const message = formatWriteGateDeny({
+      file: `${changes.length} file(s)`,
+      reason: first?.message || `this ${toolName} breaks the architecture layers`,
+      ruleId: first?.ruleId,
+      nextAction: first?.nextAction,
+      extraLines: [
+        ...result.diagnostics.slice(1).map((d) => `[${d.ruleId}] ${d.message}`),
+        ...(designDelta && !designDelta.valid
+          ? formatDesignDeltaBlock(designDelta).split('\n').slice(1)
+          : []),
+        'No project file was written. Fix the complete patch and retry.',
+      ],
+    });
     output.stderr(`${message}\n`);
     if (args.hookRepair) {
       output.stderr(
@@ -910,13 +948,7 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
     })),
   });
 
-  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
-  // hint — e.g. the mayImportInfrastructure escape hatch — print it once.
+  const firstDiagnostic = adapterResult.diagnostics[0];
   const suggestions = [
     ...new Set(combinedViolations.map((violation) => violation.suggestion).filter(Boolean)),
   ];
@@ -924,27 +956,34 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
   // W4: structured repair payload is opt-in (--hook-repair / ARK_HOOK_REPAIR).
   // Default remains hard block with prose only — hosts that cannot re-inject stay clean.
   const repair = Boolean(args.hookRepair);
-  const message = [
-    `Ark architecture gate blocked this write to ${rel}${layer ? ` (layer: ${layer})` : ''}:`,
-    ...lines,
-    ...(suggestions.length > 0 ? ['Fix:', ...suggestions.map((s) => `  ${s}`)] : []),
-    ...(autoPatch && repair
-      ? [
-          `autoPatch available (${autoPatch.remediationKind}, confidence ${autoPatch.confidence}): ` +
-            'apply the patched source from ARK_AUTOPATCH_JSON / ARK_REPAIR_JSON on stderr' +
-            (grokStyle ? ' (or autoPatch in the deny JSON on stdout)' : '') +
-            ' instead of re-drafting. Gate still denies this write (never silent apply).',
-        ]
-      : []),
-    ...(autoPatch && !repair
-      ? [
-          `Mechanical-safe autoPatch is available (${autoPatch.remediationKind}). ` +
-            'Enable repair payload with ARK_HOOK_REPAIR=1 or --hook-repair to receive ' +
-            'machine-readable source (still hard-blocks; host re-injects).',
-        ]
-      : []),
-    'Fix the violations and retry. Call the project-bound ark_manifest MCP tool for the architecture contract.',
-  ].join('\n');
+  const message = formatWriteGateDeny({
+    file: rel,
+    reason: firstDiagnostic?.message || (layer ? `${layer} write breaks the layers` : 'this write breaks the layers'),
+    ruleId: firstDiagnostic?.ruleId,
+    nextAction: firstDiagnostic?.nextAction,
+    extraLines: [
+      ...adapterResult.diagnostics.slice(1).map(
+        (diagnostic) =>
+          `[${diagnostic.ruleId}] ${diagnostic.message}${diagnostic.location.line ? ` (line ${diagnostic.location.line})` : ''}`
+      ),
+      ...(suggestions.length > 0 ? suggestions.map((s) => `Fix: ${s}`) : []),
+      ...(autoPatch && repair
+        ? [
+            `autoPatch available (${autoPatch.remediationKind}, confidence ${autoPatch.confidence}): ` +
+              'apply the patched source from ARK_AUTOPATCH_JSON / ARK_REPAIR_JSON on stderr' +
+              (grokStyle ? ' (or autoPatch in the deny JSON on stdout)' : '') +
+              ' instead of re-drafting. Gate still denies this write (never silent apply).',
+          ]
+        : []),
+      ...(autoPatch && !repair
+        ? [
+            `Mechanical-safe autoPatch is available (${autoPatch.remediationKind}). ` +
+              'Enable repair payload with ARK_HOOK_REPAIR=1 or --hook-repair to receive ' +
+              'machine-readable source (still hard-blocks; host re-injects).',
+          ]
+        : []),
+    ],
+  });
   output.stderr(message + '\n');
 
   if (repair) {
@@ -1387,7 +1426,7 @@ function printSessionContext(config, profile, forbiddenGlobals, args, configPath
   const governedPercent = coverage?.coverage?.governed?.percent ?? coverage?.governed?.percent;
   if (shouldShowNewHereNudge(args.root, configPath, governedPercent, false)) {
     lines.push('');
-    lines.push('New to Ark? Run /ark-architect or: ark-check --recommend');
+    lines.push('New to Ark? /ark-adopt or: arkgate-check --doctor');
   }
 
   process.stdout.write(`${lines.join('\n')}\n`);
@@ -2002,9 +2041,9 @@ export async function runArkMcp({ hookInput } = {}) {
     {
       name: 'ark_identity',
       description:
-        'Return the canonical ArkGate project, config, contract, and live MCP runtime identity. ' +
-        'Pass project.expectedRoot and/or expectedProjectId to verify this process before ' +
-        'trusting any architecture evidence.',
+        'First call. Prove this MCP process is the right project: pass project.expectedRoot ' +
+        '(exact absolute root) and reuse the returned projectId. Do this before any other Ark tool. ' +
+        'A missing, unmatched, or different root means restart the host and use the local CLI.',
       inputSchema: { type: 'object', properties: {} },
     },
     {
@@ -2047,11 +2086,10 @@ export async function runArkMcp({ hookInput } = {}) {
     {
       name: 'ark_check',
       description:
-        'Run the full Ark architecture check on the project and return structured results ' +
-        '(layer-import violations, forbidden globals, circular deps, config warnings). Use ' +
-        'this to answer "is the architecture currently valid?" instead of shelling out to ' +
-        'ark-check. Preserves legacy ok and adds identity/completeness/graph/coverage/gates/' +
-        'overall verdicts. Applies the baseline automatically when one exists. isError when not ok.',
+        'Scan the project for architecture findings (layer-import violations, forbidden globals, ' +
+        'cycles, config warnings). Returns pass/fail/incomplete plus evidence — not a yes/no ' +
+        'architecture score. Same engine as arkgate-check. Applies the baseline when one exists. ' +
+        'isError when the scan fails. Prefer after ark_identity.',
       inputSchema: {
         type: 'object',
         properties: {

package/bin/ark.mjs

@@ -35,6 +35,7 @@ import {
 } from './lib/prepare-change.mjs';
 import { runStatusCommand } from './lib/status-command.mjs';
 import { runAgentProjectionCommand } from './lib/agent-projection-command.mjs';
+import { setupUsage, setupUsageAll, upgradeUsage } from './lib/first-run-help.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const arkCheck = path.join(here, 'ark-check.mjs');
@@ -90,13 +91,14 @@ function parseArgs(argv) {
     check: false,
     stdout: false,
     help: false,
+    all: false,
     version: false,
   };
 
   const requireValue = (flag, index) => {
     const value = argv[index + 1];
     if (value === undefined || value.startsWith('-')) {
-      throw new Error(`Missing value for ${flag}. Run ark --help for usage.`);
+      throw new Error(`Missing value for ${flag}. Run arkgate --help for usage.`);
     }
     return value;
   };
@@ -138,83 +140,20 @@ function parseArgs(argv) {
     }
     else if (arg === '--expected-root') args.expectedRoot = path.resolve(requireValue(arg, i++));
     else if (arg === '--expected-project-id') args.expectedProjectId = requireValue(arg, i++);
+    else if (arg === '--vs') args.vs = requireValue(arg, i++);
     else if (arg === '--write') args.write = true;
     else if (arg === '--check') args.check = true;
     else if (arg === '--stdout') args.stdout = true;
     else if (arg === '--help' || arg === '-h' || arg === 'help') args.help = true;
+    else if (arg === '--all') args.all = true;
     else if (arg === '--version' || arg === '-V') args.version = true;
     else if (!arg.startsWith('-') && args.command === undefined) args.command = arg;
-    else throw new Error(`Unknown argument: ${arg}. Run ark --help for usage.`);
+    else throw new Error(`Unknown argument: ${arg}. Run arkgate --help for usage.`);
   }
 
   return args;
 }
 
-function usage() {
-  return `Usage:
-  ark start   [--root <project>] [--tools <host>] [--require-write-hook <host>] [--install] [--apply] [--json]
-  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>] [--tools <list>] [--apply] [--plan-digest <sha256>] [--accept-conflicts] [--refresh-skills] [--json] [--no-install] [--no-strict]
-  ark preflight --changes <change-set.json> [--change-map <map.json>] [--root <project>] [--config ark.config.json] [--manifest <manifest.json>] [--tsconfig <tsconfig.json>] [--json]
-  ark status  [--root <project>] [--config ark.config.json] [--json]
-              [--expected-root <abs>] [--expected-project-id sha256:…] [--tools <host>]
-  ark agents-md [--root <project>] [--config ark.config.json] [--write] [--check] [--stdout] [--json]
-                [--tools <host>]
-
-Commands:
-  start     New here? Analyze and preview the complete setup. Read-only unless --apply.
-  init      Configure Ark project enforcement with explicit prompts.
-  upgrade   Preview identity-proven Ark-managed asset updates. With package install,
-            --apply bumps toward registry latest when behind (not only when CLI ≠ pin)
-            and recomputes the preview; a second explicit --apply --no-install applies
-            those exact bytes and verifies them. --refresh-skills opts in to rewrite
-            customized managed skills to package templates (never silent default).
-            (alias: ark update)
-  preflight Validate one atomic create/update/delete set without writing project files.
-  status    Unified session/project manifest (identity, activation, last check, rules).
-            Never prompts. Prefer --json for agents; CI=1 forces JSON.
-  agents-md Version-matched agent contract projection (ACS04). Stamps package version +
-            contract summary into a managed AGENTS.md block. Non-authoritative — not a
-            gate input. Preview by default; --write merges without clobbering outside
-            regions; --check fails on version drift; --stdout prints the block only.
-            (aliases: agents-md, agent-projection)
-
-Options:
-  --yes        Non-interactive defaults: create config if needed, install gate templates, run strict check.
-               (Also the implicit default when stdin/stdout are not a TTY — agents never hang on prompts.)
-  --force      Allow generated files to overwrite existing files.
-  --no-strict  Skip the final strict ark-check run.
-  --install    Pin and install arkgate as a project devDependency (default for start).
-  --no-install Skip adding/installing arkgate as a project devDependency (start/upgrade).
-  --apply       Apply a start plan; for upgrade, update/repreview or apply managed bytes.
-  --accept-conflicts
-                Allow upgrade to recreate deleted managed assets or replace recorded conflicts.
-  --plan-digest Digest emitted by an upgrade preview; required to apply managed bytes.
-  --json        Emit the start/upgrade/status/agents-md preview as deterministic machine-readable JSON.
-  --write       For agents-md: merge the version-matched projection into AGENTS.md.
-  --check       For agents-md: exit 1 when projection stamp drifts from package version.
-  --stdout      For agents-md: print the projection block only (no file write).
-  --expected-root / --expected-project-id
-                Optional project expectation for status (MCP-compatible binding check).
-  --preset     Start from a named architecture preset instead of detection.
-  --archetype  Application shape from templates/architecture-playbook.json (maps to the matching preset).
-               Valid ids: crud-product, api-backend, frontend-surface, library-sdk, cli-utility,
-               worker-pipeline, event-coordinator, integration-bridge, multi-app-workspace, prototype-spike,
-               vertical-slice-product, ddd-bounded-contexts.
-  --tools      One active agent host for start (claude,cursor,codex,grok,windsurf,cline,copilot,kiro,roo,continue,gemini).
-               Omit to use the active host; an unknown host creates only the shared compact router.
-  --remove-host <host>
-               Preview or apply removal of that compact host integration; re-add it with --tools <host>.
-  --require-write-hook <host>
-               Require and verify a hard local write hook for Claude, Grok, Antigravity, or Cursor.
-               Codex/OpenCode 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.
-`;
-}
-
 function cliVersion() {
   try {
     const pkg = JSON.parse(fs.readFileSync(path.join(here, '..', 'package.json'), 'utf8'));
@@ -795,23 +734,22 @@ async function start(args) {
     }
     console.log('');
     console.log('Next (the only flow you need):');
+    console.log(`  1. Status: ${arkCommand(root, 'arkgate-check', '--doctor')} — do primary next action #1`);
     if (falseGreenGap) {
-      console.log('  1. In your agent:  /ark-adopt  (or /ark-contract) — fix the contract first');
-      console.log('     → reclassify I/O dirs out of Application; then /ark-autopilot for residual debt.');
+      console.log('  2. Session 0 in your agent:  /ark-adopt — fix the architecture config first');
+      console.log('     → reclassify I/O dirs out of Application; leftover design later via /ark-explore then /ark-autopilot.');
     } else {
-      console.log('  1. In your agent:  /ark-autopilot');
-      console.log('     → explore first, dual plan (remediation + pattern bets), safe fixes, leave gates on.');
+      console.log('  2. Session 0 in your agent:  /ark-adopt');
+      console.log('     → mark the path (greenfield or brownfield). Day-to-day new files: /ark-place.');
     }
-    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-merge')}`);
+    console.log(`  3. After edits:    ${arkCommand(root, 'arkgate-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`
+        `  4. When green but cores still optional: ${arkCommand(root, 'arkgate-check', '--ratchet-cores')} → honest ENFORCE`
       );
     }
     console.log('');
-    console.log('Optional later: ark-check --report ark-report.html (captures a day-zero/evolution report).');
-    console.log('Optional later: --plan · --coverage · /ark-explore · /ark-fix · /ark-place · ark upgrade');
+    console.log('Optional later: leftover design → /ark-explore then /ark-autopilot; bump → arkgate upgrade.');
     return 0;
   } finally {
     rl?.close();
@@ -830,8 +768,12 @@ async function main() {
     console.log(cliVersion());
     return 0;
   }
+  if (args.help && (args.command === 'upgrade' || args.command === 'update')) {
+    console.log(upgradeUsage());
+    return 0;
+  }
   if (args.help || !args.command) {
-    console.log(usage());
+    console.log(args.all ? setupUsageAll() : setupUsage());
     return 0;
   }
 
@@ -941,6 +883,7 @@ async function main() {
       expectedProjectId: args.expectedProjectId,
       host: args.tools,
       arkgateVersion: cliVersion(),
+      vs: args.vs,
     });
   }
 
@@ -959,7 +902,7 @@ async function main() {
   }
 
   console.error(`Unknown command: ${args.command}`);
-  console.error(usage());
+  console.error(setupUsage());
   return 2;
 }
 

package/bin/lib/agent-projection.mjs

@@ -151,7 +151,7 @@ export function buildAgentProjectionBody(facts) {
         lines.push('### Primary path', '', '1. Run doctor (`ark-check --doctor`) — status light + primary next action.', '2. Read the improvement compass (not a score). Name leftover work in plain language; never “done” on green imports alone while leftover design work remains.', '3. Call `ark_identity` with `project.expectedRoot` at the exact project root; reuse root + `projectId` on Ark MCP calls.', '4. Read architecture config with `ark_manifest` (same expectation). `ark://manifest` is compatibility-only / unverified.', '5. Place files inside configured layers; validate; run the check command above on violations — fix architecture, do not weaken the gate.', '6. Single door: import-rule debt → fix; leftover design work / residual shape lenses → map then guided apply with user OK.', '', '### Contract layers (summary)', '', formatAgentProjectionLayers(layers), '');
     }
     else {
-        lines.push('### Contract layers', '', formatAgentProjectionLayers(layers), '', 'When creating a **new** kind of code that no layer covers, update `ark.config.json` first (`/ark-contract`), then place the file.', '', '### Diagnostic codes (short list)', '', formatAgentProjectionCatalogShortList(catalog, docsPath), '', '### Session truth', '', '- Machine snapshot: `ark status --json` (or MCP `ark_status`) — identity, activation honesty, last check, residual counts. **Not a score.**', '- Authoritative contract: `ark_manifest` after a matched `ark_identity` handshake.', '');
+        lines.push('### Contract layers', '', formatAgentProjectionLayers(layers), '', 'When creating a **new** kind of code that no layer covers, update `ark.config.json` first (`/ark-adopt`), then place the file.', '', '### Diagnostic codes (short list)', '', formatAgentProjectionCatalogShortList(catalog, docsPath), '', '### Session truth', '', '- Machine snapshot: `ark status --json` (or MCP `ark_status`) — identity, activation honesty, last check, residual counts. **Not a score.**', '- Authoritative contract: `ark_manifest` after a matched `ark_identity` handshake.', '');
     }
     lines.push('### Enforcement surfaces (authoritative)', '', AGENT_PROJECTION_ENFORCEMENT_SURFACES.map((surface) => `- \`${surface}\``).join('\n'), '');
     return lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';