arkgate 4.8.17 → 4.8.19

package/CHANGELOG.md

@@ -96,6 +96,114 @@ 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.19 — 2026-09-20
+
+**Patch** over **4.8.18**. Daily accumulate (2026-09-20 ART) of the five
+ships that landed after 4.8.18 published: pre-hook write gate first
+([#280](https://github.com/pedroknigge/arkgate/pull/280)), honest
+workspace evidence + playground exclude
+([#286](https://github.com/pedroknigge/arkgate/pull/286)), skill stamp
+refresh ([#285](https://github.com/pedroknigge/arkgate/pull/285)),
+honest start docs and install-fail next step
+([#287](https://github.com/pedroknigge/arkgate/pull/287)), and honest
+recommend label when `uiHeavy` is true
+([#289](https://github.com/pedroknigge/arkgate/pull/289)).
+**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.19**).
+
+### Changed
+- Write-gate order: install and trust the host pre-hook first. MCP
+  `ark_prepare_write` is fallback when that path is missing or fail-open.
+  Compact Cursor now requires the fail-closed hook (MCP alone is not
+  enough). Doctor / start / host matrix name the fallback
+  ([#280](https://github.com/pedroknigge/arkgate/pull/280)).
+
+### Fixed
+- Stranger-path `--recommend` treats `pnpm-workspace.yaml` (even without
+  `package.json#workspaces`) as workspace evidence, and no longer says
+  "not a workspace monorepo" on a workspace tree. Start / recommend skip
+  playground, fixture, and scaffold trees the same way the check walk
+  does ([#286](https://github.com/pedroknigge/arkgate/pull/286)).
+- Managed upgrade refreshes a skill's `arkVersion` / `arkgate@X.Y.Z`
+  description stamp when the body is unchanged (`state: current`).
+  Frozen redirect stubs no longer keep a stale picker version after a
+  pin bump. Reuses `planSkillInstall` `stamp-refresh`;
+  `summary.metadataRefresh` counts those writes
+  ([#285](https://github.com/pedroknigge/arkgate/pull/285) /
+  [#284](https://github.com/pedroknigge/arkgate/issues/284)).
+- Stranger start path no longer leads with `npm install -D arkgate`
+  (hard-fail on `workspace:*`). Docs lead with `npx arkgate start`;
+  `start --apply` already pins with `pnpm add -w` / `yarn add -W`.
+  pnpm `minimumReleaseAge` recovery is a one-liner. Doctor after a
+  failed install leads with resolve the package, not "make CI required"
+  ([#287](https://github.com/pedroknigge/arkgate/pull/287) /
+  [#268](https://github.com/pedroknigge/arkgate/issues/268)).
+- `start` / `--recommend` no longer labels a UI monorepo as "API server
+  without UI in this repository" when `uiHeavy` is true. The one-minute
+  label becomes "API-heavy monorepo with UI packages". Default monorepo
+  start parks `web/**` / `web/src/**` on PresentationAdapters
+  ([#289](https://github.com/pedroknigge/arkgate/pull/289) /
+  [#288](https://github.com/pedroknigge/arkgate/issues/288)).
+
+## 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 +215,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.19** 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.19](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)
 
 ---
 
@@ -66,19 +66,21 @@ Full map: **[docs/README.md](docs/README.md)**
 ## Start in one minute
 
 ```bash
-npm install -D arkgate typescript
 npx arkgate start                 # preview files + commands
 npx arkgate start --apply         # compact config + host router + CI plan
 npx --package=arkgate arkgate-check --doctor        # status — one next step
 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` pins arkgate with this repo's package manager (`pnpm add -w` / `yarn add -W` at a workspace root). Do not run `npm install -D arkgate` at a `workspace:*` root — npm rejects that protocol. After a local install, `npx arkgate-check --doctor` also works. `arkgate-check` is a command in the `arkgate` package, not its own npm package.
 
 `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**.
 
@@ -201,7 +203,7 @@ Codex hard write covers only a complete local `apply_patch`; Cursor covers only
 installed + trusted, while shell/direct
 filesystem writes, hosted or specialized opt-out paths, and human edits still rely on CI.
 
-This table describes the supported profile **after its files are installed and the host loads/trusts them**. A hard local boundary covers only the listed hook operations; alternate tools, direct filesystem writes, and human edits still rely on CI. MCP validation is advisory because the agent must call it. The CI check blocks a merge only when the repository makes that status required. Repair **envelopes** may be emitted without reinjection being guaranteed; silent auto-apply never happens. Run `arkgate-check --doctor` (or `ark-check --doctor`) for the evidence actually detected in the current repository.
+This table describes the supported profile **after its files are installed and the host loads/trusts them**. A hard local boundary covers only the listed hook operations; alternate tools, direct filesystem writes, and human edits still rely on CI. **Write-gate order:** install and trust the host pre-hook first. MCP prepare is fallback when that path is missing or fail-open. MCP validation is advisory because the agent must call it. The CI check blocks a merge only when the repository makes that status required. Repair **envelopes** may be emitted without reinjection being guaranteed; silent auto-apply never happens. Run `arkgate-check --doctor` (or `ark-check --doctor`) for the evidence actually detected in the current repository.
 <!-- arkgate-host-support:end -->
 
 #### Why required CI is the hard line
@@ -344,8 +346,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.19 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-mcp-runtime.mjs

@@ -2037,8 +2037,8 @@ export async function runArkMcp({ hookInput } = {}) {
         'When the matched layer has layers[].description, the JSON includes description; the field is omitted when absent. ' +
         'When the matched layer has layers[].trustBoundary (public|auth|admin|internal), the JSON includes trustBoundary; omitted when absent. ' +
         'When the matched layer has layers[].owners, the JSON includes owners; omitted when absent. ' +
-        'Call BEFORE writing a new file. ' +
-        'Prefer ark_prepare_write when you already have the source snippet (place+validate+autoPatch in one call).',
+        'Call BEFORE writing a new file to learn the layer. ' +
+        'Prefer ark_prepare_write only as fallback when the host has no hard pre-hook (or that hook is missing / fail-open) and you already have the source snippet.',
       inputSchema: {
         type: 'object',
         properties: {
@@ -2061,7 +2061,7 @@ export async function runArkMcp({ hookInput } = {}) {
         'constrain (layer, mayImport, mustNotImport, forbiddenGlobals) + validate source + optional ' +
         'mechanical-safe autoPatch + judgmentBrief when judgment is needed + contentHash for host commit. ' +
         'Also returns the versioned new/worsened designDelta for the proposed full file. ' +
-        'Composes ark_place + write-gate — call BEFORE Write/Edit when you have the snippet. ' +
+        'Composes ark_place + write-gate. Fallback when the host has no trusted hard pre-hook (or that hook is fail-open). When a hard hook is installed, the host already gates the write; this tool stays available but is not the primary gate. ' +
         'When the matched layer has layers[].description, the JSON includes description; the field is omitted when absent. ' +
         'When the matched layer has layers[].trustBoundary (public|auth|admin|internal), the JSON includes trustBoundary; omitted when absent. ' +
         'When the matched layer has layers[].owners, the JSON includes owners; omitted when absent. ' +

package/bin/ark-shared.mjs

@@ -875,12 +875,61 @@ const SKIP_DIR_NAMES = new Set([
   '__pycache__',
 ]);
 
+/**
+ * Non-product trees — same convention as the governed check walk
+ * (`isSkippedSourceDir` in scan-files). Start/recommend/discovery must not
+ * treat playground, fixtures, scaffolds, or tests as production architecture.
+ */
+export const NON_PRODUCT_SOURCE_DIR_NAMES = new Set([
+  'bench',
+  'benches',
+  'benchmark',
+  'benchmarks',
+  'docs',
+  'documentation',
+  'example',
+  'examples',
+  'fixture',
+  'fixtures',
+  'testdata',
+  'playground',
+  'scaffold',
+  'scaffolds',
+  '__tests__',
+  '__mocks__',
+  'e2e',
+  'test',
+  'tests',
+]);
+
+export function isNonProductSourceDirName(name) {
+  return NON_PRODUCT_SOURCE_DIR_NAMES.has(name);
+}
+
+export function isNonProductRelativePath(relPath) {
+  return String(relPath)
+    .split(/[/\\]/)
+    .filter(Boolean)
+    .some((token) => NON_PRODUCT_SOURCE_DIR_NAMES.has(token.toLowerCase()));
+}
+
+/** Check-walk skip: vendor/build plus non-product fixture trees. */
+export function isSkippedSourceDir(name) {
+  return (
+    name === 'node_modules' ||
+    name === 'dist' ||
+    name === 'coverage' ||
+    NON_PRODUCT_SOURCE_DIR_NAMES.has(name)
+  );
+}
+
 function dirHasTsSources(dir, maxDepth) {
   try {
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
       if (entry.isFile() && /\.(tsx?|jsx?|mts|cts)$/i.test(entry.name)) return true;
       if (!entry.isDirectory()) continue;
       if (SKIP_DIR_NAMES.has(entry.name) || entry.name.startsWith('.')) continue;
+      if (isSkippedSourceDir(entry.name)) continue;
       if (maxDepth > 0 && dirHasTsSources(path.join(dir, entry.name), maxDepth - 1)) return true;
     }
   } catch {
@@ -918,8 +967,14 @@ export function detectTsPackageRoots(root, options = {}) {
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
       if (SKIP_DIR_NAMES.has(entry.name) || entry.name.startsWith('.')) continue;
-      // Skip agent skill asset trees (not app code).
-      if (entry.name === 'skills' || entry.name === 'templates' || entry.name === 'fixtures') continue;
+      // Skip agent skill asset trees and non-product fixture/playground/test trees.
+      if (
+        entry.name === 'skills' ||
+        entry.name === 'templates' ||
+        isSkippedSourceDir(entry.name)
+      ) {
+        continue;
+      }
       const childRel = rel ? `${rel}/${entry.name}` : entry.name;
       visit(path.join(abs, entry.name), childRel, depth + 1);
     }
@@ -944,7 +999,7 @@ export function resolveIncludeRoots(root) {
   const workspaces = detectWorkspaces(root);
   const tsRoots = detectTsPackageRoots(root);
   if (workspaces.length === 0) {
-    if (tsRoots.length > 0) return tsRoots.filter((r) => r !== '.');
+    if (tsRoots.length > 0) return tsRoots.filter((r) => r !== '.' && !isNonProductRelativePath(r));
     return [];
   }
   // Workspaces present: keep them, add TS package roots not covered by a workspace prefix
@@ -960,7 +1015,7 @@ export function resolveIncludeRoots(root) {
       if (fs.existsSync(path.join(root, tr, 'package.json'))) merged.add(tr);
     }
   }
-  return [...merged];
+  return [...merged].filter((entry) => !isNonProductRelativePath(entry));
 }
 
 function isSourceFile(name) {
@@ -982,18 +1037,96 @@ function readJsonc(file) {
 
 function packageRole(rel, pkg) {
   const tokens = rel.toLowerCase().split('/');
-  if (tokens.some((token) => ['docs', 'documentation', 'website', 'examples', 'example', 'tests', 'test', 'fixtures'].includes(token))) {
-    return tokens.some((token) => token.startsWith('doc') || token === 'website')
-      ? 'docs'
-      : tokens.some((token) => token.startsWith('test') || token === 'fixtures')
-        ? 'test'
-        : 'example';
+  if (tokens.some((token) => ['docs', 'documentation', 'website'].includes(token))) {
+    return 'docs';
+  }
+  if (
+    tokens.some((token) =>
+      [
+        'tests',
+        'test',
+        'fixtures',
+        'fixture',
+        'testdata',
+        'e2e',
+        '__tests__',
+        'playground',
+        'scaffold',
+        'scaffolds',
+      ].includes(token)
+    )
+  ) {
+    return 'test';
+  }
+  if (tokens.some((token) => ['examples', 'example'].includes(token))) {
+    return 'example';
   }
   if (pkg?.bin) return 'cli';
   if (pkg?.exports || pkg?.main || pkg?.module || pkg?.types || pkg?.typings) return 'library';
   return 'application';
 }
 
+/** Path tokens already treated as UI app folders in discoverRepoUnits (root scan). */
+export const UI_PACKAGE_PATH_TOKENS = new Set(['web', 'frontend', 'client', 'ui']);
+
+const UI_PACKAGE_DEP_NAMES =
+  /^(react|react-dom|vue|svelte|preact|solid-js|next|@angular\/core|@sveltejs\/kit)$/i;
+
+/** True when a relative source path sits under a conventional UI package folder. */
+export function sourcePathLooksLikeUi(relPath) {
+  return String(relPath ?? '')
+    .toLowerCase()
+    .split(/[/\\]/)
+    .filter((token) => token && token !== '.')
+    .some((token) => UI_PACKAGE_PATH_TOKENS.has(token));
+}
+
+/**
+ * Application/CLI unit that is a UI surface (folder name or UI framework deps).
+ * Used so monorepo start does not park `web/**` on ApplicationOrchestration.
+ */
+export function isUiPackageUnit(unit) {
+  if (!unit || typeof unit !== 'object') return false;
+  if (sourcePathLooksLikeUi(unit.root)) return true;
+  const deps = unit.productionDeps ?? {};
+  return Object.keys(deps).some((name) => UI_PACKAGE_DEP_NAMES.test(String(name).split('/')[0]));
+}
+
+/** Source root of an application unit that should land on Presentation, not Application. */
+export function isUiApplicationSource(unit, sourceRoot) {
+  if (!unit) return sourcePathLooksLikeUi(sourceRoot);
+  const base =
+    unit.root === '.'
+      ? sourceRoot
+      : sourceRoot === '.' || !sourceRoot
+        ? unit.root
+        : `${unit.root}/${sourceRoot}`;
+  return sourcePathLooksLikeUi(base) || isUiPackageUnit(unit);
+}
+
+/**
+ * Monorepo start globs for package units by role. `uiMode: 'ui'` keeps only UI
+ * application roots (web/, frontend/, react/vue/svelte); `'not-ui'` drops them
+ * so they are not parked on ApplicationOrchestration (#288).
+ */
+export function monorepoRoleSourceGlobs(units, roles, { root, domainScoped = false, uiMode } = {}) {
+  if (!root || !Array.isArray(units)) return [];
+  return 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}`;
+        if (!base || base === '.') return null;
+        const uiSource = isUiApplicationSource(unit, sourceRoot);
+        if (uiMode === 'ui' && !uiSource) return null;
+        if (uiMode === 'not-ui' && uiSource) return null;
+        return `${base}/**`;
+      })
+    )
+    .filter((pattern) => pattern && (!domainScoped || /^(packages|libs)\//.test(pattern)));
+}
+
 function entrypointDirs(pkg) {
   const values = [];
   const add = (value) => {
@@ -1025,9 +1158,18 @@ export function discoverRepoUnits(root) {
     for (const name of ['tsconfig.json', 'jsconfig.json']) {
       const config = readJsonc(path.join(abs, name));
       const rootDir = config?.compilerOptions?.rootDir;
-      if (typeof rootDir === 'string') roots.add(normalizeRel(rootDir));
+      if (typeof rootDir === 'string' && !/\.(json|jsonc)$/i.test(rootDir)) {
+        const normalizedRootDir = normalizeRel(rootDir);
+        if (!isNonProductRelativePath(normalizedRootDir)) roots.add(normalizedRootDir);
+      }
       for (const ref of config?.references ?? []) {
-        if (typeof ref?.path === 'string') roots.add(normalizeRel(ref.path).replace(/^\.\//, ''));
+        if (typeof ref?.path !== 'string') continue;
+        const relRef = normalizeRel(ref.path).replace(/^\.\//, '');
+        // Project references often point at tsconfig.app.json — that is not a source root.
+        if (!relRef || relRef === '.' || /\.(json|jsonc)$/i.test(relRef)) continue;
+        if (isNonProductRelativePath(relRef)) continue;
+        const absRef = path.join(abs, relRef);
+        if (fs.statSync(absRef, { throwIfNoEntry: false })?.isDirectory()) roots.add(relRef);
       }
     }
     for (const dir of entrypointDirs(pkg)) {
@@ -1067,6 +1209,7 @@ function walkSourceFiles(dir, files = [], depth = 0) {
     // `.github/workflows/` CI dir must not read as an app "workflows"/saga signal, and Ark's
     // own installed `.claude`/`.codex` dirs must not perturb a re-run's recommendation.
     if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name.startsWith('.')) continue;
+    if (isSkippedSourceDir(entry.name)) continue;
     walkSourceFiles(path.join(dir, entry.name), files, depth + 1);
   }
   return files;
@@ -1105,6 +1248,7 @@ function dirExistsAnywhere(root, names) {
       // Skip node_modules/dist and ALL dot-dirs so `.github/workflows/` (CI YAML) can't be read
       // as an app "workflows"/saga signal, and Ark's own `.claude`/`.codex` don't self-perturb.
       if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name.startsWith('.')) continue;
+      if (isSkippedSourceDir(entry.name)) continue;
       if (names.has(entry.name)) return true;
       const child = rel === '.' ? entry.name : `${rel}/${entry.name}`;
       if (child.split('/').length < 8) queue.push(child);
@@ -1139,7 +1283,14 @@ export function collectRepoShapeSignals(root) {
   const pkg = readPackageJson(root);
   const repoUnits = discoverRepoUnits(root);
   const workspaceDirs = detectWorkspaces(root);
-  const workspaces = workspaceDirs.length > 0;
+  // Manifest presence is workspace evidence even when globs parse to no dirs
+  // (pnpm-workspace.yaml without package.json#workspaces is the common case).
+  const workspaces =
+    workspaceDirs.length > 0 ||
+    isPnpmWorkspaceRoot(root) ||
+    isNpmYarnWorkspaceRoot(root) ||
+    fs.existsSync(path.join(root, 'rush.json')) ||
+    fs.existsSync(path.join(root, 'lerna.json'));
   // Include frontend/web/client — common Next monorepo app folders.
   const candidateScanDirs = repoUnits
     .filter((unit) => !['docs', 'example', 'test'].includes(unit.role))
@@ -1362,7 +1513,10 @@ export function collectRepoShapeSignals(root) {
 }
 
 const SIGNAL_WHY = {
-  workspaces: (signals) => `workspace roots declared (${signals.workspaceDirs.join(', ')})`,
+  workspaces: (signals) =>
+    signals.workspaceDirs?.length
+      ? `workspace roots declared (${signals.workspaceDirs.join(', ')})`
+      : 'workspace manifest present (pnpm-workspace.yaml, package.json workspaces, rush, or lerna)',
   tinyTree: (signals) => `few source files (${signals.sourceFileCount})`,
   ui: () => 'UI directories or multiple TSX files present',
   uiHeavy: () => 'substantial UI surface (multiple TSX files)',
@@ -1397,8 +1551,24 @@ const SIGNAL_WHY = {
   expressLike: () => 'HTTP framework dependency (express/fastify/hono/…)',
 };
 
+/**
+ * Playbook labels that claim "without UI" are only honest when uiHeavy is false.
+ * Mirror of the #282 workspace negative-copy overlay: do not invent a new
+ * archetype — rewrite the one-minute label so it cannot contradict the sensors.
+ */
+export function honestArchetypeLabel(label, signals) {
+  if (typeof label !== 'string' || !signals?.uiHeavy) return label;
+  if (!/without UI/i.test(label)) return label;
+  if (signals.workspaces && signals.apiSurface) return 'API-heavy monorepo with UI packages';
+  if (signals.apiSurface) return 'API-heavy repository with a UI surface';
+  return 'Repository with a UI surface';
+}
+
 const NEGATIVE_SIGNAL_WHY = {
-  workspaces: () => 'not a workspace monorepo (penalized for this shape)',
+  workspaces: (signals) =>
+    signals.workspaces
+      ? `workspace monorepo (${signals.workspaceDirs?.join(', ') || 'manifest present'}; this shape prefers a single package)`
+      : 'not a workspace monorepo (penalized for this shape)',
   cli: () => 'CLI bin entry present (penalized for this shape)',
   ui: () => 'UI directories present (penalized for this shape)',
   uiHeavy: () => 'heavy UI surface (penalized for this shape)',
@@ -1582,7 +1752,7 @@ export function scoreArchetypes(signals, playbook) {
     );
     scored.push({
       id,
-      label: def.label,
+      label: honestArchetypeLabel(def.label, signals),
       preset: resolvePreset(def, signals),
       score,
       maxPositive: maxPositive || 1,
@@ -1718,6 +1888,7 @@ export function buildArchitectureRecommendation(root, options = {}) {
       })),
       workspaces: signals.workspaces,
       ui: signals.ui,
+      uiHeavy: signals.uiHeavy,
       apiSurface: signals.apiSurface,
       persistence: signals.persistence,
       jobs: signals.jobs,
@@ -1740,7 +1911,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 +1993,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,9 +24,12 @@ import { pinArkgateDevDependency, FALSE_GREEN_GAP_ID } from './lib/field-install
 import { validateHardWriteRequest } from './lib/enforcement-profiles.mjs';
 import {
   applyStartPreview,
+  emitStartSetupBudgetRefuse,
+  evaluateStartSetupBudgetGate,
   formatStartPackageInstallFailure,
   planStart,
   renderStartPreview,
+  runStartPackageInstall,
 } from './lib/start-preview.mjs';
 import { runUpgradeCommand } from './lib/upgrade-command.mjs';
 import { detectActiveAgentHost } from './lib/skill-install.mjs';
@@ -209,11 +212,6 @@ function cliVersion() {
 
 // packageInstallArgv is imported from ark-shared (workspace-aware -w / -W).
 
-function runCommand(command, commandArgs, cwd) {
-  const result = spawnSync(command, commandArgs, { cwd, stdio: 'inherit', encoding: 'utf8' });
-  return result.status ?? 1;
-}
-
 function runArkCheck(args, options = {}) {
   const result = spawnSync(process.execPath, [arkCheck, ...args], {
     cwd: options.cwd,
@@ -280,13 +278,16 @@ export function ensureProjectArkgateDependency(root, opts = {}) {
   }
   const pinned = pinArkgateDevDependency(root);
   let installStatus = null;
+  let hostOutput = '';
   // Only run the package manager after a successful pin change — avoid surprise
   // network on every start when arkgate is already listed.
   if (runPm && pinned.changed) {
     const [command, commandArgs] = packageInstallArgv(root, pinned.version);
-    installStatus = runCommand(command, commandArgs, root);
+    const install = runStartPackageInstall(command, commandArgs, root);
+    installStatus = install.status;
+    hostOutput = `${install.stdout}\n${install.stderr}`;
   }
-  return { pinned, installStatus };
+  return { pinned, installStatus, hostOutput };
 }
 
 async function resolveArchetypeInteractive(rl, root) {
@@ -470,6 +471,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);
@@ -497,16 +502,16 @@ async function start(args) {
         const installCommand = `${command} ${commandArgs.join(' ')}`;
         if (!args.json) console.log(`Installing package: ${installCommand}`);
         // Keep stdout clean for --json consumers (package managers are chatty on stdout).
-        const status = args.json
-          ? (spawnSync(command, commandArgs, {
-              cwd: args.root,
-              stdio: ['ignore', 'pipe', 'pipe'],
-              encoding: 'utf8',
-            }).status ?? 1)
-          : runCommand(command, commandArgs, args.root);
-        if (status !== 0) {
-          console.error(formatStartPackageInstallFailure({ exitStatus: status, installCommand }));
-          return status;
+        const install = runStartPackageInstall(command, commandArgs, args.root);
+        if (install.status !== 0) {
+          console.error(
+            formatStartPackageInstallFailure({
+              exitStatus: install.status,
+              installCommand,
+              hostOutput: `${install.stdout}\n${install.stderr}`,
+            })
+          );
+          return install.status;
         }
       }
     }
@@ -566,7 +571,7 @@ async function start(args) {
     // 2b) Pin arkgate as a project devDependency so CI/npx do not depend on a stale global.
     // Default install=true; only --no-install skips. (installExplicit tracks user override for copy.)
     if (args.install && fs.existsSync(path.join(root, 'package.json'))) {
-      const { pinned, installStatus } = ensureProjectArkgateDependency(root, {
+      const { pinned, installStatus, hostOutput } = ensureProjectArkgateDependency(root, {
         install: true,
         runPackageManager: !args.skipPackageManager,
       });
@@ -578,6 +583,7 @@ async function start(args) {
             formatStartPackageInstallFailure({
               exitStatus: installStatus,
               installCommand: `${command} ${commandArgs.join(' ')}`,
+              hostOutput,
             })
           );
         }

package/bin/lib/agent-gates.mjs

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