phronesis 1.0.0

package/src/doctor.js

@@ -0,0 +1,303 @@
+// `phronesis doctor [--dir <install>] [--json]` (core-0038 / change 0030) — a READ-ONLY install-
+// health overview that COMPOSES existing diagnostics into a one-screen OK / warn / fail report. It
+// makes NO writes to the install and emits NO events: the install (incl. .phronesis/events/) is
+// byte-identical after a run — validate-doctor's byte-identical proof is the guard. It REPORTS; it
+// never fixes (remediation is core-0039 / the operator).
+//
+// READ-ONLY is unconditional, even on a MODIFIED install (Codex round-1 F1): doctor never EXECUTES
+// install-owned code. The Codex-adapter check is STRUCTURAL only (codexAdapterReport structuralOnly:
+// true — pure file reads, no hook spawning); the full behavioral probe (which execs the install's
+// hook scripts) stays in `phronesis adapter test codex`, a deliberate operator self-check.
+//
+// Classification (D4): fail (exit non-zero) — no/invalid/unreadable install, a malformed registry /
+// domains list, an invalid skill registry (the install is genuinely broken). warn (exit 0) —
+// incomplete hook wiring, a non-compliant Codex adapter (Codex is the SECONDARY surface; Claude Code
+// is primary/always-on), USER.md placeholders, pending drafts. Exit is non-zero IFF a fail tripped;
+// no warn check ever fails the command. Every check is guarded — a throw becomes a fail/warn check,
+// never a crash (F2/F3 fail-closed).
+
+import { join } from 'node:path';
+import { existsSync, statSync, readFileSync } from 'node:fs';
+import { readFile, readdir } from 'node:fs/promises';
+import fse from 'fs-extra';
+import { resolveInstall, resolveHooks, RE_SLUG, validateScheduleRegistry, scheduleStaleness } from '@phronesis/core';
+import { registryJson } from './layout.js';
+import { skillsStatusReport } from './skills.js';
+import { codexAdapterReport } from './adapter.js';
+
+// The fixed check id set (D6) — the --json contract asserts on exactly these.
+export const DOCTOR_CHECK_IDS = ['install_root', 'domain', 'skills', 'hooks', 'adapter_codex', 'user_profile', 'pending_drafts', 'schedule'];
+
+function isExecutable(p) {
+  try {
+    const st = statSync(p);
+    // A runnable hook 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 (Codex round-3 F1).
+    return st.isFile() && Boolean(st.mode & 0o111);
+  } catch {
+    return false;
+  }
+}
+
+function isFileParseableJson(p) {
+  try {
+    if (!statSync(p).isFile()) return false;
+    JSON.parse(readFileSync(p, 'utf8'));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Build the structured doctor report — PURE w.r.t. the install (read-only). Returns the D6 shape:
+// { root, checks:[{ id, status, detail }], summary:{ ok, warn, fail }, exit }.
+export async function doctorReport({ dir } = {}) {
+  const checks = [];
+  const add = (id, status, detail) => checks.push({ id, status, detail });
+  // Run a check body; turn ANY throw into a check of `failClass` (never a crash — F2/F3).
+  const guarded = async (id, failClass, fn) => {
+    try {
+      const [status, detail] = await fn();
+      add(id, status, detail);
+    } catch (err) {
+      add(id, failClass, `${id} check errored: ${err.message}`);
+    }
+  };
+
+  // install_root — the only short-circuit: nothing else resolves without a root.
+  const installed = resolveInstall({ dir });
+  if (installed.error) {
+    add('install_root', 'fail', installed.error);
+    return finalize(null, checks);
+  }
+  const root = installed.root;
+  add('install_root', 'ok', root);
+
+  // Shared registry read — a present-but-corrupt registry.json (resolveInstall passes on existence)
+  // fails the registry-derived checks, never crashes (F3).
+  let registry = null;
+  let registryError = null;
+  try {
+    registry = await fse.readJson(join(root, '.phronesis', 'registry.json'));
+  } catch (err) {
+    registryError = err.message;
+  }
+
+  // Validated domain list (F2): a non-empty array of kebab-case SLUGs (RE_SLUG — the shared grammar
+  // a domain dir is named by). A non-slug (`../outside`, `pm/evil`, ` pm `, null, {}) is malformed —
+  // it would otherwise crash or path-traverse join(root,'domains',slug,...) in the dependent loops.
+  // `domains` is the safe slug-only subset the dependent (hooks / user_profile) loops iterate.
+  let domains = [];
+  let domainsValid = false;
+  if (!registryError) {
+    const d = registry?.domains;
+    const isSlug = (x) => typeof x === 'string' && RE_SLUG.test(x);
+    domainsValid = Array.isArray(d) && d.length > 0 && d.every(isSlug);
+    domains = Array.isArray(d) ? d.filter(isSlug) : [];
+  }
+
+  // domain
+  if (registryError) {
+    add('domain', 'fail', `registry.json unreadable: ${registryError}`);
+  } else if (!domainsValid) {
+    add('domain', 'fail', `malformed registry.domains (expected a non-empty array of domain slugs): ${JSON.stringify(registry?.domains)}`);
+  } else {
+    add('domain', 'ok', `registered: ${domains.join(', ')}`);
+  }
+
+  // skills — the PURE report (no print / no exit-code leak, D2/D3); a load error is fail.
+  await guarded('skills', 'fail', async () => {
+    const sr = await skillsStatusReport({ dir: root });
+    if (sr.status === 'ok') {
+      const n = Object.keys(sr.skills).length;
+      return ['ok', `${n} skill(s) registered${sr.unregistered.length ? ` · ${sr.unregistered.length} unregistered dir(s): ${sr.unregistered.join(', ')}` : ''}`];
+    }
+    return ['fail', sr.errors.slice(0, 3).join('; ').slice(0, 400) || 'skill registry invalid'];
+  });
+
+  // hooks — presence of the in-pipeline hook scripts + the surface configs (incomplete is warn, D4).
+  await guarded('hooks', 'warn', () => hookWiring(root, registry, registryError, domains));
+
+  // adapter_codex — the STRUCTURAL-only report (read-only: NO hook execution, F1); the PURE report
+  // (no exit-code leak, D2). Codex is the secondary surface → never fail (D4).
+  await guarded('adapter_codex', 'warn', async () => {
+    const ar = codexAdapterReport({ dir: root, structuralOnly: true });
+    if (ar.error) return ['warn', `could not run the Codex adapter check: ${ar.error}`];
+    return [
+      ar.report.compliant ? 'ok' : 'warn',
+      ar.report.compliant
+        ? 'Codex adapter structurally wired (run `phronesis adapter test codex` for the full behavioral check)'
+        : 'Codex adapter not fully wired — run `phronesis adapter test codex` (Codex is the secondary surface; Claude Code is primary/always-on)',
+    ];
+  });
+
+  // user_profile — warn if any domain's USER.md still carries [Name]/[Role] (D4).
+  await guarded('user_profile', 'warn', () => userProfile(root, domains));
+
+  // pending_drafts — warn with the count under .phronesis/drafts/ (D4).
+  await guarded('pending_drafts', 'warn', () => pendingDrafts(root));
+
+  // schedule (core-0051 / change 0042) — a malformed schedule registry OR entries overdue by
+  // > 2× cadence are WARN, never fail: the schedule is a SEPARATE failure domain (a bad one
+  // does not disable the action layer — ratification (a)), and `phronesis validate` is where the
+  // hard contract check lives. Read-only (validateScheduleRegistry + scheduleStaleness are pure).
+  await guarded('schedule', 'warn', () => scheduleHealth(root));
+
+  return finalize(root, checks);
+}
+
+function finalize(root, checks) {
+  const summary = { ok: 0, warn: 0, fail: 0 };
+  for (const c of checks) summary[c.status] += 1;
+  const exit = summary.fail > 0 ? 1 : 0;
+  return { root, checks, summary, exit };
+}
+
+async function hookWiring(root, registry, registryError, domains) {
+  if (registryError) {
+    return ['fail', `registry.json unreadable (${registryError}) — cannot verify hook wiring`];
+  }
+  // Compose the REAL hook validator (D3 — don't re-implement a shallow check). An INVALID hooks
+  // section (a non-array, an unknown key, a v0-registry, a malformed entry) DISABLES the action
+  // layer (actions.js: the act pipeline refuses a hooks section it cannot parse), so it is a FAIL —
+  // the same class as an invalid skill registry — not a mere wiring warn (Codex round-2 F1).
+  const hookRes = resolveHooks(registry);
+  if (hookRes.errors.length) {
+    return ['fail', `invalid hooks registry (the action layer is disabled until fixed): ${hookRes.errors.slice(0, 3).join('; ').slice(0, 300)}`];
+  }
+  const missing = [];
+  const hooks = Array.isArray(registry.hooks) ? registry.hooks : [];
+  // The default reinforcement subscription (the post-compile active-context projection refresh) must
+  // be present AND match the SCAFFOLDED contract (Codex round-4 F2): an id-only check would pass a
+  // drifted/dead subscription (wrong event / filter / command) while reporting healthy. Compose the
+  // contract from layout.js (the single source init writes) — comparing the functional fields
+  // (subscribes_to / filter / command), not quota/classification an operator may legitimately tune.
+  const scaffoldDefault = registryJson(['pm']).hooks.find((h) => h.id === 'compile-active-context');
+  const defaultHook = hooks.find((h) => h && h.id === 'compile-active-context');
+  if (!defaultHook) {
+    missing.push('the default compile-active-context hook subscription is absent');
+  } else if (scaffoldDefault) {
+    if (JSON.stringify(defaultHook.subscribes_to) !== JSON.stringify(scaffoldDefault.subscribes_to)) missing.push('compile-active-context.subscribes_to drifted from the scaffolded wiring');
+    if (JSON.stringify(defaultHook.filter) !== JSON.stringify(scaffoldDefault.filter)) missing.push('compile-active-context.filter drifted from the scaffolded wiring');
+    if (defaultHook.command !== scaffoldDefault.command) missing.push('compile-active-context.command drifted from the scaffolded wiring');
+  }
+  for (const h of hooks) {
+    const cmd = h && typeof h.command === 'string' ? h.command : null;
+    if (!cmd) {
+      missing.push('a hook subscription has no command');
+      continue;
+    }
+    const p = join(root, cmd);
+    if (!existsSync(p)) missing.push(`${cmd} (missing)`);
+    else if (!isExecutable(p)) missing.push(`${cmd} (not executable)`);
+  }
+  // The Claude Code surface config must be a regular file with parseable JSON (Codex round-4 F3) —
+  // a directory or malformed JSON at that path is not a usable config.
+  const claudeCfg = join(root, '.claude', 'settings.json');
+  if (!existsSync(claudeCfg)) missing.push('.claude/settings.json (Claude Code surface config) missing');
+  else if (!isFileParseableJson(claudeCfg)) missing.push('.claude/settings.json is not a readable JSON file (a directory or malformed)');
+  for (const slug of domains) {
+    // domains is pre-validated to string slugs (F2) — safe to join.
+    if (!existsSync(join(root, 'domains', slug, '.codex', 'hooks.json'))) missing.push(`domains/${slug}/.codex/hooks.json (Codex surface config) missing`);
+  }
+  if (missing.length) return ['warn', `incomplete hook wiring: ${missing.join('; ')}`];
+  return ['ok', 'hooks registry valid; in-pipeline scripts present + executable; .claude + .codex surface configs present'];
+}
+
+async function userProfile(root, domains) {
+  const slugs = domains.length ? domains : ['pm']; // best-effort when no valid domains resolved
+  const unfilled = [];
+  for (const slug of slugs) {
+    try {
+      const text = await readFile(join(root, 'domains', slug, 'USER.md'), 'utf8');
+      if (text.includes('[Name]') || text.includes('[Role]')) unfilled.push(slug);
+    } catch (err) {
+      unfilled.push(`${slug} (USER.md unreadable: ${err.code || err.message})`);
+    }
+  }
+  if (unfilled.length) {
+    return ['warn', `USER.md still has [Name]/[Role] placeholders for: ${unfilled.join(', ')} — fill it in (or re-run \`phronesis init\` with --name/--role)`];
+  }
+  return ['ok', 'USER.md personalized (no [Name]/[Role] placeholders)'];
+}
+
+async function scheduleHealth(root) {
+  const v = await validateScheduleRegistry({ installRoot: root });
+  if (!v.ok) {
+    return ['warn', `.phronesis/schedule.json invalid (${v.errors.length} issue(s)) — run \`phronesis validate\`: ${v.errors.slice(0, 2).join('; ').slice(0, 300)}`];
+  }
+  const warns = [];
+  const { stale } = await scheduleStaleness({ installRoot: root });
+  if (stale.length) {
+    const detail = stale.map((s) => `${s.schedule_id} (${s.days_overdue}d overdue, ${s.cadence_days}d cadence)`).join(', ');
+    warns.push(`${stale.length} schedule(s) overdue by > 2× cadence: ${detail} — run \`phronesis due\``);
+  }
+  // Runtime-state gitignore gap (Codex round-9 F3): a fresh scaffold ignores `.phronesis/state/`,
+  // but an install created BEFORE this feature and upgraded to this CLI has an older .gitignore.
+  // Once completion state is written there it becomes git-trackable. Export is safe regardless
+  // (the exclude globs are code-driven), so this is a WARN — flag it once state actually exists.
+  if (existsSync(join(root, '.phronesis', 'state')) && !gitignoreCoversState(root)) {
+    warns.push('runtime schedule state (.phronesis/state/) exists but is not in .gitignore — an install predating this feature; add `.phronesis/state/` so completion state stays out of git (`phronesis export` already excludes it)');
+  }
+  if (warns.length) return ['warn', warns.join('; ')];
+  return ['ok', 'schedule registry valid; no entries overdue by > 2× cadence'];
+}
+
+function gitignoreCoversState(root) {
+  try {
+    return readFileSync(join(root, '.gitignore'), 'utf8').includes('.phronesis/state/');
+  } catch {
+    return false; // no .gitignore ⇒ not covered
+  }
+}
+
+async function pendingDrafts(root) {
+  const base = join(root, '.phronesis', 'drafts');
+  if (!existsSync(base)) return ['ok', 'no pending compile drafts'];
+  let count = 0;
+  for (const domainEnt of await readdir(base, { withFileTypes: true })) {
+    if (!domainEnt.isDirectory()) continue;
+    const domainDir = join(base, domainEnt.name);
+    for (const typeEnt of await readdir(domainDir, { withFileTypes: true })) {
+      if (!typeEnt.isDirectory()) continue;
+      for (const f of await readdir(join(domainDir, typeEnt.name))) {
+        if (f.endsWith('.md')) count += 1;
+      }
+    }
+  }
+  if (count > 0) return ['warn', `${count} pending compile draft(s) under .phronesis/drafts/ — run \`phronesis compile review\``];
+  return ['ok', 'no pending compile drafts'];
+}
+
+// --- CLI wrapper: print (human or json) + set the exit code (D4). doctor's exit is its OWN —
+// neither skillsStatusReport nor codexAdapterReport sets process.exitCode (they are pure), so no
+// composed surface's exit leaks here.
+export async function runDoctor({ dir, json = false } = {}) {
+  const report = await doctorReport({ dir });
+  if (json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    printHuman(report);
+  }
+  process.exitCode = report.exit;
+  return report;
+}
+
+function printHuman(report) {
+  const mark = (s) => (s === 'ok' ? '✓' : s === 'warn' ? '!' : '✗');
+  console.log(`phronesis doctor — ${report.root || '(no install)'}`);
+  console.log('');
+  for (const c of report.checks) {
+    console.log(`  ${mark(c.status)} ${c.id}${c.detail ? ` — ${c.detail}` : ''}`);
+  }
+  console.log('');
+  const { ok, warn, fail } = report.summary;
+  console.log(`  ${ok} ok · ${warn} warn · ${fail} fail`);
+  console.log(
+    report.exit === 0
+      ? warn
+        ? '  Install is healthy (warnings above are informational, not blocking).'
+        : '  Install is healthy.'
+      : '  Install has FAIL-level issues above — resolve them before dogfooding.',
+  );
+}

package/src/due.js

@@ -0,0 +1,271 @@
+// `phronesis due [--json]`, `phronesis due complete <id>`, and
+// `phronesis due run <id>` (core-0051/core-0058 / change 0042).
+// CLI glue only (the boundary rule): the registry load, the pure due computation, and the
+// completion floor live in @phronesis/core (schedule.js). This module resolves the install,
+// formats, and sets the exit code.
+//
+// `phronesis due` is a PURE READ (D2): it computes overdue entries from the registry + the
+// runtime state + the clock, prints them, and MUTATES NOTHING, EMITS NOTHING. The
+// `schedule.due` events are the session-start due-check's job (`phronesis hooks due-check`),
+// so the event's provenance stays with the authoritative emitter.
+
+import { spawn } from 'node:child_process';
+import { realpathSync, statSync } from 'node:fs';
+import { isAbsolute, relative, resolve as resolvePath, sep } from 'node:path';
+import {
+  resolveInstall,
+  computeScheduleDue,
+  validateScheduleRegistry,
+  loadScheduleRegistry,
+  markScheduleCompleted,
+} from '@phronesis/core';
+import { run as runCliDispatch } from './cli.js';
+
+function installOrFail(dir) {
+  const r = resolveInstall({ dir });
+  if (r.error) {
+    console.error(r.error);
+    process.exitCode = 1;
+    return null;
+  }
+  return r.root;
+}
+
+function overduePhrase(daysOverdue) {
+  return daysOverdue === 0 ? 'due now' : `${daysOverdue} day(s) overdue`;
+}
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function cliVerbArgs(target) {
+  return target.trim().split(/\s+/).filter(Boolean);
+}
+
+function outsideRoot(root, target) {
+  const rel = relative(root, target);
+  return rel === '' || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel);
+}
+
+export function resolveConnectorPullRunTarget(installRoot, target) {
+  if (isAbsolute(target)) {
+    return { error: `connector_pull target "${target}" must be install-relative, not an absolute path` };
+  }
+  const resolved = resolvePath(installRoot, target);
+  if (outsideRoot(installRoot, resolved)) {
+    return { error: `connector_pull target "${target}" resolves outside the install root` };
+  }
+  let realTarget;
+  try {
+    realTarget = realpathSync(resolved);
+  } catch {
+    return { error: `connector_pull target "${target}" does not exist under the install root` };
+  }
+  let realRoot;
+  try {
+    realRoot = realpathSync(installRoot);
+  } catch {
+    realRoot = installRoot;
+  }
+  if (outsideRoot(realRoot, realTarget)) {
+    return { error: `connector_pull target "${target}" resolves (via a symlink) outside the install root` };
+  }
+  let st;
+  try {
+    st = statSync(realTarget);
+  } catch {
+    return { error: `connector_pull target "${target}" does not exist under the install root` };
+  }
+  if (!st.isFile() || !(st.mode & 0o111)) {
+    return { error: `connector_pull target "${target}" is not an executable file (needs the executable bit)` };
+  }
+  return { abs: realTarget };
+}
+
+async function runConnectorPull({ installRoot, target }) {
+  const resolved = resolveConnectorPullRunTarget(installRoot, target);
+  if (resolved.error) throw new Error(resolved.error);
+  return new Promise((resolve) => {
+    const child = spawn(resolved.abs, [], {
+      cwd: installRoot,
+      env: process.env,
+      stdio: ['ignore', 'inherit', 'inherit'],
+    });
+    child.on('error', (err) => {
+      console.error(`due run: failed to execute connector_pull target "${target}": ${err.message}`);
+      resolve(1);
+    });
+    child.on('close', (code, signal) => {
+      if (signal) {
+        console.error(`due run: connector_pull target "${target}" terminated by signal ${signal}.`);
+        resolve(1);
+      } else {
+        resolve(code ?? 1);
+      }
+    });
+  });
+}
+
+// Pure read: registry + clock → overdue list. No events, no writes.
+export async function runDue({ dir, json = false } = {}) {
+  const installRoot = installOrFail(dir);
+  if (!installRoot) return null;
+  try {
+    // Fail closed: a registry that would fail `validate` surfaces NOTHING and exits non-zero —
+    // never a partial/invalid due list (Codex round-2 F1). `validate` is the fix path.
+    const { ok, errors } = await validateScheduleRegistry({ installRoot });
+    if (!ok) {
+      console.error(
+        `schedule.json is invalid — run \`phronesis validate\` to fix it (not surfacing schedules until then). First issue: ${errors[0]}`,
+      );
+      if (json) console.log('[]');
+      process.exitCode = 1;
+      return [];
+    }
+    const due = await computeScheduleDue({ installRoot });
+    if (json) {
+      console.log(JSON.stringify(due));
+      process.exitCode = 0;
+      return due;
+    }
+    if (!due.length) {
+      console.log('No schedule entries due.');
+      process.exitCode = 0;
+      return due;
+    }
+    console.log(`Phronesis schedule: ${due.length} item(s) due.`);
+    for (const d of due) {
+      console.log(`\n  ${d.schedule_id} — ${d.kind}:${d.target} — ${overduePhrase(d.days_overdue)}`);
+      if (d.kind === 'cli_verb' || d.kind === 'connector_pull') {
+        console.log(`    run now: phronesis due run ${d.schedule_id}`);
+      }
+      console.log(`    mark done: phronesis due complete ${d.schedule_id}`);
+    }
+    process.exitCode = 0;
+    return due;
+  } catch (err) {
+    console.error(`due: ${err.message}`);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
+// Operator-invoked executor for deterministic schedule kinds (core-0058). `kind: skill`
+// remains session work: run the skill in the operator session, then use the explicit floor.
+export async function runDueRun({ dir, scheduleId } = {}) {
+  const installRoot = installOrFail(dir);
+  if (!installRoot) return null;
+  if (!scheduleId) {
+    console.error('due run: a schedule <id> is required (e.g. `phronesis due run gmail-pull-daily`).');
+    process.exitCode = 1;
+    return null;
+  }
+  try {
+    const { ok, errors } = await validateScheduleRegistry({ installRoot });
+    if (!ok) {
+      console.error(`due run: schedule.json is invalid — run \`phronesis validate\` first (${errors[0]}).`);
+      process.exitCode = 1;
+      return null;
+    }
+    const { schedules } = await loadScheduleRegistry({ installRoot });
+    const entry = schedules.find((e) => isPlainObject(e) && e.id === scheduleId);
+    if (!entry) {
+      console.error(`due run: no schedule "${scheduleId}" in .phronesis/schedule.json.`);
+      process.exitCode = 1;
+      return null;
+    }
+    if (entry.kind === 'skill') {
+      console.error(
+        `due run: schedule "${scheduleId}" is kind: skill. Skills run in operator sessions; run the skill, then \`phronesis due complete ${scheduleId}\`.`,
+      );
+      process.exitCode = 1;
+      return null;
+    }
+    if (entry.kind !== 'cli_verb' && entry.kind !== 'connector_pull') {
+      console.error(`due run: schedule "${scheduleId}" has unsupported kind "${entry.kind}".`);
+      process.exitCode = 1;
+      return null;
+    }
+
+    const priorCwd = process.cwd();
+    let code = 0;
+    if (entry.kind === 'connector_pull') {
+      code = await runConnectorPull({ installRoot, target: entry.target });
+    } else {
+      const args = cliVerbArgs(entry.target);
+      if (!args.length) {
+        console.error(`due run: schedule "${scheduleId}" has an empty cli_verb target.`);
+        process.exitCode = 1;
+        return null;
+      }
+      if (args[0] === 'due') {
+        console.error(
+          `due run: schedule "${scheduleId}" has a cli_verb target that invokes \`phronesis due\`; run schedule completion explicitly instead.`,
+        );
+        process.exitCode = 1;
+        return null;
+      }
+      process.exitCode = 0;
+      try {
+        process.chdir(installRoot);
+        await runCliDispatch(args);
+        code = process.exitCode ?? 0;
+      } finally {
+        process.chdir(priorCwd);
+      }
+    }
+
+    if (code !== 0) {
+      console.error(`due run: target for "${scheduleId}" exited non-zero (${code}); schedule not completed.`);
+      process.exitCode = code || 1;
+      return null;
+    }
+
+    const result = await markScheduleCompleted({
+      installRoot,
+      scheduleId,
+      actor: process.env.PHRONESIS_ACTOR || 'operator',
+      surface: 'cli',
+      ranTarget: entry.target,
+    });
+    console.log(`Ran "${result.schedule_id}" (${entry.kind}:${entry.target}) and marked complete (${result.last_completed}).`);
+    process.exitCode = 0;
+    return result;
+  } catch (err) {
+    console.error(`due run: ${err.message}`);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
+// The explicit, surface-independent completion floor (D4): advance last_completed for <id>.
+// Required because Codex emits no `skill.completed`, so automatic advancement cannot be the
+// only path. Refuses an id absent from the registry.
+export async function runDueComplete({ dir, scheduleId } = {}) {
+  const installRoot = installOrFail(dir);
+  if (!installRoot) return null;
+  if (!scheduleId) {
+    console.error('due complete: a schedule <id> is required (e.g. `phronesis due complete lint-weekly`).');
+    process.exitCode = 1;
+    return null;
+  }
+  try {
+    const result = await markScheduleCompleted({
+      installRoot,
+      scheduleId,
+      // `due complete` is operator-invoked (packet D4) → attribute the audit trail to the
+      // operator by default; a surface adapter that runs it on the operator's behalf overrides
+      // via PHRONESIS_ACTOR (Codex round-7 F2).
+      actor: process.env.PHRONESIS_ACTOR || 'operator',
+      surface: 'cli',
+    });
+    console.log(`Marked "${result.schedule_id}" complete (${result.last_completed}).`);
+    process.exitCode = 0;
+    return result;
+  } catch (err) {
+    console.error(err.message);
+    process.exitCode = 1;
+    return null;
+  }
+}