arkgate 4.8.14 → 4.8.15

package/bin/lib/rules-under-contract.mjs

@@ -4,6 +4,7 @@
  * Summary includes per-layer + structure/invariant detail so showcase HTML /ark-explain
  * can teach what is under contract, not only aggregate numbers.
  */
+import path from 'node:path';
 import { loadEffectiveArkRulesFromDisk } from './effective-contract-load.mjs';
 import { evaluateInvariantCoverage } from './invariant-coverage.mjs';
 import {
@@ -16,6 +17,15 @@ import {
   composeMergePlanesHonesty,
   demoteExtraPlaneTeethUnderClassificationFloor,
 } from './extra-merge-teeth.mjs';
+import { collectEmptyInvariantCatalogFindings } from './arkrules-sensors.mjs';
+import { layerForRelativePath } from '../ark-layer-match.mjs';
+import {
+  ARKRULES_EMPTY_CATALOG_NEXT,
+  ARKRULES_FIRST_CONTACT_NEXT,
+  ARKRULES_ONE_BREATH,
+} from './product-copy.mjs';
+
+export { ARKRULES_EMPTY_CATALOG_NEXT, ARKRULES_FIRST_CONTACT_NEXT, ARKRULES_ONE_BREATH };
 
 /**
  * Cap long catalogs in doctor JSON (and HTML, which consumes the same summary).
@@ -27,6 +37,18 @@ const UNCOVERED_CATALOG_MAX = 30;
 
 export { EXTRA_MERGE_TEETH_GOVERNED_FLOOR };
 
+/** Doctor walk often hands absolute paths; layer globs are project-relative. */
+function projectRelativePath(root, filePath) {
+  const posix = String(filePath).replace(/\\/g, '/');
+  if (path.isAbsolute(posix) && typeof root === 'string' && root.length > 0) {
+    const relative = path.relative(root, posix).replace(/\\/g, '/');
+    if (relative && !relative.startsWith('..') && !path.isAbsolute(relative)) {
+      return relative;
+    }
+  }
+  return posix.replace(/^\.\//, '');
+}
+
 /**
  * P1M / extraMergeTeeth: under the classification floor, demote enforced ArkRules
  * and ArkRun findings so merge matches doctor stamp (layer graph only).
@@ -186,6 +208,25 @@ export function summarizeRulesUnderContract(root, config, facts, classification)
     const invariantAdvisory = invariants - invariantEnforced;
     const coveredInvariants = coverage.coverage.filter((c) => c.covered).length;
     const uncoveredInvariants = coverage.coverage.filter((c) => !c.covered).length;
+    const catalogFiles = Array.isArray(facts?.files)
+      ? facts.files
+          .map((entry) => {
+            const raw = typeof entry?.path === 'string' ? entry.path : '';
+            if (!raw) return null;
+            const relative = projectRelativePath(root, raw);
+            return {
+              path: relative,
+              layer: layerForRelativePath(relative, config.layers ?? []),
+            };
+          })
+          .filter(Boolean)
+      : [];
+    const emptyCatalogFinding = collectEmptyInvariantCatalogFindings({
+      arkRulesActive: true,
+      arkRules: loaded.arkRules,
+      layers: config.layers ?? [],
+      files: catalogFiles,
+    })[0];
     const mergePlanes = composeMergePlanesHonesty({
       classification,
       arkRules: {
@@ -221,6 +262,14 @@ export function summarizeRulesUnderContract(root, config, facts, classification)
       mergePlanes,
       notAScore: true,
       note: 'ArkRules plane (intra-layer) — counts and catalog, never a score. Green with uncovered residual must say so. Structure sensors are heuristics; invariants are catalog+coverage evidence, not a business runtime.',
+      ...(emptyCatalogFinding
+        ? {
+            emptyInvariantCatalog: true,
+            catalogFillPath: emptyCatalogFinding.arkruleSource,
+            catalogFillLayer: emptyCatalogFinding.fromLayer,
+            catalogFailsStrict: emptyCatalogFinding.failsStrict === true,
+          }
+        : { emptyInvariantCatalog: false }),
     };
   } catch (error) {
     return {
@@ -231,6 +280,61 @@ export function summarizeRulesUnderContract(root, config, facts, classification)
   }
 }
 
+/**
+ * Compact / details doctor lines. Empty when the map is off — absence is silent.
+ * @param {ReturnType<typeof summarizeRulesUnderContract>|null|undefined} section
+ * @returns {string[]}
+ */
+export function formatArkRulesDoctorLines(section) {
+  if (!section || typeof section !== 'object') return [];
+  if (section.active !== true) return [];
+
+  if (Array.isArray(section.loadErrors) && section.loadErrors.length > 0) {
+    const first = section.loadErrors[0];
+    const detail =
+      typeof first?.message === 'string' && first.message.length > 0
+        ? first.message
+        : 'Fix the path in arkRules.';
+    return [
+      ARKRULES_ONE_BREATH,
+      `ArkRules: the rules file failed to load — a full check will refuse. ${detail}`,
+    ];
+  }
+
+  const structure = Number(section.structureRules) || 0;
+  const invariants = Number(section.invariants) || 0;
+  const uncovered = Number(section.uncoveredInvariants) || 0;
+  const enforced =
+    (Number(section.mergePlanes?.structureSensors?.enforced) || 0) +
+    (Number(section.mergePlanes?.invariants?.enforced) || 0);
+  const teeth =
+    enforced > 0
+      ? 'some enforced'
+      : 'advisory only — does not fail the merge';
+  const lines = [
+    ARKRULES_ONE_BREATH,
+    `ArkRules: on · structure=${structure} · invariants=${invariants} · uncovered=${uncovered} · ${teeth} · not a score`,
+  ];
+  if (section.emptyInvariantCatalog === true) {
+    const fill =
+      typeof section.catalogFillPath === 'string' && section.catalogFillPath.length > 0
+        ? section.catalogFillPath
+        : 'arkrules/<Domain>.json';
+    const layer =
+      typeof section.catalogFillLayer === 'string' && section.catalogFillLayer.length > 0
+        ? section.catalogFillLayer
+        : 'Domain';
+    lines.push(
+      `ArkRules: ${layer} has code, but invariants[] is empty — add 1–2 short phrases in ${fill}.`
+    );
+    lines.push(ARKRULES_EMPTY_CATALOG_NEXT);
+  } else if (uncovered > 0) lines.push(ARKRULES_FIRST_CONTACT_NEXT);
+  else if (typeof section.note === 'string' && /failed/i.test(section.note)) {
+    lines.push(`ArkRules: ${section.note}`);
+  }
+  return lines;
+}
+
 /**
  * Showcase HTML for the ArkRules plane (used by html-report-advisories).
  * @param {ReturnType<typeof summarizeRulesUnderContract>|null|undefined} section
@@ -347,12 +451,23 @@ export function formatRulesUnderContractHtml(section, esc) {
     uncoveredOverflow > 0
       ? `<p class="muted">…(+${uncoveredOverflow} more uncovered)</p>`
       : '';
+  const emptyCatalogBlock =
+    section.emptyInvariantCatalog === true
+      ? `<p class="tag warn" style="margin-top:.55rem">Domain has code, but <code>invariants[]</code> is empty — that is not done.
+        Add 1–2 short phrases in <code>${escape(section.catalogFillPath || 'arkrules/<Domain>.json')}</code>.
+        ${
+          section.catalogFailsStrict === true
+            ? 'A domain structure rule is already enforced, so <code>--strict-merge</code> can refuse.'
+            : 'Advisory — does not fail the merge until a domain structure rule is enforced.'
+        }</p>`
+      : '';
   const uncoveredBlock =
+    emptyCatalogBlock ||
     // Aggregate total (not the truncated array length) decides "all covered".
-    Number(section.uncoveredInvariants) === 0 && uncovered.length === 0
+    (Number(section.uncoveredInvariants) === 0 && uncovered.length === 0
       ? `<p class="clean-body" style="margin-top:.55rem">All catalogued invariants have coverage evidence (test/symbol scan) — residual inventory may still suggest new candidates via <code>--rules-inventory</code>.</p>`
       : `<h3 style="margin-top:.9rem;font-size:.95rem">Uncovered invariants</h3>
-      <ul class="senior-list">${uncoveredItems}</ul>${uncoveredMore}`;
+      <ul class="senior-list">${uncoveredItems}</ul>${uncoveredMore}`);
 
   const coveredItems = coveredSample
     .map(

package/bin/lib/snippet-analysis.mjs

@@ -2,6 +2,19 @@
 import { layerForRelativePath } from '../ark-layer-match.mjs';
 import { ANALYSIS_COMPLETENESS } from './analysis-completeness.mjs';
 import { evaluateArkRunEditorSensorsFromSource } from './ark-run-sensors.mjs';
+import { getDiagnosticCatalogEntry } from './diagnostic-catalog.mjs';
+
+function lexicalEvidenceIncompleteMessage(file) {
+  const entry = getDiagnosticCatalogEntry('LEXICAL_EVIDENCE_INCOMPLETE');
+  const text = [entry?.why, entry?.fix].filter(Boolean).join(' ');
+  return {
+    code: 'LEXICAL_EVIDENCE_INCOMPLETE',
+    message:
+      text ||
+      'This check only saw one file, so it cannot fully prove how the import resolves. The result is provisional — `ark-check` on the project is the authority. Run `npx arkgate-check --root . --config ark.config.json` to confirm. Do not call ark_prepare_change from a hook deny.',
+    ...(file ? { file } : {}),
+  };
+}
 
 export function flattenTsParseDiagnostics(ts, diagnostics, sourceFile) {
   if (!Array.isArray(diagnostics) || !ts) return [];
@@ -156,14 +169,7 @@ export function validateSnippetAnalysis({ gate, ts, source, context = {} }) {
       valid: false,
       lexicalValid: base.valid,
       completeness: ANALYSIS_COMPLETENESS.partial,
-      completenessReasons: [
-        {
-          code: 'LEXICAL_EVIDENCE_INCOMPLETE',
-          message:
-            'Single-file validation cannot prove project module resolution. The write hook is already the verdict, or re-run `npx arkgate-check --root . --config ark.config.json`. Do not call ark_prepare_change from a hook deny.',
-          ...(file ? { file } : {}),
-        },
-      ],
+      completenessReasons: [lexicalEvidenceIncompleteMessage(file)],
     };
   } catch {
     return {

package/bin/lib/start-preview.mjs

@@ -3,7 +3,8 @@ import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { arkCommand, buildArchitectureRecommendation } from '../ark-shared.mjs';
+import { arkCommand, buildArchitectureRecommendation, START_APPLY_REFUSE_FOOTER } from '../ark-shared.mjs';
+import { withProjectedGovernedCoverage } from './projected-governed-coverage.mjs';
 import { ARKORDER_FIRST_CONTACT_NEXT, ARKORDER_ONE_BREATH } from './ark-order-doctor.mjs';
 import { compactAgentInstructions, instructionRule, mcpJson } from './ci-and-commands.mjs';
 import {
@@ -166,6 +167,7 @@ export function renderStartPreview(preview, options = {}) {
     console.log('Optional extras stay off. This start is layers only — they stop bad imports.');
     console.log(ARKORDER_ONE_BREATH);
     console.log(ARKORDER_FIRST_CONTACT_NEXT);
+    console.log(START_APPLY_REFUSE_FOOTER);
   }
   if (preview.runtimeActivation) {
     console.log('Host: Codex is configured but not verified yet. Restart the host, then confirm this project.');
@@ -325,12 +327,13 @@ export async function planStart(args, helpers) {
     };
   } else {
     try {
-      const rec = buildArchitectureRecommendation(root);
+      const rec = withProjectedGovernedCoverage(buildArchitectureRecommendation(root), root);
       recommendation = {
         archetype: rec.archetype,
         label: rec.label,
         confidence: rec.confidence,
         mature: rec.mature,
+        projectedGovernedCoverage: rec.signals?.projectedGovernedCoverage,
       };
     } catch {
       recommendation = null;

package/bin/lib/states-transitions-presence.mjs

@@ -0,0 +1,212 @@
+/**
+ * Soft states/transitions artifact guidance (P2 §2 / Guiar).
+ * Tooling I/O. Never a gate fail. Silent unless a conventional domain
+ * (or dedicated states) markdown home is already in play.
+ * Does not walk the tree. Does not scan code for status fields.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Product-domain / domain-model homes. Closed list — no tree walk. */
+export const STATES_TRANSITIONS_DOMAIN_HOMES = Object.freeze([
+  'docs/domain.md',
+  'docs/data-model.md',
+  'docs/product-domain.md',
+  'docs/modelo-de-dominio.md',
+  'docs/producto-y-dominio.md',
+  'docs/architecture.md',
+]);
+
+/** Evolved dedicated homes. Adopt if present; do not force a filename. */
+export const STATES_TRANSITIONS_DEDICATED_HOMES = Object.freeze([
+  'docs/states.md',
+  'docs/transitions.md',
+  'docs/states-transitions.md',
+  'docs/lifecycle.md',
+]);
+
+export const STATES_TRANSITIONS_ASK_MISSING =
+  'A domain doc is in play, but there is no states → transitions map yet.';
+
+export const STATES_TRANSITIONS_ASK_INCOMPLETE =
+  'The states heading is there, but it is not a map yet — no table or link.';
+
+export const STATES_TRANSITIONS_NEXT =
+  'Add a short table (entity · states · allowed from → to) — or one link — on the domain doc. Names from the code. No flag soup.';
+
+function readMarkdown(abs) {
+  try {
+    if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) return null;
+    const text = fs.readFileSync(abs, 'utf8');
+    return text.trim().length > 0 ? text : '';
+  } catch {
+    return null;
+  }
+}
+
+function cellIsStateVocab(cell) {
+  return (
+    cell === 'state' ||
+    cell === 'states' ||
+    cell.startsWith('state ') ||
+    cell.endsWith(' state') ||
+    cell.endsWith(' states')
+  );
+}
+
+function cellIsTransitionVocab(cell) {
+  return (
+    cell.includes('transition') ||
+    cell === 'from' ||
+    cell === 'to' ||
+    cell === 'from → to' ||
+    cell === 'from -> to'
+  );
+}
+
+function cellIsEntityVocab(cell) {
+  return cell === 'entity' || cell === 'entities';
+}
+
+/** Closed table: entity | states | allowed transitions (or from → to). */
+export function markdownHasStatesTable(text) {
+  if (typeof text !== 'string' || text.length === 0) return false;
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|')) continue;
+    const cells = trimmed
+      .split('|')
+      .map((cell) => cell.trim().toLowerCase())
+      .filter((cell) => cell.length > 0 && !/^[-:]+$/.test(cell));
+    if (cells.length < 2) continue;
+    const hasEntity = cells.some((cell) => cellIsEntityVocab(cell));
+    const hasState = cells.some((cell) => cellIsStateVocab(cell));
+    const hasTransition = cells.some((cell) => cellIsTransitionVocab(cell));
+    if ((hasState && hasTransition) || (hasEntity && (hasState || hasTransition))) return true;
+  }
+  return false;
+}
+
+function mentionsStatesTopic(value) {
+  return (
+    value.includes('transition') ||
+    value.includes('lifecycle') ||
+    value.includes('states/transitions') ||
+    value.includes('states-transitions') ||
+    value.includes('state machine')
+  );
+}
+
+/** One link to the captain’s existing authority. */
+export function markdownHasStatesLink(text) {
+  if (typeof text !== 'string' || text.length === 0) return false;
+  let from = 0;
+  while (from < text.length) {
+    const open = text.indexOf('[', from);
+    if (open < 0) break;
+    const mid = text.indexOf('](', open + 1);
+    if (mid < 0) break;
+    const close = text.indexOf(')', mid + 2);
+    if (close < 0) break;
+    const label = text.slice(open + 1, mid).toLowerCase();
+    const href = text.slice(mid + 2, close).toLowerCase();
+    if (mentionsStatesTopic(label) || mentionsStatesTopic(href)) return true;
+    from = close + 1;
+  }
+  return false;
+}
+
+export function markdownHasStatesHeading(text) {
+  if (typeof text !== 'string' || text.length === 0) return false;
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('#')) continue;
+    const title = trimmed.replace(/^#+\s*/, '').toLowerCase();
+    if (
+      title === 'state' ||
+      title === 'states' ||
+      title === 'transition' ||
+      title === 'transitions' ||
+      title === 'lifecycle' ||
+      title.includes('states/transitions') ||
+      title.includes('states and transitions')
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function scoreMarkdown(text) {
+  if (text == null) return 'absent';
+  if (text === '') return 'incomplete';
+  if (markdownHasStatesTable(text) || markdownHasStatesLink(text)) return 'present';
+  if (markdownHasStatesHeading(text)) return 'incomplete';
+  return 'missing';
+}
+
+function existingHomes(root, relatives) {
+  const found = [];
+  for (const rel of relatives) {
+    const text = readMarkdown(path.join(root, rel));
+    if (text == null) continue;
+    found.push({ rel, score: scoreMarkdown(text) });
+  }
+  return found;
+}
+
+/**
+ * First conventional home already on disk (domain doc or dedicated file).
+ * Empty / missing files do not count as a home.
+ *
+ * @param {string} root
+ * @returns {string | null}
+ */
+export function findStatesTransitionsHome(root) {
+  if (typeof root !== 'string' || root.length === 0) return null;
+  const homes = [
+    ...existingHomes(root, STATES_TRANSITIONS_DOMAIN_HOMES),
+    ...existingHomes(root, STATES_TRANSITIONS_DEDICATED_HOMES),
+  ];
+  return homes[0]?.rel ?? null;
+}
+
+function nextActionFor(home) {
+  if (!home) return STATES_TRANSITIONS_NEXT;
+  return `Add a short table (entity · states · allowed from → to) — or one link — to ${home}. Names from the code. No flag soup.`;
+}
+
+/**
+ * Soft residual when a domain (or dedicated states) doc is in play and the
+ * map is missing or only a heading. Off / no such doc → null (silent).
+ *
+ * @param {{ root?: string }} [input]
+ * @returns {{ kind: 'missing' | 'incomplete', home: string, ask: string, nextAction: string } | null}
+ */
+export function collectStatesTransitionsResidual(input = {}) {
+  const root = input.root ?? '';
+  if (typeof root !== 'string' || root.length === 0) return null;
+  const homes = [
+    ...existingHomes(root, STATES_TRANSITIONS_DOMAIN_HOMES),
+    ...existingHomes(root, STATES_TRANSITIONS_DEDICATED_HOMES),
+  ];
+  if (homes.length === 0) return null;
+  if (homes.some((row) => row.score === 'present')) return null;
+  const incomplete = homes.find((row) => row.score === 'incomplete');
+  const home = (incomplete ?? homes[0]).rel;
+  if (incomplete) {
+    return {
+      kind: 'incomplete',
+      home,
+      ask: STATES_TRANSITIONS_ASK_INCOMPLETE,
+      nextAction: nextActionFor(home),
+    };
+  }
+  return {
+    kind: 'missing',
+    home,
+    ask: STATES_TRANSITIONS_ASK_MISSING,
+    nextAction: nextActionFor(home),
+  };
+}

package/bin/lib/status-command.mjs

@@ -306,6 +306,8 @@ export function collectStatusFacts(options = {}) {
   const softWriteHost = Boolean(matrix && matrix.capabilities?.['hard-write'] !== true);
   const writePathHonesty = buildWritePathHonesty(hostKey, hardWriteActive, {
     packageInstalled: writePath?.enforcementState?.localWrite?.installed !== false,
+    nativeFailClosed: writePath?.nativeFailClosed,
+    nativeFailClosedPolicy: writePath?.nativeFailClosedPolicy,
   });
 
   const latestPath = path.join(reportsDir(resolvedRoot), 'latest.json');