arkgate 4.0.1 → 4.1.0

package/bin/lib/project-root.mjs

@@ -0,0 +1,268 @@
+/**
+ * Effective project root for ark-check / doctor.
+ *
+ * Monorepo honesty (NEW-MONOREPO-CWD-WALKUP): when cwd (or --root) has no
+ * ark.config.json, walk parent directories until one is found. Never invent a
+ * silent 11-layer / empty ADAPT world while a parent monorepo contract exists.
+ *
+ * Security (S0 walk-up review):
+ * - Split **config discovery root** from **write root**.
+ * - Walk-up is for read/doctor/check by default.
+ * - Mutating commands stay on explicit --root/cwd unless --follow-config-root.
+ * - Walk is bounded by git root, workspaces package root, and max depth.
+ * - Config write paths must stay under the write root (no --config ../outside).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Safety cap so a pathological tree cannot walk forever. */
+export const MAX_CONFIG_WALK_DEPTH = 32;
+
+/**
+ * True when dir looks like a package-manager workspaces / monorepo root.
+ * Used as an upper bound for walk-up (config at this root is accepted; parents are not).
+ * @param {string} dir
+ */
+export function isWorkspacesPackageRoot(dir) {
+  const pkgPath = path.join(dir, 'package.json');
+  try {
+    if (!fs.statSync(pkgPath, { throwIfNoEntry: false })?.isFile()) {
+      // still check workspace marker files below
+    } else {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      if (
+        pkg &&
+        (Array.isArray(pkg.workspaces) ||
+          (pkg.workspaces && typeof pkg.workspaces === 'object'))
+      ) {
+        return true;
+      }
+    }
+  } catch {
+    // ignore
+  }
+  for (const marker of ['pnpm-workspace.yaml', 'lerna.json', 'rush.json', 'nx.json']) {
+    try {
+      if (fs.statSync(path.join(dir, marker), { throwIfNoEntry: false })?.isFile()) return true;
+    } catch {
+      // ignore
+    }
+  }
+  return false;
+}
+
+/**
+ * True when dir is a git worktree root (.git file or directory).
+ * @param {string} dir
+ */
+export function isGitRoot(dir) {
+  try {
+    const git = path.join(dir, '.git');
+    const st = fs.statSync(git, { throwIfNoEntry: false });
+    return Boolean(st && (st.isDirectory() || st.isFile()));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve config path and require it is under projectRoot (or equal).
+ * Used by mutative paths (migrate-contract --write, init --force, etc.).
+ *
+ * @param {string} projectRoot
+ * @param {string} configPathOrName absolute path or relative name
+ * @returns {{ ok: true, configPath: string } | { ok: false, error: string, configPath: string }}
+ */
+export function resolveConfigPathWithinRoot(projectRoot, configPathOrName) {
+  const root = path.resolve(projectRoot || process.cwd());
+  const raw = configPathOrName || 'ark.config.json';
+  const configPath = path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(root, raw);
+  const rel = path.relative(root, configPath);
+  if (rel.startsWith('..') || path.isAbsolute(rel)) {
+    return {
+      ok: false,
+      configPath,
+      error: `Refusing config path outside project root: ${configPath} (root ${root}). Pass a path under --root, or only use --follow-config-root when intentional monorepo writes are required.`,
+    };
+  }
+  return { ok: true, configPath };
+}
+
+/**
+ * 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.
+ *
+ * @param {string} startDir
+ * @param {string} [configName='ark.config.json']
+ * @param {{ maxDepth?: number, boundAtGitRoot?: boolean, boundAtWorkspacesRoot?: boolean }} [opts]
+ * @returns {{ root: string, configPath: string, walkedUp: boolean } | null}
+ */
+export function findNearestArkConfig(startDir, configName = 'ark.config.json', opts = {}) {
+  const maxDepth = Number.isFinite(opts.maxDepth) ? opts.maxDepth : MAX_CONFIG_WALK_DEPTH;
+  const boundAtGit = opts.boundAtGitRoot !== false;
+  const boundAtWorkspaces = opts.boundAtWorkspacesRoot !== false;
+
+  if (typeof configName === 'string' && path.isAbsolute(configName)) {
+    if (fs.existsSync(configName)) {
+      const root = path.dirname(configName);
+      const start = path.resolve(startDir || process.cwd());
+      return { root, configPath: configName, walkedUp: path.resolve(root) !== start };
+    }
+    return null;
+  }
+
+  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);
+    try {
+      if (fs.statSync(candidate, { throwIfNoEntry: false })?.isFile()) {
+        return {
+          root: dir,
+          configPath: candidate,
+          walkedUp: dir !== start,
+        };
+      }
+    } catch {
+      // unreadable — keep walking
+    }
+
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    depth += 1;
+    if (depth > maxDepth) return null;
+
+    // Do not walk above git / workspaces roots (config at this dir already checked).
+    if (boundAtGit && isGitRoot(dir)) return null;
+    if (boundAtWorkspaces && isWorkspacesPackageRoot(dir)) return null;
+
+    dir = parent;
+  }
+}
+
+/**
+ * Resolve config discovery vs write roots for CLI invocation.
+ *
+ * - If config exists at startRoot → use startRoot for both.
+ * - Else walk parents for config (bounded) → configRoot may differ from writeRoot.
+ * - writeMode without followConfigRoot: keep writeRoot/start as `root` (do not rewrite parent).
+ * - writeMode + followConfigRoot (or read mode): adopt walked config root as `root`.
+ *
+ * @param {string} startRoot
+ * @param {{
+ *   configName?: string,
+ *   writeMode?: boolean,
+ *   followConfigRoot?: boolean,
+ *   maxDepth?: number,
+ * }} [opts]
+ * @returns {{
+ *   root: string,
+ *   writeRoot: string,
+ *   config: string,
+ *   configPath: string,
+ *   configRoot: string,
+ *   walkedUp: boolean,
+ *   configFound: boolean,
+ *   writeRootFollowedConfig: boolean,
+ * }}
+ */
+export function resolveEffectiveProjectRoot(startRoot, opts = {}) {
+  const configName = opts.configName || 'ark.config.json';
+  const start = path.resolve(startRoot || process.cwd());
+  const writeMode = opts.writeMode === true;
+  const followConfigRoot = opts.followConfigRoot === true;
+  // Writes adopt walked config root only with explicit opt-in.
+  const adoptWalkedRoot = !writeMode || followConfigRoot;
+
+  if (typeof configName === 'string' && path.isAbsolute(configName)) {
+    const found = findNearestArkConfig(start, configName, opts);
+    if (found) {
+      const root = adoptWalkedRoot ? found.root : start;
+      return {
+        root,
+        writeRoot: start,
+        config: configName,
+        configPath: found.configPath,
+        configRoot: found.root,
+        walkedUp: found.walkedUp,
+        configFound: true,
+        writeRootFollowedConfig: adoptWalkedRoot && found.walkedUp,
+      };
+    }
+    return {
+      root: start,
+      writeRoot: start,
+      config: configName,
+      configPath: configName,
+      configRoot: start,
+      walkedUp: false,
+      configFound: false,
+      writeRootFollowedConfig: false,
+    };
+  }
+
+  const localPath = path.join(start, configName);
+  try {
+    if (fs.statSync(localPath, { throwIfNoEntry: false })?.isFile()) {
+      return {
+        root: start,
+        writeRoot: start,
+        config: configName,
+        configPath: localPath,
+        configRoot: start,
+        walkedUp: false,
+        configFound: true,
+        writeRootFollowedConfig: false,
+      };
+    }
+  } catch {
+    // fall through to walk-up
+  }
+
+  const found = findNearestArkConfig(start, configName, opts);
+  if (found) {
+    const root = adoptWalkedRoot ? found.root : start;
+    return {
+      root,
+      writeRoot: start,
+      config: configName,
+      configPath: found.configPath,
+      configRoot: found.root,
+      walkedUp: true,
+      configFound: true,
+      writeRootFollowedConfig: adoptWalkedRoot && found.walkedUp,
+    };
+  }
+
+  return {
+    root: start,
+    writeRoot: start,
+    config: configName,
+    configPath: localPath,
+    configRoot: start,
+    walkedUp: false,
+    configFound: false,
+    writeRootFollowedConfig: false,
+  };
+}
+
+/**
+ * Commands that mutate project files under --root.
+ * Walk-up must not rewrite a parent monorepo unless --follow-config-root.
+ * @param {Record<string, unknown>} args
+ */
+export function isMutatingCliCommand(args = {}) {
+  if (args.installAgentGates) return true;
+  if (args.init) return true;
+  if (args.applyPolicyPack) return true;
+  if (args.migrateContract && args.write) return true;
+  if (args.adoptContract && args.write) return true;
+  if (args.updateBaseline) return true;
+  if (args.ratchetCores) return true;
+  if (args.migrateCommands) return true;
+  if (args.suggestInclude && args.write) return true;
+  return false;
+}

package/bin/lib/remediation.mjs

@@ -109,14 +109,7 @@ export function classifyRemediation(violation) {
                 rationale: 'Whole source file is type-only surface (no runtime statements) with a type-only cross-layer edge: relocate the file to the owning layer (or extract the type there). Behavior-preserving; gate verifies.',
             };
         }
-        if (violation?.typeOnly) {
-            return {
-                class: 'mechanical-safe',
-                confidence: 0.9,
-                remediationKind: 'type-only-import-move',
-                rationale: 'Type-only import (erased at runtime): move the type to the layer that owns it and re-export for back-compat. Behavior-preserving, and the gate verifies it.',
-            };
-        }
+        // Pure type-only *module* first (target has no value exports) — convert to import type.
         if (violation?.targetTypeOnlyExports) {
             return {
                 class: 'mechanical-safe',
@@ -125,9 +118,9 @@ export function classifyRemediation(violation) {
                 rationale: 'Static import targets a pure type-only module: convert to `import type` (erased at runtime) and place the type in a shared/owning layer. No runtime coupling; gate verifies.',
             };
         }
-        // R6: value-syntax named import/export of type-only exports from a mixed module.
-        // Only set when scan proves no dual-space value export and no top-level side effects.
-        if (violation?.namedBindingsTypeOnly) {
+        // R6: value-syntax named import of type-only exports from a *mixed* module.
+        // When the edge is already `import type`, prefer relocate (type-only-import-move) below.
+        if (violation?.namedBindingsTypeOnly && !violation?.typeOnly) {
             return {
                 class: 'mechanical-safe',
                 confidence: 0.86,
@@ -135,6 +128,14 @@ export function classifyRemediation(violation) {
                 rationale: 'Named bindings are type-only exports of the target module (even if the file also exports values): convert to `import type` / `export type` (erased at runtime). Gate verifies.',
             };
         }
+        if (violation?.typeOnly) {
+            return {
+                class: 'mechanical-safe',
+                confidence: 0.9,
+                remediationKind: 'type-only-import-move',
+                rationale: 'Type-only import (erased at runtime): move the type to the layer that owns it and re-export for back-compat. Behavior-preserving, and the gate verifies it.',
+            };
+        }
         // W6: port-proof inject is a *suggested* shape when proof holds, but always judgment
         // for auto-apply — adding a required parameter breaks external call sites.
         if (violation?.portProofEligible &&

package/bin/lib/rules-inventory.mjs

@@ -15,11 +15,24 @@ 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 posix = file.replace(/\\/g, '/');
+        // P2-N — clear UI bags only (components/theme/styles). Do NOT blanket-skip all
+        // app/pages (server actions / route handlers live there and stay inventoriable).
+        const isUiChrome = /(?:^|\/)(?:components|ui|layouts|styles|hooks|theme|tokens|i18n|locales?)(?:\/|$)/i.test(posix) ||
+            /(?:^|\/)(?:src\/)?(?:app|pages)\/.+\.(?:tsx|jsx)$/i.test(posix) &&
+                /(?:page|layout|loading|error|template|default)\.(?:tsx|jsx)$/i.test(posix);
+        const isApiRoute = /(?:^|\/)(?:app|pages)(?:\/[^/]+)*\/api(?:\/|$)/i.test(posix);
+        const isServerAction = /(?:^|\/)actions?(?:\/|\.|$)/i.test(posix) || /['"]use server['"]/.test(content);
+        const isController = /controller|handler|resolver/i.test(file) ||
+            isApiRoute ||
+            isServerAction ||
+            (/route\.(?:ts|js|tsx|jsx)$/i.test(posix) && !isUiChrome) ||
+            /@(Controller|Get|Post|Put|Delete|Patch)\b/.test(content) ||
+            /\bexport\s+(?:async\s+)?function\s+(?:GET|POST|PUT|DELETE|PATCH)\b/.test(content) ||
+            /\bexport\s+const\s+(?:GET|POST|PUT|DELETE|PATCH)\s*=/.test(content);
         const isDomain = /domain|entity|aggregate|model/i.test(file);
-        // validation-in-controller
-        if (isController) {
+        // validation-in-controller (API/Nest/server-action handlers — not pure UI chrome)
+        if (isController && !isUiChrome) {
             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) {
@@ -40,11 +53,32 @@ export function buildRulesInventory(input) {
                 });
             }
         }
-        // magic business constants (heuristic)
+        // magic business constants (heuristic) — quiet UI labels via anchored prefixes/tokens
         const magicRe = /\b(const|let)\s+([A-Z][A-Z0-9_]{2,})\s*=\s*(\d{2,}|['"][^'"]{8,}['"])/g;
         let magic;
+        // Wave-2 (P2N residual): infra / I/O / storage noise without swallowing domain seeds
+        // like MAX_CART_SIZE, ORDER_STATUS_OPEN, MAX_PROPERTY_LIMIT, MAX_MEDIA_PER_PROPERTY,
+        // DEFAULT_ORDER_LIMIT (narrow DEFAULT_/REQUEST_/STORAGE_ — do not drop all DEFAULT_*).
+        const isInfraMagicName = (name) => /^(?:TEST|SPEC|TIMEOUT|PORT|VERSION|MAX_RETRY|MIN_RETRY|TTL|CACHE|HEADER|COOKIE|MIME|CONTENT_TYPE|HTTP_STATUS|NODE_ENV|LOG_LEVEL|FEATURE_FLAG|ID_PREFIX|Z_INDEX)(?:_|$)/i.test(name) ||
+            /^(?:ROUTE|PATH|LABEL|TITLE|HEADING|CLASS|STYLE|COLOR|THEME|BREAKPOINT|QUERY|PARAM|ICON|ARIA|MSG|COPY|I18N|LOCALE|PAGE|NAV|MENU|TAB|BTN|BUTTON|PLACEHOLDER|TOOLTIP|SHADOW|RADIUS|GAP|PADDING|MARGIN|FONT|WIDTH|HEIGHT|OPACITY|DURATION|EASE|ANIM)_/i.test(name) ||
+            /_(?:ROUTE|PATH|LABEL|TITLE|COLOR|THEME|CLASS|STYLE|ICON|ARIA|MSG|COPY|TIMEOUT|PORT|VERSION|RETRY|DELAY|INTERVAL|TTL|CACHE)$/i.test(name) ||
+            // ms/timeout/bytes/storage/bucket/url infra suffixes (predial residual)
+            /_(?:TIMEOUT(?:_MS)?|MS|BYTES|BUCKET|STORAGE_KEY|WINDOW_MS)$/i.test(name) ||
+            // Narrow DEFAULT_/REQUEST_/STORAGE_ — only known infra tokens, not all DEFAULT_* seeds
+            /^(?:DEFAULT_(?:BASE_URL|TIMEOUT(?:_MS)?|RETRY|PORT|HOST|HEADERS?|CACHE|TTL|MS|LOCALE|LANG|TIMEZONE|TZ)|REQUEST_(?:TIMEOUT(?:_MS)?|HEADERS?|RETRY|ID_PREFIX)|STORAGE_(?:KEY|PREFIX|BUCKET)|DAY_MS$|APP_DOMAIN$|BASE_URL$)$/i.test(name) ||
+            // Known I/O bag prefixes that are never domain seeds in field clones
+            /^(?:FAVORITES_STORAGE|LISTINGS_CACHE|DOCS_PATH|METRICS_INTERVAL)/i.test(name);
         while ((magic = magicRe.exec(content)) !== null) {
-            if (/TEST|SPEC|TIMEOUT|PORT|VERSION|MAX_RETRY/i.test(magic[2]))
+            const name = magic[2];
+            if (isInfraMagicName(name))
+                continue;
+            // P2-N: skip remaining ALL_CAPS noise only on clear UI chrome (not all of app/).
+            if (isUiChrome && !isDomain)
+                continue;
+            // Wave-2: integrations / repos / clients are usually I/O constants, not Domain seeds.
+            // Keep Domain/controller paths so spaghetti magic limits still surface.
+            const isIoSurface = /(?:^|\/)(?:integrations?|repos?|clients?|infra(?:structure)?|adapters?)(?:\/|$)/i.test(posix) && !isDomain;
+            if (isIoSurface)
                 continue;
             seq += 1;
             candidates.push({
@@ -52,9 +86,9 @@ export function buildRulesInventory(input) {
                 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.`,
+                message: `Magic business constant ${name} may belong in a Domain policy or invariant catalog.`,
                 confidence: 'heuristic',
-                suggestedArkRule: { layer: 'DomainModel', invariantId: `INV-${magic[2]}` },
+                suggestedArkRule: { layer: 'DomainModel', invariantId: `INV-${name}` },
                 neverMechanicalSafe: true,
             });
         }
@@ -87,27 +121,35 @@ export function buildRulesInventory(input) {
         }
         // 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
+            // Wave-2: *Error / *access.error bags are not aggregate mutators (propia residual).
+            // Narrow: path-based error modules only — do not skip whole domain files that
+            // merely export an Error class alongside aggregates.
+            const isErrorBag = /\.error\.(?:ts|js|tsx|jsx)$/i.test(posix) ||
+                /(?:^|\/)[^/]*(?:-access)?\.error\./i.test(posix) ||
+                /(?:^|\/)errors?(?:\/|$)/i.test(posix);
+            if (!isErrorBag) {
+                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
+                    }
                 }
             }
         }

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

@@ -16,12 +16,54 @@ const COVERED_SAMPLE_MAX = 24;
 const STRUCTURE_CATALOG_MAX = 40;
 const UNCOVERED_CATALOG_MAX = 30;
 
+/** Minimum governed % before enforced ArkRules may arm extra merge teeth (P1M / FG-EXTRATEETH). */
+export const EXTRA_MERGE_TEETH_GOVERNED_FLOOR = 50;
+
+/**
+ * P1M / extraMergeTeeth: under the classification floor, demote enforced ArkRules
+ * structure/invariant findings so merge matches doctor stamp (layer graph only).
+ * Unknown classification (null/null) → do not demote (contract-only callers).
+ *
+ * @param {object[]} violations
+ * @param {{ governedPercent?: number|null, populatedLayerCount?: number|null }} classification
+ * @returns {object[]}
+ */
+export function demoteArkRuleTeethUnderClassificationFloor(violations, classification = {}) {
+  if (!Array.isArray(violations)) return violations;
+  const governed =
+    typeof classification.governedPercent === 'number' ? classification.governedPercent : null;
+  const populated =
+    typeof classification.populatedLayerCount === 'number'
+      ? classification.populatedLayerCount
+      : null;
+  if (governed == null && populated == null) return violations;
+  const allowsTeeth =
+    (governed ?? 0) >= EXTRA_MERGE_TEETH_GOVERNED_FLOOR && (populated ?? 0) >= 1;
+  if (allowsTeeth) return violations;
+  for (const v of violations) {
+    const isArkRule =
+      v?.arkruleId != null ||
+      (typeof v?.ruleId === 'string' &&
+        (v.ruleId.startsWith('ARKRULE') || v.ruleId.startsWith('arkrule')));
+    if (isArkRule && v.failsStrict !== false) {
+      v.failsStrict = false;
+      if (v.severity === 'error') v.severity = 'warning';
+    }
+  }
+  return violations;
+}
+
 /**
  * @param {string} root
  * @param {Record<string, unknown>} config
  * @param {{ files?: Array<{ path: string }> }} [facts] optional facts for path set
+ * @param {{
+ *   governedPercent?: number | null,
+ *   populatedLayerCount?: number | null,
+ *   classifiedFiles?: number | null,
+ * }} [classification] layer-plane coverage (when known)
  */
-export function summarizeRulesUnderContract(root, config, facts) {
+export function summarizeRulesUnderContract(root, config, facts, classification) {
   if (!config?.arkRules || Object.keys(config.arkRules).length === 0) {
     return {
       active: false,
@@ -112,12 +154,88 @@ export function summarizeRulesUnderContract(root, config, facts) {
     const coveredTruncated = Math.max(0, coveredAll.length - COVERED_SAMPLE_MAX);
     const coveredSample = coveredAll.slice(0, COVERED_SAMPLE_MAX);
 
+    const structureEnforced = structureAll.filter((s) => s.mode === 'enforced').length;
+    const structureAdvisory = structureAll.length - structureEnforced;
+    const invariantEnforced = (loaded.arkRules.invariants ?? []).filter(
+      (inv) => inv.mode === 'enforced'
+    ).length;
+    const invariantAdvisory = invariants - invariantEnforced;
+    const coveredInvariants = coverage.coverage.filter((c) => c.covered).length;
+    const uncoveredInvariants = coverage.coverage.filter((c) => !c.covered).length;
+    const hasEnforcedTeeth = structureEnforced > 0 || invariantEnforced > 0;
+    // P1M-EXTRATEETH-EMPTY-GRAPH / FG-EXTRATEETH-EMPTY-CLASSIFICATION:
+    // Do not arm structure/invariant merge teeth when the layer plane is empty or
+    // barely classified (e.g. 0% governed). Classification unknown → allow teeth
+    // (contract-only callers / unit tests without coverage).
+    const governedPercent =
+      classification && typeof classification.governedPercent === 'number'
+        ? classification.governedPercent
+        : null;
+    const populatedLayerCount =
+      classification && typeof classification.populatedLayerCount === 'number'
+        ? classification.populatedLayerCount
+        : classification && typeof classification.classifiedFiles === 'number'
+          ? classification.classifiedFiles > 0
+            ? 1
+            : 0
+          : null;
+    const classificationKnown = governedPercent != null || populatedLayerCount != null;
+    const classificationAllowsTeeth = !classificationKnown
+      ? true
+      : (governedPercent ?? 0) >= EXTRA_MERGE_TEETH_GOVERNED_FLOOR &&
+        (populatedLayerCount ?? 0) >= 1;
+    const extraMergeTeeth = hasEnforcedTeeth && classificationAllowsTeeth;
+    const teethDeferredForClassification =
+      hasEnforcedTeeth && classificationKnown && !classificationAllowsTeeth;
+    // P1-M — which plane can fail merge (layers vs enforced structure vs invariants).
+    const mergePlanes = {
+      layers: {
+        role: 'inter-layer-edges',
+        alwaysOnGate: true,
+        note: 'Import/export layer graph — the default merge plane. Absent arkRules changes nothing here.',
+      },
+      structureSensors: {
+        role: 'intra-layer-heuristics',
+        total: structureRules,
+        enforced: structureEnforced,
+        advisory: structureAdvisory,
+        note: 'Structure sensors are heuristics (prefer false negatives). Only mode:enforced fails merge; noisy sensors stay advisory by default. Advisory-only packs never add merge teeth (FG-ARKRULES-ADVISORY-ONLY).',
+      },
+      invariants: {
+        role: 'catalog-plus-coverage',
+        total: invariants,
+        enforced: invariantEnforced,
+        advisory: invariantAdvisory,
+        covered: coveredInvariants,
+        uncovered: uncoveredInvariants,
+        note: 'Invariants are catalog + coverage evidence, not a business runtime. Enforced + proven-uncovered fails merge; absence of enforced rules adds no extra teeth.',
+      },
+      dualPlaneStamp:
+        'Structure = heuristics; invariants = catalog+coverage evidence (not business runtime). The two planes never merge into one architecture score. Advisory ArkRules ≠ merge teeth.',
+      extraMergeTeeth,
+      ...(classificationKnown
+        ? {
+            classificationGate: {
+              governedPercent: governedPercent ?? null,
+              populatedLayerCount: populatedLayerCount ?? null,
+              floorPercent: EXTRA_MERGE_TEETH_GOVERNED_FLOOR,
+              allowsTeeth: classificationAllowsTeeth,
+            },
+          }
+        : {}),
+      failMergeWhen: extraMergeTeeth
+        ? 'Layer graph failures plus enforced structure/invariant findings (advisory sensors never fail merge alone).'
+        : teethDeferredForClassification
+          ? `Layer graph only — enforced ArkRules structure/invariant findings are demoted under the teeth floor (need ≥${EXTRA_MERGE_TEETH_GOVERNED_FLOOR}% governed and ≥1 populated layer); they do not merge-block until classification is honest.`
+          : 'Layer graph only — no enforced ArkRules structure/invariant teeth on this tree. Advisory packs do not arm merge teeth.',
+    };
+
     return {
       active: true,
       structureRules,
       invariants,
-      coveredInvariants: coverage.coverage.filter((c) => c.covered).length,
-      uncoveredInvariants: coverage.coverage.filter((c) => !c.covered).length,
+      coveredInvariants,
+      uncoveredInvariants,
       partialCoverage: coverage.partial,
       testFilesScanned: coverageInputs.testFiles.length,
       layers,
@@ -127,8 +245,9 @@ export function summarizeRulesUnderContract(root, config, facts) {
       uncoveredTruncated,
       coveredSample,
       coveredTruncated,
+      mergePlanes,
       notAScore: true,
-      note: 'ArkRules plane (intra-layer) — counts and catalog, never a score. Green with uncovered residual must say so.',
+      note: 'ArkRules plane (intra-layer) — counts and catalog, never a score. Green with uncovered residual must say so. Structure sensors are heuristics; invariants are catalog+coverage evidence, not a business runtime.',
     };
   } catch (error) {
     return {
@@ -155,6 +274,7 @@ export function formatRulesUnderContractHtml(section, esc) {
     <h2>Rules under contract <span class="muted">(ArkRules opt-in)</span></h2>
     <p class="dim" style="margin:.15rem 0 .55rem;font-size:.88rem">
       Intra-layer plane (structure sensors + domain invariants as data). Separate from inter-layer import edges.
+      Absence of arkRules adds no extra merge teeth beyond the layer graph.
     </p>
     ${note}
   </section>`;
@@ -284,6 +404,15 @@ export function formatRulesUnderContractHtml(section, esc) {
           : ''
       }`;
 
+  const mergePlanes = section.mergePlanes;
+  const mergeHtml =
+    mergePlanes && typeof mergePlanes === 'object'
+      ? `<p class="muted" style="margin:.35rem 0 .55rem;font-size:.86rem">
+          <b>Merge planes:</b> ${escape(mergePlanes.failMergeWhen || '')}
+          ${mergePlanes.dualPlaneStamp ? `<br/>${escape(mergePlanes.dualPlaneStamp)}` : ''}
+        </p>`
+      : '';
+
   return `
   <section class="section card" data-advisory="rulesUnderContract">
     <h2>Rules under contract <span class="muted">(ArkRules — not a score)</span></h2>
@@ -293,6 +422,7 @@ export function formatRulesUnderContractHtml(section, esc) {
       <b>Invariants</b> = named policies + coverage evidence (symbol/test), not a business runtime
       and not a fitness score.
     </p>
+    ${mergeHtml}
     <div class="kpis" style="margin-bottom:.55rem">
       <div class="kpi"><b>${Number(section.structureRules) || 0}</b><span>Structure rules</span></div>
       <div class="kpi"><b>${Number(section.invariants) || 0}</b><span>Invariants</span></div>