arkgate 3.9.1 → 4.0.0

package/bin/lib/pilot-loop.mjs

@@ -166,6 +166,13 @@ export function formatExtractionCard(card) {
  */
 export function summarizePilotLoop(opts = {}) {
   const designWeak = opts.designWeak === true;
+  // Same forbid bits as DESIGN_WEAK_HONESTY_FLAGS (both auto-apply aliases).
+  const forbid = {
+    multiPilotBatchForbidden: true,
+    autoApplyForbidden: true,
+    autoApplyPlanBForbidden: true,
+  };
+
   if (!designWeak) {
     return {
       active: false,
@@ -173,6 +180,7 @@ export function summarizePilotLoop(opts = {}) {
       reason: 'not-design-weak',
       oneAtATime: true,
       neverMechanicalSafe: true,
+      ...forbid,
     };
   }
 
@@ -186,21 +194,32 @@ export function summarizePilotLoop(opts = {}) {
       reason: 'no-pattern-bets',
       oneAtATime: true,
       neverMechanicalSafe: true,
+      ...forbid,
     };
   }
 
   const remaining = Array.isArray(opts.patternBets) ? opts.patternBets.length : 0;
+  const queued = Math.max(0, remaining - 1);
 
   return {
     active: true,
     id: PILOT_LOOP_ID,
     oneAtATime: true,
     neverMechanicalSafe: true,
+    ...forbid,
     remainingBets: remaining,
+    // Remaining pattern bets are a queue, never concurrent pilots.
+    queuedBets: queued,
+    ...(queued > 0
+      ? {
+          queueNote: `${queued} additional pattern bet(s) stay queued — run the single nextPilot only, then re-doctor before selecting another.`,
+        }
+      : {}),
     nextPilot,
     instruction:
       'Apply ONE pilot from nextPilot (extraction card), then re-doctor. ' +
       'Do not multi-pilot batch. patternBets never mechanical-safe. ' +
+      'Never silent auto-apply of plan B. ' +
       'Success = reduced smell evidence on pilot paths; residual outside pilot may remain.',
     cardText: formatExtractionCard(nextPilot),
   };

package/bin/lib/policy-delta-io.mjs

@@ -2,6 +2,9 @@ import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { analyzePolicyDelta } from './analysis-engine.mjs';
+import { loadEffectiveArkRulesFromDisk } from './effective-contract-load.mjs';
+import { loadInvariantCoverageInputs } from './invariant-coverage-io.mjs';
+import { evaluateInvariantCoverage } from './invariant-coverage.mjs';
 
 function readJsonFile(filePath, label) {
   if (!fs.existsSync(filePath)) throw new Error(`${label} not found: ${filePath}`);
@@ -151,11 +154,41 @@ export function analyzePolicyTransition({
     throw new Error('Policy delta was requested but no policy base could be resolved.');
   }
   if (!base) return undefined;
+
+  // AR02/AR11: load Effective ArkRules so mode edits inside arkrules/*.json classify,
+  // and attach candidate coverage so covered advisory→enforced can auto-allow.
+  const baseLoad = loadEffectiveArkRulesFromDisk(root, base.config);
+  const candidateLoad = loadEffectiveArkRulesFromDisk(root, candidateConfig);
+  if (candidateLoad.errors.length > 0) {
+    const message = candidateLoad.errors
+      .map((issue) => `- ${issue.path}: ${issue.message}`)
+      .join('\n');
+    throw new Error(`Invalid candidate Effective Contract:\n${message}`);
+  }
+  // Base load errors: best-effort empty (base git tree may lack arkrules files on disk).
+  const baseArkRules = baseLoad.errors.length > 0 ? undefined : baseLoad.arkRules;
+  const candidateArkRules = candidateLoad.arkRules;
+
+  let candidateInvariantCoverage;
+  if ((candidateArkRules?.invariants?.length ?? 0) > 0) {
+    const coverageInputs = loadInvariantCoverageInputs(root, { files: [] });
+    const evaluated = evaluateInvariantCoverage({
+      arkRules: candidateArkRules,
+      fileContents: coverageInputs.fileContents,
+      testFiles: coverageInputs.testFiles,
+      testGlobsMissing: coverageInputs.testGlobsMissing,
+    });
+    candidateInvariantCoverage = evaluated.coverage;
+  }
+
   return analyzePolicyDelta({
     baseConfig: base.config,
     candidateConfig,
     acknowledgement: readPolicyAcknowledgement(root, acknowledgementPath),
     baseSource: base.source,
     candidateSource: path.isAbsolute(configPath) ? configPath : path.join(root, configPath),
+    ...(baseArkRules ? { baseArkRules } : {}),
+    candidateArkRules,
+    ...(candidateInvariantCoverage ? { candidateInvariantCoverage } : {}),
   });
 }

package/bin/lib/post-green-path.mjs

@@ -23,6 +23,22 @@ export const POST_GREEN_PRIMARY_ACTION =
 export const POST_GREEN_PRIMARY_SHORT =
   '/ark-explore shape-focus → /ark-autopilot (apply B with OK)  # Shape residual';
 
+/** Placement coaching while design residual remains (new code only). */
+export const POST_GREEN_PLACEMENT_COACHING =
+  'New code: /ark-place (contract + optional golden). Design residual: map smells → ONE pilot via pilotLoop.nextPilot → re-doctor. Never multi-pilot batch; never silent auto-apply of plan B.';
+
+/**
+ * Shared design-weak honesty flags for plan/doctor/pilot JSON.
+ * Canonical auto-apply forbid is `autoApplyForbidden`; `autoApplyPlanBForbidden`
+ * is the same bit (alias for plan-B wording) so agents can key either path.
+ */
+export const DESIGN_WEAK_HONESTY_FLAGS = Object.freeze({
+  healthyFinishedForbidden: true,
+  multiPilotBatchForbidden: true,
+  autoApplyForbidden: true,
+  autoApplyPlanBForbidden: true,
+});
+
 /**
  * @param {{ designWeak?: boolean } | null | undefined} designFitness
  * @returns {null | {
@@ -33,7 +49,11 @@ export const POST_GREEN_PRIMARY_SHORT =
  *   flow: string,
  *   action: string,
  *   short: string,
+ *   placementCoaching: string,
  *   neverMechanicalSafe: true,
+ *   multiPilotBatchForbidden: true,
+ *   autoApplyForbidden: true,
+ *   autoApplyPlanBForbidden: true,
  *   healthyFinishedForbidden: true,
  * }}
  */
@@ -47,8 +67,9 @@ export function buildPostGreenNextAction(designFitness) {
     flow: 'shape-focus',
     action: POST_GREEN_PRIMARY_ACTION,
     short: POST_GREEN_PRIMARY_SHORT,
+    placementCoaching: POST_GREEN_PLACEMENT_COACHING,
     neverMechanicalSafe: true,
-    healthyFinishedForbidden: true,
+    ...DESIGN_WEAK_HONESTY_FLAGS,
   };
 }
 

package/bin/lib/presets.mjs

@@ -1,6 +1,9 @@
 /**
  * Architecture starter presets for ark-check init/coverage suggestions.
  */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import {
   applyFrameworkLayoutOverlays,
   createElevenLayerConfig,
@@ -11,6 +14,9 @@ import {
 } from '../ark-shared.mjs';
 import { withArkConfigMetadata } from './config-contract.mjs';
 
+const PRESETS_DIR = path.dirname(fileURLToPath(import.meta.url));
+const ARKRULES_TEMPLATES_DIR = path.join(PRESETS_DIR, '../../templates/arkrules');
+
 export function denyUpward(names) {
   const rules = [];
   for (let i = 0; i < names.length; i += 1) {
@@ -50,9 +56,243 @@ export function peerIsolationEdges(layerNames, sliceFolders, message) {
 // `src/**/domain/**` would otherwise swallow `src/kernel/domain`. Do NOT use `**/kernel/**`
 // (that carves out legitimate `src/shared/kernel/**` SharedKernel paths).
 export const FRAMEWORK_INTERNAL_EXCLUDE = ['src/kernel/**', '**/src/kernel/**'];
+/**
+ * AR08 — attach lean arkRules map. Keys are always exact project layer names.
+ * Sensor roles (domain-structure / orchestration / adapter-thin / generic) are
+ * independent of display names so renamed layers still get the right starter.
+ */
+export const DEFAULT_ARKRULES_REFS = {
+  DomainModel: 'arkrules/DomainModel.json',
+  ApplicationOrchestration: 'arkrules/ApplicationOrchestration.json',
+  PresentationAdapters: 'arkrules/PresentationAdapters.json',
+  PersistenceAdapters: 'arkrules/PersistenceAdapters.json',
+};
+
+/** Sensor roles used when selecting or synthesizing per-layer templates. */
+export const ARKRULES_SENSOR_ROLES = Object.freeze({
+  DOMAIN_STRUCTURE: 'domain-structure',
+  ORCHESTRATION: 'orchestration',
+  ADAPTER_THIN: 'adapter-thin',
+  GENERIC: 'generic',
+});
+
+/**
+ * Exact-name aliases → sensor role. Prefer this table over heuristics when the
+ * project uses a known vocabulary (hexagonal, monorepo field renames, etc.).
+ */
+export const LAYER_SENSOR_ROLE_ALIASES = Object.freeze({
+  // Domain / pure model
+  DomainModel: ARKRULES_SENSOR_ROLES.DOMAIN_STRUCTURE,
+  Domain: ARKRULES_SENSOR_ROLES.DOMAIN_STRUCTURE,
+  Entities: ARKRULES_SENSOR_ROLES.DOMAIN_STRUCTURE,
+  // Application / use cases
+  ApplicationOrchestration: ARKRULES_SENSOR_ROLES.ORCHESTRATION,
+  Application: ARKRULES_SENSOR_ROLES.ORCHESTRATION,
+  UseCases: ARKRULES_SENSOR_ROLES.ORCHESTRATION,
+  // Presentation / UI adapters
+  PresentationAdapters: ARKRULES_SENSOR_ROLES.ADAPTER_THIN,
+  Presentation: ARKRULES_SENSOR_ROLES.ADAPTER_THIN,
+  UI: ARKRULES_SENSOR_ROLES.ADAPTER_THIN,
+  WebPresentation: ARKRULES_SENSOR_ROLES.ADAPTER_THIN,
+  ApiComposition: ARKRULES_SENSOR_ROLES.ADAPTER_THIN,
+  // Persistence / infrastructure adapters
+  PersistenceAdapters: ARKRULES_SENSOR_ROLES.ADAPTER_THIN,
+  Infrastructure: ARKRULES_SENSOR_ROLES.ADAPTER_THIN,
+  Persistence: ARKRULES_SENSOR_ROLES.ADAPTER_THIN,
+  Data: ARKRULES_SENSOR_ROLES.ADAPTER_THIN,
+});
+
+/**
+ * Resolve a stable sensor role for a project layer name.
+ * Exact alias first, then specific adapter/domain cues, then broad application
+ * heuristics (so ApplicationAdapters → thin-adapter, not orchestration).
+ */
+export function resolveLayerSensorRole(layerName) {
+  if (typeof layerName !== 'string' || layerName.length === 0) {
+    return ARKRULES_SENSOR_ROLES.GENERIC;
+  }
+  if (LAYER_SENSOR_ROLE_ALIASES[layerName]) return LAYER_SENSOR_ROLE_ALIASES[layerName];
+  const n = layerName.toLowerCase();
+  if (/(^|[^a-z])(domain|entit)/.test(n) || n.includes('domainmodel')) {
+    return ARKRULES_SENSOR_ROLES.DOMAIN_STRUCTURE;
+  }
+  // Adapter / I/O cues before broad "application" — ApplicationAdapters must not
+  // inherit orchestration-only sensors.
+  if (
+    n.includes('present') ||
+    n.includes('persist') ||
+    n.includes('infra') ||
+    n.includes('adapter') ||
+    n.includes('repository') ||
+    /(^|[^a-z])(ui|web|data)([^a-z]|$)/.test(n)
+  ) {
+    return ARKRULES_SENSOR_ROLES.ADAPTER_THIN;
+  }
+  if (
+    n.includes('application') ||
+    n.includes('orchestr') ||
+    n.includes('usecase') ||
+    n.includes('use-case') ||
+    n.includes('use_case')
+  ) {
+    return ARKRULES_SENSOR_ROLES.ORCHESTRATION;
+  }
+  return ARKRULES_SENSOR_ROLES.GENERIC;
+}
+
+/**
+ * Pick the shipped archetype filename for a layer (role + presentation vs persistence cue).
+ * Returns null for generic molds.
+ */
+export function archetypeTemplateFileForLayer(layerName, role = resolveLayerSensorRole(layerName)) {
+  if (role === ARKRULES_SENSOR_ROLES.DOMAIN_STRUCTURE) return 'DomainModel.json';
+  if (role === ARKRULES_SENSOR_ROLES.ORCHESTRATION) return 'ApplicationOrchestration.json';
+  if (role === ARKRULES_SENSOR_ROLES.ADAPTER_THIN) {
+    const n = String(layerName).toLowerCase();
+    if (
+      n.includes('present') ||
+      n.includes('ui') ||
+      n.includes('web') ||
+      n.includes('page') ||
+      n.includes('widget') ||
+      n.includes('api')
+    ) {
+      return 'PresentationAdapters.json';
+    }
+    return 'PersistenceAdapters.json';
+  }
+  return null;
+}
+
+/**
+ * Layer names used as single path segments under arkrules/ must not escape the dir
+ * (reject `/`, `\`, `..`, absolute, empty). Mirrors managed-upgrade isSafeRelativePath.
+ */
+export function isSafeArkRulesLayerName(layerName) {
+  if (typeof layerName !== 'string' || layerName.length === 0) return false;
+  if (layerName.includes('\0') || layerName.includes('/') || layerName.includes('\\')) return false;
+  if (layerName === '.' || layerName === '..' || layerName.includes('..')) return false;
+  // Single path segment: letters/digits/underscore/hyphen; optional leading letter preferred
+  // but allow common PascalCase layer vocabularies.
+  if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(layerName)) return false;
+  return true;
+}
+
+/** Relative path for a layer's arkrules file (always arkrules/<exactLayerName>.json). */
+export function arkRulesPathForLayer(layerName) {
+  if (!isSafeArkRulesLayerName(layerName)) {
+    throw new Error(
+      `unsafe arkRules layer name ${JSON.stringify(layerName)}: must be a single path segment (A-Za-z0-9_-) under arkrules/`
+    );
+  }
+  return `arkrules/${layerName}.json`;
+}
+
+/** True when rel is a safe project-relative arkrules/*.json path (no escape). */
+export function isSafeArkRulesRelativePath(rel) {
+  if (typeof rel !== 'string' || rel.length === 0) return false;
+  if (rel.includes('\0') || rel.includes('\\') || path.isAbsolute(rel)) return false;
+  const normalized = path.posix.normalize(rel);
+  if (normalized !== rel || normalized === '.' || normalized.startsWith('../')) return false;
+  if (!normalized.startsWith('arkrules/') || !normalized.endsWith('.json')) return false;
+  // Exactly one segment under arkrules/ (no nested dirs).
+  const rest = normalized.slice('arkrules/'.length);
+  if (!rest || rest.includes('/') || rest === '..' || rest.includes('..')) return false;
+  return true;
+}
+
+/**
+ * Build starter ArkRules JSON for a project layer: archetype clone with rewritten
+ * `layer` field, or an empty generic mold the agent can refine.
+ */
+export function buildArkRulesTemplateForLayer(layerName, role = resolveLayerSensorRole(layerName)) {
+  const archetype = archetypeTemplateFileForLayer(layerName, role);
+  if (archetype) {
+    const sourcePath = path.join(ARKRULES_TEMPLATES_DIR, archetype);
+    if (fs.existsSync(sourcePath)) {
+      try {
+        const parsed = JSON.parse(fs.readFileSync(sourcePath, 'utf8'));
+        return {
+          ...parsed,
+          layer: layerName,
+        };
+      } catch {
+        // Fall through to generic mold.
+      }
+    }
+  }
+  // Generic mold: valid empty contract keyed to the exact project layer name.
+  // Structure is empty so agents refine without inheriting the wrong sensors.
+  return {
+    $schema: 'https://unpkg.com/arkgate/schemas/ark.arkrules.schema.json',
+    schemaVersion: '1.0',
+    layer: layerName,
+    structure: [],
+    invariants: [],
+  };
+}
+
+/**
+ * Attach arkRules map for every declared layer. Keys = exact layer names.
+ * Existing map entries are preserved (never overwritten).
+ */
+export function withDefaultArkRules(config) {
+  const layers = config.layers ?? [];
+  if (layers.length === 0) return config;
+  const arkRules = { ...(config.arkRules ?? {}) };
+  let changed = false;
+  for (const layer of layers) {
+    const name = layer?.name;
+    if (typeof name !== 'string' || name.length === 0) continue;
+    if (arkRules[name]) continue;
+    if (!isSafeArkRulesLayerName(name)) continue;
+    arkRules[name] = arkRulesPathForLayer(name);
+    changed = true;
+  }
+  if (!changed) return config;
+  return { ...config, arkRules };
+}
+
+/**
+ * Write starter arkrules/*.json for each arkRules map entry (AR08).
+ * Uses sensor-role mapping so renamed layers get the right archetype;
+ * unknown layers get a generic empty mold. Skips existing files unless force=true.
+ * Rejects paths that escape arkrules/ (mirror managed-upgrade path safety).
+ */
+export function writeArkRulesTemplates(root, config, { force = false } = {}) {
+  const refs = config?.arkRules;
+  if (!refs || typeof refs !== 'object') return [];
+  const written = [];
+  const resolvedRoot = path.resolve(root);
+  for (const [layerName, rel] of Object.entries(refs)) {
+    if (typeof rel !== 'string' || !rel.endsWith('.json')) continue;
+    if (!isSafeArkRulesRelativePath(rel)) {
+      throw new Error(
+        `refusing arkRules write for unsafe path ${JSON.stringify(rel)} (layer ${JSON.stringify(layerName)})`
+      );
+    }
+    const target = path.resolve(resolvedRoot, rel);
+    const relToRoot = path.relative(resolvedRoot, target);
+    if (!relToRoot || relToRoot.startsWith('..') || path.isAbsolute(relToRoot)) {
+      throw new Error(`arkRules path escapes project root: ${rel}`);
+    }
+    const underArkRules = path.relative(path.join(resolvedRoot, 'arkrules'), target);
+    if (!underArkRules || underArkRules.startsWith('..') || path.isAbsolute(underArkRules)) {
+      throw new Error(`arkRules path escapes arkrules/: ${rel}`);
+    }
+    if (fs.existsSync(target) && !force) continue;
+    const role = resolveLayerSensorRole(layerName);
+    const body = buildArkRulesTemplateForLayer(layerName, role);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, `${JSON.stringify(body, null, 2)}\n`);
+    written.push(rel);
+  }
+  return written;
+}
+
 export function presetWithOverlays(baseConfig, root) {
   const config = root ? applyFrameworkLayoutOverlays(baseConfig, root) : baseConfig;
-  return withArkConfigMetadata(config);
+  return withArkConfigMetadata(withDefaultArkRules(config));
 }
 
 export const ARCHITECTURE_PRESETS = {

package/bin/lib/remediation.mjs

@@ -62,7 +62,18 @@ export function deterministicNextAction(violation) {
             return 'Publish through a registered intent creator, then run Ark again.';
         case 'PUBLISH_MISSING_SOURCE':
             return 'Add metadata.source to the publish call, then run Ark again.';
+        case 'ARKRULE_STRUCTURE':
+        case 'ARKRULE_INVARIANT':
+        case 'INVARIANT_UNCOVERED':
+            return `Fix the structure or invariant for ${typeof violation.arkruleId === 'string' && violation.arkruleId.length > 0
+                ? violation.arkruleId
+                : 'the ArkRule'} (declared in ${typeof violation.arkruleSource === 'string' && violation.arkruleSource.length > 0
+                ? violation.arkruleSource
+                : 'arkrules/<Layer>.json'}), then preflight again. Do not demote the rule without a hash-bound policy acknowledgement.`;
         default:
+            if (typeof violation.ruleId === 'string' && violation.ruleId.startsWith('ARKRULE_')) {
+                return `Fix the ArkRule ${typeof violation.arkruleId === 'string' ? violation.arkruleId : violation.ruleId}, then preflight again.`;
+            }
             return `Resolve ${typeof violation.ruleId === 'string' && violation.ruleId.length > 0 ? violation.ruleId : 'ARK_UNKNOWN'} without weakening ark.config.json, then run Ark again.`;
     }
 }
@@ -164,6 +175,16 @@ export function classifyRemediation(violation) {
             rationale: 'Dependency cycle: breaking it means deciding which side owns the shared abstraction.',
         };
     }
+    if (ruleId === 'ARKRULE_STRUCTURE' ||
+        ruleId === 'ARKRULE_INVARIANT' ||
+        ruleId === 'INVARIANT_UNCOVERED' ||
+        (typeof ruleId === 'string' && ruleId.startsWith('ARKRULE_'))) {
+        return {
+            class: 'judgment',
+            confidence: 0.85,
+            rationale: 'ArkRule structure/invariant findings are never mechanical-safe — restore private state, factory shape, event publish, coverage, or redesign the aggregate with judgment.',
+        };
+    }
     if (typeof ruleId === 'string' && ruleId.length > 0) {
         return {
             class: 'judgment',
@@ -239,6 +260,13 @@ export function enrichViolationWithFixClass(violation) {
             enriched.enthusiastHint =
                 'Reference that intent from a layer allowed to know about it — usually an adapter or application layer, not the domain core.';
             break;
+        case 'ARKRULE_STRUCTURE':
+        case 'ARKRULE_INVARIANT':
+        case 'INVARIANT_UNCOVERED':
+            enriched.fixClass = 'review-contract';
+            enriched.effort = 'medium';
+            enriched.enthusiastHint = `ArkRule ${typeof violation.arkruleId === 'string' ? violation.arkruleId : 'rule'} failed${typeof violation.arkruleSource === 'string' ? ` (from ${violation.arkruleSource})` : ''}. Restore the declared structure or add a covering test/symbol — do not demote without acknowledgement.`;
+            break;
         case 'CIRCULAR_DEPENDENCY':
             enriched.fixClass = 'break-cycle';
             enriched.effort = 'medium';

package/bin/lib/resolved-candidate-facts.mjs

@@ -34,6 +34,7 @@ import {
   typeOnlyExportNames,
 } from './ast-scan.mjs';
 import { provePortProofInject } from './port-proof.mjs';
+import { extractClassShapesFromSource } from './arkrules-sensors.mjs';
 import {
   collectGovernedFiles,
   isGovernableSourceFile,
@@ -995,6 +996,8 @@ export function resolveCandidateFacts({
   const publishCalls = [];
   const intentReferences = [];
   const safetyUses = [];
+  /** ADR 0013 class-shape facts for ArkRules structure sensors. */
+  const classShapes = [];
 
   for (const candidate of candidateFiles) {
     const sourceFile = ts.createSourceFile(
@@ -1076,6 +1079,15 @@ export function resolveCandidateFacts({
     safetyUses.push(
       ...collectSafetyUses(ts, sourceFile, candidate.path, candidate.content, semanticDependencies)
     );
+    // Class-shape extraction is text-conservative (false negatives over false positives).
+    // Only TS/TSX candidates; sensors consume the same shape via facts.classShapes.
+    if (/\.(tsx?|mts|cts)$/i.test(candidate.path)) {
+      try {
+        classShapes.push(...extractClassShapesFromSource(candidate.path, candidate.content));
+      } catch {
+        // Never fail the resolver for shape extraction; sensors stay silent on this file.
+      }
+    }
   }
 
   const dependencies = [];
@@ -1140,7 +1152,7 @@ export function resolveCandidateFacts({
 
   const projectPackageName = readPackageName(canonicalRoot, observeInput);
   return createTrustedResolvedCandidateFacts({
-    schemaVersion: '1.0',
+    schemaVersion: '1.1',
     completeness: completenessReasons.length === 0 ? 'complete' : 'partial',
     completenessReasons,
     resolverIdentity: RESOLVED_FACTS_RESOLVER_IDENTITY,
@@ -1156,5 +1168,6 @@ export function resolveCandidateFacts({
     publishCalls,
     intentReferences,
     safetyUses,
+    classShapes,
   });
 }

package/bin/lib/rules-inventory.mjs

@@ -0,0 +1,144 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/rulesInventory.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/rules-inventory.mjs). Zero Node I/O.
+ */
+
+function lineOf(content, index) {
+    return content.slice(0, index).split('\n').length;
+}
+export function buildRulesInventory(input) {
+    const candidates = [];
+    let seq = 0;
+    for (const [file, content] of Object.entries(input.fileContents).sort(([a], [b]) => a.localeCompare(b))) {
+        const isController = /controller|route|handler|resolver/i.test(file) ||
+            /@(Controller|Get|Post|Put|Delete|Patch)\b/.test(content);
+        const isDomain = /domain|entity|aggregate|model/i.test(file);
+        // validation-in-controller
+        if (isController) {
+            const valRe = /\b(if\s*\([^)]{0,80}(amount|total|price|qty|quantity|balance)[^)]{0,40}\)|throw new (Error|BadRequest|ValidationError)|z\.object\(|yup\.|class-validator|@Is[A-Z])/g;
+            let m;
+            while ((m = valRe.exec(content)) !== null) {
+                seq += 1;
+                candidates.push({
+                    id: `inv-val-${seq}`,
+                    kind: 'validation-in-controller',
+                    file,
+                    line: lineOf(content, m.index),
+                    message: 'Business validation appears in a controller/handler — extract an invariant or Domain rule.',
+                    confidence: 'direct-evidence',
+                    suggestedArkRule: {
+                        layer: 'DomainModel',
+                        invariantId: `INV-EXTRACT-${seq}`,
+                        sensor: 'invariant-coverage',
+                    },
+                    neverMechanicalSafe: true,
+                });
+            }
+        }
+        // magic business constants (heuristic)
+        const magicRe = /\b(const|let)\s+([A-Z][A-Z0-9_]{2,})\s*=\s*(\d{2,}|['"][^'"]{8,}['"])/g;
+        let magic;
+        while ((magic = magicRe.exec(content)) !== null) {
+            if (/TEST|SPEC|TIMEOUT|PORT|VERSION|MAX_RETRY/i.test(magic[2]))
+                continue;
+            seq += 1;
+            candidates.push({
+                id: `inv-magic-${seq}`,
+                kind: 'magic-business-constant',
+                file,
+                line: lineOf(content, magic.index),
+                message: `Magic business constant ${magic[2]} may belong in a Domain policy or invariant catalog.`,
+                confidence: 'heuristic',
+                suggestedArkRule: { layer: 'DomainModel', invariantId: `INV-${magic[2]}` },
+                neverMechanicalSafe: true,
+            });
+        }
+        // anemic entity
+        if (isDomain) {
+            const classRe = /export\s+class\s+([A-Za-z_][A-Za-z0-9_]*)\s*\{([^}]{0,800})\}/g;
+            let c;
+            while ((c = classRe.exec(content)) !== null) {
+                const body = c[2] ?? '';
+                const methods = (body.match(/\b[a-zA-Z_][a-zA-Z0-9_]*\s*\(/g) ?? []).length;
+                const fields = (body.match(/:\s*[A-Za-z]/g) ?? []).length;
+                if (fields >= 2 && methods <= 1) {
+                    seq += 1;
+                    candidates.push({
+                        id: `inv-anemic-${seq}`,
+                        kind: 'anemic-entity',
+                        file,
+                        line: lineOf(content, c.index),
+                        message: `Class ${c[1]} looks anemic (data-heavy, few behaviors).`,
+                        confidence: 'heuristic',
+                        suggestedArkRule: {
+                            layer: 'DomainModel',
+                            structureId: 'no-anemic-model',
+                            sensor: 'no-anemic-model',
+                        },
+                        neverMechanicalSafe: true,
+                    });
+                }
+            }
+        }
+        // mutation without guard in domain
+        if (isDomain) {
+            const mutRe = /this\.\w+\s*=/g;
+            let mut;
+            while ((mut = mutRe.exec(content)) !== null) {
+                const window = content.slice(Math.max(0, mut.index - 200), mut.index + 200);
+                if (!/\b(ensureInvariants|assertInvariants|validate|publish|emit)\b/.test(window)) {
+                    seq += 1;
+                    candidates.push({
+                        id: `inv-mut-${seq}`,
+                        kind: 'mutation-without-guard',
+                        file,
+                        line: lineOf(content, mut.index),
+                        message: 'Domain field mutation without nearby guard/publish call.',
+                        confidence: 'heuristic',
+                        suggestedArkRule: {
+                            layer: 'DomainModel',
+                            structureId: 'events-on-mutation',
+                            sensor: 'domain-event-on-mutation',
+                        },
+                        neverMechanicalSafe: true,
+                    });
+                    break; // one per file is enough for inventory ranking
+                }
+            }
+        }
+    }
+    const contracted = new Set(input.contractedRuleIds ?? []);
+    const underContract = candidates.filter((c) => (c.suggestedArkRule?.invariantId && contracted.has(c.suggestedArkRule.invariantId)) ||
+        (c.suggestedArkRule?.structureId && contracted.has(c.suggestedArkRule.structureId))).length;
+    return {
+        candidates,
+        inventoried: candidates.length,
+        underContract,
+        frozen: (input.frozenKeys ?? []).length,
+        notAScore: true,
+    };
+}
+/** Build a pilotLoop extraction card for the top inventory candidate (AR14). */
+export function inventoryToExtractionCard(candidate) {
+    return {
+        pilot: `Extract rule candidate ${candidate.id} (${candidate.kind})`,
+        pilotTarget: candidate.file,
+        smellId: candidate.kind,
+        move: `Declare in arkrules/${candidate.suggestedArkRule?.layer ?? 'DomainModel'}.json, implement pure Domain logic, add covering test.`,
+        doNot: [
+            'Do not auto-apply codemods',
+            'Do not promote to enforced without coverage evidence',
+            'Do not batch multiple extractions',
+        ],
+        successSignal: 'Doctor reports candidate under contract; gate green with residual honest.',
+        killSwitch: 'Stop if extraction requires multi-module redesign without a clear aggregate owner.',
+        neverMechanicalSafe: true,
+        class: 'judgment',
+        next: 'Run ark_prepare_change / preflight, then re-doctor.',
+    };
+}