arkgate 4.8.24 → 4.8.26

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

@@ -7,6 +7,7 @@ import {
   directoryArkRulesReader,
   loadEffectiveArkRules,
   loadEffectiveArkRulesFromDisk,
+  normalizeProjectRelativePath,
   objectArkRulesReader,
 } from './effective-contract-load.mjs';
 import {
@@ -15,7 +16,9 @@ import {
   loadInvariantCoverageInputs,
 } from './invariant-coverage-io.mjs';
 import { evaluateInvariantCoverage } from './invariant-coverage.mjs';
+import { attachProbeEvidence } from './invariant-probe-io.mjs';
 import { attachPolicyAdrNote } from './adr-path.mjs';
+import { collectGovernedFiles } from './scan-files.mjs';
 
 function readJsonFile(filePath, label) {
   if (!fs.existsSync(filePath)) throw new Error(`${label} not found: ${filePath}`);
@@ -95,6 +98,20 @@ function configPathInRepository(root, configPath, top) {
  * ArkRules files at the base ref, relative to the project root inside the repository.
  * A path absent at the ref (added by the candidate) reads as `missing`.
  */
+function baseRefSourceFiles(top, ref, prefix) {
+  const shown = runGit(top, ['ls-tree', '-r', '--name-only', ref]);
+  if (shown.status !== 0) return [];
+  const rootPrefix = prefix ? `${prefix}/` : '';
+  const files = [];
+  for (const line of shown.stdout.split('\n')) {
+    if (!line) continue;
+    if (rootPrefix && !line.startsWith(rootPrefix)) continue;
+    const rel = rootPrefix ? line.slice(rootPrefix.length) : line;
+    if (/\.[cm]?[tj]sx?$/.test(rel) && !rel.endsWith('.d.ts')) files.push(rel);
+  }
+  return files;
+}
+
 function baseRefArkRulesReader(root, top, ref) {
   const prefix = path
     .relative(fs.realpathSync(top), fs.realpathSync(root))
@@ -102,6 +119,7 @@ function baseRefArkRulesReader(root, top, ref) {
     .join('/');
   const spec = (rel) => `${ref}:${prefix ? `${prefix}/` : ''}${rel}`;
   return {
+    files: baseRefSourceFiles(top, ref, prefix),
     readArkRulesFile: (rel) => {
       const shown = runGit(top, ['show', spec(rel)]);
       if (shown.status === 0) return { ok: true, content: shown.stdout };
@@ -131,11 +149,16 @@ export function resolvePolicyBaseConfig({
     // A base config FILE carries its ArkRules next to it (same relative paths as the
     // project), never from the candidate working tree: that would compare the
     // candidate catalog with itself and hide every demotion/deletion.
+    const baseRoot = fs.realpathSync(path.dirname(absolute));
+    const include = Array.isArray(config.include) && config.include.length > 0 ? config.include : ['src'];
     return {
       config,
       source: absolute,
       ref: null,
-      readArkRulesFile: directoryArkRulesReader(fs.realpathSync(path.dirname(absolute))),
+      files: collectGovernedFiles(baseRoot, { ...config, include })
+        .map((file) => path.relative(baseRoot, file).split(path.sep).join('/'))
+        .filter((rel) => rel && !rel.startsWith('..')),
+      readArkRulesFile: directoryArkRulesReader(baseRoot),
     };
   }
 
@@ -198,9 +221,10 @@ export function readPolicyAcknowledgement(root, acknowledgementPath) {
  * failure is fail-closed: silently dropping the base catalog would make every
  * ArkRule demotion or deletion classify as neutral.
  */
-export function loadBaseArkRules(base) {
+function loadBaseArkRules(base) {
   const loaded = loadEffectiveArkRules(base.config, base.readArkRulesFile, {
     missingAsEmpty: base.ref != null,
+    ...(Array.isArray(base.files) ? { files: base.files } : {}),
   });
   if (loaded.errors.length > 0) {
     const message = loaded.errors.map((issue) => `- ${issue.path}: ${issue.message}`).join('\n');
@@ -220,6 +244,17 @@ function hasArkRulesMap(config) {
   return Boolean(refs && typeof refs === 'object' && Object.keys(refs).length > 0);
 }
 
+/** Paths in a supplied catalog. A slice rule file is enough for the child wall to name it. */
+function catalogPaths(files) {
+  if (!files || typeof files !== 'object') return [];
+  const out = [];
+  for (const key of Object.keys(files)) {
+    const rel = normalizeProjectRelativePath(String(key));
+    if (rel) out.push(rel);
+  }
+  return out;
+}
+
 function loadedOrThrow(loaded, label) {
   if (loaded.errors.length === 0) return loaded.arkRules;
   const message = loaded.errors.map((issue) => `- ${issue.path}: ${issue.message}`).join('\n');
@@ -275,7 +310,9 @@ export function resolvePolicyDeltaArkRules({
       );
     }
     baseArkRules = loadedOrThrow(
-      loadEffectiveArkRules(baseConfig, objectArkRulesReader(baseArkRuleFiles)),
+      loadEffectiveArkRules(baseConfig, objectArkRulesReader(baseArkRuleFiles), {
+        files: catalogPaths(baseArkRuleFiles),
+      }),
       'Base'
     );
   } else {
@@ -285,7 +322,9 @@ export function resolvePolicyDeltaArkRules({
   let candidateArkRules;
   if (candidateArkRuleFiles && typeof candidateArkRuleFiles === 'object') {
     candidateArkRules = loadedOrThrow(
-      loadEffectiveArkRules(candidateConfig, objectArkRulesReader(candidateArkRuleFiles)),
+      loadEffectiveArkRules(candidateConfig, objectArkRulesReader(candidateArkRuleFiles), {
+        files: catalogPaths(candidateArkRuleFiles),
+      }),
       'Candidate'
     );
   } else if (candidateIsProjectConfig) {
@@ -316,16 +355,17 @@ export function analyzePolicyTransition({
   acknowledgementPath,
 }) {
   if (!strictMerge && !basePath && !baseRef && !acknowledgementPath) return undefined;
+  if (strictMerge && !basePath) {
+    const top = repositoryRoot(root);
+    if (top) configPathInRepository(root, configPath, top);
+  }
   const base = resolvePolicyBaseConfig({ root, configPath, basePath, baseRef, adoptMissingBase });
   if (!base && (basePath || (baseRef && !adoptMissingBase) || acknowledgementPath)) {
     throw new Error('Policy delta was requested but no policy base could be resolved.');
   }
   if (!base) return undefined;
 
-  // AR02/AR11: load Effective ArkRules so mode edits inside arkrules/*.json classify,
-  // and attach candidate coverage so covered advisory→enforced can auto-allow.
-  // Base ArkRules come from the SAME source as the base config (git ref or the
-  // base file's directory), never from the candidate working tree.
+  // Base ArkRules come from the base ref or base file, never the candidate tree.
   const baseArkRules = loadBaseArkRules(base);
   const candidateLoad = loadEffectiveArkRulesFromDisk(root, candidateConfig);
   if (candidateLoad.errors.length > 0) {
@@ -347,12 +387,20 @@ export function analyzePolicyTransition({
       fileContents: coverageInputs.fileContents,
       testFiles: coverageInputs.testFiles,
       testGlobsMissing: coverageInputs.testGlobsMissing,
-      // No coverageStats / coverageRoots: this caller reads coverage ROWS and
-      // drops the violations, and both only shape violation messages. Passing
-      // them would look like wiring while changing nothing observable here.
       coverageBudgetExhausted: coverageInputs.coverageBudgetExhausted === true,
+      ...(coverageInputs.stats ? { coverageStats: coverageInputs.stats } : {}),
+      // The declared roots set `coverageRootsDeclared` / `outsideDeclaredRoots`
+      // on each row, and canPromoteInvariant refuses without them. Same inputs
+      // as `--promote` (sensor-promote-io), so both surfaces judge alike.
+      ...(coverageInputs.coverageRoots ? { coverageRoots: coverageInputs.coverageRoots } : {}),
     });
-    candidateInvariantCoverage = evaluated.coverage;
+    // ADR 0039: the same committed probe evidence --promote reads, so both
+    // surfaces refuse alike. Read-only; nothing here runs a test.
+    candidateInvariantCoverage = attachProbeEvidence(
+      root,
+      evaluated.coverage,
+      candidateArkRules.invariants
+    ).rows;
   }
 
   const acknowledgement = readPolicyAcknowledgement(root, acknowledgementPath);

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

@@ -21,7 +21,7 @@ export const POST_GREEN_PRIMARY_SKILL = '/ark-explore';
 export const POST_GREEN_PRIMARY_ACTION = POST_GREEN_HUMAN;
 
 /** Short label for tables / metrics. */
-export const POST_GREEN_PRIMARY_SHORT =
+const POST_GREEN_PRIMARY_SHORT =
   '/ark-explore shape-focus → /ark-autopilot (apply one B pilot)  # Shape residual';
 
 /** Placement coaching while design residual remains (new code only). */

package/bin/lib/prepare-change.mjs

@@ -15,7 +15,7 @@ import {
 import { effectiveAnalysisConfig } from './analysis-policy.mjs';
 import { isScanExcludedRelative } from '../ark-shared.mjs';
 import { classifyChangeSet, evaluateTeamGate } from './team-parliament.mjs';
-import { loadEffectiveArkRulesFromDisk } from './effective-contract-load.mjs';
+import { arkRulesLoadFailed, loadEffectiveArkRulesFromDisk } from './effective-contract-load.mjs';
 import {
   coverageOptionsFromConfig,
   invariantIdsFromCatalog,
@@ -83,7 +83,7 @@ function assertInsideProject(root, relativePath) {
   }
 }
 
-export function normalizeChangeSet(input) {
+function normalizeChangeSet(input) {
   if (!Array.isArray(input)) throw new Error('changes must be an array.');
   return input.map((change, index) => {
     if (!change || typeof change !== 'object' || Array.isArray(change)) {
@@ -201,13 +201,7 @@ export function prepareChangeFromRoot({
   // and a broken reference fails closed instead of silently dropping the catalog.
   const arkRulesLoad = loadEffectiveArkRulesFromDisk(root, effectiveConfig);
   if (arkRulesLoad.errors.length > 0) {
-    const message = arkRulesLoad.errors
-      .map((issue) => (typeof issue === 'string' ? issue : `- ${issue.path}: ${issue.message}`))
-      .join('\n');
-    const error = new Error(`Invalid Effective Contract (${contractSource}):\n${message}`);
-    error.code = 'ARKRULES_LOAD_FAILED';
-    error.issues = arkRulesLoad.errors;
-    throw error;
+    throw arkRulesLoadFailed(contractSource, arkRulesLoad.errors);
   }
   const contract = loadContract(effectiveConfig, contractSource, {
     arkRules: arkRulesLoad.arkRules,

package/bin/lib/prepare-write.mjs

@@ -8,11 +8,10 @@ import crypto from 'node:crypto';
 import { validateWithAutoPatch } from './auto-patch.mjs';
 import { classifyRemediation, enrichViolationWithFixClass } from './remediation.mjs';
 import {
-  layerDescriptionCaption,
   placementDescriptionFields,
 } from './layer-description.mjs';
 
-export { layerDescriptionCaption, placementDescriptionFields };
+export { placementDescriptionFields };
 
 /**
  * Stable content identity for host commit / cache keys.

package/bin/lib/presets.mjs

@@ -19,7 +19,7 @@ import { withArkConfigMetadata } from './config-contract.mjs';
 const PRESETS_DIR = path.dirname(fileURLToPath(import.meta.url));
 const ARKRULES_TEMPLATES_DIR = path.join(PRESETS_DIR, '../../templates/arkrules');
 
-export function denyUpward(names) {
+function denyUpward(names) {
   const rules = [];
   for (let i = 0; i < names.length; i += 1) {
     for (let j = i + 1; j < names.length; j += 1) {
@@ -33,7 +33,7 @@ export function denyUpward(names) {
  * peerIsolation matrix: deny only when importer/importee sit under different slices.
  * Covers same-layer and cross-layer pairs (honest DDD / vertical-slice isolation).
  */
-export function peerIsolationEdges(layerNames, sliceFolders, message) {
+function peerIsolationEdges(layerNames, sliceFolders, message) {
   const rules = [];
   for (const from of layerNames) {
     for (const to of layerNames) {
@@ -57,7 +57,7 @@ export function peerIsolationEdges(layerNames, sliceFolders, message) {
 // Framework internals under `src/kernel/**` are NOT application architecture — a broad
 // `src/**/domain/**` would otherwise swallow `src/kernel/domain`. Do NOT use `**/kernel/**`
 // (that carves out legitimate `src/shared/kernel/**` SharedKernel paths).
-export const FRAMEWORK_INTERNAL_EXCLUDE = ['src/kernel/**', '**/src/kernel/**'];
+const FRAMEWORK_INTERNAL_EXCLUDE = ['src/kernel/**', '**/src/kernel/**'];
 
 /**
  * Shared high-spec domain globs. Prefer these over Application/Presentation scatter
@@ -217,18 +217,6 @@ export const APPLICATION_LIB_ORCHESTRATION_PATTERNS = Object.freeze([
   '**/lib/api-handlers/**',
 ]);
 
-/**
- * AR08 — attach lean arkRules map. Keys are always exact project layer names.
- * Sensor roles (domain-structure / orchestration / adapter-thin / generic) are
- * independent of display names so renamed layers still get the right starter.
- */
-export const DEFAULT_ARKRULES_REFS = {
-  DomainModel: 'arkrules/DomainModel.json',
-  ApplicationOrchestration: 'arkrules/ApplicationOrchestration.json',
-  PresentationAdapters: 'arkrules/PresentationAdapters.json',
-  PersistenceAdapters: 'arkrules/PersistenceAdapters.json',
-};
-
 /** Sensor roles used when selecting or synthesizing per-layer templates. */
 export const ARKRULES_SENSOR_ROLES = Object.freeze({
   DOMAIN_STRUCTURE: 'domain-structure',
@@ -241,7 +229,7 @@ export const ARKRULES_SENSOR_ROLES = Object.freeze({
  * Exact-name aliases → sensor role. Prefer this table over heuristics when the
  * project uses a known vocabulary (hexagonal, monorepo field renames, etc.).
  */
-export const LAYER_SENSOR_ROLE_ALIASES = Object.freeze({
+const LAYER_SENSOR_ROLE_ALIASES = Object.freeze({
   // Domain / pure model
   DomainModel: ARKRULES_SENSOR_ROLES.DOMAIN_STRUCTURE,
   Domain: ARKRULES_SENSOR_ROLES.DOMAIN_STRUCTURE,
@@ -448,7 +436,46 @@ export function writeArkRulesTemplates(root, config, { force = false } = {}) {
   return written;
 }
 
-export function presetWithOverlays(baseConfig, root) {
+/**
+ * Deny edges shared by the ports-and-adapters presets after their DomainModel
+ * rules: orchestration never reaches adapters, adapters never reach each other,
+ * and presentation never reaches the domain directly. Fresh objects per call.
+ */
+function portsAndAdaptersRules() {
+  return [
+    { from: 'ApplicationOrchestration', to: 'PersistenceAdapters', allowed: false },
+    { from: 'ApplicationOrchestration', to: 'PresentationAdapters', allowed: false },
+    { from: 'PresentationAdapters', to: 'PersistenceAdapters', allowed: false },
+    { from: 'PresentationAdapters', to: 'DomainModel', allowed: false },
+    { from: 'PersistenceAdapters', to: 'ApplicationOrchestration', allowed: false },
+    { from: 'PersistenceAdapters', to: 'PresentationAdapters', allowed: false },
+  ];
+}
+
+/**
+ * UI-surface preset rules: the domain and orchestration stay out of the UI, while
+ * presentation may reach data clients on day one (soft, `message` explains why).
+ * Persistence → Presentation stays denied. Fresh objects per call.
+ * @param {string} presentationToPersistenceMessage
+ */
+function uiSurfaceRules(presentationToPersistenceMessage) {
+  return [
+    { from: 'DomainModel', to: 'PresentationAdapters', allowed: false },
+    { from: 'DomainModel', to: 'PersistenceAdapters', allowed: false },
+    { from: 'DomainModel', to: 'ApplicationOrchestration', allowed: false },
+    { from: 'ApplicationOrchestration', to: 'PresentationAdapters', allowed: false },
+    {
+      from: 'PresentationAdapters',
+      to: 'PersistenceAdapters',
+      allowed: true,
+      message: presentationToPersistenceMessage,
+    },
+    { from: 'PersistenceAdapters', to: 'PresentationAdapters', allowed: false },
+    { from: 'PersistenceAdapters', to: 'ApplicationOrchestration', allowed: false },
+  ];
+}
+
+function presetWithOverlays(baseConfig, root) {
   const config = root ? applyFrameworkLayoutOverlays(baseConfig, root) : baseConfig;
   return withArkConfigMetadata(withDefaultArkRules(config));
 }
@@ -511,12 +538,7 @@ export const ARCHITECTURE_PRESETS = {
           { from: 'DomainModel', to: 'ApplicationOrchestration', allowed: false },
           { from: 'DomainModel', to: 'PersistenceAdapters', allowed: false },
           { from: 'DomainModel', to: 'PresentationAdapters', allowed: false },
-          { from: 'ApplicationOrchestration', to: 'PersistenceAdapters', allowed: false },
-          { from: 'ApplicationOrchestration', to: 'PresentationAdapters', allowed: false },
-          { from: 'PresentationAdapters', to: 'PersistenceAdapters', allowed: false },
-          { from: 'PresentationAdapters', to: 'DomainModel', allowed: false },
-          { from: 'PersistenceAdapters', to: 'ApplicationOrchestration', allowed: false },
-          { from: 'PersistenceAdapters', to: 'PresentationAdapters', allowed: false },
+          ...portsAndAdaptersRules(),
         ],
       },
       root
@@ -705,12 +727,7 @@ export const ARCHITECTURE_PRESETS = {
           { from: 'DomainModel', to: 'ApplicationOrchestration', allowed: false },
           { from: 'DomainModel', to: 'PresentationAdapters', allowed: false },
           { from: 'DomainModel', to: 'PersistenceAdapters', allowed: false },
-          { from: 'ApplicationOrchestration', to: 'PersistenceAdapters', allowed: false },
-          { from: 'ApplicationOrchestration', to: 'PresentationAdapters', allowed: false },
-          { from: 'PresentationAdapters', to: 'PersistenceAdapters', allowed: false },
-          { from: 'PresentationAdapters', to: 'DomainModel', allowed: false },
-          { from: 'PersistenceAdapters', to: 'ApplicationOrchestration', allowed: false },
-          { from: 'PersistenceAdapters', to: 'PresentationAdapters', allowed: false },
+          ...portsAndAdaptersRules(),
         ],
       },
       root
@@ -810,24 +827,12 @@ export const ARCHITECTURE_PRESETS = {
             optional: true,
           },
         ],
-        rules: [
-          { from: 'DomainModel', to: 'PresentationAdapters', allowed: false },
-          { from: 'DomainModel', to: 'PersistenceAdapters', allowed: false },
-          { from: 'DomainModel', to: 'ApplicationOrchestration', allowed: false },
-          { from: 'ApplicationOrchestration', to: 'PresentationAdapters', allowed: false },
-          // Next RSC often imports data clients from routes; deny is ideal but day-one
-          // ui-surface keeps this as a soft guidance edge (allowed) until ports exist —
-          // Persistence → Presentation stays denied when that edge appears.
-          {
-            from: 'PresentationAdapters',
-            to: 'PersistenceAdapters',
-            allowed: true,
-            message:
-              'UI/routes may reach data clients on day one (RSC); prefer application ports as the product grows.',
-          },
-          { from: 'PersistenceAdapters', to: 'PresentationAdapters', allowed: false },
-          { from: 'PersistenceAdapters', to: 'ApplicationOrchestration', allowed: false },
-        ],
+        // Next RSC often imports data clients from routes; deny is ideal but day-one
+        // ui-surface keeps this as a soft guidance edge (allowed) until ports exist —
+        // Persistence → Presentation stays denied when that edge appears.
+        rules: uiSurfaceRules(
+          'UI/routes may reach data clients on day one (RSC); prefer application ports as the product grows.'
+        ),
       },
       root
     ),
@@ -978,12 +983,7 @@ export const ARCHITECTURE_PRESETS = {
           { from: 'DomainModel', to: 'ApplicationOrchestration', allowed: false },
           { from: 'DomainModel', to: 'PersistenceAdapters', allowed: false },
           { from: 'DomainModel', to: 'PresentationAdapters', allowed: false },
-          { from: 'ApplicationOrchestration', to: 'PersistenceAdapters', allowed: false },
-          { from: 'ApplicationOrchestration', to: 'PresentationAdapters', allowed: false },
-          { from: 'PresentationAdapters', to: 'PersistenceAdapters', allowed: false },
-          { from: 'PresentationAdapters', to: 'DomainModel', allowed: false },
-          { from: 'PersistenceAdapters', to: 'ApplicationOrchestration', allowed: false },
-          { from: 'PersistenceAdapters', to: 'PresentationAdapters', allowed: false },
+          ...portsAndAdaptersRules(),
           { from: 'SharedKernel', to: 'DomainModel', allowed: false },
           { from: 'SharedKernel', to: 'ApplicationOrchestration', allowed: false },
           { from: 'SharedKernel', to: 'PresentationAdapters', allowed: false },
@@ -1078,21 +1078,9 @@ export const ARCHITECTURE_PRESETS = {
             optional: true,
           },
         ],
-        rules: [
-          { from: 'DomainModel', to: 'PresentationAdapters', allowed: false },
-          { from: 'DomainModel', to: 'PersistenceAdapters', allowed: false },
-          { from: 'DomainModel', to: 'ApplicationOrchestration', allowed: false },
-          { from: 'ApplicationOrchestration', to: 'PresentationAdapters', allowed: false },
-          {
-            from: 'PresentationAdapters',
-            to: 'PersistenceAdapters',
-            allowed: true,
-            message:
-              'SPA day-one UI may reach data clients; prefer ports as the product grows.',
-          },
-          { from: 'PersistenceAdapters', to: 'PresentationAdapters', allowed: false },
-          { from: 'PersistenceAdapters', to: 'ApplicationOrchestration', allowed: false },
-        ],
+        rules: uiSurfaceRules(
+          'SPA day-one UI may reach data clients; prefer ports as the product grows.'
+        ),
       },
       root
     ),

package/bin/lib/product-copy.mjs

@@ -25,7 +25,7 @@ export const ARKRULES_FIRST_CONTACT_NEXT =
 export const ARKRULES_EMPTY_CATALOG_NEXT =
   'Next: add 1–2 short phrases to invariants[] in the Domain rules file, then ark-check --doctor.';
 
-/** Status-light leftover-design qualifier (was “design-weak”). */
+/** Status-light leftover-design qualifier (was “design-weak”); also the HTML/doctor badge text. */
 export const LEFTOVER_DESIGN_LABEL = 'leftover design work';
 
 /**
@@ -41,14 +41,9 @@ export function operatingModeTitle(mode, leftoverDesign, stewardsUnset) {
   return light;
 }
 
-/** Short HTML/doctor badge text. */
-export const LEFTOVER_DESIGN_BADGE = LEFTOVER_DESIGN_LABEL;
-
 export const POST_GREEN_HUMAN =
   'Imports check out, but the design is still messy. Next: /ark-explore, then one small refactor with /ark-autopilot and your OK.';
 
 export const POST_GREEN_LEDE =
   'Import rules are clean, but leftover design work remains. That does not fail the check — it only means “done” is still wrong until you tidy shape.';
 
-export const HARD_WRITE_HUMAN = 'pre-write block';
-export const ADVISORY_WRITE_HUMAN = 'warning only (not blocked)';

package/bin/lib/project-root.mjs

@@ -4,6 +4,12 @@
  * 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.
+ * That ancestor contains the directory the caller named, so the requested tree
+ * stays inside the analysis.
+ *
+ * An explicit --config path (absolute, or any name with a separator) is a file.
+ * Layer patterns resolve against the caller's --root. The file's directory is
+ * never a fallback analysis root (#352).
  *
  * Security (S0 walk-up review):
  * - Split **config discovery root** from **write root**.
@@ -16,14 +22,14 @@ 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;
+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) {
+function isWorkspacesPackageRoot(dir) {
   const pkgPath = path.join(dir, 'package.json');
   try {
     if (!fs.statSync(pkgPath, { throwIfNoEntry: false })?.isFile()) {
@@ -55,7 +61,7 @@ export function isWorkspacesPackageRoot(dir) {
  * True when dir is a git worktree root (.git file or directory).
  * @param {string} dir
  */
-export function isGitRoot(dir) {
+function isGitRoot(dir) {
   try {
     const git = path.join(dir, '.git');
     const st = fs.statSync(git, { throwIfNoEntry: false });
@@ -97,18 +103,13 @@ function isFile(absPath) {
 }
 
 /** True when --config is a path (nested or absolute), not a basename to walk. */
-export function configNameIsPath(configName) {
+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
@@ -118,7 +119,7 @@ function isInsideRoot(root, target) {
  * @param {string} configName
  * @returns {string | null} absolute config file path
  */
-export function resolveConfigPathCandidate(startDir, configName) {
+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;
@@ -145,7 +146,8 @@ export function resolveConfigPathCandidate(startDir, configName) {
  * 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.
+ * An explicit --config path is a file. The returned root stays `startDir`.
+ * Basename walk-up (`ark.config.json`) may still adopt an ancestor.
  *
  * @param {string} startDir
  * @param {string} [configName='ark.config.json']
@@ -157,26 +159,12 @@ export function findNearestArkConfig(startDir, configName = 'ark.config.json', o
   const boundAtGit = opts.boundAtGitRoot !== false;
   const boundAtWorkspaces = opts.boundAtWorkspacesRoot !== false;
 
-  if (typeof configName === 'string' && path.isAbsolute(configName)) {
-    if (isFile(configName)) {
-      const root = path.dirname(configName);
-      const start = path.resolve(startDir || process.cwd());
-      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,
-    };
+    return { root: start, configPath: resolved, walkedUp: false };
   }
 
   let dir = path.resolve(startDir || process.cwd());
@@ -213,9 +201,10 @@ export function findNearestArkConfig(startDir, configName = 'ark.config.json', o
  * 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.
+ * - An explicit --config path keeps `root` at startRoot. The file's directory is not a fallback.
+ * - Else walk parents for a basename 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`.
+ * - writeMode + followConfigRoot (or read mode): adopt a basename walk-up root as `root`.
  *
  * @param {string} startRoot
  * @param {{
@@ -243,76 +232,45 @@ export function resolveEffectiveProjectRoot(startRoot, opts = {}) {
   // Writes adopt walked config root only with explicit opt-in.
   const adoptWalkedRoot = !writeMode || followConfigRoot;
 
+  /** Config found by walk-up (or at start); root follows it unless a plain write. */
+  const walkedResult = (found) => ({
+    root: adoptWalkedRoot ? found.root : start,
+    writeRoot: start,
+    config: configName,
+    configPath: found.configPath,
+    configRoot: found.root,
+    walkedUp: found.walkedUp,
+    configFound: true,
+    writeRootFollowedConfig: adoptWalkedRoot && found.walkedUp,
+  });
+  /** Everything stays at the start directory. */
+  const startResult = (configPath, configFound) => ({
+    root: start,
+    writeRoot: start,
+    config: configName,
+    configPath,
+    configRoot: start,
+    walkedUp: false,
+    configFound,
+    writeRootFollowedConfig: false,
+  });
+
   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,
-    };
+    return found ? walkedResult(found) : startResult(configName, 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,
-      };
+      return startResult(localPath, true);
     }
   } 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: found.walkedUp,
-      configFound: true,
-      writeRootFollowedConfig: adoptWalkedRoot && found.walkedUp,
-    };
-  }
-
-  return {
-    root: start,
-    writeRoot: start,
-    config: configName,
-    configPath: localPath,
-    configRoot: start,
-    walkedUp: false,
-    configFound: false,
-    writeRootFollowedConfig: false,
-  };
+  return found ? walkedResult(found) : startResult(localPath, false);
 }
 
 /**