arkgate 4.8.23 → 4.8.25

package/bin/lib/arkrules-sensors.mjs

@@ -8,6 +8,8 @@
  * Pure CLI helper (bin/lib/arkrules-sensors.mjs). Zero Node I/O.
  */
 
+import { findClassDeclarations, scanClassMembers } from './class-source-scan.mjs';
+import { sourceHasPersistenceWrite, sourceHasTaggedSqlWrite, sourceImportsPersistenceDriverText, } from './persistence-write-hint.mjs';
 /** Keep in lockstep with arkRulesTypes.ARK_RULE_TIER2_SENSOR_IDS (self-contained for CLI gen). */
 const ARK_RULE_TIER2_SENSOR_IDS = ['no-anemic-model'];
 /**
@@ -30,11 +32,10 @@ export const DOMAIN_EVENTS_PUSH_RE = new RegExp(`\\bthis\\.${EVENTS_ARRAY_PROP}\
 const EVENTS_ARRAY_RESET_RE = new RegExp(`^this\\.${EVENTS_ARRAY_PROP}\\s*=\\s*\\[\\s*\\]`);
 const ANY_THIS_EMPTY_ARRAY_RE = /^this\.[A-Za-z_][A-Za-z0-9_]*\s*=\s*\[\s*\]/;
 const THIS_FIELD_ASSIGNMENT_RE = /\bthis\.[A-Za-z_][A-Za-z0-9_]*\s*=(?!=)/g;
-const SHAPE_TRUNCATED_UNTIL = 'truncatedUntil';
 export function expectedDomainInvariantWordsPhrase() {
     return `${DOMAIN_INVARIANT_WORDS.join(', ')}, or events-array .push(`;
 }
-export function referencesGuardOrPublish(source) {
+function referencesGuardOrPublish(source) {
     return DOMAIN_INVARIANT_WORD_RE.test(source) || DOMAIN_EVENTS_PUSH_RE.test(source);
 }
 export function isIdiomaticEventsReset(source, assignIndex, methodName) {
@@ -59,18 +60,10 @@ function methodAssignsThis(methodName, methodBody) {
     return false;
 }
 function attachShapeTruncation(shape, truncatedUntil) {
-    if (truncatedUntil == null)
-        return shape;
-    Object.defineProperty(shape, SHAPE_TRUNCATED_UNTIL, {
-        value: truncatedUntil,
-        enumerable: false,
-        configurable: true,
-    });
-    return shape;
+    return truncatedUntil == null ? shape : { ...shape, truncatedUntil };
 }
 function shapeTruncatedUntil(shape) {
-    const value = Object.getOwnPropertyDescriptor(shape, SHAPE_TRUNCATED_UNTIL)?.value;
-    return typeof value === 'number' ? value : undefined;
+    return typeof shape.truncatedUntil === 'number' ? shape.truncatedUntil : undefined;
 }
 function shapeTruncationSuffix(shape) {
     const until = shapeTruncatedUntil(shape);
@@ -188,9 +181,22 @@ function shapesForRule(rule, shapes, layerForFile) {
         return true;
     });
 }
+/**
+ * A shape the scanner could not walk to its end (unbalanced header/body) is
+ * reported, never passed in silence: later members may be invisible.
+ */
+function truncatedShapeViolation(rule, shape, what) {
+    const until = shapeTruncatedUntil(shape);
+    if (until == null)
+        return undefined;
+    return baseViolation(rule, shape.file, `Exported class ${shape.className} shape analysed until character ${until}; later ${what} may be invisible (sensor ${rule.sensor}).`);
+}
 function evaluateAggregatePrivateState(rule, shapes, layerForFile) {
     const out = [];
     for (const shape of shapesForRule(rule, shapes, layerForFile)) {
+        const truncated = truncatedShapeViolation(rule, shape, 'members');
+        if (truncated)
+            out.push(truncated);
         // 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) {
@@ -202,6 +208,9 @@ function evaluateAggregatePrivateState(rule, shapes, layerForFile) {
 function evaluateAlwaysValidFactory(rule, shapes, layerForFile) {
     const out = [];
     for (const shape of shapesForRule(rule, shapes, layerForFile)) {
+        const truncated = truncatedShapeViolation(rule, shape, 'constructors and factories');
+        if (truncated)
+            out.push(truncated);
         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
@@ -221,9 +230,9 @@ function evaluateDomainEventOnMutation(rule, shapes, layerForFile) {
     const expected = expectedDomainInvariantWordsPhrase();
     for (const shape of shapesForRule(rule, shapes, layerForFile)) {
         const truncation = shapeTruncationSuffix(shape);
-        if (shapeTruncatedUntil(shape) != null) {
-            out.push(baseViolation(rule, shape.file, `Exported class ${shape.className} shape analysed until character ${shapeTruncatedUntil(shape)}; later methods may be invisible (sensor domain-event-on-mutation).`));
-        }
+        const truncated = truncatedShapeViolation(rule, shape, 'methods');
+        if (truncated)
+            out.push(truncated);
         for (const method of shape.mutatingMethods) {
             if (!method.referencesGuardOrPublish) {
                 out.push(baseViolation(rule, shape.file, `Mutating method ${shape.className}.${method.name} does not reference ${expected} (sensor domain-event-on-mutation).${truncation}`));
@@ -459,24 +468,11 @@ export function collectEmptyInvariantCatalogFindings(input) {
         },
     ];
 }
-/** IO / ORM import evidence. postgres and drizzle-orm include package subpaths. Keep in lockstep with arkOrderFacts. */
-const IO_IMPORT_HINT_RE = /\bfrom\s+['"](?:@?prisma\/client|@supabase\/|drizzle-orm(?:\/[^'"]+)?|postgres(?:\/[^'"]+)?|typeorm|knex|mongodb|pg|mysql2|mongoose|better-sqlite3|ioredis|redis|kysely|sequelize)['"]|require\(\s*['"](?:@?prisma\/client|pg|postgres(?:\/[^'"]+)?|drizzle-orm(?:\/[^'"]+)?|knex|typeorm|mongoose)/;
-/**
- * Path-alias / local db module (`@/lib/db`) without resolving tsconfig.
- * Keep in lockstep with arkOrderFacts.
- */
-const IO_ALIAS_IMPORT_RE = /\bfrom\s+['"](?:@\/|~\/)?(?:[\w.-]+\/)*(?:db|database|prisma|drizzle)(?:\.[cm]?[jt]sx?)?['"]|require\(\s*['"](?:@\/|~\/)?(?:[\w.-]+\/)*(?:db|database|prisma|drizzle)/;
-/**
- * Write tokens that skip the aggregate when paired with a persistence driver import.
- * Callee must be db|tx|client|prisma|drizzle (PrismaClient included); not repo.update(.
- * Keep in lockstep with arkOrderFacts.
- */
-const PERSISTENCE_WRITE_HINT_RE = /\b(?:db|tx|client|prisma(?:Client)?|drizzle)\b(?:\s*\.\s*[A-Za-z_]\w*)*\s*\.\s*(?:insert(?:One|Many)?|update(?:One|Many)?|upsert|delete(?:One|Many)?|createMany|create|replaceOne|findOneAnd(?:Update|Delete|Replace))\s*\(|\bINSERT\s+INTO\b|\bUPDATE\s+[A-Za-z_][\w.]*\s+SET\b|\bDELETE\s+FROM\b/i;
-export function isPersistenceDriverLayer(layer) {
+function isPersistenceDriverLayer(layer) {
     return layer === 'PersistenceAdapters';
 }
-export function sourceImportsPersistenceDriver(content, resolvedImports) {
-    if (IO_IMPORT_HINT_RE.test(content) || IO_ALIAS_IMPORT_RE.test(content))
+function sourceImportsPersistenceDriver(content, resolvedImports) {
+    if (sourceImportsPersistenceDriverText(content))
         return true;
     if (!resolvedImports)
         return false;
@@ -487,7 +483,7 @@ export function sourceImportsPersistenceDriver(content, resolvedImports) {
         if (!specifier)
             continue;
         const synthetic = `from '${specifier}'`;
-        if (IO_IMPORT_HINT_RE.test(synthetic) || IO_ALIAS_IMPORT_RE.test(synthetic))
+        if (sourceImportsPersistenceDriverText(synthetic))
             return true;
     }
     return false;
@@ -506,7 +502,9 @@ export function deriveArkRuleFileHints(_file, content, resolvedImports) {
     if (!content)
         return null;
     const hasIo = sourceImportsPersistenceDriver(content, resolvedImports);
-    const persistenceWrite = hasIo && PERSISTENCE_WRITE_HINT_RE.test(content);
+    // A tagged-template SQL write head is evidence on its own (the use case composed
+    // the statement). ORM verbs and untagged SQL still need a driver import.
+    const persistenceWrite = (hasIo && sourceHasPersistenceWrite(content)) || sourceHasTaggedSqlWrite(content);
     // Orchestration/adapter heuristics need a longer window; writes still fire on short probes.
     if (content.length < 40) {
         return persistenceWrite ? { persistenceWrite: true } : null;
@@ -549,213 +547,18 @@ export function buildArkRuleFileHints(fileContents, resolvedImportsByFile) {
     }
     return out;
 }
-const MEMBER_MODIFIERS = new Set([
-    'public',
-    'private',
-    'protected',
-    'static',
-    'async',
-    'readonly',
-    'abstract',
-    'override',
-    'declare',
-    'get',
-    'set',
-]);
 const CONTROL_FLOW_METHOD_NAMES = new Set(['if', 'match', 'when']);
-function skipStringOrComment(src, index) {
-    const ch = src[index];
-    if (ch === '/' && src[index + 1] === '/') {
-        const nl = src.indexOf('\n', index);
-        return nl === -1 ? src.length : nl;
-    }
-    if (ch === '/' && src[index + 1] === '*') {
-        const end = src.indexOf('*/', index + 2);
-        return end === -1 ? src.length : end + 2;
-    }
-    if (ch === "'" || ch === '"' || ch === '`') {
-        let j = index + 1;
-        while (j < src.length) {
-            if (src[j] === '\\') {
-                j += 2;
-                continue;
-            }
-            if (src[j] === ch)
-                return j + 1;
-            j += 1;
-        }
-        return src.length;
-    }
-    return index;
-}
-function skipWsAndComments(src, index) {
-    let i = index;
-    while (i < src.length) {
-        if (/\s/.test(src[i])) {
-            i += 1;
-            continue;
-        }
-        if (src[i] === '/' && (src[i + 1] === '/' || src[i + 1] === '*')) {
-            i = skipStringOrComment(src, i);
-            continue;
-        }
-        break;
-    }
-    return i;
-}
-function readIdent(src, index) {
-    const ch = src[index];
-    if (!ch || !/[A-Za-z_]/.test(ch))
-        return null;
-    let j = index + 1;
-    while (j < src.length && /[A-Za-z0-9_]/.test(src[j]))
-        j += 1;
-    return { ident: src.slice(index, j), end: j };
-}
-function skipBalanced(src, openIndex, openCh, closeCh) {
-    if (src[openIndex] !== openCh)
-        return null;
-    let depth = 1;
-    let i = openIndex + 1;
-    while (i < src.length && depth > 0) {
-        const skipped = skipStringOrComment(src, i);
-        if (skipped !== i) {
-            i = skipped;
-            continue;
-        }
-        const ch = src[i];
-        if (ch === openCh)
-            depth += 1;
-        else if (ch === closeCh)
-            depth -= 1;
-        i += 1;
-    }
-    return depth === 0 ? i : null;
-}
-function scanClassMembers(body) {
-    const members = [];
-    let i = 0;
-    let truncatedAt;
-    while (i < body.length) {
-        i = skipWsAndComments(body, i);
-        if (i >= body.length)
-            break;
-        if (body[i] === ';') {
-            i += 1;
-            continue;
-        }
-        const modifiers = [];
-        let cursor = i;
-        while (true) {
-            const tok = readIdent(body, cursor);
-            if (!tok || !MEMBER_MODIFIERS.has(tok.ident))
-                break;
-            modifiers.push(tok.ident);
-            cursor = skipWsAndComments(body, tok.end);
-        }
-        const nameTok = readIdent(body, cursor);
-        if (!nameTok) {
-            i += 1;
-            continue;
-        }
-        cursor = skipWsAndComments(body, nameTok.end);
-        if (body[cursor] === '<') {
-            const afterGeneric = skipBalanced(body, cursor, '<', '>');
-            if (afterGeneric == null) {
-                truncatedAt = body.length;
-                break;
-            }
-            cursor = skipWsAndComments(body, afterGeneric);
-        }
-        if (body[cursor] === '(') {
-            const afterParen = skipBalanced(body, cursor, '(', ')');
-            if (afterParen == null) {
-                truncatedAt = body.length;
-                break;
-            }
-            cursor = skipWsAndComments(body, afterParen);
-            if (body[cursor] === ':') {
-                cursor += 1;
-                while (cursor < body.length && body[cursor] !== '{' && body[cursor] !== ';') {
-                    const skipped = skipStringOrComment(body, cursor);
-                    if (skipped !== cursor) {
-                        cursor = skipped;
-                        continue;
-                    }
-                    cursor += 1;
-                }
-            }
-            if (body[cursor] === '{') {
-                const afterBrace = skipBalanced(body, cursor, '{', '}');
-                if (afterBrace == null) {
-                    truncatedAt = body.length;
-                    break;
-                }
-                members.push({
-                    name: nameTok.ident,
-                    modifiers,
-                    kind: 'method',
-                    body: body.slice(cursor + 1, afterBrace - 1),
-                });
-                i = afterBrace;
-                continue;
-            }
-            if (body[cursor] === ';') {
-                i = cursor + 1;
-                continue;
-            }
-            i = cursor + 1;
-            continue;
-        }
-        let depthBrace = 0;
-        let depthParen = 0;
-        let depthBracket = 0;
-        while (cursor < body.length) {
-            const skipped = skipStringOrComment(body, cursor);
-            if (skipped !== cursor) {
-                cursor = skipped;
-                continue;
-            }
-            const ch = body[cursor];
-            if (ch === '{')
-                depthBrace += 1;
-            else if (ch === '}') {
-                if (depthBrace === 0)
-                    break;
-                depthBrace -= 1;
-            }
-            else if (ch === '(')
-                depthParen += 1;
-            else if (ch === ')')
-                depthParen -= 1;
-            else if (ch === '[')
-                depthBracket += 1;
-            else if (ch === ']')
-                depthBracket -= 1;
-            else if (ch === ';' &&
-                depthBrace === 0 &&
-                depthParen === 0 &&
-                depthBracket === 0) {
-                cursor += 1;
-                break;
-            }
-            cursor += 1;
-        }
-        members.push({
-            name: nameTok.ident,
-            modifiers,
-            kind: 'field',
-            body: '',
-        });
-        i = cursor;
-    }
-    return { members, truncatedAt };
-}
 /**
  * Lightweight class-shape extraction from TypeScript source text (no compiler).
  * Conservative: prefers false negatives over false positives for mutability.
  * Tooling may replace with TypeScript-API facts; sensors consume the same shape.
  *
+ * The header and body are walked by the shared tokenizer (classSourceScan):
+ * type parameters (`class Box<T>`), generic `extends` / `implements` clauses, and
+ * braces inside strings, comments, or template literals are handled. A class whose
+ * header or body cannot be walked is still reported, with a truncation mark, so
+ * enforced sensors say so instead of passing in silence.
+ *
  * Limitation (AR05/AR06): only `export class` / `export abstract class` forms.
  * `export default class`, re-exported classes, and non-exported aggregates are
  * invisible — enforced structure sensors stay silent (false negative). Silence
@@ -763,25 +566,25 @@ function scanClassMembers(body) {
  */
 export function extractClassShapesFromSource(file, content) {
     const shapes = [];
-    // Match exported class declarations (simple cases; see limitation above).
-    const classRe = /export\s+(?:abstract\s+)?class\s+([A-Za-z_][A-Za-z0-9_]*)\s*(?:extends\s+[^{]+)?(?:implements\s+[^{]+)?\{/g;
-    let match;
-    while ((match = classRe.exec(content)) !== null) {
-        const className = match[1];
-        const start = match.index + match[0].length;
-        // Brace match body
-        let depth = 1;
-        let i = start;
-        while (i < content.length && depth > 0) {
-            const ch = content[i];
-            if (ch === '{')
-                depth += 1;
-            else if (ch === '}')
-                depth -= 1;
-            i += 1;
+    for (const decl of findClassDeclarations(content, { exportedOnly: true })) {
+        const className = decl.name;
+        if (decl.bodyStart == null) {
+            // Header seen, body not derivable: an unshaped class, never a silent pass.
+            shapes.push(attachShapeTruncation({
+                file,
+                className,
+                exported: true,
+                hasPublicMutableFields: false,
+                hasPublicSetters: false,
+                hasPublicConstructor: false,
+                hasStaticFactory: false,
+                mutatingMethods: [],
+            }, decl.start));
+            continue;
         }
-        const body = content.slice(start, i - 1);
-        const classUnclosed = depth > 0;
+        const start = decl.bodyStart;
+        const classUnclosed = decl.bodyEnd == null;
+        const body = content.slice(start, decl.bodyEnd ?? content.length);
         const scanned = scanClassMembers(body);
         const truncatedUntil = classUnclosed
             ? content.length

package/bin/lib/check-args.mjs

@@ -1,6 +1,7 @@
 /**
  * ark-check CLI flag parsing.
  */
+import fs from 'node:fs';
 import path from 'node:path';
 import { discoverLocalBaseRef, normalizePolicyBaseRef } from './policy-delta-io.mjs';
 
@@ -23,7 +24,26 @@ export const LOCAL_STRICT_MERGE_MESSAGE =
   '--local cannot be combined with --strict-merge: CI stays the full fail-closed check. Use --local (or ARK_CHECK_LOCAL=1) only on the local / pre-push path.';
 
 export const LOCAL_TREE_MODE_MESSAGE =
-  '--local cannot be combined with report modes that need the whole tree (--doctor, --coverage, --plan, --report, --promote). Use --local --base <ref> for the cheap local check.';
+  '--local cannot be combined with report modes that need the whole tree (--doctor, --coverage, --plan, --report, --promote, --probe-invariants) or with --update-baseline. Use --local --base <ref> for the cheap local check.';
+
+const PROBE_RUNNERS = ['vitest', 'jest', 'node'];
+
+export const UPDATE_BASELINE_SCOPE_MESSAGE =
+  '--update-baseline cannot be combined with a changed-files scope (--changed, --local, or a --persona that implies --changed): the baseline is a whole-tree record, and a changed-files scan would overwrite it with only that subset and delete every other frozen key. Drop the scope flag (ARK_CHECK_LOCAL=1 is ignored for a baseline update) and re-run.';
+
+/**
+ * Baseline file that suppresses frozen findings for this run, or null.
+ * Explicit `--baseline` always wins. `--report` (without `--against`) applies the committed
+ * `.ark-baseline.json` by default, the same file `--doctor` reads, so report, `ark status`
+ * and doctor agree on what is active vs frozen.
+ */
+export function effectiveBaselineName(args, root, exists = fs.existsSync) {
+  if (args?.baseline) return args.baseline;
+  // A merge verdict (--strict / --strict-merge / --contract-diff) never inherits the
+  // committed freeze implicitly: adding --report must not flip a fail-closed run to pass.
+  if (!args?.report || args.against || args.strictMerge || args.contractDiff) return null;
+  return exists(path.join(root, '.ark-baseline.json')) ? '.ark-baseline.json' : null;
+}
 
 export function localCheckEnvelope(args, root) {
   if (!args?.local) return {};
@@ -48,6 +68,8 @@ export function applyLocalCheckMode(args, env = process.env) {
     args.plan && '--plan',
     args.report && '--report',
     args.promote && '--promote',
+    args.probeInvariants && '--probe-invariants',
+    args.updateBaseline && '--update-baseline',
   ].filter(Boolean);
   if (args.strictMerge) {
     if (explicit) throw new Error(LOCAL_STRICT_MERGE_MESSAGE);
@@ -182,6 +204,24 @@ export function parseArgs(argv, env = process.env) {
         args.promote = next && !next.startsWith('-') ? argv[++i] : true;
       }
     }
+    else if (arg === '--probe-invariants' || arg.startsWith('--probe-invariants=')) {
+      // Same shape as --promote: bare probes every declared invariant; a value
+      // narrows to one id (`=<id>` also carries an id that begins with '-').
+      const eq = arg.indexOf('=');
+      if (eq > 0) {
+        args.probeInvariants = arg.slice(eq + 1) || true;
+      } else {
+        const next = argv[i + 1];
+        args.probeInvariants = next && !next.startsWith('-') ? argv[++i] : true;
+      }
+    }
+    else if (arg === '--runner') {
+      const value = requireValue(arg, i++).trim().toLowerCase();
+      if (!PROBE_RUNNERS.includes(value)) {
+        throw new Error(`--runner must be one of ${PROBE_RUNNERS.join(', ')} (got ${JSON.stringify(value)}).`);
+      }
+      args.runner = value;
+    }
     else if (arg === '--apply') args.apply = true;
     else if (arg === '--recommend') args.recommend = true;
     else if (arg === '--write-plan') args.writePlan = true;
@@ -288,5 +328,49 @@ export function parseArgs(argv, env = process.env) {
       );
     }
   }
+  assertProbeInvariantsAlone(args);
+  if (args.updateBaseline && (args.changed || args.local)) {
+    throw new Error(UPDATE_BASELINE_SCOPE_MESSAGE);
+  }
   return applyLocalCheckMode(args, env);
 }
+
+/**
+ * ADR 0039 D1: the probe runs the project's own tests in a temporary copy, so
+ * it is never part of a check, the merge gate, status, or a changed-files scope.
+ * Every pairing that would put it on one of those paths is refused, and a
+ * report mode that answers first would make it silently do nothing.
+ */
+function assertProbeInvariantsAlone(args) {
+  if (args.runner && !args.probeInvariants) {
+    throw new Error('--runner applies to --probe-invariants. Run `arkgate-check --probe-invariants --runner <id>`.');
+  }
+  if (!args.probeInvariants) return;
+  const gatePaths = [
+    args.local && '--local',
+    args.changed && '--changed',
+    args.strictMerge && '--strict-merge',
+    args.updateBaseline && '--update-baseline',
+    args.doctor && '--doctor',
+  ].filter(Boolean);
+  if (gatePaths.length > 0) {
+    throw new Error(
+      `--probe-invariants cannot be combined with ${gatePaths.join(', ')}: the probe runs your tests in a temporary copy and is never part of a check, the merge gate, or status. Run it on its own.`
+    );
+  }
+  const shadowing = [
+    args.promote && '--promote',
+    args.sensors && '--sensors',
+    args.pathDrift && '--path-drift',
+    args.coverage && '--coverage',
+    args.plan && '--plan',
+    args.report && '--report',
+    args.rulesInventory && '--rules-inventory',
+    args.recommend && '--recommend',
+  ].filter(Boolean);
+  if (shadowing.length > 0) {
+    throw new Error(
+      `--probe-invariants cannot be combined with ${shadowing.join(', ')}: one of them would answer first and the other would silently do nothing. Run them separately.`
+    );
+  }
+}

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

@@ -16,22 +16,12 @@ import {
   buildAgentProjectionBlock,
 } from './agent-projection.mjs';
 import { getDiagnosticCatalogEntry } from './diagnostic-catalog.mjs';
-import { falseGreenAdoptionGap } from './field-install.mjs';
+import { addPackageJsonPropertyPreservingFormat } from './field-install.mjs';
 import { renderHostSupportMatrixMarkdown } from './host-support-matrix.mjs';
 import { PREFERRED_MCP_BIN } from './hook-templates.mjs';
 import { hasCheckArchitectureScript, readPackageJson } from './gate-files.mjs';
 import { arkPackageVersion } from './skill-install.mjs';
-
-// Field-install helpers re-exported for callers that import from this module.
-export {
-  ensureBaselineFlagInCheckCommand,
-  syncBaselineIntoCheckSurfaces,
-  pinArkgateDevDependency,
-  IO_DIR_SEGMENTS,
-  detectContractFalseGreenRisk,
-  FALSE_GREEN_GAP_ID,
-  falseGreenAdoptionGap,
-} from './field-install.mjs';
+import { arkgateIsProjectDependency, pinnedArkgateRunner } from './package-manager.mjs';
 
 export function checkArgsForRoot(root, { requireGates = false } = {}) {
   const baselineFlag = fs.existsSync(path.join(root, '.ark-baseline.json'))
@@ -41,8 +31,18 @@ export function checkArgsForRoot(root, { requireGates = false } = {}) {
   return `--root . --config ark.config.json ${profile}${baselineFlag}`;
 }
 
-
 export function packageManager(root) {
+  const pm = localPackageManager(root);
+  if (arkgateIsProjectDependency(root)) return pm;
+  // arkgate is not pinned: the local runner would ask npm for a package named `ark-check`
+  // (404) or run a stale global, so name the exact arkgate that generated this workflow.
+  const run = `${pinnedArkgateRunner()} ark-check ${checkArgsForRoot(root, { requireGates: true })}`;
+  // No package.json: nothing to install, and setup-node's cache needs a lockfile.
+  if (!readPackageJson(root)) return { cache: null, setup: [], install: null, run };
+  return { ...pm, run };
+}
+
+function localPackageManager(root) {
   // CI always require-gates; baseline follows checkArgsForRoot.
   const checkArgs = checkArgsForRoot(root, { requireGates: true });
   // Same detection as every emitted command (execRunner): honors the packageManager field and
@@ -102,65 +102,13 @@ export function checkArchitectureScriptSnippet(root) {
  * @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)}`;
+  return addPackageJsonPropertyPreservingFormat(
+    source,
+    'scripts',
+    scriptName,
+    scriptValue,
+    'package.json scripts'
+  );
 }
 
 /**
@@ -243,10 +191,11 @@ ${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
+ * @param {string} [configPath] contract file (defaults to `<root>/ark.config.json`)
  */
-export function loadConfigLayersForAgents(root) {
+export function loadConfigLayersForAgents(root, configPath = path.join(root, 'ark.config.json')) {
   try {
-    const cfgPath = path.join(root, 'ark.config.json');
+    const cfgPath = configPath;
     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;
@@ -638,10 +587,7 @@ ${setupSteps ? `${setupSteps}\n` : ''}      - name: Setup Node
         uses: actions/setup-node@v4
         with:
 ${nodeSetup}
-          cache: ${pm.cache}
-      - name: Install dependencies
-        run: ${pm.install}
-${qualityBlock ? `${qualityBlock}\n` : ''}      - name: Ark architecture check
+${pm.cache ? `          cache: ${pm.cache}\n` : ''}${pm.install ? `      - name: Install dependencies\n        run: ${pm.install}\n` : ''}${qualityBlock ? `${qualityBlock}\n` : ''}      - name: Ark architecture check
         env:
           ARK_POLICY_BASE_REF: \${{ github.event.pull_request.base.sha || github.event.before }}
         run: |

package/bin/lib/ci-merge-boundary.mjs

@@ -6,7 +6,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 export const CI_MERGE_BOUNDARY_REL = '.ark/ci-merge-boundary.json';
-export const CI_MERGE_BOUNDARY_SCHEMA = '1.0';
+const CI_MERGE_BOUNDARY_SCHEMA = '1.0';
 
 /**
  * @param {{