arkgate 4.5.7 → 4.6.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ in the immutable pre-2.0 archive linked below.
 
 ## Unreleased
 
+## 4.6.0 — 2026-08-12
+
+**Minor** over **4.5.7**. Understandable Ark: doctor, HTML, skills, and public docs use common
+software words (import rules, leftover design work, pre-write block) while **ArkGate** and
+**ArkRules** stay as product names. Shared Claude/Grok agent homes get the same monotonic
+“always latest” floor Codex already had. **No required config migration.** JSON field names
+and `ruleId`s stay stable. No new skill names, sensors, or scores.
+
+**Status: prepared** (not yet on npm `latest`; see `docs/releases/4.6.0.md`).
+
+### Added
+
+- **Shared Claude/Grok home skills:** `--claude-home`, `--grok-home`, and `--agent-homes`
+  write monotonic home catalogs (Codex-parity lock + floor). Doctor reports stale
+  `~/.claude/skills` / `~/.grok/skills` when those catalogs exist. Temp/upgrade `--root`
+  never mutates default user homes.
+
+### Changed
+
+- **Human language:** doctor, HTML report, compact router, skills, and public lanes prefer
+  common terms. Leftover design work replaces “design-weak” in human copy; JSON `designWeak`
+  is unchanged.
+
 ## 4.5.7 — 2026-08-12
 
 **Patch** over **4.5.6**. Cursor hard write path: project `.cursor/hooks.json` `preToolUse`
@@ -13,7 +36,7 @@ gate for `Write` / `StrReplace` (failClosed), host matrix + doctor honesty, payl
 emit; Write `updated_input` reinjection is **not** claimed. Codex/OpenCode stay advisory at
 write. Shell/Tab/human edits still rely on required CI. **No required config migration.**
 
-**Status: prepared** (not published).
+**Status: published** (on npm `latest`; see `docs/releases/4.5.7.md`).
 
 ### Added
 

package/README.md

@@ -2,7 +2,7 @@
 
 # ArkGate — Architecture Co-pilot for AI TypeScript
 
-**One contract. One gate. One co-pilot.**
+**One architecture config. One check. One coach.**
 
 Your AI writes most of the code. ArkGate keeps that work inside an architecture you can trust —
 and makes sure a “green” check means something real.
@@ -16,8 +16,8 @@ and makes sure a “green” check means something real.
 
 </div>
 
-> **ArkGate 4.5.6** is on npm `latest` — field upgrade truth, multi-project MCP honesty, skill drift.
-> [4.5.6 notes](docs/releases/4.5.6.md) · [4.5.5](docs/releases/4.5.5.md) · [4.5.0](docs/releases/4.5.0.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
+> **ArkGate 4.6.0** is prepared — clearer language + shared agent home skills.
+> [4.6.0 notes](docs/releases/4.6.0.md) · [4.5.7](docs/releases/4.5.7.md) (npm `latest`) · [4.5.6](docs/releases/4.5.6.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
 
 ---
 
@@ -43,9 +43,9 @@ npx arkgate-check --doctor        # control plane: status light + primary next a
 ```
 
 That is the product. Doctor is the control plane — when stuck, do **primary next action #1**.
-Doctor also shows an **improvement compass** (architecture lenses such as separation of concerns and
-dependency inversion — **not a score**). Residual lenses mean Shape work may remain even when edges
-are green. Details: [use.md — Improvement compass](docs/use.md#improvement-compass-not-a-score).
+Doctor also shows **what to improve next** (architecture lenses such as separation of concerns and
+dependency inversion — **not a score**). Leftover lenses mean design work may remain even when
+imports are green. Details: [use.md — Improvement compass](docs/use.md#improvement-compass-not-a-score).
 
 ```text
 start → doctor (+ compass) → day-to-day (place + gate)
@@ -64,15 +64,15 @@ A machine-readable architecture file (`ark.config.json`) plus enforcement:
 
 | When | Tool |
 |------|------|
-| **While the AI writes** | Hard PreToolUse on supported hosts; advisory MCP elsewhere |
+| **While the AI writes** | Pre-write block on supported hosts; warning only elsewhere |
 | **Before merge** | `arkgate-check` as a **required** CI status |
 
 ### Two planes (4.0)
 
 | Plane | What it guards | Config |
 |-------|----------------|--------|
-| **Layers** (always) | Who may talk to whom — imports, placement, purity, isolation | `ark.config.json` layers + rules |
-| **ArkRules** (opt-in) | Habits *inside* a layer — structure sensors + domain invariants as data | `arkRules` → `arkrules/<Layer>.json` |
+| **Layers** (always) | Who may import whom — imports, placement, purity, isolation | `ark.config.json` layers + rules |
+| **ArkRules** (opt-in; structure rules inside a layer) | Habits *inside* a layer — structure sensors + domain invariants as data | `arkRules` → `arkrules/<Layer>.json` |
 
 Absence of ArkRules changes no inter-layer verdict. Label residual **`[Layer]`** vs **`[ArkRules]`**.  
 Details: [configuration](docs/configuration.md#arkrules-intra-layer-opt-in) · [use path](docs/use.md).
@@ -175,6 +175,8 @@ npx arkgate-check --plan
 npx arkgate-check --coverage
 npx arkgate-check --strict-merge   # CI / required status
 npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok
+# optional: refresh shared home skills (Claude/Grok/Codex; never downgrades)
+# npx arkgate-check --install-agent-gates --skills-only --agent-homes --force
 # optional: same 13 skills via Agent Skills ecosystem (no new names)
 # npx skills add ./node_modules/arkgate/templates/agent-skills
 ```
@@ -208,7 +210,7 @@ for real systems. Details: [docs/production-hardening.md](docs/production-harden
 | 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 release (4.5.6 on npm `latest`) | [docs/releases/4.5.6.md](docs/releases/4.5.6.md) · [CHANGELOG](CHANGELOG.md) |
+| Current release (4.5.7 on npm `latest`) | [docs/releases/4.5.7.md](docs/releases/4.5.7.md) · [CHANGELOG](CHANGELOG.md) |
 | Prior (4.5.0) | [docs/releases/4.5.0.md](docs/releases/4.5.0.md) |
 | Prior (4.4.0) | [docs/releases/4.4.0.md](docs/releases/4.4.0.md) |
 | Prior (4.3.0) | [docs/releases/4.3.0.md](docs/releases/4.3.0.md) |

package/bin/ark-check-runtime.mjs

@@ -213,6 +213,14 @@ function parseArgs(argv) {
     else if (arg === '--watch') args.watch = true;
     else if (arg === '--beginner') args.beginner = true;
     else if (arg === '--codex-home') args.codexHome = true;
+    else if (arg === '--claude-home') args.claudeHome = true;
+    else if (arg === '--grok-home') args.grokHome = true;
+    else if (arg === '--agent-homes') {
+      args.agentHomes = true;
+      args.codexHome = true;
+      args.claudeHome = true;
+      args.grokHome = true;
+    }
     else if (arg === '--migrate-commands') args.migrateCommands = true;
     else if (arg === '--no-cache') args.noCache = true;
     else if (arg === '--resident') args.resident = true;
@@ -275,7 +283,7 @@ function usage() {
     '           Best-effort open in browser (local TTY). No-op if open fails. --no-open / ARK_NO_OPEN_REPORT=1 to skip; --open forces open.',
     '       ark-check --init [--preset hexagonal|layered|feature-sliced|monorepo|ui-surface|vertical-slice|ddd-bounded-contexts|vite-vercel-spa|clean-architecture|onion-architecture] [--force] [--follow-config-root]',
     '       --follow-config-root  On writes (init/install-agent-gates/migrate --write/…), adopt walked-up monorepo config root (default: keep explicit --root)',
-    '       ark-check --install-agent-gates [--tools claude,cursor,codex,grok] [--require-write-hook <host>] [--skills-only] [--codex-home] [--force]',
+    '       ark-check --install-agent-gates [--tools claude,cursor,codex,grok] [--require-write-hook <host>] [--skills-only] [--codex-home] [--claude-home] [--grok-home] [--agent-homes] [--force]',
     '       ark-check --update-baseline [file]     freeze current violations (default .ark-baseline.json)',
     '       ark-check --print-config eleven-layer',
     '',

package/bin/lib/agent-homes.mjs

@@ -0,0 +1,296 @@
+/**
+ * Shared agent home skill catalogs (Claude / Grok), Codex-parity monotonic install.
+ * Repo catalogs stay per-project; these homes are the machine floor (never downgrade).
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { arkCommand } from '../ark-shared.mjs';
+import { isTempOrUpgradeRoot } from './codex-home.mjs';
+import {
+  arkPackageVersion,
+  assessSkillCatalogParity,
+  detectActiveAgentHost,
+  isValidSemver,
+  isVersionOlder,
+  skillTemplateNames,
+  skillTemplates,
+} from './skill-install.mjs';
+import {
+  HOME_SKILL_CATALOG,
+  HOME_SKILL_PENDING_CATALOG,
+  installSkillCatalog,
+  skillInstallLine,
+} from './skill-write.mjs';
+
+/** @typedef {'claude'|'grok'} AgentHomeHost */
+
+const HOSTS = {
+  claude: {
+    id: 'claude',
+    label: 'Claude',
+    envKey: 'CLAUDE_HOME',
+    defaultDirName: '.claude',
+    flag: '--claude-home',
+  },
+  grok: {
+    id: 'grok',
+    label: 'Grok',
+    envKey: 'GROK_HOME',
+    defaultDirName: '.grok',
+    flag: '--grok-home',
+  },
+};
+
+export function agentHomeHostIds() {
+  return Object.keys(HOSTS);
+}
+
+export function claudeHomeDir(env = process.env, homeDir = os.homedir()) {
+  return resolveHomeDir(HOSTS.claude, env, homeDir);
+}
+
+export function grokHomeDir(env = process.env, homeDir = os.homedir()) {
+  return resolveHomeDir(HOSTS.grok, env, homeDir);
+}
+
+export function claudeSkillsDir(env = process.env, homeDir = os.homedir()) {
+  return path.join(claudeHomeDir(env, homeDir), 'skills');
+}
+
+export function grokSkillsDir(env = process.env, homeDir = os.homedir()) {
+  return path.join(grokHomeDir(env, homeDir), 'skills');
+}
+
+export function usesDefaultClaudeHome(env = process.env, homeDir = os.homedir()) {
+  return usesDefaultHome(HOSTS.claude, env, homeDir);
+}
+
+export function usesDefaultGrokHome(env = process.env, homeDir = os.homedir()) {
+  return usesDefaultHome(HOSTS.grok, env, homeDir);
+}
+
+function resolveHomeDir(spec, env, homeDir) {
+  const configured = env?.[spec.envKey];
+  if (typeof configured === 'string' && configured.trim() !== '') {
+    return path.resolve(configured);
+  }
+  return path.resolve(homeDir, spec.defaultDirName);
+}
+
+function usesDefaultHome(spec, env, homeDir) {
+  const configured = env?.[spec.envKey];
+  if (typeof configured !== 'string' || configured.trim() === '') return true;
+  return path.resolve(configured) === path.resolve(homeDir, spec.defaultDirName);
+}
+
+function skillsDirFor(host, env = process.env) {
+  return host === 'grok' ? grokSkillsDir(env) : claudeSkillsDir(env);
+}
+
+function readHomeCatalogFloor(skillsDir) {
+  const readOne = (file) => {
+    try {
+      const value = JSON.parse(fs.readFileSync(file, 'utf8'));
+      const version = typeof value?.packageVersion === 'string' ? value.packageVersion : null;
+      const valid =
+        value &&
+        value.schemaVersion === '1.0' &&
+        isValidSemver(version) &&
+        Array.isArray(value.skills);
+      return { exists: true, valid, version: valid ? version : null };
+    } catch (error) {
+      if (error && error.code === 'ENOENT') return { exists: false, valid: true, version: null };
+      return { exists: true, valid: false, version: null };
+    }
+  };
+  const catalog = readOne(path.join(skillsDir, HOME_SKILL_CATALOG));
+  const pending = readOne(path.join(skillsDir, HOME_SKILL_PENDING_CATALOG));
+  let floorVersion = catalog.version;
+  if (pending.version && (!floorVersion || isVersionOlder(floorVersion, pending.version))) {
+    floorVersion = pending.version;
+  }
+  return {
+    floorVersion,
+    pendingVersion: pending.version,
+    hasMetadata: catalog.exists || pending.exists,
+    metadataInvalid:
+      (catalog.exists && !catalog.valid) || (pending.exists && !pending.valid),
+  };
+}
+
+function homeInPlay(parity, catalogState) {
+  return parity.presentCount > 0 || catalogState.hasMetadata;
+}
+
+/**
+ * Detect Claude/Grok user-home ark-* catalogs that lag this package.
+ * Absent homes are not debt. Stamp-only body-match is not content-behind
+ * (assessSkillCatalogParity already treats identity match as current).
+ *
+ * @param {string} root
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {Array<{
+ *   host: AgentHomeHost,
+ *   label: string,
+ *   skillsDir: string,
+ *   missing: number,
+ *   stale: number,
+ *   presentCount: number,
+ *   expectedCount: number,
+ *   packageVersion: string|null,
+ *   catalogVersion: string|null,
+ *   pendingRecoveryRequired: boolean,
+ *   catalogMetadataInvalid: boolean,
+ *   catalogStateReason: string|null,
+ *   flag: string,
+ * }>}
+ */
+export function detectAgentHomeGaps(root, env = process.env) {
+  if (!fs.existsSync(path.join(root, 'AGENTS.md'))) return [];
+  if (fs.existsSync(path.join(root, 'templates', 'skills'))) return [];
+  const skillNames = skillTemplateNames();
+  if (skillNames.length === 0) return [];
+  const packageVersion = arkPackageVersion();
+  const gaps = [];
+  for (const host of agentHomeHostIds()) {
+    const spec = HOSTS[host];
+    const dir = skillsDirFor(host, env);
+    const skillFile = (name) => path.join(dir, name, 'SKILL.md');
+    const parity = assessSkillCatalogParity(skillNames, skillFile, packageVersion);
+    const catalogState = readHomeCatalogFloor(dir);
+    if (!homeInPlay(parity, catalogState)) continue;
+    const newerFloor =
+      catalogState.floorVersion &&
+      isValidSemver(packageVersion) &&
+      isVersionOlder(packageVersion, catalogState.floorVersion);
+    const pendingRecoveryRequired =
+      catalogState.pendingVersion !== null && !newerFloor;
+    const needsAttention =
+      !newerFloor &&
+      (parity.missing > 0 ||
+        parity.stale > 0 ||
+        pendingRecoveryRequired ||
+        catalogState.metadataInvalid);
+    if (!needsAttention) continue;
+    gaps.push({
+      host,
+      label: spec.label,
+      skillsDir: dir,
+      missing: parity.missing,
+      stale: parity.stale,
+      presentCount: parity.presentCount,
+      expectedCount: skillNames.length,
+      packageVersion,
+      catalogVersion: catalogState.floorVersion,
+      pendingRecoveryRequired,
+      catalogMetadataInvalid: catalogState.metadataInvalid,
+      catalogStateReason: catalogState.metadataInvalid
+        ? 'invalid catalog metadata'
+        : pendingRecoveryRequired
+          ? 'interrupted catalog commit'
+          : null,
+      flag: spec.flag,
+    });
+  }
+  return gaps;
+}
+
+/**
+ * Claude home is loaded by Claude Code and often by Cursor. Treat both as in-session.
+ * Grok home is urgent only on a Grok session (or when ARK_ACTIVE_HOST=grok).
+ */
+export function agentHomeConcernIsActive(host, env = process.env) {
+  const active = detectActiveAgentHost(env);
+  if (host === 'claude') return active === 'claude' || active === 'cursor' || !active;
+  if (host === 'grok') return active === 'grok' || !active;
+  return true;
+}
+
+export function agentHomeRefreshCommand(root, gap) {
+  return arkCommand(
+    root,
+    'ark-check',
+    `--install-agent-gates --skills-only ${gap.flag} --force`
+  );
+}
+
+/**
+ * @param {{
+ *   root: string,
+ *   skills?: Array<[string, string]>,
+ *   version: string|null,
+ *   force?: boolean,
+ *   claudeHome?: boolean,
+ *   grokHome?: boolean,
+ *   agentHomes?: boolean,
+ *   json?: boolean,
+ *   env?: NodeJS.ProcessEnv,
+ * }} args
+ * @returns {Array<{ host: string, results: object[] }>}
+ */
+export function installRequestedAgentHomes(args) {
+  const env = args.env ?? process.env;
+  const wantClaude = Boolean(args.claudeHome || args.agentHomes);
+  const wantGrok = Boolean(args.grokHome || args.agentHomes);
+  if (!wantClaude && !wantGrok) return [];
+  const skills = args.skills ?? skillTemplates();
+  const version = args.version ?? arkPackageVersion();
+  const installed = [];
+  const targets = [
+    wantClaude ? { host: 'claude', spec: HOSTS.claude, dir: claudeSkillsDir(env), usesDefault: usesDefaultClaudeHome(env) } : null,
+    wantGrok ? { host: 'grok', spec: HOSTS.grok, dir: grokSkillsDir(env), usesDefault: usesDefaultGrokHome(env) } : null,
+  ].filter(Boolean);
+
+  for (const target of targets) {
+    if (isTempOrUpgradeRoot(args.root) && target.usesDefault) {
+      if (!args.json) {
+        console.log('');
+        console.log(
+          `${target.spec.label} home skills: skipped (temp/upgrade --root must not mutate default ~/${target.spec.defaultDirName}).`
+        );
+      }
+      installed.push({
+        host: target.host,
+        skipped: true,
+        reason: 'temp-root-default-home',
+        results: [],
+      });
+      continue;
+    }
+    if (!args.json) {
+      console.log('');
+      console.log(
+        `${target.spec.label} home skills (scope=home-shared; source=${version ? `arkgate@${version}` : 'arkgate@unknown'}; target=${target.dir}/<name>/SKILL.md):`
+      );
+      console.log(
+        '  Compatibility: monotonic downgrade protection requires ArkGate 4.2.0+ writers; older packages cannot lower this catalog.'
+      );
+    }
+    try {
+      fs.mkdirSync(target.dir, { recursive: true });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (!args.json) console.error(`  FAILED to create ${target.dir} (${message})`);
+      installed.push({
+        host: target.host,
+        skipped: false,
+        results: [{ relativePath: target.dir, status: 'failed', message }],
+      });
+      continue;
+    }
+    const results = [];
+    for (const result of installSkillCatalog({
+      directory: target.dir,
+      skills,
+      packageVersion: version,
+      force: args.force,
+      scope: 'home',
+    })) {
+      if (!args.json) console.log(skillInstallLine(result));
+      results.push(result);
+    }
+    installed.push({ host: target.host, skipped: false, results });
+  }
+  return installed;
+}

package/bin/lib/agent-projection.mjs

@@ -148,7 +148,7 @@ export function buildAgentProjectionBody(facts) {
         '',
     ];
     if (profile === 'compact') {
-        lines.push('### Primary path', '', '1. Run doctor (`ark-check --doctor`) — status light + primary next action.', '2. Read the improvement compass (not a score). Name residual lenses in plain language; never “done” on green edges alone while residual remains.', '3. Call `ark_identity` with `project.expectedRoot` at the exact project root; reuse root + `projectId` on Ark MCP calls.', '4. Read the contract with `ark_manifest` (same expectation). `ark://manifest` is compatibility-only / unverified.', '5. Place files inside configured layers; validate; run the check command above on violations — fix architecture, do not weaken the gate.', '6. Single door: edges debt → fix; design-weak / residual shape lenses → map then guided apply with user OK.', '', '### Contract layers (summary)', '', formatAgentProjectionLayers(layers), '');
+        lines.push('### Primary path', '', '1. Run doctor (`ark-check --doctor`) — status light + primary next action.', '2. Read the improvement compass (not a score). Name leftover work in plain language; never “done” on green imports alone while leftover design work remains.', '3. Call `ark_identity` with `project.expectedRoot` at the exact project root; reuse root + `projectId` on Ark MCP calls.', '4. Read architecture config with `ark_manifest` (same expectation). `ark://manifest` is compatibility-only / unverified.', '5. Place files inside configured layers; validate; run the check command above on violations — fix architecture, do not weaken the gate.', '6. Single door: import-rule debt → fix; leftover design work / residual shape lenses → map then guided apply with user OK.', '', '### Contract layers (summary)', '', formatAgentProjectionLayers(layers), '');
     }
     else {
         lines.push('### Contract layers', '', formatAgentProjectionLayers(layers), '', 'When creating a **new** kind of code that no layer covers, update `ark.config.json` first (`/ark-contract`), then place the file.', '', '### Diagnostic codes (short list)', '', formatAgentProjectionCatalogShortList(catalog, docsPath), '', '### Session truth', '', '- Machine snapshot: `ark status --json` (or MCP `ark_status`) — identity, activation honesty, last check, residual counts. **Not a score.**', '- Authoritative contract: `ark_manifest` after a matched `ark_identity` handshake.', '');

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

@@ -343,7 +343,7 @@ Pick **one** primary skill. Prefer doctor top action #1 when unsure.
 |------|--------|----------|
 | Unsure what to do next | **Doctor top action #1** (\`${doctorCmd}\`), then re-run doctor | skill-shopping, defaulting to autopilot |
 | Make architecture sound (guided apply path) | **/ark-autopilot** | explore-only, coverage-only |
-| **Messy / spaghetti / design-weak after green / Shape residual** | **Single path:** \`/ark-explore\` shape-focus → dual-plan B, then \`/ark-autopilot\` only to apply B with OK | coverage, think, loop-as-done, skill-shopping |
+| **Messy / leftover design work after green** | **Single path:** \`/ark-explore\` shape-focus → plan B, then \`/ark-autopilot\` only to apply B with OK | coverage, think, loop-as-done, skill-shopping |
 | Map / residual / dual-plan seed only (no apply, already know you want recon) | \`/ark-explore\` | coverage (fitness only) |
 | Greenfield shape / empty tree | \`/ark-architect\` | adopt |
 | Brownfield / wrong contract / false-green | \`/ark-adopt\` then \`/ark-contract\` if globs wrong | architect |
@@ -351,13 +351,13 @@ Pick **one** primary skill. Prefer doctor top action #1 when unsure.
 | New file “where does this go?” | \`/ark-place\` | architect (unless greenfield shape missing) |
 | Gate violation on a change (small cluster) | \`/ark-fix\` | loop/autopilot unless bulk |
 | Drive plan **A** to goal.met | \`/ark-loop\` | explore (unless A empty + design residual → single Shape path above) |
-| Ark **fitness** only (governed%, gates, baseline, install gaps) | \`/ark-coverage\` | Shape / design-weak (use single path above) |
+| Ark **fitness** only (governed%, gates, baseline, install gaps) | \`/ark-coverage\` | leftover design work (use single path above) |
 | One design decision, 2–3 options | \`/ark-think\` | full Shape residual (use single path) |
 | Explain / HTML report tour | \`/ark-explain\` | explore |
 | Bump arkgate + refresh hosts | \`/ark-upgrade\` | — |
 | Optional runtime kernel evaluate | \`/ark-runtime\` | — |
 
-**Post-green door (Q01):** when doctor reports ENFORCE · design-weak, the **primary** next action is the single Shape path above — not a choice among explore / coverage / think. Doctor JSON: \`postGreenPath\` / \`primaryNextAction\`.
+**Post-green door:** when doctor reports ENFORCE · leftover design work, the **primary** next action is the single Shape path above — not a choice among explore / coverage / think. Doctor JSON: \`postGreenPath\` / \`primaryNextAction\`.
 
 **Phases (brownfield honesty):** Align (contract truth) → Stabilize (real baseline) → Shape (golden pattern + pilot). Empty plan A after Stabilize still leaves Shape work — that is the single post-green path, not “healthy finished.”
 
@@ -406,14 +406,14 @@ ${projectionBlock}
 
 1. Status anytime: \`${doctorCmd}\` — one status light, one primary next action (control plane).
 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. Before trusting 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 the process is stale: restart the host and use the local CLI meanwhile.
-4. Day to day: call \`ark_manifest\` with the same project expectation; place new files with \`ark_place\`; validate after edits; run \`${checkCmd}\`. The \`ark://manifest\` resource is compatibility-only and always unverified/non-authoritative. On a gate deny, fix the architecture — do not weaken the contract.
+3. Before trusting 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; place new files with \`ark_place\`; validate after edits; run \`${checkCmd}\`. The \`ark://manifest\` resource is compatibility-only and always unverified. On a gate deny, fix the architecture — do not weaken \`ark.config.json\`.
 5. If MCP is unavailable: inspect \`ark.config.json\` and run \`${checkCmd}\`.
 
 **Single door when residual remains:**
 - **Edges debt** (import/capability violations) → fix with the gate / plan; skill pack only if doctor names a skill.
-- **Design-weak / residual shape lenses** (compass residual while edges may look green) → map first, then guided apply with user OK — never “you’re done” on green edges alone.
-- Empty plan A + residual lenses / design-weak → **not finished**.
+- **Design leftover / residual shape lenses** (compass leftover while imports may look green) → map first, then guided apply with user OK — never “you’re done” on green imports alone.
+- Empty plan A + leftover design work → **not finished**.
 
 **Two-axis done (never collapse):**
 1. **Architecture residual** — status / doctor / compass (scan). Prefer deep modules; name seams; test at the public interface.

package/bin/lib/design-smells.mjs

@@ -9,6 +9,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { layerForFile } from '../ark-shared.mjs';
 import { detectContractFalseGreenRisk } from './field-install.mjs';
+import { operatingModeTitle, LEFTOVER_DESIGN_LABEL } from './product-copy.mjs';
 
 /** Stable smell ids (doctor JSON + plan B + skills). */
 export const DESIGN_SMELL_IDS = Object.freeze([
@@ -476,20 +477,15 @@ export function isDesignWeak(smells, ctx = {}) {
  */
 export function summarizeDesignFitness(smells, ctx = {}) {
   const designWeak = isDesignWeak(smells, ctx);
-  const mode =
-    typeof ctx.operatingMode === 'string' &&
-    /^(?:suggest|adapt|enforce)$/.test(ctx.operatingMode)
-      ? ctx.operatingMode.toUpperCase()
-      : null;
   return {
     status: designWeak ? 'design-weak' : smells.length > 0 ? 'smells-with-open-edges' : 'ok',
     designWeak,
     smellCount: Array.isArray(smells) ? smells.length : 0,
     ids: (smells || []).map((s) => s.id),
     label: designWeak
-      ? `${mode ? `${mode} · ` : ''}design-weak — edges clean; Shape residual remains (see designSmells / plan B)`
+      ? `${operatingModeTitle(ctx.operatingMode, true)} — import rules check out; leftover design work remains (see designSmells / plan B)`
       : smells.length > 0
-        ? 'Design smells present alongside open edge debt'
+        ? 'Design smells present alongside open import-rule debt'
         : 'No deterministic design smells detected',
   };
 }

package/bin/lib/doctor-plan.mjs

@@ -12,6 +12,12 @@ import {
 import * as arkShared from '../ark-shared.mjs';
 import { summarizeRulesUnderContract } from './rules-under-contract.mjs';
 import { describePackageVersionDualTruth } from './field-install.mjs';
+import {
+  detectAgentHomeGaps,
+  agentHomeConcernIsActive,
+  agentHomeRefreshCommand,
+} from './agent-homes.mjs';
+import { operatingModeTitle } from './product-copy.mjs';
 export { summarizeRulesUnderContract };
 
 /** Optional S3 dual-match classifier when ark-shared exports it (soft dep for S5 landing). */
@@ -340,7 +346,7 @@ export function buildRemediationPlan(
             : 'No active violations — the architecture already meets its contract.';
   if (designWeak) {
     statement =
-      'No active edge violations — contract edges are clean, but design smells remain (design-weak). Shape residual is plan B only; not healthy finished.';
+      'No active import-rule violations — imports check out, but design smells remain (leftover design work). Shape work is plan B only; not healthy finished.';
   }
   if (completeness !== ANALYSIS_COMPLETENESS.complete) statement = analysisIncompleteStatement(completeness);
 
@@ -523,6 +529,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   }
   const gatesMissing = missingGates(root);
   const skillGaps = detectSkillGaps(root);
+  const agentHomeGaps = detectAgentHomeGaps(root);
   // Dual-truth: CLI version vs package.json pin (field residual after upgrade --no-install).
   const packageVersionTruth = describePackageVersionDualTruth(root);
   const staleRunners = staleRunnerGateFiles(root);
@@ -759,6 +766,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             },
             gatesMissing,
             skillGaps,
+            ...(agentHomeGaps.length > 0 ? { agentHomeGaps } : {}),
             staleRunnerFiles: staleRunners,
             writePath: {
               activeHost: writePath.activeHost,
@@ -836,21 +844,18 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   // modeTitle alone names the light — bodies must not re-prefix Suggest/Adapt/Enforce.
   const modeHelp = {
     suggest:
-      'thin or new tree; the contract is not yet the control plane. You do not pick this light. Next: ark start (preview), then ark start --apply; re-check with --doctor.',
+      'thin or new tree; architecture config is not yet in charge. You do not pick this light. Next: ark start (preview), then ark start --apply; re-check with --doctor.',
     adapt:
-      'contract and tree still disagree, or debt is open. Write path does not fully protect you yet. You do not pick this light. Next: do doctor top action #1 (often /ark-adopt, /ark-contract, or /ark-autopilot).',
+      'config and tree still disagree, or debt is open. The write path does not fully protect you yet. You do not pick this light. Next: do doctor top action #1 (often /ark-adopt, /ark-contract, or /ark-autopilot).',
     enforce:
-      'honest coverage and clean checked edges. You arrived here; you never turn Enforce on. Next: keep the host write path and CI check; only NEW violations should fail.',
+      'honest coverage and clean checked imports. You arrived here; you never turn Enforce on. Next: keep the host write path and CI check; only NEW violations should fail.',
   };
-  const modeTitle =
-    designFitness.designWeak
-      ? `${mode.toUpperCase()} · design-weak`
-      : mode.toUpperCase();
+  const modeTitle = operatingModeTitle(mode, designFitness.designWeak);
   line(
     modeMark,
     `${modeTitle} — ${
       designFitness.designWeak
-        ? 'checked edges are honest; design smells remain. Green is not elegant design. You do not pick this light. Next: one Shape door — /ark-explore shape-focus → dual-plan B; apply B only with /ark-autopilot and your OK. Empty plan A is not done.'
+        ? 'import rules check out; design smells remain. Green is not elegant design. You do not pick this light. Next: one Shape door — /ark-explore shape-focus → plan B; apply B only with /ark-autopilot and your OK. A clean import check is not done.'
         : modeHelp[mode]
     }`
   );
@@ -914,7 +919,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
         `Next pilot (one at a time): ${np.pilotTarget || np.pilot} [${np.smellId}] → re-doctor after change`
       );
       line(' ', color.dim(`success: ${np.successSignal}`));
-      line(' ', color.dim('never multi-pilot batch; patternBets never mechanical-safe'));
+      line(' ', color.dim('never multi-pilot batch; pattern bets are never auto-applied'));
     }
   }
 
@@ -933,7 +938,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
       ok,
       `"${goldenPattern.name}" — ${goldenPattern.norm}` +
         (goldenPattern.newCodeHome ? ` Prefer: ${goldenPattern.newCodeHome}.` : '') +
-        ' Advisory only — does not clear design-weak or replace the gate.'
+        ' Advisory only — does not clear leftover design work or replace the gate.'
     );
   } else if (goldenPattern.invalid) {
     console.log('');
@@ -1038,7 +1043,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
         'No active violations — coverage is still thin, so green is not yet honest enforcement'
       );
     } else if (designFitness.designWeak) {
-      line(warn, `None on checked edges — edges match the contract; design residual remains (${modeTitle}). Not healthy finished.`);
+      line(warn, `None on checked imports — import rules match the config; leftover design work remains (${modeTitle}). Not healthy finished.`);
     } else {
       line(ok, 'None — the code matches the contract on checked edges');
     }
@@ -1157,6 +1162,25 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
       actions.push(codexHomeGap.catalogMetadataInvalid ? 'repair invalid Codex home catalog metadata after verifying the newest installed version' : 'refresh Codex home skills (--install-agent-gates --skills-only --codex-home --force)');
     }
   }
+  for (const gap of agentHomeGaps) {
+    const parts = [
+      gap.missing > 0 ? `${gap.missing} missing` : null,
+      gap.stale > 0 ? `${gap.stale} content-behind-package` : null,
+      gap.catalogStateReason,
+    ].filter(Boolean);
+    const deferred = !agentHomeConcernIsActive(gap.host);
+    const summary = `${gap.label} shared agent skills ${parts.join(', ')}`;
+    if (deferred) {
+      line(color.dim('·'), color.dim(`${summary} (deferred — not this session)`));
+    } else {
+      line(warn, summary);
+      actions.push(
+        gap.catalogMetadataInvalid
+          ? `repair invalid ${gap.label} home catalog metadata after verifying the newest installed version`
+          : `refresh ${gap.label} shared agent skills (${agentHomeRefreshCommand(root, gap)})`
+      );
+    }
+  }
 
   console.log('');
   console.log(color.bold('Baseline'));

package/bin/lib/golden-pattern.mjs

@@ -154,7 +154,7 @@ export function formatGoldenPatternNote(result) {
   let s = `Golden pattern (advisory for NEW code only): "${g.name}" — ${g.norm}`;
   if (g.newCodeHome) s += ` Prefer new files under ${g.newCodeHome}.`;
   if (g.examplePath) s += ` Example: ${g.examplePath}.`;
-  s += ' Does not clear design-weak or replace the gate.';
+  s += ' Does not clear leftover design work or replace the gate.';
   return s;
 }