arkgate 4.6.5 → 4.6.7

package/bin/lib/enforcement-honesty.mjs

@@ -10,6 +10,11 @@ import {
   HOST_SUPPORT_MATRIX,
   HOST_SUPPORT_HOSTS,
 } from './host-support-matrix.mjs';
+import {
+  classifyAdopted,
+  MERGE_BOUNDARY_NOT_REQUIRED,
+  NOT_ADOPTED_NEXT_ACTION,
+} from './adoption-stance.mjs';
 
 /** Soft = matrix hard-write false; hard-capable = matrix hard-write true. Single source of truth. */
 function hostWriteClassSets() {
@@ -380,6 +385,37 @@ export function buildProductHonesty(input = {}) {
     });
   }
 
+  const adopted =
+    typeof input.adopted === 'string'
+      ? input.adopted
+      : input.ciMergeBoundary || input.github || input.adoptionStance || input.considerMergeBoundary
+        ? classifyAdopted({
+            stance: input.adoptionStance,
+            github: input.github,
+            ci: input.ciMergeBoundary?.ci,
+          })
+        : null;
+  if (adopted === 'not-adopted') {
+    reasons.push({
+      id: MERGE_BOUNDARY_NOT_REQUIRED,
+      message:
+        'Merge boundary not adopted — require a GitHub status running arkgate-check --strict-merge, or write .ark/adoption-stance.json with stance: "advisory-only".',
+    });
+  }
+
+  const emptyStewards =
+    input.emptyStewards === true ||
+    input.stewardNudge?.emptyStewardsPastGrace === true ||
+    (input.stewardNudge?.needsStewards === true &&
+      (input.stewardNudge?.stewardCount ?? 0) === 0);
+  if (emptyStewards) {
+    reasons.push({
+      id: 'empty-stewards',
+      message:
+        'No stewards listed — not a finished Enforce. Name GitHub handles or emails for stewards[], or this stays Adapt-or-nudge. /ark-adopt asks; it does not invent names.',
+    });
+  }
+
   // Mode adapt/suggest (FG-FINISHED-ADAPT-DEBT): prefer unfinished unless the tree is
   // whole-tree green AND zero design smells AND zero blocking violations.
   // Type-only placement debt alone must not keep adapt unfinished via active-blocking.
@@ -442,6 +478,8 @@ export function buildProductHonesty(input = {}) {
     architectureReasons.find((r) => r.id === 'package-pin-absent') ||
     architectureReasons.find((r) => r.id === 'baseline-missing-with-debt') ||
     architectureReasons.find((r) => r.id === 'residual-pilot') ||
+    architectureReasons.find((r) => r.id === MERGE_BOUNDARY_NOT_REQUIRED) ||
+    architectureReasons.find((r) => r.id === 'empty-stewards') ||
     architectureReasons[0] ||
     environmentResiduals[0];
 
@@ -450,6 +488,9 @@ export function buildProductHonesty(input = {}) {
     primaryMessage =
       primary?.message ||
       'Not finished: residual honesty signals remain (violations, mode, coverage, freeze, design, package pin, or pilots).';
+  } else if (adopted === 'advisory-only-acked') {
+    primaryMessage =
+      'This tree acked advisory-only in .ark/adoption-stance.json. That is not a required GitHub merge status.';
   } else if (softWriteOnly) {
     primaryMessage = `${hostLabel} local writes stay advisory/bypassable; architecture contract on this slice is ready. Hard merge boundary is a required GitHub status context running arkgate-check --strict-merge (alias ark-check --strict-merge).`;
   } else if (wholeTreeGoverned) {
@@ -468,6 +509,8 @@ export function buildProductHonesty(input = {}) {
     headline = wholeTreeGoverned
       ? `Architecture contract ready; ${hostLabel} local writes are advisory`
       : `Contract residual clear; ${hostLabel} local writes are advisory`;
+  } else if (!unfinished && adopted === 'advisory-only-acked') {
+    headline = 'Advisory-only adoption — merge status is not required';
   } else if (!unfinished) {
     headline = 'Honesty clear on residual signals';
   } else if (coverageIncomplete) {
@@ -487,6 +530,12 @@ export function buildProductHonesty(input = {}) {
   } else if (!primaryNextAction && pinAbsent) {
     primaryNextAction =
       'Add arkgate to package.json and install so CI/npx resolve this CLI (PACKAGE_PIN_ABSENT)';
+  } else if (!primaryNextAction && adopted === 'not-adopted') {
+    primaryNextAction = NOT_ADOPTED_NEXT_ACTION;
+  } else if (!primaryNextAction && emptyStewards) {
+    primaryNextAction =
+      input.stewardNudge?.nextAction ||
+      '/ark-adopt (ask, then update stewards[] — do not invent names)';
   } else if (!primaryNextAction && softWriteOnly) {
     primaryNextAction =
       'Confirm the GitHub required status context name runs arkgate-check --strict-merge (or ark-check --strict-merge). Soft-write hosts stay advisory at local write; the required status is the hard merge boundary.';
@@ -558,6 +607,12 @@ export function computeDoctorEnforcementHonesty({
   packageInstalled,
   selfHost,
   motherCli,
+  adopted: adoptedInput,
+  ciMergeBoundary,
+  github,
+  adoptionStance,
+  emptyStewards,
+  stewardNudge,
 } = {}) {
   const coverageHonesty = buildCoverageHonesty({
     percent: governedPercent,
@@ -583,6 +638,14 @@ export function computeDoctorEnforcementHonesty({
   const blockingForHonesty = Number.isFinite(Number(activeBlockingViolations))
     ? Math.max(0, Number(activeBlockingViolations))
     : Number(activeViolations) || 0;
+  const adopted =
+    typeof adoptedInput === 'string'
+      ? adoptedInput
+      : classifyAdopted({
+          stance: adoptionStance,
+          github,
+          ci: ciMergeBoundary?.ci,
+        });
   const productHonesty = buildProductHonesty({
     coverageHonesty,
     baselineHonesty,
@@ -598,6 +661,13 @@ export function computeDoctorEnforcementHonesty({
     primaryNextAction,
     operatingMode,
     activeBlockingViolations: blockingForHonesty,
+    adopted,
+    ciMergeBoundary,
+    github,
+    adoptionStance,
+    considerMergeBoundary: true,
+    emptyStewards,
+    stewardNudge,
   });
   return {
     coverageHonesty,

package/bin/lib/first-run-help.mjs

@@ -5,14 +5,11 @@
 export function setupUsage() {
   return `arkgate (alias ark) — One architecture config. One check. One coach.
 
-  arkgate start              preview what will change (no writes)
-  arkgate start --apply      write the compact contract + host router + CI
-  arkgate-check --doctor     status light + primary next action
+  arkgate start              preview (no writes)
+  arkgate start --apply      write host + CI setup
+  arkgate-check --doctor     where you are + one next action
 
-Then session 0 in your agent: /ark-adopt
 Stuck? Run doctor. Do #1.
-
-More commands and flags: arkgate --help --all
 `;
 }
 
@@ -114,7 +111,7 @@ export function checkUsageAll() {
     'Usage: arkgate-check | ark-check  (identical bins; product name ArkGate)',
     '       arkgate-check --version',
     '       arkgate-check --root <project> --config <ark.config.json> [--manifest <ark.manifest.json>] [--tsconfig <tsconfig.json>] [--strict-merge | --strict | --strict-config] [--policy-base <file> | --policy-base-ref <git-ref>] [--policy-ack <file>] [--fail-on-new-smells --base-ref <git-ref>] [--contract-diff] [--contract-session] [--changed] [--against <git-ref>] [--base <git-ref>] [--persona touch|contributor|agent|steward] [--author <id>] [--require-gates] [--require-write-hook <host>] [--json] [--baseline [file]] [--report [file.html]] [--no-cache]',
-    '       ark-check --doctor [--json] [--resident] [--fail-on-new-smells --base-ref <git-ref>]  read-only diagnosis; resident JSON falls back cold',
+    '       ark-check --doctor [--json] [--all] [--resident] [--fail-on-new-smells --base-ref <git-ref>]  compact first screen; --all prints Details; resident JSON falls back cold',
     '       ark-check --coverage [--json]          per-layer file counts + full unclassified list (report only, exit 0)',
     '       ark-check --plan [--json]              classified remediation plan (mechanical-safe / judgment / deferred) + goal; report only',
     '       ark-check --rules-inventory [--json]   brownfield rules inventory (AR13; deterministic candidates, not a score)',
@@ -183,6 +180,10 @@ export function checkUsageAll() {
     'transition. Weakening or judgment-required findings fail unless --policy-ack names',
     'every finding and is bound to both policy hashes. Use --policy-base/--policy-base-ref',
     'for an explicit comparison; ARK_POLICY_BASE_REF is the CI environment equivalent.',
+    'The same merge profile blocks new UI business-rule files (domain-logic-in-ui) created',
+    'versus that base; leftover design on existing files stays green. Missing base skips',
+    'this check (does not exit 2). --fail-on-new-smells --base-ref remains the full',
+    'new+worsened-on-touched-paths ratchet.',
     'Add --require-write-hook claude|grok|antigravity|cursor|codex to validate a hard local',
     'write boundary for that specific host. Codex covers complete local apply_patch only;',
     'hosted/specialized/direct-write paths and OpenCode remain CI-backed. Merge blocking requires',

package/bin/lib/github-enforcement.mjs

@@ -3,6 +3,19 @@ import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 
+/** Kill hung gh instead of stalling CI. */
+export const SPAWN_TIMEOUT_MS = 8000;
+
+function runGh(args, opts = {}) {
+  const { run, ...rest } = opts;
+  const spawn = typeof run === 'function' ? run : spawnSync;
+  return spawn('gh', args, {
+    encoding: 'utf8',
+    ...rest,
+    timeout: SPAWN_TIMEOUT_MS,
+  });
+}
+
 const IF_LINE = /^[ \t]*(?:-\s+)?(?:"if"|'if'|if):\s*(.*?)\s*(?:#.*)?$/i;
 const CONTINUE_LINE = /^[ \t]*(?:-\s+)?(?:"continue-on-error"|'continue-on-error'|continue-on-error):\s*(.*?)\s*(?:#.*)?$/i;
 const SAFE_IF = /^(?:['"]?true['"]?|['"]?\$\{\{\s*(?:true|always\(\))\s*\}\}['"]?)$/i;
@@ -434,7 +447,7 @@ export function reportGithubCiRuntime(opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
   const env = opts.env ?? process.env;
   const limit = Number.isFinite(Number(opts.limit)) ? Math.max(1, Number(opts.limit)) : 30;
-  if (spawnSync('gh', ['--version'], { encoding: 'utf8', env }).status !== 0) {
+  if (runGh(['--version'], { env, run: opts.run }).status !== 0) {
     return { runtimeObserved: false, latestCiRun: null, reason: 'gh-cli-unavailable' };
   }
   const args = [
@@ -443,7 +456,7 @@ export function reportGithubCiRuntime(opts = {}) {
     '--json', 'name,conclusion,status,workflowName,displayTitle,event',
   ];
   if (opts.repo) args.push('--repo', opts.repo);
-  const result = spawnSync('gh', args, { cwd, encoding: 'utf8', env });
+  const result = runGh(args, { cwd, env, run: opts.run });
   if (result.status !== 0) {
     const err = `${result.stderr || ''}${result.stdout || ''}`.slice(0, 400);
     return {
@@ -499,14 +512,14 @@ export function reportGithubCiRuntime(opts = {}) {
 export function reportGithubBranchProtection(opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
   const env = opts.env ?? process.env;
-  if (spawnSync('gh', ['--version'], { encoding: 'utf8', env }).status !== 0) {
+  if (runGh(['--version'], { env, run: opts.run }).status !== 0) {
     return { available: false, reason: 'gh-cli-unavailable', runtimeObserved: false, latestCiRun: null };
   }
   let repo = opts.repo;
   let branch = opts.branch;
   if (!repo || !branch) {
     const args = ['repo', 'view', ...(repo ? [repo] : []), '--json', 'nameWithOwner,defaultBranchRef'];
-    const metadata = parseJson(spawnSync('gh', args, { cwd, encoding: 'utf8', env }));
+    const metadata = parseJson(runGh(args, { cwd, env, run: opts.run }));
     if (!metadata?.nameWithOwner || !metadata?.defaultBranchRef?.name) {
       return { available: false, reason: 'gh-repo-unavailable', runtimeObserved: false, latestCiRun: null };
     }
@@ -514,13 +527,13 @@ export function reportGithubBranchProtection(opts = {}) {
     branch ??= metadata.defaultBranchRef.name;
   }
 
-  const classicResult = spawnSync('gh', [
+  const classicResult = runGh([
     'api', `repos/${repo}/branches/${encodeURIComponent(branch)}/protection`, '--jq',
     '{strict: .required_status_checks.strict, contexts: .required_status_checks.contexts, checks: .required_status_checks.checks, enforcesAdmins: .enforce_admins.enabled}',
-  ], { cwd, encoding: 'utf8', env });
-  const rulesResult = spawnSync(
-    'gh', ['api', `repos/${repo}/rules/branches/${encodeURIComponent(branch)}`],
-    { cwd, encoding: 'utf8', env }
+  ], { cwd, env, run: opts.run });
+  const rulesResult = runGh(
+    ['api', `repos/${repo}/rules/branches/${encodeURIComponent(branch)}`],
+    { cwd, env, run: opts.run }
   );
   const classic = parseJson(classicResult);
   const rules = parseJson(rulesResult);

package/bin/lib/html-report-advisories.mjs

@@ -313,17 +313,25 @@ function deepModuleCoachHtml(coach) {
 
 function stewardNudgeHtml(nudge) {
   if (!nudge || nudge.notAScore !== true) return '';
+  const unfinished = Boolean(
+    nudge.emptyStewardsPastGrace || (nudge.needsStewards && (nudge.stewardCount ?? 0) === 0)
+  );
   const ask =
-    (nudge.needsStewards || nudge.drift) && typeof nudge.ask === 'string' && nudge.ask
+    (nudge.needsStewards || nudge.drift || nudge.emptyStewardsPastGrace) &&
+    typeof nudge.ask === 'string' &&
+    nudge.ask
       ? `<p>${esc(nudge.ask)}</p>`
       : '<p class="muted">No steward list gap (advisory).</p>';
   const next =
     typeof nudge.nextAction === 'string' && nudge.nextAction
       ? `<p class="muted">Next: ${esc(nudge.nextAction)}</p>`
       : '';
+  const qualifier = unfinished
+    ? '(unfinished residual — changes finished, not check valid)'
+    : '(advisory — never changes the check valid bit)';
   return `
   <section class="section card" data-advisory="stewardNudge">
-    <h2>Stewards <span class="muted">(advisory — never changes the verdict)</span></h2>
+    <h2>Stewards <span class="muted">${qualifier}</span></h2>
     ${ask}
     ${next}
     <p class="muted">GitHub handle or email. Never invent names. Always <code>notAScore</code>.</p>

package/bin/lib/html-report.mjs

@@ -28,6 +28,9 @@ import { captureGitSnapshot } from './report-snapshot-context.mjs';
 
 export { arkGitignoreAppendDecision, gitignoreCoversArkState, gitignoreHasArkNegationException } from './ark-gitignore.mjs';
 
+/** Cap the rendered violation list so showcase HTML cannot dump unbounded findings. */
+export const HTML_REPORT_VIOLATION_LIST_CAP = 12;
+
 export function detectEnforcement(root) {
   const has = (rel) => fs.existsSync(path.join(root, rel));
   const fileIncludes = (rel, needle) => {
@@ -110,7 +113,7 @@ export function baselineSignalHint(signal) {
 export function modeBadgeHint(mode) {
   switch (String(mode || '').toLowerCase()) {
     case 'enforce':
-      return 'Contract matches the tree: cores are required where populated, coverage is honest, gates can hold the line.';
+      return 'Contract matches the tree on checked import edges. Required GitHub status (or an advisory-only ack) is what adopts the merge boundary.';
     case 'adapt':
       return 'Contract is live but still aligning (optional cores with files, empty cores, or presentation-bag false green).';
     case 'suggest':
@@ -255,7 +258,7 @@ export function computeReportFitness({ coverage, violations, ok, enforcement, co
   const modeBlurb = {
     suggest: 'Starter shape — expand layers as the codebase grows.',
     adapt: 'Contract is live; raise governed coverage or match real folders.',
-    enforce: 'Contract governs the tree. Gates can honestly hold the line.',
+    enforce: 'Contract matches the tree on checked import edges. Merge is adopted only with a required GitHub status or an advisory-only ack.',
   }[mode];
   const scoreCoverage = governedPercent == null ? 50 : governedPercent;
   const scoreClean =
@@ -392,9 +395,13 @@ export function renderBeginnerHtmlReport({ root, config, violations, ok, version
     })
     .join('\n');
 
+  const listedBeginner = violations.slice(0, HTML_REPORT_VIOLATION_LIST_CAP);
+  const hiddenBeginner = Math.max(0, violations.length - listedBeginner.length);
+  const beginnerRemainder = hiddenBeginner
+    ? `<div class="dim">+${hiddenBeginner} more (${violations.length} total)</div>`
+    : '';
   const violationRows = violations.length
-    ? violations
-        .slice(0, 12)
+    ? listedBeginner
         .map((v) => {
           const enriched = enrichViolationWithFixClass(v);
           return `<li><code>${esc(v.file)}:${v.line}</code> — ${esc(enriched.enthusiastHint ?? v.message)}</li>`;
@@ -436,6 +443,7 @@ export function renderBeginnerHtmlReport({ root, config, violations, ok, version
   </table>
   <h2>What to fix first</h2>
   <ul>${violationRows}</ul>
+  ${beginnerRemainder}
   <h2>Next steps</h2>
   <p><code>${arkCheckCommand(root)}</code></p>
   <p><code>${arkCommand(root, 'ark-check', '--recommend')}</code></p>
@@ -781,13 +789,22 @@ export function renderHtmlReport({
     })
     .join('\n');
 
-  const byRule = new Map();
+  const listedViolations = violations.slice(0, HTML_REPORT_VIOLATION_LIST_CAP);
+  const hiddenViolationCount = Math.max(0, violations.length - listedViolations.length);
+  const ruleTotals = new Map();
   for (const v of violations) {
+    ruleTotals.set(v.ruleId, (ruleTotals.get(v.ruleId) || 0) + 1);
+  }
+  const byRule = new Map();
+  for (const v of listedViolations) {
     if (!byRule.has(v.ruleId)) byRule.set(v.ruleId, []);
     byRule.get(v.ruleId).push(v);
   }
-  const violationBlocks = violations.length
-    ? [...byRule.entries()]
+  const remainderNote = hiddenViolationCount
+    ? `<div class="dim">+${hiddenViolationCount} more (${violations.length} total)</div>`
+    : '';
+  const violationBlocks = listedViolations.length
+    ? `${[...byRule.entries()]
         .map(([ruleId, items]) => {
           const hint = FIX_HINTS[ruleId];
           const rows = items
@@ -803,12 +820,12 @@ export function renderHtmlReport({
             })
             .join('\n');
           return `<div class="vgroup">
-            <div class="vghead"><span class="rule">${esc(ruleId)}</span> <span class="dim">${items.length}</span></div>
+            <div class="vghead"><span class="rule">${esc(ruleId)}</span> <span class="dim">${ruleTotals.get(ruleId) ?? items.length}</span></div>
             <ul class="vitems">${rows}</ul>
             ${hint ? `<div class="fix">fix: ${esc(hint)}</div>` : ''}
           </div>`;
         })
-        .join('\n')
+        .join('\n')}${remainderNote}`
     : `<div class="clean hero-clean">
         <div class="clean-title">Architecture matches the contract</div>
         <div class="clean-body">No active violations${suppressed ? ` · ${suppressed} frozen by baseline` : ''}. This is what “honest green” looks like when coverage is real.</div>

package/bin/lib/mcp-adoption.mjs

@@ -17,6 +17,11 @@ import { detectActiveAgentHost, skillTemplateNames } from './skill-install.mjs';
 import { detectDeployPathQuality } from './deploy-path.mjs';
 import { collectWeakestLinkGaps } from './weakest-link.mjs';
 import { codexRuntimeActivation, withCiProviderEvidence } from './enforcement-state.mjs';
+import {
+  classifyAdopted,
+  readAdoptionStance,
+  NOT_ADOPTED_NEXT_ACTION,
+} from './adoption-stance.mjs';
 
 export { detectDeployPathQuality };
 
@@ -528,6 +533,20 @@ export function collectAdoptionGaps(root, config, coverage) {
     gaps.push(g);
   }
 
+  const adoptedKind = classifyAdopted({
+    stance: readAdoptionStance(root),
+    github: weakest.github,
+  });
+  if (adoptedKind === 'not-adopted') {
+    gaps.push({
+      id: 'adoption-stance-missing',
+      severity: 'warn',
+      message:
+        'Merge boundary not adopted: require a GitHub status on arkgate-check --strict-merge, or write .ark/adoption-stance.json with stance: "advisory-only".',
+      fix: NOT_ADOPTED_NEXT_ACTION,
+    });
+  }
+
   return {
     gaps,
     hosts,