axstack 0.20.3 → 0.20.5

package/README.md

@@ -56,6 +56,11 @@ axstack check --harness codex
 axstack install --harness codex --preset mixed --yes
 ```
 
+Codex skills default to the shared `~/.agents/skills` root while its owned
+`AGENTS.md` block stays under `$CODEX_HOME` (default `~/.codex`). A default
+install safely retires only unchanged manifest-owned legacy Axstack skills;
+use `--skills-dir` for an explicit target without automatic migration.
+
 Then open an Orca chat and ask for the relevant skill:
 
 ```text

package/bin/axstack.js

@@ -8,6 +8,8 @@ import { join, resolve } from '../src/posixpath.js';
 import {
   checkInstructionBinding,
   installBundle,
+  readLegacySkillsManifest,
+  retireLegacySkills,
   uninstallBundle,
   validateBundle,
 } from '../src/installer.js';
@@ -57,7 +59,8 @@ Flags:
                       profiles/presets/*.json role data. Defaults to the package root.
   --preset <name>     Required routing preset: mixed, codex-only, or claude-only.
                       Aliases: codex = codex-only; claude = claude-only.
-  --skills-dir <dir>  Explicit install target (required). Overrides --harness.
+  --skills-dir <dir>  Explicit install target. Overrides harness skill defaults
+                      and automatic legacy Codex skill retirement.
   --instructions <file>
                       Instruction file to receive the owned routing block.
                       Harness defaults: ~/.claude/CLAUDE.md for Claude,
@@ -71,6 +74,8 @@ Flags:
                       Skip Claude Code user-settings management.
   --harness <name>    Known harness (${harnessLocations().map((h) => h.harness).join(', ')}).
                       Grok has no verified auto-discovery: --skills-dir is required.
+                      Codex skills default to ~/.agents/skills; CODEX_HOME
+                      continues to select its AGENTS.md configuration home.
   --force             Overwrite/remove user-edited owned assets and take
                       ownership of unknown files. Off by default.
   --yes               Confirm writes inside your home directory. Temp dirs
@@ -203,13 +208,20 @@ function resolveHarnessTarget(harness) {
     );
   }
   if (entry.harness === 'codex') {
-    // User skills live under $CODEX_HOME/skills; CODEX_HOME defaults to ~/.codex.
-    const home = Bun.env.CODEX_HOME ? expandHome(Bun.env.CODEX_HOME) : join(homeDir(), '.codex');
-    return join(home, 'skills');
+    // Axstack uses Codex's shared user-skill root. CODEX_HOME remains the
+    // configuration home for AGENTS.md, not an Axstack skill destination.
+    return join(homeDir(), '.agents', 'skills');
   }
   return expandHome(entry.skillsDir);
 }
 
+function legacyCodexSkillsTarget() {
+  const codexHome = Bun.env.CODEX_HOME
+    ? expandHome(Bun.env.CODEX_HOME)
+    : join(homeDir(), '.codex');
+  return join(codexHome, 'skills');
+}
+
 function resolveHarnessInstructions(harness) {
   if (harness === 'claude') return join(homeDir(), '.claude', 'CLAUDE.md');
   if (harness === 'codex') {
@@ -278,18 +290,45 @@ async function main() {
         : flags.harness
           ? resolveHarnessInstructions(flags.harness)
           : null;
+      const usesCodexDefault = flags.harness === 'codex' && !flags['skills-dir'];
+      const legacyCodexDir = usesCodexDefault ? legacyCodexSkillsTarget() : null;
+      const legacyCodexManifest = legacyCodexDir
+        ? await readLegacySkillsManifest(legacyCodexDir)
+        : null;
       const summary = await installBundle({
         bundleDir: flags.bundle ? resolve(flags.bundle) : PACKAGE_ROOT,
         skillsDir,
         preset: flags.preset,
         instructionsPath,
+        inheritedInstructions: legacyCodexManifest?.instructions,
         force: !!flags.force,
         yes: !!flags.yes,
         claude: resolveClaudeOption(flags, 'install'),
         log: (m) => { if (m !== 'plan complete') console.log(m); },
       });
+      const migrationReady = summary.instructions?.status !== 'conflict' &&
+        summary.roles?.ready !== false && summary.ownershipComplete;
+      if (usesCodexDefault && migrationReady) {
+        try {
+          summary.legacyCodex = await retireLegacySkills({
+            canonicalSkillsDir: skillsDir,
+            legacySkillsDir: legacyCodexDir,
+            acceptedInstructionTransfer: summary.acceptedInstructionTransfer,
+            yes: !!flags.yes,
+          });
+        } catch (err) {
+          summary.legacyCodex = {
+            removed: [], preserved: [], missing: [], skipped: false,
+            failed: true,
+            reason: `legacy Codex skills not retired: ${err.message}`,
+          };
+        }
+      } else if (usesCodexDefault) {
+        summary.legacyCodex = { removed: [], preserved: [], missing: [], held: true };
+      }
       const changed =
         summary.added.length + summary.updated.length + summary.removed.length +
+        (summary.legacyCodex?.removed.length ?? 0) +
         (['created', 'updated'].includes(summary.instructions?.status) ? 1 : 0);
       if (changed === 0) {
         console.log('Install complete: no changes (idempotent, everything unchanged).');
@@ -303,6 +342,31 @@ async function main() {
         console.log(`preserved user edits (use --force to overwrite): ${summary.preserved.join(', ')}`);
       }
       if (summary.stale.length) console.log(`stale owned files left on disk: ${summary.stale.join(', ')}`);
+      if (summary.legacyCodex && !summary.legacyCodex.skipped) {
+        if (summary.legacyCodex.held) {
+          console.log(
+            `legacy Codex skills preserved (retirement held): ${summary.legacyCodex.reason ?? 'canonical install has an unresolved conflict'}`,
+          );
+          if (summary.legacyCodex.failure) process.exitCode = 1;
+        }
+        if (summary.legacyCodex.failed) {
+          console.log(
+            `canonical install completed; legacy retirement failed: ${summary.legacyCodex.reason}`,
+          );
+          process.exitCode = 1;
+        }
+        if (summary.legacyCodex.removed.length) {
+          console.log(`legacy Codex skills retired: ${summary.legacyCodex.removed.join(', ')}`);
+        }
+        if (summary.legacyCodex.preserved.length) {
+          console.log(
+            `legacy Codex skills preserved (modified; resolve manually): ${summary.legacyCodex.preserved.join(', ')}`,
+          );
+        }
+        if (summary.legacyCodex.missing.length) {
+          console.log(`legacy Codex manifest entries already missing: ${summary.legacyCodex.missing.join(', ')}`);
+        }
+      }
       if (summary.instructions) {
         const i = summary.instructions;
         if (i.status === 'conflict') {

package/docs/installation.md

@@ -24,6 +24,8 @@ axstack install --preset <mixed|codex-only|claude-only> --bundle <dir> --skills-
 - `--bundle` defaults to the package root and contains `skills/` plus
   `profiles/presets/*.json`.
 - `--skills-dir` is required unless a verified harness default resolves it.
+  Codex defaults to the shared `~/.agents/skills` root; an explicit override
+  remains authoritative and disables automatic legacy Codex-root retirement.
 - `--instructions` selects the instruction file that receives Axstack's owned
   marker block. `--harness claude` defaults to `~/.claude/CLAUDE.md`;
   `--harness codex` defaults to `$CODEX_HOME/AGENTS.md` or `~/.codex/AGENTS.md`;
@@ -34,6 +36,23 @@ axstack install --preset <mixed|codex-only|claude-only> --bundle <dir> --skills-
   reads `~/.claude/skills`, so its own directory is only needed for the owned
   routing block; Antigravity (IDE and `agy` CLI) reads `~/.gemini/config/skills`
   only.
+
+For a default Codex install, Axstack first installs and verifies the canonical
+`~/.agents/skills` copy. It then retires only unchanged files owned by the
+legacy `$CODEX_HOME/skills/.axstack-manifest.json`. Modified, missing, unowned,
+or symlinked content is preserved or refused and reported; an instruction
+conflict preserves the complete legacy install. An unchanged owned Codex
+`AGENTS.md` binding is transferred to the canonical manifest without changing
+the instruction bytes. Other harness ownership, settings, and inert profile
+provenance remain untouched. Repeated installs verify the same canonical
+preset and converge without duplicate skill entries.
+
+If retirement leaves only the legacy manifest's Claude-settings ownership,
+first confirm its `files` map is empty and it has no instruction or profile
+conflict. Then finish that owner with
+`axstack uninstall --skills-dir "${CODEX_HOME:-$HOME/.codex}/skills" --yes`;
+the settings sidecar preserves the value while any other install still owns it.
+
 - `--claude-settings` and `--no-claude-settings` control the existing Claude
   Code subagent-default transaction. They do not configure Orca roles.
 - `--force` may replace an edited owned asset; it never adopts or removes
@@ -197,7 +216,7 @@ survives.
 | Harness | Default directory | Status |
 | --- | --- | --- |
 | Claude | `~/.claude/skills` | documented upstream |
-| Codex | `$CODEX_HOME/skills` (default `~/.codex/skills`) | documented upstream |
+| Codex | `~/.agents/skills` | documented upstream |
 | OpenCode | `~/.config/opencode/skills` | documented upstream |
 | Antigravity | `~/.gemini/config/skills` | documented upstream |
 | Grok | explicit `--skills-dir` only | auto-discovery unverified |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "axstack",
-  "version": "0.20.3",
+  "version": "0.20.5",
   "description": "Axstack installer and setup CLI: installs owned chat skills and role data, configures supported harness settings, and checks Orca capabilities.",
   "keywords": [
     "claude-code",

package/skills/axstack/references/automations.md

@@ -66,7 +66,17 @@ intent alone is insufficient. Conversely a completed run row does not prove exit
 If these facts remain unknown, report the hold at the durable decision location;
 do not silently stand down forever or replace a potentially live owner.
 
-Before PR admission, reconcile old pass resources. If three or more unreclaimed
+Before PR admission, reconcile old pass resources and reclaim every safely
+removable earlier pass workspace under the retirement guards below. This is
+routine cleanup on every admitted pass; do not wait for the three-workspace
+threshold to start cleanup. Save confirmed exit and ownership-release receipts
+before removing each workspace. Preserve dirty, unpushed, evidence-bearing,
+user-owned, active, or uncertain resources; the threshold never relaxes these guards.
+Explicitly classified evidence may cease to block cleanup only after the
+[private evidence archive](evidence-archive.md) is verified and its receipt is
+read back from durable continuity. This never makes other dirt disposable.
+After cleanup, re-list and count only the earlier pass workspaces still remaining.
+If three or more unreclaimed
 earlier pass workspaces remain, disable only this automation through the native
 CLI, verify the disabled setting, save/report the cleanup hold, and admit no new
 PR jobs. Also pause on a confirmed cleanup failure or unresolved lane ownership.
@@ -146,12 +156,14 @@ publication receipt, hold, and next action. GitHub remains authoritative for
 open state, revisions, reviews, checks, and merge state.
 
 When the current event is handled, settle and release owned native resources.
-Preserve dirty worktrees, unpushed candidates, review evidence, pending
+Preserve dirty worktrees, unpushed candidates, unarchived review evidence, pending
 external results, and user-owned work until durability and ownership are
 proven. Unknown liveness, `user_takeover`, and ambiguous publication likewise
 forbid cleanup. Here a pending external result means an unconfirmed publication
 or send outcome, not pending CI. Waiting state belongs in GitHub and the compact
 record, never in an idle model, per-PR timer, or polling loop.
+Follow the [private evidence archive](evidence-archive.md) when evidence is the
+only local state to preserve; archive success does not relax any other guard.
 
 ## Review and repair authority
 
@@ -216,8 +228,11 @@ self-close. Waiting PRs still occupy zero slots once their owned trees settle.
 
 Cleanup of PR-job setup shells stays scoped to positively identified owned unused
 setup shells: use the native exact-terminal close operation for each only.
-Preserve dirty worktrees, unpushed candidates, review evidence, user-owned
+Preserve dirty worktrees, unpushed candidates, unarchived review evidence, user-owned
 terminals, unknown liveness, `user_takeover`, and ambiguous publication state.
+Never classify all dirt as evidence. If explicitly classified evidence is the
+last retention reason, apply and verify the [private evidence archive](evidence-archive.md),
+update durable continuity, and read it back before native retirement.
 
 For the manager pass only, verify native run/workspace identity, exclusive
 automation ownership, no unsettled descendants, and a fresh terminal inventory
@@ -235,9 +250,12 @@ A failed or uncertain close is not proof of retirement. The next admitted pass
 reconciles prior retirement from native state before trusting saved intent.
 Retire only positively identified completed pass resources; do not kill another
 live or unknown manager. Remove an old pass worktree only with native cleanup
-after terminal retirement is confirmed and its Git state is clean, with no
-unpushed commits, retained evidence, children, or user-owned work. Never use
-recursive shell deletion. Failed cleanup remains recorded, not silently forgotten.
+after terminal retirement is confirmed and it has no unpushed commits,
+unarchived evidence, children, user-owned work, unknown files, or unexplained
+dirty source. A verified evidence archive does not require otherwise clean Git
+state, but every remaining change must still be positively classified and safe;
+unknown dirt blocks removal. Never use recursive shell deletion. Failed cleanup
+remains recorded, not silently forgotten.
 
 The activation canary must additionally prove distinct workspace IDs per pass,
 cross-workspace lane admission, self-retirement and absence after client reconnect,

package/skills/axstack/references/evidence-archive.md

@@ -0,0 +1,68 @@
+# Private evidence archive
+
+Use this only when local review or coordinator evidence is the last reason a
+finished automation-owned worktree cannot be retired. It archives evidence; it
+never decides that a terminal or worktree is safe to remove and never performs
+native cleanup.
+
+## Eligibility
+
+First prove the exact repository, PR, 40-character head SHA, Task/Dispatch,
+workspace, terminal incarnation, automation ownership, descendant settlement,
+and liveness from current native state. A manual chat, `user_takeover`, an
+active or unknown task terminal, an unsettled descendant, unpushed commits,
+dirty source, ambiguous publication, or an unknown file remains protected.
+
+Classify each evidence file explicitly. Do not equate a dirty worktree with
+disposable evidence, archive a whole worktree, or copy source changes as a way
+to authorize deletion. Evidence may be archived while unrelated protected state
+continues to block cleanup.
+
+## Archive and verify
+
+Choose a configured absolute private archive root outside every disposable
+worktree and outside public Orca artifacts. The root must be owned for this
+purpose and inaccessible to group/other users. From the installed `axstack`
+skill directory, run:
+
+```sh
+bun scripts/archive-evidence.js \
+  --source-root <absolute-worktree-or-evidence-root> \
+  --archive-root <absolute-private-archive-root> \
+  --repo <owner/repository> --pr <number> --head <40-character-sha> \
+  --dispatch <exact-dispatch-id> \
+  --file <classified-relative-file> [--file <classified-relative-file> ...]
+```
+
+The helper refuses path escapes, symlinks, non-private archive directories,
+identity changes, and existing content that does not verify. It copies only the
+listed regular files, writes them with private permissions, hashes their exact
+bytes, and emits a JSON receipt containing the archive directory, manifest path,
+manifest hash, and file count. Repeating the same command verifies the immutable
+archive and returns the same receipt; it does not overwrite it.
+
+Record the receipt plus the exact repo/PR/head/Task/Dispatch/workspace/terminal
+identities in durable lane continuity, then read the continuity and archive
+manifest back before cleanup. If either readback differs or is unavailable,
+preserve the worktree.
+
+## Native retirement
+
+Retire descendants before their parent. For each positively identified unused
+setup shell, use the native exact-terminal close operation, then re-list native
+state and require exit proof for that exact terminal incarnation. A task
+terminal, manual chat, unexpected terminal, failed close, or uncertain exit
+remains protected.
+
+After receipt and continuity readback, if the only remaining Git dirt is the
+verified archived untracked evidence, compare its current bytes with the
+manifest again and unlink only those exact regular evidence files individually.
+Never remove tracked or unknown files, directories, or any path whose hash now
+differs. Re-read Git and native state; any remaining or uncertain dirt holds
+retirement.
+
+Only then use the version-matched Orca guide's native worktree cleanup operation
+with the exact workspace identity. Never use shell recursive deletion and never
+treat archive success as ownership, settlement, exit, or cleanup proof. Record
+and verify native absence before advancing continuity; failure or uncertainty
+preserves the resource.

package/skills/axstack/scripts/archive-evidence.js

@@ -0,0 +1,298 @@
+#!/usr/bin/env bun
+import {
+  chmod,
+  lstat,
+  mkdir,
+  readdir,
+  readFile,
+  rename,
+  rm,
+  writeFile,
+} from 'node:fs/promises';
+
+function isAbsolute(path) {
+  return path.startsWith('/');
+}
+
+function normalize(path) {
+  const absolute = isAbsolute(path);
+  const parts = [];
+  for (const part of path.split('/')) {
+    if (!part || part === '.') continue;
+    if (part === '..') {
+      if (parts.length > 0) parts.pop();
+    } else parts.push(part);
+  }
+  const normalized = `${absolute ? '/' : ''}${parts.join('/')}`;
+  return normalized || (absolute ? '/' : '.');
+}
+
+function join(...parts) {
+  return normalize(parts.filter(Boolean).join('/'));
+}
+
+function resolve(...parts) {
+  let path = '';
+  for (let i = parts.length - 1; i >= 0; i -= 1) {
+    path = `${parts[i]}${path ? `/${path}` : ''}`;
+    if (isAbsolute(parts[i])) return normalize(path);
+  }
+  return normalize(`${process.cwd()}/${path}`);
+}
+
+function dirname(path) {
+  const normalized = normalize(path);
+  if (normalized === '/') return '/';
+  const index = normalized.lastIndexOf('/');
+  if (index < 0) return '.';
+  return index === 0 ? '/' : normalized.slice(0, index);
+}
+
+function relative(from, to) {
+  const fromParts = resolve(from).split('/').filter(Boolean);
+  const toParts = resolve(to).split('/').filter(Boolean);
+  let common = 0;
+  while (fromParts[common] === toParts[common] && common < fromParts.length) common += 1;
+  return [...Array(fromParts.length - common).fill('..'), ...toParts.slice(common)].join('/');
+}
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function parseArgs(argv) {
+  const values = { files: [] };
+  for (let i = 0; i < argv.length; i += 2) {
+    const flag = argv[i];
+    const value = argv[i + 1];
+    if (!flag?.startsWith('--') || value === undefined) fail(`invalid argument near ${flag ?? '(end)'}`);
+    const key = flag.slice(2);
+    if (key === 'file') values.files.push(value);
+    else if (['source-root', 'archive-root', 'repo', 'pr', 'head', 'dispatch'].includes(key)) {
+      if (values[key] !== undefined) fail(`duplicate --${key}`);
+      values[key] = value;
+    } else fail(`unknown argument: ${flag}`);
+  }
+  for (const key of ['source-root', 'archive-root', 'repo', 'pr', 'head', 'dispatch']) {
+    if (!values[key]) fail(`missing --${key}`);
+  }
+  if (values.files.length === 0) fail('at least one --file is required');
+  if (!isAbsolute(values['source-root']) || !isAbsolute(values['archive-root'])) {
+    fail('source and archive roots must be absolute');
+  }
+  if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(values.repo)) fail('repo must be owner/name');
+  if (!/^[1-9][0-9]*$/.test(values.pr)) fail('pr must be a positive integer');
+  if (!/^[0-9a-f]{40}$/.test(values.head)) fail('head must be an exact 40-character lowercase SHA');
+  if (!/^[A-Za-z0-9_-]+$/.test(values.dispatch)) fail('dispatch contains unsafe characters');
+  values.files = [...new Set(values.files)].sort();
+  for (const file of values.files) {
+    const parts = file.split('/');
+    if (!file || isAbsolute(file) || parts.some((part) => !part || part === '.' || part === '..') || file.includes('\0')) {
+      fail(`unsafe evidence path: ${file || '(empty)'}`);
+    }
+  }
+  return values;
+}
+
+async function assertRealPath(path, expectedType) {
+  const st = await lstat(path).catch((err) => {
+    if (err?.code === 'ENOENT') return null;
+    throw err;
+  });
+  if (!st) fail(`missing ${expectedType}: ${path}`);
+  if (st.isSymbolicLink()) fail(`refusing symlink: ${path}`);
+  if (expectedType === 'directory' && !st.isDirectory()) fail(`not a directory: ${path}`);
+  if (expectedType === 'file' && !st.isFile()) fail(`not a regular file: ${path}`);
+  return st;
+}
+
+async function assertNoSymlinkComponents(root, rel) {
+  let current = root;
+  for (const part of rel.split('/')) {
+    current = join(current, part);
+    const st = await assertRealPath(current, current === join(root, rel) ? 'file' : 'directory');
+    if (st.isSymbolicLink()) fail(`refusing symlink: ${current}`);
+  }
+}
+
+async function assertSafeAncestors(path) {
+  const absolute = resolve(path);
+  let current = '/';
+  for (const part of absolute.split('/').filter(Boolean)) {
+    current = join(current, part);
+    const st = await lstat(current).catch((err) => {
+      if (err?.code === 'ENOENT') return null;
+      throw err;
+    });
+    if (!st) break;
+    if (st.isSymbolicLink()) fail(`refusing symlink path component: ${current}`);
+  }
+}
+
+async function ensurePrivateDir(path) {
+  const st = await lstat(path).catch((err) => {
+    if (err?.code === 'ENOENT') return null;
+    throw err;
+  });
+  if (st) {
+    if (st.isSymbolicLink() || !st.isDirectory()) fail(`unsafe archive directory: ${path}`);
+    if ((st.mode & 0o077) !== 0) fail(`archive directory must have private 0700 permissions: ${path}`);
+    return;
+  }
+  await mkdir(path, { mode: 0o700 });
+  await chmod(path, 0o700);
+}
+
+function sha256(bytes) {
+  const hasher = new Bun.CryptoHasher('sha256');
+  hasher.update(bytes);
+  return hasher.digest('hex');
+}
+
+async function collectSource(sourceRoot, files) {
+  await assertRealPath(sourceRoot, 'directory');
+  const collected = {};
+  for (const rel of files) {
+    await assertNoSymlinkComponents(sourceRoot, rel);
+    const bytes = await readFile(join(sourceRoot, rel));
+    collected[rel] = { bytes, sha256: sha256(bytes), size: bytes.length };
+  }
+  return collected;
+}
+
+function manifestBytes(identity, collected) {
+  const files = {};
+  for (const rel of Object.keys(collected).sort()) {
+    files[rel] = { sha256: collected[rel].sha256, size: collected[rel].size };
+  }
+  return Buffer.from(JSON.stringify({ version: 1, identity, files }, null, 2) + '\n');
+}
+
+async function verifyArchive(archiveDir, identity, collected) {
+  const archiveStat = await assertRealPath(archiveDir, 'directory');
+  if ((archiveStat.mode & 0o077) !== 0) fail(`archive permissions are not private: ${archiveDir}`);
+  const filesRoot = join(archiveDir, 'files');
+  const filesStat = await assertRealPath(filesRoot, 'directory');
+  if ((filesStat.mode & 0o077) !== 0) fail(`archive permissions are not private: ${filesRoot}`);
+  const manifestPath = join(archiveDir, 'manifest.json');
+  const expectedManifest = manifestBytes(identity, collected);
+  const actualManifest = await readFile(manifestPath);
+  if (!actualManifest.equals(expectedManifest)) fail(`archive manifest mismatch: ${manifestPath}`);
+  if (((await assertRealPath(manifestPath, 'file')).mode & 0o077) !== 0) {
+    fail(`archive manifest permissions are not private: ${manifestPath}`);
+  }
+  for (const [rel, expected] of Object.entries(collected)) {
+    const archived = join(archiveDir, 'files', rel);
+    await assertNoSymlinkComponents(filesRoot, rel);
+    const st = await assertRealPath(archived, 'file');
+    if ((st.mode & 0o077) !== 0) fail(`archived evidence permissions are not private: ${archived}`);
+    if (sha256(await readFile(archived)) !== expected.sha256) fail(`archived evidence hash mismatch: ${rel}`);
+  }
+  const actualFiles = await listArchiveFiles(archiveDir);
+  const expectedFiles = ['manifest.json', ...Object.keys(collected).map((rel) => `files/${rel}`)].sort();
+  if (JSON.stringify(actualFiles) !== JSON.stringify(expectedFiles)) {
+    fail(`archive contains unexpected or missing files: ${archiveDir}`);
+  }
+  return {
+    archiveDir,
+    manifestPath,
+    manifestHash: sha256(actualManifest),
+    files: Object.keys(collected).length,
+  };
+}
+
+async function listArchiveFiles(root, prefix = '') {
+  const files = [];
+  const entries = await readdir(join(root, prefix), { withFileTypes: true });
+  entries.sort((a, b) => a.name.localeCompare(b.name));
+  for (const entry of entries) {
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    const st = await lstat(join(root, rel));
+    if (st.isSymbolicLink()) fail(`refusing symlink in archive: ${rel}`);
+    if (st.isDirectory()) files.push(...await listArchiveFiles(root, rel));
+    else if (st.isFile()) files.push(rel);
+    else fail(`unexpected archive entry: ${rel}`);
+  }
+  return files.sort();
+}
+
+async function main() {
+  const args = parseArgs(Bun.argv.slice(2));
+  const sourceRoot = resolve(args['source-root']);
+  const archiveRoot = resolve(args['archive-root']);
+  const sourceToArchive = relative(sourceRoot, archiveRoot);
+  const archiveToSource = relative(archiveRoot, sourceRoot);
+  if (
+    sourceToArchive === '' || (!sourceToArchive.startsWith('..') && !isAbsolute(sourceToArchive)) ||
+    archiveToSource === '' || (!archiveToSource.startsWith('..') && !isAbsolute(archiveToSource))
+  ) fail('source and archive roots must not contain each other');
+
+  const collected = await collectSource(sourceRoot, args.files);
+  const identity = {
+    repo: args.repo,
+    pr: Number(args.pr),
+    head: args.head,
+    dispatch: args.dispatch,
+  };
+  const repoSlug = args.repo.replace('/', '--');
+  const archiveDir = join(archiveRoot, repoSlug, `pr-${args.pr}`, args.head, args.dispatch);
+
+  await assertSafeAncestors(archiveRoot);
+  let current = archiveRoot;
+  const generated = [repoSlug, `pr-${args.pr}`, args.head];
+  await ensurePrivateDir(current);
+  for (const part of generated) {
+    current = join(current, part);
+    await ensurePrivateDir(current);
+  }
+  const existing = await lstat(archiveDir).catch((err) => {
+    if (err?.code === 'ENOENT') return null;
+    throw err;
+  });
+  if (existing) {
+    if (existing.isSymbolicLink() || !existing.isDirectory()) fail(`unsafe existing archive: ${archiveDir}`);
+    const receipt = await verifyArchive(archiveDir, identity, collected);
+    console.log(JSON.stringify({ status: 'verified', ...receipt }));
+    return;
+  }
+
+  const tempDir = `${archiveDir}.tmp-${process.pid}`;
+  if (await lstat(tempDir).catch((err) => err?.code === 'ENOENT' ? null : Promise.reject(err))) {
+    fail(`temporary archive already exists: ${tempDir}`);
+  }
+  await mkdir(join(tempDir, 'files'), { recursive: true, mode: 0o700 });
+  await chmod(tempDir, 0o700);
+  await chmod(join(tempDir, 'files'), 0o700);
+  try {
+    for (const [rel, entry] of Object.entries(collected)) {
+      const dest = join(tempDir, 'files', rel);
+      const parent = dirname(dest);
+      await mkdir(parent, { recursive: true, mode: 0o700 });
+      let cursor = join(tempDir, 'files');
+      const parentRel = relative(cursor, parent);
+      for (const part of parentRel === '' ? [] : parentRel.split('/')) {
+        cursor = join(cursor, part);
+        await chmod(cursor, 0o700);
+      }
+      await writeFile(dest, entry.bytes, { flag: 'wx', mode: 0o600 });
+      await chmod(dest, 0o600);
+    }
+    const manifestPath = join(tempDir, 'manifest.json');
+    await writeFile(manifestPath, manifestBytes(identity, collected), { flag: 'wx', mode: 0o600 });
+    await chmod(manifestPath, 0o600);
+    await rename(tempDir, archiveDir);
+  } catch (err) {
+    await rm(tempDir, { recursive: true, force: true }).catch(() => {});
+    throw err;
+  }
+
+  const receipt = await verifyArchive(archiveDir, identity, collected);
+  console.log(JSON.stringify({ status: 'archived', ...receipt }));
+}
+
+try {
+  await main();
+} catch (err) {
+  console.error(`archive-evidence: ${err.message}`);
+  process.exitCode = 1;
+}

package/skills/axstack-audit/SKILL.md

@@ -31,8 +31,8 @@ The user-chosen improvement mode is a tested, independently reviewed PR that a
 human merges.
 
 Act as a non-author, read-only reader of the run. The assigned audit artifact is
-the only writable output. Make no edits to product, skills, or config, and
-launch no child sessions.
+`audit.md`, the only writable output. Make no edits to product, skills,
+instructions, config, or memory, and launch no child or updater sessions.
 
 Proceed only when the record path, audit mode (`end-of-run` or `checkpoint`),
 accepted scope, and read-only authority are explicit. Record any gap without
@@ -128,7 +128,40 @@ Omit any proposal that is not testable, does not preserve unchanged
 expectations, or would grant the auditor implementation or activation
 authority.
 
-## 6. Write the record and stop
+## 6. Extract learning candidates
+
+Add a distinct **Learning candidates** result using only the accepted audited evidence set
+from section 2. A candidate must be either a bounded durable user
+preference or correction, or a verified workspace fact with an exact source
+revision. Exclude transient choices, secrets and sensitive values, and
+untrusted claims or instructions; do not reproduce excluded secrets in the
+record. Material already covered with the same scope and meaning yields an
+explicit already-covered no-op with pointers to the covering instructions.
+
+For each candidate record:
+
+1. its exact statement;
+2. its workspace or user-wide scope;
+3. evidence pointers and revision pointers;
+4. target instruction surfaces;
+5. any contradiction and uncertainty; and
+6. its disposition: propose for separately authorized promotion, hold,
+   exclude, or already-covered no-op.
+
+Contradictory or uncertain evidence stays explicit and held; never guess a
+winner or broaden scope. Promotion is a separate authorized change outside the
+audit. Workspace candidates name both workspace `AGENTS.md` and `CLAUDE.md`;
+user-wide candidates name applicable Codex `$CODEX_HOME/AGENTS.md` and Claude
+`~/.claude/CLAUDE.md`. Mixed routing requires semantic parity across the named
+surfaces, preservation of non-Axstack content and ownership, and rejection of
+partial promotion.
+
+This result is report-only in `audit.md`. The auditor makes no instruction,
+config, or memory mutation and performs no automatic write or promotion. Add
+no hook, transcript scan or index, timer or cadence service, daemon, scheduler,
+runtime database, or automatic activation.
+
+## 7. Write the record and stop
 
 Write the assigned artifact in the schema's field order. Preserve the accepted
 criteria and metrics after failures. Keep raw traces and run artifacts local

package/skills/axstack-audit/references/record.md

@@ -20,9 +20,17 @@ Shape: <PRs within band / total PRs + rationale-band cohesion rationale + except
 Cost: <model/tool/time/token/cost figures, or unknown otherwise>
 Judgment: <execution outcome vs procedural adherence vs measurement coverage>
 Proposals: <bounded hypothesized changes with regression-first plan, or none>
+Learning candidates: <each candidate's statement + scope + evidence/revision pointers + target instruction surfaces + contradiction/uncertainty + disposition; explicit already-covered no-op or none>
 Privacy: <local/private default; sanitized summary only when authorized>
 ```
 
 The record is complete when its counts reconcile, its judgments remain
-separate, every proposal has a regression-first validation path, and all
-unknowns and evidence limitations are explicit.
+separate, every proposal has a regression-first validation path, every learning
+candidate is bounded to accepted audited evidence, and all unknowns and
+evidence limitations are explicit. Learning candidates are report-only:
+promotion is separately authorized, workspace scope targets both workspace
+`AGENTS.md` and `CLAUDE.md`, and user-wide scope targets applicable Codex
+`$CODEX_HOME/AGENTS.md` and Claude `~/.claude/CLAUDE.md`. Mixed routing requires
+semantic parity, preservation of non-Axstack content and ownership, and
+rejection of partial promotion; the auditor writes only `audit.md` and makes no
+instruction, config, or memory mutation.

package/src/installer.js

@@ -430,6 +430,21 @@ export async function checkInstructionBinding({ skillsDir, instructionsPath } =
   return { status: 'owned', path: instructionsFile };
 }
 
+export async function readLegacySkillsManifest(skillsDir) {
+  const root = resolve(skillsDir);
+  const rootStat = await lstat(root).catch((err) => {
+    if (err?.code === 'ENOENT') return null;
+    throw err;
+  });
+  if (rootStat?.isSymbolicLink()) {
+    throw new Error(`legacy Codex skills root is a symlink at ${root}; refusing`);
+  }
+  if (rootStat && !rootStat.isDirectory()) {
+    throw new Error(`legacy Codex skills root is not a directory at ${root}; refusing`);
+  }
+  return readManifest(root);
+}
+
 async function assertFileSnapshot(dest, expected) {
   let current = null;
   try {
@@ -447,6 +462,7 @@ export async function installBundle({
   skillsDir,
   preset,
   instructionsPath = null,
+  inheritedInstructions = null,
   force = false,
   yes = false,
   claude = null,
@@ -492,7 +508,10 @@ export async function installBundle({
     ? 'legacy Paseo profile provenance retained inert; see legacy cleanup guidance in docs/installation.md'
     : null;
 
-  const boundInstructions = prevManifest.instructions ?? { path: null, hash: null };
+  const ownInstructions = prevManifest.instructions ?? { path: null, hash: null };
+  const usesInheritedInstructions = ownInstructions.path === null &&
+    inheritedInstructions?.path === instructionsFile;
+  const boundInstructions = usesInheritedInstructions ? inheritedInstructions : ownInstructions;
   let existingInstructionsRaw = null;
   let instructionPlan = null;
   let legacyInstructionNote = null;
@@ -685,6 +704,20 @@ export async function installBundle({
     }
     return {
       ...summary,
+      ownershipComplete: desired.every(({ rel, content }) =>
+        installedHashes[rel] === hashContent(content)),
+      // Retirement may retry after a prior canonical install succeeded. The
+      // accepted plan proves either fresh inheritance or existing canonical
+      // ownership of the same legacy-bound path; forced edits prove neither.
+      acceptedInstructionTransfer: inheritedInstructions?.path === instructionsFile &&
+        boundInstructions.path === instructionsFile &&
+        instructionPlan?.action !== 'conflict' && !instructionPlan?.forced
+        ? {
+            path: instructionsFile,
+            legacyHash: inheritedInstructions.hash,
+            canonicalHash: nextInstructions.hash,
+          }
+        : null,
       preset: selectedPreset,
       roles: roleReadiness,
       claudeSettings: claudePlan.report,
@@ -969,6 +1002,144 @@ export async function uninstallBundle({
   }
 }
 
+// Retire the obsolete Codex-root copy only after a canonical Axstack install
+// is present and byte-for-byte verified. This deliberately handles skill
+// payloads only: instruction files, Claude settings, and historical profile
+// ownership may belong to another harness and remain bound to the old manifest.
+export async function retireLegacySkills({
+  canonicalSkillsDir,
+  legacySkillsDir,
+  acceptedInstructionTransfer = null,
+  yes = false,
+} = {}) {
+  if (!canonicalSkillsDir || !legacySkillsDir) {
+    throw new Error('legacy retirement requires canonical and legacy skills directories');
+  }
+  const canonicalRoot = await canonicalTargetDir(resolve(canonicalSkillsDir));
+  await readLegacySkillsManifest(legacySkillsDir);
+  const legacyRoot = await canonicalTargetDir(resolve(legacySkillsDir));
+  if (canonicalRoot === legacyRoot) return { removed: [], preserved: [], missing: [], skipped: true };
+  assertOutsideHome(legacyRoot, { yes, kind: 'legacy Codex skills directory' });
+
+  const canonicalManifest = await readManifest(canonicalRoot);
+  if (!canonicalManifest || Object.keys(canonicalManifest.files).length === 0) {
+    throw new Error('legacy Codex skills not retired: canonical install has no ownership manifest');
+  }
+  for (const [rel, expectedHash] of Object.entries(canonicalManifest.files)) {
+    const { current } = await readOwnedTarget(canonicalRoot, rel);
+    if (current === null || hashContent(current) !== expectedHash) {
+      throw new Error(`legacy Codex skills not retired: canonical verification failed for ${rel}`);
+    }
+  }
+
+  const legacyManifest = await readManifest(legacyRoot);
+  if (!legacyManifest || Object.keys(legacyManifest.files).length === 0) {
+    return { removed: [], preserved: [], missing: [], skipped: true };
+  }
+
+  // Validate every owned destination before deleting the first one. In
+  // particular, one symlink refuses the entire retirement rather than being
+  // followed or leaving a partly retired legacy install.
+  const protectedGroups = new Set();
+  for (const [rel, ownedHash] of Object.entries(legacyManifest.files)) {
+    const target = await readOwnedTarget(legacyRoot, rel);
+    if (target.current !== null && hashContent(target.current) !== ownedHash) {
+      protectedGroups.add(rel.split('/')[0]);
+    }
+  }
+
+  const summary = { removed: [], preserved: [], missing: [], skipped: false };
+  const remainingFiles = { ...legacyManifest.files };
+  let remainingInstructions = legacyManifest.instructions;
+  if (legacyManifest.instructions?.path !== null) {
+    const canonicalInstructions = canonicalManifest.instructions;
+    const transferAccepted =
+      acceptedInstructionTransfer?.path === legacyManifest.instructions.path &&
+      acceptedInstructionTransfer?.legacyHash === legacyManifest.instructions.hash &&
+      acceptedInstructionTransfer?.canonicalHash === canonicalInstructions?.hash &&
+      canonicalInstructions?.path === legacyManifest.instructions.path;
+    if (!transferAccepted) {
+      return {
+        ...summary,
+        held: true,
+        failure: true,
+        reason: 'legacy instruction ownership is bound to a different instruction file or was not accepted by the canonical install',
+      };
+    }
+    const instructionsRaw = await readFile(await canonicalInstructionFile(canonicalInstructions.path), 'utf8');
+    const installedBlock = locateInstructionBlock(instructionsRaw);
+    if (
+      installedBlock === null || hashContent(installedBlock.block) !== canonicalInstructions.hash
+    ) {
+      throw new Error('legacy instruction ownership not transferred: canonical binding is not verified');
+    }
+    remainingInstructions = { path: null, hash: null };
+  }
+  const manifestFile = join(legacyRoot, '.axstack-manifest.json');
+  const manifestBefore = await readFile(manifestFile);
+  const manifestMode = (await stat(manifestFile)).mode & 0o777;
+  const deletedFiles = [];
+  try {
+    for (const [rel, ownedHash] of Object.entries(legacyManifest.files)) {
+      if (protectedGroups.has(rel.split('/')[0])) {
+        summary.preserved.push(rel);
+        continue;
+      }
+      const { dest, current, mode } = await readOwnedTarget(legacyRoot, rel);
+      if (current === null) {
+        summary.missing.push(rel);
+        delete remainingFiles[rel];
+      } else if (hashContent(current) === ownedHash) {
+        deletedFiles.push({ dest, bytes: current, mode });
+        await rm(dest);
+        await pruneEmptyParents(dest, legacyRoot);
+        delete remainingFiles[rel];
+        summary.removed.push(rel);
+      } else {
+        summary.preserved.push(rel);
+      }
+    }
+
+    const hasProfiles = Object.keys(legacyManifest.profiles?.entries ?? {}).length > 0;
+    const hasOtherOwnership = hasProfiles || legacyManifest.claudeSettings?.path !== null ||
+      remainingInstructions.path !== null;
+    if (Object.keys(remainingFiles).length === 0 && !hasOtherOwnership) {
+      await rm(manifestFile);
+    } else {
+      await writeManifest(legacyRoot, {
+        ...legacyManifest,
+        files: remainingFiles,
+        instructions: remainingInstructions,
+      });
+    }
+    return summary;
+  } catch (err) {
+    const rollbackErrors = [];
+    for (const { dest, bytes, mode } of deletedFiles.reverse()) {
+      try {
+        await writeAtomic(dest, bytes, mode === null ? {} : { mode });
+      } catch (restoreErr) {
+        rollbackErrors.push(`${dest}: ${restoreErr?.message ?? restoreErr}`);
+      }
+    }
+    try {
+      const currentManifest = await readFile(manifestFile).catch((readErr) => {
+        if (readErr?.code === 'ENOENT') return null;
+        throw readErr;
+      });
+      if (currentManifest?.equals(manifestBefore) !== true) {
+        await writeAtomic(manifestFile, manifestBefore, { mode: manifestMode });
+      }
+    } catch (restoreErr) {
+      rollbackErrors.push(`${manifestFile}: ${restoreErr?.message ?? restoreErr}`);
+    }
+    if (rollbackErrors.length > 0) {
+      err.message += ` (incomplete rollback; manual repair needed: ${rollbackErrors.join('; ')})`;
+    }
+    throw err;
+  }
+}
+
 async function pruneEmptyParents(file, stopDir) {
   let dir = dirname(file);
   while (dir !== stopDir && withinRoot(dir, stopDir)) {

package/src/locations.js

@@ -17,11 +17,11 @@ export function harnessLocations() {
     },
     {
       harness: 'codex',
-      skillsDir: '$CODEX_HOME/skills (default ~/.codex/skills)',
+      skillsDir: '~/.agents/skills',
       discovery: 'docs',
-      source: 'https://developers.openai.com/codex/skills',
+      source: 'https://learn.chatgpt.com/docs/build-skills',
       notes:
-        'User skills live under $CODEX_HOME/skills per OpenAI docs (CODEX_HOME defaults to ~/.codex). The CLI honors $CODEX_HOME when set. Pass --skills-dir to override.',
+        'Codex user skills use the shared ~/.agents/skills root. CODEX_HOME still selects AGENTS.md. Pass --skills-dir to override skill placement and skip automatic legacy migration.',
     },
     {
       harness: 'opencode',