@supersuit/hypercontext 0.0.0-stage → 0.2.0

package/src/find.mjs

@@ -0,0 +1,157 @@
+// Where each kind's records live in a workspace, as paths relative to the workspace root.
+//
+// The layout is the one Supersuit writes (self/, people/, superprojects/, documents/ ...), plus
+// the names it used before (projects/, PROJECT.md, PLAN.md), because a workspace mid-conversion
+// holds both and a check that saw only one would report the other as clean. Nothing here reads a
+// record; it lists files. The filesystem is injected so tests never read the machine.
+import { readdirSync, existsSync, lstatSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const fsDefault = {
+  list: (p) => { try { return readdirSync(p); } catch { return []; } },
+  // lstat, never stat: a linked file or folder is another tree's record (a document symlinked
+  // in from a company workspace, a superproject shared by link). Reading it here would count it
+  // twice, and stamping it would write into a repo this check was never pointed at.
+  isDir: (p) => { try { return lstatSync(p).isDirectory(); } catch { return false; } },
+  isFile: (p) => { try { return lstatSync(p).isFile(); } catch { return false; } },
+  exists: (p) => existsSync(p),
+};
+
+// A folder name that is never part of the record tree: hidden, private scratch, dependencies.
+const skip = (name) => name.startsWith('.') || name.startsWith('_') || name === 'node_modules';
+const NOT_RECORDS = new Set(['README.md', 'CLAUDE.md', 'AGENTS.md', '_TEMPLATE.md', 'TEMPLATE.md']);
+
+/**
+ * The superproject roots: superprojects/, and projects/ unless it is the link the rename leaves
+ * behind (isDir never follows a link, so that link is not a second root).
+ */
+export function superprojectRoots(ws, fs = fsDefault) {
+  return ['superprojects', 'projects'].filter((r) => fs.isDir(join(ws, r)));
+}
+
+// Every folder under a superprojects root that is a superproject (holds a record file), at any
+// depth: done/, a parent's own superprojects/ or projects/, never inside a documents/ folder.
+const PROJECT_FILES = ['SUPERPROJECT.md', 'PROJECT.md'];
+export function superprojectDirs(ws, fs = fsDefault) {
+  const out = [];
+  const walk = (rel, depth) => {
+    if (depth > 6) return;
+    for (const name of fs.list(join(ws, rel)).sort()) {
+      if (skip(name) || name === 'documents') continue;
+      const child = `${rel}/${name}`;
+      if (!fs.isDir(join(ws, child))) continue;
+      const files = fs.list(join(ws, child));
+      if (PROJECT_FILES.some((f) => files.includes(f)) || files.includes('STATE.md')) out.push(child);
+      walk(child, depth + 1);
+    }
+  };
+  for (const root of superprojectRoots(ws, fs)) walk(root, 0);
+  return out;
+}
+
+// The documents/ folders a workspace keeps: the root one and every superproject's own.
+export function documentHomes(ws, fs = fsDefault) {
+  const homes = fs.isDir(join(ws, 'documents')) ? ['documents'] : [];
+  for (const d of superprojectDirs(ws, fs)) if (fs.isDir(join(ws, d, 'documents'))) homes.push(`${d}/documents`);
+  return homes;
+}
+
+const filesIn = (ws, rel, fs, pick) =>
+  fs.list(join(ws, rel)).filter((n) => !skip(n) && fs.isFile(join(ws, rel, n)) && pick(n)).sort().map((n) => `${rel}/${n}`);
+
+const dirsIn = (ws, rel, fs) =>
+  fs.list(join(ws, rel)).filter((n) => !skip(n) && fs.isDir(join(ws, rel, n))).sort();
+
+// Every piece.md at any depth under a documents home.
+function pieces(ws, home, fs) {
+  const out = [];
+  const walk = (rel, depth) => {
+    if (depth > 6) return;
+    for (const name of fs.list(join(ws, rel)).sort()) {
+      if (skip(name)) continue;
+      const child = `${rel}/${name}`;
+      if (name === 'piece.md' && fs.isFile(join(ws, child))) out.push(child);
+      else if (fs.isDir(join(ws, child))) walk(child, depth + 1);
+    }
+  };
+  walk(home, 0);
+  return out;
+}
+
+/** Every record of one kind, as workspace-relative paths, sorted. */
+export function findRecords(ws, kind, fs = fsDefault) {
+  const md = (n) => n.endsWith('.md') && !NOT_RECORDS.has(n);
+  switch (kind) {
+    case 'self':
+      return fs.isFile(join(ws, 'self/self.md')) ? ['self/self.md'] : [];
+    case 'friend':
+      // An archived person keeps their record under people/archive/, and it is still a record.
+      return [
+        ...dirsIn(ws, 'people', fs).filter((n) => n !== 'groups' && fs.isFile(join(ws, 'people', n, 'friend.md'))).map((n) => `people/${n}/friend.md`),
+        ...dirsIn(ws, 'people/archive', fs).filter((n) => fs.isFile(join(ws, 'people/archive', n, 'friend.md'))).map((n) => `people/archive/${n}/friend.md`),
+      ];
+    case 'group':
+      return dirsIn(ws, 'people/groups', fs).filter((n) => fs.isFile(join(ws, 'people/groups', n, 'group.md')))
+        .map((n) => `people/groups/${n}/group.md`);
+    case 'superproject':
+      return superprojectDirs(ws, fs).flatMap((d) => {
+        const f = PROJECT_FILES.find((x) => fs.isFile(join(ws, d, x)));
+        return f ? [`${d}/${f}`] : [];
+      });
+    case 'state':
+      return superprojectDirs(ws, fs).filter((d) => fs.isFile(join(ws, d, 'STATE.md'))).map((d) => `${d}/STATE.md`);
+    case 'atomic-action-map':
+      return superprojectDirs(ws, fs).flatMap((d) => {
+        const f = ['ATOMIC-ACTION-MAP.md', 'PLAN.md'].find((x) => fs.isFile(join(ws, d, x)));
+        return f ? [`${d}/${f}`] : [];
+      });
+    case 'superobjective': {
+      const out = [];
+      for (const home of ['self/calling/superobjectives', 'superobjectives']) {
+        const walk = (rel, depth) => {
+          if (depth > 3) return;
+          for (const n of dirsIn(ws, rel, fs)) {
+            if (fs.isFile(join(ws, rel, n, 'superobjective.md'))) out.push(`${rel}/${n}/superobjective.md`);
+            else walk(`${rel}/${n}`, depth + 1);
+          }
+        };
+        walk(home, 0);
+      }
+      return out;
+    }
+    case 'piece':
+      return documentHomes(ws, fs).flatMap((h) => pieces(ws, h, fs));
+    case 'conversation':
+      return dirsIn(ws, 'meeting-transcripts', fs).filter((n) => fs.isFile(join(ws, 'meeting-transcripts', n, 'transcript.md')))
+        .map((n) => `meeting-transcripts/${n}/transcript.md`);
+    case 'document':
+      return documentHomes(ws, fs).flatMap((h) => filesIn(ws, h, fs, md));
+    case 'checkpoint':
+      return filesIn(ws, 'checkpoints', fs, md);
+    case 'hdsop':
+      return filesIn(ws, 'workflows', fs, (n) => md(n) && n !== 'CATALOG.md');
+    case 'workflow-catalog':
+      return fs.isFile(join(ws, 'workflows/CATALOG.md')) ? ['workflows/CATALOG.md'] : [];
+    case 'recurrent':
+      return filesIn(ws, 'recurrents', fs, md);
+    case 'tile-app': {
+      const out = [];
+      for (const home of ['helm/tile-apps', 'tile-apps']) {
+        for (const n of dirsIn(ws, home, fs)) if (fs.isFile(join(ws, home, n, 'app.json'))) out.push(`${home}/${n}/app.json`);
+      }
+      return out;
+    }
+    default:
+      throw new Error(`no such kind: ${kind}`);
+  }
+}
+
+/** Records a workspace still holds in a shape a kind's standard retired, which no finder above sees. */
+export function legacyRecords(ws, fs = fsDefault) {
+  const out = [];
+  if (fs.isFile(join(ws, 'self/SUPEROBJECTIVE.md'))) out.push({ kind: 'superobjective', path: 'self/SUPEROBJECTIVE.md' });
+  for (const n of fs.list(join(ws, 'people'))) {
+    if (n.endsWith('.md') && !NOT_RECORDS.has(n) && fs.isFile(join(ws, 'people', n))) out.push({ kind: 'friend', path: `people/${n}` });
+  }
+  return out;
+}

package/src/index.mjs

@@ -0,0 +1,9 @@
+export { KINDS, STANDARD_BASE, CURRENT_VERSION, byKind, bareStandard, versionOf } from './kinds.mjs';
+export { manifestHome, implementedVersions, readManifest, exportManifests, sameManifest, checkOnline, manifestFindings, MANIFEST_CODE } from './manifest.mjs';
+export { findRecords, legacyRecords, superprojectRoots, superprojectDirs, documentHomes } from './find.mjs';
+export { judge, standardOf, stampStandard, CODE, VERSION_CODE } from './selfdoc.mjs';
+export { check } from './check.mjs';
+export { stamp, PACKAGE_STAMPS } from './stamp.mjs';
+export { readBaseline, applyBaseline, writeBaseline, keyOf } from './baseline.mjs';
+export { renderReport, renderStamp } from './render.mjs';
+export { resolvePackage, normalize } from './packages.mjs';

package/src/kinds.mjs

@@ -0,0 +1,77 @@
+// Every kind of record a hypercontext workspace holds: where its records live, the one page that
+// is its standard, and the package that checks its shape.
+//
+// THIS FILE DEFINES NO RECORD TYPE. A kind's shape belongs to its own package (friend-md,
+// group-md, superprojects ...), and this list only says where to look and whom to ask. The one
+// rule this package owns is the property every record shares, hypercontext itself: a record
+// names the standard it follows, so a stranger or a fresh agent can open it cold and find its
+// rules (Gary, 2026-10-17: "AMNESIAC AIS need to be able to refer the standard a file/folder is
+// supposed to uphold"; 2026-10-20: "every instance ... needs to be self documenting").
+//
+// Every kind has its package (since 0.2.0). A kind added with `pkg: null` would still be checked
+// for the shared property, and the report would say in one line that nothing checks its shape,
+// so the gap is visible from the same command that would close it.
+
+// The URL shapes and how a URL reads back as a version are shared by every record package, so they
+// live in @supersuit/hypercontext-core and are re-exported here unchanged.
+import { STANDARD_BASE, bareStandard, standardUrl, versionOf } from '@supersuit/hypercontext-core';
+export { STANDARD_BASE, bareStandard, versionOf };
+// A record names one VERSION of its standard (docs/STANDARDS.md): the page at /v<N> never changes
+// meaning, so the link says which rules the record was written to. The bare /standards/<kind>
+// is the latest page, for people; a record carrying it predates versions.
+export const CURRENT_VERSION = 1;
+const url = (slug, v = CURRENT_VERSION) => standardUrl(slug, v);
+
+/**
+ * @typedef {object} Kind
+ * @property {string} kind       the record kind, as the report names it
+ * @property {string} label      what a person calls it
+ * @property {string} standard   the versioned page its `standard:` field must name
+ * @property {'md'|'json'} format where the field lives: a YAML header or a JSON key
+ * @property {string[]} context  the shared context keys this kind's standard requires
+ * @property {object|null} pkg   the package that checks its shape, or null when none exists
+ * @property {string} [sharesLint] another kind whose package run already covers this one
+ * @property {boolean} [stampable] false when no tool may add the field yet (see `why`)
+ * @property {string} [why]      why a kind is not stampable, said in the report
+ */
+
+const CONTEXT = Object.freeze(['id', 'summary', 'read_when', 'as_of', 'keep']);
+const SUPERPROJECTS = Object.freeze({ name: '@supersuit/superprojects', repo: 'superprojects', bin: 'bin/superprojects.mjs' });
+// One package owns both the workflow maps and the catalog that scores them; one run checks both.
+const HDSOP = Object.freeze({ name: '@supersuit/hdsop-md', repo: 'hdsop-md', bin: 'bin/hdsop-md.mjs' });
+
+/** @type {readonly Kind[]} */
+export const KINDS = Object.freeze([
+  { kind: 'self', label: 'the owner, self/self.md', standard: url('self'), format: 'md', context: CONTEXT,
+    pkg: { name: '@supersuit/self-md', repo: 'self-md', bin: 'bin/self-md.mjs' } },
+  { kind: 'friend', label: 'people, people/<slug>/friend.md', standard: url('friend'), format: 'md', context: CONTEXT,
+    pkg: { name: '@supersuit/friend-md', repo: 'friend-md', bin: 'bin/friend-md.mjs' } },
+  { kind: 'group', label: 'groups, people/groups/<id>/group.md', standard: url('group'), format: 'md', context: [],
+    pkg: { name: '@supersuit/group-md', repo: 'group-md', bin: 'bin/group-md.mjs' } },
+  { kind: 'superproject', label: 'superprojects, SUPERPROJECT.md', standard: url('superproject'), format: 'md', context: [],
+    pkg: SUPERPROJECTS },
+  { kind: 'state', label: 'superproject state, STATE.md', standard: url('state'), format: 'md', context: [],
+    pkg: SUPERPROJECTS, sharesLint: 'superproject' },
+  { kind: 'atomic-action-map', label: 'atomic action maps, ATOMIC-ACTION-MAP.md', standard: url('atomic-action-map'), format: 'md', context: [],
+    pkg: SUPERPROJECTS, sharesLint: 'superproject' },
+  { kind: 'superobjective', label: 'superobjectives, superobjective.md', standard: url('superobjective'), format: 'md', context: CONTEXT,
+    pkg: { name: '@supersuit/superobjective', repo: 'superobjective', bin: 'bin/superobjective.mjs' } },
+  { kind: 'piece', label: 'pieces, piece.md', standard: url('piece'), format: 'md', context: CONTEXT,
+    pkg: { name: '@supersuit/piece-md', repo: 'piece-md', bin: 'bin/piece-md.mjs' } },
+  { kind: 'conversation', label: 'conversations, transcript.md', standard: url('conversation'), format: 'md', context: [],
+    pkg: { name: '@supersuit/transcript-md', repo: 'transcript-md', bin: 'lib/freedom-conversations-cli.mjs' } },
+  { kind: 'document', label: 'documents, documents/*.md', standard: url('document'), format: 'md', context: [],
+    pkg: { name: '@supersuit/document-md', repo: 'document-md', bin: 'bin/document-md.mjs' } },
+  { kind: 'checkpoint', label: 'checkpoints, checkpoints/*.md', standard: url('checkpoint'), format: 'md', context: [],
+    pkg: { name: '@supersuit/checkpoint-md', repo: 'checkpoint-md', bin: 'bin/checkpoint-md.mjs' } },
+  { kind: 'hdsop', label: 'workflow maps, workflows/*.md', standard: url('hdsop'), format: 'md', context: [],
+    pkg: HDSOP },
+  { kind: 'workflow-catalog', label: 'the workflow catalog, workflows/CATALOG.md', standard: url('workflow-catalog'), format: 'md', context: [],
+    pkg: HDSOP, sharesLint: 'hdsop' },
+  { kind: 'recurrent', label: 'recurrents, recurrents/*.md', standard: url('recurrent'), format: 'md', context: [],
+    pkg: { name: '@supersuit/recurrent-md', repo: 'recurrent-md', bin: 'bin/recurrent-md.mjs' } },
+  { kind: 'tile-app', label: 'tile apps, <app>/app.json', standard: url('tile-app'), format: 'json', context: [],
+    pkg: { name: '@supersuit/tile-app-md', repo: 'tile-app-md', bin: 'bin/tile-app-md.mjs' } },
+]);
+
+export const byKind = (k) => KINDS.find((x) => x.kind === k);

package/src/manifest.mjs

@@ -0,0 +1,129 @@
+// The manifests: each version of each standard as data (docs/STANDARDS.md).
+//
+// ONE SOURCE. A kind's manifest is the file its own package ships at standards/<kind>/v<N>.json,
+// and this package ships them only for kinds no package owns yet. Nothing here writes a
+// manifest's content; `exportManifests` copies each from its owner so the wiki publishes the
+// owner's bytes, and `--online` proves the published copy is still the owner's.
+import { readFileSync, readdirSync, mkdirSync, writeFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { KINDS, STANDARD_BASE, CURRENT_VERSION } from './kinds.mjs';
+import { resolvePackage } from './packages.mjs';
+import { validateManifest } from '@supersuit/hypercontext-core';
+
+/** The finding for a manifest an owner ships that a reader with no package could not use. */
+export const MANIFEST_CODE = 'manifest:invalid';
+
+const OWN = join(dirname(dirname(fileURLToPath(import.meta.url))), 'standards');
+
+/** The folder holding a kind's manifests, and who owns it. */
+export function manifestHome(kind, { packagesDir } = {}) {
+  if (kind.pkg) {
+    const dir = resolvePackage(kind.pkg, { packagesDir });
+    if (dir && existsSync(join(dir, 'standards', kind.kind))) return { dir: join(dir, 'standards', kind.kind), owner: kind.pkg.name };
+    return { dir: null, owner: kind.pkg.name };
+  }
+  // A kind with no package and no manifest here has none at all: missing, never a crash.
+  const own = join(OWN, kind.kind);
+  return { dir: existsSync(own) ? own : null, owner: '@supersuit/hypercontext' };
+}
+
+/** Every version a kind's owner ships a manifest for; [current] when none can be read. */
+export function implementedVersions(kind, opts = {}) {
+  const { dir } = manifestHome(kind, opts);
+  if (!dir) return [CURRENT_VERSION];
+  const got = readdirSync(dir).map((n) => n.match(/^v(\d+)\.json$/)).filter(Boolean).map((m) => Number(m[1])).sort((a, b) => a - b);
+  return got.length ? got : [CURRENT_VERSION];
+}
+
+/** A kind's manifest for one version, from its owner, or null. */
+export function readManifest(kind, version = CURRENT_VERSION, opts = {}) {
+  const { dir } = manifestHome(kind, opts);
+  if (!dir) return null;
+  try { return JSON.parse(readFileSync(join(dir, `v${version}.json`), 'utf8')); } catch { return null; }
+}
+
+/**
+ * Every manifest a kind's owner ships, judged by @supersuit/hypercontext-core's validateManifest
+ * (STANDARDS.md section 2), plus the two things only the file's place can say: it is the manifest
+ * of this kind, and of the version its file name says. One error finding per bad file.
+ * @returns {Array<{kind, level, code, path, message}>}
+ */
+export function manifestFindings(kind, opts = {}) {
+  const { dir, owner } = manifestHome(kind, opts);
+  if (!dir) return [];
+  const out = [];
+  for (const name of readdirSync(dir).filter((n) => /^v\d+\.json$/.test(n)).sort()) {
+    const rel = `standards/${kind.kind}/${name}`;
+    const bad = (why) => out.push({ kind: kind.kind, level: 'error', code: MANIFEST_CODE, path: '', message: `${owner} ships ${rel}, ${why}` });
+    let m;
+    try { m = JSON.parse(readFileSync(join(dir, name), 'utf8')); } catch { bad('which is not JSON'); continue; }
+    const { problems } = validateManifest(m);
+    if (m && typeof m === 'object') {
+      if (m.kind !== kind.kind) problems.push(`its kind is ${JSON.stringify(m.kind)}, not ${kind.kind}`);
+      if (m.version !== Number(name.match(/\d+/)[0])) problems.push(`its version is ${JSON.stringify(m.version)}, not the ${name.replace('.json', '')} its file name says`);
+    }
+    if (problems.length) bad(`which is not a valid manifest: ${problems.join('; ')}`);
+  }
+  return out;
+}
+
+/**
+ * Copy every kind's manifests from their owners into `out/<kind>/v<N>.json`, plus `out/index.json`
+ * listing them, for a site to publish unchanged. A kind whose owner is not installed is listed as
+ * missing, never written from a guess, and one whose owner ships an invalid manifest is listed with
+ * `invalid` and not written.
+ */
+export function exportManifests(out, opts = {}) {
+  const index = [];
+  for (const k of KINDS) {
+    const { dir, owner } = manifestHome(k, opts);
+    // An invalid manifest is never published: the page a record links to must describe its rules.
+    const invalid = dir ? manifestFindings(k, opts).map((f) => f.message) : [];
+    const versions = dir && !invalid.length ? implementedVersions(k, opts) : [];
+    for (const v of versions) {
+      mkdirSync(join(out, k.kind), { recursive: true });
+      writeFileSync(join(out, k.kind, `v${v}.json`), readFileSync(join(dir, `v${v}.json`)));
+    }
+    index.push({ kind: k.kind, owner, latest: `${STANDARD_BASE}${k.kind}`, versions: versions.map((v) => `${STANDARD_BASE}${k.kind}/v${v}`), missing: !dir, ...(invalid.length ? { invalid } : {}) });
+  }
+  mkdirSync(out, { recursive: true });
+  writeFileSync(join(out, 'index.json'), JSON.stringify({ manifest_version: 1, standards: index }, null, 2) + '\n');
+  return index;
+}
+
+// Key order is not meaning: compare manifests as canonical JSON.
+const canon = (v) => (Array.isArray(v) ? v.map(canon) : v && typeof v === 'object' ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, canon(v[k])])) : v);
+export const sameManifest = (a, b) => JSON.stringify(canon(a)) === JSON.stringify(canon(b));
+
+/**
+ * Prove every standard a workspace's records name is live, and says what the installed owner
+ * enforces. `seen` maps kind -> Set of standard URLs found in its records.
+ * @returns {Promise<Array<{kind, level, code, path, message}>>}
+ */
+export async function checkOnline(seen, { fetch: get = globalThis.fetch, packagesDir, timeoutMs = 15000 } = {}) {
+  const findings = [];
+  for (const k of KINDS) {
+    for (const url of seen.get(k.kind) ?? []) {
+      const m = url.match(/\/v(\d+)$/);
+      const page = await probe(get, url, timeoutMs);
+      if (!page.ok) { findings.push({ kind: k.kind, level: 'error', code: 'standard:unreachable', path: '', message: `${url} answered ${page.status}; every record naming it points at nothing` }); continue; }
+      if (!m) continue;
+      const json = await probe(get, `${url}.json`, timeoutMs, true);
+      if (!json.ok) { findings.push({ kind: k.kind, level: 'error', code: 'standard:unreachable', path: '', message: `${url}.json answered ${json.status}; the standard has no published manifest` }); continue; }
+      const local = readManifest(k, Number(m[1]), { packagesDir });
+      if (!local) continue;
+      if (!sameManifest(json.body, local)) findings.push({ kind: k.kind, level: 'error', code: 'standard:drift', path: '', message: `the manifest published at ${url}.json differs from the one ${manifestHome(k, { packagesDir }).owner} ships; republish the owner's file` });
+    }
+  }
+  return findings;
+}
+
+async function probe(get, url, timeoutMs, asJson = false) {
+  try {
+    const r = await get(url, { redirect: 'follow', signal: AbortSignal.timeout(timeoutMs) });
+    if (r.status !== 200) return { ok: false, status: r.status };
+    if (!asJson) return { ok: true, status: 200 };
+    try { return { ok: true, status: 200, body: await r.json() }; } catch { return { ok: false, status: '200 with a body that is not JSON' }; }
+  } catch (e) { return { ok: false, status: `no answer (${e.name})` }; }
+}

package/src/packages.mjs

@@ -0,0 +1,175 @@
+// Asking each kind's own package to check its records, and reading back what it said.
+//
+// Every package is asked through its documented command line, with --json, rather than through
+// its internals: the CLI is the contract each package promises to keep, so this package keeps
+// working across their releases. Their outputs differ in shape (rule or code or check, severity
+// or level), and normalize() is the only place that knows it.
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, relative } from 'node:path';
+
+const require = createRequire(import.meta.url);
+// This package's own root. In the hypercontext repository every record package is a sibling
+// workspace (packages/<repo>), so a checkout finds them with no install and no flag.
+const SELF_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+
+const nameAt = (dir) => { try { return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).name; } catch { return null; } };
+
+/**
+ * Where a package is, in this order:
+ * 1. `packagesDir/<repo>` when a folder of checkouts is named (the option or HYPERCONTEXT_PACKAGES).
+ *    Named means only: nothing else is consulted, so a caller can say exactly which packages run.
+ * 2. node resolution from this package, which finds an installed package and, in the hypercontext
+ *    repository after `npm install`, the workspace links.
+ * 3. `<repo>` beside this package, the layout of the hypercontext repository, so an un-installed
+ *    checkout still finds its sibling packages.
+ * @returns {string|null} the package root
+ */
+export function resolvePackage(pkg, { packagesDir = process.env.HYPERCONTEXT_PACKAGES } = {}) {
+  if (packagesDir) {
+    const dir = join(packagesDir, pkg.repo);
+    return nameAt(dir) === pkg.name ? dir : null;
+  }
+  try {
+    let dir = dirname(require.resolve(pkg.name));
+    for (let i = 0; i < 6; i++) {
+      if (nameAt(dir) === pkg.name) return realpathSync(dir);
+      dir = dirname(dir);
+    }
+  } catch { /* not installed; try the sibling workspace */ }
+  const sibling = join(dirname(SELF_ROOT), pkg.repo);
+  return nameAt(sibling) === pkg.name ? sibling : null;
+}
+
+export function packageVersion(dir) {
+  try { return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).version ?? ''; } catch { return ''; }
+}
+
+/** Run a package's command with --json and parse what it printed. */
+export function runJson(dir, bin, args, { cwd } = {}) {
+  const r = spawnSync(process.execPath, [join(dir, bin), ...args, '--json'], { cwd, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+  if (r.error) return { ok: false, error: r.error.message };
+  const out = (r.stdout ?? '').trim();
+  if (!out) return { ok: false, error: (r.stderr ?? '').trim().split('\n')[0] || `exit ${r.status}`, status: r.status };
+  try { return { ok: true, json: JSON.parse(out), status: r.status }; }
+  catch { return { ok: false, error: `printed something that is not JSON (exit ${r.status})`, status: r.status }; }
+}
+
+const LEVEL = { error: 'error', err: 'error', warn: 'warn', warning: 'warn', info: 'info', ok: 'ok' };
+
+/**
+ * One package finding in the shape this package reports: {level, code, path, message}.
+ * `where` maps the package's own pointer (a slug, an id, a piece path) to a workspace path.
+ */
+export function normalize(f, where = (x) => x) {
+  const level = LEVEL[String(f.level ?? f.severity ?? '').toLowerCase()] ?? 'warn';
+  const code = String(f.code ?? f.rule ?? f.check ?? 'finding');
+  const ptr = f.path ?? f.file ?? f.record ?? f.piece ?? f.slug ?? f.id ?? '';
+  const message = String(f.message ?? f.line ?? '');
+  return { level, code, path: ptr ? where(String(ptr)) : '', message, ...(f.fix ? { fix: String(f.fix) } : {}) };
+}
+
+const findingsOf = (json) => (Array.isArray(json) ? json : Array.isArray(json?.findings) ? json.findings : []);
+
+/**
+ * The per-kind calls. Each returns {ran, findings, note}. `ws` is absolute; paths returned are
+ * relative to it. A kind's call covers every record of that kind in the workspace.
+ */
+export const LINTS = {
+  self: (dir, bin, ws) => {
+    const r = runJson(dir, bin, ['lint', '--workspace', ws]);
+    return r.ok ? { ran: true, findings: findingsOf(r.json).map((f) => normalize(f)) } : { ran: false, note: r.error };
+  },
+  friend: (dir, bin, ws) => {
+    const r = runJson(dir, bin, ['lint', '--people', join(ws, 'people')]);
+    return r.ok ? { ran: true, findings: findingsOf(r.json).map((f) => normalize({ ...f, path: undefined, slug: f.slug }, (s) => `people/${s}/friend.md`)) } : { ran: false, note: r.error };
+  },
+  group: (dir, bin, ws) => {
+    if (!existsSync(join(ws, 'people/groups'))) return { ran: true, findings: [] };
+    const r = runJson(dir, bin, ['lint', join(ws, 'people/groups')]);
+    return r.ok ? { ran: true, findings: findingsOf(r.json).map((f) => normalize(f, (s) => `people/groups/${s}/group.md`)) } : { ran: false, note: r.error };
+  },
+  superproject: (dir, bin, ws, { roots }) => {
+    const findings = [];
+    for (const root of roots) {
+      const r = runJson(dir, bin, ['lint', '--root', join(ws, root)]);
+      if (!r.ok) return { ran: false, note: r.error };
+      // A nested superproject comes back as an absolute path rather than a slug.
+      const where = (s) => (s.startsWith('/') ? relative(ws, s) : `${root}/${s}`);
+      for (const f of findingsOf(r.json)) if (f.level !== 'ok') findings.push(normalize(f, where));
+    }
+    return { ran: true, findings };
+  },
+  superobjective: (dir, bin, ws, { homes }) => {
+    const findings = [];
+    for (const home of homes) {
+      const r = runJson(dir, bin, ['lint', join(ws, home)]);
+      if (!r.ok) return { ran: false, note: r.error };
+      for (const f of findingsOf(r.json)) findings.push(normalize(f, (s) => `${home}/${s}`));
+    }
+    return { ran: true, findings };
+  },
+  // One call per documents home. A home the package cannot read is one finding against that
+  // home, and the other homes are still checked.
+  piece: (dir, bin, ws, { homes }) => {
+    const findings = [];
+    for (const home of homes) {
+      const r = runJson(dir, bin, ['lint', join(ws, home)]);
+      if (!r.ok) { findings.push({ level: 'error', code: 'validator:failed', path: home, message: `piece-md could not check this folder: ${r.error}` }); continue; }
+      for (const f of findingsOf(r.json)) findings.push(normalize(f, (s) => `${home}/${s}`));
+    }
+    return { ran: true, findings };
+  },
+  // document-md takes every documents home in one call and names each finding by its home plus
+  // the document's path under it.
+  document: (dir, bin, ws, { homes }) => {
+    if (!homes.length) return { ran: true, findings: [] };
+    const r = runJson(dir, bin, ['lint', ...homes.map((h) => join(ws, h))]);
+    return r.ok
+      ? { ran: true, findings: findingsOf(r.json).map((f) => normalize({ ...f, path: f.home && f.document ? relative(ws, join(f.home, f.document)) : f.document })) }
+      : { ran: false, note: r.error };
+  },
+  checkpoint: (dir, bin, ws) => {
+    const r = runJson(dir, bin, ['lint', join(ws, 'checkpoints')]);
+    return r.ok ? { ran: true, findings: findingsOf(r.json).map((f) => normalize(f, (s) => `checkpoints/${s}`)) } : { ran: false, note: r.error };
+  },
+  // One hdsop-md run checks the maps and the catalog; each finding says which kind it is about.
+  hdsop: (dir, bin, ws) => {
+    const r = runJson(dir, bin, ['lint', join(ws, 'workflows')]);
+    if (!r.ok) return { ran: false, note: r.error };
+    return { ran: true, findings: findingsOf(r.json).map((f) => ({ ...normalize(f, (s) => `workflows/${s}`), kind: f.kind === 'workflow-catalog' ? 'workflow-catalog' : 'hdsop' })) };
+  },
+  recurrent: (dir, bin, ws) => {
+    const r = runJson(dir, bin, ['lint', join(ws, 'recurrents')]);
+    return r.ok ? { ran: true, findings: findingsOf(r.json).map((f) => normalize({ ...f, path: f.recurrent ?? f.path }, (s) => `recurrents/${s}`)) } : { ran: false, note: r.error };
+  },
+  // tile-app-md finds the apps itself from the workspace, and names each by its absolute path.
+  'tile-app': (dir, bin, ws) => {
+    const r = runJson(dir, bin, ['lint', ws]);
+    return r.ok ? { ran: true, findings: findingsOf(r.json).map((f) => normalize(f, (s) => (s.startsWith('/') ? relative(ws, s) : s))) } : { ran: false, note: r.error };
+  },
+  // A conversation is checked in-process through the package's codec: one process per file
+  // would cost minutes on a workspace that holds thousands.
+  conversation: async (dir, _bin, ws, { records, read }) => {
+    let mod;
+    try { mod = await import(new URL(`file://${join(dir, 'index.mjs')}`)); } catch (e) { return { ran: false, note: e.message }; }
+    if (typeof mod.parseConversationHeader !== 'function' || typeof mod.validateConversation !== 'function') {
+      return { ran: false, note: 'this version exports no parseConversationHeader/validateConversation' };
+    }
+    const findings = [];
+    for (const rel of records) {
+      let parsed;
+      try { parsed = mod.parseConversationHeader(Buffer.from(read(join(ws, rel)))); }
+      catch (e) { findings.push({ level: 'error', code: e.code ?? 'header:unreadable', path: rel, message: e.message }); continue; }
+      const folderId = rel.split('/').at(-2);
+      const diagnostics = parsed.header ? mod.validateConversation(parsed.header, { folderId }) : parsed.diagnostics;
+      for (const d of diagnostics ?? []) {
+        const f = normalize({ level: d.severity ?? 'error', code: d.code, message: `${d.field ? `${d.field}: ` : ''}${d.message ?? ''}` });
+        findings.push({ ...f, path: rel });
+      }
+    }
+    return { ran: true, findings };
+  },
+};

package/src/render.mjs

@@ -0,0 +1,51 @@
+// The check as text a person reads: one row per kind, then the findings that need someone.
+const pad = (s, n) => String(s).padEnd(n);
+const lpad = (s, n) => String(s).padStart(n);
+
+export function renderReport(r, { limit = 40 } = {}) {
+  const lines = [];
+  const width = Math.max(4, ...r.rows.map((x) => x.kind.length));
+  lines.push(`${pad('kind', width)}  ${lpad('records', 7)}  ${lpad('names standard', 14)}  ${lpad('context', 7)}  validated by`);
+  for (const row of r.rows) {
+    const v = row.validator ? `${row.validator}${row.validatorNote ? ` (${row.validatorNote})` : ''}` : `none: ${row.validatorNote}`;
+    lines.push(`${pad(row.kind, width)}  ${lpad(row.records, 7)}  ${lpad(`${row.selfDocumenting}/${row.records}`, 14)}  ${lpad(`${row.contextComplete}/${row.records}`, 7)}  ${v}`);
+  }
+  lines.push('');
+  const errors = r.findings.filter((f) => f.level === 'error' && !f.known);
+  const warns = r.findings.filter((f) => f.level === 'warn');
+  const byCode = (list) => {
+    const m = new Map();
+    for (const f of list) { const k = `${f.kind} ${f.code}`; m.set(k, (m.get(k) ?? 0) + 1); }
+    return [...m].sort((a, b) => b[1] - a[1]);
+  };
+  if (r.known) lines.push(`${r.known} error(s) predate the baseline and are tolerated.`);
+  if (errors.length) {
+    lines.push(`${errors.length} error(s)${r.known != null && r.known ? ' new since the baseline' : ''}:`);
+    for (const [k, n] of byCode(errors)) lines.push(`  ${lpad(n, 5)}  ${k}`);
+    lines.push('');
+    for (const f of errors.slice(0, limit)) lines.push(`  error  ${f.kind}  ${f.code}  ${f.path || '(workspace)'}  ${f.message}`);
+    if (errors.length > limit) lines.push(`  ... and ${errors.length - limit} more (--json lists every one)`);
+  }
+  if (warns.length) {
+    lines.push(`${warns.length} warning(s):`);
+    for (const [k, n] of byCode(warns)) lines.push(`  ${lpad(n, 5)}  ${k}`);
+  }
+  lines.push('');
+  lines.push(r.ok ? 'ok: every record names its standard and passes its package.' : 'not ok: fix the errors above, or run `hypercontext stamp --apply` for the missing standards.');
+  return lines.join('\n');
+}
+
+export function renderStamp(s) {
+  const lines = [s.apply ? 'Stamped:' : 'Would stamp (dry run; --apply writes):'];
+  for (const k of s.kinds) {
+    if (!k.missing) continue;
+    const n = k.changed != null ? `${k.changed} of ${k.missing}` : `${k.missing}`;
+    lines.push(`  ${k.kind}: ${n} via ${k.via}${k.note ? `; ${k.note}` : ''}${k.reasons ? `; skipped ${Object.entries(k.reasons).map(([r, c]) => `${c} (${r})`).join(', ')}` : ''}`);
+    // What the kind's own package said: its count, and each record it would not touch and why.
+    for (const l of k.said ?? []) lines.push(`      ${l}`);
+    for (const l of (k.skippedLines ?? []).slice(0, 10)) lines.push(`      ${l}`);
+    if ((k.skippedLines?.length ?? 0) > 10) lines.push(`      ... and ${k.skippedLines.length - 10} more skipped (--json lists every one)`);
+  }
+  if (lines.length === 1) lines.push('  nothing: every record already names its standard.');
+  return lines.join('\n');
+}