phronesis 1.0.0

package/src/lint.js

@@ -0,0 +1,58 @@
+// `phronesis lint` — deterministic read-only workspace health report (core-0022 PR1).
+// The semantic judgment layer lives in the lint skill; this CLI surface exposes the
+// mechanical foundation as JSON or a compact operator report.
+
+import chalk from 'chalk';
+import { runWorkspaceLint } from '@phronesis/core';
+
+export async function runLint({
+  dir,
+  domain,
+  allDomains = false,
+  staleMonths,
+  json = false,
+} = {}) {
+  try {
+    const out = await runWorkspaceLint({
+      dir,
+      cwd: process.cwd(),
+      domain,
+      allDomains,
+      staleMonths,
+    });
+    console.log(json ? JSON.stringify(out) : formatLint(out));
+    process.exitCode = 0;
+    return out;
+  } catch (err) {
+    console.error(`lint: ${err.message}`);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
+function scopeLine(out) {
+  const domains = out.scope.all_domains
+    ? `all domains (${out.scope.domains.join(', ') || 'none'})`
+    : out.scope.domains.join(', ');
+  return chalk.dim(`scope: ${domains} + codex · ${out.latency_ms}ms · stale threshold ${out.stale_months} month(s)`);
+}
+
+function findingLine(finding) {
+  const where = finding.path ? `${finding.path}` : finding.hook ?? finding.seed_ref ?? finding.normalized ?? finding.kind;
+  const target = finding.target ? ` -> ${finding.target}` : '';
+  return `  - ${finding.kind}: ${where}${target}`;
+}
+
+function formatLint(out) {
+  const lines = [scopeLine(out)];
+  if (out.empty_result) {
+    lines.push(chalk.dim('no deterministic lint findings (empty result).'));
+    return lines.join('\n');
+  }
+  for (const surface of out.surfaces) {
+    if (surface.empty_result) continue;
+    lines.push('', chalk.bold(surface.id.replaceAll('_', ' ')));
+    for (const finding of surface.findings) lines.push(findingLine(finding));
+  }
+  return lines.join('\n');
+}

package/src/profile.js

@@ -0,0 +1,116 @@
+// Minimal operator-profile capture for `phronesis init` (core-0039 / change 0031). Two halves:
+//   1. resolveProfile — INPUT resolution behind a dependency-injected seam ({ flags, isTTY, prompt })
+//      so the prompt path is gate-testable without a real terminal. Off a TTY it NEVER prompts (the
+//      load-bearing no-hang invariant: `npx phronesis init` in CI must never block).
+//   2. fillOperatorProfile — the deterministic WRITE: fills [Name]/[Role] in BOTH always-read files
+//      (USER.md AND AGENTS.md §1), with a compact, budget-checked §1 (≤8192, fail closed).
+// Not a wizard: name + role (+ optional company/working-style, USER.md-only). The fuller profile
+// stays with onboarding (a deferred surface — NOT T3.3, which is the six PM-door skills).
+
+import { join } from 'node:path';
+import { readFile, writeFile } from 'node:fs/promises';
+
+// AGENTS.md §1 is always-loaded and ≤8192 bytes; per-field caps bound the worst case so a
+// pathological --name can't blow the budget (the budget check in fillOperatorProfile is the backstop).
+const FIELD_MAX = { name: 48, role: 48, company: 64, workingStyle: 80 };
+const CONTROL_RE = /[\x00-\x1F\x7F]/g;
+const AGENTS_BUDGET = 8192;
+
+// Sanitize a profile value before it lands in an always-loaded file (D6): strip control chars +
+// newlines (no line injection into the one-line §1), collapse internal whitespace, trim. An
+// empty/whitespace value is MISSING (keep the placeholder); an over-long value FAILS CLOSED (throws),
+// never silently truncates the operator's input or overflows the budget.
+export function sanitizeProfileField(value, max) {
+  if (typeof value !== 'string') return undefined;
+  const cleaned = value.replace(CONTROL_RE, ' ').replace(/\s+/g, ' ').trim();
+  if (cleaned === '') return undefined;
+  if (cleaned.length > max) {
+    throw new Error(`profile value too long (max ${max} characters, got ${cleaned.length}): "${cleaned.slice(0, 24)}…" — shorten it.`);
+  }
+  return cleaned;
+}
+
+// Resolve { name?, role?, company?, workingStyle? } from flags, then (only on a TTY) prompt for a
+// missing name/role via the injected `prompt`. Returns sanitized values (omitting unprovided ones).
+export async function resolveProfile({ flags = {}, isTTY = false, prompt } = {}) {
+  const out = {};
+  for (const key of ['name', 'role', 'company', 'workingStyle']) {
+    const v = sanitizeProfileField(flags[key], FIELD_MAX[key]);
+    if (v !== undefined) out[key] = v;
+  }
+  // Interactive: on a TTY, prompt for the missing headline fields (name/role) ONLY — not a wizard,
+  // and NOT for company/working-style (flag-only). Off a TTY: never prompt (the no-hang invariant).
+  if (isTTY && typeof prompt === 'function' && (out.name === undefined || out.role === undefined)) {
+    const answers = (await prompt({ name: out.name, role: out.role })) || {};
+    if (out.name === undefined) {
+      const n = sanitizeProfileField(answers.name, FIELD_MAX.name);
+      if (n !== undefined) out.name = n;
+    }
+    if (out.role === undefined) {
+      const r = sanitizeProfileField(answers.role, FIELD_MAX.role);
+      if (r !== undefined) out.role = r;
+    }
+  }
+  return out;
+}
+
+// Deterministically fill the profile into BOTH always-read files. No clock → same inputs reproduce
+// byte-identical files (D3). Throws on a budget overflow (fail closed) or a missing §1 line (the
+// template drifted) — the caller (createInstallation, before the registry marker) rolls back.
+export async function fillOperatorProfile(installRoot, domain, profile = {}) {
+  const { name, role, company, workingStyle } = profile;
+  const hasIdentity = name !== undefined || role !== undefined;
+  if (!hasIdentity && company === undefined && workingStyle === undefined) return; // nothing provided
+
+  const userPath = join(installRoot, 'domains', domain, 'USER.md');
+  const agentsPath = join(installRoot, 'domains', domain, 'AGENTS.md');
+
+  // COMPUTE + VALIDATE both files' next content BEFORE writing EITHER, so a failure (template drift,
+  // a budget overflow) leaves BOTH files byte-unchanged — never a half-filled profile (Codex round-1 F2).
+
+  // Use FUNCTION replacers for EVERY operator-supplied value (Codex round-2 F1): a value passed as a
+  // replacement STRING has its `$`-tokens interpreted by replace() — `$&` re-emits the matched
+  // placeholder (leaving `[Name]`), `$'` splices the entire tail of the file (ballooning it over
+  // budget), `$$` collapses to `$`. A function replacer substitutes the value LITERALLY. And each
+  // required placeholder must actually be present (F3) — a zero-replacement is template drift, not a
+  // silent no-op that reports success while the dead air survives.
+  let userNext = await readFile(userPath, 'utf8');
+  if (name !== undefined) {
+    if (!userNext.includes('[Name]')) throw new Error('USER.md has no [Name] placeholder to fill — template drift');
+    userNext = userNext.replaceAll('[Name]', () => name);
+  }
+  if (role !== undefined) {
+    if (!userNext.includes('[Role]')) throw new Error('USER.md has no [Role] placeholder to fill — template drift');
+    userNext = userNext.replaceAll('[Role]', () => role);
+  }
+  const extra = [];
+  if (company !== undefined) extra.push(`- Company: ${company}`);
+  if (workingStyle !== undefined) extra.push(`- Working style: ${workingStyle}`);
+  if (extra.length) {
+    const withExtra = userNext.replace(/^(- Role:.*)$/m, (m) => `${m}\n${extra.join('\n')}`);
+    if (withExtra === userNext) throw new Error('USER.md "- Role:" line not found — cannot add company/working-style lines');
+    userNext = withExtra;
+  }
+
+  // AGENTS.md §1 next (only when name/role provided — company/working-style are USER.md-only). An
+  // unprovided field keeps its placeholder. Fill + COMPACT the suffix, then budget-check.
+  let agentsNext = null;
+  if (hasIdentity) {
+    const agents = await readFile(agentsPath, 'utf8');
+    const filledName = name !== undefined ? name : '[Name]';
+    const filledRole = role !== undefined ? role : '[Role]';
+    const newLine = `${filledName}, ${filledRole}. Profile + preferences: \`USER.md\`.`;
+    agentsNext = agents.replace(/^\[Name\], \[Role\]\..*$/m, () => newLine); // function replacer: newLine is literal (F1)
+    if (agentsNext === agents) {
+      throw new Error('AGENTS.md §1 operator line ("[Name], [Role]. …") not found — cannot fill the profile');
+    }
+    const byteLen = Buffer.byteLength(agentsNext, 'utf8');
+    if (byteLen > AGENTS_BUDGET) {
+      throw new Error(`profile fill would push AGENTS.md to ${byteLen} bytes, over the ${AGENTS_BUDGET}-byte always-loaded budget — shorten --name/--role.`);
+    }
+  }
+
+  // All replacements matched and the budget holds → commit both writes.
+  await writeFile(userPath, userNext);
+  if (agentsNext !== null) await writeFile(agentsPath, agentsNext);
+}

package/src/prompts.js

@@ -0,0 +1,26 @@
+import Enquirer from 'enquirer';
+
+// Confirm replacing a non-empty target. Interactive surfaces only; non-TTY
+// callers (CI, the fitness probe) fail closed and require --force instead.
+export async function confirmOverwrite(targetDir) {
+  const enquirer = new Enquirer();
+  const { overwrite } = await enquirer.prompt({
+    type: 'confirm',
+    name: 'overwrite',
+    message: `${targetDir} already exists and is not empty. Replace it?`,
+    initial: false,
+  });
+  return overwrite;
+}
+
+// Prompt for the missing headline profile fields (name/role) on an interactive TTY (core-0039). The
+// caller guards on `process.stdin.isTTY` (exactly like confirmOverwrite) — this is never reached off
+// a TTY, so a scripted `init` never hangs. Only the unprovided fields are asked.
+export async function promptProfile({ name, role } = {}) {
+  const questions = [];
+  if (name === undefined) questions.push({ type: 'input', name: 'name', message: 'Your name (for USER.md + AGENTS.md §1):' });
+  if (role === undefined) questions.push({ type: 'input', name: 'role', message: 'Your role:' });
+  if (!questions.length) return {};
+  const enquirer = new Enquirer();
+  return enquirer.prompt(questions);
+}

package/src/registry.js

@@ -0,0 +1,190 @@
+// `phronesis registry status` (core-0011 / T2.4; hooks since core-0013) — the diagnosis
+// surface for the install's action-type registry AND its hook subscriptions: where the
+// table comes from (registry section vs compiled defaults), every type's EFFECTIVE
+// permission and its relation to the code default/floor, the registered layout, the
+// schema summary, and every registered hook. On an invalid registry it prints the same
+// load errors runAction refuses with and exits non-zero — status is how the operator
+// sees WHY the action layer is disabled. Both sections go through the SAME shared
+// resolvers the action core consumes (the act/status parity lesson).
+
+import { join } from 'node:path';
+import fse from 'fs-extra';
+import {
+  ACTION_REGISTRY,
+  PERMISSION_ORDER,
+  resolveActionTypes,
+  resolveHooks,
+  resolveInstall,
+} from '@phronesis/core';
+
+// Relation of an effective permission to its code default + floor — what status
+// prints next to each type. The baseline for LEGALITY is the floor (G4); the
+// baseline for DISPLAY is the default, because "what changed from stock" is what
+// the operator is auditing.
+function permissionRelation(type, effective) {
+  const code = ACTION_REGISTRY[type];
+  if (code.deferredTo) return null; // descriptive string, not lattice-governed
+  if (code.approvalFloor) return 'floor — not overridable';
+  if (effective.permission === code.permission) return 'default';
+  const delta =
+    PERMISSION_ORDER.indexOf(effective.permission) > PERMISSION_ORDER.indexOf(code.permission)
+      ? 'tightened'
+      : 'loosened';
+  return `${delta} from ${code.permission}`;
+}
+
+function schemaSummary(schema) {
+  return Object.entries(schema)
+    .map(([field, spec]) => `${field}${spec.required ? '*' : ''} (${spec.kind})`)
+    .join(', ');
+}
+
+export async function runRegistryStatus({ dir, json = false } = {}) {
+  const installed = resolveInstall({ dir });
+  if (installed.error) {
+    console.error(installed.error);
+    process.exitCode = 1;
+    return;
+  }
+  const root = installed.root;
+
+  let registry;
+  try {
+    registry = await fse.readJson(join(root, '.phronesis', 'registry.json'));
+  } catch (err) {
+    console.error(`could not read the install registry (.phronesis/registry.json): ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // ONE validator for both surfaces: the loaders check everything the action layer
+  // depends on (incl. the domains list and the hooks section), so status can never call
+  // the layer disabled while `act` still writes — or vice versa (the two-matchers
+  // drift, rules.md).
+  const { errors, source, effective } = resolveActionTypes(registry);
+  const hookRes = resolveHooks(registry);
+  if (errors.length || hookRes.errors.length) {
+    if (errors.length) {
+      console.error(
+        'invalid .phronesis/registry.json (action-type registry) — the action layer is disabled until it is fixed (removing the action_types section restores built-in defaults):',
+      );
+      for (const e of errors) console.error(`  ✗ ${e}`);
+    }
+    if (hookRes.errors.length) {
+      console.error(
+        'invalid .phronesis/registry.json (hooks) — the action layer is disabled until it is fixed (an absent hooks section means no registered hooks):',
+      );
+      for (const e of hookRes.errors) console.error(`  ✗ ${e}`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  const unregistered = Object.keys(ACTION_REGISTRY).filter((t) => !effective[t]);
+
+  if (json) {
+    const out = {
+      root,
+      schema_version: registry.schema_version,
+      source,
+      action_types: {},
+      unregistered,
+      hooks: hookRes.hooks,
+    };
+    for (const [type, entry] of Object.entries(effective)) {
+      const code = ACTION_REGISTRY[type];
+      out.action_types[type] = {
+        permission: entry.permission,
+        default_permission: code.permission,
+        relation: permissionRelation(type, entry),
+        floor: Boolean(code.approvalFloor),
+        // compile (H2b) carries a per-object_type layout map; every other type a single layout.
+        ...(entry.targetLayoutByObjectType
+          ? { target_layout_by_object_type: entry.targetLayoutByObjectType }
+          : { target_layout: entry.targetLayout }),
+        ...(code.note ? { note: code.note } : {}),
+        ...(code.deferredTo ? { deferred_to: code.deferredTo } : {}),
+        ...(entry.schema
+          ? {
+              schema: Object.fromEntries(
+                Object.entries(entry.schema).map(([f, spec]) => [f, { ...spec }]),
+              ),
+            }
+          : {}),
+      };
+    }
+    console.log(JSON.stringify(out, null, 2));
+    return;
+  }
+
+  console.log(`Phronesis action-type registry — ${root}`);
+  console.log(
+    source === 'registry'
+      ? `source: .phronesis/registry.json action_types (schema_version ${registry.schema_version})`
+      : 'source: built-in defaults (the registry predates the action_types section — re-run init on a fresh install, or add the section, to customize)',
+  );
+  console.log(`domains: ${registry.domains.join(', ')}`);
+  for (const [type, entry] of Object.entries(effective)) {
+    const code = ACTION_REGISTRY[type];
+    const relation = permissionRelation(type, entry);
+    console.log(`\n${type}`);
+    console.log(`  permission: ${entry.permission}${relation ? ` (${relation})` : ''}`);
+    if (entry.targetLayoutByObjectType) {
+      const map = Object.entries(entry.targetLayoutByObjectType)
+        .map(([k, v]) => `${k} → ${v}`)
+        .join('; ');
+      console.log(`  layout:     ${map}${code.note ? ` — ${code.note}` : ''}`);
+    } else {
+      console.log(`  layout:     ${entry.targetLayout}${code.note ? ` — ${code.note}` : ''}`);
+    }
+    if (code.deferredTo) {
+      console.log(`  deferred:   handler lands at ${code.deferredTo} (not runnable yet)`);
+    }
+    if (entry.schema) {
+      console.log(`  schema:     ${schemaSummary(entry.schema)}`);
+    }
+  }
+  if (unregistered.length) {
+    console.log(
+      `\nunregistered — absent from action_types, these refuse to run (removed by an operator edit, or newer than this registry file): ${unregistered.join(', ')}`,
+    );
+  }
+
+  // The hook subscriptions in the registry's top-level hooks array (core-0013). The V1
+  // in-pipeline executor fires ONLY action_type.requested/committed subscriptions; a
+  // subscription to any other type is a registration the V1.5 daemon (or a surface-
+  // native bridge) will execute — status must say so per hook, or a registered-but-
+  // never-fired hook reads as live (silent intent-drop, the class this repo refuses).
+  const IN_PIPELINE = ['action_type.requested', 'action_type.committed'];
+  if (!hookRes.hooks.length) {
+    console.log(
+      '\nhooks: none registered (top-level hooks array — the V1 executor fires action_type.requested/committed subscriptions in-pipeline)',
+    );
+  } else {
+    console.log(
+      `\nhooks (${hookRes.hooks.length} registered — the V1 in-pipeline executor fires action_type.requested/committed subscriptions; other types execute from V1.5):`,
+    );
+    for (const h of hookRes.hooks) {
+      const filter = h.filter
+        ? ` filter ${Object.entries(h.filter)
+            .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
+            .join(' AND ')}`
+        : '';
+      console.log(`  ${h.id} (${h.kind}, ${h.classification})`);
+      console.log(`    subscribes_to: ${h.subscribes_to.join(', ')}${filter}`);
+      const dormant = h.subscribes_to.filter((t) => !IN_PIPELINE.includes(t));
+      if (dormant.length === h.subscribes_to.length) {
+        console.log(
+          `    NOT FIRED in V1: no subscribed type is an in-pipeline emit point — this registration waits for the V1.5 daemon / a surface-native executor`,
+        );
+      } else if (dormant.length) {
+        console.log(
+          `    partially fired in V1: ${dormant.join(', ')} wait(s) for the V1.5 daemon / a surface-native executor`,
+        );
+      }
+      console.log(
+        `    command: ${h.command} — quota ${h.quota.max_per_session}/session, bypass ${h.kill_switch}`,
+      );
+    }
+  }
+}

package/src/scaffold.js

@@ -0,0 +1,134 @@
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { symlink } from 'node:fs/promises';
+import fse from 'fs-extra';
+import {
+  installationDirs,
+  domainDirs,
+  registryJson,
+  configJson,
+  scheduleJson,
+  scheduleExampleJson,
+  installationGitignore,
+  templateCopies,
+  defaultSkillCopies,
+  domainSymlinks,
+  DEFAULT_DOMAIN,
+} from './layout.js';
+import { refreshSkillDiscovery } from './skill-discovery.js';
+import { fillOperatorProfile } from './profile.js';
+
+const TEMPLATES_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'templates');
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+
+export async function resolveDefaultSkillSourceRoot({
+  templatesDir = TEMPLATES_DIR,
+  repoRoot = REPO_ROOT,
+} = {}) {
+  const repoCheckout = await fse.pathExists(join(repoRoot, 'apps', 'cli', 'src', 'scaffold.js'));
+  if (repoCheckout) {
+    const repoComplete = await Promise.all(
+      defaultSkillCopies().map(({ from }) => fse.pathExists(join(repoRoot, from))),
+    );
+    if (repoComplete.every(Boolean)) return repoRoot;
+  }
+
+  const mirrorComplete = await Promise.all(
+    defaultSkillCopies().map(({ from }) => fse.pathExists(join(templatesDir, from))),
+  );
+  return mirrorComplete.every(Boolean) ? templatesDir : repoRoot;
+}
+
+// Create the three-layer installation at targetDir: directories, .gitkeep on empty
+// leaves, the installation .gitignore, the session-file and codex templates, the
+// cross-surface symlinks, and finally the registry. Pure scaffolding — no action
+// types, hooks, or runtime. Idempotent: safe to re-run into the same target.
+export async function createInstallation(
+  targetDir,
+  {
+    domain = DEFAULT_DOMAIN,
+    profile = {},
+    templatesDir = TEMPLATES_DIR,
+    repoRoot = REPO_ROOT,
+  } = {},
+) {
+  const dirs = [...installationDirs(), ...domainDirs(domain)];
+  const registry = registryJson([domain]);
+
+  for (const rel of dirs) {
+    await fse.ensureDir(join(targetDir, rel));
+  }
+
+  // .gitkeep only on leaf dirs. Durable artifact directories are intentionally
+  // empty until a validated artifact is written: the gate scans every file below
+  // artifacts/, so a scaffold sentinel would itself be invalid cargo.
+  // Session-file and codex templates land in container dirs (domains/{slug}/ and
+  // codex/), so leaf computation is otherwise unchanged. codex/seed is excluded like
+  // skills/: the seed principle library template tree (T5.4) populates it, so a sentinel
+  // would be spurious cargo alongside real codex-principle-seed objects.
+  const isLeaf = (d) => !dirs.some((other) => other !== d && other.startsWith(`${d}/`));
+  for (const rel of dirs.filter((dir) => isLeaf(dir) && dir !== 'skills' && dir !== 'codex/seed' && !dir.endsWith('/artifacts/prd'))) {
+    await fse.writeFile(join(targetDir, rel, '.gitkeep'), '');
+  }
+
+  await fse.writeFile(join(targetDir, '.gitignore'), installationGitignore());
+
+  // Session files + codex map + session-boundary hooks, copied verbatim from the
+  // staged templates. Hook scripts get the executable bit explicitly — fse.copy
+  // preserves the source mode, but a tarball/registry install may have lost it, and
+  // a non-executable hook is a silent no-fire.
+  for (const { from, to, executable } of templateCopies(domain)) {
+    const dest = join(targetDir, to);
+    await fse.copy(join(templatesDir, from), dest);
+    if (executable) await fse.chmod(dest, 0o755);
+  }
+
+  // Default V1 skills: the repo checkout copies canonical skills/; the packaged
+  // tarball copies the tracked templates/skills mirror.
+  const skillSourceRoot = await resolveDefaultSkillSourceRoot({ templatesDir, repoRoot });
+  for (const { from, to } of defaultSkillCopies()) {
+    const src = join(skillSourceRoot, from);
+    if (!(await fse.pathExists(src))) {
+      throw new Error(`default skill source missing: ${from}`);
+    }
+    await fse.copy(src, join(targetDir, to));
+  }
+
+  await refreshSkillDiscovery({ installRoot: targetDir, domain, registry });
+
+  // Minimal operator profile (core-0039): fill [Name]/[Role] into BOTH always-read files (USER.md +
+  // AGENTS.md §1) when provided. Runs AFTER §4 fill (so the AGENTS.md budget check sees the final
+  // bytes) and BEFORE the registry marker below — a budget-overflow / template-drift throw rolls back
+  // the partial install (init.js), never leaving a marked-but-half-built install. No-op when no
+  // profile was provided (the placeholders stay — the non-interactive no-flags path).
+  await fillOperatorProfile(targetDir, domain, profile);
+
+  // Cross-surface symlinks (relative target; remove-first keeps this idempotent).
+  for (const { link, target } of domainSymlinks(domain)) {
+    const linkPath = join(targetDir, link);
+    await fse.remove(linkPath);
+    await symlink(target, linkPath, 'file');
+  }
+
+  // Installation config — carries the single model-swap provider swap-point
+  // (specs/security.md model-swap invariant). Tracked, no secrets.
+  await fse.writeJson(join(targetDir, '.phronesis', 'config.json'), configJson(), { spaces: 2 });
+
+  // Schedule registry (core-0051 / change 0042): the EMPTY declarations file plus its sibling
+  // worked example. Tracked + exported; a SEPARATE failure domain from registry.json (a
+  // malformed schedule never disables the action layer). Written BEFORE the registry marker so
+  // a partial failure never leaves a marked install missing them. The `.phronesis/state/`
+  // runtime dir is NOT scaffolded — it is gitignored state created lazily on first completion.
+  await fse.writeJson(join(targetDir, '.phronesis', 'schedule.json'), scheduleJson(), { spaces: 2 });
+  await fse.writeJson(join(targetDir, '.phronesis', 'schedule.example.json'), scheduleExampleJson(), {
+    spaces: 2,
+  });
+
+  // registry.json is the ownership marker (isPhronesisInstall checks it). Write it
+  // LAST so a partial failure never leaves a half-built install that reads as healthy.
+  await fse.writeJson(join(targetDir, '.phronesis', 'registry.json'), registry, {
+    spaces: 2,
+  });
+
+  return { targetDir, domain, dirs };
+}

package/src/search.js

@@ -0,0 +1,139 @@
+// `phronesis search` / `phronesis query` / `phronesis index rebuild` — the operator-
+// facing retrieval surface (core-0014 / T5.2; specs/compile-retrieve-loop.md §"The V1
+// retrieval surface contract"). Porcelain over a library-first core: this file parses
+// execution context and formats output ONLY — every retrieval primitive (snapshot,
+// freshness repair, BM25, link walk) lives in @phronesis/core (the D7 act pattern;
+// context-server.md §"V1.0 preparation"), so the V1.5 context server and any direct
+// caller run the same retrieval the CLI does.
+
+import chalk from 'chalk';
+import { loadSearchIndex, rebuildSearchIndex } from '@phronesis/core';
+
+// A failed cache write degrades retrieval (slower next load), never blocks it — but it
+// is never silent either (a read-only checkout sees this once per invocation).
+function warnPersist(index, command) {
+  if (index.persistError) {
+    console.error(
+      `${command}: warning — machine index not persisted (${index.persistError}); results are live, the cache was not updated.`,
+    );
+  }
+}
+
+export async function runSearch({ query, dir, domain, allDomains = false, includeArtifacts = false, limit, json = false } = {}) {
+  // A blank or whitespace-only query is an operator mistake, not a search — refuse with
+  // guidance. (The LIBRARY treats an unqueryable string as an honest negative; the CLI
+  // is where "you probably mistyped" guidance belongs.)
+  if (!query || !query.trim()) {
+    console.error('search: give a query string (e.g. phronesis search "pricing decision").');
+    process.exitCode = 1;
+    return null;
+  }
+  try {
+    const index = await loadSearchIndex({ dir, cwd: process.cwd(), domain, allDomains, includeArtifacts });
+    warnPersist(index, 'search');
+    const out = index.search(query, limit === undefined ? {} : { limit });
+    console.log(json ? JSON.stringify(out) : formatSearch(out));
+    process.exitCode = 0;
+    return out;
+  } catch (err) {
+    console.error(`search: ${err.message}`);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
+export async function runQuery({ query, dir, domain, allDomains = false, includeArtifacts = false, limit, hops, json = false } = {}) {
+  if (!query || !query.trim()) {
+    console.error('query: give a question string (e.g. phronesis query "what did we decide on pricing?").');
+    process.exitCode = 1;
+    return null;
+  }
+  try {
+    const index = await loadSearchIndex({ dir, cwd: process.cwd(), domain, allDomains, includeArtifacts });
+    warnPersist(index, 'query');
+    const opts = {};
+    if (limit !== undefined) opts.limit = limit;
+    if (hops !== undefined) opts.hops = hops;
+    const out = index.query(query, opts);
+    console.log(json ? JSON.stringify(out) : formatQuery(out));
+    process.exitCode = 0;
+    return out;
+  } catch (err) {
+    console.error(`query: ${err.message}`);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
+export async function runIndexRebuild({ dir, json = false } = {}) {
+  try {
+    const out = await rebuildSearchIndex({ dir, cwd: process.cwd() });
+    console.log(
+      json
+        ? JSON.stringify({ objects: out.objects, ms: out.ms })
+        : `rebuilt the machine index: ${out.objects} object(s) in ${out.ms}ms (.phronesis/index/ — derived, rebuildable).`,
+    );
+    process.exitCode = 0;
+    return out;
+  } catch (err) {
+    console.error(`index rebuild: ${err.message}`);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
+function scopeLine(out) {
+  const domains = out.scope.all_domains
+    ? `all domains (${out.scope.domains.join(', ') || 'none'})`
+    : out.scope.domains.join(', ');
+  return chalk.dim(`scope: ${domains} + codex · ${out.latency_ms}ms`);
+}
+
+// The honest negative is part of the surface contract: say plainly that no workspace
+// state matched (the guard composes this into its pre-answer packet — T5.2a).
+function emptyLine() {
+  return chalk.dim('no compiled/codex state matched (empty result).');
+}
+
+function resultLines(r) {
+  const label = r.layer === 'codex' ? `codex ${r.type ?? '?'}` : `${r.type ?? '?'}`;
+  const lines = [`${chalk.bold(r.title ?? r.name ?? r.path)}  ${chalk.dim(`${label} · ${r.score.toFixed(2)}`)}`];
+  lines.push(`  ${chalk.dim(r.path)}`);
+  if (r.snippet) lines.push(`  ${r.snippet}`);
+  return lines;
+}
+
+function formatSearch(out) {
+  const lines = [scopeLine(out)];
+  if (out.empty_result) {
+    lines.push(emptyLine());
+    return lines.join('\n');
+  }
+  for (const r of out.results) {
+    lines.push('', ...resultLines(r));
+  }
+  return lines.join('\n');
+}
+
+function formatQuery(out) {
+  const lines = [scopeLine(out)];
+  if (out.empty_result) {
+    lines.push(emptyLine());
+    return lines.join('\n');
+  }
+  for (const r of out.results) {
+    lines.push('', ...resultLines(r));
+    const linked = r.subgraph.nodes.filter((n) => n.hop > 0 && n.kind === 'object');
+    for (const n of linked) {
+      lines.push(`    ↳ ${n.type ?? n.kind} ${n.name ?? n.path}${n.title ? `  ${chalk.dim(n.title)}` : ''}`);
+    }
+    const other = r.subgraph.nodes.filter((n) => n.kind === 'outside-scope' || n.kind === 'unresolved');
+    for (const n of other) {
+      lines.push(`    ↳ ${chalk.dim(`${n.kind} ${n.path}`)}`);
+    }
+    if (r.sources.length > 0) {
+      lines.push(`    ${chalk.dim(`sources: ${r.sources.join(', ')}`)}`);
+    }
+  }
+  return lines.join('\n');
+}