phronesis 1.0.0

package/vendor/core/src/link-index.js

@@ -0,0 +1,198 @@
+// Link index + walk — Stage 2 retrieval (specs/compile-retrieve-loop.md §"Stage 2 —
+// typed link walk"; core-0005 / T2.3). Builds the typed-link graph over a domain's
+// compiled/ objects + the shared codex/, then walks N hops from any object to return the
+// connected subgraph: the related decisions, the people involved, the sources they
+// cite (ontology §"Link types").
+//
+// Derived, not authoritative: per change 0008 the machine retrieval index is derived and
+// rebuildable from compiled/ + codex/, never source of truth. This module builds it in
+// memory. Persistence, daemon reindex-on-write, and `phronesis index rebuild` are T5.2's
+// machine-index substrate — out of scope here. Reuses contract.js (classifyTarget) for the
+// locked link-target grammar and workspace-scan.js for object discovery.
+
+import { resolve, join, relative } from 'node:path';
+import { classifyTarget } from './contract.js';
+import { listRetrievableObjectFiles, readObjectRecord } from './workspace-scan.js';
+
+const DIRECTIONS = new Set(['out', 'in', 'both']);
+
+// Leaf kind for a visited path that is not an indexed object — derived from the edge that
+// reached it: a resolvable raw source vs a not-yet-(or no-longer-)compiled object target.
+function leafKind(form) {
+  return form === 'raw-source' ? 'raw' : 'unresolved';
+}
+
+// One typed object's node metadata (the fields a retrieval consumer presents).
+function nodeMeta(relPath, fm, ctx) {
+  return {
+    path: relPath,
+    kind: 'object',
+    type: fm.type ?? null,
+    name: fm.name ?? null,
+    title: fm.title ?? null,
+    status: fm.status ?? null,
+    exposure: fm.exposure ?? null,
+    stance: fm.stance ?? null,
+    domain: ctx.domain,
+  };
+}
+
+export class LinkIndex {
+  constructor({ root, nodes, outEdges, inEdges }) {
+    this.root = root;
+    this.nodes = nodes; // Map<relPath, nodeMeta>
+    this.outEdges = outEdges; // Map<relPath, Edge[]>  (from === key)
+    this.inEdges = inEdges; // Map<relPath, Edge[]>  (to === key)
+  }
+
+  get size() {
+    return this.nodes.size;
+  }
+
+  has(path) {
+    return this.nodes.has(path);
+  }
+
+  node(path) {
+    return this.nodes.get(path) ?? null;
+  }
+
+  // Resolve an operator-supplied query to a single node path. Accepts an exact
+  // install-relative path, a bare object name, or a `{type-dir}/{name}` suffix. Returns
+  // { path } on a unique hit, { error } otherwise (no match / ambiguous).
+  find(query) {
+    if (this.nodes.has(query)) return { path: query };
+    const q = String(query).replace(/\.md$/, '');
+    const hits = [];
+    for (const [path, meta] of this.nodes) {
+      if (meta.name === q || path.replace(/\.md$/, '').endsWith(`/${q}`)) hits.push(path);
+    }
+    if (hits.length === 1) return { path: hits[0] };
+    if (hits.length === 0) return { error: `no indexed object matches "${query}"` };
+    return { error: `"${query}" is ambiguous — matches ${hits.length} objects: ${hits.join(', ')}` };
+  }
+
+  // N-hop connected subgraph from `start` (an install-relative object path).
+  // direction: 'out' | 'in' | 'both' (default 'both' — see core-0005 Decisions: a hub
+  // object is reached by inbound edges, so the connected subgraph needs both; every edge
+  // preserves its own direction + rel regardless). Raw-source and forward/unresolved
+  // targets are terminal leaves: included in the result, never traversed. Cycles
+  // terminate (each node is visited once).
+  walk(start, { hops = 1, direction = 'both' } = {}) {
+    if (!this.nodes.has(start)) {
+      throw new Error(`walk: "${start}" is not an indexed object`);
+    }
+    if (!DIRECTIONS.has(direction)) {
+      throw new Error(`walk: direction must be one of ${[...DIRECTIONS].join(' | ')}`);
+    }
+    const maxHops = Math.max(0, Math.floor(hops));
+
+    const distance = new Map([[start, 0]]); // path -> hop distance
+    const leafForms = new Map(); // non-object path -> the form that reached it
+    const edges = [];
+    const seenEdge = new Set();
+    let frontier = [start];
+
+    for (let d = 0; d < maxHops && frontier.length; d += 1) {
+      const next = [];
+      for (const cur of frontier) {
+        const adj = [];
+        if (direction === 'out' || direction === 'both') adj.push(...(this.outEdges.get(cur) || []));
+        if (direction === 'in' || direction === 'both') adj.push(...(this.inEdges.get(cur) || []));
+        for (const e of adj) {
+          // JSON tuple, not a delimiter-joined string: a raw-source path can contain any
+          // character (incl. spaces), so a literal separator could collide two distinct
+          // edges into one and silently drop one. JSON.stringify is collision-free.
+          const key = JSON.stringify([e.from, e.to, e.rel]);
+          if (!seenEdge.has(key)) {
+            seenEdge.add(key);
+            edges.push(e);
+          }
+          const other = e.from === cur ? e.to : e.from;
+          if (distance.has(other)) continue;
+          distance.set(other, d + 1);
+          // Leaf-vs-traverse is decided by *resolvability to an indexed object*, not by the
+          // `forward` flag: a forward link whose target actually exists is a real node and is
+          // traversed; a raw source or a still-missing (typo'd / not-yet-compiled) target is a
+          // terminal leaf.
+          if (this.nodes.has(other)) next.push(other);
+          else leafForms.set(other, e.form);
+        }
+      }
+      frontier = next;
+    }
+
+    const nodes = [...distance.keys()].map((path) => {
+      const meta = this.nodes.get(path);
+      if (meta) return { ...meta, hop: distance.get(path) };
+      return { path, kind: leafKind(leafForms.get(path)), hop: distance.get(path) };
+    });
+
+    return { root: start, hops: maxHops, direction, nodes, edges };
+  }
+}
+
+// Build the link index from pre-parsed object records ({ rel, ctx, fm } triples — the
+// same shape the disk pass below produces and the search snapshot (T5.2 / core-0014)
+// persists). ONE edge-resolution implementation for both consumers: a re-typed sibling
+// graph builder is the same drift class as a re-typed frontmatter regex (rules.md:335).
+export function buildLinkIndexFromRecords(records, root) {
+  const parsed = records;
+  const nodes = new Map();
+  const outEdges = new Map();
+  const inEdges = new Map();
+  const ensureIn = (p) => {
+    if (!inEdges.has(p)) inEdges.set(p, []);
+    return inEdges.get(p);
+  };
+
+  for (const p of parsed) {
+    if (!p) continue;
+    nodes.set(p.rel, nodeMeta(p.rel, p.fm, p.ctx));
+    outEdges.set(p.rel, []);
+    ensureIn(p.rel);
+  }
+
+  // Second pass: resolve each object's outbound links to edges (both adjacency maps).
+  for (const p of parsed) {
+    if (!p) continue;
+    const links = Array.isArray(p.fm.links) ? p.fm.links : [];
+    for (const link of links) {
+      if (link === null || typeof link !== 'object') continue;
+      const target = link.target;
+      if (typeof target !== 'string' || target === '') continue;
+      const cls = classifyTarget(target);
+      if (cls.form === 'invalid') continue; // malformed — the validator flags it; skip here
+      const to = cls.relPath(p.ctx.domain);
+      if (to === null) continue; // unresolvable bare slug from a codex object — skip
+      // Never propagate a target that escapes the install (a raw-source target can carry
+      // `..`). Mirrors validate.js's containment guard so the index hands no downstream
+      // consumer a path-traversal string to resolve. The validator separately errors on it.
+      if (relative(root, join(root, to)).startsWith('..')) continue;
+      const edge = {
+        from: p.rel,
+        to,
+        rel: typeof link.rel === 'string' ? link.rel : null,
+        forward: link.forward === true,
+        form: cls.form,
+      };
+      outEdges.get(p.rel).push(edge);
+      ensureIn(to).push(edge);
+    }
+  }
+
+  return new LinkIndex({ root, nodes, outEdges, inEdges });
+}
+
+// Build the link index by scanning every typed object under domains/*/compiled/ + codex/.
+// File→record parsing rides the ONE shared readObjectRecord (skip non-objects /
+// unparseable — the index is best-effort over a possibly-imperfect workspace; the
+// validator flags bad objects, the index just routes around them).
+export async function buildLinkIndex({ dir, installRoot } = {}) {
+  const root = installRoot || resolve(process.cwd(), dir || '.');
+  // Retrieval set excludes the quarantined seed library (workspace-scan.js): the shipped
+  // codex/seed/ principles are never link-graph nodes — discoverability is codex/INDEX.md + lint.
+  const files = await listRetrievableObjectFiles(root);
+  const parsed = await Promise.all(files.map((rel) => readObjectRecord(root, rel)));
+  return buildLinkIndexFromRecords(parsed, root);
+}

package/vendor/core/src/lint.js

@@ -0,0 +1,368 @@
+// Deterministic workspace lint (core-0022 / T5.3 PR1): the read-only mechanical
+// foundation beneath the heavy judgment skill. This module computes exact graph /
+// frontmatter findings from compiled/ + codex/ state, writes nothing, and deliberately
+// loads the retrieval snapshot with persist:false so a health check cannot repair or
+// create .phronesis/index/ as a side effect.
+
+import { performance } from 'node:perf_hooks';
+import { buildLinkIndexFromRecords } from './link-index.js';
+import { loadSearchIndex } from './search.js';
+import { readAuditLog } from './hook-executor.js';
+import { listObjectFiles, readObjectRecord } from './workspace-scan.js';
+
+export const DEFAULT_LINT_STALE_MONTHS = 6;
+
+// Hook-hygiene bypass surface (core-0027 J4, re-homed from core-0022/L8): a hook bypassed
+// frequently is a hook the operator is working around — a suggested removal
+// (specs/hooks.md §"Bypass discipline" — "Lint surfaces frequent-bypass patterns as
+// suggested hook removals"). A logged bypass is a `skipped-kill-switch` audit entry
+// (PHRONESIS_SKIP=<id>). Deterministic: a count over a fixed trailing window.
+export const LINT_BYPASS_WINDOW_DAYS = 7;
+export const LINT_BYPASS_THRESHOLD = 5;
+
+const SURFACE_ORDER = [
+  'orphan',
+  'inverse_pair_gap',
+  'stale_forward_ref',
+  'codex_citation',
+  'seed_adoption',
+  'relationship_value_consistency',
+  // Hook hygiene is its OWN section, separate from the knowledge-graph findings above
+  // (core-0022/L8 — "a clearly-separated 'hook hygiene' section"). Last so the graph
+  // findings stay grouped.
+  'hook_hygiene',
+];
+
+const INVERSE_RELS = {
+  supersedes: 'superseded-by',
+  'superseded-by': 'supersedes',
+};
+
+function relSort(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+function recordMeta(record) {
+  return {
+    path: record.rel,
+    type: record.fm.type ?? null,
+    name: record.fm.name ?? null,
+    title: record.fm.title ?? null,
+  };
+}
+
+function parseDateOnly(value) {
+  if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value)) return null;
+  const [year, month, day] = value.split('-').map(Number);
+  return new Date(Date.UTC(year, month - 1, day));
+}
+
+function cutoffDate(now, months) {
+  const d = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+  d.setUTCMonth(d.getUTCMonth() - months);
+  return d;
+}
+
+function objectDate(record) {
+  return record.fm.updated ?? record.fm.created ?? null;
+}
+
+function olderThanThreshold(dateValue, now, months) {
+  const parsed = parseDateOnly(dateValue);
+  if (!parsed) return false;
+  return parsed < cutoffDate(now, months);
+}
+
+function seedRefFromPath(path) {
+  const match = path.match(/^codex\/seed\/([^/]+)\/([^/]+)\.md$/);
+  return match ? `${match[1]}/${match[2]}` : null;
+}
+
+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 inbound links that resolve within their source domain; bare targets from other domains do not count as cross-domain inbound links';
+}
+
+function lintRecords(records, scope) {
+  return records.filter((record) => {
+    if (record.ctx.layer === 'domain') return scope.domains.includes(record.ctx.domain);
+    if (record.ctx.layer === 'codex') return record.ctx.codexKind === 'personal' || record.ctx.codexKind === 'seed';
+    return false;
+  });
+}
+
+function indexEdges(index) {
+  const edges = [];
+  for (const [from, outbound] of index.outEdges) {
+    for (const edge of outbound) edges.push({ ...edge, from });
+  }
+  return edges.sort((a, b) => relSort(`${a.from}:${a.rel}:${a.to}`, `${b.from}:${b.rel}:${b.to}`));
+}
+
+function hasInverse(index, edge, inverseRel) {
+  const targetOutbound = index.outEdges.get(edge.to) ?? [];
+  return targetOutbound.some((candidate) => candidate.rel === inverseRel && candidate.to === edge.from);
+}
+
+function adoptedSeedMap(records) {
+  const adoptions = new Map();
+  for (const record of records) {
+    if (record.ctx.layer !== 'codex' || record.ctx.codexKind !== 'personal') continue;
+    const ref = record.fm.provenance?.adopted_from_seed;
+    if (typeof ref !== 'string' || ref.trim() === '') continue;
+    const key = ref.trim();
+    if (!adoptions.has(key)) adoptions.set(key, []);
+    adoptions.get(key).push(record.rel);
+  }
+  for (const paths of adoptions.values()) paths.sort(relSort);
+  return adoptions;
+}
+
+function normalizeRelationship(value) {
+  return String(value).trim().toLowerCase().replace(/[_\s]+/g, '-').replace(/-+/g, '-');
+}
+
+function buildSurfaces(findings) {
+  return SURFACE_ORDER.map((id) => {
+    const surfaceFindings = findings.filter((finding) => finding.surface === id);
+    return {
+      id,
+      findings: surfaceFindings,
+      empty_result: surfaceFindings.length === 0,
+    };
+  });
+}
+
+function countByKind(findings) {
+  const counts = {};
+  for (const finding of findings) counts[finding.kind] = (counts[finding.kind] ?? 0) + 1;
+  return counts;
+}
+
+// Frequent-bypass hook-hygiene findings (J4): a hook whose documented kill-switch
+// (PHRONESIS_SKIP=<id>, audited as outcome `skipped-kill-switch`) was bypassed
+// >= LINT_BYPASS_THRESHOLD times within the trailing LINT_BYPASS_WINDOW_DAYS is a
+// suggested removal — the operator is routing around it. Counts only datable in-window
+// bypasses; an entry with no usable ts is ignored (the window is the contract).
+function hookHygieneFindings(auditEntries, now) {
+  const cutoff = new Date(now.getTime() - LINT_BYPASS_WINDOW_DAYS * 86_400_000).toISOString();
+  const counts = new Map();
+  for (const entry of auditEntries) {
+    if (entry.outcome !== 'skipped-kill-switch') continue;
+    if (typeof entry.hook !== 'string' || entry.hook === '') continue;
+    if (typeof entry.ts !== 'string' || entry.ts < cutoff) continue;
+    counts.set(entry.hook, (counts.get(entry.hook) ?? 0) + 1);
+  }
+  const findings = [];
+  for (const [hook, bypasses] of counts) {
+    if (bypasses < LINT_BYPASS_THRESHOLD) continue;
+    findings.push({
+      surface: 'hook_hygiene',
+      kind: 'frequent_bypass',
+      severity: 'warn',
+      hook,
+      bypasses,
+      window_days: LINT_BYPASS_WINDOW_DAYS,
+      detail: `hook bypassed ${bypasses} time(s) in the last ${LINT_BYPASS_WINDOW_DAYS} days (PHRONESIS_SKIP) — a hook routinely worked around is a suggested removal (specs/hooks.md §"Bypass discipline")`,
+    });
+  }
+  return findings;
+}
+
+export async function runWorkspaceLint({
+  dir,
+  installRoot,
+  cwd = process.cwd(),
+  domain,
+  allDomains = false,
+  staleMonths = DEFAULT_LINT_STALE_MONTHS,
+  now = new Date(),
+} = {}) {
+  if (!Number.isInteger(staleMonths) || staleMonths < 1) {
+    throw new Error(`staleMonths must be a positive integer (got ${JSON.stringify(staleMonths)})`);
+  }
+
+  const t0 = performance.now();
+  const loaded = await loadSearchIndex({
+    dir,
+    installRoot,
+    cwd,
+    domain,
+    allDomains,
+    persist: false,
+  });
+
+  const parsed = (await Promise.all((await listObjectFiles(loaded.root)).map((rel) => readObjectRecord(loaded.root, rel))))
+    .filter(Boolean)
+    .sort((a, b) => relSort(a.rel, b.rel));
+  const records = lintRecords(parsed, loaded.scope);
+  const byPath = new Map(records.map((record) => [record.rel, record]));
+  const index = buildLinkIndexFromRecords(records, loaded.root);
+  const edges = indexEdges(index);
+  const findings = [];
+  const adoptions = adoptedSeedMap(records);
+
+  // 1. Orphans: domain compiled objects with no inbound object edge.
+  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) {
+      findings.push({
+        surface: 'orphan',
+        kind: 'orphan',
+        severity: 'info',
+        ...recordMeta(record),
+        detail: orphanDetail(loaded.scope),
+      });
+    }
+  }
+
+  // 2. Inverse-pair gaps: supersedes <-> superseded-by.
+  for (const edge of edges) {
+    const inverseRel = INVERSE_RELS[edge.rel];
+    if (!inverseRel || !index.has(edge.to)) continue;
+    if (!hasInverse(index, edge, inverseRel)) {
+      findings.push({
+        surface: 'inverse_pair_gap',
+        kind: 'inverse_pair_gap',
+        severity: 'error',
+        path: edge.from,
+        target: edge.to,
+        rel: edge.rel,
+        missing_rel: inverseRel,
+        detail: `${edge.rel} link is missing its ${inverseRel} reciprocal`,
+      });
+    }
+  }
+
+  // 3. Stale forward refs: forward domain-object targets still missing past threshold.
+  for (const edge of edges) {
+    if (!edge.forward || edge.form !== 'domain-object' || index.has(edge.to)) continue;
+    const record = byPath.get(edge.from);
+    if (!record) continue;
+    const dateValue = objectDate(record);
+    if (!olderThanThreshold(dateValue, now, staleMonths)) continue;
+    findings.push({
+      surface: 'stale_forward_ref',
+      kind: 'stale_forward_ref',
+      severity: 'warn',
+      path: edge.from,
+      target: edge.to,
+      rel: edge.rel,
+      object_date: dateValue,
+      threshold_months: staleMonths,
+      detail: 'forward reference target is still missing past the lint staleness threshold',
+    });
+  }
+
+  // 4. Broken/unjustified codex citations.
+  for (const edge of edges) {
+    if (edge.form !== 'codex-object') continue;
+    if (!index.has(edge.to)) {
+      findings.push({
+        surface: 'codex_citation',
+        kind: 'broken_codex_citation',
+        severity: 'error',
+        path: edge.from,
+        target: edge.to,
+        rel: edge.rel,
+        detail: 'codex citation target does not resolve',
+      });
+      continue;
+    }
+    const seedRef = seedRefFromPath(edge.to);
+    if (seedRef && !adoptions.has(seedRef)) {
+      findings.push({
+        surface: 'codex_citation',
+        kind: 'unjustified_codex_seed_citation',
+        severity: 'warn',
+        path: edge.from,
+        target: edge.to,
+        seed_ref: seedRef,
+        rel: edge.rel,
+        detail: 'codex/seed citation has not been adopted into codex/personal',
+      });
+    }
+  }
+
+  // 5. Seed-adoption hygiene: unadopted old seed and duplicate adoption.
+  for (const record of records) {
+    const seedRef = seedRefFromPath(record.rel);
+    if (!seedRef || adoptions.has(seedRef)) continue;
+    const dateValue = objectDate(record);
+    if (!olderThanThreshold(dateValue, now, staleMonths)) continue;
+    findings.push({
+      surface: 'seed_adoption',
+      kind: 'unadopted_seed',
+      severity: 'info',
+      ...recordMeta(record),
+      seed_ref: seedRef,
+      object_date: dateValue,
+      threshold_months: staleMonths,
+      detail: 'seed principle has not been adopted past the lint staleness threshold',
+    });
+  }
+  for (const [seedRef, paths] of adoptions) {
+    if (paths.length < 2) continue;
+    findings.push({
+      surface: 'seed_adoption',
+      kind: 'duplicate_seed_adoption',
+      severity: 'warn',
+      seed_ref: seedRef,
+      paths,
+      detail: 'seed principle was adopted into more than one codex/personal object',
+    });
+  }
+
+  // 6. relationships value-consistency: values that normalize together but differ in spelling.
+  const relationshipGroups = new Map();
+  for (const record of records) {
+    const values = Array.isArray(record.fm.relationships) ? record.fm.relationships : [];
+    for (const value of values) {
+      if (typeof value !== 'string' || value.trim() === '') continue;
+      const normalized = normalizeRelationship(value);
+      if (!relationshipGroups.has(normalized)) relationshipGroups.set(normalized, new Map());
+      const variants = relationshipGroups.get(normalized);
+      if (!variants.has(value)) variants.set(value, new Set());
+      variants.get(value).add(record.rel);
+    }
+  }
+  for (const [normalized, variants] of relationshipGroups) {
+    if (variants.size < 2) continue;
+    const variantList = [...variants.keys()].sort(relSort);
+    const paths = [...new Set([...variants.values()].flatMap((set) => [...set]))].sort(relSort);
+    findings.push({
+      surface: 'relationship_value_consistency',
+      kind: 'relationship_value_drift',
+      severity: 'warn',
+      normalized,
+      variants: variantList,
+      paths,
+      detail: `relationship values collapse to "${normalized}" but use multiple spellings`,
+    });
+  }
+
+  // 7. Hook hygiene (J4): frequent kill-switch bypasses over .phronesis/audit.log —
+  // re-admitted to lint's read surface by core-0027 (core-0022/L8 had excluded it, gated on
+  // this packet's audit-retention landing). readAuditLog returns [] when the file is absent,
+  // so no audit ⇒ no hook-hygiene findings. This is the only read OUTSIDE compiled/+codex/,
+  // and it stays read-only — lint writes nothing. The read is the whole LIVE audit.log (not
+  // the archive — a 7-day bypass window is never in the 90-day-retention archive); J5 bounds
+  // that file's growth, so the read stays proportional to recent activity, not all history.
+  const auditEntries = await readAuditLog(loaded.root);
+  for (const finding of hookHygieneFindings(auditEntries, now)) findings.push(finding);
+
+  findings.sort((a, b) => relSort(`${a.surface}:${a.kind}:${a.path ?? a.hook ?? ''}:${a.target ?? ''}`, `${b.surface}:${b.kind}:${b.path ?? b.hook ?? ''}:${b.target ?? ''}`));
+
+  return {
+    scope: loaded.scope,
+    stale_months: staleMonths,
+    surfaces: buildSurfaces(findings),
+    findings,
+    counts: countByKind(findings),
+    empty_result: findings.length === 0,
+    latency_ms: Math.round(performance.now() - t0),
+  };
+}