phronesis 1.0.0

package/vendor/core/src/active-context.js

@@ -0,0 +1,167 @@
+// Active-context projection — the tracked, human-facing summary of a domain's compiled
+// state (core-0017 H5 / B2; specs/compile-retrieve-loop.md §"Generated-state hygiene";
+// specs/workspace-substrate.md §"Derived vs tracked generated state"). ONE file per
+// domain, domains/{domain}/ACTIVE_CONTEXT.md: generated-but-tracked (kept in version
+// control + the export, staleness-checked) — distinct from the DERIVED machine index
+// under .phronesis/index/ (rebuildable, gitignored, export-stripped) and from MEMORY.md's
+// compound-memory role.
+//
+// It is NOT a typed object — it lives outside compiled/, so contextFor returns null and
+// `phronesis validate` skips it as content. But the validate-time staleness check reads
+// it: a compiled object newer than its projection entry fails validation until a refresh
+// (the post_compile hook) brings the projection current. compile is the only writer that
+// refreshes it; no action type writes it directly (core-0016 review finding #2 — generated
+// state is never a free-form action write).
+
+import { join, dirname } from 'node:path';
+import { readFile, writeFile, rename, readdir } from 'node:fs/promises';
+import fse from 'fs-extra';
+import { walkMarkdown, readObjectRecord } from './workspace-scan.js';
+
+const PROJECTION_FILE = 'ACTIVE_CONTEXT.md';
+const DATE_LINE_RE = /^### (\d{4}-\d{2}-\d{2})\s*$/;
+// The strict, parseable entry line: the staleness check reads `{typeDir}/{name}` and its
+// recorded freshness date back out of it. Human-readable AND machine-checkable, so the
+// one file serves both the operator and the gate (the key carries the type-dir, so the
+// section headings are cosmetic and the parser never depends on them).
+const ENTRY_RE = /^- `([a-z0-9-]+\/[a-z0-9-]+)` — .*\(updated (\d{4}-\d{2}-\d{2})\)$/;
+
+// One object's freshness = the latest date it reflects: created, updated (if any), and
+// every dated ## Log entry. YYYY-MM-DD sorts lexically, so the string max IS the date max.
+function objectFreshness(fm, body) {
+  const dates = [];
+  if (typeof fm.created === 'string') dates.push(fm.created);
+  if (typeof fm.updated === 'string') dates.push(fm.updated);
+  for (const line of body.split('\n')) {
+    const m = line.match(DATE_LINE_RE);
+    if (m) dates.push(m[1]);
+  }
+  return dates.length ? dates.sort().at(-1) : '0000-00-00';
+}
+
+// Domain dirs under domains/ (a fresh install may have none populated yet).
+async function listDomainSlugs(installRoot) {
+  let entries;
+  try {
+    entries = await readdir(join(installRoot, 'domains'), { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort();
+}
+
+// One domain's compiled objects → [{ key, name, typeDir, title, freshness }], key-sorted.
+async function domainObjects(installRoot, domain) {
+  const files = await walkMarkdown(installRoot, join(installRoot, 'domains', domain, 'compiled'));
+  const out = [];
+  for (const rel of files) {
+    const rec = await readObjectRecord(installRoot, rel);
+    if (!rec || rec.ctx.layer !== 'domain') continue;
+    out.push({
+      key: `${rec.ctx.typeDir}/${rec.ctx.name}`,
+      name: rec.ctx.name,
+      typeDir: rec.ctx.typeDir,
+      title: typeof rec.fm.title === 'string' ? rec.fm.title : rec.ctx.name,
+      freshness: objectFreshness(rec.fm, rec.body),
+    });
+  }
+  out.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+  return out;
+}
+
+// Deterministic projection bytes for one domain (no clock, no machine-only state — it is
+// tracked + exported, so it must be reproducible from compiled/ alone).
+export async function buildActiveContextProjection({ installRoot, domain }) {
+  const objects = await domainObjects(installRoot, domain);
+  const lines = [
+    `# Active context — ${domain}`,
+    '',
+    `> Generated projection of ${domain}'s compiled state — derived but tracked (in version`,
+    '> control and `phronesis export`), refreshed by compile. `phronesis validate` flags it',
+    '> stale when a compiled object is newer than its entry here. Do not hand-edit.',
+    '',
+  ];
+  if (objects.length === 0) {
+    lines.push('_No compiled objects yet._', '');
+    return lines.join('\n');
+  }
+  const byDir = new Map();
+  for (const o of objects) {
+    if (!byDir.has(o.typeDir)) byDir.set(o.typeDir, []);
+    byDir.get(o.typeDir).push(o);
+  }
+  for (const typeDir of [...byDir.keys()].sort()) {
+    lines.push(`## ${typeDir}`, '');
+    for (const o of byDir.get(typeDir)) {
+      lines.push(`- \`${o.key}\` — ${o.title} (updated ${o.freshness})`);
+    }
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+async function writeAtomic(abs, content) {
+  await fse.ensureDir(dirname(abs));
+  // .partial- is the scan-ignored, gitignored temp family the writers use; a crash
+  // mid-write never leaves a torn projection.
+  const tmp = `${abs}.partial-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
+  await writeFile(tmp, content);
+  await rename(tmp, abs);
+}
+
+// Refresh one domain's projection (the post_compile hook's job, and the accept path's).
+export async function refreshActiveContext({ installRoot, domain }) {
+  const content = await buildActiveContextProjection({ installRoot, domain });
+  await writeAtomic(join(installRoot, 'domains', domain, PROJECTION_FILE), content);
+  return { domain, path: `domains/${domain}/${PROJECTION_FILE}` };
+}
+
+// Parse an existing projection's recorded entries → Map(`{typeDir}/{name}` → date).
+function parseProjectionEntries(content) {
+  const recorded = new Map();
+  for (const line of content.split('\n')) {
+    const m = line.match(ENTRY_RE);
+    if (m) recorded.set(m[1], m[2]);
+  }
+  return recorded;
+}
+
+// The validate-time staleness check (H5): for each domain that HAS a projection, flag any
+// recorded object whose current freshness is newer than its projection entry — the
+// projection is stale until a refresh brings it current. Minimal by design (the packet's
+// scope guard): present-but-stale only; missing-object and the AGENTS.md-conflict check
+// are deferred. A domain with no projection is not stale (nothing claims to summarize it),
+// so non-compile flows (a decision logged with no compile yet) never trip it.
+export async function checkActiveContextStaleness({ installRoot }) {
+  const findings = [];
+  for (const domain of await listDomainSlugs(installRoot)) {
+    let projContent;
+    try {
+      projContent = await readFile(join(installRoot, 'domains', domain, PROJECTION_FILE), 'utf8');
+    } catch {
+      continue; // no projection — nothing to be stale against
+    }
+    const recorded = parseProjectionEntries(projContent);
+    if (recorded.size === 0) continue;
+    const freshnessByKey = new Map(
+      (await domainObjects(installRoot, domain)).map((o) => [o.key, o.freshness]),
+    );
+    for (const [key, projDate] of recorded) {
+      const objDate = freshnessByKey.get(key);
+      if (objDate === undefined) continue; // object gone (out-of-band delete) — not this check's job
+      if (objDate > projDate) {
+        findings.push({
+          domain,
+          key,
+          path: `domains/${domain}/compiled/${key}.md`,
+          objectDate: objDate,
+          projectionDate: projDate,
+        });
+      }
+    }
+  }
+  return findings;
+}

package/vendor/core/src/artifacts.js

@@ -0,0 +1,301 @@
+// Durable operator-facing artifacts — deliberately outside the typed-object ontology.
+//
+// Artifacts are the small, exportable deliverable class from change 0020. They are
+// non-canonical (so they do not pass through action types, compile, or the normal
+// search snapshot), but they still have a narrow structural contract: one allowed
+// kind, private exposure, resolved optional links, and explicit refinements.
+
+import { join, relative, sep } from 'node:path';
+import { link, open, readFile, readdir, rename, writeFile } from 'node:fs/promises';
+import { randomBytes } from 'node:crypto';
+import fse from 'fs-extra';
+import yaml from 'js-yaml';
+import { DATE_RE, LINK_RELS, RE_SLUG, classifyTarget } from './contract.js';
+import { serializeFrontmatter } from './action-writers.js';
+import { matchFrontmatterBlock, splitFrontmatter } from './workspace-scan.js';
+
+export const ARTIFACT_KINDS = Object.freeze(['prd']);
+
+const ARTIFACT_PATH_RE = new RegExp(
+  `^domains/(${RE_SLUG.source.slice(1, -1)})/artifacts/(${ARTIFACT_KINDS.join('|')})/(${RE_SLUG.source.slice(1, -1)})\\.md$`,
+);
+
+function localDateStamp(date = new Date()) {
+  const y = date.getFullYear();
+  const m = String(date.getMonth() + 1).padStart(2, '0');
+  const d = String(date.getDate()).padStart(2, '0');
+  return `${y}-${m}-${d}`;
+}
+
+function validDate(value) {
+  if (typeof value !== 'string' || !DATE_RE.test(value)) return false;
+  const [year, month, day] = value.split('-').map(Number);
+  const candidate = new Date(Date.UTC(year, month - 1, day));
+  return candidate.getUTCFullYear() === year && candidate.getUTCMonth() === month - 1 && candidate.getUTCDate() === day;
+}
+
+function plainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+// Returns null for every non-artifact path. A malformed path underneath artifacts/
+// returns a context with an error so the structural gate can name the exact file.
+export function artifactContextFor(relPath) {
+  const normalized = relPath.split(sep).join('/');
+  const match = normalized.match(ARTIFACT_PATH_RE);
+  if (match) return { domain: match[1], kind: match[2], slug: match[3], relPath: normalized };
+  if (normalized.startsWith('domains/') && normalized.includes('/artifacts/')) {
+    return { error: `"${normalized}" is not an allowed artifact path (expected domains/{domain}/artifacts/prd/{slug}.md)` };
+  }
+  return null;
+}
+
+async function walkFiles(installRoot, root) {
+  let entries;
+  try {
+    entries = await readdir(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const entry of entries) {
+    const absolute = join(root, entry.name);
+    if (entry.isDirectory()) files.push(...(await walkFiles(installRoot, absolute)));
+    else if (entry.isFile()) files.push(relative(installRoot, absolute));
+  }
+  return files;
+}
+
+// The structural gate must see every file under artifacts/, not only Markdown. A
+// stray binary or text file would otherwise travel in export without any contract.
+export async function listArtifactFiles(installRoot) {
+  return (await walkFiles(installRoot, join(installRoot, 'domains'))).filter((p) => p.split(sep).includes('artifacts'));
+}
+
+async function checkLinks({ installRoot, domain, links, errors }) {
+  if (links === undefined) return;
+  if (!Array.isArray(links)) {
+    errors.push('links: must be a list');
+    return;
+  }
+  for (const [i, link] of links.entries()) {
+    if (!plainObject(link)) {
+      errors.push(`links[${i}]: must be a mapping with rel + target`);
+      continue;
+    }
+    if (!link.rel) errors.push(`links[${i}]: missing rel`);
+    else if (!LINK_RELS.includes(link.rel)) errors.push(`links[${i}]: rel "${link.rel}" is not in the link vocabulary`);
+    if (link.forward !== undefined && typeof link.forward !== 'boolean') {
+      errors.push(`links[${i}]: forward must be a boolean when present`);
+    }
+    if (typeof link.target !== 'string' || link.target === '') {
+      errors.push(`links[${i}]: target must be a non-empty string`);
+      continue;
+    }
+    const cls = classifyTarget(link.target);
+    if (cls.form === 'invalid') {
+      errors.push(`links[${i}]: target "${link.target}" matches no link-target form`);
+      continue;
+    }
+    if (link.forward === true && !cls.domainObject) {
+      errors.push(`links[${i}]: forward:true is only allowed on domain-object targets (not "${link.target}")`);
+    }
+    const targetRel = cls.relPath(domain);
+    if (targetRel === null) {
+      errors.push(`link "${link.target}": a bare-slug target has no domain to resolve against`);
+      continue;
+    }
+    if (link.forward === true && cls.domainObject) continue;
+    const target = join(installRoot, targetRel);
+    if (relative(installRoot, target).startsWith('..')) {
+      errors.push(`link "${link.target}": target resolves outside the installation`);
+    } else if (!(await fse.pathExists(target))) {
+      errors.push(`link "${link.target}": target does not resolve to an existing file (add forward: true if it is not compiled yet)`);
+    }
+  }
+}
+
+// Validate one durable artifact's structural contract. This intentionally does not
+// call validateFrontmatter: a PRD has no ontology `type`, domain object identity, or
+// provenance requirement. The shared link grammar is retained.
+export async function checkArtifactContent({ installRoot, relPath, content }) {
+  const context = artifactContextFor(relPath);
+  if (!context) return [`"${relPath}" is not an artifact path`];
+  if (context.error) return [context.error];
+
+  const block = matchFrontmatterBlock(content);
+  if (!block) return ['no frontmatter block'];
+  let fm;
+  try {
+    fm = yaml.load(block[1], { schema: yaml.JSON_SCHEMA });
+  } catch (error) {
+    return [`could not parse frontmatter: ${error.message}`];
+  }
+  if (!plainObject(fm)) return ['frontmatter is not a YAML mapping'];
+
+  const errors = [];
+  for (const field of ['kind', 'title', 'created', 'exposure']) {
+    if (fm[field] === undefined || fm[field] === null || fm[field] === '') errors.push(`missing required field: ${field}`);
+  }
+  if (fm.kind !== undefined && fm.kind !== context.kind) {
+    errors.push(`kind: "${fm.kind}" does not match artifact path kind "${context.kind}"`);
+  }
+  if (!ARTIFACT_KINDS.includes(fm.kind)) errors.push(`kind: "${fm.kind}" is not an allowed artifact kind (${ARTIFACT_KINDS.join(' | ')})`);
+  if (fm.title !== undefined && (typeof fm.title !== 'string' || fm.title.trim() === '')) errors.push('title: must be a non-empty string');
+  if (fm.created !== undefined && !validDate(fm.created)) errors.push(`created: "${fm.created}" is not YYYY-MM-DD (a real calendar date)`);
+  if (fm.exposure !== 'private') errors.push('exposure: durable artifacts must be private in V1');
+  if (fm.updated !== undefined) {
+    if (!validDate(fm.updated)) errors.push(`updated: "${fm.updated}" is not YYYY-MM-DD (a real calendar date)`);
+    else if (validDate(fm.created) && fm.updated < fm.created) errors.push('updated: must be greater than or equal to created');
+  }
+  if (content.slice(block[0].length).trim() === '') {
+    errors.push('body: durable artifacts must contain a non-whitespace document body');
+  }
+
+  if (fm.provenance !== undefined) {
+    if (!plainObject(fm.provenance)) {
+      errors.push('provenance: must be a mapping when present');
+    } else if (fm.provenance.refinements !== undefined) {
+      if (!Array.isArray(fm.provenance.refinements)) {
+        errors.push('provenance.refinements: must be an append-only list of { date, note } entries');
+      } else {
+        fm.provenance.refinements.forEach((entry, i) => {
+          if (!plainObject(entry)) {
+            errors.push(`provenance.refinements[${i}]: must be a { date, note } mapping`);
+            return;
+          }
+          if (!validDate(entry.date)) errors.push(`provenance.refinements[${i}].date: must be YYYY-MM-DD (a real calendar date)`);
+          if (typeof entry.note !== 'string' || entry.note.trim() === '') errors.push(`provenance.refinements[${i}].note: must be a non-empty string`);
+        });
+      }
+    }
+  }
+  await checkLinks({ installRoot, domain: context.domain, links: fm.links, errors });
+  return errors;
+}
+
+export async function readArtifactRecord(installRoot, relPath) {
+  const context = artifactContextFor(relPath);
+  if (!context || context.error) return null;
+  let content;
+  try {
+    content = await readFile(join(installRoot, relPath), 'utf8');
+  } catch {
+    return null;
+  }
+  const errors = await checkArtifactContent({ installRoot, relPath, content });
+  if (errors.length) return null;
+  const block = matchFrontmatterBlock(content);
+  const fm = yaml.load(block[1], { schema: yaml.JSON_SCHEMA });
+  return {
+    path: relPath,
+    layer: 'domain',
+    domain: context.domain,
+    codexKind: null,
+    type: `artifact:${fm.kind}`,
+    name: context.slug,
+    title: typeof fm.title === 'string' ? fm.title : context.slug,
+    status: null,
+    exposure: fm.exposure ?? null,
+    stance: null,
+    links: Array.isArray(fm.links) ? fm.links : [],
+    body: content.slice(block[0].length),
+  };
+}
+
+export function artifactPath({ domain, kind = 'prd', slug }) {
+  if (!RE_SLUG.test(domain) || !ARTIFACT_KINDS.includes(kind) || !RE_SLUG.test(slug)) {
+    throw new Error('artifact path requires a valid domain, allowed kind, and kebab-case slug');
+  }
+  return `domains/${domain}/artifacts/${kind}/${slug}.md`;
+}
+
+// Direct artifact writer for runtime-capable surfaces. It never emits events because
+// artifacts are non-canonical. Existing paths are a fail-closed choice: only an
+// explicit refinement can edit in place, preserving the artifact path as identity.
+export async function writeArtifact({ installRoot, domain, kind = 'prd', slug, title, body, links, refine = false, refinementNote, now = new Date() }) {
+  const relPath = artifactPath({ domain, kind, slug });
+  const absolute = join(installRoot, relPath);
+  const date = localDateStamp(now);
+  await fse.ensureDir(join(installRoot, `domains/${domain}/artifacts/${kind}`));
+  // Keep the cooperative lock alongside the installation metadata rather than
+  // under artifacts/. That avoids both an export-visible operational directory
+  // and a path that the artifact structural gate would need to special-case.
+  const lockPath = join(installRoot, '.phronesis', `.artifact-lock-${domain}-${kind}-${slug}.lock`);
+  await fse.ensureDir(join(installRoot, '.phronesis'));
+  let lock;
+  try {
+    lock = await open(lockPath, 'wx');
+  } catch (error) {
+    if (error?.code === 'EEXIST') {
+      return {
+        ok: false,
+        path: relPath,
+        prompt: `Artifact ${relPath} is currently being written. Retry after that write completes.`,
+      };
+    }
+    throw error;
+  }
+
+  let temporary;
+  try {
+    // Check existence only after acquiring the lock. This makes same-slug creation
+    // fail closed across concurrent cooperative callers, rather than last-rename wins.
+    const exists = await fse.pathExists(absolute);
+    let fm;
+    let documentBody;
+    if (exists) {
+      if (!refine) {
+        return {
+          ok: false,
+          path: relPath,
+          prompt: `Artifact ${relPath} already exists. State explicit refine intent or choose a new slug; existing artifacts are never silently replaced.`,
+        };
+      }
+      const current = await readFile(absolute, 'utf8');
+      const errors = await checkArtifactContent({ installRoot, relPath, content: current });
+      if (errors.length) throw new Error(`cannot refine malformed artifact ${relPath}: ${errors.join('; ')}`);
+      const source = splitFrontmatter(current);
+      const currentBlock = matchFrontmatterBlock(current);
+      fm = yaml.load(source, { schema: yaml.JSON_SCHEMA });
+      const provenance = plainObject(fm.provenance) ? { ...fm.provenance } : {};
+      const refinements = Array.isArray(provenance.refinements) ? [...provenance.refinements] : [];
+      refinements.push({ date, note: refinementNote || 'Refined in conversation.' });
+      fm = { ...fm, title: title || fm.title, updated: date, provenance: { ...provenance, refinements } };
+      documentBody = body === undefined ? current.slice(currentBlock[0].length) : body;
+    } else {
+      if (typeof title !== 'string' || title.trim() === '') throw new Error('a new artifact requires a non-empty title');
+      fm = { kind, title, created: date, exposure: 'private' };
+      documentBody = body;
+    }
+    if (links !== undefined) fm.links = links;
+    const content = `${serializeFrontmatter(fm)}\n${String(documentBody ?? '').trim()}\n`;
+    const errors = await checkArtifactContent({ installRoot, relPath, content });
+    if (errors.length) throw new Error(`invalid artifact ${relPath}: ${errors.join('; ')}`);
+    temporary = `${absolute}.partial-${process.pid}-${randomBytes(4).toString('hex')}`;
+    await writeFile(temporary, content, 'utf8');
+    if (exists) {
+      await rename(temporary, absolute);
+    } else {
+      try {
+        // link() is an atomic no-clobber publication primitive: unlike rename(), it
+        // refuses EEXIST rather than replacing a concurrent new artifact.
+        await link(temporary, absolute);
+      } catch (error) {
+        if (error?.code === 'EEXIST') {
+          return {
+            ok: false,
+            path: relPath,
+            prompt: `Artifact ${relPath} was created concurrently. State explicit refine intent or choose a new slug.`,
+          };
+        }
+        throw error;
+      }
+    }
+    return { ok: true, path: relPath, refined: exists };
+  } finally {
+    if (temporary) await fse.remove(temporary).catch(() => {});
+    if (lock) await lock.close().catch(() => {});
+    await fse.remove(lockPath).catch(() => {});
+  }
+}

package/vendor/core/src/content-digest.js

@@ -0,0 +1,21 @@
+// Content digest for the compile-review TOCTOU lock (change 0027). ONE matcher, shared by
+// the compile handler (stamping `content_digest` on `compile.candidate`), `compile review`'s
+// `classifyDrafts` (re-hashing the on-disk draft), and the gate — so the handler and the
+// verifier can never disagree about "what the bytes are" (the two-consumers→one-matcher rule,
+// rules.md). The digest is over RAW file bytes (a Buffer, no utf8 round-trip): both sides read
+// the same file the same way, removing the entire "is it the string or the bytes?" class.
+
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+
+// sha-256 over raw bytes, formatted `sha256:<lowercase-hex>` (the 0027 delta format).
+export function contentDigest(bytes) {
+  return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+
+// Digest the EXACT persisted bytes at an absolute path. Reads with no encoding → a Buffer,
+// so the hash is over the file's real bytes (what the verifier later re-reads), not a
+// utf8-decoded-then-re-encoded string. Throws on a read error (the caller fails closed).
+export async function digestFile(absPath) {
+  return contentDigest(await readFile(absPath));
+}