arkgate 4.5.7 → 4.6.0

package/bin/lib/host-support-matrix.mjs

@@ -224,18 +224,18 @@ export function doctorWritePathHonestyMessage(activeHost, hardWriteActive) {
   const mergeBoundary =
     'Required CI hard merge boundary = a required GitHub status context that runs arkgate-check --strict-merge (alias ark-check --strict-merge)';
   if (host === 'cursor' && !hardWriteActive) {
-    return `Cursor: hard preToolUse is supported for Write/StrReplace when .cursor/hooks.json is installed + trusted; without runtime-observed hook evidence, hard is unverified. ${mergeBoundary}.`;
+    return `Cursor: pre-write block is supported for Write/StrReplace when .cursor/hooks.json is installed + trusted; without runtime-observed hook evidence, the block is unverified. ${mergeBoundary}.`;
   }
   if (host === 'codex') {
-    return `Codex: write path is advisory / best-effort at write (not Claude/Grok/Cursor hard). ${mergeBoundary}.`;
+    return `Codex: edits are warning only (not blocked) at write time. ${mergeBoundary}.`;
   }
   if (host === 'opencode') {
-    return `OpenCode: write path is advisory / best-effort (MCP + optional plugin; not Claude/Grok/Antigravity/Cursor hard). ${mergeBoundary}.`;
+    return `OpenCode: edits are warning only (not blocked). ${mergeBoundary}.`;
   }
   if ((host === 'claude' || host === 'grok' || host === 'antigravity') && !hardWriteActive) {
     const label =
       host === 'claude' ? 'Claude' : host === 'grok' ? 'Grok' : 'Antigravity';
-    return `${label}: hard PreToolUse is supported for listed ops when installed + trusted; without runtime-observed hook evidence, hard is unverified. ${mergeBoundary}.`;
+    return `${label}: pre-write block is supported for listed ops when installed + trusted; without runtime-observed hook evidence, the block is unverified. ${mergeBoundary}.`;
   }
   return null;
 }

package/bin/lib/html-report-depth.mjs

@@ -24,6 +24,7 @@ import { describePackageVersionDualTruth } from './field-install.mjs';
 import { buildDoctorImprovementCompass } from './improvement-compass-doctor.mjs';
 import { buildDeepModuleCoachAdvisory } from './deep-module-coach.mjs';
 import { computePhysicalCohesion } from './physical-cohesion.mjs';
+import { POST_GREEN_LEDE, operatingModeTitle } from './product-copy.mjs';
 
 function esc(value) {
   return String(value)
@@ -383,13 +384,11 @@ export function renderDesignDepthStrip(depth = {}) {
 
   const mode = String(depth.mode || '').toLowerCase();
   const title = designWeak
-    ? mode === 'enforce'
-      ? 'ENFORCE · design-weak'
-      : `${(mode || 'edges').toUpperCase()} · design-weak`
-    : 'Design smells (edges still open)';
+    ? operatingModeTitle(mode || 'enforce', true)
+    : 'Design smells (imports still open)';
   const lede = designWeak
-    ? 'Contract edges are clean, but lived design residual remains. This does not fail PASS — it blocks “healthy finished” until Shape work lands.'
-    : 'Design smells exist alongside open edge debt. Fix edges first; treat smells as Shape residual after green.';
+    ? POST_GREEN_LEDE
+    : 'Design smells exist alongside open import-rule debt. Fix imports first; treat smells as leftover design work after green.';
 
   const smellItems = smells
     .slice(0, 6)
@@ -411,7 +410,7 @@ export function renderDesignDepthStrip(depth = {}) {
     ? `<div class="pilot-card">
         <h3 style="margin-top:.85rem">Next pilot (one at a time)</h3>
         <p class="dim" style="margin:.15rem 0 .4rem;font-size:.86rem">
-          Judgment only — never mechanical-safe · never multi-pilot batch
+          Judgment only — never auto-applied · never multi-pilot batch
         </p>
         <ul class="senior-list">
           <li><b>Smell</b> · <code>${esc(pilot.smellId || pilot.id || '—')}</code></li>
@@ -489,7 +488,7 @@ export function renderDesignCleanNote(depth = {}) {
   return `<div class="section card design-strip is-clean" id="design-depth">
       <div class="design-head">
         <span class="badge design-ok" title="No deterministic design smells with clean edges">Design depth · OK</span>
-        <span class="dim" style="font-size:.86rem">No design-weak residual detected</span>
+        <span class="dim" style="font-size:.86rem">No leftover design work detected</span>
       </div>
       <p class="dim" style="margin:.45rem 0 0;font-size:.88rem">
         Edges and deterministic design sensors agree. Keep placing new code on the golden path;

package/bin/lib/html-report.mjs

@@ -11,6 +11,7 @@ import {
   resolveOperatingMode,
 } from '../ark-shared.mjs';
 import { collectAdoptionGaps, arkCheckCommand } from './agent-gates.mjs';
+import { LEFTOVER_DESIGN_BADGE } from './product-copy.mjs';
 import { CORE_LAYER_NAMES } from './core-layers.mjs';
 import {
   renderBaselineSignalLegend,
@@ -525,7 +526,7 @@ export function renderHtmlReport({
   const designSmells = Array.isArray(depth.designSmells) ? depth.designSmells : [];
   const designWeakBadge =
     designFitness?.designWeak === true
-      ? ` <span class="badge design" title="Edges can be green while lived design residual remains (Shape). Not a FAIL.">design-weak</span>`
+      ? ` <span class="badge design" title="Import rules can be green while leftover design work remains. Not a FAIL.">${LEFTOVER_DESIGN_BADGE}</span>`
       : '';
   const designStripHtml =
     renderDesignDepthStrip({

package/bin/lib/install-migrate.mjs

@@ -80,6 +80,7 @@ import {
   RUNNER_BEFORE_ARK,
 } from './mcp-adoption.mjs';
 import { inspectCodexInstallActivation, printCodexActivationHandoff, reportPartialInstall } from './install-activation.mjs';
+import { installRequestedAgentHomes } from './agent-homes.mjs';
 import {
   hasHardWriteHook,
   validateHardWriteRequest,
@@ -647,6 +648,17 @@ export function runInstallAgentGates(args) {
     }
   }
 
+  installRequestedAgentHomes({
+    root,
+    skills,
+    version,
+    force: args.force,
+    claudeHome: args.claudeHome,
+    grokHome: args.grokHome,
+    agentHomes: args.agentHomes,
+    json: args.json,
+  });
+
   // Optional legacy/home fallback. Normal Codex installs use the project-scoped
   // .codex/config.toml above, avoiding cross-project primary binding conflicts.
   //

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

@@ -6,6 +6,8 @@
  * Plan B stays never mechanical-safe.
  */
 
+import { POST_GREEN_HUMAN } from './product-copy.mjs';
+
 /** Stable product id for JSON / tests. */
 export const POST_GREEN_PATH_ID = 'clarify-for-ai';
 
@@ -16,8 +18,7 @@ export const POST_GREEN_PRIMARY_SKILL = '/ark-explore';
  * Canonical human / agent next-action string (single door).
  * Chained: explore shape-focus then autopilot only to apply B with user OK.
  */
-export const POST_GREEN_PRIMARY_ACTION =
-  'Shape residual (design-weak): edges are clean, design is not finished. Map with /ark-explore shape-focus → dual-plan B; apply B only via /ark-autopilot with your OK. Empty plan A is not done; pattern bets are never mechanical-safe.';
+export const POST_GREEN_PRIMARY_ACTION = POST_GREEN_HUMAN;
 
 /** Short label for tables / metrics. */
 export const POST_GREEN_PRIMARY_SHORT =

package/bin/lib/product-copy.mjs

@@ -0,0 +1,32 @@
+/**
+ * Human-facing product copy (4.6). JSON field names stay stable; this module
+ * owns labels people read in doctor, HTML, and compact router.
+ *
+ * Brands kept: ArkGate, ArkRules. Dialect (design-weak, hard write, …) maps to
+ * common software words. See docs/product-voice.md.
+ */
+
+/** Status-light leftover-design qualifier (was “design-weak”). */
+export const LEFTOVER_DESIGN_LABEL = 'leftover design work';
+
+/**
+ * Operating-mode title for humans (and doctor JSON `designFitness.label` prefix).
+ * @param {string|null|undefined} mode suggest|adapt|enforce
+ * @param {boolean} leftoverDesign
+ */
+export function operatingModeTitle(mode, leftoverDesign) {
+  const light = String(mode || 'enforce').toUpperCase();
+  return leftoverDesign ? `${light} · ${LEFTOVER_DESIGN_LABEL}` : light;
+}
+
+/** Short HTML/doctor badge text. */
+export const LEFTOVER_DESIGN_BADGE = LEFTOVER_DESIGN_LABEL;
+
+export const POST_GREEN_HUMAN =
+  'Imports check out, but the design is still messy. Map leftover work with /ark-explore shape-focus, then apply one small refactor via /ark-autopilot with your OK. A clean import check is not done; pattern bets are never auto-applied.';
+
+export const POST_GREEN_LEDE =
+  'Import rules are clean, but leftover design work remains. That does not fail the check — it only means “done” is still wrong until you tidy shape.';
+
+export const HARD_WRITE_HUMAN = 'pre-write block';
+export const ADVISORY_WRITE_HUMAN = 'warning only (not blocked)';

package/bin/lib/skill-write.mjs

@@ -16,7 +16,7 @@ export const HOME_SKILL_PENDING_CATALOG = '.arkgate-catalog.pending.json';
 const HOME_SKILL_LOCK = '.arkgate-install.lock';
 const HOME_SKILL_CATALOG_SCHEMA = '1.0';
 const HOME_SKILL_LOCK_STALE_MS = 5 * 60 * 1000;
-const HOME_SKILL_LOCK_ATTEMPTS = 100;
+const HOME_SKILL_LOCK_ATTEMPTS = 200;
 const HOME_SKILL_LOCK_RETRY_MS = 25;
 const UUID_PATTERN =
   /^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i;

package/bin/lib/upgrade-whats-new.mjs

@@ -33,6 +33,22 @@ export function buildUpgradeWhatsNewSuggestions() {
     neverGateInput: true,
     title: 'Suggested improvements — try or inspect after this package',
     items: [
+      {
+        id: 'plain-language-doctor',
+        title: 'Doctor in plain language',
+        try: 'npx arkgate-check --doctor',
+        inspect: 'Status light + leftover design work (not a score)',
+        why:
+          'Doctor and the HTML report use common words (import rules, leftover design work, pre-write block). ArkGate and ArkRules stay as product names.',
+      },
+      {
+        id: 'shared-agent-homes',
+        title: 'Shared agent skills (home)',
+        try: 'npx arkgate-check --install-agent-gates --skills-only --agent-homes --force',
+        inspect: 'doctor.agentHomeGaps (Claude/Grok ~/.*/skills when those catalogs exist)',
+        why:
+          'Project skills follow this pin. Shared homes stay on the newest ArkGate on the machine (additive; never downgrade). Orphan 2.x global skills stop coaching the wrong version.',
+      },
       {
         id: 'deep-module-coach',
         title: 'Deep-module coach (hot paths + deepening)',