arkgate 4.8.9 → 4.8.11

package/bin/lib/doctor-next-actions.mjs

@@ -116,7 +116,9 @@ export function collectDoctorNextActions(ctx) {
     actions.push('review dirty baseline freezes — fix the contract before trusting green-via-freeze');
   }
   if (ctx.analysisComplete && ctx.staleBaseline > 0) {
-    actions.push('tighten the baseline (--update-baseline)');
+    actions.push(
+      'tighten the baseline (--update-baseline --force --contract-session --author <steward>)'
+    );
   }
   if (ctx.staleRunners.length > 0) {
     actions.push(

package/bin/lib/field-install.mjs

@@ -83,6 +83,27 @@ function addDevDependencyPreservingFormat(source, version) {
   return `${source.slice(0, contentEnd)}${addition}${eol}${rootClosingIndent}${source.slice(rootClose)}`;
 }
 
+const ARK_CHECK_BIN_RE = /\b(?:ark-check|arkgate-check)(?:\.mjs|\.js)?\b/;
+const ARK_CHECK_RUNNER_RE =
+  /(?:^|[\s"'`;|&])(?:npx|pnpm|yarn|npm|bunx?|node)(?:\s|$)/;
+const GITHUB_RUN_KEY_RE = /^\s*(?:-\s+)?run:\s+/;
+const YAML_CHECK_JOB_ID_RE =
+  /^\s*(?:-\s+)?['"]?(?:ark-check|arkgate-check)['"]?\s*:/;
+const YAML_CONCURRENCY_GROUP_RE = /^\s*group:\s+/;
+
+/**
+ * True when the line invokes ark-check / arkgate-check (npx/pnpm/yarn/npm/node/run).
+ * YAML concurrency.group and job-id keys that only contain the name are not invocations.
+ */
+export function isArkCheckInvocationLine(command) {
+  if (typeof command !== 'string' || !command.trim()) return false;
+  if (/^\s*#/.test(command)) return false;
+  if (YAML_CHECK_JOB_ID_RE.test(command)) return false;
+  if (YAML_CONCURRENCY_GROUP_RE.test(command)) return false;
+  if (!ARK_CHECK_BIN_RE.test(command)) return false;
+  return ARK_CHECK_RUNNER_RE.test(command) || GITHUB_RUN_KEY_RE.test(command);
+}
+
 /**
  * Ensure a check command string includes `--baseline <file>`.
  * Only touches strings that already invoke ark-check / arkgate-check.
@@ -97,7 +118,7 @@ export function ensureBaselineFlagInCheckCommand(
   if (/^\s*#/.test(command)) {
     return { command, changed: false };
   }
-  if (!/\b(ark-check|arkgate-check)\b/.test(command)) {
+  if (!isArkCheckInvocationLine(command)) {
     return { command, changed: false };
   }
   if (/(?:^|\s)--baseline(?:\s|=|$)/.test(command)) {
@@ -180,7 +201,7 @@ export function syncBaselineIntoCheckSurfaces(root, opts = {}) {
       let fileChanged = false;
       const nextLines = lines.map((line) => {
         if (/^\s*#/.test(line)) return line;
-        if (!/\b(ark-check|arkgate-check)\b/.test(line)) return line;
+        if (!isArkCheckInvocationLine(line)) return line;
         if (/(?:^|\s)--baseline(?:\s|=|$)/.test(line)) return line;
         const { command, changed: c } = ensureBaselineFlagInCheckCommand(line, flagRel);
         if (c) {

package/bin/lib/first-run-help.mjs

@@ -95,12 +95,74 @@ Non-interactive (no TTY): uses the same defaults as --yes — never calls readli
 `;
 }
 
+/** `--sensors` is contract + coverage-evidence only — never a full-check pass. */
+export const SENSORS_PARTIAL_MODE_LINE =
+  'Contract + coverage-evidence only: no TypeScript, no analysis. Not a validity verdict.';
+
+export const SENSORS_DID_NOT_RUN = Object.freeze(['TypeScript', 'analysis']);
+
+/**
+ * Stamp a successful `--sensors --json` payload so agents cannot read exit 0 as
+ * a full-check pass. Failure payloads (`sensors.ok === false`) stay untouched.
+ */
+export function stampSensorsPartialModePayload(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return payload;
+  const sensors = payload.sensors;
+  if (!sensors || typeof sensors !== 'object' || Array.isArray(sensors)) return payload;
+  if (sensors.ok === false) return payload;
+  return {
+    ...payload,
+    sensors: {
+      ...sensors,
+      notAVerdict: true,
+      didNotRun: [...SENSORS_DID_NOT_RUN],
+      partialMode: 'contract-only',
+    },
+  };
+}
+
+/**
+ * After `runSensors`, name what this mode skipped. Human success prints the
+ * line on stdout; JSON success restamps the captured object. Failures reprint
+ * as-is so exit 2 does not look like a map.
+ */
+export async function withSensorsPartialModeHonesty(args, run) {
+  if (args?.json) {
+    const chunks = [];
+    const original = console.log;
+    console.log = (...parts) => {
+      chunks.push(parts.map(String).join(' '));
+    };
+    try {
+      await run();
+    } finally {
+      console.log = original;
+    }
+    const text = chunks.join('\n');
+    if ((process.exitCode ?? 0) !== 0) {
+      if (text) original(text);
+      return;
+    }
+    try {
+      original(JSON.stringify(stampSensorsPartialModePayload(JSON.parse(text)), null, 2));
+    } catch {
+      original(text);
+    }
+    return;
+  }
+  await run();
+  if ((process.exitCode ?? 0) === 0) {
+    console.log(SENSORS_PARTIAL_MODE_LINE);
+  }
+}
+
 export function checkUsage() {
   return [
     'arkgate-check (alias ark-check) — the architecture check.',
     '',
     '  arkgate-check --doctor         where you are: one status light, one next action',
     '  arkgate-check --strict-merge   CI / merge gate (required GitHub status)',
+    '  arkgate-check --sensors        which sensors can ever be enforced (does not run analysis)',
     '',
     'Every flag and command: arkgate-check --help --all',
   ].join('\n');
@@ -124,7 +186,7 @@ export function checkUsageAll() {
     '           Exit 0 ran and clean, 1 drift remains, 2 could not run (no usable base ref).',
     '       ark-check --sensors [--json]           every sensor with its tier and whether it can EVER be enforced, plus every declared rule',
     '           with its local id, the sensor it delegates to, its source file, its mode and why it can or cannot be promoted.',
-    '           Contract + coverage-evidence only: no TypeScript, no analysis. Exit 0 on a report, 2 if the contract will not load.',
+    `           ${SENSORS_PARTIAL_MODE_LINE} Exit 0 on a report, 2 if the contract will not load.`,
     '       ark-check --promote [<ruleId>] [--json] [--apply]',
     '           what enforcing would cost: the findings each advisory rule already produces, from ONE run rather than one run per attempt.',
     '           Plan by default; --promote <ruleId> --apply (or --promote=<ruleId>) writes mode "enforced" into the ArkRules file that declares it.',
@@ -143,12 +205,14 @@ export function checkUsageAll() {
     '       ark-check --init [--preset hexagonal|layered|feature-sliced|monorepo|ui-surface|vertical-slice|ddd-bounded-contexts|vite-vercel-spa|clean-architecture|onion-architecture] [--force] [--follow-config-root]',
     '       --follow-config-root  On writes (init/install-agent-gates/migrate --write/…), adopt walked-up monorepo config root (default: keep explicit --root)',
     '       ark-check --install-agent-gates [--tools claude,cursor,codex,grok,antigravity] [--require-write-hook <host>] [--skills-only] [--codex-home] [--claude-home] [--grok-home] [--antigravity-home] [--agent-homes] [--force]',
-    '       ark-check --update-baseline [file]     freeze current violations (default .ark-baseline.json)',
+    '       ark-check --update-baseline [file] --force --contract-session --author <steward>',
+    '           freeze current violations (default .ark-baseline.json). --contract-session is required;',
+    '           --force when freeze-refuse fires; --author when stewards[] is set.',
     '       ark-check --print-config eleven-layer',
     '',
-    'Adopting Ark in an existing codebase? Run --update-baseline once to freeze existing',
-    'violations, commit the baseline file, and gate CI with --baseline: only NEW violations',
-    'fail the check, so the ratchet only moves toward zero.',
+    'Adopting Ark in an existing codebase? Run --update-baseline --force --contract-session --author <steward>',
+    'once to freeze existing violations, commit the baseline file, and gate CI with --baseline: only NEW',
+    'violations fail the check, so the ratchet only moves toward zero.',
     '',
     'Team parliament: law files (ark.config / arkrules / .ark-baseline.json) cannot ship in',
     'the same diff as product source. --changed --base <ref> checks touched files only.',

package/bin/lib/project-root.mjs

@@ -88,10 +88,64 @@ export function resolveConfigPathWithinRoot(projectRoot, configPathOrName) {
   return { ok: true, configPath };
 }
 
+function isFile(absPath) {
+  try {
+    return Boolean(fs.statSync(absPath, { throwIfNoEntry: false })?.isFile());
+  } catch {
+    return false;
+  }
+}
+
+/** True when --config is a path (nested or absolute), not a basename to walk. */
+export function configNameIsPath(configName) {
+  return (
+    typeof configName === 'string' &&
+    (path.isAbsolute(configName) || /[\\/]/.test(configName))
+  );
+}
+
+function isInsideRoot(root, target) {
+  const rel = path.relative(root, target);
+  return rel === '' || (!rel.startsWith(`..${path.sep}`) && rel !== '..' && !path.isAbsolute(rel));
+}
+
+/**
+ * Resolve a nested/absolute --config path without walking parents.
+ * `--root examples/app --config examples/app/ark.config.json` must load the nested
+ * contract, not latch onto a parent basename walk.
+ *
+ * @param {string} startDir
+ * @param {string} configName
+ * @returns {string | null} absolute config file path
+ */
+export function resolveConfigPathCandidate(startDir, configName) {
+  if (typeof configName !== 'string' || configName.trim() === '') return null;
+  const start = path.resolve(startDir || process.cwd());
+  if (path.isAbsolute(configName)) return isFile(configName) ? path.resolve(configName) : null;
+
+  const fromStart = path.resolve(start, configName);
+  if (isFile(fromStart)) return fromStart;
+
+  const base = path.basename(configName);
+  const relDir = path.dirname(configName);
+  if (relDir && relDir !== '.') {
+    const namedLeaf = path.basename(relDir);
+    if (namedLeaf && namedLeaf === path.basename(start)) {
+      const stripped = path.join(start, base);
+      if (isFile(stripped)) return stripped;
+    }
+  }
+
+  const fromCwd = path.resolve(process.cwd(), configName);
+  if (fromCwd !== fromStart && isFile(fromCwd)) return fromCwd;
+  return null;
+}
+
 /**
  * Walk parents from startDir looking for configName (default ark.config.json).
  * Bounds: filesystem root, max depth, git root, workspaces package root.
  * Config found at a bound root is accepted; walking above a bound is refused.
+ * Nested relative --config (`examples/app/ark.config.json`) is a file path, never a walk-up name.
  *
  * @param {string} startDir
  * @param {string} [configName='ark.config.json']
@@ -104,17 +158,29 @@ export function findNearestArkConfig(startDir, configName = 'ark.config.json', o
   const boundAtWorkspaces = opts.boundAtWorkspacesRoot !== false;
 
   if (typeof configName === 'string' && path.isAbsolute(configName)) {
-    if (fs.existsSync(configName)) {
+    if (isFile(configName)) {
       const root = path.dirname(configName);
       const start = path.resolve(startDir || process.cwd());
-      return { root, configPath: configName, walkedUp: path.resolve(root) !== start };
+      return { root, configPath: path.resolve(configName), walkedUp: path.resolve(root) !== start };
     }
     return null;
   }
 
+  const name = configName || 'ark.config.json';
+  if (configNameIsPath(name)) {
+    const resolved = resolveConfigPathCandidate(startDir, name);
+    if (!resolved) return null;
+    const start = path.resolve(startDir || process.cwd());
+    const inside = isInsideRoot(start, resolved);
+    return {
+      root: inside ? start : path.dirname(resolved),
+      configPath: resolved,
+      walkedUp: !inside,
+    };
+  }
+
   let dir = path.resolve(startDir || process.cwd());
   const start = dir;
-  const name = configName || 'ark.config.json';
   let depth = 0;
   for (;;) {
     const candidate = path.join(dir, name);
@@ -231,7 +297,7 @@ export function resolveEffectiveProjectRoot(startRoot, opts = {}) {
       config: configName,
       configPath: found.configPath,
       configRoot: found.root,
-      walkedUp: true,
+      walkedUp: found.walkedUp,
       configFound: true,
       writeRootFollowedConfig: adoptWalkedRoot && found.walkedUp,
     };

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

@@ -750,6 +750,83 @@ function declaredIntent(value, config) {
   );
 }
 
+/** Call names whose string arguments are declared intent-reference sites. */
+const INTENT_CALL_NAMES = new Set(['publish', 'subscribe', 'defineIntent', 'registerHandler']);
+
+function isSyntaxWrapper(ts, node) {
+  return Boolean(
+    node &&
+      (ts.isParenthesizedExpression(node) ||
+        ts.isAsExpression(node) ||
+        (typeof ts.isTypeAssertionExpression === 'function' &&
+          ts.isTypeAssertionExpression(node)) ||
+        (typeof ts.isSatisfiesExpression === 'function' && ts.isSatisfiesExpression(node)))
+  );
+}
+
+function unwrapWrappers(ts, node) {
+  let current = node;
+  while (current?.parent && isSyntaxWrapper(ts, current.parent)) {
+    current = current.parent;
+  }
+  return current;
+}
+
+function callCalleeName(ts, node) {
+  if (!node || !ts.isCallExpression(node)) return undefined;
+  const expression = node.expression;
+  if (ts.isIdentifier(expression)) return expression.text;
+  if (ts.isPropertyAccessExpression(expression)) return expression.name.text;
+  return undefined;
+}
+
+function isPublishMetadataSource(ts, sourceProp) {
+  const object = sourceProp.parent;
+  if (!object || !ts.isObjectLiteralExpression(object)) return false;
+  const objectSite = unwrapWrappers(ts, object);
+  const objectParent = objectSite.parent;
+  if (!objectParent) return false;
+  if (ts.isCallExpression(objectParent) && callCalleeName(ts, objectParent) === 'publish') {
+    const args = objectParent.arguments;
+    return args[1] === objectSite || args[2] === objectSite;
+  }
+  if (
+    ts.isPropertyAssignment(objectParent) &&
+    syntaxPropertyName(ts, objectParent.name) === 'metadata'
+  ) {
+    const eventObject = objectParent.parent;
+    if (!eventObject) return false;
+    const eventSite = unwrapWrappers(ts, eventObject);
+    const call = eventSite.parent;
+    return Boolean(
+      call && ts.isCallExpression(call) && callCalleeName(ts, call) === 'publish'
+    );
+  }
+  return false;
+}
+
+/** Events, sagas, and publish metadata — not every string that matches a prefix. */
+function isDeclaredIntentSite(ts, node) {
+  const siteNode = unwrapWrappers(ts, node);
+  const parent = siteNode.parent;
+  if (!parent) return false;
+  if (ts.isCallExpression(parent)) {
+    const name = callCalleeName(ts, parent);
+    if (INTENT_CALL_NAMES.has(name) && parent.arguments.some((arg) => arg === siteNode)) {
+      return true;
+    }
+  }
+  if (ts.isArrayLiteralExpression(parent)) {
+    return isDeclaredIntentSite(ts, parent);
+  }
+  if (ts.isPropertyAssignment(parent)) {
+    const name = syntaxPropertyName(ts, parent.name);
+    if (name === 'intent' || name === 'onEvent' || name === 'reactsTo') return true;
+    if (name === 'source' && isPublishMetadataSource(ts, parent)) return true;
+  }
+  return false;
+}
+
 function mayContainForbiddenCapability(ts, sourceFile, forbiddenGlobals) {
   // Every symbol-aware match originates in an identifier or static string path segment.
   // Inspect decoded AST text so escaped identifiers still take the full checker path.
@@ -788,7 +865,11 @@ function collectPolicyFacts(ts, sourceFile, relativePath, config) {
           : {}),
       });
     }
-    if (ts.isStringLiteralLike(node) && declaredIntent(node.text, config)) {
+    if (
+      ts.isStringLiteralLike(node) &&
+      declaredIntent(node.text, config) &&
+      isDeclaredIntentSite(ts, node)
+    ) {
       intentReferences.push({
         file: relativePath,
         line: lineOf(sourceFile, node.getStart(sourceFile)),

package/bin/lib/rules-inventory.mjs

@@ -8,6 +8,7 @@
  * Pure CLI helper (bin/lib/rules-inventory.mjs). Zero Node I/O.
  */
 
+import { DOMAIN_EVENTS_PUSH_RE, DOMAIN_INVARIANT_WORD_RE, expectedDomainInvariantWordsPhrase, isIdiomaticEventsReset, } from './arkrules-sensors.mjs';
 function lineOf(content, index) {
     return content.slice(0, index).split('\n').length;
 }
@@ -226,7 +227,7 @@ export function buildRulesInventory(input) {
                 /(?:^|\/)[^/]*(?:-access)?\.error\./i.test(posix) ||
                 /(?:^|\/)errors?(?:\/|$)/i.test(posix);
             if (!isErrorBag) {
-                const mutRe = /this\.\w+\s*=/g;
+                const mutRe = /\bthis\.[A-Za-z_][A-Za-z0-9_]*\s*=(?!=)/g;
                 let mut;
                 while ((mut = mutRe.exec(content)) !== null) {
                     const classStart = content.lastIndexOf('class ', mut.index);
@@ -239,15 +240,18 @@ export function buildRulesInventory(input) {
                     if (/\bextends\s+(?:Error|[A-Za-z_$][A-Za-z0-9_$]*Error)\b/.test(classHeader)) {
                         continue;
                     }
+                    if (isIdiomaticEventsReset(content, mut.index))
+                        continue;
                     const window = content.slice(Math.max(0, mut.index - 200), mut.index + 200);
-                    if (!/\b(ensureInvariants|assertInvariants|validate|publish|emit)\b/.test(window)) {
+                    if (!DOMAIN_INVARIANT_WORD_RE.test(window) &&
+                        !DOMAIN_EVENTS_PUSH_RE.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.',
+                            message: `Domain field mutation without nearby ${expectedDomainInvariantWordsPhrase()}.`,
                             confidence: 'heuristic',
                             governedLayer,
                             suggestedArkRule: {