arkgate 4.0.1 → 4.1.1

package/bin/lib/enforcement-honesty.mjs

@@ -3,6 +3,7 @@
  *
  * Pure / fail-closed: never invent hard write guarantees; never paint thin
  * coverage or a dirty freeze as "done." Advisory labels only.
+ * Never invents a numeric architecture score.
  */
 import {
   doctorWritePathHonestyMessage,
@@ -164,35 +165,369 @@ export function buildBaselineHonesty(input = {}) {
 /**
  * Write-path honesty for the active host (fail-closed).
  * Soft hosts never claim hard local write; hard hosts without proof stay unverified.
+ * Never hard:true without package install evidence (and pin when not self-host).
+ *
  * @param {string|null|undefined} activeHost
  * @param {boolean} hardWriteActive
+ * @param {{
+ *   packageInstalled?: boolean,
+ *   packagePinCode?: string | null,
+ *   packagePinAbsent?: boolean,
+ *   selfHost?: boolean,
+ *   motherCli?: boolean,
+ * }} [extras]
  */
-export function buildWritePathHonesty(activeHost, hardWriteActive = false) {
+export function buildWritePathHonesty(activeHost, hardWriteActive = false, extras = {}) {
   const host = typeof activeHost === 'string' ? activeHost.trim().toLowerCase() : '';
   const softWriteHost = SOFT_WRITE_HOSTS.has(host);
   const hardCapable = HARD_WRITE_HOSTS.has(host);
-  const message = doctorWritePathHonestyMessage(host, hardWriteActive);
+  const packageInstalled = extras.packageInstalled !== false;
+  const selfHost = extras.selfHost === true;
+  const motherCli =
+    extras.motherCli === true ||
+    process.env.ARK_MOTHER_CLI === '1' ||
+    process.env.ARK_MOTHER_CLI === 'true';
+  const pinCode = typeof extras.packagePinCode === 'string' ? extras.packagePinCode : null;
+  const pinAbsent =
+    extras.packagePinAbsent === true ||
+    pinCode === 'PACKAGE_PIN_ABSENT';
+  // Self-host / mother library tree: pin-absent is expected (package IS arkgate).
+  const pinAbsentForUser = pinAbsent && !selfHost && !motherCli && pinCode !== 'PACKAGE_PIN_SELF_HOST';
+  // Hard write requires package on disk; pin-absent consumers never get hard:true.
+  const hardAllowed = packageInstalled && !pinAbsentForUser;
+  const effectiveHard =
+    Boolean(hardWriteActive) && hardCapable && !softWriteHost && hardAllowed;
+  const message = doctorWritePathHonestyMessage(host, effectiveHard);
 
-  return {
+  /** @type {Record<string, unknown>} */
+  const out = {
     advisory: true,
     activeHost: host || null,
     softWriteHost,
     hardWriteSupported: hardCapable,
-    hardWriteActive: Boolean(hardWriteActive) && hardCapable && !softWriteHost,
-    hardWriteUnverified: hardCapable && !hardWriteActive,
-    hardMergeBoundary: 'required-ci-status (arkgate-check --strict-merge)',
-    message,
-    // Explicit product rule for soft hosts.
-    ...(softWriteHost
-      ? {
-          note: 'Local write is advisory / best-effort — not a hard PreToolUse boundary. Required CI status is the hard merge boundary.',
-        }
-      : {}),
+    hardWriteActive: effectiveHard,
+    hardWriteUnverified: hardCapable && !effectiveHard,
+    hardMergeBoundary:
+      'required-github-status-context (CLI: arkgate-check --strict-merge / ark-check --strict-merge)',
+    packageInstalled,
+    packagePinAbsent: pinAbsentForUser,
+    ...(pinCode ? { packagePinCode: pinCode } : {}),
+    message:
+      pinAbsentForUser
+        ? `${message} Package pin absent (PACKAGE_PIN_ABSENT) — configured hooks ≠ installed enforcement until arkgate is pinned and in node_modules.`
+        : !packageInstalled && hardCapable
+          ? `${message} arkgate package not resolved from this project — hard write is not proven.`
+          : message,
+  };
+  if (softWriteHost) {
+    out.note =
+      'Local write is advisory / best-effort — not a hard PreToolUse boundary. Required CI status is the hard merge boundary.';
+  }
+  if (pinAbsentForUser) {
+    out.pinNote =
+      'No arkgate pin in package.json; CI/npx may not resolve this CLI version. Ladder/state hard stays false until pin + install.';
+  }
+  return out;
+}
+
+/**
+ * One coherent anti-false-green product surface (P0-B / FG01).
+ * finished is true only when residual honesty sensors are clear AND the graph
+ * + mode are green — never when blocking violations, adapt/suggest residual,
+ * missing baseline with debt, design residual, dual-truth, weak coverage,
+ * pin-absent, or residual pilots remain.
+ *
+ * activeBlockingViolations must be failsStrict !== false counts only
+ * (type-only placement debt must NOT force active-blocking-violations).
+ *
+ * Adapt/suggest policy (documented): unfinished when mode is adapt/suggest
+ * unless whole-tree green AND zero design smells AND zero blocking — contract
+ * and tree still disagree while operating outside enforce.
+ * Never invents a numeric architecture score.
+ *
+ * @param {{
+ *   coverageHonesty?: ReturnType<typeof buildCoverageHonesty>,
+ *   baselineHonesty?: ReturnType<typeof buildBaselineHonesty>,
+ *   writePathHonesty?: ReturnType<typeof buildWritePathHonesty>,
+ *   designWeak?: boolean,
+ *   designWeakLabel?: string | null,
+ *   designSmellCount?: number,
+ *   designSmellsWithOpenEdges?: boolean,
+ *   packageVersionTruth?: {
+ *     dualTruth?: boolean,
+ *     note?: string,
+ *     code?: string,
+ *     cliVersion?: string | null,
+ *   } | null,
+ *   residualPilots?: boolean,
+ *   pilotTarget?: string | null,
+ *   arkRulesMergeHonesty?: Record<string, unknown> | null,
+ *   primaryNextAction?: string | null,
+ *   operatingMode?: string | null,
+ *   activeBlockingViolations?: number | null,
+ * }} input
+ */
+export function buildProductHonesty(input = {}) {
+  const reasons = [];
+  const cov = input.coverageHonesty;
+  const base = input.baselineHonesty;
+  const write = input.writePathHonesty;
+  const designWeak = input.designWeak === true;
+  const dualTruth = input.packageVersionTruth?.dualTruth === true;
+  const pinCode = input.packageVersionTruth?.code || write?.packagePinCode || null;
+  const pinAbsent =
+    write?.packagePinAbsent === true ||
+    pinCode === 'PACKAGE_PIN_ABSENT';
+  const residualPilots = input.residualPilots === true;
+  const operatingMode =
+    typeof input.operatingMode === 'string' ? input.operatingMode.trim().toLowerCase() : null;
+  // Prefer explicit blocking count; never treat raw violation totals (incl. type-only) as blocking.
+  const activeBlocking = Number.isFinite(Number(input.activeBlockingViolations))
+    ? Math.max(0, Number(input.activeBlockingViolations))
+    : Number(base?.activeViolations) || 0;
+  const smellCount = Number(input.designSmellCount) || 0;
+  const designSmellsOpenEdges =
+    input.designSmellsWithOpenEdges === true || (smellCount > 0 && activeBlocking > 0);
+  const wholeTreeGovernedEarly = cov?.wholeTreeGoverned === true;
+
+  if (cov?.status === 'empty-scope' || cov?.worseThanNoGate) {
+    reasons.push({
+      id: 'coverage-weak-or-empty',
+      message: cov.message,
+    });
+  } else if (cov?.greenIsNotEnforcement) {
+    reasons.push({
+      id: 'coverage-partial',
+      message: cov.message,
+    });
+  }
+
+  // FG01 / P0B-FINISHED-WITH-OPEN-DEBT — red graph is never "finished".
+  if (activeBlocking > 0) {
+    reasons.push({
+      id: 'active-blocking-violations',
+      message: `${activeBlocking} active blocking violation(s) remain — not finished; green edges only after debt is cleared or honestly baselined.`,
+    });
+  }
+
+  if (base?.status === 'missing-with-debt') {
+    reasons.push({
+      id: 'baseline-missing-with-debt',
+      message:
+        base.message ||
+        'No baseline while violations exist — freeze only real debt after the contract is honest.',
+    });
+  }
+
+  if (base?.dirtyBaselineRisk) {
+    reasons.push({
+      id: 'dirty-freeze',
+      message: base.message,
+    });
+  }
+
+  if (designWeak) {
+    reasons.push({
+      id: 'design-weak',
+      message:
+        input.designWeakLabel ||
+        'ENFORCE · design-weak: edges may be clean, but design residual remains — not elegant, not finished.',
+    });
+  } else if (designSmellsOpenEdges) {
+    // DL-DESIGN-SMELLS-VS-WEAK — smells + open edges ⇒ unfinished (not "elegant true").
+    reasons.push({
+      id: 'design-smells-open-edges',
+      message:
+        'Design smells present alongside open edge debt — not elegant, not finished. Fix edges first; Shape residual after green.',
+    });
+  }
+
+  if (dualTruth) {
+    reasons.push({
+      id: 'package-version-dual-truth',
+      message:
+        input.packageVersionTruth?.note ||
+        'CLI version and package.json pin disagree — upgrade truth is dual until the pin catches up.',
+    });
+  } else if (pinAbsent) {
+    reasons.push({
+      id: 'package-pin-absent',
+      message:
+        input.packageVersionTruth?.note ||
+        write?.pinNote ||
+        'No arkgate pin in package.json (PACKAGE_PIN_ABSENT) — configured gates ≠ installed enforcement until pin + install.',
+    });
+  }
+
+  if (residualPilots) {
+    reasons.push({
+      id: 'residual-pilot',
+      message: input.pilotTarget
+        ? `Residual pilot remains (${input.pilotTarget}) — one Shape/extraction card at a time; not whole-tree done.`
+        : 'Residual pilot pressure remains — one Shape/extraction card at a time; not whole-tree done.',
+    });
+  }
+
+  // EH05: soft-write-host is a permanent host posture residual — keep in evidence,
+  // do NOT alone force architecture "Not finished". Reclassified out of contract debt.
+  if (write?.softWriteHost) {
+    reasons.push({
+      id: 'soft-write-host',
+      bucket: 'environment',
+      message:
+        write.message ||
+        'Local write is advisory; hard merge boundary = a required GitHub status context running arkgate-check --strict-merge (alias ark-check --strict-merge).',
+    });
+  }
+
+  // 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.
+  if (operatingMode === 'adapt' || operatingMode === 'suggest') {
+    const adaptClear =
+      wholeTreeGovernedEarly &&
+      activeBlocking === 0 &&
+      smellCount === 0 &&
+      !designWeak &&
+      !designSmellsOpenEdges;
+    if (!adaptClear) {
+      reasons.push({
+        id: operatingMode === 'adapt' ? 'mode-adapt-with-debt' : 'mode-suggest-with-debt',
+        message:
+          operatingMode === 'adapt'
+            ? 'Operating mode is ADAPT — not finished until whole-tree green, zero blocking, and zero design smells (contract and tree still disagree).'
+            : 'Operating mode is SUGGEST — not finished until whole-tree green, zero blocking, and zero design smells (contract is not yet the control plane).',
+      });
+    }
+  }
+
+  if (input.arkRulesMergeHonesty?.active === true && input.arkRulesMergeHonesty?.extraMergeTeeth === false) {
+    // Informational only when no enforced arkrule plane — does not alone make unfinished.
+  }
+
+  // EH05: environment residual deny-list (future reason ids stay architecture debt by default).
+  const ENVIRONMENT_REASON_IDS = new Set(['soft-write-host']);
+
+  const environmentResiduals = reasons.filter((r) => ENVIRONMENT_REASON_IDS.has(r.id));
+  const architectureReasons = reasons.filter((r) => !ENVIRONMENT_REASON_IDS.has(r.id));
+  // unfinished = any non-environment residual (deny-list env, not allowlist architecture)
+  const unfinished = architectureReasons.length > 0;
+  const wholeTreeGoverned = wholeTreeGovernedEarly;
+  const coverageIncomplete =
+    cov?.status === 'empty-scope' ||
+    cov?.worseThanNoGate === true ||
+    cov?.greenIsNotEnforcement === true ||
+    !wholeTreeGoverned;
+
+  const softWriteOnly =
+    !unfinished && environmentResiduals.some((r) => r.id === 'soft-write-host');
+  const hostLabel = (() => {
+    const h = typeof write?.activeHost === 'string' ? write.activeHost.trim().toLowerCase() : '';
+    if (h === 'codex') return 'Codex';
+    if (h === 'cursor') return 'Cursor';
+    if (h === 'opencode') return 'OpenCode';
+    if (h) return h;
+    return 'this host';
+  })();
+
+  const primary =
+    architectureReasons.find((r) => r.id === 'active-blocking-violations') ||
+    architectureReasons.find((r) => r.id === 'mode-adapt-with-debt') ||
+    architectureReasons.find((r) => r.id === 'mode-suggest-with-debt') ||
+    architectureReasons.find((r) => r.id === 'design-weak') ||
+    architectureReasons.find((r) => r.id === 'design-smells-open-edges') ||
+    architectureReasons.find((r) => r.id === 'coverage-weak-or-empty') ||
+    architectureReasons.find((r) => r.id === 'dirty-freeze') ||
+    architectureReasons.find((r) => r.id === 'package-version-dual-truth') ||
+    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[0] ||
+    environmentResiduals[0];
+
+  let primaryMessage;
+  if (unfinished) {
+    primaryMessage =
+      primary?.message ||
+      'Not finished: residual honesty signals remain (violations, mode, coverage, freeze, design, package pin, or pilots).';
+  } 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) {
+    primaryMessage =
+      'No residual honesty blockers on this slice — still not a numeric architecture score; re-doctor after material change.';
+  } else {
+    primaryMessage =
+      'No residual honesty blockers flagged — green is only as wide as the governed slice.';
+  }
+
+  // P0B-HEADLINE: dual-truth / pin-only unfinished must not claim "not whole-tree"
+  // when the governed tree is already 100%.
+  // EH05: soft-write alone → composite readiness headline, never global "Not finished".
+  let headline;
+  if (!unfinished && softWriteOnly) {
+    headline = wholeTreeGoverned
+      ? `Architecture contract ready; ${hostLabel} local writes are advisory`
+      : `Contract residual clear; ${hostLabel} local writes are advisory`;
+  } else if (!unfinished) {
+    headline = 'Honesty clear on residual signals';
+  } else if (coverageIncomplete) {
+    headline = 'Not finished / not whole-tree guarantee';
+  } else {
+    headline = 'Not finished';
+  }
+
+  // Prefer caller next action; dual-truth / pin-absent get install/pin path when empty.
+  // Soft-write-only must not leave a failure headline with null next action (EH05).
+  let primaryNextAction = input.primaryNextAction || null;
+  if (!primaryNextAction && dualTruth) {
+    const ver = input.packageVersionTruth?.cliVersion;
+    primaryNextAction = ver
+      ? `Bump package.json arkgate pin to ${ver} (or re-run install without --no-install)`
+      : 'Bump package.json arkgate pin to match this CLI (or re-run install without --no-install)';
+  } else if (!primaryNextAction && pinAbsent) {
+    primaryNextAction =
+      'Add arkgate to package.json and install so CI/npx resolve this CLI (PACKAGE_PIN_ABSENT)';
+  } 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.';
+  }
+
+  const contractReadiness = unfinished ? 'not-ready' : wholeTreeGoverned ? 'ready' : 'partial';
+  const localWriteBoundary = write?.softWriteHost
+    ? 'advisory'
+    : write?.hardWriteActive
+      ? 'hard'
+      : write?.hardWriteSupported
+        ? 'unverified'
+        : 'unknown';
+
+  return {
+    finished: !unfinished && wholeTreeGoverned && !designWeak && activeBlocking === 0,
+    elegant: !designWeak && !base?.dirtyBaselineRisk && !designSmellsOpenEdges && activeBlocking === 0,
+    wholeTreeGuarantee:
+      wholeTreeGoverned &&
+      !designWeak &&
+      !base?.dirtyBaselineRisk &&
+      !cov?.greenIsNotEnforcement &&
+      activeBlocking === 0,
+    unfinished,
+    notAScore: true,
+    // Full evidence including soft-write-host (reclassified, not silenced)
+    reasonIds: reasons.map((r) => r.id),
+    reasons,
+    architectureReasonIds: architectureReasons.map((r) => r.id),
+    environmentResidualIds: environmentResiduals.map((r) => r.id),
+    environmentResiduals,
+    contractReadiness,
+    localWriteBoundary,
+    primaryMessage,
+    primaryNextAction,
+    headline,
   };
 }
 
 /**
- * One-shot doctor honesty bundle (coverage + baseline + write path).
+ * One-shot doctor honesty bundle (coverage + baseline + write path + product surface).
  * Keeps doctor-plan.mjs under its module budget.
  */
 export function computeDoctorEnforcementHonesty({
@@ -202,24 +537,70 @@ export function computeDoctorEnforcementHonesty({
   baselineExists,
   frozenKeys,
   activeViolations,
+  /** failsStrict !== false count only — type-only must not force active-blocking. */
+  activeBlockingViolations,
   suppressed,
   totalViolations,
   activeHost,
   hardWriteActive,
+  designWeak,
+  designWeakLabel,
+  designSmellCount,
+  designSmellsWithOpenEdges,
+  packageVersionTruth,
+  residualPilots,
+  pilotTarget,
+  arkRulesMergeHonesty,
+  primaryNextAction,
+  operatingMode,
+  packageInstalled,
+  selfHost,
+  motherCli,
 } = {}) {
+  const coverageHonesty = buildCoverageHonesty({
+    percent: governedPercent,
+    totalFiles,
+    emptyScope,
+  });
+  const baselineHonesty = buildBaselineHonesty({
+    exists: baselineExists,
+    frozenKeys,
+    activeViolations,
+    suppressed,
+    totalViolations,
+  });
+  const writePathHonesty = buildWritePathHonesty(activeHost, hardWriteActive, {
+    packageInstalled,
+    packagePinCode: packageVersionTruth?.code,
+    packagePinAbsent: packageVersionTruth?.code === 'PACKAGE_PIN_ABSENT',
+    selfHost,
+    motherCli,
+  });
+  // Prefer explicit blocking count; fall back to activeViolations only when callers
+  // already pass blocking-only totals (legacy tests). Type-only must not invent debt.
+  const blockingForHonesty = Number.isFinite(Number(activeBlockingViolations))
+    ? Math.max(0, Number(activeBlockingViolations))
+    : Number(activeViolations) || 0;
+  const productHonesty = buildProductHonesty({
+    coverageHonesty,
+    baselineHonesty,
+    writePathHonesty,
+    designWeak,
+    designWeakLabel,
+    designSmellCount,
+    designSmellsWithOpenEdges,
+    packageVersionTruth,
+    residualPilots,
+    pilotTarget,
+    arkRulesMergeHonesty,
+    primaryNextAction,
+    operatingMode,
+    activeBlockingViolations: blockingForHonesty,
+  });
   return {
-    coverageHonesty: buildCoverageHonesty({
-      percent: governedPercent,
-      totalFiles,
-      emptyScope,
-    }),
-    baselineHonesty: buildBaselineHonesty({
-      exists: baselineExists,
-      frozenKeys,
-      activeViolations,
-      suppressed,
-      totalViolations,
-    }),
-    writePathHonesty: buildWritePathHonesty(activeHost, hardWriteActive),
+    coverageHonesty,
+    baselineHonesty,
+    writePathHonesty,
+    productHonesty,
   };
 }

package/bin/lib/enforcement-state.mjs

@@ -1,2 +1,2 @@
 // Generated from enforcement-state.source.mjs — run npm run generate:packaged-tooling.
-import b from"node:fs";import{createRequire as q}from"node:module";import h from"node:path";const n="unverified";function S(a){const e=h.join(a,"package.json");try{if(JSON.parse(b.readFileSync(e,"utf8"))?.name==="arkgate"&&b.statSync(h.join(a,"bin","ark-check.mjs"),{throwIfNoEntry:!1})?.isFile())return{installed:!0,source:"package.json + bin/ark-check.mjs (self-host)"}}catch{}try{const r=q(e).resolve("arkgate/package.json"),o=h.dirname(r),t=JSON.parse(b.readFileSync(r,"utf8")),l=h.join(o,"bin","ark-check.mjs");if(t?.name==="arkgate"&&b.statSync(l,{throwIfNoEntry:!1})?.isFile())return{installed:!0,source:"arkgate/package.json via project resolver"}}catch{}return{installed:!1,source:"arkgate/package.json unresolved from project"}}function M(a){return a.length>0?a:["filesystem scan (no matching configuration)"]}function y({supported:a,configuredPaths:e,installed:r,active:o,runtimeObserved:t,operation:l,operationCoverage:d,bypassable:u,required:c,hard:i,sources:s}){const p=e.length>0,v=!!r.installed;return{supported:a,analyzed:!0,configured:p,installed:v,active:o,runtimeObserved:t,operation:l,operationCoverage:d,bypassable:u,required:c,hard:i,evidence:[...M(e).map(g=>({field:"configured",source:g,value:p})),{field:"installed",source:r.source,value:v},{field:"active",source:s.active,value:o},{field:"runtimeObserved",source:s.runtimeObserved,value:t},{field:"operationCoverage",source:s.operationCoverage,value:d},{field:"bypassable",source:s.bypassable,value:u},{field:"required",source:s.required,value:c},{field:"hard",source:s.hard,value:i}]}}function O(a,e){const r=S(a),o=!!e.support?.capabilities?.["hard-write"],t=!!e.support?.capabilities?.["advisory-write"],l=e.capabilityEvidence["hard-write"],d=e.capabilityEvidence["advisory-write"],u=e.capabilityEvidence["merge-gate"],c=e.enforcementLadder.localWrite,i=typeof c.operationCovered=="boolean",s=i?c.operationCovered:n,p=i&&s===!0,v=!!(o&&p&&c.hard===!0),g=i?p:o&&l.length>0&&r.installed?n:!1,k=t&&d.length>0&&r.installed?n:!1,f=!!(e.ci?.failClosed&&u.length>0),C=f&&r.installed?n:!1;return{schemaVersion:"1.1",activeHost:e.activeHost,localWrite:y({supported:o,configuredPaths:l,installed:r,active:g,runtimeObserved:i,operation:i?c.operation??null:null,operationCoverage:s,bypassable:v?!1:o&&!i?n:!0,required:n,hard:v,sources:{active:i?"observed PreToolUse attempt":"runtime observation unavailable",runtimeObserved:i?"fresh PreToolUse invocation":"runtime observation unavailable",operationCoverage:i?"active-host operation matcher":"operation not observed",bypassable:v?"observed hard write boundary":"host runtime bypass evidence unavailable",required:"local host policy unavailable",hard:v?"fresh covered active-host invocation":"hardness not proven for this invocation"}}),advisoryMcp:y({supported:t,configuredPaths:d,installed:r,active:k,runtimeObserved:!1,operation:null,operationCoverage:n,bypassable:!0,required:n,hard:!1,sources:{active:"MCP runtime observation unavailable",runtimeObserved:"doctor did not observe an MCP tool invocation",operationCoverage:"advisory MCP is caller-invoked",bypassable:"advisory MCP does not intercept every write",required:"local host policy unavailable",hard:"MCP presence is advisory and never proves a hard boundary"}}),ciMerge:y({supported:!0,configuredPaths:f?u:[],installed:r,active:C,runtimeObserved:!1,operation:"merge",operationCoverage:f?n:!1,bypassable:f?n:!0,required:n,hard:!1,sources:{active:"CI run and provider enforcement not observed",runtimeObserved:"provider evidence unavailable",operationCoverage:"required-status operation coverage unavailable",bypassable:"branch-protection evidence unavailable",required:"branch-protection evidence unavailable",hard:"merge hardness requires fresh provider evidence"}})}}function w(a,e,r,o){return{...a,...o,evidence:[...a.evidence.filter(t=>!e.includes(t.field)),...e.map(t=>({field:t,source:r,value:o[t]}))]}}function x(a,e){if(!e?.available)return a;const r=typeof e.arkCheckRequired=="boolean"?e.arkCheckRequired:n,o=!!(a.enforcementState.ciMerge.configured&&a.enforcementState.ciMerge.installed),t=r===!0?o:r===!1?!1:o?n:!1,l=t===!0?e.arkCheckSourceBound===!1?!0:n:r===!1?!0:o?n:!0,d=`GitHub branch protection (${e.repo??"repository"}:${e.branch??"default"})`,u=!0,c=r,i=t===!0&&l===!1&&c===!0,s=w(a.enforcementState.ciMerge,["active","runtimeObserved","operationCoverage","bypassable","required","hard"],d,{active:t,runtimeObserved:u,operationCoverage:c,bypassable:l,required:r,hard:i});return{...a,enforcementState:{...a.enforcementState,ciMerge:s},enforcementLadder:{...a.enforcementLadder,ciMerge:{...a.enforcementLadder.ciMerge,requiredStatus:r}}}}function m(a,e){const r=o=>o===!0?"yes":o===!1?"no":String(o);return`${a} \u2014 supported: ${r(e.supported)} \xB7 analyzed: ${r(e.analyzed)} \xB7 configured: ${r(e.configured)} \xB7 installed: ${r(e.installed)} \xB7 runtime observed: ${r(e.runtimeObserved)} \xB7 operation: ${e.operation??"none"} \xB7 operation covered: ${r(e.operationCoverage)} \xB7 active: ${r(e.active)} \xB7 bypassable: ${r(e.bypassable)} \xB7 required: ${r(e.required)} \xB7 hard: ${r(e.hard)}`}function P(a){const e=[{level:a.localWrite.active===!0?"ok":"warn",text:m("Local write",a.localWrite)},{level:"warn",text:m("Advisory MCP",a.advisoryMcp)},{level:a.ciMerge.required===!0?"ok":"warn",text:m("CI merge",a.ciMerge)}];return a.localWrite.active===n&&a.localWrite.hard===!1&&e.push({level:"bad",text:"RED FLAG: local hook assets exist, but this active-host operation was not observed at runtime; hard blocking is unverified."}),a.activeHost==="unknown"&&e.push({level:"warn",text:"Active host unknown for this invocation \u2014 enforcementState is session projection only. See writePath.inventory for on-disk host hooks; hard write is never claimed without runtime proof."}),e}export{O as buildEnforcementState,P as enforcementDoctorLines,x as withCiProviderEvidence};
+import m from"node:fs";import{createRequire as q}from"node:module";import h from"node:path";const n="unverified";function S(a){const e=h.join(a,"package.json");try{if(JSON.parse(m.readFileSync(e,"utf8"))?.name==="arkgate"&&m.statSync(h.join(a,"bin","ark-check.mjs"),{throwIfNoEntry:!1})?.isFile())return{installed:!0,source:"package.json + bin/ark-check.mjs (self-host)",selfHost:!0}}catch{}try{const r=q(e).resolve("arkgate/package.json"),o=h.dirname(r),i=JSON.parse(m.readFileSync(r,"utf8")),s=h.join(o,"bin","ark-check.mjs");if(i?.name==="arkgate"&&m.statSync(s,{throwIfNoEntry:!1})?.isFile())return{installed:!0,source:"arkgate/package.json via project resolver",selfHost:!1}}catch{}return{installed:!1,source:"arkgate/package.json unresolved from project",selfHost:!1}}function M(a){return a.length>0?a:["filesystem scan (no matching configuration)"]}function g({supported:a,configuredPaths:e,installed:r,active:o,runtimeObserved:i,operation:s,operationCoverage:v,bypassable:u,required:c,hard:t,sources:l}){const p=e.length>0,d=!!r.installed;return{supported:a,analyzed:!0,configured:p,installed:d,active:o,runtimeObserved:i,operation:s,operationCoverage:v,bypassable:u,required:c,hard:t,evidence:[...M(e).map(f=>({field:"configured",source:f,value:p})),{field:"installed",source:r.source,value:d},{field:"active",source:l.active,value:o},{field:"runtimeObserved",source:l.runtimeObserved,value:i},{field:"operationCoverage",source:l.operationCoverage,value:v},{field:"bypassable",source:l.bypassable,value:u},{field:"required",source:l.required,value:c},{field:"hard",source:l.hard,value:t}]}}function O(a,e){const r=S(a),o=!!e.support?.capabilities?.["hard-write"],i=!!e.support?.capabilities?.["advisory-write"],s=e.capabilityEvidence["hard-write"],v=e.capabilityEvidence["advisory-write"],u=e.capabilityEvidence["merge-gate"],c=e.enforcementLadder.localWrite,t=typeof c.operationCovered=="boolean",l=t?c.operationCovered:n,p=t&&l===!0,d=!!(o&&r.installed&&p&&c.hard===!0),f=t?p&&r.installed:o&&s.length>0&&r.installed?n:!1,b=i&&v.length>0&&r.installed?n:!1,y=!!(e.ci?.failClosed&&u.length>0),C=y&&r.installed?n:!1;return{schemaVersion:"1.1",activeHost:e.activeHost,localWrite:g({supported:o,configuredPaths:s,installed:r,active:f,runtimeObserved:t,operation:t?c.operation??null:null,operationCoverage:l,bypassable:d?!1:o&&!t?n:!0,required:n,hard:d,sources:{active:t?"observed PreToolUse attempt":"runtime observation unavailable",runtimeObserved:t?"fresh PreToolUse invocation":"runtime observation unavailable",operationCoverage:t?"active-host operation matcher":"operation not observed",bypassable:d?"observed hard write boundary":"host runtime bypass evidence unavailable",required:"local host policy unavailable",hard:d?"fresh covered active-host invocation":"hardness not proven for this invocation"}}),advisoryMcp:g({supported:i,configuredPaths:v,installed:r,active:b,runtimeObserved:!1,operation:null,operationCoverage:n,bypassable:!0,required:n,hard:!1,sources:{active:"MCP runtime observation unavailable",runtimeObserved:"doctor did not observe an MCP tool invocation",operationCoverage:"advisory MCP is caller-invoked",bypassable:"advisory MCP does not intercept every write",required:"local host policy unavailable",hard:"MCP presence is advisory and never proves a hard boundary"}}),ciMerge:g({supported:!0,configuredPaths:y?u:[],installed:r,active:C,runtimeObserved:!1,operation:"merge",operationCoverage:y?n:!1,bypassable:y?n:!0,required:n,hard:!1,sources:{active:"CI run and provider enforcement not observed",runtimeObserved:"provider evidence unavailable",operationCoverage:"required-status operation coverage unavailable",bypassable:"branch-protection evidence unavailable",required:"branch-protection evidence unavailable",hard:"merge hardness requires fresh provider evidence"}})}}function $(a,e,r,o){return{...a,...o,evidence:[...a.evidence.filter(i=>!e.includes(i.field)),...e.map(i=>({field:i,source:r,value:o[i]}))]}}function R(a,e){if(!e)return a;const r=e.reason==="provider-policy-unavailable-plan"||e.policyReason==="unavailable-plan",o=e.available===!0,i=!o&&!r&&(e.reason==="provider-enforcement-unverified"||e.reason==="gh-cli-unavailable"||e.reason==="gh-repo-unavailable"||!!e.reason);if(!o&&e.runtimeObserved!==!0&&!r&&!i)return a;const s=o?typeof e.arkCheckRequired=="boolean"?e.arkCheckRequired:n:r?!1:n,v=!!(a.enforcementState.ciMerge.configured&&a.enforcementState.ciMerge.installed),u=s===!0?v:s===!1?!1:v?n:!1,c=u===!0?e.arkCheckSourceBound===!1?!0:n:s===!1?!0:v?n:!0,t=e.runtimeObserved===!0,l=o?`GitHub branch protection (${e.repo??"repository"}:${e.branch??"default"})`:r?`GitHub provider policy unavailable (plan) (${e.repo??"repository"}:${e.branch??"default"})`:`GitHub CI runtime (${e.repo??"repository"})`,p=s,d=u===!0&&c===!1&&p===!0,f=$(a.enforcementState.ciMerge,["active","runtimeObserved","operationCoverage","bypassable","required","hard"],l,{active:u,runtimeObserved:t,operationCoverage:p,bypassable:c,required:s,hard:d}),b={...a,enforcementState:{...a.enforcementState,ciMerge:f},enforcementLadder:{...a.enforcementLadder,ciMerge:{...a.enforcementLadder.ciMerge,requiredStatus:s,...e.latestCiRun?{latestCiRun:e.latestCiRun}:{},...r?{providerPolicy:"unavailable-plan"}:{}}}};return(r||e.reason)&&(b.providerEnforcement={available:o,reason:e.reason||(r?"provider-policy-unavailable-plan":"provider-enforcement-unverified"),policyReason:e.policyReason||(r?"unavailable-plan":null),runtimeObserved:t,latestCiRun:e.latestCiRun??null,hard:d===!0}),b}function k(a,e){const r=o=>o===!0?"yes":o===!1?"no":String(o);return`${a} \u2014 supported: ${r(e.supported)} \xB7 analyzed: ${r(e.analyzed)} \xB7 configured: ${r(e.configured)} \xB7 installed: ${r(e.installed)} \xB7 runtime observed: ${r(e.runtimeObserved)} \xB7 operation: ${e.operation??"none"} \xB7 operation covered: ${r(e.operationCoverage)} \xB7 active: ${r(e.active)} \xB7 bypassable: ${r(e.bypassable)} \xB7 required: ${r(e.required)} \xB7 hard: ${r(e.hard)}`}function x(a){const e=[{level:a.localWrite.active===!0?"ok":"warn",text:k("Local write",a.localWrite)},{level:"warn",text:k("Advisory MCP",a.advisoryMcp)},{level:a.ciMerge.required===!0?"ok":"warn",text:k("CI merge",a.ciMerge)}];return a.localWrite.active===n&&a.localWrite.hard===!1&&e.push({level:"bad",text:"RED FLAG: local hook assets exist, but this active-host operation was not observed at runtime; hard blocking is unverified."}),a.activeHost==="unknown"&&e.push({level:"warn",text:"Active host unknown for this invocation \u2014 enforcementState is session projection only. See writePath.inventory for on-disk host hooks; hard write is never claimed without runtime proof."}),e}export{O as buildEnforcementState,x as enforcementDoctorLines,S as packageInstallation,R as withCiProviderEvidence};

package/bin/lib/field-install.mjs

@@ -221,6 +221,22 @@ export function readDeclaredArkgatePin(root) {
   }
 }
 
+/**
+ * True when this tree *is* the arkgate package (mother / self-host dogfood).
+ * Consumers never match: they depend on arkgate; they are not named arkgate with bin/.
+ * @param {string} root
+ */
+export function isArkgateSelfHostRoot(root) {
+  try {
+    const pkgPath = path.join(root, 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    if (pkg?.name !== 'arkgate') return false;
+    return fs.statSync(path.join(root, 'bin', 'ark-check.mjs'), { throwIfNoEntry: false })?.isFile() === true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Dual-truth: CLI/package-shipped version vs consumer package.json pin.
  * Used by doctor + upgrade so agents never confuse managed-asset CLI with CI pin.
@@ -231,8 +247,9 @@ export function readDeclaredArkgatePin(root) {
  *   dualTruth: boolean,
  *   cliVersion: string|null,
  *   declaredPin: string|null,
- *   code: 'PACKAGE_PIN_BEHIND_CLI' | 'PACKAGE_PIN_MATCHES' | 'PACKAGE_PIN_ABSENT' | 'CLI_VERSION_UNKNOWN',
- *   note: string
+ *   code: 'PACKAGE_PIN_BEHIND_CLI' | 'PACKAGE_PIN_MATCHES' | 'PACKAGE_PIN_ABSENT' | 'PACKAGE_PIN_SELF_HOST' | 'CLI_VERSION_UNKNOWN',
+ *   note: string,
+ *   selfHost?: boolean,
  * }}
  */
 export function describePackageVersionDualTruth(root, opts = {}) {
@@ -241,6 +258,7 @@ export function describePackageVersionDualTruth(root, opts = {}) {
       ? opts.cliVersion
       : arkPackageVersion();
   const declaredPin = readDeclaredArkgatePin(root);
+  const selfHost = isArkgateSelfHostRoot(root);
   if (!cliVersion) {
     return {
       dualTruth: false,
@@ -248,15 +266,28 @@ export function describePackageVersionDualTruth(root, opts = {}) {
       declaredPin,
       code: 'CLI_VERSION_UNKNOWN',
       note: 'Could not read shipped arkgate package version for this CLI.',
+      selfHost,
     };
   }
   if (!declaredPin) {
+    // Mother / library author tree: package IS arkgate — no consumer pin required.
+    if (selfHost || process.env.ARK_MOTHER_CLI === '1' || process.env.ARK_MOTHER_CLI === 'true') {
+      return {
+        dualTruth: false,
+        cliVersion,
+        declaredPin: null,
+        code: 'PACKAGE_PIN_SELF_HOST',
+        note: 'This tree is arkgate itself (self-host); no consumer package.json pin is required.',
+        selfHost: true,
+      };
+    }
     return {
       dualTruth: false,
       cliVersion,
       declaredPin: null,
       code: 'PACKAGE_PIN_ABSENT',
       note: 'No arkgate pin in package.json; CI/npx may not resolve this CLI version.',
+      selfHost: false,
     };
   }
   // Normalize ^x.y.z / ~x.y.z / x.y.z for comparison of leading version token.
@@ -294,6 +325,7 @@ export function describePackageVersionDualTruth(root, opts = {}) {
       declaredPin,
       code: 'PACKAGE_PIN_BEHIND_CLI',
       note: `Managed CLI is arkgate@${cliVersion} but package.json pins ${declaredPin}. Bump the pin or re-run install so CI resolves the same version (common after upgrade --no-install).`,
+      selfHost,
     };
   }
   return {
@@ -302,6 +334,7 @@ export function describePackageVersionDualTruth(root, opts = {}) {
     declaredPin,
     code: 'PACKAGE_PIN_MATCHES',
     note: `package.json pin ${declaredPin} is aligned with CLI arkgate@${cliVersion}.`,
+    selfHost,
   };
 }