arkgate 4.8.17 → 4.8.18

package/CHANGELOG.md

@@ -96,6 +96,62 @@ in the immutable pre-2.0 archive linked below.
   Existing configs keep whatever URL they already have. Editor completion
   matches the 4.x line you just installed.
 
+## 4.8.18 — 2026-09-18
+
+**Patch** over **4.8.17**. Daily accumulate (2026-09-18 ART) of the six
+ships that landed after 4.8.17 published: monorepo DomainModel globs
+([#269](https://github.com/pedroknigge/arkgate/pull/269)), packed
+README latest-truth
+([#270](https://github.com/pedroknigge/arkgate/issues/270) /
+[#272](https://github.com/pedroknigge/arkgate/pull/272)), deep pstack
+audit ([#273](https://github.com/pedroknigge/arkgate/pull/273)), doctor
+#1 dual-match honesty
+([#275](https://github.com/pedroknigge/arkgate/pull/275)), compact-start
+size refuse ([#274](https://github.com/pedroknigge/arkgate/pull/274)),
+and stale-skill Guiar
+([#278](https://github.com/pedroknigge/arkgate/pull/278)).
+**Write. Check. Ship.** **No required config migration.** No
+`schemaVersion` bump. Does not close `K01` / `Z09`. This mother
+`ark.config.json` still does **not** turn `arkOrder` on.
+
+**Status: published** (npm `latest` is **4.8.18**).
+
+### Added
+- Doctor and `ark-check` warn when installed `/ark-*` skills are behind
+  this package (canonical `.agents/skills` included, even with no host
+  marker dir). Primary next action is skills-only refresh
+  (`--install-agent-gates --skills-only --force`) — not a full re-adopt
+  ([#278](https://github.com/pedroknigge/arkgate/pull/278)).
+- Maintainer pstack audit report (core + add-ons) at
+  `docs/audit/2026-09-17-pstack-deep-product-audit.md`
+  ([#273](https://github.com/pedroknigge/arkgate/pull/273)). Report
+  only. No product code.
+
+### Fixed
+- Monorepo `arkgate start` no longer puts whole-app roots (`api/**`,
+  `client/**`) on DomainModel next to the finer globs. Domain stays
+  package-scoped (`packages/*/src/**`, `**/domain/**`). When dual-match
+  is huge, doctor #1 is “fix overlapping layer globs” with one example,
+  not only “make CI required”
+  ([#269](https://github.com/pedroknigge/arkgate/pull/269)).
+- Packed README / docs hub no longer pin npm `latest` to an older
+  version than this tarball. `check:package-files` and the
+  packed-artifact path refuse that waiting-room pin
+  ([#270](https://github.com/pedroknigge/arkgate/issues/270) /
+  [#272](https://github.com/pedroknigge/arkgate/pull/272)).
+- Doctor #1 no longer treats intentional Domain+Tooling file+glob
+  dual-lists as a glob leak, and overlapping-glob copy names the tree's
+  real roots instead of a canned `api/**` sermon
+  ([#275](https://github.com/pedroknigge/arkgate/pull/275)).
+- `doctorResidentWarm` CI ceiling is 800ms after docs-only main already
+  missed 680ms (p95 697–707ms). Same miss as #270 / the audit tip
+  ([#275](https://github.com/pedroknigge/arkgate/pull/275)).
+- Cold `arkgate start --apply` now refuses a plan that is too big for
+  compact start **before** any “writing…” copy, names the file/byte
+  numbers, and prints one next action (`arkgate-check --init`).
+  `--force` does not unlock the size lock
+  ([#274](https://github.com/pedroknigge/arkgate/pull/274)).
+
 ## 4.8.17 — 2026-09-17
 
 **Patch** over **4.8.16**. Daily accumulate of the two ships that landed
@@ -107,8 +163,7 @@ policy-delta-ack-match confidence retarget
 `schemaVersion` bump. Does not close `K01` / `Z09`. This mother
 `ark.config.json` still does **not** turn `arkOrder` on.
 
-**Status: prepared** (npm `latest` remains **4.8.16** until Actions `publish-npm`
-runs with `tag=v4.8.17` and `dry_run=false`).
+**Status: published** (npm `latest` is **4.8.17**).
 
 ### Added
 - A weaken, new layer, or new allow edge must name a short ADR /

package/README.md

@@ -39,7 +39,7 @@ Works with Cursor, Claude, Codex, and Grok.
 
 </div>
 
-> **ArkGate 4.8.17** is prepared on this tree; npm `latest` remains **4.8.16** until `publish-npm` for `v4.8.17`.
+> **ArkGate 4.8.18** is on npm `latest`.
 > Write. Check. Ship. Adopted = required GitHub
 > status running `arkgate-check --strict-merge`, or an explicit `advisory-only` stance.
 > Status is compact (`arkgate-check --doctor`; `--all` for Details). Optional **ArkRun**
@@ -47,7 +47,7 @@ Works with Cursor, Claude, Codex, and Grok.
 > (`arkgate/order`) stops rewriting a big product choice — like the billing plan —
 > as if it were a seat count. Change those choices through a valve, not a generic update.
 > `@arkgate/runtime` is deprecated.
-> [4.8.17 prepared](CHANGELOG.md) · [4.8.11 published](docs/releases/4.8.11.md) · [4.8.10](docs/releases/4.8.10.md) · [4.8.9](docs/releases/4.8.9.md) · [4.8.8](docs/releases/4.8.8.md) · [4.8.7](docs/releases/4.8.7.md) · [4.8.6](docs/releases/4.8.6.md) · [4.8.5](docs/releases/4.8.5.md) · [4.8.4](docs/releases/4.8.4.md) · [4.8.3](docs/releases/4.8.3.md) · [4.8.2](docs/releases/4.8.2.md) · [4.8.1](docs/releases/4.8.1.md) · [4.8.0](docs/releases/4.8.0.md) · [Docs hub](docs/README.md) · [Voice](docs/product-voice.md)
+> [4.8.18](CHANGELOG.md) · [4.8.11](docs/releases/4.8.11.md) · [4.8.10](docs/releases/4.8.10.md) · [4.8.9](docs/releases/4.8.9.md) · [4.8.8](docs/releases/4.8.8.md) · [4.8.7](docs/releases/4.8.7.md) · [4.8.6](docs/releases/4.8.6.md) · [4.8.5](docs/releases/4.8.5.md) · [4.8.4](docs/releases/4.8.4.md) · [4.8.3](docs/releases/4.8.3.md) · [4.8.2](docs/releases/4.8.2.md) · [4.8.1](docs/releases/4.8.1.md) · [4.8.0](docs/releases/4.8.0.md) · [Docs hub](docs/README.md) · [Voice](docs/product-voice.md)
 
 ---
 
@@ -76,9 +76,12 @@ npx --package=arkgate arkgate-check --doctor --all  # full details
 `arkgate-check` is a command in the `arkgate` package, not its own npm package. After a local install, `npx arkgate-check --doctor` also works.
 
 `start --apply` refuses when projected governed coverage is below 50% or
-shape confidence is weak (below 0.6 with coverage under 80%). That lock is
-deliberate. Lock the shape with `--archetype <id>`, `--preset <name>`, or
-`--force`, or inspect ranked shapes with `npx arkgate-check --recommend`.
+shape confidence is weak (below 0.6 with coverage under 80%), or when the
+planned write is too big for compact start (more than 8 gate files or 32 KB).
+That lock is deliberate. Coverage/shape: lock with `--archetype <id>`,
+`--preset <name>`, or `--force`. Size: `--force` does not unlock. Next:
+`npx arkgate-check --init`. Or inspect ranked shapes with
+`npx arkgate-check --recommend`.
 
 That is the product. Stuck? Run status (`--doctor`) and do action **#1**.
 
@@ -344,8 +347,8 @@ Compact starters leave the extra off. Details: [ArkOrder](docs/arkorder.md).
 | Config · package surface · TS | [configuration](docs/configuration.md) · [package-surface](docs/package-surface.md) · [typescript-support](docs/typescript-support.md) |
 | Brownfield | [docs/brownfield-adoption.md](docs/brownfield-adoption.md) |
 | Security | [SECURITY.md](SECURITY.md) |
-| Prepared (4.8.17; not published) | [CHANGELOG](CHANGELOG.md) |
-| Current published (4.8.11 on npm `latest`) | [docs/releases/4.8.11.md](docs/releases/4.8.11.md) · [CHANGELOG](CHANGELOG.md) |
+| Current published (4.8.18 on npm `latest`) | [CHANGELOG](CHANGELOG.md) |
+| Prior published (4.8.11) | [docs/releases/4.8.11.md](docs/releases/4.8.11.md) · [CHANGELOG](CHANGELOG.md) |
 | Prior published (4.8.10) | [docs/releases/4.8.10.md](docs/releases/4.8.10.md) · [CHANGELOG](CHANGELOG.md) |
 | Prior published (4.8.9) | [docs/releases/4.8.9.md](docs/releases/4.8.9.md) · [CHANGELOG](CHANGELOG.md) |
 | Prior published (4.8.7) | [docs/releases/4.8.7.md](docs/releases/4.8.7.md) · [CHANGELOG](CHANGELOG.md) |

package/bin/ark-shared.mjs

@@ -1740,7 +1740,12 @@ export function buildArchitectureRecommendation(root, options = {}) {
     // a thin slice and can mis-flag framework internals, so steer these to the adoption flow.
     mature: signals.sourceFileCount >= MATURE_REPO_FILE_THRESHOLD,
     initCommand: `${arkCommand(root, 'ark', `init --archetype ${result.archetype} --yes`)}`,
-    firstCommand: `${arkCommand(root, 'ark', `start --apply --archetype ${result.archetype}`)}`,
+    // Greenfield: compact start. Mature: `--init` writes the rules file without the
+    // compact-start size lock that cold `start --apply` can hit on large trees.
+    firstCommand:
+      signals.sourceFileCount >= MATURE_REPO_FILE_THRESHOLD
+        ? arkCommand(root, 'ark-check', '--init')
+        : `${arkCommand(root, 'ark', `start --apply --archetype ${result.archetype}`)}`,
     adoptCommand: arkCommand(root, 'ark-check', '--recommend --write-plan'),
     recommendCommand: arkCommand(root, 'ark-check', '--recommend'),
     checkCommand: arkCommand(root, 'ark-check', '--root . --config ark.config.json --strict-config'),
@@ -1817,10 +1822,11 @@ export function resolveStartInitPreset(root, rec = {}, archetype = rec.archetype
   return preset ?? null;
 }
 
-/** One-minute / preview footer when the coverage·confidence gate may refuse apply. */
+/** One-minute / preview footer when apply may refuse (coverage·shape or compact size). */
 export const START_APPLY_REFUSE_FOOTER = [
-  'If apply refuses (coverage below 50% or weak shape), that lock is deliberate.',
-  'Lock the shape: --archetype <id>  ·  --preset <name>  ·  --force',
+  'If apply refuses (coverage below 50%, weak shape, or too big for compact start), that lock is deliberate.',
+  'Coverage/shape: --archetype <id>  ·  --preset <name>  ·  --force',
+  'Too big for compact start: --force does not unlock. Next: arkgate-check --init',
   'Inspect ranked shapes: arkgate-check --recommend',
 ].join('\n');
 

package/bin/ark.mjs

@@ -24,6 +24,8 @@ import { pinArkgateDevDependency, FALSE_GREEN_GAP_ID } from './lib/field-install
 import { validateHardWriteRequest } from './lib/enforcement-profiles.mjs';
 import {
   applyStartPreview,
+  emitStartSetupBudgetRefuse,
+  evaluateStartSetupBudgetGate,
   formatStartPackageInstallFailure,
   planStart,
   renderStartPreview,
@@ -470,6 +472,10 @@ async function start(args) {
         }
         return 2;
       }
+      if (!evaluateStartSetupBudgetGate(preview.setupBudget).ok) {
+        emitStartSetupBudgetRefuse(preview, args.json);
+        return 2;
+      }
     }
     if (args.json) console.log(JSON.stringify(preview, null, 2));
     else if (!args.apply) renderStartPreview(preview);

package/bin/lib/agent-gates.mjs

@@ -106,6 +106,8 @@ export {
   assessSkillCatalogParity,
   detectSkillGaps,
   skillGapsForActiveHost,
+  skillGapToolLabel,
+  SKILL_CANONICAL_TOOL,
   agentsMdSkillRefs,
   verifyHostSkillCatalog,
   printSkillAndCodexGapHints,

package/bin/lib/doctor-human.mjs

@@ -11,7 +11,7 @@ import { printDoctorAdvisories, printCompactExtraDoctorLines } from './doctor-ad
 import { designDeltaDoctorLines } from './design-delta.mjs';
 import { enforcementDoctorLines } from './enforcement-state.mjs';
 import { analysisIncompleteStatement } from './analysis-completeness.mjs';
-import { skillGapsForActiveHost, detectCodexHomeGap, codexConcernIsActive } from './agent-gates.mjs';
+import { skillGapsForActiveHost, detectCodexHomeGap, codexConcernIsActive, skillGapToolLabel } from './agent-gates.mjs';
 import { agentHomeConcernIsActive } from './agent-homes.mjs';
 import { layerGuidanceLine } from './layer-description.mjs';
 import {
@@ -467,7 +467,7 @@ export function printDoctorDetailsHuman(view) {
   if (remMiss + remStale > 0) {
     line(
       warn,
-      `${remMiss} missing / ${remStale} content-behind-package /ark-* skill(s) for ${remainingGaps.map((g) => g.tool).join(', ')}`
+      `${remMiss} missing / ${remStale} content-behind-package /ark-* skill(s) for ${remainingGaps.map((g) => skillGapToolLabel(g.tool)).join(', ')}`
     );
   }
   const codexHomeGap = detectCodexHomeGap(root);

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

@@ -2,7 +2,7 @@
  * Rank doctor next actions from already-computed facts (no I/O).
  * Lets the human printer show light + #1 before honesty/compass sections.
  */
-import { arkCommand } from '../ark-shared.mjs';
+import { arkCommand, globToRegExp } from '../ark-shared.mjs';
 import { skillGapsForActiveHost } from './agent-gates.mjs';
 import { agentHomeConcernIsActive, agentHomeRefreshCommand } from './agent-homes.mjs';
 import { mergePostGreenTopActions } from './post-green-path.mjs';
@@ -17,6 +17,99 @@ function missingGateFiles(ctx) {
   return list;
 }
 
+/** Ignore a handful of expected Next API dual-matches. */
+const DUAL_MATCH_REPAIR_FLOOR = 20;
+/** Absolute pile-up even when the tree is huge. */
+const DUAL_MATCH_REPAIR_ABSOLUTE = 50;
+/** Share of in-scope files that match two+ layers. */
+const DUAL_MATCH_REPAIR_SHARE = 0.1;
+
+function isWildcardPattern(pattern) {
+  return /[*?]/.test(String(pattern ?? ''));
+}
+
+function posixRel(file) {
+  return String(file ?? '').split(/\\/).join('/');
+}
+
+function layerPatterns(cov, layerName) {
+  const rows = Array.isArray(cov?.layers) ? cov.layers : [];
+  const row = rows.find((layer) => layer?.name === layerName);
+  return Array.isArray(row?.patterns) ? row.patterns : [];
+}
+
+function fileMatchesWildcardPatterns(file, patterns) {
+  const rel = posixRel(file);
+  return patterns.some((pattern) => isWildcardPattern(pattern) && globToRegExp(pattern).test(rel));
+}
+
+/**
+ * Domain overlap is a glob leak when Domain matched the sample via a wildcard.
+ * Exact-file Domain listings under another layer glob (mother generated CLI)
+ * are intentional dual-lists, not a repair. No layer patterns → keep the
+ * Domain-sample shortcut so older #269 fixtures still fire.
+ */
+function domainSampleIsGlobLeak(row, cov) {
+  if (!(row?.layers ?? []).includes('DomainModel')) return false;
+  const patterns = layerPatterns(cov, 'DomainModel');
+  if (patterns.length === 0) return true;
+  return fileMatchesWildcardPatterns(row.file, patterns);
+}
+
+/** Overlapping roots from matching Domain wildcards, else sample path prefixes. */
+export function overlappingRootsFromCoverage(cov) {
+  const samples = Array.isArray(cov?.dualMembership?.samples) ? cov.dualMembership.samples : [];
+  const domainPatterns = layerPatterns(cov, 'DomainModel');
+  const fromPatterns = [];
+  for (const row of samples) {
+    const rel = posixRel(row?.file);
+    for (const pattern of domainPatterns) {
+      if (isWildcardPattern(pattern) && globToRegExp(pattern).test(rel)) {
+        fromPatterns.push(pattern);
+      }
+    }
+  }
+  if (fromPatterns.length > 0) {
+    return [...new Set(fromPatterns)].slice(0, 2);
+  }
+  const derived = [];
+  for (const row of samples) {
+    const first = posixRel(row?.file).split('/').filter(Boolean)[0];
+    if (first) derived.push(`${first}/**`);
+  }
+  return [...new Set(derived)].slice(0, 2);
+}
+
+/**
+ * Dual-match is a lying layer map when it is large — especially Domain
+ * overlapping Presentation/Application after over-broad monorepo start globs.
+ * Intentional file+glob dual-lists (exact Domain files under Tooling `bin/**`)
+ * do not steal doctor #1.
+ */
+export function dualMatchNeedsGlobRepair(cov) {
+  const count = Number(cov?.dualMembership?.count) || 0;
+  if (count < DUAL_MATCH_REPAIR_FLOOR) return false;
+  const total = Number(cov?.totalFiles ?? cov?.governed?.totalFiles) || 0;
+  const samples = Array.isArray(cov?.dualMembership?.samples) ? cov.dualMembership.samples : [];
+  const domainOverlap = samples.some((row) => domainSampleIsGlobLeak(row, cov));
+  if (domainOverlap) return true;
+  if (total > 0 && count / total >= DUAL_MATCH_REPAIR_SHARE) return true;
+  return count >= DUAL_MATCH_REPAIR_ABSOLUTE;
+}
+
+export function overlappingGlobNextAction(cov) {
+  const count = Number(cov?.dualMembership?.count) || 0;
+  const sample = Array.isArray(cov?.dualMembership?.samples) ? cov.dualMembership.samples[0] : null;
+  const layers = Array.isArray(sample?.layers) ? sample.layers.filter(Boolean) : [];
+  const example =
+    sample?.file && layers.length > 1
+      ? `${sample.file} matches ${layers.join(' + ')}`
+      : 'the same files match two layer globs';
+  const roots = overlappingRootsFromCoverage(cov);
+  const rootPhrase = roots.length > 0 ? roots.join(', ') : 'the overlapping globs';
+  return `Fix overlapping layer globs — ${count} files match more than one layer (e.g. ${example}). Narrow overlapping roots like ${rootPhrase}. Then /ark-adopt`;
+}
+
 export function collectDoctorNextActions(ctx) {
   const actions = [];
   const missingFiles = missingGateFiles(ctx);
@@ -37,9 +130,26 @@ export function collectDoctorNextActions(ctx) {
   if (ctx.layerOwners?.required && ctx.layerOwners.nextAction) {
     actions.push(ctx.layerOwners.nextAction);
   }
+  const humanSkillGaps = skillGapsForActiveHost(ctx.skillGaps ?? []);
+  const legacyCodex = humanSkillGaps.some((g) => g.tool === 'codex' && g.legacyPromptsOnly);
+  const remainingGaps = humanSkillGaps.filter(
+    (g) => !(g.tool === 'codex' && (g.legacyPromptsOnly || g.legacyAdvisory))
+  );
+  const remMiss = remainingGaps.reduce((s, g) => s + g.missing, 0);
+  const remStale = remainingGaps.reduce((s, g) => s + g.stale, 0);
+  if (legacyCodex) {
+    actions.push('install Codex SKILL.md catalog (--install-agent-gates --skills-only --tools codex --force)');
+  }
+  if (remMiss > 0) {
+    actions.push('install missing /ark-* skills (--install-agent-gates --skills-only --force)');
+  } else if (remStale > 0) {
+    actions.push('refresh stale /ark-* skills (--install-agent-gates --skills-only --force) — gates are installed, catalog is stale');
+  }
   const enforceEmptyPlan =
     ctx.operatingMode === 'enforce' && planAEmpty && gatesInstalled && !notAdopted;
-  if (enforceEmptyPlan) {
+  // Stale/missing doors outrank the Shape nudge — a colleague on an old catalog
+  // must see skills-only refresh as #1, not leftover-design explore.
+  if (enforceEmptyPlan && remMiss === 0 && remStale === 0 && !legacyCodex) {
     actions.push(
       ctx.postGreenPath?.action ||
         '/ark-explore, then one small refactor with /ark-autopilot and your OK'
@@ -70,6 +180,8 @@ export function collectDoctorNextActions(ctx) {
   if (ctx.coverageHonesty.greenIsNotEnforcement && ctx.coverageHonesty.worseThanNoGate) {
     actions.push('raise governed coverage above a minority slice before treating green as enforcement');
   }
+  const overlapAction = dualMatchNeedsGlobRepair(ctx.cov) ? overlappingGlobNextAction(ctx.cov) : null;
+  if (overlapAction) actions.push(overlapAction);
   if (ctx.cov.suggestions.length > 0) actions.push('classify the ungoverned directories (/ark-adopt)');
   if (ctx.packageVersionTruth?.dualTruth) {
     actions.push(
@@ -100,21 +212,6 @@ export function collectDoctorNextActions(ctx) {
           : 'Remove the skippable if:, or write .ark/adoption-stance.json with stance: advisory-only')
     );
   }
-  const humanSkillGaps = skillGapsForActiveHost(ctx.skillGaps);
-  const legacyCodex = humanSkillGaps.some((g) => g.tool === 'codex' && g.legacyPromptsOnly);
-  const remainingGaps = humanSkillGaps.filter(
-    (g) => !(g.tool === 'codex' && (g.legacyPromptsOnly || g.legacyAdvisory))
-  );
-  const remMiss = remainingGaps.reduce((s, g) => s + g.missing, 0);
-  const remStale = remainingGaps.reduce((s, g) => s + g.stale, 0);
-  if (legacyCodex) {
-    actions.push('install Codex SKILL.md catalog (--install-agent-gates --skills-only --tools codex --force)');
-  }
-  if (remMiss > 0) {
-    actions.push('install missing /ark-* skills (--install-agent-gates --skills-only --force)');
-  } else if (remStale > 0) {
-    actions.push('refresh stale /ark-* skills (--install-agent-gates --skills-only --force) — gates are installed, catalog is stale');
-  }
   if (ctx.codexHomeGap && ctx.codexConcernActive && ctx.codexHomeGap.duplicateHome) {
     actions.push(
       'remove duplicate Codex home /ark-* skills (project .agents/skills is enough): --install-agent-gates --skills-only --prune-home-duplicates'
@@ -162,6 +259,9 @@ export function collectDoctorNextActions(ctx) {
   if (ctx.designFitness.designWeak && unique.length === 0 && ctx.postGreenPath) {
     unique.push(ctx.postGreenPath.action);
   }
+  if (overlapAction) {
+    return [overlapAction, ...unique.filter((a) => a !== overlapAction)];
+  }
   if (notAdopted) {
     const next = ctx.notAdoptedNextAction || NOT_ADOPTED_NEXT_ACTION;
     return [next, ...unique.filter((a) => a !== next)];

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

@@ -12,6 +12,7 @@ ${NORTH_STAR_ONE_LINE}
   arkgate start              preview (no writes)
   arkgate start --apply      write host + CI setup
                              (refuses weak coverage/shape; lock with --archetype/--preset/--force)
+                             (refuses a plan too big for compact start; next: arkgate-check --init)
   arkgate-check --doctor     status — one next step
                              (if missing: npx --package=arkgate arkgate-check --doctor)
 
@@ -70,6 +71,7 @@ Options:
   --yes        Non-interactive defaults: create config if needed, install gate templates, run strict check.
                (Also the implicit default when stdin/stdout are not a TTY — agents never hang on prompts.)
   --force      Allow generated files to overwrite existing files.
+               Unlocks weak coverage/shape on start --apply. Does not unlock a plan too big for compact start.
   --no-strict  Skip the final strict ark-check run.
   --install    Pin and install arkgate as a project devDependency (default for start).
   --no-install Skip adding/installing arkgate as a project devDependency (start/upgrade).
@@ -303,7 +305,8 @@ export function checkUsageAll() {
     'rule file. Existing files are never overwritten without --force, so re-running',
     'after an update only adds what is missing. --skills-only restricts the write to',
     'just the /ark-* skills (safe to --force-refresh — it leaves a customized AGENTS.md,',
-    'settings, and CI workflow untouched).',
+    'settings, and CI workflow untouched). Doctor / ark-check warn when an already-installed',
+    'catalog is behind this package; that next action is --skills-only --force, not re-adopt.',
     'Pass --tools to pick which tool configs to write; otherwise they are auto-detected',
     'from their config directories (.claude/, .cursor/, .codex/, .grok/, .windsurf/,',
     '.clinerules/, .kiro/, .roo/, .continue/, .gemini/; copilot is explicit-only).',

package/bin/lib/html-report.mjs

@@ -905,7 +905,7 @@ export function renderHtmlReport({
     );
   } else {
     skillsParts.push(
-      `<div class="pill warn">${actionableSkillGaps.length} skill gap(s) — run ark upgrade / --install-agent-gates</div>`
+      `<div class="pill warn">${actionableSkillGaps.length} skill gap(s) — refresh skills only: ark-check --install-agent-gates --skills-only --force</div>`
     );
   }
   if (legacyAdvisoryOnly) {

package/bin/lib/presets.mjs

@@ -629,27 +629,21 @@ export const ARCHITECTURE_PRESETS = {
     }
     // Turborepo: apps/ + packages/; Nx enterprise: apps/ + libs/ (+ packages/).
     if (include.length === 0) include = ['packages', 'apps', 'libs'];
-    // Established workspaces often have flat package source roots rather than a
-    // directory named domain/application. The package manifest supplies a real,
-    // reviewable role signal: a published library is a domain surface; an app or
-    // CLI package coordinates work. This is deliberately limited to package roots
-    // Ark already discovered, never a catch-all **/src/** fallback.
-    const packagePatterns = (roles) => {
-      if (!root) return [];
-      return units
-        .filter((unit) => roles.includes(unit.role))
-        .flatMap((unit) => unit.sourceRoots.map((sourceRoot) => {
-          const base = unit.root === '.'
-            ? sourceRoot
-            : sourceRoot === '.'
-              ? unit.root
-              : `${unit.root}/${sourceRoot}`;
-          return base === '.' ? null : `${base}/**`;
-        }))
-        .filter(Boolean);
-    };
-    const librarySourcePatterns = packagePatterns(['library']);
-    const applicationSourcePatterns = packagePatterns(['application', 'cli']);
+    // Library Domain bags stay under packages/ or libs/ — never api/** or client/**.
+    const roleGlobs = (roles, domainScoped) =>
+      !root
+        ? []
+        : units
+            .filter((unit) => roles.includes(unit.role) && !(domainScoped && unit.root === '.'))
+            .flatMap((unit) =>
+              (unit.sourceRoots ?? []).map((sourceRoot) => {
+                const base = unit.root === '.' ? sourceRoot : sourceRoot === '.' ? unit.root : `${unit.root}/${sourceRoot}`;
+                return base === '.' ? null : `${base}/**`;
+              })
+            )
+            .filter((pattern) => pattern && (!domainScoped || /^(packages|libs)\//.test(pattern)));
+    const librarySourcePatterns = roleGlobs(['library'], true);
+    const applicationSourcePatterns = roleGlobs(['application', 'cli'], false);
     return presetWithOverlays(
       {
         include,

package/bin/lib/skill-install.mjs

@@ -261,8 +261,22 @@ export const SKILL_TOOL_TARGETS = {
   windsurf: (name) => `.windsurf/workflows/${name}.md`,
   cline: (name) => `.clinerules/workflows/${name}.md`,
   copilot: (name) => `.github/prompts/${name}.prompt.md`,
+  // Catalog-only gap: `.agents/skills` exists without a host marker that reads it.
+  agents: (name) => canonicalSkillPath(name),
 };
 
+/** Synthetic detectSkillGaps tool when only the canonical catalog is present. */
+export const SKILL_CANONICAL_TOOL = 'agents';
+
+export function skillGapToolLabel(tool) {
+  return tool === SKILL_CANONICAL_TOOL ? SKILL_CANONICAL_DIR : String(tool ?? '');
+}
+
+export function skillTargetIsCanonical(tool) {
+  const target = SKILL_TOOL_TARGETS[tool];
+  return typeof target === 'function' && target('ark-place') === canonicalSkillPath('ark-place');
+}
+
 /** Hosts whose catalog is the project `.agents/skills` tree (write once). */
 export function usesCanonicalSkillCatalog(tool) {
   return (
@@ -1086,10 +1100,32 @@ export function detectSkillGaps(root) {
   if (fs.existsSync(path.join(root, '.cursor'))) detected.push('cursor');
   if (fs.existsSync(path.join(root, '.codex'))) detected.push('codex');
   if (fs.existsSync(path.join(root, '.grok'))) detected.push('grok');
+  // Same markers as resolveTools — Antigravity/OpenCode read or link the catalog.
+  if (
+    fs.existsSync(path.join(root, '.agents', 'hooks.json')) ||
+    fs.existsSync(path.join(root, '.agents', 'mcp_config.json'))
+  ) {
+    detected.push('antigravity');
+  }
+  if (
+    fs.existsSync(path.join(root, 'opencode.json')) ||
+    fs.existsSync(path.join(root, 'opencode.jsonc')) ||
+    fs.existsSync(path.join(root, '.opencode'))
+  ) {
+    detected.push('opencode');
+  }
   if (fs.existsSync(path.join(root, '.windsurf'))) detected.push('windsurf');
   if (fs.statSync(path.join(root, '.clinerules'), { throwIfNoEntry: false })?.isDirectory()) {
     detected.push('cline');
   }
+  // One-catalog trees may have `.agents/skills` and no host marker dir.
+  // Without this, a colleague who `npm install`s a new pin keeps stale doors silently.
+  if (
+    fs.existsSync(path.join(root, SKILL_CANONICAL_DIR)) &&
+    !detected.some((tool) => skillTargetIsCanonical(tool))
+  ) {
+    detected.push(SKILL_CANONICAL_TOOL);
+  }
   const version = arkPackageVersion();
   const gaps = [];
   for (const tool of detected) {
@@ -1150,7 +1186,9 @@ export function detectSkillGaps(root) {
 export function skillGapsForActiveHost(skillGaps, env = process.env) {
   const activeHost = detectActiveAgentHost(env);
   if (!activeHost) return skillGaps ?? [];
-  return (skillGaps ?? []).filter((gap) => gap.tool === activeHost);
+  return (skillGaps ?? []).filter(
+    (gap) => gap.tool === activeHost || gap.tool === SKILL_CANONICAL_TOOL
+  );
 }
 
 /**
@@ -1174,7 +1212,7 @@ export function printSkillAndCodexGapHints(root, opts) {
     );
     const missingTotal = remaining.reduce((sum, gap) => sum + gap.missing, 0);
     const staleTotal = remaining.reduce((sum, gap) => sum + gap.stale, 0);
-    const tools = remaining.map((gap) => gap.tool).join(', ');
+    const tools = remaining.map((gap) => skillGapToolLabel(gap.tool)).join(', ');
     if (legacyCodex) {
       console.log(
         color.yellow(
@@ -1200,9 +1238,9 @@ export function printSkillAndCodexGapHints(root, opts) {
     }
     if (staleTotal > 0) {
       console.log(
-        color.dim(
+        color.yellow(
           `${staleTotal} /ark-* skill(s) content behind this Ark package for ${tools}. ` +
-            `Refresh: ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --force')}`
+            `Refresh skills only (do not re-adopt): ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --force')}`
         )
       );
     }

package/bin/lib/start-preview.mjs

@@ -122,6 +122,73 @@ export function setupBudget(changes) {
   };
 }
 
+/** One next write when compact start is the wrong size. `--force` does not unlock. */
+export const START_SETUP_BUDGET_NEXT = 'arkgate-check --init';
+
+function formatSetupKb(bytes) {
+  return `${Math.max(1, Math.round(Number(bytes) / 1024))} KB`;
+}
+
+/**
+ * Compact-start size lock. `--force` unlocks coverage/shape only — never this.
+ * @param {object|null|undefined} setupBudget
+ * @param {{ force?: boolean }} [options]
+ */
+export function evaluateStartSetupBudgetGate(setupBudget, { force = false } = {}) {
+  if (!setupBudget || setupBudget.ok) {
+    return { ok: true, forceIgnored: Boolean(force) };
+  }
+  const reasons = [];
+  const maxFiles = setupBudget.maxFiles ?? 8;
+  const maxBytes = setupBudget.maxBytes ?? 32 * 1024;
+  const gateFiles =
+    typeof setupBudget.gateFiles === 'number' ? setupBudget.gateFiles : setupBudget.files;
+  if (typeof gateFiles === 'number' && gateFiles > maxFiles) {
+    reasons.push(`${gateFiles} gate files (max ${maxFiles})`);
+  }
+  if (typeof setupBudget.bytes === 'number' && setupBudget.bytes >= maxBytes) {
+    reasons.push(`${formatSetupKb(setupBudget.bytes)} (max ${formatSetupKb(maxBytes)})`);
+  }
+  if (reasons.length === 0) {
+    reasons.push('the planned write is larger than compact start allows');
+  }
+  return {
+    ok: false,
+    reasons,
+    nextAction: START_SETUP_BUDGET_NEXT,
+    forceBypasses: false,
+    setupBudget,
+  };
+}
+
+/**
+ * Human refuse / preview warning. Avoids the first-run phrase "Compact setup budget".
+ * @param {object|null|undefined} setupBudget
+ * @param {{ applying?: boolean }} [options]
+ */
+export function formatStartSetupBudgetRefuse(setupBudget, { applying = true } = {}) {
+  const gate = evaluateStartSetupBudgetGate(setupBudget);
+  if (gate.ok) return '';
+  const facts = gate.reasons.map((reason) => `  • ${reason}`).join('\n');
+  const next = `--force does not unlock this. Next: ${gate.nextAction}`;
+  if (applying) {
+    return `Refusing ark start --apply: this plan is too big for compact start.\n${facts}\n${next}`;
+  }
+  return `This plan is too big for compact start.\n${facts}\nApply will refuse. ${next}`;
+}
+
+/** Apply-path emit: JSON envelope or human refuse. Call before any “writing…” copy. */
+export function emitStartSetupBudgetRefuse(preview, json) {
+  const gate = evaluateStartSetupBudgetGate(preview.setupBudget);
+  if (json) {
+    console.log(
+      JSON.stringify({ ok: false, error: 'start-setup-budget-gate', ...gate, preview }, null, 2)
+    );
+    return;
+  }
+  console.error(formatStartSetupBudgetRefuse(preview.setupBudget, { applying: true }));
+}
+
 function commands(root, args, helpers) {
   if (args.removeHost) {
     return [`ark start --root ${root} --tools ${args.removeHost} --apply`];
@@ -160,6 +227,7 @@ export function formatStartPackageInstallFailure({ exitStatus, installCommand })
  */
 export function renderStartPreview(preview, options = {}) {
   const applying = options.applying === true;
+  const budgetOk = preview.setupBudget?.ok !== false;
   if (applying) {
     console.log(
       preview.changes.length === 0
@@ -170,7 +238,11 @@ export function renderStartPreview(preview, options = {}) {
     console.log('Ark start preview — no files were changed.');
   }
   if (!applying) {
-    console.log('Apply this plan with: arkgate start --apply');
+    if (budgetOk) {
+      console.log('Apply this plan with: arkgate start --apply');
+    } else {
+      console.log(formatStartSetupBudgetRefuse(preview.setupBudget, { applying: false }));
+    }
   }
   if (preview.analysis) {
     console.log(`Your project looks like: ${preview.analysis.label}.`);
@@ -208,8 +280,8 @@ export function renderStartPreview(preview, options = {}) {
 }
 
 export function applyStartPreview(root, preview) {
-  if (!preview.setupBudget?.ok) {
-    throw new Error('Refusing to apply a start plan that exceeds the compact setup budget.');
+  if (!evaluateStartSetupBudgetGate(preview.setupBudget).ok) {
+    throw new Error(formatStartSetupBudgetRefuse(preview.setupBudget, { applying: true }));
   }
   for (const change of preview.changes) {
     const target = path.join(root, change.path);