phronesis 1.0.0

package/src/init.js

@@ -0,0 +1,150 @@
+import { resolve, relative, isAbsolute, join } from 'node:path';
+import fse from 'fs-extra';
+import chalk from 'chalk';
+import slugify from 'slugify';
+import { createInstallation } from './scaffold.js';
+import { confirmOverwrite, promptProfile } from './prompts.js';
+import { resolveProfile } from './profile.js';
+import { DEFAULT_DOMAIN } from './layout.js';
+
+const DEFAULT_DIR = 'phronesis-installation';
+
+// True if `child` is `parent` or nested under it. Used to refuse deleting the
+// directory the process is standing in (or any ancestor of it).
+function isInsideOrEqual(child, parent) {
+  const rel = relative(parent, child);
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+
+// Recognize a prior Phronesis installation by its registry. Only a directory we
+// can identify as our own is eligible for destructive replacement — Phronesis
+// never deletes data it did not create (specs/security.md: agents do not delete).
+async function isPhronesisInstall(dir) {
+  return fse.pathExists(join(dir, '.phronesis', 'registry.json'));
+}
+
+export async function init({ dir, force = false, domain, name, role, company, workingStyle } = {}) {
+  const targetDir = resolve(process.cwd(), dir || DEFAULT_DIR);
+  const domainSlug = slugify(domain || DEFAULT_DOMAIN, { lower: true, strict: true }) || DEFAULT_DOMAIN;
+  if (domain && domainSlug !== domain) {
+    console.error(`Note: --domain "${domain}" normalized to "${domainSlug}".`);
+  }
+  if (domainSlug !== DEFAULT_DOMAIN) {
+    console.error(
+      `Note: V1 ships PM-shaped templates — the "${domainSlug}" domain gets PM-door ` +
+        'content until its own door exists.',
+    );
+  }
+
+  // Never delete the ground we stand on (covers `init .`, `init ..`, `init ~`).
+  if (isInsideOrEqual(process.cwd(), targetDir)) {
+    console.error(
+      `Refusing to initialize ${targetDir}: it is the current directory (or an ancestor). ` +
+        'Run init from the parent and pass a subdirectory name.',
+    );
+    process.exitCode = 1;
+    return { cancelled: true };
+  }
+
+  let mustRemove = false;
+  if (await fse.pathExists(targetDir)) {
+    const entries = await fse.readdir(targetDir);
+    if (entries.length > 0) {
+      if (!(await isPhronesisInstall(targetDir))) {
+        console.error(
+          `Refusing to overwrite ${targetDir}: it is not empty and is not a Phronesis ` +
+            'installation. Phronesis does not delete data it did not create — remove it ' +
+            'yourself or choose an empty target.',
+        );
+        process.exitCode = 1;
+        return { cancelled: true };
+      }
+      // A prior Phronesis install — replacement is in-bounds, but still confirm.
+      if (!force) {
+        if (process.stdin.isTTY) {
+          const ok = await confirmOverwrite(targetDir);
+          if (!ok) {
+            console.log('Setup cancelled.');
+            return { cancelled: true };
+          }
+        } else {
+          console.error(
+            `${targetDir} already holds a Phronesis installation. Re-run with --force to replace it.`,
+          );
+          process.exitCode = 1;
+          return { cancelled: true };
+        }
+      }
+      // Replace it — but DEFER the destructive remove until the profile is validated below, so a bad
+      // --name/--role never deletes an existing install without a replacement (Codex round-1 F1).
+      mustRemove = true;
+    }
+    // An existing empty dir is fine to scaffold into; nothing to remove.
+  }
+
+  // Resolve the minimal operator profile (flags + a TTY-only prompt for missing name/role), AFTER the
+  // re-init refusals (never prompt then refuse) but BEFORE the destructive remove below. An over-long
+  // value fails closed HERE — before any install is removed (F1). Off a TTY this NEVER prompts (the
+  // load-bearing no-hang invariant, D2).
+  let profile;
+  try {
+    profile = await resolveProfile({
+      flags: { name, role, company, workingStyle },
+      isTTY: Boolean(process.stdin.isTTY),
+      prompt: promptProfile,
+    });
+  } catch (err) {
+    console.error(`Initialization failed: ${err.message}`);
+    process.exitCode = 1;
+    return { cancelled: true, error: err.message };
+  }
+
+  // --force replaces a prior install: the ORIGINAL remove-then-build, UNCHANGED (D4). 0039 only adds
+  // profile capture, and its operator-triggerable failure mode is already closed BEFORE this point —
+  // resolveProfile validated the flags above (so a bad --name never reaches here), and the fill itself
+  // is literal + atomic + budget-checked, so it cannot throw on operator input. (The general --force
+  // remove-then-build window — a *build* failure after the remove — is the pre-existing core-0001/0002
+  // behavior, out of this packet's scope; a crash-safe atomic --force is flagged as a follow-up.)
+  if (mustRemove) await fse.remove(targetDir);
+
+  let result;
+  try {
+    result = await createInstallation(targetDir, { domain: domainSlug, profile });
+  } catch (err) {
+    // Roll back the partial install so a failed init never leaves a half-built directory
+    // (registry.json is written last, so the marker won't survive either).
+    await fse.remove(targetDir).catch(() => {});
+    console.error(`Initialization failed; removed the partial install at ${targetDir}. ${err.message}`);
+    process.exitCode = 1;
+    return { cancelled: true, error: err.message };
+  }
+
+  printSuccess(result);
+  return result;
+}
+
+function printSuccess({ targetDir, domain }) {
+  console.log();
+  console.log('Phronesis installation ready.');
+  console.log();
+  console.log(`  ${chalk.bold(targetDir)}`);
+  console.log(chalk.dim('    codex/             shared principles, citable from every domain'));
+  console.log(chalk.dim(`    domains/${domain}/        your ${domain} workspace (raw + compiled)`));
+  console.log(chalk.dim('    skills/            installed engine + door skills'));
+  console.log(chalk.dim('    .phronesis/        runtime and configuration'));
+  console.log();
+  console.log(chalk.dim('  Source of truth is the folder. Plain Markdown, yours to keep.'));
+  console.log();
+  // Surface adapters: Claude Code reads .claude/settings.json at the install root
+  // automatically. Codex (change 0028 / core-0034) needs a trust step the operator must
+  // take, and a specific open target — so it earns an explicit note here.
+  console.log('  Codex (CLI + desktop app):');
+  console.log(chalk.dim(`    Open Codex AT  ${join(targetDir, 'domains', domain)}  — its .codex/ hooks load only`));
+  console.log(chalk.dim('    from the opened directory (no parent-walk), and the session spec lives there too.'));
+  console.log(chalk.dim('    Trust the project + enable its hooks: CLI `/hooks`, or the app Settings → Coding →'));
+  console.log(chalk.dim('    Hooks. Then verify: `phronesis adapter test codex`. (Claude Code needs no trust step.)'));
+  console.log();
+  console.log('  First run: ask your agent to run `onboard me`.');
+  console.log(chalk.dim('    The onboard skill maps your world, compiles the first anchors, and guides seed adoption.'));
+  console.log();
+}

package/src/layout.js

@@ -0,0 +1,394 @@
+// Canonical three-layer installation layout (specs/workspace-substrate.md).
+//
+// Single source of truth for what `phronesis init` creates and what the fitness
+// checks assert. STRUCTURE ONLY — session-file content (AGENTS.md, MEMORY.md,
+// USER.md, codex/INDEX.md, the CLAUDE.md/.cursorrules symlinks, seed principles)
+// is authored by T1.2 / T3.3, not here. core-0001 lays the skeleton.
+
+// The compiled/ type-dirs come from the ontology contract's TYPE_DIR (one source —
+// the scaffold and the validator must never disagree about what a type-dir is named;
+// the 0012 rename made the second hand-list a live drift risk).
+export const COMPILED_SUBDIRS = COMPILED_DIRS;
+export const PHRONESIS_SUBDIRS = ['hooks', 'events', 'evals', 'connectors', 'invocations'];
+
+// Default V1 configuration: a single PM door plus the shared codex. The constants
+// live in @phronesis/core (the shared path-layout subset, core-0007); re-exported
+// here so init/scaffold callers keep one import site. No duplication — one source.
+import { DEFAULT_DOMAIN, RAW_SUBDIRS, COMPILED_DIRS, defaultActionTypesSection } from '@phronesis/core';
+export { DEFAULT_DOMAIN, RAW_SUBDIRS };
+
+// The V1 default skill set (specs/skills.md §"V1 skill set"). SINGLE SOURCE for
+// both scaffold copies and .phronesis/registry.json's skills section: if this
+// list drifts from skills/<name>/SKILL.md frontmatter, validate-workspace fails.
+export const DEFAULT_SKILLS = Object.freeze([
+  Object.freeze({ name: 'ingest', version: '0.1.0' }),
+  Object.freeze({ name: 'compile', version: '0.1.0' }),
+  Object.freeze({ name: 'research', version: '0.1.0' }),
+  Object.freeze({ name: 'recall', version: '0.1.0' }),
+  Object.freeze({ name: 'lint', version: '0.1.0' }),
+  Object.freeze({ name: 'onboard', version: '0.2.0' }),
+  Object.freeze({ name: 'prep-extraction', version: '0.1.0' }),
+  Object.freeze({ name: 'extract-gold-dust', version: '0.1.0' }),
+  Object.freeze({ name: 'meeting-prep', version: '0.1.1' }),
+  Object.freeze({ name: 'stakeholder-update', version: '0.1.0' }),
+  Object.freeze({ name: 'decision-log', version: '0.1.0' }),
+  Object.freeze({ name: 'prd-draft', version: '0.1.0' }),
+]);
+
+export function defaultSkillsSection() {
+  return Object.fromEntries(DEFAULT_SKILLS.map(({ name, version }) => [name, { version }]));
+}
+
+// Legacy two-layer artifact that must NEVER appear in a V1 installation. The
+// old pming scaffold rooted everything under context/; the three-layer engine
+// replaces it with codex/ (Layer 3) + domains/{slug}/{raw,compiled} (Layers 1-2).
+export const FORBIDDEN_DIRS = ['context'];
+
+// Installation-level dirs (Layer 3 codex + shared), relative to the install root.
+// The codex is NOT nested under a domain: it is unaffiliated and citable by all.
+export function installationDirs() {
+  return [
+    'codex',
+    'codex/seed', // immutable seeded principles (content: T5.4)
+    'codex/personal', // operator-adopted/promoted principles
+    'skills',
+    'domains',
+    '.phronesis',
+    ...PHRONESIS_SUBDIRS.map((d) => `.phronesis/${d}`),
+  ];
+}
+
+// One domain workspace (Layer 1 raw + Layer 2 compiled), relative to install root.
+export function domainDirs(slug) {
+  return [
+    `domains/${slug}`,
+    `domains/${slug}/raw`,
+    ...RAW_SUBDIRS.map((d) => `domains/${slug}/raw/${d}`),
+    `domains/${slug}/compiled`,
+    ...COMPILED_SUBDIRS.map((d) => `domains/${slug}/compiled/${d}`),
+    `domains/${slug}/memory`,
+    `domains/${slug}/artifacts`,
+    `domains/${slug}/artifacts/prd`,
+    `domains/${slug}/exports`,
+  ];
+}
+
+// The installation registry: what init created (domains) PLUS the action-type
+// registry (core-0011 / T2.4) — schema, permission, target layout per type,
+// GENERATED from the @phronesis/core code table so the scaffold and the compiled
+// defaults can never drift (one source). The operator edits permissions here within
+// the code-resident safety lattice (loosening a floor action fails closed at load);
+// `phronesis registry status` shows the effective state. Deterministic (no
+// timestamps) so smoke tests can assert on it.
+export function registryJson(domains = [DEFAULT_DOMAIN]) {
+  return {
+    // schema_version 2 (core-0017): the compile handler landed, so the action_types
+    // section carries the REAL compile entry (the H2b per-object_type layout + a runnable
+    // schema), not the pre-T5.1 deferred stub. A pre-2 install with the deferred compile
+    // entry upgrades via `node harness/migrations/0017-compile-handler.mjs <install>`.
+    schema_version: 2,
+    created_by: 'phronesis-cli',
+    domains,
+    action_types: defaultActionTypesSection(),
+    // Hook subscriptions (core-0013 / T4.2): the V1 in-pipeline executor fires these at
+    // the act pipeline's requested/committed emit points; the V1.5 daemon consumes the
+    // same section. V1 ships ONE default: the post-compile active-context projection
+    // refresh (core-0017 H5) — subscribes to action_type.committed filtered to compile, so
+    // it fires on a trusted compile or an accept (canonical mutation) and NOT on any other
+    // action type. A mutation hook: a failure is audited, never blocking.
+    hooks: [
+      {
+        id: 'compile-active-context',
+        kind: 'mutation',
+        subscribes_to: ['action_type.committed'],
+        filter: { 'payload.action_type': 'compile' },
+        command: '.phronesis/hooks/compile-active-context.sh',
+        quota: { max_per_session: 500 },
+        classification: 'silent',
+        kill_switch: 'PHRONESIS_SKIP=compile-active-context',
+      },
+    ],
+    // Skill registry (core-0015 / T3.1): name → { version }, loaded from
+    // skills/{name}/SKILL.md and validated against skills.md §"Frontmatter contract"
+    // + the runtime-free degrade contract. Generated from DEFAULT_SKILLS so init
+    // installs and registers the V1 set as one deterministic unit.
+    skills: defaultSkillsSection(),
+  };
+}
+
+// Installation config. The model-swap emancipation invariant (specs/security.md)
+// requires that pointing the workspace at a different LLM provider is a SINGLE
+// config-value change — never an edit to operator data. `provider` is that single
+// swap-point: change `id` (and `model`) here and nowhere else. No API key lives
+// here — keys stay in the OS keychain (security.md). The provider id deliberately
+// appears in exactly one file so swapping providers leaves domains/ and codex/
+// untouched; validate-emancipation enforces that.
+//
+// No LLM-calling code reads this yet. Consumption (and any schema refinement) is
+// Phase 5's compile/retrieve loop; this establishes the swap-point the invariant
+// gates on. Deterministic (no timestamps) so smoke tests can assert on it.
+//
+// The event_log section (core-0006 / T4.0) is ADDITIVE — a sibling of `provider`, never a
+// change to it — so the model-swap emancipation gate (which checks the provider swap-point)
+// is undisturbed. `capture_message_text` is the privacy gate (default OFF: message bodies
+// and recall queries stay out of the log, per security.md + change 0005);
+// `retention_days` is the rotation window (`events rotate` archives older day files).
+export function configJson() {
+  return {
+    schema_version: 0,
+    provider: {
+      id: 'anthropic',
+      model: 'claude-opus-4-8',
+    },
+    event_log: {
+      capture_message_text: false,
+      retention_days: 90,
+    },
+  };
+}
+
+// Schedule registry (core-0051 / change 0042): the operator-authored cadence DECLARATIONS,
+// a separate failure domain from registry.json (ratification (a) — a malformed schedule must
+// never disable the action layer). Scaffolded EMPTY: nothing fires unasked on a fresh install.
+// JSON has no comments and the registry's own unknown-field refusal forbids a `$comment`
+// workaround (change 0041 / F2), so the worked example lives in a SIBLING file
+// (`.phronesis/schedule.example.json`) + the docs, never as commented-out JSON. TRACKED +
+// exported (durable operator intent); the mutable runtime state is the separate file below.
+export function scheduleJson() {
+  return { schedules: [] };
+}
+
+// The sibling worked example (`.phronesis/schedule.example.json`) — a VALID entry the operator
+// copies into schedule.json and edits. Deterministic; passes validateScheduleRegistry as-is (a
+// fitness assertion). Deliberately DOMAIN-AGNOSTIC: a `kind: skill` example must demonstrate the
+// auto-advance path (it completes when `lint` runs), and only domain-agnostic skill schedules
+// auto-advance — `skill.completed` carries no domain, so a domain-scoped one is confirmed via
+// `phronesis due complete` (Codex round-6/7). `domain` stays an optional, spec-documented field.
+export function scheduleExampleJson() {
+  return {
+    schedules: [
+      {
+        id: 'lint-weekly',
+        kind: 'skill',
+        target: 'lint',
+        cadence: '7d',
+        unattended: false,
+        classification: 'acknowledged',
+      },
+    ],
+  };
+}
+
+// Transient / non-canonical installation state: rebuildable, disposable, or
+// operational. SINGLE SOURCE OF TRUTH for what the install .gitignore omits AND
+// what `phronesis export` strips — the two must never drift. A backup that keeps
+// privacy-sensitive event logs, or a .gitignore that tracks disposable renders,
+// breaks the emancipation promise. Canonical state (compiled/, codex/, raw/, the
+// session files, config) is never listed here.
+//
+// `gitignore` entries are .gitignore lines; `exclude` entries are tar globs.
+//
+// Path-specific globs are given in BOTH a bare and a `*/`-prefixed form because
+// GNU tar and bsdtar disagree on `--exclude` matching: GNU defaults to
+// non-anchored matching (the bare `.phronesis/events` matches inside the
+// `install/...` member path), while bsdtar anchors at the start (so it needs the
+// leading `*/` to skip the top-level `install/` dir). Listing both covers both
+// families; a pattern that matches nothing is harmless. validate-emancipation
+// asserts the strip actually bit on whatever tar ran.
+const TRANSIENT_STATE = [
+  {
+    comment: 'OS cruft',
+    gitignore: ['.DS_Store', 'Thumbs.db'],
+    exclude: ['.DS_Store', 'Thumbs.db'],
+  },
+  {
+    comment: 'Disposable renders (exports are disposable per workspace-substrate)',
+    gitignore: ['domains/*/exports/'],
+    exclude: ['domains/*/exports', '*/domains/*/exports'],
+  },
+  {
+    comment: 'Operational event stream (local logs; privacy-sensitive, retained locally)',
+    gitignore: ['.phronesis/events/'],
+    exclude: ['.phronesis/events', '*/.phronesis/events'],
+  },
+  {
+    comment: 'Hook execution audit log (operational, local — same class as the event stream)',
+    gitignore: ['.phronesis/audit.log'],
+    exclude: ['.phronesis/audit.log', '*/.phronesis/audit.log'],
+  },
+  {
+    // audit.log retention archive (core-0027 J5): `events rotate`/`purge --archive` moves
+    // audit lines past retention here. Same operational/local class as audit.log itself —
+    // gitignore + export globs are per-entry explicit lists (never inherited from a sibling),
+    // so the archive needs its own row or it would ship in export while audit.log is stripped.
+    comment: 'Hook audit retention archive (operational, local — rotated audit.log lines)',
+    gitignore: ['.phronesis/audit.log.archive'],
+    exclude: ['.phronesis/audit.log.archive', '*/.phronesis/audit.log.archive'],
+  },
+  {
+    comment: 'Derived machine search index — rebuildable from compiled/ + codex/ (phronesis index rebuild)',
+    gitignore: ['.phronesis/index/'],
+    exclude: ['.phronesis/index', '*/.phronesis/index'],
+  },
+  {
+    // Compile draft staging (core-0017): UNAPPROVED candidates for untrusted compiles,
+    // pending operator accept/reject. Transient-but-NOT-derived (distinct from the index):
+    // excluded because a draft is unapproved, not because it is rebuildable. The exclusion
+    // is NOT inherited — gitignore + exportExcludeGlobs are per-subdir explicit lists, so
+    // without this entry a draft is git-committed AND shipped in `phronesis export`,
+    // reintroducing the exact "unapproved draft visible as canonical" failure 0015 prevents.
+    comment: 'Compile draft staging — unapproved candidates pending operator review (security.md draft lifecycle)',
+    gitignore: ['.phronesis/drafts/'],
+    exclude: ['.phronesis/drafts', '*/.phronesis/drafts'],
+  },
+  {
+    // Compile-review batch journal (core-0029 PR2): the durable receipt a `compile review
+    // --approve-all` writes so a mid-batch crash is recoverable via --resume. Transient
+    // operational state — its intent/cursor reference local paths + event ids and it is
+    // deleted once the batch completes; it must never be committed or shipped in export.
+    comment: 'Compile-review batch journal — transient resume receipt (core-0029 compile review)',
+    gitignore: ['.phronesis/compile-review-journal.json'],
+    exclude: ['.phronesis/compile-review-journal.json', '*/.phronesis/compile-review-journal.json'],
+  },
+  {
+    // Claude Code skill lifecycle active records (core-0032): adapter-minted
+    // invocation_id state scoped to the current session. Transient-but-NOT-derived,
+    // and privacy-sensitive operational state: a stale export or commit would turn a
+    // live attribution record into portable data. The exclusion is explicit because
+    // gitignore/export globs are per-subdir lists, not inherited from .phronesis/.
+    comment: 'Skill lifecycle active records — adapter-owned session state (never canonical)',
+    gitignore: ['.phronesis/invocations/'],
+    exclude: ['.phronesis/invocations', '*/.phronesis/invocations'],
+  },
+  {
+    // Schedule runtime state (core-0051 / change 0042): mutable `last_completed` per schedule
+    // id. The DECLARATIONS (.phronesis/schedule.json, scaffolded above) are tracked + exported;
+    // this DERIVED completion state is gitignored + export-excluded (change 0008 tracked-vs-
+    // derived line). Losing it degrades to one-time over-surfacing, never a silent skip — so it
+    // must never ship in a backup or a commit and read back as authored intent. Per-subdir
+    // explicit lists (not inherited from .phronesis/), like every row here.
+    comment: 'Schedule runtime state — derived last_completed per schedule id (never canonical)',
+    gitignore: ['.phronesis/state/'],
+    exclude: ['.phronesis/state', '*/.phronesis/state'],
+  },
+];
+
+// Tar exclude globs for `phronesis export`: strips the transient set above so the
+// archive carries canonical state only — no privacy-sensitive logs, no disposable
+// renders. "Strip nothing canonical" means exactly this set and no more.
+export function exportExcludeGlobs() {
+  return TRANSIENT_STATE.flatMap((e) => e.exclude);
+}
+
+// Installation .gitignore. The operator may version their install for backup or
+// portability — this ignores ONLY the transient set above. Canonical workspace
+// state (compiled/, codex/, raw/, the session files, config) stays tracked. The
+// machine search index landed with core-0014, so its entry is a real TRANSIENT_STATE
+// row (the placeholder comment this block once carried is retired).
+export function installationGitignore() {
+  const lines = [
+    '# Phronesis installation — generated and transient state only.',
+    '# Your canonical workspace (compiled/, codex/, raw/, session files) IS tracked.',
+  ];
+  for (const { comment, gitignore } of TRANSIENT_STATE) {
+    lines.push('', `# ${comment}`, ...gitignore);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+// Session-file + codex templates copied into a fresh installation. `from` is
+// relative to apps/cli/templates/; `to` is relative to the install root. V1 ships
+// the PM door's templates; other doors get PM-shaped content until their own exist.
+// The session-boundary hook set (core-0013 / T4.2, change 0010 D4) ships with every
+// install: Claude Code wiring in .claude/settings.json plus hook scripts — all degrade
+// to a clean no-op when no Phronesis runtime is on PATH (change 0013).
+//
+// Surface adapters (specs/hooks.md §"Surface adapters") wire a hook-capable AI surface's
+// native lifecycle events to the SAME .phronesis/hooks/ scripts. Claude Code is the first
+// (.claude/settings.json @ install root, via $CLAUDE_PROJECT_DIR). Codex is the second
+// (change 0028 / core-0034): its .codex/ hook config + launchers are emitted at the DOMAIN
+// WORKSPACE dir (domains/{slug}/), because Codex loads .codex/ ONLY from the opened
+// directory (no parent-walk, spike 2026-06-21) and the session spec (AGENTS.md/CLAUDE.md)
+// already lives there — so the operator opens one directory and gets both. The launchers
+// carry no slug-specific content (they walk up to the install's .phronesis/), so the
+// templates are static → a re-init is byte-identical and does not re-trigger Codex's
+// per-hook trust (core-0034 P4). See apps/cli/templates/codex-surface/.
+// The Codex surface adapter contract (change 0028 / core-0034): Codex native event →
+// the .codex/ launcher that handles it → the shared .phronesis/hooks/ script it execs →
+// the reinforcement role + compliance tier (event-log.md §"Compliance levels"). SINGLE
+// SOURCE: init emits hooks.json wiring exactly these; `phronesis adapter test codex` and
+// harness/fitness/validate-codex-adapter assert the emitted config against it, so the
+// emission and its checks can never disagree. `reinforcement` events are the Level-1 loop
+// (recall / due-check / sweep, + the compaction reminder that supports it); `lifecycle` is
+// the Level-2 skill-lifecycle close, PARTIAL on Codex (no invocation_id minted — no
+// fabricated events, change 0021).
+export const CODEX_ADAPTER_HOOKS = [
+  { event: 'SessionStart', launcher: 'session-start.sh', script: 'session-start.sh', role: 'due-check', tier: 'reinforcement' },
+  { event: 'UserPromptSubmit', launcher: 'recall-guard.sh', script: 'recall-guard.sh', role: 'recall-guard', tier: 'reinforcement' },
+  { event: 'Stop', launcher: 'session-sweep.sh', script: 'session-sweep.sh', role: 'capture-sweep', tier: 'reinforcement' },
+  { event: 'SubagentStop', launcher: 'session-sweep-subagent.sh', script: 'session-sweep.sh', role: 'subagent-lifecycle-close', tier: 'lifecycle' },
+  { event: 'PreCompact', launcher: 'session-sweep-precompact.sh', script: 'session-sweep.sh', role: 'compaction-reminder', tier: 'reinforcement' },
+];
+const CODEX_SURFACE_HOOKS = CODEX_ADAPTER_HOOKS.map((h) => h.launcher);
+// Every file under codex-surface/hooks/ that init emits: the per-event launchers plus the
+// shared _resolve.sh they source for cwd-independent, decoy-immune install-root resolution
+// (core-0034 adversarial review #1). _resolve.sh is infrastructure, not an event hook, so it
+// is NOT in CODEX_ADAPTER_HOOKS — but it must ship, or every launcher fails to source it.
+export const CODEX_SURFACE_RESOLVER = '_resolve.sh';
+const CODEX_SURFACE_FILES = [CODEX_SURFACE_RESOLVER, ...CODEX_SURFACE_HOOKS];
+export function templateCopies(slug = DEFAULT_DOMAIN) {
+  return [
+    { from: 'domains/pm/AGENTS.md', to: `domains/${slug}/AGENTS.md` },
+    { from: 'domains/pm/MEMORY.md', to: `domains/${slug}/MEMORY.md` },
+    { from: 'domains/pm/USER.md', to: `domains/${slug}/USER.md` },
+    { from: 'codex/INDEX.md', to: 'codex/INDEX.md' },
+    // Immutable PM-shaped seed principle library (T5.4): the whole codex/seed/ template
+    // tree (collections of codex-principle-seed objects) copied verbatim into the install.
+    // Ships INSIDE the public phronesis package (package.json files: ["templates"]) — no
+    // separate repo-root mirror, unlike the skills/ tree. Quarantined out of retrieval until
+    // adopted via `promote_to_codex --from-seed`; discoverable through codex/INDEX.md
+    // (specs/compile-retrieve-loop.md §"Seed-vs-personal quarantine").
+    { from: 'codex/seed', to: 'codex/seed' },
+    { from: 'claude/settings.json', to: '.claude/settings.json' },
+    { from: 'phronesis-hooks/recall-guard.sh', to: '.phronesis/hooks/recall-guard.sh', executable: true },
+    { from: 'phronesis-hooks/skill-lifecycle.sh', to: '.phronesis/hooks/skill-lifecycle.sh', executable: true },
+    { from: 'phronesis-hooks/session-start.sh', to: '.phronesis/hooks/session-start.sh', executable: true },
+    { from: 'phronesis-hooks/session-sweep.sh', to: '.phronesis/hooks/session-sweep.sh', executable: true },
+    // The post-compile active-context projection refresh (core-0017 H5), registered by
+    // default in registryJson's hooks array — both must ship together or the subscription
+    // names a command that is not there.
+    { from: 'phronesis-hooks/compile-active-context.sh', to: '.phronesis/hooks/compile-active-context.sh', executable: true },
+    // Codex surface adapter (change 0028 / core-0034): hook config + launchers at the
+    // domain workspace open target. NOTE the template source dir is `codex-surface/`, not
+    // `codex/` — the latter is the unrelated shared-codex INDEX (Layer 3 principles).
+    { from: 'codex-surface/hooks.json', to: `domains/${slug}/.codex/hooks.json` },
+    { from: 'codex-surface/README.md', to: `domains/${slug}/.codex/README.md` },
+    ...CODEX_SURFACE_FILES.map((name) => ({
+      from: `codex-surface/hooks/${name}`,
+      to: `domains/${slug}/.codex/hooks/${name}`,
+      executable: true,
+    })),
+  ];
+}
+
+// Default V1 skills copied from repo-root skills/ into operator installs. The
+// rubric is runtime-referenced by every SKILL.md body; golden cases and dev notes
+// deliberately stay out of installs.
+export function defaultSkillCopies() {
+  return DEFAULT_SKILLS.flatMap(({ name }) => [
+    { from: `skills/${name}/SKILL.md`, to: `skills/${name}/SKILL.md` },
+    { from: `skills/${name}/evals/rubric.md`, to: `skills/${name}/evals/rubric.md` },
+  ]);
+}
+
+// Cross-surface entry points: vendor filenames symlink to the canonical AGENTS.md
+// (specs/canonical-session-spec.md). Target is RELATIVE ('AGENTS.md', same dir) so
+// the installation stays portable when moved or tarred, and resolves with no
+// Phronesis runtime present (the skill-portability invariant).
+export function domainSymlinks(slug = DEFAULT_DOMAIN) {
+  return [
+    { link: `domains/${slug}/CLAUDE.md`, target: 'AGENTS.md' },
+    { link: `domains/${slug}/.cursorrules`, target: 'AGENTS.md' },
+  ];
+}

package/src/links.js

@@ -0,0 +1,83 @@
+// `phronesis links` — the substrate/debug surface over the Stage 2 link walk
+// (core-0005 / T2.3). Plumbing, not porcelain (cf. `phronesis act`, ontology.md:163):
+// it makes the walk exercisable + gate-able on the real binary. T5.2 composes the same
+// link index (@phronesis/core) into the operator-facing `phronesis query`; this command
+// does not claim the search/query surfaces.
+
+import { resolve } from 'node:path';
+import fse from 'fs-extra';
+import chalk from 'chalk';
+import { buildLinkIndex } from '@phronesis/core';
+
+export async function runLinks({ dir, object, hops = 2, direction = 'both', json = false } = {}) {
+  const installRoot = resolve(process.cwd(), dir || '.');
+
+  const hasDomains = await fse.pathExists(resolve(installRoot, 'domains'));
+  const hasCodex = await fse.pathExists(resolve(installRoot, 'codex'));
+  if (!hasDomains && !hasCodex) {
+    console.error(`Not a Phronesis installation: ${installRoot} has no domains/ or codex/.`);
+    process.exitCode = 1;
+    return null;
+  }
+
+  if (!object) {
+    console.error('links: name an object to walk from (a path, a name, or {type-dir}/{name}).');
+    process.exitCode = 1;
+    return null;
+  }
+
+  const index = await buildLinkIndex({ installRoot });
+  const found = index.find(object);
+  if (found.error) {
+    console.error(found.error);
+    process.exitCode = 1;
+    return null;
+  }
+
+  const subgraph = index.walk(found.path, { hops, direction });
+
+  if (json) {
+    console.log(JSON.stringify(subgraph));
+  } else {
+    console.log(formatHuman(subgraph, index));
+  }
+  process.exitCode = 0;
+  return subgraph;
+}
+
+function formatHuman(sub, index) {
+  const root = index.node(sub.root);
+  const lines = [
+    chalk.bold(root?.title || sub.root),
+    chalk.dim(sub.root),
+    chalk.dim(
+      `${sub.hops}-hop subgraph · direction ${sub.direction} · ${sub.nodes.length} node(s), ${sub.edges.length} edge(s)`,
+    ),
+  ];
+
+  const byHop = new Map();
+  for (const n of sub.nodes) {
+    if (n.hop === 0) continue;
+    if (!byHop.has(n.hop)) byHop.set(n.hop, []);
+    byHop.get(n.hop).push(n);
+  }
+
+  if (byHop.size === 0) {
+    lines.push('', chalk.dim('no linked objects within range.'));
+    return lines.join('\n');
+  }
+
+  for (const hop of [...byHop.keys()].sort((a, b) => a - b)) {
+    lines.push('', chalk.dim(`hop ${hop}`));
+    for (const n of byHop.get(hop)) {
+      const label = n.kind === 'object' ? `${n.type} ${n.name}` : `${n.kind} ${n.path}`;
+      lines.push(`  ${label}${n.title ? `  ${n.title}` : ''}`);
+    }
+  }
+
+  lines.push('', chalk.dim('edges'));
+  for (const e of sub.edges) {
+    lines.push(`  ${e.from} --[${e.rel || '?'}${e.forward ? ' forward' : ''}]--> ${e.to}`);
+  }
+  return lines.join('\n');
+}