phronesis 1.0.0 → 1.1.0

package/vendor/core/src/lint.js

@@ -80,9 +80,9 @@ function seedRefFromPath(path) {
 
 function orphanDetail(scope) {
   if (!scope.all_domains) {
-    return 'domain compiled object has no inbound links from the scoped graph';
+    return 'domain compiled object has no typed link in either direction to another object in the scoped graph (links to raw sources do not count as connectivity)';
   }
-  return 'domain compiled object has no inbound links that resolve within their source domain; bare targets from other domains do not count as cross-domain inbound links';
+  return 'domain compiled object has no typed link in either direction to another object that resolves within its source domain; links to raw sources and bare targets from other domains do not count as connectivity';
 }
 
 function lintRecords(records, scope) {
@@ -204,11 +204,28 @@ export async function runWorkspaceLint({
   const findings = [];
   const adoptions = adoptedSeedMap(records);
 
-  // 1. Orphans: domain compiled objects with no inbound object edge.
+  // 1. Orphans: an in-scope domain object with NO typed edge in either direction to another
+  // in-scope object (core-0061 D1 — direction-agnostic). The engine's own action types write
+  // hub-and-spoke (`log_decision` links `enables → projects/*` outbound), so inbound-only
+  // counting flags every spoke and reports a maximally healthy young workspace as ~90%
+  // orphans — pure noise. Connectivity counts only edges whose OTHER endpoint is an in-scope
+  // node: `index.has(edge.to)` for outbound drops raw-source + unresolved forward targets
+  // (never nodes); every edge's `from` is an in-scope node by construction. Self-edges never
+  // count. Cross-domain scoping (D3) is structural: an edge's `to` resolves within its source
+  // domain, so it can only land on a node when that domain is itself in scope.
   for (const record of records) {
     if (record.ctx.layer !== 'domain') continue;
-    const inbound = (index.inEdges.get(record.rel) ?? []).filter((edge) => edge.from !== record.rel);
-    if (inbound.length === 0) {
+    // Connectivity counts edges to/from another in-scope object that is *earned mesh* — a
+    // domain compiled object or ADOPTED codex (codex/personal). A quarantined codex/seed node
+    // is discoverability, not connectivity (D1 / change 0053): a domain object linked only to
+    // an unadopted seed, or pointed at only by one, is still an orphan. `seedRefFromPath` is
+    // non-null exactly for codex/seed/ paths, so it excludes seed endpoints in both directions.
+    const outbound = index.outEdges.get(record.rel) ?? [];
+    const inbound = index.inEdges.get(record.rel) ?? [];
+    const connected =
+      outbound.some((edge) => edge.to !== record.rel && index.has(edge.to) && seedRefFromPath(edge.to) === null) ||
+      inbound.some((edge) => edge.from !== record.rel && seedRefFromPath(edge.from) === null);
+    if (!connected) {
       findings.push({
         surface: 'orphan',
         kind: 'orphan',

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

@@ -15,8 +15,13 @@ import { appendAuditEntry } from './hook-executor.js';
 import { matchFrontmatterBlock } from './workspace-scan.js';
 import { resolveInstall } from './install-root.js';
 import { advanceSchedulesForSkill } from './schedule.js';
+import { RE_SLUG } from './contract.js';
 
 const RECORD_VERSION = 1;
+// The DEFAULT surface for a minted lifecycle event. Claude Code was the sole minter until change
+// 0056; the producer now takes a `surface` parameter (default this value) so a first-party in-process
+// surface — Craft Phronesis Desktop — mints `skill.invoked`/`skill.completed` truthfully with its own
+// `surface: 'desktop'`. Every existing Claude Code caller omits the parameter and is unchanged.
 const SURFACE = 'claude-code';
 const ACTOR = 'agent';
 const DEDUPE_WINDOW_MS = 30_000;
@@ -195,6 +200,34 @@ async function resolveSkillMetadata({ installRoot, hookInput }) {
   return null;
 }
 
+// Surface-neutral skill metadata for a FIRST-PARTY model-invocation (change 0056). Unlike a Claude
+// Code hook (which carries a `PreToolUse`+`Skill` or slash envelope), an in-process surface's
+// `invoke_skill(name)` already holds the skill name. The descriptor is `{ name, version?, mode?,
+// start_path? }`; the version resolves from the install registry / SKILL.md when omitted, exactly as
+// the hook path resolves it — and, mirroring the hook path, an unregistered/unknown skill returns
+// null (the lifecycle stream only starts for skills the workspace actually knows about). The name is
+// slug-validated before it reaches a `skills/{name}/SKILL.md` read (path-traversal fail-closed).
+async function resolveExplicitSkill({ installRoot, skill }) {
+  if (!isPlainObject(skill)) return null;
+  const name = nonEmptyString(skill.name);
+  if (!name || !RE_SLUG.test(name)) return null;
+  // The skill MUST exist in the workspace (registry entry or a readable SKILL.md) before a lifecycle is
+  // minted (Codex R3 F5): a caller-supplied `version` for an unknown skill would fabricate a
+  // skill.invoked/completed pair for a skill that cannot run. Prove existence FIRST, then a caller
+  // version may pin it; otherwise fall to the resolved one.
+  const existingVersion =
+    (await registrySkillVersion(installRoot, name)) || (await fileSkillVersion(installRoot, name));
+  if (!existingVersion) return null;
+  const version = nonEmptyString(skill.version) || existingVersion;
+  return {
+    skill_name: name,
+    version,
+    mode: nonEmptyString(skill.mode) || 'suggested',
+    start_path: nonEmptyString(skill.start_path) || 'model',
+    start_event: 'model-invocation',
+  };
+}
+
 function mintInvocationId() {
   return `inv_${randomUUID()}`;
 }
@@ -229,6 +262,7 @@ export async function completeActiveSkillInvocation({
   session,
   hookInput,
   reason = 'stop',
+  surface = SURFACE,
   now = new Date(),
 } = {}) {
   const record = await readActiveInvocation({ installRoot, session });
@@ -255,7 +289,7 @@ export async function completeActiveSkillInvocation({
     type: 'skill.completed',
     session_id: session,
     actor: ACTOR,
-    surface: SURFACE,
+    surface,
     payload: {
       skill_name: record.skill_name,
       action_types_committed: count,
@@ -348,11 +382,25 @@ function shouldDedupeStart(prior, meta, now) {
   return Math.abs(now.getTime() - started) <= DEDUPE_WINDOW_MS;
 }
 
-export async function beginSkillInvocation({ installRoot, hookInput, now = new Date() } = {}) {
-  const session = hookSession(hookInput);
+export async function beginSkillInvocation({
+  installRoot,
+  hookInput,
+  skill,
+  session: sessionArg,
+  surface = SURFACE,
+  pinDeviation,
+  resolvedModel,
+  now = new Date(),
+} = {}) {
+  // Session: a Claude hook carries it in `hookInput.session_id`; a first-party surface passes it
+  // explicitly (`session`), since its `skill` descriptor is not a hook envelope (change 0056).
+  const session = hookSession(hookInput) || nonEmptyString(sessionArg);
   if (!session) return { started: false, reason: 'missing-session' };
 
-  const meta = await resolveSkillMetadata({ installRoot, hookInput });
+  // A `skill` descriptor is the first-party model-invocation path; `hookInput` is the Claude path.
+  const meta = skill
+    ? await resolveExplicitSkill({ installRoot, skill })
+    : await resolveSkillMetadata({ installRoot, hookInput });
   if (!meta) return { started: false, reason: 'not-a-skill-start', session };
 
   const prior = await readActiveInvocation({ installRoot, session });
@@ -365,6 +413,7 @@ export async function beginSkillInvocation({ installRoot, hookInput, now = new D
       installRoot,
       session,
       reason: 'next-start',
+      surface,
       now,
     });
   }
@@ -377,7 +426,7 @@ export async function beginSkillInvocation({ installRoot, hookInput, now = new D
     version: meta.version,
     mode: meta.mode,
     started_at: now.toISOString(),
-    start_event: hookInput.hook_event_name,
+    start_event: hookInput?.hook_event_name || meta.start_event || 'model-invocation',
     start_path: meta.start_path,
     ...(meta.tool_use_id ? { tool_use_id: meta.tool_use_id } : {}),
     ...(meta.command_name ? { command_name: meta.command_name } : {}),
@@ -388,12 +437,17 @@ export async function beginSkillInvocation({ installRoot, hookInput, now = new D
     type: 'skill.invoked',
     session_id: session,
     actor: ACTOR,
-    surface: SURFACE,
+    surface,
     payload: {
       skill_name: record.skill_name,
       version: record.version,
       mode: record.mode,
       invocation_id: record.invocation_id,
+      // Pin-deviation (change 0051 / CR3): an additive optional field a ROUTING surface (the desktop)
+      // stamps when it substitutes a tier-equivalent for the skill's pinned model. Shape:
+      // { pinned_model, substituted_model, provider, tier }. No new event type; skill.invoked carries it.
+      ...(isPlainObject(pinDeviation) ? { pin_deviation: pinDeviation } : {}),
+      ...(nonEmptyString(resolvedModel) ? { resolved_model: resolvedModel } : {}),
     },
     now,
   });
@@ -405,18 +459,24 @@ export async function beginSkillInvocation({ installRoot, hookInput, now = new D
 export async function abandonActiveSkillInvocation({
   installRoot,
   hookInput,
+  session: sessionArg,
   reason = 'StopFailure',
+  surface = SURFACE,
   now = new Date(),
 } = {}) {
-  const session = hookSession(hookInput);
+  const session = hookSession(hookInput) || nonEmptyString(sessionArg);
   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 });
+  // Honest gap (StopFailure-equivalent): clear the active record and audit the abandonment; NEVER
+  // mint a synthetic skill.completed to fake a clean close (emission honesty). The desktop calls this
+  // on an errored/cancelled turn with surface: 'desktop'.
   await auditLifecycle(installRoot, {
     session_id: session,
     invocation_id: record.invocation_id,
     skill_name: record.skill_name,
+    surface,
     event_type: hookInput?.hook_event_name || reason,
     outcome: 'skill-lifecycle-abandoned',
     reason: nonEmptyString(hookInput?.error_type) || nonEmptyString(hookInput?.error) || reason,