phronesis 1.0.0

package/vendor/core/src/skill-lifecycle.js

@@ -0,0 +1,479 @@
+// Claude Code skill lifecycle producer (core-0032; change 0021 live surface adapter).
+//
+// The active invocation record is the adapter-owned channel between Claude Code skill
+// start hooks and later `phronesis act` calls in the same session. It is transient
+// state, not canonical workspace data: the record mints and carries the live
+// invocation_id, while the action core remains the only writer of action_type.* events.
+
+import { createHash, randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import yaml from 'js-yaml';
+import fse from 'fs-extra';
+import { appendEvent, readEvents } from './event-log.js';
+import { appendAuditEntry } from './hook-executor.js';
+import { matchFrontmatterBlock } from './workspace-scan.js';
+import { resolveInstall } from './install-root.js';
+import { advanceSchedulesForSkill } from './schedule.js';
+
+const RECORD_VERSION = 1;
+const SURFACE = 'claude-code';
+const ACTOR = 'agent';
+const DEDUPE_WINDOW_MS = 30_000;
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function nonEmptyString(v) {
+  return typeof v === 'string' && v.trim() !== '' ? v.trim() : undefined;
+}
+
+function recordKey(session) {
+  return createHash('sha256').update(session).digest('hex').slice(0, 32);
+}
+
+export function invocationsDir(installRoot) {
+  return join(installRoot, '.phronesis', 'invocations');
+}
+
+export function activeInvocationPath(installRoot, session) {
+  return join(invocationsDir(installRoot), `${recordKey(session)}.json`);
+}
+
+export async function readActiveInvocation({ installRoot, session } = {}) {
+  if (!nonEmptyString(session)) return null;
+  let parsed;
+  try {
+    parsed = await fse.readJson(activeInvocationPath(installRoot, session));
+  } catch {
+    return null;
+  }
+  if (!isPlainObject(parsed) || parsed.schema_version !== RECORD_VERSION) return null;
+  if (parsed.session_id !== session) return null;
+  if (!nonEmptyString(parsed.invocation_id) || !nonEmptyString(parsed.skill_name)) return null;
+  return parsed;
+}
+
+async function writeActiveInvocation({ installRoot, session, record }) {
+  await fse.ensureDir(invocationsDir(installRoot));
+  const path = activeInvocationPath(installRoot, session);
+  const tmp = `${path}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+  await fse.writeJson(tmp, record, { spaces: 2 });
+  await fse.move(tmp, path, { overwrite: true });
+  return record;
+}
+
+export async function clearActiveInvocation({ installRoot, session } = {}) {
+  if (!nonEmptyString(session)) return false;
+  const path = activeInvocationPath(installRoot, session);
+  const existed = await fse.pathExists(path);
+  await fse.remove(path);
+  return existed;
+}
+
+function hookSession(hookInput) {
+  return nonEmptyString(hookInput?.session_id);
+}
+
+function toolInput(hookInput) {
+  return isPlainObject(hookInput?.tool_input) ? hookInput.tool_input : {};
+}
+
+function skillNameFromTool(hookInput) {
+  const input = toolInput(hookInput);
+  return (
+    nonEmptyString(input.skill_name) ||
+    nonEmptyString(input.skill) ||
+    nonEmptyString(input.name) ||
+    nonEmptyString(hookInput?.skill_name)
+  );
+}
+
+function skillNameFromSlash(hookInput) {
+  if (hookInput?.expansion_type && hookInput.expansion_type !== 'slash_command') return undefined;
+  return nonEmptyString(hookInput?.command_name);
+}
+
+async function registrySkillVersion(installRoot, name) {
+  try {
+    const registry = await fse.readJson(join(installRoot, '.phronesis', 'registry.json'));
+    const entry = registry?.skills?.[name];
+    return nonEmptyString(entry?.version);
+  } catch {
+    return undefined;
+  }
+}
+
+async function readSkillFrontmatter(installRoot, name) {
+  try {
+    const source = await readFile(join(installRoot, 'skills', name, 'SKILL.md'), 'utf8');
+    const block = matchFrontmatterBlock(source);
+    if (!block) return null;
+    const fm = yaml.load(block[1], { schema: yaml.JSON_SCHEMA });
+    if (!isPlainObject(fm) || fm.name !== name) return null;
+    return fm;
+  } catch {
+    return null;
+  }
+}
+
+async function fileSkillVersion(installRoot, name) {
+  const fm = await readSkillFrontmatter(installRoot, name);
+  return fm ? nonEmptyString(fm.version) : undefined;
+}
+
+// The registered skill's declared weight (skills.md §"Frontmatter contract"): 'heavy'
+// marks a SUBSTANTIVE skill — one whose cognitive load crowds out ambient capture, so it
+// embeds structural checkpoints. An unreadable / unregistered / missing weight resolves to
+// undefined ⇒ NOT substantive: the on_skill_complete warning never fires on a skill the
+// workspace cannot class (the safe default — better a missed warning than a noisy one).
+async function fileSkillWeight(installRoot, name) {
+  const fm = await readSkillFrontmatter(installRoot, name);
+  return fm ? nonEmptyString(fm.weight) : undefined;
+}
+
+// on_skill_complete warning POLICY (core-0027 J1; specs/hooks.md:79 — "checks
+// mesh_enrichments; flags if zero on a substantive skill"). J1 owns this policy; core-0032
+// owns the one Stop command that sequences emit → evaluate (this runs in-process right
+// after the skill.completed emit). SUBSTANTIVE = weight 'heavy' (skills.md §"weight"). The
+// signal is mesh_enrichments === 0, NOT action_types_committed === 0: action-zero ⇒
+// mesh-zero but never the reverse, so the action-zero marker MISSES the case J1 exists for
+// — a heavy skill that committed actions yet enriched no links (mesh-zero with
+// action_types_committed > 0). WARNING-CLASS only, never a gate: mesh_enrichments is a
+// links_updated sum (a coarse enrichment heuristic, change 0021), the producer DERIVES it
+// from the matching committed events — it is not an agent self-report, but a sum is still
+// only a heuristic for "this run enriched the mesh."
+export function meshZeroWarning({ skillName, weight, meshEnrichments, actionTypesCommitted } = {}) {
+  if (weight !== 'heavy') return null;
+  if (!Number.isInteger(meshEnrichments) || meshEnrichments !== 0) return null;
+  return {
+    skill_name: skillName,
+    weight,
+    mesh_enrichments: meshEnrichments,
+    action_types_committed: actionTypesCommitted,
+  };
+}
+
+async function resolveSkillMetadata({ installRoot, hookInput }) {
+  const event = hookInput?.hook_event_name;
+  if (event === 'PreToolUse' && hookInput?.tool_name === 'Skill') {
+    const name = skillNameFromTool(hookInput);
+    if (!name) return null;
+    const version = (await registrySkillVersion(installRoot, name)) || (await fileSkillVersion(installRoot, name));
+    // A model-visible Skill tool input is not enough to mint a dogfood denominator
+    // entry. The lifecycle stream only starts for skills the workspace actually
+    // knows about, matching the direct slash path below.
+    if (!version) return null;
+    return {
+      skill_name: name,
+      version,
+      mode: nonEmptyString(toolInput(hookInput).mode) || 'suggested',
+      start_path: 'model',
+      tool_use_id: nonEmptyString(hookInput.tool_use_id),
+      boundary_key: nonEmptyString(hookInput.transcript_path),
+    };
+  }
+
+  if (event === 'UserPromptExpansion') {
+    const name = skillNameFromSlash(hookInput);
+    if (!name) return null;
+    const version = (await registrySkillVersion(installRoot, name)) || (await fileSkillVersion(installRoot, name));
+    // UserPromptExpansion also covers custom slash commands. Only emit for commands
+    // that map to a Phronesis skill in the workspace.
+    if (!version) return null;
+    return {
+      skill_name: name,
+      version,
+      mode: 'explicit',
+      start_path: 'slash',
+      command_name: name,
+      boundary_key: nonEmptyString(hookInput.transcript_path),
+    };
+  }
+
+  return null;
+}
+
+function mintInvocationId() {
+  return `inv_${randomUUID()}`;
+}
+
+async function auditLifecycle(installRoot, entry) {
+  await appendAuditEntry(installRoot, {
+    hook: 'skill-lifecycle',
+    ...entry,
+  });
+}
+
+async function committedEventsForInvocation({ installRoot, record }) {
+  const events = await readEvents({ installRoot, type: 'action_type.committed' });
+  return events.filter(
+    (ev) =>
+      ev.session_id === record.session_id &&
+      ev.payload?.invocation_id === record.invocation_id &&
+      ev.payload?.no_op !== true &&
+      (!record.started_at || ev.ts >= record.started_at),
+  );
+}
+
+function meshEnrichmentCount(commits) {
+  return commits.reduce((sum, ev) => {
+    const n = ev.payload?.links_updated;
+    return Number.isInteger(n) && n > 0 ? sum + n : sum;
+  }, 0);
+}
+
+export async function completeActiveSkillInvocation({
+  installRoot,
+  session,
+  hookInput,
+  reason = 'stop',
+  now = new Date(),
+} = {}) {
+  const record = await readActiveInvocation({ installRoot, session });
+  if (!record) return { completed: false };
+  const boundaryEvent = nonEmptyString(hookInput?.hook_event_name) || reason;
+  const boundaryKey = nonEmptyString(hookInput?.transcript_path);
+  if (boundaryEvent === 'SubagentStop' && (!boundaryKey || boundaryKey !== record.boundary_key)) {
+    await auditLifecycle(installRoot, {
+      session_id: session,
+      event_type: 'SubagentStop',
+      invocation_id: record.invocation_id,
+      skill_name: record.skill_name,
+      outcome: 'skill-lifecycle-subagent-boundary-skipped',
+      reason: boundaryKey ? 'boundary-mismatch' : 'missing-boundary-key',
+    });
+    return { completed: false, skipped: true, reason: 'subagent-boundary-mismatch', record };
+  }
+
+  const commits = await committedEventsForInvocation({ installRoot, record });
+  const count = commits.length;
+  const meshEnrichments = meshEnrichmentCount(commits);
+  const event = await appendEvent({
+    installRoot,
+    type: 'skill.completed',
+    session_id: session,
+    actor: ACTOR,
+    surface: SURFACE,
+    payload: {
+      skill_name: record.skill_name,
+      action_types_committed: count,
+      mesh_enrichments: meshEnrichments,
+      invocation_id: record.invocation_id,
+    },
+    now,
+  });
+  await clearActiveInvocation({ installRoot, session });
+
+  // Schedule sugar (change 0042 / core-0051): advance any `kind: skill` schedule targeting this
+  // skill, HERE at the single authoritative skill.completed boundary — so EVERY completion path
+  // advances it (the Stop hook AND the next-start-closes-prior path via beginSkillInvocation;
+  // Codex round-3 F1), keyed on this event's own day. Best-effort: the completion has already
+  // committed (event emitted, invocation cleared), so a schedule-state write failure must NOT
+  // fail the lifecycle close — it degrades to the schedule staying due (safe over-surface).
+  try {
+    await advanceSchedulesForSkill({ installRoot, skillName: record.skill_name, now: new Date(event.ts) });
+  } catch {
+    // over-surface, never break the completion
+  }
+
+  if (count === 0) {
+    await auditLifecycle(installRoot, {
+      session_id: session,
+      event_type: 'skill.completed',
+      event_id: event.id,
+      invocation_id: record.invocation_id,
+      skill_name: record.skill_name,
+      outcome: 'skill-lifecycle-zero-capture',
+      reason,
+    });
+  }
+
+  // J1 zero-capture warning (core-0027): phase (2), in-process after the emit (NOT a
+  // second Stop hook — parallel Stop hooks could scan before phase 1, Codex round 9). A
+  // substantive (heavy) skill with mesh_enrichments === 0 banked nothing — the change-0010
+  // misfire class. This is the only signal that catches a heavy skill which committed
+  // actions yet enriched zero links (mesh-zero with action_types_committed > 0).
+  //
+  // It does NOT replace the action-zero `skill-lifecycle-zero-capture` audit above: the
+  // packet keeps action-zero as "a complementary/coarser audit detail, not a substitute".
+  // The two carry distinct `outcome`s for distinct machine consumers (action-zero is
+  // core-0032's coarse capture marker; mesh-zero-warning is J1's heavy-skill warning), so
+  // a heavy run that is BOTH action-zero and mesh-zero is intentionally recorded by both —
+  // each consumer filters by its own outcome; neither double-counts the other.
+  //
+  // SURFACING is the caller's job and only at the Stop boundary: runHooksSkillComplete
+  // turns this warning into an operator-visible systemMessage. A sequential/next-start
+  // completion (a heavy skill closed because the NEXT skill started — beginSkillInvocation)
+  // records this audit entry but surfaces no systemMessage (a skill-start is not a Stop
+  // boundary). That misfire is then audit-only, by design.
+  const weight = await fileSkillWeight(installRoot, record.skill_name);
+  const warning = meshZeroWarning({
+    skillName: record.skill_name,
+    weight,
+    meshEnrichments,
+    actionTypesCommitted: count,
+  });
+  if (warning) {
+    await auditLifecycle(installRoot, {
+      session_id: session,
+      event_type: 'skill.completed',
+      event_id: event.id,
+      invocation_id: record.invocation_id,
+      skill_name: record.skill_name,
+      weight,
+      mesh_enrichments: meshEnrichments,
+      action_types_committed: count,
+      outcome: 'skill-lifecycle-mesh-zero-warning',
+      reason,
+    });
+  }
+
+  return {
+    completed: true,
+    event,
+    record,
+    action_types_committed: count,
+    mesh_enrichments: meshEnrichments,
+    warning,
+  };
+}
+
+function shouldDedupeStart(prior, meta, now) {
+  if (!prior || prior.start_path !== 'slash' || meta.start_path !== 'model') return false;
+  if (prior.skill_name !== meta.skill_name) return false;
+  const started = Date.parse(prior.started_at || '');
+  if (Number.isNaN(started)) return false;
+  return Math.abs(now.getTime() - started) <= DEDUPE_WINDOW_MS;
+}
+
+export async function beginSkillInvocation({ installRoot, hookInput, now = new Date() } = {}) {
+  const session = hookSession(hookInput);
+  if (!session) return { started: false, reason: 'missing-session' };
+
+  const meta = await resolveSkillMetadata({ installRoot, hookInput });
+  if (!meta) return { started: false, reason: 'not-a-skill-start', session };
+
+  const prior = await readActiveInvocation({ installRoot, session });
+  if (shouldDedupeStart(prior, meta, now)) {
+    return { started: false, deduped: true, record: prior, session };
+  }
+  let completedPrior = null;
+  if (prior) {
+    completedPrior = await completeActiveSkillInvocation({
+      installRoot,
+      session,
+      reason: 'next-start',
+      now,
+    });
+  }
+
+  const record = {
+    schema_version: RECORD_VERSION,
+    session_id: session,
+    invocation_id: mintInvocationId(),
+    skill_name: meta.skill_name,
+    version: meta.version,
+    mode: meta.mode,
+    started_at: now.toISOString(),
+    start_event: hookInput.hook_event_name,
+    start_path: meta.start_path,
+    ...(meta.tool_use_id ? { tool_use_id: meta.tool_use_id } : {}),
+    ...(meta.command_name ? { command_name: meta.command_name } : {}),
+    ...(meta.boundary_key ? { boundary_key: meta.boundary_key } : {}),
+  };
+  const event = await appendEvent({
+    installRoot,
+    type: 'skill.invoked',
+    session_id: session,
+    actor: ACTOR,
+    surface: SURFACE,
+    payload: {
+      skill_name: record.skill_name,
+      version: record.version,
+      mode: record.mode,
+      invocation_id: record.invocation_id,
+    },
+    now,
+  });
+  await writeActiveInvocation({ installRoot, session, record });
+
+  return { started: true, event, record, completedPrior, session };
+}
+
+export async function abandonActiveSkillInvocation({
+  installRoot,
+  hookInput,
+  reason = 'StopFailure',
+  now = new Date(),
+} = {}) {
+  const session = hookSession(hookInput);
+  if (!session) return { abandoned: false, reason: 'missing-session' };
+  const record = await readActiveInvocation({ installRoot, session });
+  if (!record) return { abandoned: false, reason: 'no-active-record', session };
+  await clearActiveInvocation({ installRoot, session });
+  await auditLifecycle(installRoot, {
+    session_id: session,
+    invocation_id: record.invocation_id,
+    skill_name: record.skill_name,
+    event_type: hookInput?.hook_event_name || reason,
+    outcome: 'skill-lifecycle-abandoned',
+    reason: nonEmptyString(hookInput?.error_type) || nonEmptyString(hookInput?.error) || reason,
+    ts_observed: now.toISOString(),
+  });
+  return { abandoned: true, record, session };
+}
+
+export async function sweepStaleSkillInvocation({ installRoot, session, now = new Date() } = {}) {
+  const record = await readActiveInvocation({ installRoot, session });
+  if (!record) return { cleared: false };
+  await clearActiveInvocation({ installRoot, session });
+  await auditLifecycle(installRoot, {
+    session_id: session,
+    invocation_id: record.invocation_id,
+    skill_name: record.skill_name,
+    event_type: 'SessionStart',
+    outcome: 'skill-lifecycle-stale-cleared',
+    reason: 'SessionStart',
+    ts_observed: now.toISOString(),
+  });
+  return { cleared: true, record };
+}
+
+export async function resolveInvocationIdForAct({
+  dir,
+  cwd = process.cwd(),
+  session,
+  callerInvocationId,
+  envInvocationId,
+  surface = 'cli',
+} = {}) {
+  const installed = resolveInstall({ dir, cwd });
+  const caller = nonEmptyString(callerInvocationId);
+  const env = nonEmptyString(envInvocationId);
+  if (installed.error || !nonEmptyString(session)) {
+    return { invocation_id: caller || env, installRoot: installed.root, active: null };
+  }
+
+  const installRoot = installed.root;
+  const active = await readActiveInvocation({ installRoot, session });
+  if (!active) return { invocation_id: caller || env, installRoot, active: null };
+
+  const attempted = [];
+  if (caller && caller !== active.invocation_id) attempted.push({ source: 'flag', value: caller });
+  if (env && env !== active.invocation_id) attempted.push({ source: 'env', value: env });
+  if (attempted.length) {
+    await auditLifecycle(installRoot, {
+      session_id: session,
+      invocation_id: active.invocation_id,
+      skill_name: active.skill_name,
+      event_type: 'action_type.requested',
+      outcome: 'skill-lifecycle-override-refused',
+      surface,
+      attempted_sources: attempted,
+    });
+  }
+
+  return { invocation_id: active.invocation_id, installRoot, active };
+}