arkgate 3.6.1 → 3.8.0

package/bin/lib/design-smells.mjs

@@ -29,7 +29,7 @@ export const DESIGN_SMELL_OUTCOMES = Object.freeze({
   'io-under-application':
     'Business/application code reaches the database or external APIs directly — the AI will keep pasting I/O into the wrong place. Put data access behind a port/adapter.',
   'handler-in-persistence':
-    'HTTP handlers live under data/repository folders — names look like “storage” but they are routes. Move handlers to the API/UI layer so the AI stops mixing transport and storage.',
+    'Static framework HTTP imports or route definitions live under data/repository folders — names look like “storage” but the code still owns transport. Move HTTP handling to the API/UI layer so the AI stops mixing transport and storage.',
   'god-module':
     'A few huge files own too many responsibilities — the AI cannot safely edit one concern without breaking others. Split the pilot file by job (one export surface per concern).',
   'domain-logic-in-ui':
@@ -70,6 +70,12 @@ const IO_IMPORT_RE =
   /\bfrom\s+['"](?:@?prisma\/client|@supabase\/|drizzle-orm|typeorm|knex|mongodb|pg|mysql2|better-sqlite3|ioredis|redis)['"]|require\(\s*['"](?:@?prisma\/client|pg|knex|typeorm)/;
 const HANDLER_CONTENT_RE =
   /\b(?:@Controller|@Get|@Post|@Put|@Delete|Router\(\)|createRouter|express\.Router|fastify\.(?:get|post)|export\s+(?:async\s+)?function\s+(?:GET|POST|PUT|DELETE|PATCH)\b|export\s+const\s+(?:GET|POST|PUT|DELETE|PATCH)\s*=)/;
+const FRAMEWORK_HTTP_IMPORT_RE =
+  /(?:^|[;\n])\s*(?:import\s+(?:type\s+)?(?:[^;]{0,512}?\s+from\s+)?|export\s+(?:type\s+)?[^;]{0,512}?\s+from\s+)['"]next\/server(?:\.js)?['"]/;
+const ROUTE_DEFINITION_CALL_RE =
+  /\bdefineRoute\s*(?:<[\s\S]{1,512}?>)?\s*\(/;
+const ROUTE_DEFINITION_DECLARATION_RE =
+  /\b(?:export\s+)?(?:declare\s+)?(?:async\s+)?function\s+defineRoute\s*(?:<[\s\S]{1,512}?>)?\s*\(/g;
 const DOMAIN_LOGIC_UI_RE =
   /\b(?:export\s+)?(?:async\s+)?function\s+(?:can|calculate|compute|should)[A-Z]\w*|\b(?:export\s+)?const\s+(?:can|calculate|compute|should)[A-Z]\w*\s*=/;
 const EXPORT_RE =
@@ -139,7 +145,33 @@ function isPresentationLayer(name) {
 function isPersistenceLayer(name) {
   return (
     typeof name === 'string' &&
-    (/persist|repository|infra|data.?access/i.test(name) || name === 'PersistenceAdapters')
+    /persist|repository|data.?access/i.test(name)
+  );
+}
+
+function stripObviousCommentsAndTemplates(source) {
+  return source
+    .replace(/\/\*[\s\S]*?\*\//g, ' ')
+    .replace(/\/\/[^\n]*/g, ' ')
+    .replace(/`(?:\\[\s\S]|[^\\`])*`/g, ' ');
+}
+
+function hasFrameworkHttpImport(source) {
+  return FRAMEWORK_HTTP_IMPORT_RE.test(stripObviousCommentsAndTemplates(source));
+}
+
+function hasRouteDefinitionCall(source) {
+  const code = stripObviousCommentsAndTemplates(source)
+    .replace(/(["'])(?:\\.|(?!\1)[^\\\r\n])*\1/g, ' ')
+    .replace(ROUTE_DEFINITION_DECLARATION_RE, 'function __ark_defineRoute_declaration__(');
+  return ROUTE_DEFINITION_CALL_RE.test(code);
+}
+
+function hasHollowPersistenceShape(source) {
+  return (
+    hasFrameworkHttpImport(source) ||
+    hasRouteDefinitionCall(source) ||
+    HANDLER_CONTENT_RE.test(source)
   );
 }
 
@@ -172,6 +204,24 @@ export function detectDesignSmells(root, config, files = [], coverage = null) {
     if (rel.includes('node_modules/') || rel.endsWith('.d.ts')) continue;
     relFiles.push(rel);
   }
+  // Y02: the general scan cap must not hide Persistence candidates in large
+  // trees. Filter by the stable role/path heuristics first, then bound reads.
+  const persistenceUniverse = [];
+  for (const f of files) {
+    const rel = normalizeRel(resolvedRoot, f);
+    if (!rel || rel.startsWith('..')) continue;
+    if (!/\.(ts|tsx|js|jsx|mts|cts)$/.test(rel)) continue;
+    if (rel.includes('node_modules/') || rel.endsWith('.d.ts')) continue;
+    persistenceUniverse.push(rel);
+  }
+  const allPersistenceCandidates = [...new Set(persistenceUniverse)].sort().filter(
+    (rel) =>
+      PERSISTENCE_PATH_RE.test(rel) ||
+      isPersistenceLayer(layerNameFor(resolvedRoot, rel, config))
+  );
+  const persistenceCandidates = allPersistenceCandidates.slice(0, MAX_SCAN_FILES);
+  const persistenceCandidatesTruncated =
+    allPersistenceCandidates.length - persistenceCandidates.length;
 
   // soft-contract: layers with files but no rule edges
   const withoutRules = Array.isArray(coverage?.layersWithoutRules)
@@ -220,8 +270,7 @@ export function detectDesignSmells(root, config, files = [], coverage = null) {
     }
     if (/\/(?:domain|application|infrastructure|adapters)\//.test(rel)) hasHexPorts = true;
 
-    const abs = path.join(resolvedRoot, rel);
-    const source = readTextLimited(abs);
+    const source = readTextLimited(path.join(resolvedRoot, rel));
     if (source == null) continue;
 
     const layer = layerNameFor(resolvedRoot, rel, config);
@@ -232,13 +281,6 @@ export function detectDesignSmells(root, config, files = [], coverage = null) {
       godEvidence.push(rel);
     }
 
-    if (
-      (PERSISTENCE_PATH_RE.test(rel) || isPersistenceLayer(layer)) &&
-      HANDLER_CONTENT_RE.test(source)
-    ) {
-      handlerInPersist.push(rel);
-    }
-
     if ((UI_PATH_RE.test(rel) || isPresentationLayer(layer)) && DOMAIN_LOGIC_UI_RE.test(source)) {
       domainInUi.push(rel);
     }
@@ -257,6 +299,13 @@ export function detectDesignSmells(root, config, files = [], coverage = null) {
     }
   }
 
+  for (const rel of persistenceCandidates) {
+    const source = readTextLimited(path.join(resolvedRoot, rel));
+    if (source != null && hasHollowPersistenceShape(source)) {
+      handlerInPersist.push(rel);
+    }
+  }
+
   if (!falseGreen?.risk && ioUnderAppFiles.length > 0) {
     smells.push(
       makeDesignSmell({
@@ -270,13 +319,17 @@ export function detectDesignSmells(root, config, files = [], coverage = null) {
   }
 
   if (handlerInPersist.length > 0) {
+    const capNote =
+      persistenceCandidatesTruncated > 0
+        ? `; ${persistenceCandidatesTruncated} more Persistence candidate(s) were not inspected by the bounded scan`
+        : '';
     smells.push(
       makeDesignSmell({
         id: 'handler-in-persistence',
         severity: 'warn',
-        message: `HTTP/route handler shape found under persistence/repository paths (${handlerInPersist.length} file(s)) — semantic false-green risk.`,
+        message: `Static framework HTTP import or route-definition/handler shape found in Persistence-role modules (${handlerInPersist.length} file(s)${capNote}) — semantic false-green risk.`,
         evidence: handlerInPersist.slice(0, 12),
-        fix: 'Move handlers to Presentation/API; keep Persistence as data access only (/ark-explore shape-focus).',
+        fix: 'Move HTTP imports and route definitions to Presentation/API; keep Persistence as data access only (/ark-explore shape-focus).',
       })
     );
   }
@@ -414,7 +467,7 @@ function successSignalFor(id) {
     case 'io-under-application':
       return '0 Application-layer files import prisma/supabase/drizzle/pg clients; I/O behind ports';
     case 'handler-in-persistence':
-      return '0 HTTP handler shapes under persistence/repository globs';
+      return '0 static framework HTTP imports or route-definition/handler shapes in Persistence-role modules';
     case 'god-module':
       return 'Pilot god module split; fan-in and export surface reduced without new edge violations';
     case 'domain-logic-in-ui':

package/bin/lib/doctor-advisories.mjs

@@ -1,24 +1,38 @@
 /**
- * Doctor's advisory sensors, aggregated (W01 contract health + U05 ambient
- * state + X04 physical cohesion). Advisory only: nothing here feeds a
- * verdict, designFitness, or an exit code. One seam keeps doctor-plan.mjs
- * inside its module budget as new advisory surfaces land.
+ * Doctor's advisory sensors, aggregated (W01 contract health, U05 ambient
+ * state, X04 physical cohesion, Y03 parse health). These sensors do not create
+ * architecture violations or designFitness findings; Z02 separately maps
+ * parse-health evidence to analysis completeness and fail-closed exits. One
+ * seam keeps doctor-plan.mjs inside its module budget as new surfaces land.
  */
 import { computeAmbientState, printAmbientStateSection } from './ambient-state.mjs';
 import { computeContractHealth, printContractHealthSection } from './contract-smells.mjs';
 import {
   computePhysicalCohesion,
-  computeReshapePilot,
   printPhysicalCohesionSection,
 } from './physical-cohesion.mjs';
+import {
+  computeDecisionAwareReshapePilot,
+  computeReshapeDecisionMemory,
+  printReshapeDecisionsSection,
+} from './reshape-decisions.mjs';
+import { printParseHealthSection, summarizeParseHealth } from './parse-health.mjs';
 
-export function computeDoctorAdvisories(root, config, cov, rules, files, ts) {
+export function computeDoctorAdvisories(root, config, cov, rules, files, ts, parseHealth) {
   const physicalCohesion = computePhysicalCohesion(root, files);
-  physicalCohesion.reshapePilot = computeReshapePilot(physicalCohesion, files, root);
+  const decisionMemory = computeReshapeDecisionMemory(root, files);
+  physicalCohesion.reshapeDecisions = decisionMemory.summary;
+  physicalCohesion.reshapePilot = computeDecisionAwareReshapePilot(
+    physicalCohesion,
+    files,
+    root,
+    decisionMemory
+  );
   return {
     contractHealth: computeContractHealth(root, config, cov, rules),
     ambientState: computeAmbientState(ts, root, config, files),
     physicalCohesion,
+    parseHealth: parseHealth ?? summarizeParseHealth(),
   };
 }
 
@@ -30,4 +44,6 @@ export function printDoctorAdvisories(advisories, io) {
     advisories.physicalCohesion?.reshapePilot,
     io
   );
+  printReshapeDecisionsSection(advisories.physicalCohesion?.reshapeDecisions, io);
+  printParseHealthSection(advisories.parseHealth, io);
 }

package/bin/lib/doctor-plan.mjs

@@ -1,6 +1,4 @@
-/**
- * Coverage, plan, and doctor CLI surfaces (roadmap #11).
- */
+/** Coverage, plan, and doctor CLI surfaces (roadmap #11). */
 import fs from 'node:fs';
 import path from 'node:path';
 import {
@@ -41,6 +39,9 @@ import {
 import { loadGoldenPattern, summarizeGoldenPattern } from './golden-pattern.mjs';
 import { summarizePilotLoop } from './pilot-loop.mjs';
 import { computeDoctorAdvisories, printDoctorAdvisories } from './doctor-advisories.mjs';
+import { ANALYSIS_COMPLETENESS, analysisIncompleteStatement, normalizeAnalysisCompleteness } from './analysis-completeness.mjs';
+import { designDeltaDoctorLines } from './design-delta.mjs';
+import { enforcementDoctorLines } from './enforcement-state.mjs';
 
 const color = {
   green: (s) => `\x1b[32m${s}\x1b[0m`,
@@ -49,12 +50,10 @@ const color = {
   dim: (s) => `\x1b[2m${s}\x1b[0m`,
   bold: (s) => `\x1b[1m${s}\x1b[0m`,
 };
-
 function normalize(value) {
   return String(value).split(path.sep).join('/');
 }
 
-
 export function computeCoverage(root, config, files, rules) {
   const layers = config.layers ?? [];
   const counts = new Map(layers.map((layer) => [layer.name, 0]));
@@ -154,9 +153,6 @@ export function runCoverage(root, config, files, rules, asJson) {
 // --doctor: one consolidated health view — coverage, violations, gates, skills, baseline,
 // and command runners — each with the exact command to fix it. Folds the data the other
 // modes already produce so a team sees "what state is my Ark adoption in?" at a glance.
-// Co-pilot Phase F — turn active violations into a classified, ordered remediation PLAN with an
-// embedded GOAL. This is the `plan` primitive the future apply-loop (Phase H, `loop`) consumes
-// and the autopilot (Phase I) drives toward the `goal`. Read-only: it changes no files.
 /**
  * @param {string} root
  * @param {object[]} activeViolations
@@ -176,11 +172,10 @@ export function buildRemediationPlan(
   totalFiles = null,
   options = {}
 ) {
-  // A plan with 0 violations but ~0% governed (or ZERO files in scope) is a FALSE green:
-  // nothing is actually being checked. Treat as "not done — classify / fix include first."
+  const completeness = normalizeAnalysisCompleteness(options.completeness);
   const governedLow = governedPercent != null && governedPercent < 50;
   const emptyScope = totalFiles === 0;
-  const notHonestlyEnforced = governedLow || emptyScope;
+  const notHonestlyEnforced = governedLow || emptyScope || completeness !== ANALYSIS_COMPLETENESS.complete;
   const steps = activeViolations.map((v, index) => {
     const verdict = classifyRemediation(v);
     return {
@@ -249,9 +244,11 @@ export function buildRemediationPlan(
     statement =
       'No active edge violations — contract edges are clean, but design smells remain (ENFORCE · design-weak). Shape residual is plan B only; not healthy finished.';
   }
+  if (completeness !== ANALYSIS_COMPLETENESS.complete) statement = analysisIncompleteStatement(completeness);
 
   return {
     version: '1',
+    completeness,
     goal: {
       statement,
       // Edge remediation termination (Phase H). Design-weak does NOT flip met false
@@ -378,6 +375,8 @@ export function runPlan(
 }
 
 export function runDoctor(root, config, files, rules, violations, asJson, options = {}) {
+  const completeness = normalizeAnalysisCompleteness(options.completeness);
+  const analysisComplete = completeness === ANALYSIS_COMPLETENESS.complete;
   const cov = computeCoverage(root, config, files, rules);
   const summary = summarizeViolations(violations);
   const configPath = options.configPath ?? path.join(root, 'ark.config.json');
@@ -408,11 +407,14 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     : 0;
   const activeCount = violations.length - suppressed;
   const designSmells = detectDesignSmells(root, config, files, cov);
-  const designFitness = summarizeDesignFitness(designSmells, {
+  const observedDesignFitness = summarizeDesignFitness(designSmells, {
     activeViolations: activeCount,
     governedPercent: cov.governed.percent,
     totalFiles: cov.governed.totalFiles,
   });
+  const designFitness = analysisComplete ? observedDesignFitness : {
+    ...observedDesignFitness, status: 'analysis-incomplete', designWeak: false, label: 'Design fitness not verified — analysis is incomplete; observed smells remain advisory.',
+  };
   // Q01 — single post-green door when design-weak (map → B; no skill shopping).
   const postGreenPath = buildPostGreenNextAction(designFitness);
   // Q03 — optional golden pattern for NEW code (advisory; never clears design-weak).
@@ -424,17 +426,18 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     patternBets: patternBetsForLoop,
     designSmells,
   });
-  const { contractHealth, ambientState, physicalCohesion } = computeDoctorAdvisories(root, config, cov, rules, files, options.ts); // W01+U05+X04 advisories — never a verdict
+  const doctorAdvisories = computeDoctorAdvisories(root, config, cov, rules, files, options.ts, options.parseHealth);
 
   if (asJson) {
-    console.log(
+    (options.writeJson ?? console.log)(
       JSON.stringify(
         {
-          ok: true,
+          ok: analysisComplete && (options.designDelta?.valid ?? true),
           doctor: {
+            completeness,
             operatingMode: resolveOperatingMode({
               governedPercent: cov.governed.percent,
-              planMet: activeCount === 0 && cov.governed.percent >= 50,
+              planMet: analysisComplete && activeCount === 0 && cov.governed.percent >= 50,
               mature: cov.governed.totalFiles >= 150,
               totalFiles: cov.governed.totalFiles,
               emptyLayers: cov.emptyLayers,
@@ -449,6 +452,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             // Path-correct ENFORCE can still be design-weak (P02).
             designFitness,
             designSmells,
+            ...(options.designDelta ? { designDelta: options.designDelta } : {}),
             // Q01: primary next action when Shape residual dominates (null if not design-weak).
             postGreenPath,
             ...(postGreenPath
@@ -461,11 +465,9 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             goldenPattern,
             // Q04: one-pilot loop (extraction card → re-doctor).
             pilotLoop,
-            // Advisories, never a verdict: W01 contract health, U05 ambient
-            // state (opt-in), X04 physical cohesion + proposed reshape pilot.
-            contractHealth,
-            ambientState,
-            physicalCohesion,
+            // Advisories, never a verdict: W01 contract health, U05 ambient state,
+            // X04 physical cohesion/reshape pilot, Y03 parse health.
+            ...doctorAdvisories,
             governed: cov.governed,
             emptyLayers: cov.emptyLayers,
             layersWithoutRules: cov.layersWithoutRules,
@@ -483,13 +485,12 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             baseline: {
               exists: baseline.exists,
               frozen: baseline.exists ? baseline.keys.size : 0,
-              stale: staleBaseline,
+              stale: analysisComplete ? staleBaseline : null,
               policy: adoption.baseline,
             },
             gatesMissing,
             skillGaps,
             staleRunnerFiles: staleRunners,
-            // Active-host guarantees plus separate repo-wide inventory.
             writePath: {
               activeHost: writePath.activeHost,
               support: writePath.support,
@@ -498,6 +499,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
               capabilityEvidence: writePath.capabilityEvidence,
               inventory: writePath.inventory,
               enforcementLadder: writePath.enforcementLadder,
+              enforcementState: writePath.enforcementState,
               mode: writePath.mode,
               prepareWrite: writePath.prepareWrite,
               autoPatch: writePath.autoPatch,
@@ -546,16 +548,16 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   const bad = color.red('✗');
   const actions = [];
   const line = (mark, text) => console.log(`  ${mark} ${text}`);
-
+  if (!analysisComplete) actions.push('restore complete analysis, then rerun ark-check --doctor');
   console.log(color.bold(`Ark doctor — ${path.basename(path.resolve(root)) || '.'}`));
+  if (!analysisComplete) line(warn, analysisIncompleteStatement(completeness));
 
   const emptyScope = cov.governed.totalFiles === 0;
   const totalFiles = cov.governed.totalFiles || 0;
   const presentationRow = cov.layers.find((r) => r.name === 'PresentationAdapters');
   const mode = resolveOperatingMode({
     governedPercent: emptyScope ? 0 : cov.governed.percent,
-    planMet:
-      activeCount === 0 && !emptyScope && cov.governed.percent >= 50,
+    planMet: analysisComplete && activeCount === 0 && !emptyScope && cov.governed.percent >= 50,
     mature: cov.governed.totalFiles >= 150,
     totalFiles: cov.governed.totalFiles,
     emptyLayers: cov.emptyLayers,
@@ -597,7 +599,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   console.log('');
   console.log(color.bold('Design fitness'));
   if (designSmells.length === 0) {
-    line(ok, designFitness.label);
+    line(analysisComplete ? ok : warn, designFitness.label);
   } else {
     line(designFitness.designWeak ? warn : warn, designFitness.label);
     for (const smell of designSmells.slice(0, 5)) {
@@ -627,6 +629,13 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     }
   }
 
+  if (options.designDelta) {
+    console.log('');
+    console.log(color.bold('Design delta (opt-in)'));
+    for (const row of designDeltaDoctorLines(options.designDelta))
+      line(row.level === 'bad' ? bad : row.level === 'ok' ? ok : ' ', row.level === 'dim' ? color.dim(row.text) : row.text);
+  }
+
   // Q03 — optional golden pattern note (advisory for new code only).
   if (goldenPattern.present) {
     console.log('');
@@ -647,7 +656,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     );
   }
 
-  printDoctorAdvisories({ contractHealth, ambientState, physicalCohesion }, { line, warn, color }); // advisory sections
+  printDoctorAdvisories(doctorAdvisories, { line, warn, color }); // advisory sections
 
   console.log('');
   console.log(color.bold('Coverage'));
@@ -702,8 +711,8 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   console.log('');
   console.log(color.bold('Violations'));
   if (violations.length === 0) {
-    // Avoid false confidence when the contract barely covers the tree.
-    if (emptyScope || cov.governed.percent < 50) {
+    if (!analysisComplete) line(warn, 'No reported violations — contract compliance is not verified until analysis is complete');
+    else if (emptyScope || cov.governed.percent < 50) {
       line(
         warn,
         'No active violations — coverage is still thin, so green is not yet honest enforcement'
@@ -747,20 +756,8 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   line(' ', `Active host: ${writePath.activeHost}`);
   line(' ', `Supported profile: ${writePath.supportSummary}`);
   line(wpMark, `Mode: ${writePath.mode} — ${writePathLabels[writePath.mode] || writePath.mode}`);
-  const ladder = writePath.enforcementLadder;
-  const state = (value) => value === true ? 'yes' : value === false ? 'no' : String(value);
-  line(
-    ladder.localWrite.installed ? ok : warn,
-    `Hard hook — supported: ${state(ladder.localWrite.supported)} · installed: ${state(ladder.localWrite.installed)} · active/trusted: ${state(ladder.localWrite.active)} · bypassable: ${state(ladder.localWrite.bypassable)}`
-  );
-  line(
-    warn,
-    `Advisory MCP — supported: ${state(ladder.advisoryMcp.supported)} · installed: ${state(ladder.advisoryMcp.installed)} · active: ${state(ladder.advisoryMcp.active)} · bypassable: ${state(ladder.advisoryMcp.bypassable)}`
-  );
-  line(
-    capabilities['merge-gate'] ? ok : bad,
-    `Merge gate — supported: ${state(ladder.ciMerge.supported)} · installed: ${state(ladder.ciMerge.installed)} · active: ${state(ladder.ciMerge.active)} · bypassable: ${state(ladder.ciMerge.bypassable)} · required status: ${state(ladder.ciMerge.requiredStatus)}`
-  );
+  const enforcement = writePath.enforcementState;
+  for (const row of enforcementDoctorLines(enforcement)) line(row.level === 'ok' ? ok : row.level === 'bad' ? bad : warn, row.text);
   line(
     capabilities['repair-payload'] ? ok : warn,
     `Repair payload at hard boundary: ${capabilities['repair-payload'] ? 'yes' : 'no'}`
@@ -814,12 +811,12 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   console.log('');
   console.log(color.bold('Baseline'));
   if (!baseline.exists) {
-    line(violations.length > 0 ? warn : ok, violations.length > 0 ? 'No baseline — adopting a dirty repo? freeze with --update-baseline' : 'No baseline (nothing to freeze)');
+    line(!analysisComplete || violations.length > 0 ? warn : ok, !analysisComplete ? 'No baseline — current violations were not fully evaluated' : violations.length > 0 ? 'No baseline — adopting a dirty repo? freeze with --update-baseline' : 'No baseline (nothing to freeze)');
   } else {
     // Baseline keys are line-agnostic, so N keys can suppress ≥N violations — label as keys
     // to avoid an apparent mismatch with the "frozen" violation count above.
-    line(ok, `${baseline.keys.size} frozen key(s)`);
-    if (staleBaseline > 0) {
+    line(analysisComplete ? ok : warn, `${baseline.keys.size} frozen key(s)${analysisComplete ? '' : ' — stale comparison not verified'}`);
+    if (analysisComplete && staleBaseline > 0) {
       line(warn, `${staleBaseline} stale entr(y/ies) no longer occur — tighten with --update-baseline`);
       actions.push('tighten the baseline (--update-baseline)');
     }

package/bin/lib/enforcement-state.mjs

@@ -0,0 +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 M(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 S(a){return a.length>0?a:["filesystem scan (no matching configuration)"]}function g({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;return{supported:a,analyzed:!0,configured:p,installed:a&&r.installed,active:o,runtimeObserved:t,operation:l,operationCoverage:d,bypassable:u,required:c,hard:i,evidence:[...S(e).map(v=>({field:"configured",source:v,value:p})),{field:"installed",source:r.source,value:a&&r.installed},{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 w(a,e){const r=M(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),m=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:g({supported:o,configuredPaths:l,installed:r,active:m,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:g({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:g({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 j(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=j(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 y(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 L(a){const e=[{level:a.localWrite.active===!0?"ok":"warn",text:y("Local write",a.localWrite)},{level:"warn",text:y("Advisory MCP",a.advisoryMcp)},{level:a.ciMerge.required===!0?"ok":"warn",text:y("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."}),e}export{w as buildEnforcementState,L as enforcementDoctorLines,x as withCiProviderEvidence};