@nurix/etna 0.19.22 → 0.19.23

package/data/harnesses/etna/codex/agents/change-review.toml

@@ -1,15 +1,14 @@
 # dropped Claude tools: Bash, Read, Write, Glob, Grep, Task
 name = "change-review"
-description = "Velocity + change-risk analysis. First classifies recent commits into a pipe-delimited velocity/severity CSV by dispatching parallel haiku sub-agents (module, feature, impact, severity, churn), then derives a commit heatmap, risk zones (high churn in contract-heavy code), stabilization signals, and team/bus-factor distribution. Self-contained — produces its own CSV, no separate git-history step. Use when planning where to invest in review focus or rules."
+description = "Velocity + change-risk analysis. First classifies recent commits into a pipe-delimited velocity/severity CSV by dispatching parallel low-cost subagents (module, feature, impact, severity, churn), then derives a commit heatmap, risk zones (high churn in contract-heavy code), stabilization signals, and team/bus-factor distribution. Self-contained — produces its own CSV, no separate git-history step. Use when planning where to invest in review focus or rules."
 developer_instructions = '''
-
 # Change-Review Agent
 
 You analyze code-change velocity over time to find risk zones — where change is accelerating or decelerating, and whether review attention matches the risk. You answer: "where should the tech lead invest review focus or rules next?"
 
 You work in two phases:
 
-1. **Classify** — turn recent git history into a structured, pipe-delimited CSV (one classified row per commit) by dispatching parallel haiku sub-agents. You do this yourself; there is no separate agent that hands you a CSV.
+1. **Classify** — turn recent git history into a structured, pipe-delimited CSV (one classified row per commit) by dispatching parallel low-cost subagents. You do this yourself; there is no separate agent that hands you a CSV.
 2. **Analyze** — read that CSV and derive the velocity heatmap, risk zones, stabilization signals, and team distribution.
 
 ## Parameters
@@ -80,7 +79,7 @@ Build a registry of objects:
 
 Split the commit registry into batches of `batch_size` commits each.
 
-Spawn **haiku** sub-agents via the Task tool with `subagent_type: "general-purpose"` and `model: "haiku"`. Launch up to 5 batches in parallel.
+Dispatch one **independent subagent per batch** on the **cheapest capable tier** — classification is mechanical, so the lowest-cost model that can follow the output format is the right one. Cap concurrency at **5 batches in parallel**; each subagent is context-isolated and returns only its rows. If the runtime offers no subagent dispatch, classify the batches inline yourself.
 
 Before building the prompt template, check if `docs/memory/change-review.md` contains **Module Taxonomy** and **Feature Taxonomy** sections. If yes, inject their content into the `{MODULE_TAXONOMY}` and `{FEATURE_TAXONOMY}` placeholders below. If no memory file exists, use these generic fallbacks:
 
@@ -241,7 +240,7 @@ Per module, list which authors made the most commits in the 3-month window. Surf
 ## Rules
 
 - Never modify source code — read-only except for writing the output CSV, `docs/memory/change-review.md`, and `docs/history/backlog.md`
-- Use `model: "haiku"` and `subagent_type: "general-purpose"` for all classification sub-agents to minimize cost
+- Run all classification subagents on the cheapest capable tier to minimize cost; they are independent and context-isolated
 - Always report progress: "Dispatching batch 1-5 of 12..." etc.
 - If git commands fail (bad branch, bad date range), stop and report the error clearly
 - Pipe characters in commit messages must be replaced with dashes before writing to CSV

package/data/harnesses/etna/codex/agents/maintenance.toml

@@ -135,6 +135,7 @@ docs/
 ├── history/
 │   ├── CHANGELOG.md       # Master changelog index
 │   ├── changelog/         # Individual entries
+│   ├── ledger/            # Refinement Ledger — append-only per-commit refinement journal (YYYY-MM.md; written at commit time, NOT scaffolded empty)
 │   ├── plans/             # Implementation plans (Status field required)
 │   ├── brainstorms/       # Harvested brainstorm sessions ({topic}/) — user decides kept (committed) or deleted; Readme.md is the index
 │   └── backlog.md         # Tracked work items by priority (P0-P3)
@@ -197,7 +198,7 @@ Re-running you is safe — the structure work is idempotent, so a second pass is
 ## Rules
 
 - **Never delete feature docs** — only update or flag for review.
-- **Never modify `docs/history/plans/` or `docs/history/changelog/`** (frozen records).
+- **Never modify `docs/history/plans/`, `docs/history/changelog/`, or `docs/history/ledger/`** (frozen/append-only records — ledger blocks are written only at commit time, distilled only by the `retro` agent).
 - **Preserve existing doc structure and formatting** when updating.
 - **When in doubt, create a backlog item** rather than making a wrong update.
 - **Be specific:** include file paths, line numbers, and what changed.

package/data/harnesses/etna/harness.json

@@ -1,11 +1,11 @@
 {
   "harness": "etna",
   "name": "etna",
-  "version": "1.1.11",
+  "version": "1.1.13",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
-  "digest": "3e3243936008"
+  "digest": "27b25f41633e"
 }

package/data/harnesses/etna/skills/documentation/SKILL.md

@@ -61,6 +61,7 @@ The two guarantees are complementary and both break on mixing: a reader holding
 | Document feature/module (LLD) | [`templates/feature.md`](templates/feature.md) |
 | Document data flow / state / Redux | [`templates/feature.md`](templates/feature.md) — they are sections of the feature doc |
 | Create/update changelog | [`templates/changelog-entry.md`](templates/changelog-entry.md) (record) |
+| Record per-commit refinement (ledger block) | [`templates/refinement-ledger.md`](templates/refinement-ledger.md) (record — written at commit time, distilled by the `retro` agent) |
 | Create/update plan | [`templates/plan.md`](templates/plan.md) (record) |
 | Record/revise architecture decision | [`templates/architecture-decision.md`](templates/architecture-decision.md) — one AD per subject; revisions update it in place |
 | System at a glance | [`templates/system-overview.md`](templates/system-overview.md) |

package/data/harnesses/etna/skills/documentation/templates/refinement-ledger.md

@@ -0,0 +1,33 @@
+# Refinement Ledger
+
+Record. Use for: the append-only per-commit journal of session refinement — one block per non-mechanical commit, written by the committing agent at commit time and staged **inside the commit it describes**. Blocks are immutable once committed: never edited, renumbered, or reconciled; a correction is a new block referencing the old. The ledger is exempt from doc-health passes by genre — it is history and can never be "wrong".
+
+Monthly files: `docs/history/ledger/YYYY-MM.md`, created on first block — the folder is never scaffolded empty. Distillation is the `retro` agent's job; this template owns only the capture format.
+
+## Block format
+
+```
+### {YYYY-MM-DD} · {surface} — {one-line outcome}
+- **Ask:** {what the user asked, compressed — taste and preference statements quoted verbatim}
+- **Iterations:** {N} · rejected: {what was rejected and why} | none
+- **Skills:** {skill}@{version} — survived | partially survived | overridden ({why, briefly}) | none used
+- **Change:** {added/changed X, which does Y, because Z — behavior first, mechanism second}
+- **Discovered:** {non-obvious fact learned by running the product — environment quirk, platform ceiling, seam behavior, dependency constraint} | none
+- **Class:** {one or more keywords — suggestive vocabulary, not a closed enum; see Field rules}
+- **Pin:** {enforced artifact written in this commit: test / token / guardrail / schema} | none — candidate: {what should hold it}
+```
+
+## Field rules
+
+- **Every field present; "none" stated explicitly.** An absent field is a template violation. Sessions assert success by default — the required `rejected:` and `overridden` entries are the counterweight; an honestly empty failure field is information too.
+- **`surface`** uses the repo's ownership vocabulary — the owning feature doc's topic or an `owns:` path stem — so the ledger is queryable per surface.
+- **`Ask` quotes taste verbatim.** The user's preference wording is the one thing no skill can infer and no rebuild recovers; the ledger is its durable home.
+- **`Skills` records efficacy honestly** — survived / partially survived / overridden with a reason. These verdicts are the raw data the `retro` agent aggregates into skill-evolution findings; sanitizing them into success stories destroys the mechanism's value.
+- **`Discovered` holds what only running the product teaches.** If it was learned in use, it is recorded here the same day — this field feeds the pin candidates.
+- **`Class` is a suggestive vocabulary, not a closed enum.** Tag with one or more keywords, preferring an existing term over a synonym so the `retro` agent can cluster; coin a new one when nothing fits — a recurring coinage is itself retro signal that the vocabulary (or the doc set) is missing a category. Suggested keywords: `ux` · `ui` · `visual` · `taste` · `layout` · `motion` · `interaction` · `copy` · `a11y` · `responsiveness` · `navigation` · `state` · `structure` · `architecture` · `seam` · `contract` · `schema` · `data` · `content` · `seed` · `performance` · `caching` · `resilience` · `error-handling` · `security` · `auth` · `observability` · `logging` · `testing` · `tooling` · `dependency` · `ops` · `deploy` · `env` · `ci` · `i18n` · `docs`.
+- **`Pin` closes the loop:** the enforced artifact written in this commit, or the named candidate for the `retro` agent to flag. A taste-verified behavior with `Pin: none` and no candidate is a template smell.
+- **Out-of-session commits** (the committing session did not do the work): fill what the diff and conversation evidence support; mark the rest `unknown — committed out-of-session`.
+
+## Exemptions (closed list)
+
+No block for: release/bot commits, harness installs and bumps, lockfile-only changes, pure renames/moves, and ledger housekeeping itself. Everything else gets a block, however short.

package/data/harnesses/etna/skills/documentation/templates/structure.md

@@ -30,6 +30,7 @@ Each topic has one canonical location. Read from here, not from plans or changel
 | Testing strategy | `docs/tests/` | strategy.md |
 | Historical plans | `docs/history/plans/` | YYYY-MM-DD-name.md |
 | Change records | `docs/history/changelog/` | Individual entries |
+| Refinement Ledger | `docs/history/ledger/` | YYYY-MM.md (append-only, written at commit time) |
 | Migration runbooks | `docs/history/migrations/` | YYYY-MM-DD-name.md |
 | Deep-research artifacts | `docs/history/research/{topic}/` | README.md + findings.md + sources.md |
 | Brainstorm design records | `docs/research/{topic}-brainstorm/` (active; legacy `-brainstorming/`) → `docs/history/brainstorms/{topic}/` (harvested; user deletes or commits) | thesis.md + forks.md + ledger.md + state.md |
@@ -51,6 +52,7 @@ Every doc is a **truth document** (states current absolutes, topic-named, update
 - `docs/tests/`: Testing strategy and test docs. Present when the repo has a test posture worth documenting.
 - `docs/history/plans/`: Records. Must have `Status:` field. Never modify after completion.
 - `docs/history/changelog/`: Records. Append-only.
+- `docs/history/ledger/`: Records. The Refinement Ledger — an append-only per-commit refinement journal (monthly `YYYY-MM.md` files) written by the committing agent, each block staged inside the commit it describes; block format is the `documentation` skill's `templates/refinement-ledger.md`, distillation is the `retro` agent. Blocks are immutable — never edited, never reconciled; the folder is never scaffolded empty.
 - `docs/history/migrations/`: Records. One-shot migration/upgrade runbooks — authored before execution, outcome-stamped and frozen after.
 - `docs/history/research/{topic}/`: Deep-research artifacts — the dumped output of a research pass, one folder per topic (conventionally `README.md` synthesis + `findings.md` verified claims & citations + `sources.md`). A point-in-time, cited record — **not** a living authority doc: it owns no code (no `owns:` frontmatter) and is never edited to "stay current." A spec/plan links to it for grounding; a new question gets a new topic folder.
 - `docs/research/{topic}-brainstorm/` → `docs/history/brainstorms/{topic}/`: Brainstorm design records — the Brainstorming-Mode session for a topic (working surface `thesis.md` + `forks.md` + `ledger.md` + `state.md` + `basis/` + `fragments/`, plus an untracked `ops/` capture layer deleted at stop), written by the `brainstorm` skill and its twin agent. An active session lives under `docs/research/` (legacy folders carry the older `-brainstorming/` suffix); on a **passed harvest** it **moves** to `docs/history/brainstorms/` — the completion marker — and the **user decides whether the moved folder is deleted or committed** as provenance. Each of the two folders carries a `Readme.md` index (the skill reads it at start instead of scanning). Author-created (never scaffolded empty), one folder per design conversation. Owns no code (no `owns:` frontmatter); the harvest routes its conclusions into `architecture/`/`features/`/`history/`. (Distinct from `docs/history/research/{topic}/` above — that is a frozen deep-research record, not a brainstorm session.)

package/data/harnesses/hr/harness.json

@@ -1,7 +1,7 @@
 {
   "harness": "hr",
   "name": "hr",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "files": [
     ".prettierignore",
     ".prettierrc.json",

package/lib/codex/README.md

@@ -8,24 +8,34 @@ Owning doc: [`docs/features/codex-support.md`](../../../../docs/features/codex-s
 
 | Source | Target | File |
 | --- | --- | --- |
-| `CLAUDE.md` | `AGENTS.md` (exact copy) | `agents-md.mjs` |
+| `CLAUDE.md` | `AGENTS.md` (byte-for-byte copy + generated adapter) | `agents-md.mjs` |
 | `.claude/skills/` | `.agents/skills/` (mirror) | `skills.mjs` |
 | bundle `codex/agents/*.toml` | `.codex/agents/*.toml` (copy) | `subagents.mjs` |
-| `hooks.json` | `.codex/hooks.json` (`type:"command"` only) | `hooks.mjs` |
+| `hooks.json` | `.codex/hooks.json` (`type:"command"`, command translated) | `hooks.mjs` |
 | `.claude-plugin/*` | `.codex-plugin/plugin.json` + `.agents/plugins/marketplace.json` | `plugin-manifest.mjs` |
 
 `index.mjs` orchestrates the install-time projectors and returns `{installed, notices, warnings, owned}`; `owned` is recorded in `.claude/harness.json` → `owned.codex` for prune-on-refresh.
 
 **Out of scope (owner decision 2026-07-13):** MCP projection and any Codex `settings.json`/`config.toml` equivalent. There is no user-editable Codex file the harness co-owns, so every Codex path is a clean full-overwrite — no managed-block merge.
 
+## Runtime adaptation the projection performs
+
+The Claude source is runtime-neutral in intent, but three edges do not survive a mechanical copy — the projectors adapt them so a Codex install works out of the box:
+
+- **Policy adapter (`agents-md.mjs`).** `AGENTS.md` is the `CLAUDE.md` policy copied byte-for-byte, then a compact **generated Codex runtime adapter** appended: it names the native skill (`.agents/skills/`) and agent (`.codex/agents/`) locations and, crucially, routes Codex to the `.claude/rules/*.md` files Codex does **not** auto-load. The list is derived from the bundled harness inventory (`bundledHarnessDir`), carries no user state, and is replaced whole on reinstall. It stays well under Codex's 32 KiB combined-instruction cap.
+- **Hook-path translation (`hooks.mjs`, install) & (`publish.mjs`, plugin).** A hook command locating its script via `$CLAUDE_PROJECT_DIR` fails under Codex (Codex sets no such variable). For a **CLI install**, `toCodexCommand` prefixes a runtime-neutral root resolution (`git rev-parse --show-toplevel`, `pwd` fallback) and re-exports `CLAUDE_PROJECT_DIR`, so the hook resolves from the project root or any nested dir. For a **marketplace plugin**, `publish.mjs` rewrites the prefix to `$CLAUDE_PLUGIN_ROOT/hooks/` — the plugin-root variable both runtimes export.
+- **Agent validation (`validate-codex-agents.mjs`).** A committed twin must be valid TOML with the required keys and carry no Claude-only primitive (`Task tool`, `subagent_type`, or a fixed model tier). Because a twin ships to consumers unparsed, this standalone validator is the gate — the authoring procedure mandates it.
+
+## CLI vs plugin capability surface
+
+The two channels do not install the same set. The **CLI** writes the full Codex footprint — `AGENTS.md`, `.agents/skills/`, `.codex/agents/*.toml`, `.codex/hooks.json`. The **marketplace plugin** carries only what `.codex-plugin/plugin.json` supports — **skills + hooks**; it exposes no project custom agents (Codex custom agents are a CLI-only feature) and no root policy. See [`codex-support.md`](../../../../docs/features/codex-support.md) → _Supported Codex plugin surface_.
+
 ## Subagents are authored, not derived at install
 
-`.claude/agents/*.md → .codex/agents/*.toml` is lossy/semantic, so it is done by the **real Codex CLI** at authoring time, not a parser at install:
+`.claude/agents/*.md → .codex/agents/*.toml` is a semantic conversion, so the twin is **authored from the `.md` by following** [`docs/architecture/harness/authoring-agents.md`](../../../../docs/architecture/harness/authoring-agents.md) — the model that writes or edits the agent produces the twin inline (frontmatter → `name`/`description`, body verbatim → `developer_instructions`, `tools:` dropped to a comment, Claude model aliases omitted), with **no external CLI**. The committed `agents/<name>.codex.toml` is checked by the validation gate:
 
 ```bash
-node packages/cli/lib/codex/gen-agents.mjs                 # shared catalog (agents/*.md), stale/missing only
-node packages/cli/lib/codex/gen-agents.mjs --force          # regenerate all shared agents
-node packages/cli/lib/codex/gen-agents.mjs --include-harness # + harness/*/agents/*.md
+node packages/cli/lib/codex/validate-codex-agents.mjs   # or: npm run validate:codex-agents
 ```
 
-`gen-agents.mjs` runs `codex exec` per agent and writes a committed `agents/<name>.codex.toml` sibling. It runs **only on a laptop with `codex` installed + authenticated — never in CI**. `build-data.js` and `publish.mjs` then ship those committed TOML; the installer copies them, so **consumers need no Codex CLI**. Regenerate an agent's TOML in the same change that edits its `.md` (source↔generated parity).
+`build-data.js` and `publish.mjs` then ship the committed TOML; the installer copies it, so **consumers need no Codex CLI**. Re-author an agent's TOML in the same change that edits its `.md` (source↔twin parity).

package/lib/codex/agents-md.mjs

@@ -1,9 +1,14 @@
 // packages/cli/lib/codex/agents-md.mjs
-// CLAUDE.md → AGENTS.md — an exact copy (Codex's confirmed CLAUDE.md analog).
-// Mirrors the installer's CLAUDE.md safety net: overwrite in place when git can
-// recover it, otherwise back up the existing file and warn.
+// CLAUDE.md → AGENTS.md — the authored policy copied byte-for-byte, then a small GENERATED
+// Codex runtime adapter appended. The policy is runtime-neutral; the adapter maps its
+// capability hooks to Codex's native locations and, crucially, routes Codex to the markdown
+// rules under .claude/rules/ that Codex does NOT auto-load. The adapter is derived from the
+// bundled harness inventory (rules/skills/agents actually shipped), carries no user state, and
+// is regenerated whole on every reinstall alongside the rest of the harness-owned AGENTS.md.
+// Mirrors the installer's CLAUDE.md safety net: overwrite in place when git can recover it,
+// otherwise back up the existing file and warn.
 
-import { existsSync, lstatSync, renameSync, cpSync } from 'node:fs';
+import { existsSync, lstatSync, renameSync, readdirSync, readFileSync, writeFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 
 function isSymlink(path) {
@@ -14,7 +19,75 @@ function isSymlink(path) {
     }
 }
 
-export function projectAgentsMd({ targetDir, bundledClaudeMd, projectHasGit }) {
+// Sorted base names of *.<ext> files directly under dir (e.g. rules/*.md → rule names).
+function listByExt(dir, ext) {
+    if (!existsSync(dir)) return [];
+    return readdirSync(dir)
+        .filter((f) => f.endsWith(ext))
+        .map((f) => f.slice(0, -ext.length))
+        .sort();
+}
+
+// Sorted names of immediate subdirectories of dir (e.g. skills/<name>/).
+function listSubdirs(dir) {
+    if (!existsSync(dir)) return [];
+    return readdirSync(dir)
+        .filter((f) => {
+            try {
+                return statSync(join(dir, f)).isDirectory();
+            } catch {
+                return false;
+            }
+        })
+        .sort();
+}
+
+// Render an inventory list as inline code names, or a runtime-neutral fallback when empty.
+function nameList(names) {
+    return names.length ? names.map((n) => `\`${n}\``).join(', ') : '_(none installed)_';
+}
+
+// Compose the generated Codex runtime adapter from the bundled harness inventory. Returns "" when
+// the bundle carries no rules, skills, or codex agents — nothing to adapt, so nothing is appended.
+export function buildCodexAdapter(bundledHarnessDir) {
+    const rules = listByExt(join(bundledHarnessDir, 'rules'), '.md');
+    const skills = listSubdirs(join(bundledHarnessDir, 'skills'));
+    const agents = listByExt(join(bundledHarnessDir, 'codex', 'agents'), '.toml');
+    if (!rules.length && !skills.length && !agents.length) return '';
+
+    const lines = [
+        '---',
+        '',
+        '## Codex runtime adapter (generated)',
+        '',
+        'This project is also installed for OpenAI Codex. The runtime-neutral policy above applies unchanged;',
+        "this section maps its capability hooks to Codex's native locations. It is generated from the installed",
+        'harness inventory and replaced whole on every reinstall — do not hand-edit.',
+        '',
+    ];
+    if (skills.length) {
+        lines.push(
+            `- **Skills** — Codex scans \`.agents/skills/\` (a mirror of \`.claude/skills/\`); invoke a skill by its name. Installed: ${nameList(skills)}.`,
+        );
+    }
+    if (agents.length) {
+        lines.push(
+            `- **Custom agents** — Codex reads \`.codex/agents/*.toml\`; dispatch a subagent by its name. Installed: ${nameList(agents)}.`,
+        );
+    }
+    if (rules.length) {
+        lines.push(
+            `- **Project rules** — Codex does NOT auto-load the markdown rules the policy references. Read the relevant file under \`.claude/rules/\` before the work it governs: ${nameList(rules)}.`,
+        );
+    }
+    lines.push(
+        '- **Ownership index** — regenerated each session by the `.codex/hooks.json` SessionStart hook; if it is absent from context, derive it by scanning `docs/features/` frontmatter.',
+    );
+    lines.push('');
+    return lines.join('\n');
+}
+
+export function projectAgentsMd({ targetDir, bundledClaudeMd, bundledHarnessDir, projectHasGit }) {
     if (!existsSync(bundledClaudeMd)) return null;
     const dest = join(targetDir, 'AGENTS.md');
     const existed = existsSync(dest) || isSymlink(dest);
@@ -30,6 +103,12 @@ export function projectAgentsMd({ targetDir, bundledClaudeMd, projectHasGit }) {
             warning = `No .git here, so no version-control safety net — backed up existing AGENTS.md → ${backup}`;
         }
     }
-    cpSync(bundledClaudeMd, dest, { force: true });
+    // Policy copied byte-for-byte; the generated adapter appended after a blank-line separator.
+    // The policy prefix is left exactly as authored — only a separator + adapter follow it.
+    const policy = readFileSync(bundledClaudeMd, 'utf8');
+    const adapter = bundledHarnessDir ? buildCodexAdapter(bundledHarnessDir) : '';
+    const separator = policy.endsWith('\n') ? '\n' : '\n\n';
+    const body = adapter ? policy + separator + adapter : policy;
+    writeFileSync(dest, body);
     return { installed: 'AGENTS.md → ./', notice, warning };
 }

package/lib/codex/hooks.mjs

@@ -3,10 +3,32 @@
 // filtered to type:"command" (the only hook type Codex executes — "prompt"/"agent"
 // entries are parsed but skipped). A standalone file, not a config.toml [hooks]
 // table, since the settings/config surface is out of scope for Codex here.
+//
+// Command translation: the source command locates its script via $CLAUDE_PROJECT_DIR,
+// which Claude Code exports but Codex does not — under Codex the token expands empty
+// and `node "/.claude/hooks/…"` exits 1, failing SessionStart. So every command that
+// references the token is prefixed with a runtime-neutral root resolution: `git
+// rev-parse` (walks up from any nested working directory) with a `pwd` fallback for a
+// non-Git project root. The resolved root is exported back as CLAUDE_PROJECT_DIR so the
+// script's own project-dir read (generate-ownership-index.mjs resolveProjectDir) also
+// points at the project root, not the session's nested cwd. The Claude source hooks.json
+// is left untouched — it stays valid for the CLI-installed .claude/settings.json path.
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 
+const PROJECT_DIR_TOKEN = /\$\{?CLAUDE_PROJECT_DIR\}?/;
+
+// Prefix a $CLAUDE_PROJECT_DIR-dependent command with a Codex-safe root resolution.
+// Commands that don't reference the token pass through unchanged.
+export function toCodexCommand(command) {
+    if (typeof command !== 'string' || !PROJECT_DIR_TOKEN.test(command)) return command;
+    return (
+        'export CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; ' +
+        command
+    );
+}
+
 export function projectHooks({ targetDir, bundledHarnessDir }) {
     const srcJson = join(bundledHarnessDir, 'hooks', 'hooks.json');
     if (!existsSync(srcJson)) return null;
@@ -20,7 +42,9 @@ export function projectHooks({ targetDir, bundledHarnessDir }) {
     for (const [event, groups] of Object.entries(parsed.hooks || {})) {
         const kept = [];
         for (const group of groups) {
-            const hooks = (group.hooks || []).filter((h) => h.type === 'command');
+            const hooks = (group.hooks || [])
+                .filter((h) => h.type === 'command')
+                .map((h) => ({ ...h, command: toCodexCommand(h.command) }));
             if (hooks.length) kept.push({ ...group, hooks });
         }
         if (kept.length) out[event] = kept;

package/lib/codex/index.mjs

@@ -39,11 +39,12 @@ export function projectCodexArtifacts({
         owned.push(ownedPath);
     };
 
-    // AGENTS.md — exact copy of CLAUDE.md, with the CLAUDE.md backup-if-no-git rule.
-    collect(projectAgentsMd({ targetDir, bundledClaudeMd, projectHasGit }), 'AGENTS.md');
+    // AGENTS.md — CLAUDE.md copied byte-for-byte + a generated Codex runtime adapter derived from
+    // the bundled harness inventory (see agents-md.mjs), with the CLAUDE.md backup-if-no-git rule.
+    collect(projectAgentsMd({ targetDir, bundledClaudeMd, bundledHarnessDir, projectHasGit }), 'AGENTS.md');
     // .agents/skills — full-rebuilt mirror of the installed (already ship-filtered) .claude/skills.
     collect(projectSkills({ targetDir, projectHasGit }), '.agents/skills');
-    // .codex/agents — copy the shipped, pre-generated *.toml (see gen-agents.mjs).
+    // .codex/agents — copy the shipped, pre-authored *.toml (see docs/architecture/harness/authoring-agents.md).
     collect(copyCodexAgents({ targetDir, bundledHarnessDir, projectHasGit }), '.codex/agents');
     // .codex/hooks.json — Claude hooks.json filtered to type:"command".
     collect(projectHooks({ targetDir, bundledHarnessDir }), '.codex/hooks.json');

package/lib/codex/plugin-manifest.mjs

@@ -19,8 +19,13 @@ export function buildCodexPluginJson(fm, { hasHooks = false } = {}) {
     return out;
 }
 
-// The repo marketplace catalog Codex reads at .agents/plugins/marketplace.json.
-// Each plugin is a local source; the first keyword (if any) seeds a category.
+// The repo marketplace catalog Codex reads at .agents/plugins/marketplace.json. Each plugin is a
+// LOCAL source (source.path relative to the catalog root) carrying an explicit install policy:
+//   · installation AVAILABLE — offered, not force-installed (INSTALLED_BY_DEFAULT / NOT_AVAILABLE
+//     are the other documented tokens; these plugins are opt-in).
+//   · authentication NONE — they bundle only skills + hooks, no credentials or external auth.
+// The first keyword (if any) seeds a category. (Enum tokens per codex-support.md → Open Questions;
+// AVAILABLE/NONE are the correct pair for an opt-in, no-auth plugin.)
 export function buildCodexMarketplace(plugins) {
     return {
         name: 'nurixlabs',
@@ -29,7 +34,8 @@ export function buildCodexMarketplace(plugins) {
             .sort((a, b) => a.name.localeCompare(b.name))
             .map((p) => ({
                 name: p.name,
-                source: `./plugins/${p.name}`,
+                source: { path: `./plugins/${p.name}` },
+                policy: { installation: 'AVAILABLE', authentication: 'NONE' },
                 ...(p.frontmatter?.keywords?.length ? { category: p.frontmatter.keywords[0] } : {}),
             })),
     };

package/lib/codex/subagents.mjs

@@ -1,6 +1,6 @@
 // packages/cli/lib/codex/subagents.mjs
-// Copy the harness's pre-generated Codex subagent TOML — bundle codex/agents/*.toml,
-// authored on a Codex-authenticated laptop by gen-agents.mjs — into the project's
+// Copy the harness's pre-authored Codex subagent TOML — bundle codex/agents/*.toml,
+// authored per docs/architecture/harness/authoring-agents.md — into the project's
 // .codex/agents/. Full rebuild each run. The consumer needs NO Codex CLI: the TOML
 // ships ready, so a missing local Codex never blocks an install.
 

package/lib/codex/validate-codex-agents.mjs

@@ -0,0 +1,126 @@
+// packages/cli/lib/codex/validate-codex-agents.mjs
+// The Codex-twin validation gate — decoupled from any generator. A `<name>.codex.toml`
+// twin is now authored by the AI following docs/architecture/harness/authoring-agents.md,
+// so this is the check that keeps a malformed or Claude-only twin from shipping: the twins
+// are copied UNPARSED into the bundle (build-data.js) and a consumer's .codex/agents/, so
+// nothing else catches a bad one before Codex fails to load it in that repo. Run it after
+// authoring/editing a twin (the authoring-agents.md checklist mandates it) and, ideally, as
+// a fail-loud publish gate.
+//
+// Checks each twin for: valid TOML (python3 tomllib when present), the required keys
+// (name/description/developer_instructions), and runtime-neutrality (no Claude-only dispatch
+// primitives or fixed model tiers). Also flags a source agent with NO twin (out of sync).
+//
+// Usage:
+//   node packages/cli/lib/codex/validate-codex-agents.mjs             # shared catalog + all harnesses
+//   node packages/cli/lib/codex/validate-codex-agents.mjs --quiet     # errors only
+// Exits 0 when every twin is valid, 1 otherwise.
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(__dirname, '..', '..', '..', '..');
+const quiet = process.argv.slice(2).includes('--quiet');
+
+// Every source agent .md and its expected twin path: the shared catalog plus every harness's
+// owned agents. The .md is the authoritative set — a listed agent with no twin is out of sync.
+function collectAgents() {
+    const out = [];
+    const push = (dir) => {
+        if (!existsSync(dir)) return;
+        for (const f of readdirSync(dir)) {
+            if (!f.endsWith('.md')) continue;
+            const name = basename(f, '.md');
+            out.push({ name, mdPath: join(dir, f), tomlPath: join(dir, `${name}.codex.toml`) });
+        }
+    };
+    push(join(repoRoot, 'agents'));
+    const harnessDir = join(repoRoot, 'harness');
+    if (existsSync(harnessDir)) {
+        for (const harness of readdirSync(harnessDir)) {
+            if (harness === 'common') continue; // not a harness — the shared root-files folder
+            push(join(harnessDir, harness, 'agents'));
+        }
+    }
+    return out.sort((a, b) => a.tomlPath.localeCompare(b.tomlPath));
+}
+
+// TOML parse via python3's tomllib when present; '' = valid, a message = invalid, null =
+// python3 unavailable (the key + runtime-neutral regex checks still run, so the gate degrades
+// gracefully rather than passing blind — but CI/macOS both ship python3, so parse runs there).
+function tomlError(toml) {
+    const res = spawnSync('python3', ['-c', 'import tomllib,sys; tomllib.loads(sys.stdin.read())'], {
+        input: toml,
+        encoding: 'utf8',
+    });
+    if (res.error && res.error.code === 'ENOENT') return null;
+    return res.status === 0 ? '' : (res.stderr || 'invalid TOML').trim();
+}
+
+// A Codex twin runs under Codex, which has neither the Task tool nor Claude model aliases. The
+// md body is copied verbatim into developer_instructions, so a hit here is a hit in the SOURCE
+// agent. The dropped-tools comment lists bare names (`Task`, `Skill`) which are fine — only the
+// prose forms (`Task tool`/`Skill tool`) and model-tier aliases are rejected.
+const CLAUDE_ONLY_PATTERNS = [
+    { re: /Task tool/i, label: '"Task tool" (name the runtime-neutral outcome, not the Claude tool)' },
+    { re: /Skill tool/i, label: '"Skill tool" (refer to the skill by name, not the Claude tool)' },
+    { re: /subagent_type/i, label: '`subagent_type` (a Claude Agent-tool parameter)' },
+    { re: /\bhaiku\b/i, label: '"haiku" (a fixed Claude model tier — say "cheapest capable tier")' },
+    { re: /\bopus\b/i, label: '"opus" (a fixed Claude model tier — say "strongest tier")' },
+    { re: /\bsonnet\b/i, label: '"sonnet" (a fixed Claude model tier)' },
+];
+
+const REQUIRED_KEYS = ['name', 'description', 'developer_instructions'];
+
+// Return the list of problems with one twin (empty ⇒ valid).
+function validateTwin(tomlPath) {
+    const problems = [];
+    const toml = readFileSync(tomlPath, 'utf8');
+    for (const key of REQUIRED_KEYS) {
+        if (!new RegExp(`^\\s*${key}\\s*=`, 'm').test(toml)) problems.push(`missing \`${key} =\` key`);
+    }
+    const err = tomlError(toml);
+    if (err) problems.push(`invalid TOML: ${err.split('\n').pop().slice(0, 160)}`);
+    for (const { re, label } of CLAUDE_ONLY_PATTERNS) {
+        if (re.test(toml)) problems.push(`Claude-only primitive: ${label}`);
+    }
+    return problems;
+}
+
+function main() {
+    const agents = collectAgents();
+    if (!agents.length) {
+        console.error('validate-codex-agents: no agents/*.md found.');
+        process.exit(1);
+    }
+    let ok = 0;
+    const failures = [];
+    for (const { name, tomlPath } of agents) {
+        if (!existsSync(tomlPath)) {
+            failures.push(`${name}: no twin at ${relPath(tomlPath)} (source .md has no .codex.toml — out of sync)`);
+            continue;
+        }
+        const problems = validateTwin(tomlPath);
+        if (problems.length) {
+            failures.push(`${relPath(tomlPath)}:\n${problems.map((p) => `    - ${p}`).join('\n')}`);
+        } else {
+            ok += 1;
+            if (!quiet) console.log(`  ok  ${relPath(tomlPath)}`);
+        }
+    }
+    if (failures.length) {
+        console.error(`\nvalidate-codex-agents: ${failures.length} invalid, ${ok} ok of ${agents.length} twin(s):\n`);
+        for (const f of failures) console.error(`  ✗ ${f}`);
+        process.exit(1);
+    }
+    console.log(`\nvalidate-codex-agents: all ${ok} twin(s) valid.`);
+}
+
+function relPath(p) {
+    return p.startsWith(repoRoot) ? p.slice(repoRoot.length + 1) : p;
+}
+
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nurix/etna",
-    "version": "0.19.22",
+    "version": "0.19.23",
     "description": "Bootstrap a project with a Nurix harness — copies the harness's CLAUDE.md, skills, agents, rules, and hooks directly into the project from a bundled payload (no marketplace fetch, no network).",
     "type": "module",
     "bin": {
@@ -21,7 +21,7 @@
     "scripts": {
         "build:data": "node scripts/build-data.js",
         "prepack": "node scripts/build-data.js",
-        "gen:codex-agents": "node lib/codex/gen-agents.mjs"
+        "validate:codex-agents": "node lib/codex/validate-codex-agents.mjs"
     },
     "repository": {
         "type": "git",