arkgate 4.7.0 → 4.7.1

package/CHANGELOG.md

@@ -5,6 +5,38 @@ in the immutable pre-2.0 archive linked below.
 
 ## Unreleased
 
+## 4.7.1 — 2026-08-25
+
+**Patch** over **4.7.0**. One project skill catalog, visible package version in the
+skill picker, no home duplicates, ArkRun routed through existing skill names.
+**No required config migration.** Does not close Z09 / K01.
+
+**Status: unpublished** (implementation on `main`; npm `latest` remains **4.7.0** until publish).
+
+### Added
+
+- **Visible skill version (picker):** install stamps `description` with
+  `arkgate@<version>. ` so Codex/Claude/Cursor/Grok show the package pin without
+  opening the file. `arkVersion:` in YAML stays for doctor. Same-body stamp drift
+  refreshes without `--force` (`stamp-refresh`).
+- **`--prune-home-duplicates`:** removes frozen `/ark-*` copies from
+  `$CODEX_HOME/skills`, `~/.claude/skills`, and `~/.grok/skills` when the project
+  already has `.agents/skills`. Never deletes non-Ark skills.
+
+### Changed
+
+- **One project catalog:** `.agents/skills/<name>/SKILL.md` is the byte source.
+  Claude / Grok / OpenCode get relative adapter links. Cursor/Codex/Antigravity
+  already read `.agents/skills` — no second copy. `.cursor/commands/ark-*.md` is
+  no longer written (Cursor listed commands + skills as two copies).
+- **`--codex-home` / `--agent-homes`:** skip home skill write (and home MCP bind)
+  when the project catalog or `.codex/config.toml` already exists. Codex lists
+  user+repo; a home copy is why `/ark-*` appeared twice and stayed old.
+- **Doctor:** when home `ark-*` and project `.agents/skills` both exist, next
+  action is prune, not `--codex-home --force`.
+- **`/ark-contract`:** routes ArkRun extra edits (first extra `/ark-adopt`,
+  companion `/ark-runtime`, new files `/ark-place`). No new skill names.
+
 ## 4.7.0 — 2026-08-25
 
 **Minor** over **4.6.7**. Ships **ArkRun**: an opt-in extra on schema `1.2` for kernel
@@ -12,8 +44,7 @@ usage and complete declarations, plus companion `@arkgate/runtime` DX. Absence i
 silent (Layers / ArkRules verdicts unchanged). In-memory stores remain
 reference-only. **No required config migration.** Does not close Z09 / K01.
 
-**Status: prepared** (see `docs/releases/4.7.0.md`). npm `latest` remains **4.6.7**
-until publish.
+**Status: published** (on npm `latest`; see `docs/releases/4.7.0.md`).
 
 ### Added
 

package/README.md

@@ -16,7 +16,7 @@ and makes sure a “green” check means something real.
 
 </div>
 
-> **ArkGate 4.7.0** is prepared on this tree. **4.6.7** remains npm `latest` until publish.
+> **ArkGate 4.7.0** is on npm `latest`. Optional **ArkRun** extra on schema `1.2`.
 > A tree is **adopted** only with a required GitHub status running `arkgate-check --strict-merge`,
 > or `.ark/adoption-stance.json` `stance: "advisory-only"`. Doctor is compact (`--doctor --all`
 > for Details). [4.7.0 notes](docs/releases/4.7.0.md) · [4.6.7](docs/releases/4.6.7.md) ·
@@ -227,8 +227,8 @@ 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 tree (4.7.0 prepared) | [docs/releases/4.7.0.md](docs/releases/4.7.0.md) · [CHANGELOG](CHANGELOG.md) |
-| Current published (4.6.7 on npm `latest`) | [docs/releases/4.6.7.md](docs/releases/4.6.7.md) |
+| Current published (4.7.0 on npm `latest`) | [docs/releases/4.7.0.md](docs/releases/4.7.0.md) · [CHANGELOG](CHANGELOG.md) |
+| Prior published (4.6.7) | [docs/releases/4.6.7.md](docs/releases/4.6.7.md) |
 | Prior published (4.6.6) | [docs/releases/4.6.6.md](docs/releases/4.6.6.md) |
 | Prior published (4.6.5) | [docs/releases/4.6.5.md](docs/releases/4.6.5.md) |
 | Prior published (4.6.3) | [docs/releases/4.6.3.md](docs/releases/4.6.3.md) |

package/bin/lib/agent-skills-package.mjs

@@ -234,6 +234,35 @@ export function validateAgentSkillsPackage(entries) {
         presentCount: names.length,
     };
 }
+/**
+ * Visible package stamp at the start of Agent Skills `description`.
+ * Hosts show `description` in the picker; `arkVersion:` in YAML is invisible there.
+ * Example: `arkgate@4.7.1. Session 0 — mark the Ark path.`
+ */
+export const ARK_SKILL_DESCRIPTION_VERSION_PATTERN = /^arkgate@(\S+)\.\s/;
+/** Prefix written at install time (`arkgate@<version>. `). */
+export function skillDescriptionVersionPrefix(version) {
+    const v = String(version ?? '').trim();
+    return v ? `arkgate@${v}. ` : '';
+}
+/** Drop a leading `arkgate@<version>. ` stamp; other text is unchanged. */
+export function stripSkillDescriptionVersion(description) {
+    return String(description ?? '').replace(ARK_SKILL_DESCRIPTION_VERSION_PATTERN, '');
+}
+/** Version inside a stamped description, or null when the prefix is absent. */
+export function parseSkillDescriptionVersion(description) {
+    const match = String(description ?? '').match(ARK_SKILL_DESCRIPTION_VERSION_PATTERN);
+    return match?.[1] ?? null;
+}
+/**
+ * Idempotent: replace an existing `arkgate@…` prefix or add one.
+ * Empty `version` strips the prefix (authoring templates stay unversioned).
+ */
+export function stampSkillDescription(description, version) {
+    const rest = stripSkillDescriptionVersion(description);
+    const v = typeof version === 'string' ? version.trim() : '';
+    return v ? `${skillDescriptionVersionPrefix(v)}${rest}` : rest;
+}
 /**
  * Normalize skill file content for identity compare (LF newlines, strip BOM).
  * Does not strip or rewrite frontmatter — Agent Skills export is 1:1 with flat templates.

package/bin/lib/check-args.mjs

@@ -124,6 +124,7 @@ export 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 === '--prune-home-duplicates') args.pruneHomeDuplicates = true;
     else if (arg === '--claude-home') args.claudeHome = true;
     else if (arg === '--grok-home') args.grokHome = true;
     else if (arg === '--agent-homes') {

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

@@ -73,7 +73,11 @@ export function collectDoctorNextActions(ctx) {
   } else if (remStale > 0) {
     actions.push('refresh stale /ark-* skills (--install-agent-gates --skills-only --force) — gates are installed, catalog is stale');
   }
-  if (ctx.codexHomeGap && ctx.codexConcernActive && ctx.codexHomeGap.preferProject !== true) {
+  if (ctx.codexHomeGap && ctx.codexConcernActive && ctx.codexHomeGap.duplicateHome) {
+    actions.push(
+      'remove duplicate Codex home /ark-* skills (project .agents/skills is enough): --install-agent-gates --skills-only --prune-home-duplicates'
+    );
+  } else if (ctx.codexHomeGap && ctx.codexConcernActive && ctx.codexHomeGap.preferProject !== true) {
     actions.push(
       ctx.codexHomeGap.catalogMetadataInvalid
         ? 'repair invalid Codex home catalog metadata after verifying the newest installed version'

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

@@ -200,8 +200,8 @@ export function checkUsageAll() {
     'windsurf, cline, copilot, kiro, roo, continue, gemini',
     '(instruction-tier rule files derived from the same contract).',
     'It also installs the /ark-* skills shipped in templates/skills/ into each',
-    'detected tool\'s command location (.claude/skills/, .cursor/commands/,',
-    '.agents/skills/ (Codex REPO catalog), .grok/skills/, .windsurf/workflows/,',
+    'detected tool\'s command location (.agents/skills/ canonical catalog;',
+    '.claude/skills/ and .grok/skills/ adapters; .windsurf/workflows/,',
     '.clinerules/workflows/, .github/prompts/).',
     'Kiro, Roo, Continue, and Gemini have no command mechanism and receive only their',
     'rule file. Existing files are never overwritten without --force, so re-running',

package/bin/lib/install-migrate.mjs

@@ -68,8 +68,11 @@ import {
   detectSkillGaps,
   arkPackageVersion,
   verifyHostSkillCatalog,
+  canonicalSkillPath,
+  usesCanonicalSkillCatalog,
 } from './skill-install.mjs';
-import { installRepoSkillFile, installSkillCatalog, skillInstallLine, skillInstallNote } from './skill-write.mjs';
+import { applySkillCatalogFollowup } from './skill-catalog-apply.mjs';
+import { installRepoSkillFile, skillInstallNote } from './skill-write.mjs';
 import { detectDeployPathQuality } from './deploy-path.mjs';
 import {
   stripMcpServerArgs,
@@ -80,7 +83,6 @@ 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,
@@ -235,9 +237,18 @@ export function buildManagedAssetCatalog({ root, tools, compact = false, skillsO
   const skills = skillTemplates().map(([name, content]) => [name, stampSkill(content, version)]);
   const skillPaths = new Set();
   if (!compact) {
-    for (const tool of selectedTools) {
+    const skillTools = [...selectedTools].filter((tool) => SKILL_TOOL_TARGETS[tool]);
+    const writeCanonical = skillTools.some((tool) => usesCanonicalSkillCatalog(tool));
+    if (writeCanonical) {
+      for (const [name, content] of skills) {
+        const relativePath = canonicalSkillPath(name);
+        skillPaths.add(relativePath);
+        add(relativePath, content, 'skill');
+      }
+    }
+    for (const tool of skillTools) {
+      if (usesCanonicalSkillCatalog(tool)) continue;
       const target = SKILL_TOOL_TARGETS[tool];
-      if (!target) continue;
       for (const [name, content] of skills) {
         const relativePath = target(name);
         skillPaths.add(relativePath);
@@ -613,60 +624,12 @@ export function runInstallAgentGates(args) {
     console.log(`    ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --force')}`);
   }
 
-  // --codex-home writes SKILL.md skills to $CODEX_HOME/skills/<name>/SKILL.md.
-  // Codex's real catalog loads skill directories (not flat $CODEX_HOME/prompts).
-  // Repo installs already write `.agents/skills/<name>/SKILL.md` when `codex` is
-  // selected; home install is for multi-project / non-repo-local refresh.
-  const homeResults = [];
-  if (args.codexHome) {
-    const dir = codexSkillsDir();
-    console.log('');
-    console.log(
-      `Codex home skills (scope=home-shared; source=${version ? `arkgate@${version}` : 'arkgate@unknown'}; target=${dir}/<name>/SKILL.md):`
-    );
-    console.log(
-      '  Compatibility: monotonic downgrade protection requires every shared-catalog writer ' +
-        'to use ArkGate 4.2.0+; pre-4.2 --codex-home ignores this catalog. Upgrade legacy repos first.'
-    );
-    try {
-      fs.mkdirSync(dir, { recursive: true });
-    } catch (error) {
-      console.error(`  FAILED to create ${dir} (${error.message})`);
-      homeResults.push({ relativePath: dir, status: 'failed' });
-    }
-    if (homeResults.length === 0) {
-      const skillName = (skill) =>
-        Array.isArray(skill) ? skill[0] : skill?.name || skill;
-      const projectHasCatalog = skills.some((skill) =>
-        fs.existsSync(path.join(root, '.agents', 'skills', skillName(skill), 'SKILL.md'))
-      );
-      if (projectHasCatalog) {
-        console.log(
-          '  Project .agents/skills already has this catalog; home write is optional. Prefer the project copy.'
-        );
-      }
-      for (const result of installSkillCatalog({
-        directory: dir,
-        skills,
-        packageVersion: version,
-        force: args.force,
-        scope: 'home',
-      })) {
-        console.log(skillInstallLine(result));
-        homeResults.push(result);
-      }
-    }
-  }
-
-  installRequestedAgentHomes({
+  const { skillNames, homeResults } = applySkillCatalogFollowup({
     root,
+    tools,
     skills,
     version,
-    force: args.force,
-    claudeHome: args.claudeHome,
-    grokHome: args.grokHome,
-    agentHomes: args.agentHomes,
-    json: args.json,
+    args,
   });
 
   // Optional legacy/home fallback. Normal Codex installs use the project-scoped
@@ -679,8 +642,10 @@ export function runInstallAgentGates(args) {
   // A redirected CODEX_HOME (tests/isolation) may still wire as requested.
   let codexMcp = null;
   const wantCodexWire = !args.compact && !args.skillsOnly && args.codexHome;
+  const projectCodexMcp = fs.existsSync(path.join(root, '.codex', 'config.toml'));
   const skipHomeWire =
-    wantCodexWire && isTempOrUpgradeRoot(root) && usesDefaultCodexHome();
+    wantCodexWire &&
+    ((isTempOrUpgradeRoot(root) && usesDefaultCodexHome()) || projectCodexMcp);
   if (wantCodexWire && !skipHomeWire) {
     codexMcp = wireCodexMcp(root, args.force);
     console.log('');
@@ -702,7 +667,14 @@ export function runInstallAgentGates(args) {
       );
     }
   } else if (skipHomeWire) {
-    codexMcp = { status: 'skipped', file: codexConfigPath(), reason: 'temp-root' };
+    const reason = projectCodexMcp ? 'project-config' : 'temp-root';
+    codexMcp = { status: 'skipped', file: codexConfigPath(), reason };
+    if (projectCodexMcp && !args.json) {
+      console.log('');
+      console.log(
+        'Skip Codex home MCP — project .codex/config.toml is the binding. Home config pointing at another checkout is leftover; do not rebind it from this install.'
+      );
+    }
   }
 
   const { codexProjectConfigured, runtimeActivation } =

package/bin/lib/managed-upgrade.mjs

@@ -126,13 +126,8 @@ function hasArkText(root, relativePath) {
 
 const HOST_SIGNALS = {
   claude: ['.claude/settings.json', '.claude/skills/ark-upgrade/SKILL.md'],
-  cursor: [
-    '.cursor/mcp.json',
-    '.cursor/hooks.json',
-    '.cursor/rules/ark.mdc',
-    '.cursor/commands/ark-upgrade.md',
-  ],
-  codex: ['.codex/hooks.json', '.codex/config.toml', '.agents/skills/ark-upgrade/SKILL.md'],
+  cursor: ['.cursor/mcp.json', '.cursor/hooks.json', '.cursor/rules/ark.mdc'],
+  codex: ['.codex/hooks.json', '.codex/config.toml'],
   grok: ['.grok/config.toml', '.grok/hooks/ark-write-gate.json', '.grok/skills/ark-upgrade/SKILL.md'],
   antigravity: ['.agents/hooks.json'],
   opencode: ['opencode.json', '.opencode/skills/ark-upgrade/SKILL.md'],

package/bin/lib/skill-catalog-apply.mjs

@@ -0,0 +1,126 @@
+/**
+ * HS post-write skill catalog: adapters, home skip/prune, Claude/Grok home skip.
+ * Kept out of install-migrate so that file stays inside its module budget.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { arkCommand } from '../ark-shared.mjs';
+import { installRequestedAgentHomes } from './agent-homes.mjs';
+import { codexSkillsDir } from './codex-home.mjs';
+import {
+  canonicalSkillPath,
+  linkSkillHostAdapters,
+  pruneHomeArkSkillDuplicates,
+  skillTemplateNames,
+} from './skill-install.mjs';
+import { installSkillCatalog, skillInstallLine } from './skill-write.mjs';
+
+function skillName(skill) {
+  return Array.isArray(skill) ? skill[0] : skill?.name || skill;
+}
+
+export function projectCatalogReady(root, skillNames) {
+  return skillNames.some((name) => fs.existsSync(path.join(root, canonicalSkillPath(name))));
+}
+
+export function applySkillCatalogFollowup({
+  root,
+  tools,
+  skills,
+  version,
+  args,
+}) {
+  const skillNames = skills.map(skillName);
+  if (!args.compact && skillNames.length > 0) {
+    const adapterResults = linkSkillHostAdapters(root, tools, skillNames, Boolean(args.force));
+    for (const row of adapterResults) {
+      if (row.status === 'linked' || row.status === 'copied') {
+        console.log(
+          `  ${row.status.padEnd(7)} ${row.relativePath}  (adapter → .agents/skills/${row.name})`
+        );
+      }
+    }
+  }
+  if (args.pruneHomeDuplicates) {
+    const pruned = pruneHomeArkSkillDuplicates(
+      root,
+      skillNames.length ? skillNames : skillTemplateNames()
+    );
+    if (!pruned.ok) {
+      console.log('  skip    --prune-home-duplicates (no project .agents/skills catalog yet)');
+    } else if (pruned.removed.length === 0) {
+      console.log('  skip    --prune-home-duplicates (no home ark-* copies)');
+    } else {
+      console.log(`  pruned  ${pruned.removed.length} home ark-* path(s) (project catalog is enough)`);
+    }
+  }
+
+  const homeResults = [];
+  if (args.codexHome) {
+    const dir = codexSkillsDir();
+    console.log('');
+    console.log(
+      `Codex home skills (scope=home-shared; source=${version ? `arkgate@${version}` : 'arkgate@unknown'}; target=${dir}/<name>/SKILL.md):`
+    );
+    console.log(
+      '  Compatibility: monotonic downgrade protection requires every shared-catalog writer ' +
+        'to use ArkGate 4.2.0+; pre-4.2 --codex-home ignores this catalog. Upgrade legacy repos first.'
+    );
+    try {
+      fs.mkdirSync(dir, { recursive: true });
+    } catch (error) {
+      console.error(`  FAILED to create ${dir} (${error.message})`);
+      homeResults.push({ relativePath: dir, status: 'failed' });
+    }
+    if (homeResults.length === 0) {
+      const hasCatalog = skills.some((skill) =>
+        fs.existsSync(path.join(root, '.agents', 'skills', skillName(skill), 'SKILL.md'))
+      );
+      if (hasCatalog) {
+        console.log(
+          '  Skip home write — project .agents/skills is the catalog. Codex lists user+repo; a home copy duplicates every /ark-*.'
+        );
+        console.log(
+          `  Remove leftover home copies: ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --prune-home-duplicates')}`
+        );
+      } else {
+        for (const result of installSkillCatalog({
+          directory: dir,
+          skills,
+          packageVersion: version,
+          force: args.force,
+          scope: 'home',
+        })) {
+          console.log(skillInstallLine(result));
+          homeResults.push(result);
+        }
+      }
+    }
+  }
+
+  const catalogReady = projectCatalogReady(root, skillNames);
+  if ((args.claudeHome || args.grokHome || args.agentHomes) && catalogReady) {
+    if (!args.json) {
+      console.log('');
+      console.log(
+        'Skip Claude/Grok home skill write — project .agents/skills + adapters are the catalog. Home ark-* copies override or duplicate.'
+      );
+      console.log(
+        `  Remove leftover home copies: ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --prune-home-duplicates')}`
+      );
+    }
+  } else {
+    installRequestedAgentHomes({
+      root,
+      skills,
+      version,
+      force: args.force,
+      claudeHome: args.claudeHome,
+      grokHome: args.grokHome,
+      agentHomes: args.agentHomes,
+      json: args.json,
+    });
+  }
+
+  return { skillNames, homeResults };
+}