phronesis 1.0.0

package/vendor/core/src/schedule.js

@@ -0,0 +1,535 @@
+// Schedule registry + cadence primitive (core-0051; change 0042 — RATIFIED 2026-07-04).
+//
+// The V1-shaped PULL layer of the scheduled-invocation contract: a typed, operator-authored
+// schedule registry, a deterministic `phronesis due` read, the session-start due-check
+// extension that emits `schedule.due`, and the completion floor. No daemon, no headless
+// model call, no new action types (the daemon time-watch + auto-run is Layer 2 / V1.5).
+//
+// SEPARATE FAILURE DOMAIN (ratification (a)): declarations live in `.phronesis/schedule.json`,
+// NOT inside `registry.json`. `registry.json` is the strict all-or-nothing action-layer loader
+// (core-0011: present-but-invalid disables the section); a malformed schedule entry must never
+// take the action layer down with it. So this module owns its own load/validate, and a bad
+// schedule is a `validate` hard-fail + a `doctor` warn — never an action-layer outage.
+//
+// DECLARATIONS vs RUNTIME STATE (ratification (d), change 0008 tracked-vs-derived line):
+//   - `.phronesis/schedule.json`      — durable operator-authored cadence; TRACKED + exported.
+//   - `.phronesis/state/schedule-state.json` — mutable `last_completed` per id; GITIGNORED +
+//     export-excluded. Losing it degrades honestly: every schedule surfaces as due once and
+//     completion rebuilds from operator confirmations — over-surfacing, never a silent skip.
+//
+// Pure core: no CLI, no provider/model endpoint, no network. The zero-API-key guard (D6) is a
+// property of this file — nothing here reaches a model; only an operator session runs a target.
+
+import { join, resolve, relative, isAbsolute, sep } from 'node:path';
+import { readFile, writeFile, rename } from 'node:fs/promises';
+import { statSync, realpathSync } from 'node:fs';
+import fse from 'fs-extra';
+import { RE_SLUG } from './contract.js';
+import { appendAuditEntry } from './hook-executor.js';
+import { appendEvent, localDateStamp } from './event-log.js';
+
+// The install-relative paths (single source — validators, doctor, export, and the scaffold
+// all key on these two strings so a rename can never half-land).
+export const SCHEDULE_REGISTRY_REL = join('.phronesis', 'schedule.json');
+export const SCHEDULE_STATE_REL = join('.phronesis', 'state', 'schedule-state.json');
+
+// The three target kinds (proposal §"schedule registry"). `skill` runs inside an operator
+// session; `cli_verb`/`connector_pull` are deterministic, model-free work.
+export const SCHEDULE_KINDS = Object.freeze(['skill', 'cli_verb', 'connector_pull']);
+
+// The only fields a schedule entry may carry. Unknown keys are REFUSED (validate hard-fails):
+// the registry is contract, not a junk drawer — and JSON has no comments, so a `$comment`
+// workaround is forbidden by exactly this refusal (change 0041 / F2).
+const ENTRY_KEYS = new Set(['id', 'kind', 'target', 'cadence', 'unattended', 'domain', 'classification']);
+
+// V1 cadence grammar (ratification (b)): SIMPLE DAY INTERVALS only — `1d`/`7d`/`30d`-class.
+// The overdue unit is whole days (`days_overdue`). Hour-grain and cron are deferred + additive
+// (V1's only execution layer is the session-start pull, so a sub-day cadence could not fire
+// more often than sessions anyway). A leading-zero / zero / non-positive interval is invalid.
+const CADENCE_RE = /^[1-9][0-9]*d$/;
+
+export function parseCadenceDays(cadence) {
+  if (typeof cadence !== 'string' || !CADENCE_RE.test(cadence)) return null;
+  const n = Number(cadence.slice(0, -1));
+  // Reject overflow: a huge digit string matches the regex but `Number(...)` is `Infinity`
+  // (or a precision-losing value), which would pass validation and then make every due check
+  // compute `daysBetween - Infinity` ⇒ negative ⇒ silently never due (Codex round-8 F2).
+  return Number.isSafeInteger(n) && n > 0 ? n : null;
+}
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+// Strict YYYY-MM-DD calendar validation → UTC ms, or null. A value that MATCHES the regex but
+// is not a real calendar date (`2026-02-31`, `9999-99-99`) must be rejected, not normalized:
+// `Date.UTC` silently rolls `2026-02-31` to Mar 3, which would let CORRUPT runtime state
+// masquerade as a real completion and SILENTLY SKIP a due schedule (Codex round-4 F2). The
+// round-trip check (reconstructed components === input) is what makes corrupt state degrade to
+// "absent" ⇒ over-surface, per the state-loss contract.
+function parseDateStamp(s) {
+  if (typeof s !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(s)) return null;
+  const [y, m, d] = s.split('-').map(Number);
+  const utc = Date.UTC(y, m - 1, d);
+  const back = new Date(utc);
+  if (back.getUTCFullYear() !== y || back.getUTCMonth() !== m - 1 || back.getUTCDate() !== d) return null;
+  return utc;
+}
+
+// Whole days between two VALIDATED YYYY-MM-DD stamps (UTC date math — both are local stamps, so
+// the difference is exact whole days). Callers must pre-validate with parseDateStamp.
+function daysBetween(fromStamp, toStamp) {
+  const toUtc = (s) => {
+    const [y, m, d] = s.split('-').map(Number);
+    return Date.UTC(y, m - 1, d);
+  };
+  return Math.round((toUtc(toStamp) - toUtc(fromStamp)) / 86_400_000);
+}
+
+// --- Load (tolerant reads; validate owns the hard errors) --------------------------------
+
+// Read `.phronesis/schedule.json`. Only a genuinely-ABSENT file (ENOENT) is the honest empty
+// registry — a fresh install ships `{"schedules":[]}` but a hand-deleted file behaves the same.
+// A PRESENT-but-unreadable path (a directory at that name → EISDIR, a permission error → EACCES)
+// is NOT "absent": it returns `{ schedules: [], error }` so `validate` fails closed and
+// `due`/`doctor` surface the fault instead of silently skipping declared schedules (rules.md
+// core-0012: an error-swallowing reader makes a broken file read as empty). A malformed-JSON /
+// wrong-shape file likewise carries an `error`.
+export async function loadScheduleRegistry({ installRoot } = {}) {
+  let raw;
+  try {
+    raw = await readFile(join(installRoot, SCHEDULE_REGISTRY_REL), 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return { schedules: [] };
+    return { schedules: [], error: `schedule.json is present but unreadable: ${err.message}` };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    return { schedules: [], error: `schedule.json is not valid JSON: ${err.message}` };
+  }
+  if (!isPlainObject(parsed) || !Array.isArray(parsed.schedules)) {
+    return { schedules: [], error: 'schedule.json must be a JSON object of shape { "schedules": [ … ] }' };
+  }
+  return { schedules: parsed.schedules, raw: parsed };
+}
+
+// Read the runtime state file. Missing OR malformed → an empty state (over-surface, never a
+// silent skip — the whole point of the declarations/state split).
+export async function loadScheduleState({ installRoot } = {}) {
+  try {
+    const raw = await readFile(join(installRoot, SCHEDULE_STATE_REL), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (isPlainObject(parsed) && isPlainObject(parsed.last_completed)) {
+      return { last_completed: { ...parsed.last_completed } };
+    }
+  } catch {
+    // fall through to empty
+  }
+  return { last_completed: {} };
+}
+
+// Atomically persist the runtime state (temp + rename — rules.md core-0003 atomic-write rule;
+// a crash mid-write leaves EITHER the old file or the new, never a torn one). Creates
+// `.phronesis/state/` on first write (the dir is NOT scaffolded — it is gitignored runtime
+// state that exists only once a completion has been recorded).
+export async function writeScheduleState({ installRoot, state } = {}) {
+  const abs = join(installRoot, SCHEDULE_STATE_REL);
+  await fse.ensureDir(join(installRoot, '.phronesis', 'state'));
+  const body = { last_completed: state.last_completed || {} };
+  const tmp = `${abs}.partial-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
+  await writeFile(tmp, `${JSON.stringify(body, null, 2)}\n`);
+  await rename(tmp, abs);
+  return body;
+}
+
+// --- Validation (the `phronesis validate` schedule pass; FS-aware for connector_pull) -----
+
+// Validate `.phronesis/schedule.json`. Returns { ok, errors } — a flat list of specific
+// reasons (rules.md: assert the specific reason). A MISSING registry is valid (empty). Every
+// class of fault is a HARD error (refuse), so a contract-breaking schedule can never be blessed:
+//   - top-level shape / unknown top-level key
+//   - per-entry: missing/duplicate/non-slug id, unknown kind, empty target, bad cadence,
+//     non-boolean unattended, non-slug domain, unknown classification, UNKNOWN FIELD
+//   - connector_pull target: absolute path, resolution outside the install root, or a target
+//     that is not a regular file with the executable bit (build directive 2026-07-04: each
+//     REFUSES — fail-closed, not warn; a schedule that pulls an external account must point at
+//     a real, install-owned, runnable target or it does not load).
+export async function validateScheduleRegistry({ installRoot } = {}) {
+  let raw;
+  try {
+    raw = await readFile(join(installRoot, SCHEDULE_REGISTRY_REL), 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return { ok: true, errors: [] }; // genuinely absent ⇒ nothing to validate
+    // Present-but-unreadable (a directory at the path, a permission error) FAILS CLOSED — never
+    // indistinguishable from "no registry" (Codex F3; rules.md core-0012 error-swallowing reader).
+    return { ok: false, errors: [`schedule.json is present but unreadable: ${err.message}`] };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    return { ok: false, errors: [`schedule.json is not valid JSON: ${err.message}`] };
+  }
+  const errors = [];
+  if (!isPlainObject(parsed)) {
+    return { ok: false, errors: ['schedule.json must be a JSON object of shape { "schedules": [ … ] }'] };
+  }
+  for (const key of Object.keys(parsed)) {
+    if (key !== 'schedules') errors.push(`schedule.json: unknown top-level key "${key}" (only "schedules" is allowed — the registry is contract, not a junk drawer; JSON has no comments)`);
+  }
+  if (!Array.isArray(parsed.schedules)) {
+    errors.push('schedule.json: "schedules" must be an array');
+    return { ok: false, errors };
+  }
+
+  const seenIds = new Set();
+  parsed.schedules.forEach((entry, i) => {
+    const at = `schedule[${i}]`;
+    if (!isPlainObject(entry)) {
+      errors.push(`${at}: each schedule must be a JSON object`);
+      return;
+    }
+    for (const key of Object.keys(entry)) {
+      if (!ENTRY_KEYS.has(key)) errors.push(`${at}: unknown field "${key}" (allowed: ${[...ENTRY_KEYS].join(', ')})`);
+    }
+    // id — required, unique, kebab-case slug (the same grammar the rest of the substrate uses).
+    const id = entry.id;
+    if (typeof id !== 'string' || !RE_SLUG.test(id)) {
+      errors.push(`${at}: "id" is required and must be a kebab-case slug`);
+    } else if (seenIds.has(id)) {
+      errors.push(`${at}: duplicate id "${id}" (schedule ids must be unique)`);
+    } else {
+      seenIds.add(id);
+    }
+    // kind
+    if (!SCHEDULE_KINDS.includes(entry.kind)) {
+      errors.push(`${at}${idTag(id)}: "kind" must be one of ${SCHEDULE_KINDS.join(' | ')}`);
+    }
+    // target
+    if (typeof entry.target !== 'string' || entry.target.trim() === '') {
+      errors.push(`${at}${idTag(id)}: "target" is required and must be a non-empty string`);
+    } else if (entry.kind === 'skill' && !RE_SLUG.test(entry.target)) {
+      // A skill target is a skill NAME (a kebab-case slug). Auto-completion matches it exactly
+      // against `skill.completed`'s skill_name, so a typo with whitespace ("lint ") or a bad slug
+      // would pass a non-empty-string check yet never auto-complete (Codex round-9 F1). Fail it
+      // here. (Registration is NOT required — an operator may forward-declare a skill they will
+      // install; a slug is the format guarantee.)
+      errors.push(`${at}${idTag(id)}: a "skill" target must be a kebab-case skill name (no whitespace, e.g. "lint" or "prd-draft")`);
+    } else if (entry.kind === 'connector_pull') {
+      const targetErr = connectorPullTargetError(installRoot, entry.target);
+      if (targetErr) errors.push(`${at}${idTag(id)}: ${targetErr}`);
+    }
+    // cadence
+    if (parseCadenceDays(entry.cadence) === null) {
+      errors.push(`${at}${idTag(id)}: "cadence" must be a simple day interval (e.g. 1d, 7d, 30d) — V1 grammar (hours/cron deferred)`);
+    }
+    // unattended — optional; boolean only
+    if ('unattended' in entry && typeof entry.unattended !== 'boolean') {
+      errors.push(`${at}${idTag(id)}: "unattended" must be a boolean (default false)`);
+    }
+    // domain — optional; slug
+    if ('domain' in entry && (typeof entry.domain !== 'string' || !RE_SLUG.test(entry.domain))) {
+      errors.push(`${at}${idTag(id)}: "domain" must be a kebab-case domain slug`);
+    }
+    // classification — optional; V1 supports ONLY `acknowledged`. The `on_schedule_due` posture
+    // is fixed acknowledged (specs/hooks.md — batched, dismissible, attributed to the operator),
+    // and the due-check surfaces every schedule that way; accepting `silent`/`interactive` would
+    // be valid data the runtime silently ignores (Codex round-9 F2). Restrict to what V1 honors;
+    // silent/interactive schedule surfacing is a deferred widening.
+    if ('classification' in entry && entry.classification !== 'acknowledged') {
+      errors.push(`${at}${idTag(id)}: V1 supports only "classification": "acknowledged" for schedules (silent/interactive surfacing is deferred)`);
+    }
+  });
+
+  return { ok: errors.length === 0, errors };
+}
+
+function idTag(id) {
+  return typeof id === 'string' && id ? ` "${id}"` : '';
+}
+
+function outsideRoot(root, target) {
+  const rel = relative(root, target);
+  // Outside when rel is empty (== root itself), is `..`/`../…`, or is absolute. Anchored on
+  // `sep` so a legitimately-named file like `..foo` is NOT a false positive.
+  return rel === '' || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel);
+}
+
+// connector_pull target rule (F6 + build directive 2026-07-04). The operator-authored entry IS
+// the allowlist (no bridge registry in V1), so the target must be an install-relative, in-root,
+// runnable executable. Containment is checked BOTH lexically (a clean error on an obvious `../`)
+// AND after realpath resolution of BOTH the target and the install root (Codex F1; rules.md
+// core-0034: realpath both sides) — so an in-root SYMLINK pointing at an executable OUTSIDE the
+// root cannot slip past a purely-lexical check (statSync/realpath follow links). Returns an
+// error STRING (refuse) or null (ok).
+function connectorPullTargetError(installRoot, target) {
+  if (isAbsolute(target)) {
+    return `connector_pull target "${target}" must be install-relative, not an absolute path`;
+  }
+  const resolved = resolve(installRoot, target);
+  if (outsideRoot(installRoot, resolved)) {
+    return `connector_pull target "${target}" resolves outside the install root`;
+  }
+  // Physical containment: realpath BOTH sides (the install root may itself sit under a symlinked
+  // prefix — /tmp→/private/tmp, /var/folders — so normalizing only one side breaks the compare).
+  let realTarget;
+  try {
+    realTarget = realpathSync(resolved);
+  } catch {
+    return `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 `connector_pull target "${target}" resolves (via a symlink) outside the install root`;
+  }
+  let st;
+  try {
+    st = statSync(realTarget);
+  } catch {
+    return `connector_pull target "${target}" does not exist under the install root`;
+  }
+  if (!st.isFile() || !(st.mode & 0o111)) {
+    return `connector_pull target "${target}" is not an executable file (needs the executable bit)`;
+  }
+  return null;
+}
+
+// --- Due computation (D2 — a PURE read: emits nothing, writes nothing) --------------------
+
+// Overdue entries as a deterministic list `{ schedule_id, target, kind, days_overdue }`, sorted
+// by schedule_id. Pure function of (registry, state, clock): the completion source of truth is
+// state.last_completed (advanced by the completion floor + the session-start reconcile). A
+// never-completed entry surfaces once as due with days_overdue 0 (there is no anchor to measure
+// overdue-ness against, and inventing one would be dishonest). Malformed / cadence-less entries
+// are SKIPPED here (validate is the place that fails on them) so `due` degrades, never throws.
+export async function computeScheduleDue({ installRoot, now = new Date() } = {}) {
+  // Fail closed (Codex round-2 F1): a registry that would fail `validate` surfaces NOTHING.
+  // due/due-check must never return or emit an entry the contract rejects — a bad `kind`, an
+  // empty `target`, or a `connector_pull` target outside the root or without the exec bit.
+  // Surfacing/emitting those would half-legitimize an invalid declaration; `validate` is the fix
+  // path (all-or-nothing, mirroring the validator's own semantics). Pure: validate only reads.
+  const { ok } = await validateScheduleRegistry({ installRoot });
+  if (!ok) return [];
+  const today = localDateStamp(now);
+  const { schedules } = await loadScheduleRegistry({ installRoot });
+  const { last_completed } = await loadScheduleState({ installRoot });
+  const due = [];
+  for (const entry of schedules) {
+    if (!isPlainObject(entry)) continue;
+    const { id, target, kind, cadence } = entry;
+    if (typeof id !== 'string' || !id) continue;
+    const cadenceDays = parseCadenceDays(cadence);
+    if (cadenceDays === null) continue;
+    const last = last_completed[id];
+    let daysOverdue;
+    if (parseDateStamp(last) === null || last > today) {
+      // Never completed, state lost, a corrupt/non-calendar date, OR a nonsensical FUTURE
+      // completion (clock skew / corruption — you cannot complete work in the future; Codex
+      // round-6 F2) ⇒ surface once (over-surface, never a silent skip). A regex-matching-but-
+      // invalid or future date is treated as absent, never trusted to suppress a due schedule.
+      daysOverdue = 0;
+    } else {
+      daysOverdue = daysBetween(last, today) - cadenceDays;
+      if (daysOverdue < 0) continue; // not yet due
+    }
+    due.push({ schedule_id: id, target, kind, days_overdue: daysOverdue });
+  }
+  due.sort((a, b) => (a.schedule_id < b.schedule_id ? -1 : a.schedule_id > b.schedule_id ? 1 : 0));
+  return due;
+}
+
+// --- Completion (advance last_completed) --------------------------------------------------
+
+// The EXPLICIT completion floor (`phronesis due complete <id>`; D4). Surface-independent —
+// required because Codex emits no `skill.completed`, so automatic advancement cannot be the
+// only path. Refuses an id absent from the registry (you cannot complete what you never
+// scheduled). Advances last_completed to the local day, persists, and writes the ordinary audit
+// trail (D4): a `schedule.completed` line to `.phronesis/audit.log` — the general operational
+// audit channel (gitignored/export-excluded, same class as the hook audit). The skill-boundary
+// advance needs no separate audit: the `skill.completed` event IS its trail.
+export async function markScheduleCompleted({ installRoot, scheduleId, actor = 'operator', surface = 'cli', now = new Date(), ranTarget } = {}) {
+  if (typeof scheduleId !== 'string' || scheduleId === '') {
+    throw new Error('due complete: a schedule id is required.');
+  }
+  // Fail closed (Codex round-4 F1): never RECORD completion against an invalid registry — a
+  // duplicate/ambiguous declaration would poison `last_completed` and then suppress the schedule
+  // the operator keeps after fixing the duplicate. `validate` is the fix path.
+  const { ok, errors } = await validateScheduleRegistry({ installRoot });
+  if (!ok) {
+    throw new Error(`due complete: schedule.json is invalid — run \`phronesis validate\` first (${errors[0]}).`);
+  }
+  const { schedules } = await loadScheduleRegistry({ installRoot });
+  const entry = schedules.find((e) => isPlainObject(e) && e.id === scheduleId);
+  if (!entry) {
+    throw new Error(`due complete: no schedule "${scheduleId}" in .phronesis/schedule.json.`);
+  }
+  const state = await loadScheduleState({ installRoot });
+  const completedOn = localDateStamp(now);
+  // AUDIT-FIRST, then persist state (PR #138 P2). If the audit append fails AFTER the state
+  // advanced, the schedule silently vanishes from `due` with no audit line — the exact silent
+  // skip this file promises never to do. Ordering the audit first makes BOTH failure modes fail
+  // in the safe (over-surface) direction: an audit failure leaves state un-advanced (still due);
+  // a state-write failure after the audit leaves an audit line for a not-yet-persisted completion
+  // (a record of intent) with the schedule still due — never a silent skip.
+  await appendAuditEntry(installRoot, {
+    event_type: 'schedule.completed',
+    schedule_id: scheduleId,
+    kind: entry.kind,
+    target: entry.target,
+    completed_on: completedOn,
+    actor,
+    surface,
+    outcome: 'schedule-completed',
+    ...(ranTarget ? { ran_target: ranTarget } : {}),
+  });
+  state.last_completed[scheduleId] = completedOn;
+  await writeScheduleState({ installRoot, state });
+  return { schedule_id: scheduleId, last_completed: completedOn };
+}
+
+// Automatic sugar for lifecycle-full surfaces (D4): when a `skill.completed` fires, advance
+// every `kind: skill` schedule whose target is that skill — AT THE COMPLETION BOUNDARY, keyed
+// on the completion's own day. Deliberately NOT a scan of the whole event log (Codex F2): a
+// history replay would rebuild completion from arbitrary past events, so a state-file loss could
+// be silently "healed" by a stale `skill.completed` and SUPPRESS the promised one-time
+// resurfacing (proposal: state loss ⇒ every schedule surfaces as due once). Completion is
+// recorded FORWARD from the event, never reconstructed backward. Persists; returns the advanced
+// ids. Codex emits no `skill.completed`, so this never fires there — the explicit
+// `due complete` floor is the surface-independent path.
+export async function advanceSchedulesForSkill({ installRoot, skillName, now = new Date() } = {}) {
+  if (typeof skillName !== 'string' || skillName === '') return { advanced: [] };
+  // Fail safe (Codex round-4 F1): never mutate state against an invalid registry — no-op until
+  // `validate` is clean. (The explicit floor `due complete` refuses louder; this best-effort
+  // sugar, called from the guarded lifecycle-close boundary, simply declines.)
+  const { ok } = await validateScheduleRegistry({ installRoot });
+  if (!ok) return { advanced: [] };
+  const { schedules } = await loadScheduleRegistry({ installRoot });
+  const matches = schedules.filter(
+    (e) =>
+      isPlainObject(e) &&
+      e.kind === 'skill' &&
+      e.target === skillName &&
+      typeof e.id === 'string' &&
+      e.id &&
+      // Domain-SCOPED skill schedules are NOT auto-advanced (Codex round-6 F1): `skill.completed`
+      // carries no domain (D4: no new telemetry), so advancing by skill name alone would wrongly
+      // complete a DIFFERENT domain's same-named schedule (two `lint` entries scoped pm vs sales).
+      // Those use the explicit `due complete <id>` floor, where the operator knows the domain.
+      // A domain-AGNOSTIC schedule (no `domain`) auto-advances as before.
+      !e.domain,
+  );
+  if (matches.length === 0) return { advanced: [] };
+  const state = await loadScheduleState({ installRoot });
+  const completedOn = localDateStamp(now);
+  const advanced = [];
+  for (const entry of matches) {
+    const priorStr = state.last_completed[entry.id];
+    // Overwrite unless the prior is a VALID completion already on this exact day. This clears an
+    // absent/corrupt prior AND a FUTURE prior (> the completion day — clock skew/corruption),
+    // matching computeScheduleDue's future-date policy so a real skill run always un-sticks a
+    // schedule instead of leaving a `2099-01-01` value due forever (Codex round-8 F1). At the
+    // real-time completion boundary a legitimate prior is always <= the completion day, so this
+    // only ever regresses a corrupt future value, never a real later completion.
+    if (parseDateStamp(priorStr) === null || priorStr !== completedOn) {
+      state.last_completed[entry.id] = completedOn;
+      advanced.push(entry.id);
+    }
+  }
+  if (advanced.length) await writeScheduleState({ installRoot, state });
+  return { advanced };
+}
+
+// --- Session-start due-check extension (D3 — the authoritative `schedule.due` emitter) -----
+
+// Compute + emit: one `schedule.due` per due entry through core appendEvent — the SAME
+// authoritative path the V1.5 daemon time-watch will drive, and the reason freehand
+// `event emit schedule.due` is refused (the event's provenance stays with the due-check).
+// Completion is advanced at the skill.completed boundary (advanceSchedulesForSkill) and by the
+// explicit floor — NOT reconstructed here — so this stays a compute-then-emit with no history
+// scan. Returns the due list + events.
+export async function runScheduleDueCheck({
+  installRoot,
+  session,
+  actor = 'agent',
+  surface = 'cli',
+  now = new Date(),
+} = {}) {
+  if (typeof session !== 'string' || session === '') {
+    throw new Error('schedule due-check: session is required (a non-empty session id).');
+  }
+  const due = await computeScheduleDue({ installRoot, now });
+  const events = [];
+  for (const d of due) {
+    events.push(
+      await appendEvent({
+        installRoot,
+        type: 'schedule.due',
+        session_id: session,
+        actor,
+        surface,
+        payload: { schedule_id: d.schedule_id, target: d.target, kind: d.kind, days_overdue: d.days_overdue },
+        now,
+      }),
+    );
+  }
+  return { due, events };
+}
+
+// --- validate warn-and-prune + doctor staleness -------------------------------------------
+
+// Orphan state entries (a last_completed keyed by an id with no matching declaration) are
+// warn-and-pruned by `phronesis validate` (D1b). Fails SAFE: if the registry is malformed we
+// cannot know the valid id set, so nothing is pruned (never delete state we cannot confirm is
+// orphaned). Returns the pruned ids.
+export async function pruneOrphanScheduleState({ installRoot } = {}) {
+  // Never prune against an unreliable declared set (Codex round-2 F2): an entry-level-invalid
+  // registry (bad kind, duplicate id, unknown field, bad connector target) can misrepresent
+  // which ids are declared, so a real completion could be mis-pruned. Fail SAFE on ANY
+  // validation failure, not just parse/shape errors — prune nothing until `validate` is clean.
+  const { ok } = await validateScheduleRegistry({ installRoot });
+  if (!ok) return { pruned: [] };
+  const registry = await loadScheduleRegistry({ installRoot });
+  const declared = new Set(registry.schedules.filter(isPlainObject).map((e) => e.id));
+  const state = await loadScheduleState({ installRoot });
+  const orphans = Object.keys(state.last_completed).filter((id) => !declared.has(id));
+  if (orphans.length === 0) return { pruned: [] };
+  for (const id of orphans) delete state.last_completed[id];
+  try {
+    await writeScheduleState({ installRoot, state });
+  } catch (err) {
+    // A prune is a NICETY (D1b warn-and-prune), not a contract check — a state-write failure
+    // (EACCES on a read-only state dir, a full disk) must never crash `phronesis validate`.
+    // Return the error so the caller WARNS; the orphan entries simply remain until a writable
+    // run cleans them (they cannot cause a wrong due result — an orphan has no declaration).
+    return { pruned: [], error: `could not prune ${orphans.length} orphan state entr(ies): ${err.message}` };
+  }
+  return { pruned: orphans };
+}
+
+// Doctor's schedule-staleness warn (D5): entries overdue by MORE THAN `factor` × cadence.
+// Pure read (doctor is byte-identical). A never-completed entry (days_overdue 0) is due, not
+// stale. Returns `{ malformed?, stale: [{ schedule_id, days_overdue, cadence_days }] }`.
+export async function scheduleStaleness({ installRoot, now = new Date(), factor = 2 } = {}) {
+  const registry = await loadScheduleRegistry({ installRoot });
+  if (registry.error) return { malformed: registry.error, stale: [] };
+  const cadenceById = new Map();
+  for (const e of registry.schedules) {
+    if (isPlainObject(e) && typeof e.id === 'string') cadenceById.set(e.id, parseCadenceDays(e.cadence));
+  }
+  const due = await computeScheduleDue({ installRoot, now });
+  const stale = [];
+  for (const d of due) {
+    const cadenceDays = cadenceById.get(d.schedule_id);
+    if (cadenceDays && d.days_overdue > factor * cadenceDays) {
+      stale.push({ schedule_id: d.schedule_id, days_overdue: d.days_overdue, cadence_days: cadenceDays });
+    }
+  }
+  return { stale };
+}