arkgate 4.1.0 → 4.1.1

package/bin/lib/github-enforcement.mjs

@@ -362,12 +362,132 @@ function parseJson(result) {
   }
 }
 
+/**
+ * Classify GitHub provider API failures (EH06).
+ * Plan/tier claims require **explicit upgrade/plan language** — bare HTTP 403
+ * (token/SSO/scope) stays generic `provider-enforcement-unverified` so we never
+ * overclaim "proven not required" / Free-plan walls.
+ *
+ * @param {string} errorText combined stderr/stdout from gh api
+ * @param {{ classicAvailable?: boolean, rulesAvailable?: boolean }} [opts]
+ * @returns {'provider-policy-unavailable-plan'|'provider-enforcement-unverified'|'ok'}
+ */
+export function classifyGithubProviderFailure(errorText, opts = {}) {
+  const text = String(errorText || '');
+  const lower = text.toLowerCase();
+  // Explicit plan/tier walls only — not every 403 (token/SSO/scope stay unverified).
+  const planRestricted =
+    /upgrade to github (pro|team|enterprise)/i.test(lower) ||
+    /not available (on|for) (your|this) (current )?plan/i.test(lower) ||
+    /requires a paid github/i.test(lower) ||
+    /github pro.*branch protection|branch protection.*github pro/i.test(lower) ||
+    /only available (with|on) github (pro|team|enterprise)/i.test(lower) ||
+    /this feature is not available (on|for) (free|your plan)/i.test(lower);
+  if (planRestricted) return 'provider-policy-unavailable-plan';
+  if (opts.classicAvailable && opts.rulesAvailable) return 'ok';
+  return 'provider-enforcement-unverified';
+}
+
+/**
+ * True when a workflow/job title is an Ark architecture check (not lint-only / spark-ci / dark-theme).
+ * Prefer exact product tokens; "architecture" only with gate/check phrasing.
+ *
+ * @param {{ name?: string, workflowName?: string, displayTitle?: string }} run
+ * @returns {boolean}
+ */
+export function isArkishCiRun(run) {
+  const blob = `${run?.name || ''} ${run?.workflowName || ''} ${run?.displayTitle || ''}`.toLowerCase();
+  if (!blob.trim()) return false;
+  // Product tokens with word boundaries (avoid spark, dark, lark false positives).
+  if (/\barkgate(?:-check)?\b/.test(blob)) return true;
+  if (/\bark-check\b/.test(blob)) return true;
+  if (/\bark\s+architecture\b/.test(blob)) return true;
+  if (/\barchitecture\s+(?:gate|check)\b/.test(blob)) return true;
+  if (/\b(?:arkgate|ark)\s+architecture\s+gate\b/.test(blob)) return true;
+  // Standalone workflow names generated by Ark (`name: Ark architecture gate`)
+  if (/\bark architecture gate\b/.test(blob)) return true;
+  return false;
+}
+
+/**
+ * Observe recent GitHub Actions success for Ark architecture checks (EH06).
+ * Independent of branch-protection / required-status policy APIs.
+ * Never falls back to non-Ark green jobs (lint/test).
+ *
+ * @param {{ cwd?: string, env?: NodeJS.ProcessEnv, repo?: string, limit?: number }} [opts]
+ * @returns {{ runtimeObserved: boolean, latestCiRun: string|null, reason: string, runs?: unknown[] }}
+ */
+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) {
+    return { runtimeObserved: false, latestCiRun: null, reason: 'gh-cli-unavailable' };
+  }
+  const args = [
+    'run', 'list',
+    '--limit', String(limit),
+    '--json', 'name,conclusion,status,workflowName,displayTitle,event',
+  ];
+  if (opts.repo) args.push('--repo', opts.repo);
+  const result = spawnSync('gh', args, { cwd, encoding: 'utf8', env });
+  if (result.status !== 0) {
+    const err = `${result.stderr || ''}${result.stdout || ''}`.slice(0, 400);
+    return {
+      runtimeObserved: false,
+      latestCiRun: null,
+      reason: classifyGithubProviderFailure(err) === 'provider-policy-unavailable-plan'
+        ? 'provider-policy-unavailable-plan'
+        : 'ci-runtime-unverified',
+    };
+  }
+  let runs = [];
+  try {
+    runs = JSON.parse(result.stdout || '[]');
+  } catch {
+    return { runtimeObserved: false, latestCiRun: null, reason: 'ci-runtime-unverified' };
+  }
+  if (!Array.isArray(runs)) {
+    return { runtimeObserved: false, latestCiRun: null, reason: 'ci-runtime-unverified' };
+  }
+  const relevant = runs.filter(isArkishCiRun);
+  if (relevant.length === 0) {
+    return {
+      runtimeObserved: false,
+      latestCiRun: null,
+      reason: runs.length === 0 ? 'ci-runtime-empty' : 'ci-runtime-no-ark-runs',
+      runs: runs.slice(0, 5),
+    };
+  }
+  const success = relevant.find(
+    (run) => String(run?.conclusion || '').toLowerCase() === 'success'
+  );
+  if (success) {
+    return {
+      runtimeObserved: true,
+      latestCiRun: 'success',
+      reason: 'ok',
+      runs: relevant.slice(0, 5),
+    };
+  }
+  const latest = relevant[0];
+  const latestConclusion = latest
+    ? String(latest.conclusion || latest.status || 'unknown').toLowerCase()
+    : null;
+  return {
+    runtimeObserved: false,
+    latestCiRun: latestConclusion,
+    reason: 'ci-runtime-no-success',
+    runs: relevant.slice(0, 5),
+  };
+}
+
 /** Query classic branch protection and all active branch rules before reporting absence. */
 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) {
-    return { available: false, reason: 'gh-cli-unavailable' };
+    return { available: false, reason: 'gh-cli-unavailable', runtimeObserved: false, latestCiRun: null };
   }
   let repo = opts.repo;
   let branch = opts.branch;
@@ -375,7 +495,7 @@ export function reportGithubBranchProtection(opts = {}) {
     const args = ['repo', 'view', ...(repo ? [repo] : []), '--json', 'nameWithOwner,defaultBranchRef'];
     const metadata = parseJson(spawnSync('gh', args, { cwd, encoding: 'utf8', env }));
     if (!metadata?.nameWithOwner || !metadata?.defaultBranchRef?.name) {
-      return { available: false, reason: 'gh-repo-unavailable' };
+      return { available: false, reason: 'gh-repo-unavailable', runtimeObserved: false, latestCiRun: null };
     }
     repo ??= metadata.nameWithOwner;
     branch ??= metadata.defaultBranchRef.name;
@@ -426,9 +546,32 @@ export function reportGithubBranchProtection(opts = {}) {
   const all = [...new Set([...contexts, ...checks.map((check) => check.context), ...statusRules.map((check) => check.context)])];
   const error = `${classicResult.stderr || ''}${rulesResult.stderr || ''}`.slice(0, 400);
 
+  let reason = available ? 'ok' : 'provider-enforcement-unverified';
+  if (!available) {
+    // Plan-restriction only when neither classic nor ruleset evidence could be read.
+    // Partial success (one source OK, other 403) stays generic unverified — not a plan claim.
+    if (!classicAvailable && !rulesAvailable) {
+      const classicFail =
+        classicResult.status !== 0 ? String(classicResult.stderr || classicResult.stdout || '') : '';
+      const rulesFail =
+        rulesResult.status !== 0 ? String(rulesResult.stderr || rulesResult.stdout || '') : '';
+      reason = classifyGithubProviderFailure(`${classicFail}\n${rulesFail}\n${error}`, {
+        classicAvailable,
+        rulesAvailable,
+      });
+    }
+  }
+
+  // EH06: CI runtime observation is independent of branch-protection availability.
+  const ciRuntime = opts.includeCiRuntime === false
+    ? { runtimeObserved: false, latestCiRun: null, reason: 'skipped' }
+    : reportGithubCiRuntime({ cwd, env, repo });
+
   return {
     available,
-    reason: available ? 'ok' : 'provider-enforcement-unverified',
+    reason,
+    // Alias for consumers that look for the short code
+    policyReason: reason === 'provider-policy-unavailable-plan' ? 'unavailable-plan' : reason,
     repo,
     branch,
     requiredStatusChecks: all,
@@ -438,6 +581,11 @@ export function reportGithubBranchProtection(opts = {}) {
     enforcesAdmins: classicAvailable ? Boolean(classic.enforcesAdmins) : null,
     arkCheckRequired,
     arkCheckSourceBound,
-    raw: { classic, rules, ...(error ? { error } : {}) },
+    // hard merge remains false when status is not proven required
+    hard: arkCheckRequired === true ? undefined : false,
+    runtimeObserved: ciRuntime.runtimeObserved === true,
+    latestCiRun: ciRuntime.latestCiRun,
+    ciRuntimeReason: ciRuntime.reason,
+    raw: { classic, rules, ...(error ? { error } : {}), ciRuntime },
   };
 }

package/bin/lib/host-support-matrix.mjs

@@ -6,7 +6,21 @@
  * reported separately by write-path-capabilities.mjs.
  */
 
-function hostProfile(label, hookPath, hookSurface, hookOperations, hardWrite, repairPayload) {
+/**
+ * @param {string} label
+ * @param {string|null} hookPath
+ * @param {string|null} hookSurface
+ * @param {string[]} hookOperations
+ * @param {boolean} hardWrite
+ * @param {boolean} repairPayload reinjection guaranteed under hard boundary (historical key)
+ * @param {{ repairEnvelopeEmitted?: boolean, operationCoverage?: Record<string, boolean> }} [extras]
+ */
+function hostProfile(label, hookPath, hookSurface, hookOperations, hardWrite, repairPayload, extras = {}) {
+  // EH07: repair envelope emission ≠ reinjection guarantee.
+  // Codex hooks may emit --hook-repair JSON while reinjection stays host-dependent / not hard.
+  const repairEnvelopeEmitted =
+    extras.repairEnvelopeEmitted === true || repairPayload === true;
+  const repairReinjectionGuaranteed = hardWrite === true && repairPayload === true;
   return Object.freeze({
     label,
     hookPath,
@@ -16,8 +30,16 @@ function hostProfile(label, hookPath, hookSurface, hookOperations, hardWrite, re
       'hard-write': hardWrite,
       'advisory-write': true,
       'merge-gate': true,
+      // Historical key: true only when hard reinjection path is package-supported.
       'repair-payload': repairPayload,
+      'repair-envelope-emitted': repairEnvelopeEmitted,
+      'repair-reinjection-guaranteed': repairReinjectionGuaranteed,
     }),
+    // EH07 minimum ops matrix (hard=false for soft hosts on every listed op).
+    operationCoverage: Object.freeze(
+      extras.operationCoverage ||
+        Object.fromEntries(hookOperations.map((op) => [op, hardWrite === true]))
+    ),
   });
 }
 
@@ -48,14 +70,25 @@ export const HOST_SUPPORT_MATRIX = Object.freeze({
     true,
     true
   ),
-  cursor: hostProfile('Cursor', null, null, [], false, false),
+  cursor: hostProfile('Cursor', null, null, [], false, false, {
+    operationCoverage: { shell: false, 'pre-commit': false },
+  }),
   codex: hostProfile(
     'OpenAI Codex',
     '.codex/hooks.json',
     'Best-effort PreToolUse `apply_patch`; Code Mode hosts may bypass the event',
     ['apply_patch'],
     false,
-    false
+    false,
+    {
+      // Install writes --hook-repair; envelope can be emitted; reinjection is not guaranteed.
+      repairEnvelopeEmitted: true,
+      operationCoverage: {
+        apply_patch: false,
+        shell: false,
+        'pre-commit': false,
+      },
+    }
   ),
   // OpenCode: first-class MCP + permissions; plugin tool.execute.before is incomplete
   // (subagent holes). Never claim hard write.
@@ -65,7 +98,10 @@ export const HOST_SUPPORT_MATRIX = Object.freeze({
     'Advisory MCP + optional experimental plugin (`tool.execute.before`); not a hard boundary',
     [],
     false,
-    false
+    false,
+    {
+      operationCoverage: { shell: false, 'pre-commit': false },
+    }
   ),
 });
 
@@ -82,7 +118,15 @@ export function formatHostSupportSummary(profile) {
   const write = capabilities['hard-write']
     ? 'hard local write boundary'
     : 'no hard local write boundary';
-  const repair = capabilities['repair-payload'] ? 'repair payload' : 'no hard-boundary repair';
+  // EH07 three-way repair story: reinjection guaranteed / envelope-only / none.
+  let repair;
+  if (capabilities['repair-reinjection-guaranteed']) {
+    repair = 'repair reinjection (hard path)';
+  } else if (capabilities['repair-envelope-emitted']) {
+    repair = 'repair envelope may emit (reinjection not guaranteed)';
+  } else {
+    repair = 'no hard-boundary repair';
+  }
   return `${write} + advisory MCP + CI check + ${repair}`;
 }
 
@@ -104,12 +148,18 @@ export function renderHostSupportMatrixMarkdown() {
     } else {
       local = '**Advisory only** at write (no hard hook)';
     }
-    const repair = capabilities['repair-payload']
-      ? 'Emitted on hook deny; host must re-inject'
-      : 'No hard-boundary payload';
-    const merge = capabilities['hard-write']
-      ? '**Required status** = hard merge boundary (`arkgate-check --strict-merge`)'
-      : '**Required status** = hard merge boundary (same CI)';
+    // EH07: distinguish envelope emission vs reinjection guarantee in the repair column.
+    let repair;
+    if (capabilities['repair-reinjection-guaranteed']) {
+      repair = 'Emitted on hook deny; host must re-inject (hard path when installed + trusted)';
+    } else if (capabilities['repair-envelope-emitted']) {
+      repair = 'Envelope may emit (`--hook-repair`); reinjection **not** guaranteed (advisory host)';
+    } else {
+      repair = 'No hard-boundary payload';
+    }
+    // EH07: name the CLI explicitly; required status is a GitHub status context name, not the CLI alone.
+    const merge =
+      '**Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`)';
     return `| ${profile.label} | ${local} | Advisory; the agent must call it | ${merge} | ${repair} |`;
   }).join('\n');
 
@@ -118,9 +168,30 @@ export function renderHostSupportMatrixMarkdown() {
 ${rows}
 
 **Read the CI column:** for every host, the repository-wide hard guarantee is a **required**
-merge check — not “CI file present.” Cursor/Codex/OpenCode never get a fake hard write claim.
+GitHub **status context** that runs the CLI — not “CI file present,” and not the CLI binary name alone.
+Cursor/Codex/OpenCode never get a fake hard write claim.
+
+This table describes the supported profile **after its files are installed and the host loads/trusts them**. A hard local boundary covers only the listed hook operations; alternate tools, direct filesystem writes, and human edits still rely on CI. MCP validation is advisory because the agent must call it. The CI check blocks a merge only when the repository makes that status required. Repair **envelopes** may be emitted without reinjection being guaranteed; silent auto-apply never happens. Run \`arkgate-check --doctor\` (or \`ark-check --doctor\`) for the evidence actually detected in the current repository.`;
+}
 
-This table describes the supported profile **after its files are installed and the host loads/trusts them**. A hard local boundary covers only the listed hook operations; alternate tools, direct filesystem writes, and human edits still rely on CI. MCP validation is advisory because the agent must call it. The CI check blocks a merge only when the repository makes that status required. Repair payloads never write code silently: the host must re-inject the candidate and ArkGate revalidates it. Run \`arkgate-check --doctor\` for the evidence actually detected in the current repository.`;
+/**
+ * EH07 doctor/JSON host capability split for repair envelope vs reinjection.
+ * @param {string|null|undefined} host
+ */
+export function hostRepairCapabilities(host) {
+  const profile = getHostSupportProfile(host);
+  if (!profile) {
+    return {
+      repairEnvelopeEmitted: false,
+      repairReinjectionGuaranteed: false,
+      operationCoverage: {},
+    };
+  }
+  return {
+    repairEnvelopeEmitted: profile.capabilities['repair-envelope-emitted'] === true,
+    repairReinjectionGuaranteed: profile.capabilities['repair-reinjection-guaranteed'] === true,
+    operationCoverage: { ...(profile.operationCoverage || {}) },
+  };
 }
 
 /**
@@ -129,19 +200,22 @@ This table describes the supported profile **after its files are installed and t
  */
 export function doctorWritePathHonestyMessage(activeHost, hardWriteActive) {
   const host = typeof activeHost === 'string' ? activeHost.trim().toLowerCase() : '';
+  // EH07: distinguish CLI command (arkgate-check / ark-check) from the GitHub required status context name.
+  const mergeBoundary =
+    'Required CI hard merge boundary = a required GitHub status context that runs arkgate-check --strict-merge (alias ark-check --strict-merge)';
   if (host === 'cursor') {
-    return 'Cursor: write path is advisory (MCP/rules; no hard PreToolUse). Required CI status (arkgate-check --strict-merge) is the hard merge boundary.';
+    return `Cursor: write path is advisory (MCP/rules; no hard PreToolUse). ${mergeBoundary}.`;
   }
   if (host === 'codex') {
-    return 'Codex: write path is advisory / best-effort at write (not Claude/Grok hard). Required CI status (arkgate-check --strict-merge) is the hard merge boundary.';
+    return `Codex: write path is advisory / best-effort at write (not Claude/Grok hard). ${mergeBoundary}.`;
   }
   if (host === 'opencode') {
-    return 'OpenCode: write path is advisory / best-effort (MCP + optional plugin; not Claude/Grok/Antigravity hard). Required CI status (arkgate-check --strict-merge) is the hard merge boundary.';
+    return `OpenCode: write path is advisory / best-effort (MCP + optional plugin; not Claude/Grok/Antigravity hard). ${mergeBoundary}.`;
   }
   if ((host === 'claude' || host === 'grok' || host === 'antigravity') && !hardWriteActive) {
     const label =
       host === 'claude' ? 'Claude' : host === 'grok' ? 'Grok' : 'Antigravity';
-    return `${label}: hard PreToolUse is supported for listed ops when installed + trusted; without runtime-observed hook evidence, hard is unverified. Required CI remains the merge hard boundary.`;
+    return `${label}: hard PreToolUse is supported for listed ops when installed + trusted; without runtime-observed hook evidence, hard is unverified. ${mergeBoundary}.`;
   }
   return null;
 }

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

@@ -288,6 +288,10 @@ function baselineLegendBody(signal) {
 export function renderProductHonestyCard(productHonesty, mergePlanes = null) {
   if (!productHonesty || typeof productHonesty !== 'object') return '';
   const unfinished = productHonesty.unfinished === true;
+  const envResiduals = Array.isArray(productHonesty.environmentResidualIds)
+    ? productHonesty.environmentResidualIds
+    : [];
+  const envOnly = !unfinished && envResiduals.length > 0;
   const headline = productHonesty.headline || (unfinished ? 'Not finished' : 'Honesty clear');
   const primary = productHonesty.primaryMessage || '';
   // Avoid repeating the same status label in title and body (past-issue pattern).
@@ -298,7 +302,9 @@ export function renderProductHonestyCard(productHonesty, mergePlanes = null) {
     if (p === h) {
       body = unfinished
         ? 'Residual honesty signals remain — not a whole-tree guarantee and not a score.'
-        : 'No residual honesty blockers on this slice — still not a numeric architecture score.';
+        : envOnly
+          ? 'Architecture residual clear; host/environment residual remains (advisory write) — not a score.'
+          : 'No residual honesty blockers on this slice — still not a numeric architecture score.';
     } else if (p.toLowerCase().startsWith(h.toLowerCase())) {
       const stripped = p.slice(h.length).replace(/^[\s—–:-]+/, '').trim();
       body = stripped || p;
@@ -319,10 +325,15 @@ export function renderProductHonestyCard(productHonesty, mergePlanes = null) {
     mergePlanes?.dualPlaneStamp
       ? `<p class="dim" style="margin:.25rem 0 0;font-size:.84rem">${esc(mergePlanes.dualPlaneStamp)}</p>`
       : '';
+  const subtitle = unfinished
+    ? 'architecture residual'
+    : envOnly
+      ? 'environment residual (advisory write)'
+      : 'no residual honesty blockers';
   return `<div class="section card design-strip ${unfinished ? 'is-weak' : 'is-clean'}" id="product-honesty" data-product-honesty="1">
     <div class="design-head">
       <span class="badge design" title="Product honesty — not a score">${esc(headline)}</span>
-      <span class="dim" style="font-size:.86rem">${unfinished ? 'residual honesty signals' : 'no residual honesty blockers'}</span>
+      <span class="dim" style="font-size:.86rem">${esc(subtitle)}</span>
     </div>
     <p style="margin:.45rem 0 0">${esc(body)}</p>
     ${reasonHtml}

package/bin/lib/html-report.mjs

@@ -21,6 +21,9 @@ import {
 } from './html-report-depth.mjs';
 import { FIX_HINTS } from './violations.mjs';
 import { capabilityBadgesFor, renderAdvisorySections } from './html-report-advisories.mjs';
+import { arkGitignoreAppendDecision } from './ark-gitignore.mjs';
+
+export { arkGitignoreAppendDecision, gitignoreCoversArkState, gitignoreHasArkNegationException } from './ark-gitignore.mjs';
 
 export function detectEnforcement(root) {
   const has = (rel) => fs.existsSync(path.join(root, rel));
@@ -336,20 +339,16 @@ export function archiveReportSnapshots(root, { html, snapshot, resetOrigin = fal
     }
   }
 
-  // Ensure .ark/ is gitignored when a .gitignore exists.
+  // EH03: cover .ark reports in .gitignore without defeating ! exceptions.
   const gitignore = path.join(root, '.gitignore');
   if (fs.existsSync(gitignore)) {
     const text = fs.readFileSync(gitignore, 'utf8');
-    const hasArk =
-      text.split('\n').some((line) => {
-        const t = line.trim();
-        return t === '.ark/' || t === '.ark' || t === '/.ark/' || t === '**/.ark/';
-      });
-    if (!hasArk) {
+    const decision = arkGitignoreAppendDecision(text);
+    if (decision.append && decision.rule) {
       const suffix = text.endsWith('\n') || text.length === 0 ? '' : '\n';
       fs.writeFileSync(
         gitignore,
-        `${text}${suffix}\n# Ark generated reports / local state\n.ark/\n`
+        `${text}${suffix}\n# Ark generated reports / local state\n${decision.rule}\n`
       );
     }
   }

package/bin/lib/write-path-detect.mjs

@@ -117,7 +117,7 @@ export function detectWritePathCapabilities(root, explicitHost, attempt) {
         : activeHost === 'opencode'
           ? 'OpenCode local write is advisory (MCP + optional experimental plugin — not a hard boundary; ' +
             'not equivalent to Claude/Grok/Antigravity PreToolUse hard-write). ' +
-            'The hard merge backstop is CI --strict-merge plus a required status check.'
+            'The hard merge backstop is a required GitHub status context running --strict-merge.'
           : `Active host ${activeHost} has advisory prepare-write/autoPatch tools, ` +
             'but no hard write boundary; CI can report failure, while merge blocking requires provider policy.';
     gap = {
@@ -127,7 +127,7 @@ export function detectWritePathCapabilities(root, explicitHost, attempt) {
       message: honesty,
       fix:
         activeHost === 'codex' || activeHost === 'opencode'
-          ? 'Keep CI on --strict-merge and require the ark-check status on the default branch; ' +
+          ? 'Keep a required GitHub status context on arkgate-check --strict-merge (alias ark-check); ' +
             `refresh ${activeHost} MCP/skills with ${arkCommand(root, 'ark-check', `--install-agent-gates --tools ${activeHost}`)}`
           : arkCommand(root, 'ark-check', `--install-agent-gates --tools ${tools}`),
     };