phronesis 1.0.0

package/README.md

@@ -0,0 +1,66 @@
+# phronesis
+
+The Phronesis CLI. Ports the pming scaffold (ESM + enquirer/chalk/fs-extra/slugify)
+forward to the three-layer installation layout, leaving pming's two-layer `context/`
+assumptions behind.
+
+## Usage
+
+```
+npx phronesis init [dir]            # default dir: phronesis-installation
+npx phronesis init . --force        # replace a non-empty target
+npx phronesis init . --domain pm    # choose the domain workspace (default: pm)
+
+# Minimal operator profile (fills USER.md + AGENTS.md §1; no [Name]/[Role] dead air):
+npx phronesis init . --name "Ada Lovelace" --role "Founder"
+#   optional, USER.md-only:  --company "Analytical Engines"  --working-style "async, terse"
+#   On a terminal, a missing --name/--role is prompted. A non-interactive (scripted/CI) init
+#   never prompts or blocks — it completes and leaves the placeholders.
+```
+
+The published V1.0 package exposes only the `phronesis` binary; `pming` remains
+the historical reference name, not a public install alias.
+
+## What `init` creates (specs/workspace-substrate.md)
+
+```
+<dir>/
+├── codex/            Layer 3 — shared across all domains (seed/ + personal/)
+├── domains/
+│   └── pm/           a domain workspace
+│       ├── raw/      Layer 1 — append-only source material
+│       ├── compiled/ Layer 2 — durable current state
+│       ├── memory/   session-scoped working memory
+│       └── exports/  disposable renders
+├── skills/
+└── .phronesis/       runtime + configuration (registry.json)
+```
+
+Source of truth is the folder: plain Markdown, no database, no upload step.
+
+## Scope
+
+`init` only — the three-layer **structure** (core-0001 / T1.1). Deliberately
+deferred to later packets:
+
+- Session-file content — `AGENTS.md`, the `CLAUDE.md` / `.cursorrules` symlinks,
+  `USER.md`, `MEMORY.md`, `codex/INDEX.md` (T1.2).
+- Immutable PM-shaped seed principles in `codex/seed/` (T5.4).
+- Daemon (`phronesisd`), hooks, action types, event log (T2.x / T4.x).
+- `MIGRATION.md` for existing pming workspaces (T1.x follow-up).
+
+## Tests
+
+```
+npm run -w phronesis test           # node --test: asserts the generated layout
+npm run -w phronesis sync-package-assets
+```
+
+The same end-to-end scaffold is exercised by `harness/fitness/validate-workspace`,
+which graduated from a docs-only stub to enforcing the export-shape invariant
+(plain folders, no legacy `context/`) once this CLI landed. Model-swap and
+skill-portability stay PENDING until the compile/retrieve loop exists (ADR 0001).
+
+`sync-package-assets` refreshes the tracked publish assets from their canonical
+sources: root `skills/` into `templates/skills/`, and `packages/core` into
+`vendor/core`. The fitness gate fails if either tracked copy drifts.

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "phronesis",
+  "version": "1.0.0",
+  "private": false,
+  "type": "module",
+  "description": "Phronesis CLI + daemon. Ports the pming scaffold forward to the three-layer installation layout.",
+  "bin": {
+    "phronesis": "src/cli.js"
+  },
+  "scripts": {
+    "prepack": "node scripts/mirror-skills.mjs check",
+    "prepublishOnly": "node scripts/verify-installability.mjs",
+    "sync-package-assets": "node scripts/mirror-skills.mjs sync",
+    "test": "node --test test/*.test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src",
+    "templates",
+    "vendor"
+  ],
+  "dependencies": {
+    "@phronesis/core": "file:vendor/core",
+    "chalk": "^5.6.2",
+    "enquirer": "^2.4.1",
+    "fs-extra": "^11.3.3",
+    "js-yaml": "^4.1.0",
+    "lunr": "^2.3.9",
+    "slugify": "^1.6.6"
+  },
+  "license": "MIT"
+}

package/src/act.js

@@ -0,0 +1,61 @@
+// `phronesis act <type> --json '<payload>'` — the action-type execution floor
+// (core-0008 / T2.2; ontology.md §"Action type contract"; change 0008). Plumbing, not
+// porcelain: a named internal surface skills compose and adapters/tests target, kept
+// out of the top-level --help. This handler ONLY parses and delegates (D7) — every
+// check, event, gate, and write lives behind runAction in @phronesis/core, so the CLI
+// and any direct caller are the same action.
+//
+// Input discipline: SEMANTIC action inputs (titles, slugs, insights, links) live inside
+// --json and are schema-validated by the core; flags carry only EXECUTION CONTEXT
+// (--session/--domain/--actor/--surface/--dir). The approval signal (D5) is the
+// adapter-set env PHRONESIS_APPROVAL_SOURCE — deliberately not a flag and not payload.
+
+import { resolveInvocationIdForAct, runAction } from '@phronesis/core';
+
+export async function runAct({ type, json, session, domain, actor, surface, dir, invocationId } = {}) {
+  if (!type) {
+    console.error('act: name an action <type> (e.g. log_decision).');
+    process.exitCode = 1;
+    return null;
+  }
+  let payload;
+  try {
+    payload = json === undefined ? {} : JSON.parse(json);
+  } catch {
+    console.error('act: --json must be valid JSON.');
+    process.exitCode = 1;
+    return null;
+  }
+
+  try {
+    const resolvedInvocation = await resolveInvocationIdForAct({
+      dir,
+      cwd: process.cwd(),
+      session,
+      callerInvocationId: invocationId,
+      envInvocationId: process.env.PHRONESIS_INVOCATION_ID,
+      surface: surface || 'cli',
+    });
+    const result = await runAction({
+      type,
+      payload,
+      ctx: {
+        dir,
+        cwd: process.cwd(),
+        session,
+        domain,
+        actor: actor || process.env.PHRONESIS_ACTOR || undefined,
+        surface,
+        invocation_id: resolvedInvocation.invocation_id,
+        approvalSource: process.env.PHRONESIS_APPROVAL_SOURCE || undefined,
+      },
+    });
+    console.log(JSON.stringify(result));
+    process.exitCode = 0;
+    return result;
+  } catch (err) {
+    console.error(`act: ${err.message}`);
+    process.exitCode = 1;
+    return null;
+  }
+}

package/src/active-context.js

@@ -0,0 +1,56 @@
+// `phronesis active-context refresh --domain <slug>` (core-0017 H5) — regenerate the
+// domain's tracked active-context projection (domains/{domain}/ACTIVE_CONTEXT.md) from its
+// compiled/ state. Plumbing, not porcelain: the post-compile hook shells out to this on
+// every compile commit, and the validate-time staleness check is its backstop. The
+// generator is deterministic and lives in @phronesis/core (refreshActiveContext) — this
+// surface only resolves the install, refuses a phantom domain, and delegates.
+
+import { join } from 'node:path';
+import fse from 'fs-extra';
+import { resolveInstall, refreshActiveContext } from '@phronesis/core';
+
+export async function runActiveContextRefresh({ dir, domain, json = false } = {}) {
+  if (!domain) {
+    console.error('active-context refresh: --domain <slug> is required.');
+    process.exitCode = 1;
+    return null;
+  }
+  const installed = resolveInstall({ dir, cwd: process.cwd() });
+  if (installed.error) {
+    console.error(installed.error);
+    process.exitCode = 1;
+    return null;
+  }
+  const installRoot = installed.root;
+
+  let registry;
+  try {
+    registry = await fse.readJson(join(installRoot, '.phronesis', 'registry.json'));
+  } catch (err) {
+    console.error(`active-context refresh: could not read the install registry: ${err.message}`);
+    process.exitCode = 1;
+    return null;
+  }
+  // Never conjure a domains/{slug}/ tree as a side effect (the resolveDomain posture,
+  // applied to the projection generator) — refuse an unregistered domain.
+  const registered = Array.isArray(registry.domains) ? registry.domains : [];
+  if (!registered.includes(domain)) {
+    console.error(
+      `active-context refresh: domain "${domain}" is not registered in this installation (registered: ${registered.join(', ') || 'none'}).`,
+    );
+    process.exitCode = 1;
+    return null;
+  }
+
+  try {
+    const res = await refreshActiveContext({ installRoot, domain });
+    if (json) console.log(JSON.stringify(res));
+    else console.log(`active-context: refreshed ${res.path}`);
+    process.exitCode = 0;
+    return res;
+  } catch (err) {
+    console.error(`active-context refresh: ${err.message}`);
+    process.exitCode = 1;
+    return null;
+  }
+}

package/src/adapter.js

@@ -0,0 +1,386 @@
+// `phronesis adapter test <surface>` — the per-surface adapter self-check
+// (specs/tech-stack.md §"Adapter test command"; specs/event-log.md §"Adapter test";
+// change 0028 / core-0034). V1 ships the Codex adapter test: it asserts the deterministic
+// emission + install-root-resolution mechanics of the project-local .codex/ wiring and
+// reports the compliance LEVEL — Level 1 (reinforcement) and whether Level 2
+// (skill-lifecycle) is met or partial — then points at the operator-verified desktop-app
+// checklist (the app half a CLI cannot auto-assert). It is read-only: it writes no
+// canonical state and emits no events.
+
+import { join } from 'node:path';
+import { readFileSync, statSync, existsSync, mkdtempSync, writeFileSync, chmodSync, rmSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { resolveInstall, RE_SLUG } from '@phronesis/core';
+import { CODEX_ADAPTER_HOOKS, CODEX_SURFACE_RESOLVER } from './layout.js';
+import { validateCodexHooksSchema } from './codex-hooks-schema.js';
+
+// The Codex adapter event→launcher→script→tier contract is the single source in layout.js
+// (alongside the templateCopies that emit it), so this self-check can never validate
+// against a wiring different from what init actually wrote.
+const HOOKS = CODEX_ADAPTER_HOOKS;
+
+const DESKTOP_CHECKLIST = 'docs/surface-setup.md';
+
+// Read the install's domains from the registry (the adapter test runs against the
+// domain workspace open target — domains/{slug}/.codex/). Falls back to 'pm'.
+function installDomains(root) {
+  try {
+    const reg = JSON.parse(readFileSync(join(root, '.phronesis', 'registry.json'), 'utf8'));
+    // Validate members are kebab-case SLUGs (RE_SLUG — core-0038 F2/round-3): a `[null]`/`[{}]` would
+    // reach checkEmission's path.join as a non-string and throw; a `"../outside"`/`"pm/evil"` would
+    // path-traverse out of the domains namespace. Either breaks codexAdapterReport's
+    // `{ root, report } | { error }` contract / fail-closed posture. A malformed/empty list falls
+    // back to the default domain.
+    const valid = Array.isArray(reg.domains) ? reg.domains.filter((d) => typeof d === 'string' && RE_SLUG.test(d)) : [];
+    if (valid.length) return valid;
+  } catch {
+    /* fall through */
+  }
+  return ['pm'];
+}
+
+function isExecutable(p) {
+  try {
+    const st = statSync(p);
+    // A runnable launcher/script must be a REGULAR file with an exec bit — a directory carries the
+    // exec bit too (0755) and would otherwise read as a runnable script (core-0038 Codex round-3 F1).
+    return st.isFile() && Boolean(st.mode & 0o111);
+  } catch {
+    return false;
+  }
+}
+
+// Structural: the emitted domains/{slug}/.codex/ wiring matches the CODEX_ADAPTER_HOOKS
+// contract — hooks.json present + parseable, each event wired to its bare relative
+// launcher path, each launcher present + executable + handing off to its shared script,
+// each shared script present. Returns { checks: [...], compliant: bool }.
+function checkEmission(root, slug) {
+  const checks = [];
+  const add = (ok, label, detail = '') => checks.push({ ok, label, detail });
+  const codexDir = join(root, 'domains', slug, '.codex');
+  const hooksJsonPath = join(codexDir, 'hooks.json');
+
+  if (!existsSync(hooksJsonPath)) {
+    add(false, `domains/${slug}/.codex/hooks.json present`, 'missing — run `phronesis init`');
+    return { checks, compliant: false };
+  }
+  let config;
+  try {
+    config = JSON.parse(readFileSync(hooksJsonPath, 'utf8'));
+  } catch (err) {
+    add(false, `domains/${slug}/.codex/hooks.json parses`, err.message);
+    return { checks, compliant: false };
+  }
+  add(true, `domains/${slug}/.codex/hooks.json present + parses`);
+  const schema = validateCodexHooksSchema(config, { source: `domains/${slug}/.codex/hooks.json` });
+  add(
+    schema.ok,
+    `domains/${slug}/.codex/hooks.json schema-pure (Codex strict parser)`,
+    schema.ok ? '' : schema.errors.join('; '),
+  );
+  if (!schema.ok) return { checks, compliant: false };
+
+  // The shared resolver the launchers source — infrastructure, not an event hook, but
+  // every launcher fails to source it if it is absent, so it must ship + be present.
+  const resolverPath = join(codexDir, 'hooks', CODEX_SURFACE_RESOLVER);
+  add(existsSync(resolverPath), `resolver ${CODEX_SURFACE_RESOLVER} present`, existsSync(resolverPath) ? '' : 'missing — launchers cannot resolve the install root');
+
+  const hooks = (config && config.hooks) || {};
+  // Exact-set match against the contract: an event wired in hooks.json but absent from
+  // CODEX_ADAPTER_HOOKS (a hand-edit, or a template that drifted ahead of the constant) is
+  // unvetted wiring — flag it, don't silently accept it (core-0034 review #4).
+  const contractEvents = new Set(HOOKS.map((h) => h.event));
+  const extras = Object.keys(hooks).filter((e) => !contractEvents.has(e));
+  add(extras.length === 0, 'no events wired beyond the adapter contract', extras.length ? `unexpected: ${extras.join(', ')}` : '');
+
+  for (const h of HOOKS) {
+    // EXACT contract, not just "[0] matches": exactly ONE entry per event, each with exactly
+    // ONE command. A second entry under a contracted event (or a second command nested in the
+    // entry) pointing at an uncontracted script is unvetted wiring a `[0]`-only read sails past
+    // — a hand-edit or a template drifted ahead of the constant. Reject it (core-0034 review #3).
+    const entries = Array.isArray(hooks[h.event]) ? hooks[h.event] : [];
+    const oneEntry = entries.length === 1;
+    // Guard EVERY member access: a hand-edited hooks.json can carry a null entry or null command
+    // (`[null]`, or `{hooks:[null]}` from a trailing comma / half-deleted block). The check must
+    // report compliant:false on those, never crash — checkEmission is NOT wrapped in try/catch,
+    // so an unguarded deref would abort the operator-facing self-check + its --json consumers.
+    const innerHooks = oneEntry && entries[0] && Array.isArray(entries[0].hooks) ? entries[0].hooks : [];
+    const oneCommand = innerHooks.length === 1;
+    const command = oneCommand && innerHooks[0] ? innerHooks[0].command : undefined;
+    const expected = `.codex/hooks/${h.launcher}`;
+    // Bare, relative, no-argument command (the variant flag is baked into the launcher so
+    // the wiring holds whether Codex execs directly or via a shell — core-0034).
+    const wired = oneEntry && oneCommand && command === expected;
+    const wiredDetail = !oneEntry
+      ? `${entries.length} hook entries wired (contract: exactly 1)`
+      : !oneCommand
+        ? `${innerHooks.length} commands under the entry (contract: exactly 1)`
+        : wired
+          ? ''
+          : `got: ${JSON.stringify(command)}`;
+    add(wired, `${h.event} → ${expected} (exactly one entry + command)`, wiredDetail);
+
+    const launcherPath = join(codexDir, 'hooks', h.launcher);
+    const launcherOk = existsSync(launcherPath) && isExecutable(launcherPath);
+    add(launcherOk, `launcher ${h.launcher} present + executable`, launcherOk ? '' : 'missing or not +x');
+
+    const scriptPath = join(root, '.phronesis', 'hooks', h.script);
+    const scriptOk = existsSync(scriptPath) && isExecutable(scriptPath);
+    add(scriptOk, `shared script .phronesis/hooks/${h.script} present + executable`, scriptOk ? '' : 'missing or not +x');
+  }
+
+  return { checks, compliant: checks.every((c) => c.ok) };
+}
+
+// Behavioral: run the reinforcement launchers (Stop, UserPromptSubmit, SessionStart) through
+// scripted events and assert each not only REACHES the right `phronesis` subcommand but produces
+// the operator-facing OUTPUT — for recall + due-check, the Codex hookSpecificOutput.additionalContext
+// envelope that actually injects the packet. Reaching `guard`/`due-check` but emitting nothing is
+// NOT recall injection (core-0034 review, round 4). The shim never execs the real CLI: it logs argv
+// AND returns CANNED guard JSON / due-check text — so the shared scripts run their envelope
+// formatting while this self-check stays non-mutating by construction (the REAL guard emits
+// recall.candidate/injected and due-check emits outcome.due/session.start, none of which may touch
+// the operator's install; the shim writes nothing and spawns nothing). A launcher OR its shared
+// .phronesis/hooks/ script replaced by a bare `exit 0` (present + executable, so the structural
+// emission check still passes), or one that calls the subcommand but drops its output, never
+// produces the envelope — so the probe fails (the "Level-1 compliant while recall is dead" gap).
+// Asserts: (a) Stop emits {"decision":"block"} (its own `node -e`, surfaces behind the shim) and
+// reaches `hooks sweep-status`; (b) UserPromptSubmit reaches `guard --surface codex` AND wraps the
+// guard packet into a UserPromptSubmit additionalContext envelope; (c) SessionStart wraps the
+// due-check text into a SessionStart additionalContext envelope; (d) the install root resolves from
+// a SUBDIR of the open target (its block reason carries `--dir <root>`, resolved in-shell).
+function checkBehavior(root, slug) {
+  const checks = [];
+  const add = (ok, label, detail = '') => checks.push({ ok, label, detail });
+  const codexHooks = join(root, 'domains', slug, '.codex', 'hooks');
+  const sweepLauncher = join(codexHooks, 'session-sweep.sh');
+  if (!existsSync(sweepLauncher)) {
+    add(false, 'Stop launcher runnable', 'session-sweep.sh launcher missing');
+    return { checks, compliant: false };
+  }
+
+  // Sentinels the shim feeds back as the guard packet / due-check text; the probes assert these
+  // survive into the emitted additionalContext envelope (proves the shared script wrapped them).
+  // PER-RUN NONCE, not a fixed literal: a constant sentinel could be satisfied by a shared script
+  // that hardcodes the envelope without wrapping anything (a vacuous pass — review round 4); a
+  // value the shared script cannot know forces it to actually carry THIS run's result through.
+  const nonce = randomBytes(8).toString('hex');
+  const RECALL_SENTINEL = `ADAPTER_PROBE_RECALL_${nonce}`;
+  const DUE_SENTINEL = `ADAPTER_PROBE_DUE_${nonce}`;
+
+  let shimDir;
+  try {
+    shimDir = mkdtempSync(join(tmpdir(), 'phronesis-adapter-'));
+    const argvLog = join(shimDir, 'argv.log');
+    const shim = join(shimDir, 'phronesis');
+    // Logs argv, returns CANNED output for the two subcommands whose result the shared scripts
+    // wrap into an envelope (`guard` → a fired recall result; `hooks due-check` → due text), and
+    // exits 0 for everything else (sweep-status, skill-sweep-stale, event emit, …) — so the Stop
+    // sweep reads "unswept" and NOTHING is execed or written (non-mutating). `$1`/`$2`/`$*` are
+    // literal shell, not JS interpolation (no `${`).
+    writeFileSync(
+      shim,
+      [
+        '#!/usr/bin/env bash',
+        `printf '%s\\n' "$*" >> ${JSON.stringify(argvLog)}`,
+        'case "$1" in',
+        `  guard) printf '%s' '{"fired":true,"packet":"${RECALL_SENTINEL}"}' ;;`,
+        `  hooks) case "$2" in due-check) printf '%s' '${DUE_SENTINEL}' ;; esac ;;`,
+        'esac',
+        'exit 0',
+        '',
+      ].join('\n'),
+    );
+    chmodSync(shim, 0o755);
+    const env = { ...process.env, PATH: `${shimDir}:${process.env.PATH || ''}` };
+    const target = join(root, 'domains', slug);
+    const readLog = () => {
+      try {
+        return readFileSync(argvLog, 'utf8');
+      } catch {
+        return '';
+      }
+    };
+    const runLauncher = (name, cwd, input) => spawnSync('bash', [join(codexHooks, name)], { cwd, env, input, encoding: 'utf8' });
+    // True iff stdout is exactly a Codex hookSpecificOutput envelope for `hookEventName` whose
+    // additionalContext carries `sentinel` (i.e. the shared script wrapped the canned result).
+    const envelopeInjects = (stdout, hookEventName, sentinel) => {
+      try {
+        const j = JSON.parse(String(stdout || '').trim());
+        return j?.hookSpecificOutput?.hookEventName === hookEventName && String(j?.hookSpecificOutput?.additionalContext ?? '').includes(sentinel);
+      } catch {
+        return false;
+      }
+    };
+    const stopFixture = '{"session_id":"adapter_probe","stop_hook_active":false}';
+
+    // (a) Stop emission shape + reaches sweep-status, run from the open target.
+    const atTarget = runLauncher('session-sweep.sh', target, stopFixture);
+    const blocks = atTarget.status === 0 && /"decision":"block"/.test(atTarget.stdout || '');
+    add(blocks, 'Stop emits {"decision":"block"} (Codex capture-sweep shape)', blocks ? '' : (atTarget.stderr || atTarget.stdout || '').trim());
+    const sweepReached = /(^|\n)hooks sweep-status\b/.test(readLog());
+    add(sweepReached, 'Stop sweep reaches `phronesis hooks sweep-status`', sweepReached ? '' : 'the shared session-sweep.sh never invoked sweep-status (stubbed/broken script?)');
+
+    // (b) UserPromptSubmit recall: reaches `guard --surface codex` (surface attribution) AND wraps
+    // the guard packet into the additionalContext envelope (the actual injection — reaching guard
+    // but emitting nothing is not recall, round 4).
+    const recallLauncher = join(codexHooks, 'recall-guard.sh');
+    if (existsSync(recallLauncher)) {
+      const recall = runLauncher('recall-guard.sh', target, '{"session_id":"adapter_probe","prompt":"Should I wait before deciding?"}');
+      const guardReached = /(^|\n)guard .*--surface codex\b/.test(readLog());
+      add(guardReached, 'UserPromptSubmit recall reaches `phronesis guard --surface codex`', guardReached ? '' : 'the shared recall-guard.sh never invoked guard (stubbed/broken script?)');
+      const recallInjected = envelopeInjects(recall.stdout, 'UserPromptSubmit', RECALL_SENTINEL);
+      add(recallInjected, 'UserPromptSubmit recall injects the packet as hookSpecificOutput.additionalContext', recallInjected ? '' : 'recall-guard.sh reached guard but emitted no Codex additionalContext envelope — the operator gets no injection');
+    } else {
+      add(false, 'UserPromptSubmit recall launcher runnable', 'recall-guard.sh launcher missing');
+    }
+
+    // (c) SessionStart due-check: wraps the due-check text into the SessionStart additionalContext
+    // envelope. This subsumes "reached due-check" — the sentinel only originates from the due-check
+    // shim response, so its presence proves the chain ran AND wrapped (round 4).
+    const startLauncher = join(codexHooks, 'session-start.sh');
+    if (existsSync(startLauncher)) {
+      const start = runLauncher('session-start.sh', target, '{"session_id":"adapter_probe","source":"startup"}');
+      const dueInjected = envelopeInjects(start.stdout, 'SessionStart', DUE_SENTINEL);
+      add(dueInjected, 'SessionStart due-check injects via hookSpecificOutput.additionalContext', dueInjected ? '' : 'session-start.sh reached due-check but did not wrap it in the Codex SessionStart additionalContext envelope');
+    } else {
+      add(false, 'SessionStart launcher runnable', 'session-start.sh launcher missing');
+    }
+
+    // (d) install-root resolution from a subdir of the open target (nearest-.phronesis walk-up).
+    // The launcher runs from the kernel-realpath'd cwd, so it emits the realpath of the install
+    // root; compare realpaths so a symlinked prefix (macOS /var → /private/var) is not a false
+    // failure. The block reason's `--dir` is resolved in-shell, independent of the shim.
+    const subdir = join(target, 'raw', 'inbox');
+    const fromSub = runLauncher('session-sweep.sh', existsSync(subdir) ? subdir : target, stopFixture);
+    let realRoot = root;
+    try {
+      realRoot = realpathSync(root);
+    } catch {
+      /* keep root */
+    }
+    const out = fromSub.stdout || '';
+    const resolved = fromSub.status === 0 && (out.includes(`--dir ${realRoot}`) || out.includes(`--dir ${root}`));
+    add(resolved, 'install root resolves from a subdirectory of the open target', resolved ? '' : (fromSub.stderr || out).trim());
+  } catch (err) {
+    add(false, 'behavioral probe ran', err.message);
+  } finally {
+    if (shimDir) rmSync(shimDir, { recursive: true, force: true });
+  }
+
+  return { checks, compliant: checks.every((c) => c.ok) };
+}
+
+// structuralOnly (core-0038 F1): run ONLY the read-only emission check (parses hooks.json, checks
+// launcher/script presence + executability — pure file reads, NO spawning). `checkBehavior` EXECUTES
+// the install's hook scripts via spawnSync; that is fine for `adapter test codex` (a deliberate
+// operator self-check) but NOT for `phronesis doctor`, whose read-only promise must hold even on a
+// MODIFIED install — a tampered hook could write to the install before satisfying the probe. So
+// doctor passes structuralOnly:true (no execution); the full behavioral probe stays in adapter test.
+function buildReport(root, domains, { structuralOnly = false } = {}) {
+  const perDomain = domains.map((slug) => {
+    const emission = checkEmission(root, slug);
+    // Only probe behavior when the wiring is structurally present (else the probe just
+    // re-reports the same missing files as opaque spawn failures) AND behavior was requested.
+    const behavior = !structuralOnly && emission.compliant ? checkBehavior(root, slug) : { checks: [], compliant: emission.compliant, skipped: structuralOnly || undefined };
+    return { domain: slug, emission, behavior };
+  });
+
+  const mechanicsOk = structuralOnly
+    ? perDomain.every((d) => d.emission.compliant)
+    : perDomain.every((d) => d.emission.compliant && (d.emission.compliant ? d.behavior.compliant : false));
+  // Level 1 = the reinforcement loop is correctly wired + fires (recall / due-check /
+  // sweep). Level 2 (skill.invoked/completed) is PARTIAL on Codex by contract: no
+  // UserPromptExpansion / StopFailure / matchable Skill PreToolUse, so no invocation_id is
+  // minted and NO fabricated lifecycle events are emitted (event-log.md; change 0021).
+  const reinforcementEvents = HOOKS.filter((h) => h.tier === 'reinforcement').map((h) => h.role);
+  return {
+    surface: 'codex',
+    install: root,
+    level_1: { name: 'reinforcement', status: mechanicsOk ? 'compliant' : 'non-compliant', wires: reinforcementEvents },
+    level_2: {
+      name: 'skill-lifecycle',
+      status: 'partial',
+      reason: 'Codex has no UserPromptExpansion / StopFailure / matchable Skill PreToolUse — no invocation_id minted; no fabricated skill.invoked/completed (change 0021).',
+    },
+    desktop_app: { status: 'operator-verified', evidence: 'spike-discharged 2026-06-21 (CLI + desktop app)', checklist: DESKTOP_CHECKLIST },
+    domains: perDomain,
+    compliant: mechanicsOk,
+  };
+}
+
+function printHuman(report) {
+  const mark = (ok) => (ok ? '✓' : '✗');
+  console.log(`phronesis adapter test codex — ${report.install}`);
+  console.log('');
+  for (const d of report.domains) {
+    console.log(`  domains/${d.domain}/.codex/`);
+    for (const c of [...d.emission.checks, ...d.behavior.checks]) {
+      console.log(`    ${mark(c.ok)} ${c.label}${c.detail ? ` — ${c.detail}` : ''}`);
+    }
+    console.log('');
+  }
+  console.log(`  Level 1 (reinforcement):  ${report.level_1.status.toUpperCase()} — wires ${report.level_1.wires.join(', ')}`);
+  console.log(`  Level 2 (skill-lifecycle): PARTIAL — ${report.level_2.reason}`);
+  console.log(`  Desktop app: operator-verified (${report.desktop_app.evidence}). Re-confirm via ${report.desktop_app.checklist}`);
+  console.log('');
+  console.log(
+    report.compliant
+      ? '  Codex adapter is correctly wired: Level-1 reinforcement compliant (with the skill-lifecycle-partial note).'
+      : '  Codex adapter is NOT correctly wired — see the failed checks above; re-run `phronesis init`.',
+  );
+  console.log('');
+  console.log('  Trust: open Codex AT the domain workspace dir above (Codex does not parent-walk to find .codex/).');
+  console.log('  Enable the project hooks: CLI `/hooks`, or the app Settings → Coding → Hooks. Editing the config re-hashes → re-trust.');
+}
+
+// PURE Codex-adapter report (core-0038 D2/D3): resolve the install + build the structural +
+// behavioral report with NO console output and NO process.exitCode side-effect. `runAdapterTest`
+// (the CLI wrapper, which keeps print + exit) AND `phronesis doctor` both consume it, so the
+// diagnosis can never disagree. `buildReport` is already pure — its only writes are an ephemeral
+// OS-temp shim OUTSIDE the install (core-0034 proved the install is byte-identical after a run),
+// so composing it keeps `doctor` install-read-only. Returns { root, report } or { error }.
+export function codexAdapterReport({ dir, domain, structuralOnly = false } = {}) {
+  const r = resolveInstall({ dir });
+  if (r.error) return { error: r.error };
+  // The EXPLICIT domain override must also be a kebab-case slug (core-0038 Codex round-4 F1): the
+  // registry path is RE_SLUG-filtered, but an unchecked `--domain ../../x` would path-traverse out
+  // of domains/{slug} — and checkBehavior EXECUTES the launcher it finds there (spawnSync). Fail
+  // closed on a non-slug override before any path is built.
+  if (domain !== undefined && !(typeof domain === 'string' && RE_SLUG.test(domain))) {
+    return { error: `adapter test: invalid --domain "${domain}" — a domain is a kebab-case slug (no path separators or traversal).` };
+  }
+  const root = r.root;
+  const domains = domain ? [domain] : installDomains(root);
+  return { root, report: buildReport(root, domains, { structuralOnly }) };
+}
+
+export async function runAdapterTest({ surface, dir, domain, json = false } = {}) {
+  if (!surface) {
+    console.error('adapter test: a <surface> is required (V1: codex).');
+    process.exitCode = 1;
+    return null;
+  }
+  if (surface !== 'codex') {
+    console.error(`adapter test: unsupported surface "${surface}". V1 ships the Codex adapter test (claude-code is the primary, always-on surface).`);
+    process.exitCode = 1;
+    return null;
+  }
+
+  const res = codexAdapterReport({ dir, domain });
+  if (res.error) {
+    console.error(res.error);
+    process.exitCode = 1;
+    return null;
+  }
+  const report = res.report;
+  if (json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    printHuman(report);
+  }
+  process.exitCode = report.compliant ? 0 : 1;
+  return report;
+}