arkgate 4.8.18 → 4.8.19

package/CHANGELOG.md

@@ -96,6 +96,58 @@ 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

package/README.md

@@ -39,7 +39,7 @@ Works with Cursor, Claude, Codex, and Grok.
 
 </div>
 
-> **ArkGate 4.8.18** is on npm `latest`.
+> **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.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)
+> [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,14 +66,13 @@ 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%), or when the
@@ -204,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
@@ -347,7 +346,7 @@ 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) |
-| Current published (4.8.18 on npm `latest`) | [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) |

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,

package/bin/ark.mjs

@@ -29,6 +29,7 @@ import {
   formatStartPackageInstallFailure,
   planStart,
   renderStartPreview,
+  runStartPackageInstall,
 } from './lib/start-preview.mjs';
 import { runUpgradeCommand } from './lib/upgrade-command.mjs';
 import { detectActiveAgentHost } from './lib/skill-install.mjs';
@@ -211,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,
@@ -282,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) {
@@ -503,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;
         }
       }
     }
@@ -572,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,
       });
@@ -584,6 +583,7 @@ async function start(args) {
             formatStartPackageInstallFailure({
               exitStatus: installStatus,
               installCommand: `${command} ${commandArgs.join(' ')}`,
+              hostOutput,
             })
           );
         }

package/bin/lib/ci-and-commands.mjs

@@ -201,7 +201,7 @@ const AGENT_CONTRACT = {
   ],
   // Cursor-only guidance: the write-time validate_code tool is available in
   // Cursor's runtime but has no equivalent in a plain AGENTS.md read.
-  cursorValidateStep: `Validate the full post-edit file content with the \`validate_code\` tool before writing whenever your runtime supports it.`,
+  cursorValidateStep: `The write gate is the host pre-hook when \`.cursor/hooks.json\` is installed, trusted, and \`failClosed\`. Call \`ark_prepare_write\` / \`validate_code\` only as fallback if that hook is missing or fail-open.`,
 };
 
 /**
@@ -413,7 +413,7 @@ Contener · Guiar · Ordenar — contain the write, guide the next step, order l
 1. Status anytime: \`${doctorCmd}\` — what's wrong and what to do first.
 2. Read the **Improvement compass** section (not a score). Name residual lenses in plain language when present (SoC, DIP, domain, …). Out-of-scope lenses (performance, app security tooling, full resilience) stay honest — do not invent Ark enforcement for them.
 3. CLI-first: if the local CLI already resolved this project root, do not wait on MCP “still connecting”. Identity handshake is optional in that case. When you do trust MCP evidence: call \`ark_identity\` with \`project.expectedRoot\` set to this project's exact absolute root, then reuse that root plus the returned \`projectIdentity.projectId\` on every Ark MCP call. A descendant path is authoritative only with that matching id. Missing tool, non-\`matched\` binding, or wrong root means this is not proven to be the right project: restart the host and use the local CLI meanwhile.
-4. Day to day: call \`ark_manifest\` with the same project expectation (or skip if CLI already bound the root); place new files with \`ark_place\` (filePath required — fail-closed); validate after edits; run \`${checkCmd}\`. The \`ark://manifest\` resource is compatibility-only and always unverified. On a deny, fix the illegal import — do not weaken \`ark.config.json\`.
+4. Day to day: call \`ark_manifest\` with the same project expectation (or skip if CLI already bound the root); place new files with \`ark_place\` (filePath required — fail-closed); run \`${checkCmd}\`. The host pre-hook is the write gate when installed; MCP \`ark_prepare_write\` is fallback if that hook is missing or fail-open. The \`ark://manifest\` resource is compatibility-only and always unverified. On a deny, fix the illegal import — do not weaken \`ark.config.json\`.
 5. If MCP is unavailable: inspect \`ark.config.json\` and run \`${checkCmd}\`. The host-readable projection is AGENTS.md and CLAUDE.md (same schema).
 
 **Single door when residual remains:**

package/bin/lib/doctor-human.mjs

@@ -147,6 +147,8 @@ export function printDoctorCompactHuman(view) {
     if (skippableCi) line(warn, skippableCi);
     else if (writePathHonesty?.nativeFailClosed === false) {
       line(warn, writePathHonesty.message || 'Write hook is fail-open — if the checker cannot run, the write still lands.');
+    } else if (listedMissing.length === 0 && writePath.gap?.id === 'write-path-mcp-only') {
+      line(warn, writePath.gap.message || 'Fell back to MCP prepare; required CI is the merge boundary.');
     } else if (listedMissing.length === 0 && (writePath.gap || writePathHonesty?.softWriteHost)) {
       line(warn, 'Local writes are advisory; required CI is the merge boundary.');
     }

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

@@ -9,6 +9,36 @@ import { mergePostGreenTopActions } from './post-green-path.mjs';
 import { ADOPTED_NOT, NOT_ADOPTED_NEXT_ACTION } from './adoption-stance.mjs';
 import { REQUIRED_GATE_WORKFLOW } from './gate-files.mjs';
 
+/** Package pin may exist; local resolve still failed. Lead with install, not CI. */
+export const PACKAGE_UNRESOLVED_NEXT_ACTION =
+  'Install arkgate in this project first (npx --package=arkgate, or pnpm add -D arkgate -w / yarn add -D arkgate -W at a workspace root), then re-run --doctor';
+
+export function packageUnresolvedNextAction(ctx) {
+  if (ctx?.packageInstalled !== false || ctx?.selfHost === true) return null;
+  const code = ctx?.packageVersionTruth?.code;
+  if (code === 'PACKAGE_PIN_SELF_HOST' || code === 'PACKAGE_PIN_ABSENT') return null;
+  // Failed start --apply: pin is in package.json, node_modules did not resolve.
+  if (code === 'PACKAGE_PIN_MATCHES' || code === 'PACKAGE_PIN_BEHIND_CLI' || ctx?.packagePinned === true) {
+    return PACKAGE_UNRESOLVED_NEXT_ACTION;
+  }
+  return null;
+}
+
+/** Compact doctor JSON #1 — same rank as collectDoctorNextActions when package is missing. */
+export function preferredDoctorPrimaryNextAction({
+  adopted,
+  packageInstalled,
+  selfHost,
+  packageVersionTruth,
+  postGreenPath,
+  dualTruthNext,
+} = {}) {
+  return (
+    packageUnresolvedNextAction({ packageInstalled, selfHost, packageVersionTruth }) ||
+    (adopted === 'not-adopted' ? NOT_ADOPTED_NEXT_ACTION : postGreenPath?.action ?? dualTruthNext ?? null)
+  );
+}
+
 function missingGateFiles(ctx) {
   const list = Array.isArray(ctx.gatesMissing) ? ctx.gatesMissing : [];
   if (ctx.ciNotFailClosed) {
@@ -119,6 +149,8 @@ export function collectDoctorNextActions(ctx) {
   if (notAdopted || ctx.adopted === ADOPTED_NOT || ctx.adopted == null) {
     actions.push(ctx.notAdoptedNextAction || NOT_ADOPTED_NEXT_ACTION);
   }
+  const resolvePkg = packageUnresolvedNextAction(ctx);
+  if (resolvePkg) actions.push(resolvePkg);
   const nudge = ctx.stewardNudge;
   if (
     nudge &&
@@ -259,6 +291,9 @@ export function collectDoctorNextActions(ctx) {
   if (ctx.designFitness.designWeak && unique.length === 0 && ctx.postGreenPath) {
     unique.push(ctx.postGreenPath.action);
   }
+  if (resolvePkg) {
+    return [resolvePkg, ...unique.filter((a) => a !== resolvePkg)];
+  }
   if (overlapAction) {
     return [overlapAction, ...unique.filter((a) => a !== overlapAction)];
   }