@supersuit/hypercontext 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## 0.2.0
+
+Every kind is now checked by its own package, so `check` reports more findings on the same workspace: a minor version, because it changes what is checked.
+
+- `document` is checked and stamped by `@supersuit/document-md`, `checkpoint` by `@supersuit/checkpoint-md`, `hdsop` and `workflow-catalog` by `@supersuit/hdsop-md` (one run covers both, each finding filed under the kind it is about), `recurrent` by `@supersuit/recurrent-md`, `tile-app` by `@supersuit/tile-app-md`. None of the six raises `validator:missing` any more.
+- This package no longer ships manifests: each kind's comes from its package. A kind with no package and no manifest is listed as missing rather than crashing `check`.
+- `recurrent` and `tile-app` are stamped. A recurrent goes through `recurrent-md migrate`, which moves its body labels into the header as it names the standard; a tile app through `tile-app-md stamp`.
+- `stamp` repeats each package's closing count and every record it skipped, with the reason, so a catalog with no header or a headerless document is named in the report rather than lost.
+- A kind whose package run also checks another (hdsop checks the catalog) runs when only the other kind has records.
+
+## 0.1.0
+
+- The header codec, `versionOf`, `bareStandard` and the byte-preserving `stampStandard` now come from `@supersuit/hypercontext-core`, a dependency at `^0.1.0`; they are re-exported here unchanged.
+- Every manifest an owner ships is checked against core's `validateManifest`: a bad one is `manifest:invalid` (error) in `check`, and `manifests` lists it as invalid, never publishes it, and exits 1.
+- Each kind's package is found by node resolution and then beside this package in the hypercontext repository, so a checkout of that repository needs no `--packages`. `--packages` (or `HYPERCONTEXT_PACKAGES`) now means only that folder.
+- The document manifest's `created` key is `type: string` with a date pattern; `date` is not a type a reader can check.
+
+The first version: one check over a whole workspace.
+
+- `hypercontext check` finds every record of fifteen kinds, judges the property they share (each names the standard it follows, `self-doc:missing` when not), counts the shared context keys, and runs each kind's own package (self-md, friend-md, group-md, superprojects, superobjective, piece-md, transcript-md). One row per kind. A kind no package checks yet is a warning saying so.
+- `hypercontext stamp` is the backfill: each packaged kind through its own package's command, the rest by one byte-preserving edit. Conversations go through `transcript-md stamp-standard`, which takes its lock and checks each file's hash. Never gives a headerless file a header, never touches a recurrent or tile app, never follows a link.
+- `hypercontext baseline` and `check --baseline`: known debt is tolerated, new debt fails, and the baseline only shrinks unless `--accept`.
+- `hypercontext kinds` lists every kind, its standard and its package.
+- Standards are versioned: a record names `https://hypercontext.wiki/standards/<kind>/v<N>`. The unversioned link is `self-doc:missing` and `stamp` upgrades it; a version the owner does not implement is `self-doc:version`. The implemented versions are read from the manifests the owner ships.
+- Manifests (docs/STANDARDS.md): this package ships them for the six kinds no package owns; `hypercontext manifests --out <dir>` copies every kind's from its owner for a site to publish; `check --online` refuses a standard that does not open (`standard:unreachable`) or whose published manifest is not its owner's (`standard:drift`).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SupersuitUp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# @supersuit/hypercontext
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+*This package lives in the [hypercontext repository](https://github.com/SupersuitUp/hypercontext/tree/main/packages/hypercontext), with every other record standard; issues and changes go there.*
+
+One check over a whole workspace, for every kind of record in it.
+
+A hypercontext workspace keeps a life or a company as plain files: a person in `people/<slug>/friend.md`, a project in `superprojects/<slug>/`, a conversation in `meeting-transcripts/<id>/transcript.md`, and so on. Each kind has its own standard and its own package that checks it. This package is the umbrella: it finds every record of every kind, asks each kind's package to check its own, and checks the one property they all share.
+
+## The shared property: every record names its standard
+
+**A record explains itself to a stranger or a fresh agent with no other context.** It does that by carrying, in its header, the address of the rules it was written to:
+
+```yaml
+---
+kind: friend
+standard: "https://hypercontext.wiki/standards/friend/v1"
+id: maya-lin
+...
+```
+
+The link names a **version**. The page at `/v1` never changes meaning, so the record says which rules it was written to; `/standards/friend` is the latest page, for people. A record without the line, or with the unversioned link written before versions, is not self-documenting however complete the rest of it is: refused as `self-doc:missing`. A version of its own standard that the installed checker does not implement is `self-doc:version`.
+
+Every version also has a **manifest**, `/standards/<kind>/v<N>.json`: the same rules as data (required header keys, every code its checker can report with what it means and how to fix it, the exact commands), so an agent can validate a record with nothing installed. The package that owns a kind ships its manifest, and a test there proves the manifest names exactly the codes its lint reports. [docs/STANDARDS.md](docs/STANDARDS.md) is the format. The shared context keys (`id`, `summary`, `read_when`, `as_of`, `keep`) are counted beside it and reported per kind; whether an empty one is a defect is each kind's own package's call.
+
+This package defines no record type. A kind's shape belongs to its package. The list below only says where each kind lives and whom to ask.
+
+| kind | standard | checked by |
+|---|---|---|
+| self | /standards/self | @supersuit/self-md |
+| friend | /standards/friend | @supersuit/friend-md |
+| group | /standards/group | @supersuit/group-md |
+| superproject, state, atomic-action-map | /standards/superproject, /state, /atomic-action-map | @supersuit/superprojects |
+| superobjective | /standards/superobjective | @supersuit/superobjective |
+| piece | /standards/piece | @supersuit/piece-md |
+| conversation | /standards/conversation | @supersuit/transcript-md |
+| document | /standards/document | @supersuit/document-md |
+| checkpoint | /standards/checkpoint | @supersuit/checkpoint-md |
+| hdsop, workflow-catalog | /standards/hdsop, /workflow-catalog | @supersuit/hdsop-md |
+| recurrent | /standards/recurrent | @supersuit/recurrent-md |
+| tile-app | /standards/tile-app | @supersuit/tile-app-md |
+
+Every kind has a package. A kind added later without one would still be checked for the shared property, with a `validator:missing` warning saying nothing checks its shape.
+
+Every standard lives at `https://hypercontext.wiki/standards/<kind>/v<N>`. `hypercontext kinds` prints the list.
+
+## Use
+
+```sh
+npx @supersuit/hypercontext check .          # every kind, one row each; exit 1 on any error
+npx @supersuit/hypercontext stamp .          # what the backfill would add (dry run)
+npx @supersuit/hypercontext stamp . --apply  # add the missing standard: to existing records, or upgrade an unversioned one
+npx @supersuit/hypercontext check . --online # also prove every standard the records name opens, onto its owner's manifest
+npx @supersuit/hypercontext manifests --out static/standards   # every kind's manifest, copied from its owner, for a site to publish
+```
+
+### Airtight, both ways
+
+`check --online` fetches every distinct standard the workspace's records name. A page that does not answer is `standard:unreachable`; a page whose `.json` manifest differs from the one the installed owner ships is `standard:drift`. So every link a record carries opens, onto the rules the checker actually enforced.
+
+```
+kind               records  names standard  context  validated by
+self                     1             1/1      1/1  @supersuit/self-md@0.2.0
+friend                 833         833/833    5/833  @supersuit/friend-md@0.3.0
+document               663         472/663  663/663  @supersuit/document-md@0.1.0
+...
+```
+
+### The backfill goes through each kind's own package
+
+`stamp` never writes a packaged kind's records itself. It runs the backfill that kind's package ships (`friend-md stamp`, `group-md migrate`, `superprojects migrate --stamp-standard`, `self-md stamp-standard`, `transcript-md stamp-standard`, `piece-md stamp`, `document-md stamp`, `checkpoint-md stamp`, `hdsop-md stamp`, `recurrent-md migrate`, `tile-app-md stamp`), because the package knows its own key order and everything else its writers keep. The report repeats each package's closing count and every record it skipped, with its reason (a document with no header, a workflow catalog with none). A kind with no package would be stamped here, by one byte-preserving edit: the line goes directly after `kind:` (or first), or an unversioned link of the same kind is upgraded where it stands, and every other byte of the file, line endings included, is unchanged. A file with no header is never given one; it is reported, because a record with no header needs writing, not stamping. A file that already names a standard, right or wrong, is left alone and the wrong one is reported.
+
+A recurrent is stamped by `recurrent-md migrate`, which moves its bold body labels into the header in the same edit, so no field is ever kept twice. A tile app is stamped by `tile-app-md stamp`, a textual edit to `app.json` that adds `"standard"` as its first key. A kind marked `stampable: false` (none is, since 0.2.0) is never touched, and the report says why.
+
+Linked files are never records here. A document symlinked in from another repository belongs to that repository; counting it would count it twice, and stamping it would write into a tree this check was never pointed at.
+
+### The ratchet
+
+A workspace adopting the standard holds thousands of records written before it, and a check that stays red until all of them are fixed is a check nobody runs. So:
+
+```sh
+hypercontext baseline . --write hypercontext-baseline.json   # today's errors become known debt
+hypercontext check . --baseline hypercontext-baseline.json   # fails only on an error the baseline does not hold
+```
+
+Rewriting the baseline drops what was fixed and refuses anything new unless you pass `--accept`, so it only ever shrinks by accident.
+
+### Where the packages come from
+
+Each kind's package is found by normal resolution, then beside this package in the hypercontext repository (`packages/<folder>`), so a checkout of that repository needs no flag. `--packages <dir>` (or `HYPERCONTEXT_PACKAGES`) names a folder of checkouts, one per folder name, to use instead, and then only that folder is looked in. A package that cannot be found is a warning naming it, never a silent pass; a package that runs and prints nothing usable is an error.
+
+Every manifest an owner ships is checked against `@supersuit/hypercontext-core`'s `validateManifest`. A bad one is `manifest:invalid` (error) in `check`, and `manifests` lists it as invalid and never publishes it.
+
+## Exit codes
+
+0 clean, 1 findings (or, with `--baseline`, new findings), 2 usage.
+
+## Library
+
+```js
+import { check, stamp, KINDS, judge, stampStandard } from '@supersuit/hypercontext';
+const report = await check('/path/to/workspace');
+```
+
+MIT.

package/bin/hypercontext.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+import { resolve, join } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { check, stamp, KINDS, readBaseline, applyBaseline, writeBaseline, renderReport, renderStamp, exportManifests } from '../src/index.mjs';
+
+const HELP = `hypercontext: one check over a whole workspace, for every kind of record in it
+
+Usage:
+  hypercontext check [<workspace>] [--baseline <file>] [--kind <k>[,<k>]] [--packages <dir>] [--no-shapes] [--online] [--json]
+      Every record names the version of the standard it follows (the hypercontext property), and
+      every kind's own package passes it. One row per kind. --online also proves every standard
+      the records name opens, and that its published manifest is the one its owner ships. Exit 1
+      on any error, or with --baseline on any error the baseline does not already hold.
+  hypercontext stamp [<workspace>] [--kind <k>[,<k>]] [--packages <dir>] [--apply] [--json]
+      Add the missing standard: to existing records, each kind through its own package's
+      backfill. A dry run unless --apply. Never commits.
+  hypercontext baseline [<workspace>] --write <file> [--accept] [--packages <dir>]
+      Record today's errors as known debt. Without --accept it only ever shrinks.
+  hypercontext kinds [--json]
+      Every kind, its standard and the package that checks it.
+  hypercontext manifests --out <dir> [--packages <dir>]
+      Copy every kind's manifest from the package that owns it into <dir>/<kind>/v<N>.json, plus
+      <dir>/index.json, for a site to publish unchanged. Exit 1 when an owner is not installed or ships
+      a manifest that is not valid (it is listed, never written).
+  hypercontext --help | --version
+
+<workspace> defaults to the current folder. Each kind's package is found by node resolution, then
+beside this package in the hypercontext repository. --packages names a folder of package checkouts
+to use instead, and only those (also HYPERCONTEXT_PACKAGES).
+
+Exit codes: 0 clean, 1 findings, 2 usage.`;
+
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+const flag = (n) => argv.includes(n);
+const opt = (n) => { const i = argv.indexOf(n); return i >= 0 ? argv[i + 1] : undefined; };
+const valued = new Set(['--baseline', '--kind', '--packages', '--write', '--out']);
+const positional = argv.slice(1).filter((a, i, all) => !a.startsWith('--') && !valued.has(all[i - 1]));
+const ws = resolve(positional[0] ?? '.');
+const json = flag('--json');
+const kinds = opt('--kind')?.split(',').map((s) => s.trim()).filter(Boolean);
+const packagesDir = opt('--packages') ? resolve(opt('--packages')) : undefined;
+
+const usage = (m) => { process.stderr.write(`${m}\nRun hypercontext --help for usage.\n`); process.exit(2); };
+// Write, then exit once the pipe has taken all of it. process.exit() straight after a large
+// write to a pipe cuts the output off mid-stream, and a cut-off --json is a parse error for
+// whoever is reading it.
+const finish = (text, code) => process.stdout.write(text, () => process.exit(code));
+
+if (!cmd || cmd === '--help' || cmd === '-h') { process.stdout.write(HELP + '\n'); process.exit(cmd ? 0 : 2); }
+if (cmd === '--version') { process.stdout.write(JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version + '\n'); process.exit(0); }
+if (kinds) for (const k of kinds) if (!KINDS.some((x) => x.kind === k)) usage(`no such kind: ${k} (hypercontext kinds lists them)`);
+
+if (cmd === 'kinds') {
+  const rows = KINDS.map((k) => ({ kind: k.kind, standard: k.standard, package: k.pkg?.name ?? null }));
+  finish(json ? JSON.stringify(rows, null, 2) + '\n' : rows.map((r) => `${r.kind.padEnd(18)} ${r.standard}  ${r.package ?? '(no package yet)'}`).join('\n') + '\n', 0);
+}
+
+if (cmd === 'check') {
+  const baseFile = opt('--baseline') ? resolve(opt('--baseline')) : undefined;
+  let baseline = null;
+  try { baseline = readBaseline(baseFile); } catch (e) { usage(`cannot read the baseline ${baseFile}: ${e.message}`); }
+  if (baseFile && !baseline) usage(`no baseline at ${baseFile}; write one with hypercontext baseline --write`);
+  const r = applyBaseline(await check(ws, { kinds, packagesDir, shapes: !flag('--no-shapes'), online: flag('--online') }), baseline);
+  finish(json ? JSON.stringify(r, null, 2) + '\n' : renderReport(r) + '\n', r.ok ? 0 : 1);
+}
+
+if (cmd === 'stamp') {
+  const s = await stamp(ws, { kinds, apply: flag('--apply'), packagesDir });
+  finish(json ? JSON.stringify(s, null, 2) + '\n' : renderStamp(s) + '\n', 0);
+}
+
+if (cmd === 'baseline') {
+  const file = opt('--write');
+  if (!file) usage('baseline needs --write <file>');
+  const r = await check(ws, { kinds, packagesDir });
+  const w = writeBaseline(resolve(file), r, { accept: flag('--accept') });
+  finish(json ? JSON.stringify(w) + '\n' : `baseline: ${w.count} known error(s) written to ${file}; ${w.dropped} fixed since the last one${w.refused ? `; ${w.refused} new error(s) NOT accepted (pass --accept to record them)` : ''}\n`, w.refused ? 1 : 0);
+}
+
+if (cmd === 'manifests') {
+  const out = opt('--out');
+  if (!out) usage('manifests needs --out <dir>');
+  const index = exportManifests(resolve(out), { packagesDir });
+  const bad = index.filter((x) => x.missing || x.invalid);
+  const line = (x) => (x.missing ? `MISSING: ${x.owner} is not installed` : x.invalid ? `INVALID: ${x.invalid.join(' | ')}` : x.versions.join(' '));
+  finish(json ? JSON.stringify(index, null, 2) + '\n' : index.map((x) => `${x.kind.padEnd(18)} ${line(x)}`).join('\n') + '\n', bad.length ? 1 : 0);
+}
+
+// finish() exits only once the output has drained, so nothing below may run after a command.
+if (!['kinds', 'check', 'stamp', 'baseline', 'manifests'].includes(cmd)) usage(`unknown command: ${cmd}`);

package/docs/STANDARDS.md

@@ -0,0 +1,86 @@
+# Standards: versioned links, and the manifest behind each one
+
+Gary, 2026-10-20: *"I'm not really tied to any past way of engineering the standards and I want the best possible airtight, validatable, hyperlinked hypercontext thing."*
+
+## 1. The link names the version
+
+Every record's header carries the version of the standard it was written to:
+
+```yaml
+standard: "https://hypercontext.wiki/standards/friend/v1"
+```
+
+- `https://hypercontext.wiki/standards/<kind>/v<N>` is one version of one standard. **Its meaning never changes once published.** A correction that changes what a valid record is becomes `v<N+1>`; a typo fix to the prose does not.
+- `https://hypercontext.wiki/standards/<kind>` is the latest version, and lists every version with what changed.
+- A record names a version, never the bare `/standards/<kind>` URL. A record that does is a record written before versions existed: still that kind, no longer self-documenting, and its package's stamp upgrades it in place.
+
+This is [every link says which version it meant](https://hypercontext.wiki/every-link-says-which-version-it-meant) applied to the link every record carries: a standard is a link to what a thing *said*, so it is pinned.
+
+## 2. Every version has a manifest
+
+Beside each version page is its machine-readable twin, `https://hypercontext.wiki/standards/<kind>/v<N>.json`. It says, as data, everything a reader needs to validate a record without installing anything, and everything a checker needs to prove the link it trusts says what it enforces.
+
+```json
+{
+  "manifest_version": 1,
+  "standard": "https://hypercontext.wiki/standards/friend/v1",
+  "kind": "friend",
+  "version": 1,
+  "title": "A person",
+  "status": "current",
+  "superseded_by": null,
+  "latest": "https://hypercontext.wiki/standards/friend",
+  "record": { "path": "people/<slug>/friend.md", "format": "md" },
+  "header": {
+    "required": ["kind", "standard", "id", "name", "summary", "read_when", "as_of", "keep"],
+    "keys": {
+      "kind": { "const": "friend" },
+      "standard": { "const": "https://hypercontext.wiki/standards/friend/v1" },
+      "keep": { "enum": ["keep", "home", "share"] }
+    }
+  },
+  "validator": {
+    "package": "@supersuit/friend-md",
+    "implements_since": "0.3.0",
+    "check": "npx -y @supersuit/friend-md@^0.3.0 lint --people people --json",
+    "backfill": "npx -y @supersuit/friend-md@^0.3.0 stamp --people people --apply"
+  },
+  "codes": [
+    { "code": "self-doc:missing", "level": "error", "means": "the record names no standard, an older one, or another kind's", "fix": "friend-md stamp --people people --apply" }
+  ],
+  "umbrella": "npx -y @supersuit/hypercontext check <workspace>"
+}
+```
+
+| key | meaning |
+|---|---|
+| `manifest_version` | `1`, the shape of this file |
+| `standard` | this version's URL; equals the `standard:` a record carries |
+| `kind`, `version` | the record kind and this version's number |
+| `title` | what a person calls the record |
+| `status`, `superseded_by` | `current` or `superseded`, and the URL that replaced it |
+| `latest` | the unversioned page that always shows the newest version |
+| `record.path`, `record.format` | where records of this kind live, and `md` (YAML header) or `json` |
+| `header.required`, `header.keys` | the header keys a record must carry, and the constraints a reader can check without a package, with JSON Schema's meaning (`const`, `enum`, `pattern`, `type`, `items`, `minLength`, `maxLength`, `minItems`, `maxItems`); `@supersuit/hypercontext-core`'s `validateManifest` refuses any other |
+| `validator` | the package that checks the full shape, the first version of it that implements this standard version, and the exact commands; `null` when no package exists yet |
+| `checked_by` | only when `validator` is `null`: the umbrella command that checks the shared property, the backfill when one may run, and a `note` saying what is not checked |
+| `codes` | **every** finding the validator can report, with its level, what it means and how to fix it. Equal to the package's own code table, which a test in the package proves |
+| `umbrella` | the one command that checks every kind |
+
+## 3. One source, no copies that drift
+
+**The package owns the manifest.** Each record package ships `standards/<kind>/v<N>.json` in its tarball, exports it, and its test suite asserts that the manifest's `codes` are exactly the codes its lint can emit and that `standard` equals its exported `STANDARD`. The wiki publishes the package's file unchanged. A kind with no package yet gets its manifest from `@supersuit/hypercontext`, with `validator: null`.
+
+## 4. What the checks prove
+
+`hypercontext check` refuses, as `self-doc:missing`:
+
+- a record naming no standard;
+- a record naming the bare, unversioned URL of its kind (written before versions; `stamp` upgrades it);
+- a record naming another kind's standard;
+
+and, as `self-doc:version`, a record naming a version of its kind that the installed validator does not implement (from the future, or retired without a migration).
+
+It also refuses, as `manifest:invalid`, any manifest an installed owner ships that does not have the shape in section 2 (checked by `validateManifest` in `@supersuit/hypercontext-core`), or whose `kind` and `version` disagree with its path. `hypercontext manifests` never exports such a file.
+
+`hypercontext check --online` also fetches every distinct standard a workspace's records name, and refuses (`standard:unreachable`) any that does not answer, and (`standard:drift`) any whose published manifest differs from the one the installed package ships. That is the hyperlink half of airtight: every link a record carries opens, and opens onto the rules the checker actually enforced.

package/package.json

@@ -1,6 +1,19 @@
 {
   "name": "@supersuit/hypercontext",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "One check over a whole workspace: every record names the standard it follows, and every kind of record passes its own package's checks.",
+  "keywords": ["hypercontext", "records", "markdown", "frontmatter", "lint", "self-documenting", "agents", "supersuit"],
+  "type": "module",
+  "bin": { "hypercontext": "bin/hypercontext.mjs" },
+  "exports": { ".": "./src/index.mjs", "./package.json": "./package.json" },
+  "files": ["bin/", "src/", "docs/", "README.md", "CHANGELOG.md", "LICENSE"],
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "mutation-check": "node scripts/mutation-check.mjs"
+  },
+  "engines": { "node": ">=20" },
+  "license": "MIT",
+  "publishConfig": { "access": "public" },
+  "repository": { "type": "git", "url": "git+https://github.com/SupersuitUp/hypercontext.git", "directory": "packages/hypercontext" },
+  "dependencies": { "@supersuit/hypercontext-core": "^0.1.0" }
+}

package/src/baseline.mjs

@@ -0,0 +1,49 @@
+// The ratchet: debt a workspace already had is recorded and tolerated; new debt fails.
+//
+// A workspace adopting a standard holds thousands of records written before it, and a check that
+// is red until every one is fixed is a check nobody runs. So the baseline lists the error
+// findings that existed when it was written, and `check --baseline` fails only on an error the
+// list does not hold. The list only ever shrinks by itself: a finding that is gone is dropped the
+// next time the baseline is written, and writing it never adds an error that a check had already
+// refused, unless the person writing it says so with --accept.
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+
+export const keyOf = (f) => `${f.kind}|${f.code}|${f.path}`;
+
+export function readBaseline(file) {
+  if (!file || !existsSync(file)) return null;
+  const j = JSON.parse(readFileSync(file, 'utf8'));
+  return { file, known: new Set(Array.isArray(j.known) ? j.known : []), written: j.written ?? '' };
+}
+
+/** Split a report's errors into the ones the baseline already knew and the new ones. */
+export function applyBaseline(report, baseline) {
+  if (!baseline) return { ...report, known: 0, fresh: report.errors };
+  let known = 0;
+  const findings = report.findings.map((f) => {
+    if (f.level !== 'error') return f;
+    if (baseline.known.has(keyOf(f))) { known++; return { ...f, known: true }; }
+    return f;
+  });
+  const fresh = report.errors - known;
+  return { ...report, findings, known, fresh, ok: fresh === 0 };
+}
+
+/**
+ * Write the baseline from a report. With an existing baseline and no `accept`, it keeps only the
+ * errors still present that it already knew, so new debt cannot be written in by accident.
+ */
+export function writeBaseline(file, report, { accept = false, today = new Date().toISOString().slice(0, 10) } = {}) {
+  const prior = readBaseline(file);
+  // One entry per record and code: two findings on one record are one piece of debt.
+  const now = [...new Set(report.findings.filter((f) => f.level === 'error').map(keyOf))];
+  const known = prior && !accept ? now.filter((k) => prior.known.has(k)) : now;
+  const sorted = [...known].sort();
+  writeFileSync(file, JSON.stringify({
+    about: 'Error findings @supersuit/hypercontext tolerates in this workspace because they predate the check. Each fixed one drops out the next time this is written; a new one fails the check. https://hypercontext.wiki/standards',
+    written: today,
+    count: sorted.length,
+    known: sorted,
+  }, null, 2) + '\n');
+  return { count: sorted.length, dropped: prior ? [...prior.known].filter((k) => !sorted.includes(k)).length : 0, refused: now.length - sorted.length };
+}

package/src/check.mjs

@@ -0,0 +1,114 @@
+// One check over a whole workspace: every kind, the shared property, and each kind's own package.
+//
+// The report is a row per kind (how many records, how many self-documenting, how many carry the
+// shared context, what checked the shape) plus the findings. An error fails the check. A kind
+// with no package is a warning, once, rather than silence: "nothing checks this" is the finding
+// that a check reporting only on what it checks can never make.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { KINDS } from './kinds.mjs';
+import { findRecords, legacyRecords, superprojectRoots, documentHomes, fsDefault } from './find.mjs';
+import { judge, acceptedFor, standardOf, CODE, VERSION_CODE } from './selfdoc.mjs';
+import { implementedVersions, checkOnline, manifestFindings } from './manifest.mjs';
+import { resolvePackage, packageVersion, LINTS } from './packages.mjs';
+
+// Codes a package reports for the property this package judges itself. Dropped from the package's
+// findings so one missing field is one finding, counted once, in one place.
+const SELF_DOC_CODES = new Set([CODE, VERSION_CODE, 'standard:missing', 'standard:value']);
+
+const STANDARDS = Object.fromEntries(KINDS.map((k) => [k.kind, k.standard]));
+
+/**
+ * @param {string} workspace absolute path
+ * @param {object} [opts]
+ * @param {string[]} [opts.kinds] limit to these kinds
+ * @param {string} [opts.packagesDir] a folder of sibling package checkouts (see packages.mjs)
+ * @param {boolean} [opts.shapes=true] false skips the packages and judges only the shared property
+ * @param {boolean} [opts.online=false] also prove every standard the records name is live and matches its owner's manifest
+ * @param {Function} [opts.fetch] injected fetch for tests
+ * @param {object} [opts.fs] injected filesystem for tests
+ * @param {object[]} [opts.registry] the kinds to judge, KINDS unless a test supplies its own
+ */
+export async function check(workspace, { kinds, packagesDir, shapes = true, online = false, fetch, fs = fsDefault, read = (p) => readFileSync(p, 'utf8'), registry = KINDS } = {}) {
+  const wanted = registry.filter((k) => !kinds || kinds.includes(k.kind));
+  const rows = [];
+  const findings = [];
+  const seen = new Map(); // kind -> Set of standard URLs its records name
+
+  for (const k of wanted) {
+    const records = findRecords(workspace, k.kind, fs);
+    let selfDoc = 0, context = 0;
+    const versions = implementedVersions(k, { packagesDir });
+    findings.push(...manifestFindings(k, { packagesDir }));
+    const named = new Set();
+    seen.set(k.kind, named);
+    for (const rel of records) {
+      let text;
+      try { text = read(join(workspace, rel)); } catch { findings.push({ kind: k.kind, level: 'error', code: 'record:unreadable', path: rel, message: 'cannot be read' }); continue; }
+      const got = standardOf(text, k.format);
+      const verdict = judge(text, k, { versions, alsoAccept: acceptedFor(k.kind, got.data, STANDARDS) });
+      if (got.standard) named.add(got.standard);
+      if (verdict.selfDocumenting) selfDoc++;
+      else findings.push({ kind: k.kind, level: 'error', code: verdict.code, path: rel, message: verdict.problem });
+      if (k.context.length === 0 || verdict.contextComplete) context++;
+    }
+    const row = { kind: k.kind, label: k.label, standard: k.standard, records: records.length, selfDocumenting: selfDoc, contextComplete: context, validator: null, validatorNote: '' };
+
+    if (!k.pkg) {
+      row.validatorNote = 'no package checks this shape yet';
+      if (records.length) findings.push({ kind: k.kind, level: 'warn', code: 'validator:missing', path: '', message: `${records.length} ${k.kind} record(s), and no package checks their shape; only the shared property is checked` });
+    } else if (!shapes) {
+      row.validatorNote = 'shapes skipped';
+    } else if (k.sharesLint) {
+      row.validator = k.pkg.name;
+      row.validatorNote = `checked with ${k.sharesLint}`;
+    } else if (records.length === 0 && !registry.some((x) => x.sharesLint === k.kind && findRecords(workspace, x.kind, fs).length)) {
+      // A kind whose run also checks another (hdsop checks the catalog) still runs when only the
+      // other kind has records.
+      row.validator = k.pkg.name;
+      row.validatorNote = 'nothing to check';
+    } else {
+      const dir = resolvePackage(k.pkg, { packagesDir });
+      if (!dir) {
+        row.validatorNote = `${k.pkg.name} is not installed`;
+        findings.push({ kind: k.kind, level: 'warn', code: 'validator:absent', path: '', message: `${k.pkg.name} checks ${k.kind} records and is not installed here; install it, or pass --packages <dir of checkouts>` });
+      } else {
+        const ctx = {
+          roots: superprojectRoots(workspace, fs),
+          homes: k.kind === 'superobjective'
+            ? [...new Set(records.map((r) => r.split('/').slice(0, -2).join('/')))].filter(Boolean)
+            : documentHomes(workspace, fs),
+          records,
+          read: (p) => readFileSync(p),
+        };
+        const res = await LINTS[k.kind](dir, k.pkg.bin, workspace, ctx);
+        row.validator = `${k.pkg.name}@${packageVersion(dir)}`;
+        if (!res.ran) {
+          row.validatorNote = `could not run: ${res.note}`;
+          findings.push({ kind: k.kind, level: 'error', code: 'validator:failed', path: '', message: `${k.pkg.name} did not run: ${res.note}` });
+        } else {
+          for (const f of res.findings) {
+            if (SELF_DOC_CODES.has(f.code) || f.level === 'ok' || f.level === 'info') continue;
+            findings.push({ kind: k.kind, ...f });
+          }
+        }
+      }
+    }
+    rows.push(row);
+  }
+
+  for (const l of legacyRecords(workspace, fs)) {
+    if (kinds && !kinds.includes(l.kind)) continue;
+    findings.push({ kind: l.kind, level: 'warn', code: 'record:legacy-shape', path: l.path, message: `a ${l.kind} kept in a shape its standard retired; its package's migrate moves it` });
+  }
+
+  if (online) {
+    // Only this workspace's own kinds' URLs: a document naming the piece standard is checked as a piece.
+    for (const [kind, urls] of seen) for (const u of [...urls]) if (!u.startsWith(`https://hypercontext.wiki/standards/${kind}`)) urls.delete(u);
+    findings.push(...await checkOnline(seen, { fetch, packagesDir }));
+  }
+
+  const errors = findings.filter((f) => f.level === 'error').length;
+  const warnings = findings.filter((f) => f.level === 'warn').length;
+  return { workspace, ok: errors === 0, errors, warnings, rows, findings };
+}