arkgate 4.0.0 → 4.1.0

package/bin/lib/arkrules-sensors.mjs

@@ -97,24 +97,37 @@ function baseViolation(rule, file, message, line = 1) {
         failsStrict,
     };
 }
+/**
+ * When layerForFile is provided, structure sensors require the same classification
+ * as the layer plane: unclassified paths are skipped (NEW-ARKRULES-UNCLASSIFIED-ATTRIBUTION).
+ * Without layerForFile, appliesTo globs alone scope the rule (unit tests / pure eval).
+ */
+function isInRuleLayer(file, rule, layerForFile) {
+    if (!layerForFile)
+        return true;
+    const layer = layerForFile(file);
+    // Unclassified (null/undefined/"") must not inherit rule.provenance.layer attribution.
+    if (!layer)
+        return false;
+    return layer === rule.provenance.layer;
+}
 function shapesForRule(rule, shapes, layerForFile) {
     return shapes.filter((shape) => {
         if (!shape.exported)
             return false;
         if (!matchesAppliesTo(shape.file, rule.appliesTo))
             return false;
-        if (layerForFile) {
-            const layer = layerForFile(shape.file);
-            if (layer && layer !== rule.provenance.layer)
-                return false;
-        }
+        if (!isInRuleLayer(shape.file, rule, layerForFile))
+            return false;
         return true;
     });
 }
 function evaluateAggregatePrivateState(rule, shapes, layerForFile) {
     const out = [];
     for (const shape of shapesForRule(rule, shapes, layerForFile)) {
-        if (shape.hasPublicMutableFields || shape.hasPublicSetters) {
+        // P1-L — require real mutability (setters or non-readonly public fields).
+        // Readonly public props on intentional value/entity shapes are false-positive-prone.
+        if (shape.hasPublicSetters || shape.hasPublicMutableFields) {
             out.push(baseViolation(rule, shape.file, `Exported class ${shape.className} exposes public mutable state (sensor aggregate-private-state).`));
         }
     }
@@ -124,6 +137,14 @@ function evaluateAlwaysValidFactory(rule, shapes, layerForFile) {
     const out = [];
     for (const shape of shapesForRule(rule, shapes, layerForFile)) {
         if (shape.hasPublicConstructor && !shape.hasStaticFactory) {
+            // P1-L — prefer false negatives on intentional DDD / DI aggregates: a public
+            // constructor alone is weak evidence. Only fire when mutable public surface
+            // exists (needs an always-valid construction story).
+            const needsAlwaysValidStory = shape.hasPublicMutableFields ||
+                shape.hasPublicSetters ||
+                (shape.mutatingMethods?.length ?? 0) > 0;
+            if (!needsAlwaysValidStory)
+                continue;
             out.push(baseViolation(rule, shape.file, `Exported class ${shape.className} exposes a public constructor without a static factory (sensor always-valid-factory).`));
         }
     }
@@ -145,11 +166,8 @@ function evaluateOrchestrationOnly(rule, input) {
     for (const file of input.files) {
         if (!matchesAppliesTo(file, rule.appliesTo))
             continue;
-        if (input.layerForFile) {
-            const layer = input.layerForFile(file);
-            if (layer && layer !== rule.provenance.layer)
-                continue;
-        }
+        if (!isInRuleLayer(file, rule, input.layerForFile))
+            continue;
         if (input.fileHints?.[file]?.orchestrationHeavy) {
             out.push(baseViolation(rule, file, `File appears to embed domain branching beyond guard-and-delegate orchestration (sensor orchestration-only).`));
         }
@@ -161,11 +179,8 @@ function evaluateThinAdapter(rule, input) {
     for (const file of input.files) {
         if (!matchesAppliesTo(file, rule.appliesTo))
             continue;
-        if (input.layerForFile) {
-            const layer = input.layerForFile(file);
-            if (layer && layer !== rule.provenance.layer)
-                continue;
-        }
+        if (!isInRuleLayer(file, rule, input.layerForFile))
+            continue;
         if (input.fileHints?.[file]?.adapterThick) {
             out.push(baseViolation(rule, file, `Adapter module mixes domain branching, persistence, and mapping beyond a thin adapter (sensor thin-adapter).`));
         }
@@ -358,11 +373,26 @@ export function extractClassShapesFromSource(file, content) {
             i += 1;
         }
         const body = content.slice(start, i - 1);
-        const hasPublicMutableFields = /(?:^|\n)\s*(?:public\s+)?(?:readonly\s+)?[a-zA-Z_][a-zA-Z0-9_]*\s*[:=]/m.test(body.replace(/(?:public\s+|private\s+|protected\s+|readonly\s+|static\s+|async\s+|get\s+|set\s+)/g, '')) &&
-            /(?:^|\n)\s*(public\s+)?(?!constructor|static|get|set|private|protected|readonly)[a-zA-Z_][a-zA-Z0-9_]*\s*[:=]/m.test(body);
-        // Simpler public field detection: "public foo" or unadorned "foo:" at class level
-        const publicField = /(?:^|\n)\s*public\s+(?!static|async|get|set|constructor)[a-zA-Z_]/.test(body) ||
-            /(?:^|\n)\s*[a-zA-Z_][a-zA-Z0-9_]*\s*:\s*[^=;\n]+[;=]/m.test(body
+        // P1-L — prefer false negatives: readonly public props are not mutable state.
+        // Strip only readonly property *declarations*, not whole lines (co-located
+        // `public readonly id; public count = 0` must keep the mutable field).
+        // Also ignore comment lines that merely mention the word "readonly".
+        const bodyNoReadonly = body
+            .split('\n')
+            .map((line) => {
+            if (/^\s*\/\//.test(line) || /^\s*\/\*|\*\//.test(line))
+                return line;
+            // Remove `public readonly foo` / `readonly foo` decls; leave other decls.
+            return line
+                .replace(/(?:public\s+|protected\s+)?readonly\s+[a-zA-Z_][a-zA-Z0-9_]*\s*(?::[^=;]+)?(?:=\s*[^;]+)?[;,]?/g, '')
+                .replace(/(?:^|[\s;{])readonly\s+[a-zA-Z_][a-zA-Z0-9_]*\s*(?::[^=;]+)?(?:=\s*[^;]+)?[;,]?/g, ' ');
+        })
+            .join('\n');
+        const hasPublicMutableFields = /(?:^|\n)\s*(?:public\s+)?[a-zA-Z_][a-zA-Z0-9_]*\s*[:=]/m.test(bodyNoReadonly.replace(/(?:public\s+|private\s+|protected\s+|static\s+|async\s+|get\s+|set\s+)/g, '')) &&
+            /(?:^|\n)\s*(public\s+)?(?!constructor|static|get|set|private|protected|readonly)[a-zA-Z_][a-zA-Z0-9_]*\s*[:=]/m.test(bodyNoReadonly);
+        // Public mutable field: "public foo" (not readonly) or unadorned assignable field.
+        const publicField = /(?:^|\n)\s*public\s+(?!static|async|get|set|constructor|readonly)[a-zA-Z_]/.test(bodyNoReadonly) ||
+            /(?:^|[\n;])\s*[a-zA-Z_][a-zA-Z0-9_]*\s*:\s*[^=;\n]+[;=]/m.test(bodyNoReadonly
                 .split('\n')
                 .filter((line) => !/^\s*(private|protected|static|constructor|get |set |async |\/)/.test(line))
                 .join('\n'));
@@ -372,10 +402,15 @@ export function extractClassShapesFromSource(file, content) {
         const hasStaticFactory = /(?:^|[\n;{])\s*static\s+(?:async\s+)?(?:create|of|from|parse|build|make|new)\s*[<(]/.test(body) ||
             /(?:^|[\n;{])\s*static\s+(?:async\s+)?[A-Za-z_][A-Za-z0-9_]*\s*\([^)]*\)\s*:\s*[A-Za-z_]/.test(body);
         const mutatingMethods = [];
+        // P1-L / P1L-STRUCTURE-NOISE-CONTROL-FLOW: fluent control-flow helpers (Property.if,
+        // .match, .when) often assign this.* for chaining — not domain mutators. Prefer FN.
+        const CONTROL_FLOW_METHOD_NAMES = new Set(['if', 'match', 'when']);
         const methodRe = /(?:^|\n)\s*(?:public\s+|private\s+|protected\s+|async\s+)*(?!constructor|get|set|static)([a-zA-Z_][a-zA-Z0-9_]*)\s*\([^)]*\)\s*(?::\s*[^{]+)?\{/g;
         let methodMatch;
         while ((methodMatch = methodRe.exec(body)) !== null) {
             const name = methodMatch[1];
+            if (CONTROL_FLOW_METHOD_NAMES.has(name))
+                continue;
             const mStart = methodMatch.index + methodMatch[0].length;
             let mDepth = 1;
             let j = mStart;
@@ -394,7 +429,13 @@ export function extractClassShapesFromSource(file, content) {
             mutatingMethods.push({ name, referencesGuardOrPublish });
         }
         const methodCount = (body.match(/(?:^|\n)\s*(?:public\s+|private\s+|protected\s+)?(?:async\s+)?[a-zA-Z_][a-zA-Z0-9_]*\s*\(/g) ?? []).length;
-        const dataOnly = methodCount <= 1 && (publicField || hasPublicMutableFields);
+        // P1-L — raise anemic bar: need multiple public fields and essentially no behavior.
+        // Single-field bags and intentional property bags with one helper stay quiet.
+        // Count fields after line starts *or* after `;` so one-line class bodies still work.
+        const publicFieldCount = (bodyNoReadonly.match(/(?:^|[\n;])\s*(?:public\s+)?(?!constructor|static|get|set|private|protected|readonly)[a-zA-Z_][a-zA-Z0-9_]*\s*[:=]/g) ?? []).length;
+        const dataOnly = methodCount <= 1 &&
+            publicFieldCount >= 2 &&
+            (publicField || hasPublicMutableFields);
         shapes.push({
             file,
             className,

package/bin/lib/ci-and-commands.mjs

@@ -14,7 +14,7 @@ import {
 import { falseGreenAdoptionGap } from './field-install.mjs';
 import { renderHostSupportMatrixMarkdown } from './host-support-matrix.mjs';
 import { PREFERRED_MCP_BIN } from './hook-templates.mjs';
-import { readPackageJson } from './gate-files.mjs';
+import { hasCheckArchitectureScript, readPackageJson } from './gate-files.mjs';
 
 // Field-install helpers re-exported for callers that import from this module.
 export {
@@ -88,6 +88,97 @@ export function checkArchitectureScriptSnippet(root) {
   return `"check:architecture": "${arkCheckCommand(root)}"`;
 }
 
+/**
+ * Insert a package.json scripts entry while preserving indentation / formatting
+ * (same contract as pinArkgateDevDependency format-preserving edits).
+ * @param {string} source
+ * @param {string} scriptName
+ * @param {string} scriptValue
+ */
+function addPackageScriptPreservingFormat(source, scriptName, scriptValue) {
+  const multiline = /\r?\n/.test(source);
+  const eol = source.includes('\r\n') ? '\r\n' : '\n';
+  const rootPropertyIndent = source.match(/\r?\n([ \t]+)"[^"\n]+"\s*:/)?.[1] ?? '  ';
+  const indentUnit = rootPropertyIndent;
+  const encoded = JSON.stringify(scriptValue);
+  const key = JSON.stringify(scriptName);
+  const scriptsMatch = /"scripts"\s*:\s*\{/.exec(source);
+
+  if (scriptsMatch) {
+    const open = source.indexOf('{', scriptsMatch.index);
+    let depth = 0;
+    let quoted = false;
+    let escaped = false;
+    let close = -1;
+    for (let index = open; index < source.length; index += 1) {
+      const char = source[index];
+      if (quoted) {
+        if (escaped) escaped = false;
+        else if (char === '\\') escaped = true;
+        else if (char === '"') quoted = false;
+        continue;
+      }
+      if (char === '"') quoted = true;
+      else if (char === '{') depth += 1;
+      else if (char === '}' && --depth === 0) {
+        close = index;
+        break;
+      }
+    }
+    if (close === -1) throw new Error('Unbalanced package.json scripts object');
+    const body = source.slice(open + 1, close);
+    if (!multiline) {
+      const addition = body.trim() ? `,${key}:${encoded}` : `${key}:${encoded}`;
+      return `${source.slice(0, close)}${addition}${source.slice(close)}`;
+    }
+    const beforeClose = source.slice(0, close);
+    const trailing = beforeClose.match(/\s*$/)?.[0] ?? '';
+    const contentEnd = close - trailing.length;
+    const closingIndent = trailing.slice(trailing.lastIndexOf('\n') + 1);
+    const propertyIndent = `${closingIndent}${indentUnit}`;
+    const addition = body.trim()
+      ? `,${eol}${propertyIndent}${key}: ${encoded}`
+      : `${propertyIndent}${key}: ${encoded}`;
+    return `${source.slice(0, contentEnd)}${addition}${eol}${closingIndent}${source.slice(close)}`;
+  }
+
+  const rootClose = source.lastIndexOf('}');
+  if (rootClose === -1) throw new Error('Unbalanced package.json object');
+  const rootBody = source.slice(0, rootClose);
+  if (!multiline) {
+    const separator = rootBody.trim().endsWith('{') ? '' : ',';
+    return `${rootBody}${separator}"scripts":{${key}:${encoded}}${source.slice(rootClose)}`;
+  }
+  const trailing = rootBody.match(/\s*$/)?.[0] ?? '';
+  const contentEnd = rootClose - trailing.length;
+  const rootClosingIndent = trailing.slice(trailing.lastIndexOf('\n') + 1);
+  const separator = source.slice(0, contentEnd).trimEnd().endsWith('{') ? '' : ',';
+  const addition = `${separator}${eol}${rootPropertyIndent}"scripts": {${eol}${rootPropertyIndent}${indentUnit}${key}: ${encoded}${eol}${rootPropertyIndent}}`;
+  return `${source.slice(0, contentEnd)}${addition}${eol}${rootClosingIndent}${source.slice(rootClose)}`;
+}
+
+/**
+ * Ensure package.json has `check:architecture` so local/CI parity is not a post-start gap.
+ * Never overwrites an existing script (even if stale). Preserves package.json formatting.
+ *
+ * @param {string} root
+ * @param {{ write?: boolean }} [opts]
+ * @returns {{ changed: boolean, reason: 'added'|'already'|'no-package-json', script?: string }}
+ */
+export function ensureCheckArchitectureScript(root, opts = {}) {
+  const write = opts.write !== false;
+  const pkgPath = path.join(root, 'package.json');
+  if (!fs.existsSync(pkgPath)) return { changed: false, reason: 'no-package-json' };
+  if (hasCheckArchitectureScript(root)) return { changed: false, reason: 'already' };
+  const script = arkCheckCommand(root);
+  if (write) {
+    const source = fs.readFileSync(pkgPath, 'utf8');
+    const next = addPackageScriptPreservingFormat(source, 'check:architecture', script);
+    fs.writeFileSync(pkgPath, next.endsWith('\n') ? next : `${next}\n`);
+  }
+  return { changed: true, reason: 'added', script };
+}
+
 // Canonical agent contract. AGENTS.md and the Cursor rule both derive from this single
 // source so the steps can never drift out of sync between the two files. `steps(checkCommand)`
 // is a builder because the check command's runner prefix varies with the package manager.
@@ -105,7 +196,30 @@ const AGENT_CONTRACT = {
   cursorValidateStep: `Validate the full post-edit file content with the \`validate_code\` tool before writing whenever your runtime supports it.`,
 };
 
-export function layerPlacementTable() {
+/**
+ * Placement table for AGENTS.md. Prefer live `ark.config.json` layers when provided
+ * so custom contracts (e.g. 8-layer monorepo) do not get a stock 11-layer table.
+ *
+ * @param {Array<{ name?: string, layer?: string, patterns?: string[], intentPrefixes?: string[], prefixes?: string[] }>|null|undefined} [layers]
+ */
+export function layerPlacementTable(layers) {
+  if (Array.isArray(layers) && layers.length > 0) {
+    const rows = layers
+      .map((layer) => {
+        const name = layer.name ?? layer.layer ?? 'Unknown';
+        const patterns = (layer.patterns ?? [])
+          .map((pattern) => `\`${pattern}\``)
+          .join(', ') || '—';
+        const prefixes = (layer.intentPrefixes ?? layer.prefixes ?? [])
+          .map((prefix) => `\`${prefix}\``)
+          .join(', ') || '—';
+        return `| ${name} | ${patterns} | ${prefixes} |`;
+      })
+      .join('\n');
+    return `| Layer | Patterns (from ark.config.json) | Intent prefixes |
+|-------|----------------------------------|-----------------|
+${rows}`;
+  }
   const rows = DEFAULT_INTENT_PREFIXES.map((entry) => {
     const dirs = (DEFAULT_LAYER_DIRECTORIES[entry.layer] ?? [])
       .map((directory) => `\`${directory}/\``)
@@ -117,6 +231,23 @@ export function layerPlacementTable() {
 ${rows}`;
 }
 
+/**
+ * Load project layers for AGENTS generation. Returns null when config is absent/invalid
+ * so callers fall back to the stock 11-layer table.
+ * @param {string} root
+ */
+export function loadConfigLayersForAgents(root) {
+  try {
+    const cfgPath = path.join(root, 'ark.config.json');
+    if (!fs.existsSync(cfgPath)) return null;
+    const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+    if (!Array.isArray(cfg?.layers) || cfg.layers.length === 0) return null;
+    return cfg.layers;
+  } catch {
+    return null;
+  }
+}
+
 export function agentInstructions(root) {
   const checkCmd = arkCheckCommand(root);
   const startCmd = arkCommand(root, 'ark', 'start');
@@ -124,6 +255,20 @@ export function agentInstructions(root) {
   const steps = AGENT_CONTRACT.steps(checkCmd)
     .map((step, index) => `${index + 1}. ${step}`)
     .join('\n');
+  const liveLayers = loadConfigLayersForAgents(root);
+  const placementTable = layerPlacementTable(liveLayers);
+  const placementBody = liveLayers
+    ? `\`ark.config.json\` is authoritative for this project. Place new code in these **${liveLayers.length}** configured layer(s) — do not invent an ungoverned location or assume the stock 11-layer layout:
+
+${placementTable}
+
+When creating a NEW kind of code that no existing layer covers, add a layer to \`ark.config.json\` first (via \`/ark-contract\`), then place the file.`
+    : `\`ark.config.json\` is authoritative for this project. When creating a NEW kind of code
+that no existing layer covers (a saga, a background job, a read model, ...), use the
+default 11-layer placement below and add the layer to \`ark.config.json\` — do not invent
+an ungoverned location:
+
+${placementTable}`;
   return `# Ark Enforcement
 
 ## Default agent flow (if unsure, do only this)
@@ -181,12 +326,7 @@ ${steps}
 
 ## Where new code belongs
 
-\`ark.config.json\` is authoritative for this project. When creating a NEW kind of code
-that no existing layer covers (a saga, a background job, a read model, ...), use the
-default 11-layer placement below and add the layer to \`ark.config.json\` — do not invent
-an ungoverned location:
-
-${layerPlacementTable()}
+${placementBody}
 
 The project is only considered Ark-enforced when its host-appropriate write path is configured
 and the CI check passes. Only Claude/Grok provide a hard local write boundary; Cursor/Codex use

package/bin/lib/core-ratchet.mjs

@@ -3,10 +3,10 @@
  * Keeps ark-check.mjs orchestration-only (dispatch only).
  */
 import fs from 'node:fs';
-import path from 'node:path';
 import { arkCommand } from '../ark-shared.mjs';
 import { computeCoverage } from './doctor-plan.mjs';
 import { CORE_LAYER_NAMES } from './core-layers.mjs';
+import { resolveConfigPathWithinRoot } from './project-root.mjs';
 
 export { CORE_LAYER_NAMES } from './core-layers.mjs';
 
@@ -68,9 +68,6 @@ export function runRatchetCores(root, config, files, rules, violations, args, de
   const displayPathFromRoot = deps.displayPathFromRoot;
   const cov = computeCoverage(root, config, files, rules);
   const activeCount = Array.isArray(violations) ? violations.length : 0;
-  const configPath = path.isAbsolute(args.config)
-    ? args.config
-    : path.join(root, args.config || 'ark.config.json');
 
   const refuse = (code, message, extra = {}) => {
     if (args.json) {
@@ -81,6 +78,14 @@ export function runRatchetCores(root, config, files, rules, violations, args, de
     process.exitCode = code;
   };
 
+  // Contain --config writes under project root (S0 security).
+  const contained = resolveConfigPathWithinRoot(root, args.config || 'ark.config.json');
+  if (!contained.ok) {
+    refuse(2, contained.error);
+    return;
+  }
+  const configPath = contained.configPath;
+
   if (activeCount > 0) {
     refuse(
       2,

package/bin/lib/doctor-advisories.mjs

@@ -48,7 +48,14 @@ export function computeDoctorAdvisories(root, config, cov, rules, files, ts, par
     // Y09 direction: advisory graph-blind spots (template-interpolation); never hard verdict.
     graphBlindSpots: detectGraphBlindSpots(ts, root, files),
     // AR12 — Rules under contract (honest counts; real test I/O, never empty-fileContents stub).
-    rulesUnderContract: summarizeRulesUnderContract(root, config, factPaths),
+    // P1M: pass classification so extraMergeTeeth cannot arm at 0% governed.
+    rulesUnderContract: summarizeRulesUnderContract(root, config, factPaths, {
+      governedPercent: cov?.governed?.percent ?? null,
+      populatedLayerCount: Array.isArray(cov?.layers)
+        ? cov.layers.filter((row) => (row?.files ?? 0) > 0).length
+        : null,
+      classifiedFiles: cov?.governed?.classifiedFiles ?? null,
+    }),
   };
 }