@panaversity/ksor 0.0.50 → 0.0.52

package/templates/scaffold/system/site/components/governance.tsx

@@ -4,6 +4,8 @@ import { DocumentActions } from "@/components/document-actions";
 import { Clock } from "lucide-react";
 import type { ReactElement } from "react";
 
+import { displayActor } from "@/lib/actor-display";
+import { peopleBook } from "@/lib/people";
 import {
   badgeAddsToStatus,
   badgeText,
@@ -257,7 +259,7 @@ export function GovernanceMeta({
             <Chip text={trust.tier} />
             {trust.by === null ? null : (
               <span className="font-normal text-fd-muted-foreground">
-                {trust.by}
+                {displayActor(trust.by, peopleBook())}
                 {trust.at === null ? null : <> · {day(trust.at)}</>}
               </span>
             )}
@@ -286,7 +288,7 @@ export function GovernanceMeta({
           Links keep full strength: `Replaces` points at the document this one
           superseded, and that is an action rather than a fact. */}
       <dl className="mt-2.5 flex flex-wrap items-baseline gap-x-8 gap-y-2.5 empty:mt-0 [&_a]:text-fd-foreground [&_dd]:font-normal [&_dd]:text-fd-muted-foreground">
-        {owner === null ? null : <Fact label="Owner">{owner}</Fact>}
+        {owner === null ? null : <Fact label="Owner">{displayActor(owner, peopleBook())}</Fact>}
         {/* Who let this into the record. `ksor.approval` is what makes a `stable`
           document stable at all (record spec §2.2), so a page that showed the
           word and not the signature would be publishing the claim without its
@@ -294,7 +296,7 @@ export function GovernanceMeta({
         {approval === null ? null : (
           <Fact label="Approved">
             <>
-              {approval.by} · {day(approval.at)}
+              {displayActor(approval.by, peopleBook())} · {day(approval.at)}
             </>
           </Fact>
         )}
@@ -307,7 +309,7 @@ export function GovernanceMeta({
         {deprecated === null ? null : (
           <Fact label="Withdrawn">
             <>
-              {deprecated.by} · {day(deprecated.at)}
+              {displayActor(deprecated.by, peopleBook())} · {day(deprecated.at)}
             </>
           </Fact>
         )}

package/templates/scaffold/system/site/lib/actor-display.ts

@@ -0,0 +1,53 @@
+/**
+ * Turn a stored actor identifier into the string the page prints.
+ *
+ * KSoR stores actors as `human:<handle>`, `process:<id>`, `team:<id>` or
+ * `<producer>/<version>`. Those forms are right for machines — the checker
+ * parses them, `.ksor/governance.yaml` lists actors by them, and the whole
+ * authority model depends on them — but a public-facing page shouldn't lead
+ * with a slug. This module bridges the two.
+ *
+ * ONE-WAY RULE. If `.ksor/people.yaml` maps this exact identifier to a name, we
+ * print `Human: Bashir Aziz`. If it does not, we print the identifier unchanged
+ * (`human:bashiraziz`, `ksor-starter/0.0.47`). No convention-based splitting,
+ * no camelCase / kebab-case guessing, and no derivation of a handle from a
+ * name: an owner is the only source of a display name.
+ *
+ * A producer actor (`<producer>/<version>`) has no `<kind>:` prefix and no
+ * natural name to look up, so it passes through unchanged — which is correct:
+ * a tool that approved a document should be named plainly, not humanised.
+ *
+ * NO IMPORTS: a leaf, like `lifecycle-rule.ts`. The phone book is handed in by
+ * the caller rather than reached for, so the rule can be exercised without a
+ * record on disk — and so nothing pulls a filesystem read in behind it.
+ */
+
+/** The prefixes KSoR's actor grammar defines, in the case the site prints. */
+const KIND_LABELS: Record<string, string> = {
+  human: "Human",
+  process: "Process",
+  team: "Team",
+};
+
+/**
+ * The display form of an actor. An actor that does not appear in
+ * `.ksor/people.yaml` renders exactly as stored, so nothing regresses on a
+ * record that has declared no names — which is every record until an owner
+ * says otherwise.
+ */
+export function displayActor(actor: string, people: ReadonlyMap<string, string>): string {
+  const colonAt = actor.indexOf(":");
+  if (colonAt === -1) {
+    // No `<kind>:` prefix — this is a producer like `ksor-starter/0.0.47`.
+    // Print it unchanged: humanising a tool's identifier would misread.
+    return actor;
+  }
+  // Looked up by the WHOLE identifier, not the bare handle: `human:ops` and
+  // `team:ops` are different actors, and a phone book keyed on `ops` would
+  // print one of them under the other's name.
+  const name = people.get(actor) ?? null;
+  if (name === null) return actor;
+  const kind = actor.slice(0, colonAt);
+  const kindLabel = KIND_LABELS[kind] ?? kind.charAt(0).toUpperCase() + kind.slice(1);
+  return `${kindLabel}: ${name}`;
+}

package/templates/scaffold/system/site/lib/people.ts

@@ -0,0 +1,82 @@
+/**
+ * Natural names for the actors this record cites — the site's phone book.
+ *
+ * A MAP keyed by the actor as stored (`human:bashiraziz`, `team:legal-ops`),
+ * not a list of names a handle is derived from. The derivation was the defect:
+ * `name.replace(/\s+/g, "").toLowerCase()` can only ever match a handle that
+ * IS somebody's squashed full name, so `human:ciso`, `human:audit-lead` and
+ * `human:mjs` — most of the actors in a real record — had no expressible name
+ * at all. It also collided: "Bashir Aziz" and "Bashira Ziz" both derive
+ * `bashiraziz`, which would print one person's name on the other's governance
+ * act. A map has neither problem, and duplicate keys are refused by the parser
+ * rather than resolved by whichever came last.
+ *
+ * ONE-WAY. The identifier is what the record stores, cites and checks against
+ * the policy; this is only what a page prints. Nothing reads a name back into
+ * an actor, and no authority follows from appearing here — which is why this is
+ * a file of its own and not a block in `.ksor/governance.yaml`: that file is
+ * the root of authority, its key set is closed on purpose, and its digest is
+ * hashed into `build.lock.json`, so correcting the spelling of someone's name
+ * there would refuse the next site build as `ksor-lock-stale`.
+ *
+ * Read from the project root rather than the process's cwd: `next build` runs
+ * in `system/site`, so a cwd-relative path found nothing and the feature was
+ * inert in exactly the builds that publish.
+ *
+ * Read AT USE and memoised, not at module load. A module-load `readFileSync`
+ * makes importing this module a filesystem act — it runs wherever the module is
+ * pulled in, including from a test that wants nothing but the display rule, and
+ * it fixes the answer before anything has had a chance to say where the record
+ * is. That is the same defect the env-tuning knobs had (#149/#194), one file
+ * over.
+ */
+
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+import { parseAllDocuments } from "yaml";
+
+import { projectRoot } from "./shared";
+
+const PEOPLE_YAML = path.join(projectRoot, ".ksor", "people.yaml");
+
+function loadPeople(): ReadonlyMap<string, string> {
+  let text: string;
+  try {
+    text = readFileSync(PEOPLE_YAML, "utf8");
+  } catch {
+    // Optional: its absence means "no natural names declared".
+    return new Map();
+  }
+  try {
+    const docs = parseAllDocuments(text.replace(/^/, ""), {
+      schema: "core",
+      uniqueKeys: true,
+      logLevel: "silent",
+    });
+    const value: unknown = docs[0]?.toJS();
+    if (typeof value !== "object" || value === null) return new Map();
+    const table = (value as { people?: unknown }).people;
+    if (typeof table !== "object" || table === null || Array.isArray(table)) return new Map();
+    const out = new Map<string, string>();
+    for (const [actor, name] of Object.entries(table as Record<string, unknown>)) {
+      // A blank value is an entry someone started and left; printing "" would
+      // erase the identifier rather than replace it.
+      if (typeof name === "string" && name.trim() !== "") out.set(actor.trim(), name.trim());
+    }
+    return out;
+  } catch {
+    return new Map();
+  }
+}
+
+let cached: ReadonlyMap<string, string> | null = null;
+
+/**
+ * What this record has declared. Memoised per process: the file is authored,
+ * not runtime state, and a static build renders many pages from one read.
+ */
+export function peopleBook(): ReadonlyMap<string, string> {
+  cached ??= loadPeople();
+  return cached;
+}

package/templates/scaffold/system/site/lib/record-href.ts

@@ -5,7 +5,7 @@
  * bundle-absolute (`/policies/x.md`, resolved against `knowledge/`) and
  * relative (`x.md`, `./x.md`, `../x.md`, against the document's own
  * directory), with `.md` optional in each. The shell resolves only the `./`
- * and `../` forms (fumadocs-core 16.14.5, `resolveHref` returns anything else
+ * and `../` forms (fumadocs-core 16.15.4, `resolveHref` returns anything else
  * untouched), so a bundle-absolute link left the record's frame entirely and a
  * bare `x.md` was resolved by the browser against the page's ROUTE rather than
  * its directory: both 404'd from every page, found live 2026-08-25 as prefetch

package/templates/scaffold/system/site/next.config.mjs

@@ -46,6 +46,19 @@ const config = {
   // Hosting under a sub-path (e.g. a GitHub Pages project site):
   //   KSOR_BASE_PATH="/my-repo" pnpm build
   basePath: process.env.KSOR_BASE_PATH ?? "",
+  // Next >= 16.3 writes AGENTS.md and CLAUDE.md into the Next project root
+  // whenever `next dev` detects a coding agent (`agentRules`, default true).
+  // Here that root is system/site, and a markdown file there is refused by the
+  // record's own hygiene rule (`ksor-site-holds-content`): the site RENDERS the
+  // record, it never holds it, so content there silently forks it. Left on, an
+  // adopter's `pnpm dev` made their own `pnpm check` go red — reproduced by the
+  // scaffold walkthrough the hour Next 16.3.3 was pinned.
+  //
+  // The scaffold already answers what the feature is for: AGENTS.md at the repo
+  // root is the coding agent's first read, and one record must not speak with
+  // two voices about one thing. Turn it back on only if you also move those two
+  // files out of system/site.
+  agentRules: false,
   turbopack: {
     root: repoRoot,
   },

package/templates/scaffold/system/site/package.json

@@ -10,11 +10,11 @@
   "dependencies": {
     "class-variance-authority": "0.7.1",
     "clsx": "2.1.1",
-    "fumadocs-core": "16.14.5",
-    "fumadocs-mdx": "15.3.0",
-    "fumadocs-ui": "16.14.5",
+    "fumadocs-core": "16.15.4",
+    "fumadocs-mdx": "15.4.0",
+    "fumadocs-ui": "16.15.4",
     "lucide-react": "1.31.0",
-    "next": "16.2.9",
+    "next": "16.3.3",
     "radix-ui": "1.6.7",
     "react": "19.2.8",
     "react-dom": "19.2.8",

package/templates/scaffold/system/site/source.config.ts

@@ -230,7 +230,7 @@ export default defineConfig({
      * apply to every group on the page and persist to the next visit. The
      * `Tabs` branch drops the attribute silently, so a reader with a
      * ten-section document would pick their tool ten times (verified against
-     * fumadocs-core 16.14.5, remark-code-tab.js).
+     * fumadocs-core 16.15.4, remark-code-tab.js).
      */
     remarkPlugins: [[remarkCodeTab, { Tabs: "CodeBlockTabs" }]],
   },