@panaversity/ksor 0.0.40 → 0.0.42

package/templates/scaffold/system/site/app/md/[[...slug]]/route.ts

@@ -1,36 +1,38 @@
 import { notFound } from "next/navigation";
 
-import { getLLMText, getSortedPages, source } from "@/lib/source";
+import { getLLMText, getMachinePages, rootIndexTwin, source } from "@/lib/source";
+import { machineAdmits } from "@/lib/stage-manifest";
 
 export const revalidate = false;
 
 /**
- * Every document as markdown, at a stable address derived from its path:
- * `/docs/policies/purchase-approval` is also served at
- * `/md/policies/purchase-approval.md`.
+ * Every MACHINE-admitted document as markdown, at a stable address derived
+ * from its path: `/docs/policies/purchase-approval` is also served at
+ * `/md/policies/purchase-approval.md`, and the record's own index at
+ * `/md/index.md` — the one index with a twin (build spec §3).
  *
  * The record already IS markdown; without this an agent handed a document URL
  * had to scrape a React app to reach text the record holds verbatim
- * (research/site-design.md F2). The body carries the document's governance as
- * frontmatter, exactly as `llms-full.txt` does, so a consumer reading one
- * document knows its status, owner, sources and successor.
+ * (research/site-design.md F2). The body carries the document's governance and
+ * the build's stamps as frontmatter, exactly as `llms-full.txt` does.
  *
- * Why a `/md/` prefix rather than appending `.md` to the document's own URL,
- * which is the convention the field has settled on: under `output: "export"` a
- * Route Handler cannot share a route segment with a Page, and there is no
- * middleware to rewrite one onto the other. The prefix is the shape that
+ * A page the machine surfaces decline — a draft, a deprecated, a not-yet-
+ * effective or a stale concept (record spec §2.5) — has no twin at all: the
+ * decision is staging's, read back here, never re-derived.
+ *
+ * Why a `/md/` prefix rather than appending `.md` to the document's own URL:
+ * under `output: "export"` a Route Handler cannot share a route segment with a
+ * Page, and there is no middleware to rewrite one onto the other. The prefix
  * survives a static host, and the page advertises it in a `rel="alternate"`
- * link so a consumer discovers it rather than guessing. Appending `.md` to the
- * canonical URL becomes possible the day a build emits these artifacts itself.
+ * link so a consumer discovers it rather than guessing.
  */
 export function generateStaticParams(): { slug: string[] }[] {
-  return source.generateParams().map(({ slug }) => {
-    const segments = slug ?? [];
-    const last = segments.at(-1);
-    return {
-      slug: last === undefined ? ["index.md"] : [...segments.slice(0, -1), `${last}.md`],
-    };
+  const twins = getMachinePages().map((page) => {
+    const segments = page.url.replace(/^\/docs\/?/, "").split("/");
+    const last = segments.at(-1) ?? "";
+    return { slug: [...segments.slice(0, -1), `${last}.md`] };
   });
+  return [{ slug: ["index.md"] }, ...twins];
 }
 
 export async function GET(
@@ -40,12 +42,11 @@ export async function GET(
   const { slug = [] } = await params;
   const last = slug.at(-1);
   if (last === undefined || !last.endsWith(".md")) notFound();
-  const docSlug = last === "index.md" ? [] : [...slug.slice(0, -1), last.slice(0, -".md".length)];
+  const headers = { "content-type": "text/markdown; charset=utf-8" };
+  if (slug.length === 1 && last === "index.md") return new Response(rootIndexTwin(), { headers });
 
-  const page = source.getPage(docSlug);
-  if (!page) notFound();
+  const page = source.getPage([...slug.slice(0, -1), last.slice(0, -".md".length)]);
+  if (!page || !machineAdmits(page.path)) notFound();
 
-  return new Response(await getLLMText(page, getSortedPages()), {
-    headers: { "content-type": "text/markdown; charset=utf-8" },
-  });
+  return new Response(getLLMText(page), { headers });
 }

package/templates/scaffold/system/site/components/footer-mark.tsx

@@ -13,10 +13,11 @@ import { audienceNotice } from "@/lib/audience";
  * carry the shape of a disclosure.
  */
 export function FooterMark(): ReactElement {
-  if (audienceNotice === null) return <BuiltWith />;
+  const notice = audienceNotice();
+  if (notice === null) return <BuiltWith />;
   return (
     <>
-      <BuiltWith /> &middot; <span className="text-fd-muted-foreground">{audienceNotice}</span>
+      <BuiltWith /> &middot; <span className="text-fd-muted-foreground">{notice}</span>
     </>
   );
 }

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

@@ -5,18 +5,25 @@ import { Clock } from "lucide-react";
 import type { ReactElement } from "react";
 
 import {
-  caveatStatus,
-  statusTone,
+  badgeAddsToStatus,
+  badgeText,
+  badgeTone,
+  dayOf,
   isCalendarDate,
+  plainBadge,
   sourceHref,
+  statusLabel,
+  statusTone,
+  trustSignal,
   type DocumentGovernance,
 } from "@/lib/governance";
+import type { LifecycleBadge } from "@/lib/lifecycle-rule";
 
 /**
  * What the record says about the document you are reading.
  *
  * The site renders the record; these render the record's governance — the
- * frontmatter `pnpm check` enforces on every document. Nothing here is
+ * profile's frontmatter `pnpm check` enforces on every concept. Nothing here is
  * authored in the site (critical rule 1) and nothing is inferred: a key the
  * document does not declare renders nothing at all.
  *
@@ -27,9 +34,9 @@ import {
  */
 
 /**
- * The successor of a superseded document: its route and the text naming it.
- * `href` is null when the pointer could not be resolved to a route, and then
- * the pointer itself is shown as text rather than as a dead link.
+ * The successor of a deprecated document: its route and the text naming it.
+ * `href` is null when the pointer could not be resolved to a route in this
+ * build, and then the pointer itself is shown as text rather than as a dead link.
  */
 export interface Successor {
   readonly href: string | null;
@@ -37,11 +44,12 @@ export interface Successor {
 }
 
 /**
- * The supersession notice. Deliberately the first thing on the page, above the
+ * The deprecation notice. Deliberately the first thing on the page, above the
  * title: a reader must not have to notice a subtle badge to learn that what
- * they are about to read has been replaced.
+ * they are about to read has been withdrawn. `successor` is null when the
+ * record deprecated the document without naming a replacement.
  */
-export function SupersededNotice({ successor }: { successor: Successor }): ReactElement {
+export function DeprecatedNotice({ successor }: { successor: Successor | null }): ReactElement {
   return (
     <aside
       // A landmark, not a note: GOV.UK ships this as role="region" with
@@ -49,7 +57,7 @@ export function SupersededNotice({ successor }: { successor: Successor }): React
       // thing on the page by landmark, rather than only meeting it in reading
       // order. role="note" is announced but not navigable.
       role="region"
-      aria-labelledby="ksor-superseded"
+      aria-labelledby="ksor-deprecated"
       // Tinted and ruled down the left edge in the CAUTION role, never
       // --color-fd-muted: the shipped light theme defines --color-fd-muted and
       // --color-fd-background as the same value, so the callout composited to
@@ -57,22 +65,29 @@ export function SupersededNotice({ successor }: { successor: Successor }): React
       // Chromium, 2026-08-20). The one thing this notice cannot be is missable.
       className="ksor-caution mb-8 rounded-lg border border-l-4 px-4 py-3 text-sm"
     >
-      <p id="ksor-superseded" className="font-medium text-fd-foreground">
-        Superseded
+      <p id="ksor-deprecated" className="font-medium text-fd-foreground">
+        Deprecated
       </p>
       <p className="mt-1 text-fd-muted-foreground">
-        This document has been replaced by{" "}
-        {successor.href === null ? (
-          <code className="break-words text-fd-foreground">{successor.label}</code>
+        {successor === null ? (
+          "The record has withdrawn this document."
         ) : (
-          <Link
-            href={successor.href}
-            className="font-medium text-fd-foreground underline underline-offset-4 transition-colors hover:text-fd-primary focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-fd-ring"
-          >
-            {successor.label}
-          </Link>
-        )}
-        . It is kept because the record never deletes what it replaces.
+          <>
+            This document has been replaced by{" "}
+            {successor.href === null ? (
+              <code className="break-words text-fd-foreground">{successor.label}</code>
+            ) : (
+              <Link
+                href={successor.href}
+                className="font-medium text-fd-foreground underline underline-offset-4 transition-colors hover:text-fd-primary focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-fd-ring"
+              >
+                {successor.label}
+              </Link>
+            )}
+            .
+          </>
+        )}{" "}
+        It is kept because the record never deletes what it replaces.
       </p>
     </aside>
   );
@@ -89,13 +104,10 @@ function Fact({
     <div className="flex items-baseline gap-2.5">
       {/* Mono, uppercase, letterspaced: these are the record's checkable facts,
           and they read as a register's column heads rather than as a form.
-
           The label is deliberately SMALLER and more letterspaced than the value
-          it introduces. Both used to be mono a single pixel apart — 11px label
-          against a 12px value — so "Owner Product Effective 2026-08-22" read as
-          one undifferentiated mono run rather than as two facts with names
-          (reported by the owner, 2026-08-22, quoting the run back verbatim).
-          The step is now 10px against 13px, and the value carries the weight. */}
+          it introduces (10px against 13px), so "Owner Product Effective
+          2026-08-22" reads as two facts with names rather than one mono run
+          (reported by the owner, 2026-08-22). */}
       <dt className="font-mono text-[0.625rem] tracking-[0.18em] text-fd-muted-foreground uppercase">
         {label}
       </dt>
@@ -106,20 +118,82 @@ function Fact({
   );
 }
 
+/** One chip: a word the record says about this document, in the register's voice. */
+function Chip({ text, tone = "" }: { text: string; tone?: string }): ReactElement {
+  return (
+    <span
+      className={`rounded-sm border border-fd-border px-1.5 py-0.5 tracking-widest whitespace-nowrap uppercase ${tone}`}
+    >
+      {text}
+    </span>
+  );
+}
+
+/** The chip a badge wears, in every listing and on the page. */
+export function BadgeChip({
+  badge,
+  effectiveFrom = null,
+}: {
+  badge: LifecycleBadge;
+  /** `ksor.effective_from`, which fills record spec §2.5's "effective from …". */
+  effectiveFrom?: string | null;
+}): ReactElement {
+  return <Chip text={badgeText(badge, effectiveFrom) ?? ""} tone={badgeTone(badge)} />;
+}
+
+/**
+ * The lifecycle caveat ALONE, for a page with no governance strip under its
+ * title — a record whose `site.governance` is off.
+ *
+ * That key turns off attribution, not caveats: the deprecation notice has
+ * always survived it, and the sidebar row, the folder card and the search
+ * result for this same document carry their badge whatever it says. The rule
+ * for which states reach here is `plainBadge`, beside the vocabulary itself.
+ *
+ * Typed like the strip's own values (mono, 13px), because a badge is the
+ * record speaking about a document and that is the voice it speaks in
+ * everywhere else.
+ */
+export function LifecycleCaveat({
+  badge,
+  effectiveFrom = null,
+}: {
+  badge: LifecycleBadge | null;
+  effectiveFrom?: string | null;
+}): ReactElement | null {
+  const caveat = plainBadge(badge);
+  if (caveat === null) return null;
+  return (
+    <div className="mb-7 font-mono text-[0.8125rem] font-medium text-fd-foreground">
+      <BadgeChip badge={caveat} effectiveFrom={effectiveFrom} />
+    </div>
+  );
+}
+
 /**
- * The one-line governance strip under the document's title: any caveat on its
- * status, who stands behind it, and when it took effect.
+ * The one-line governance strip under the document's title: what the record
+ * says about this document, and who said it.
+ *
+ * Two kinds of thing sit here and they are drawn differently on purpose. The
+ * CHIPS are states — the lifecycle status, and the date badge when the calendar
+ * keeps an otherwise current document off the machine surfaces (record spec
+ * §2.5) — and the FACTS are attributions: who owns it, who approved it, who
+ * verified it and when. A reader deciding whether to act on a document needs
+ * both halves, and the predecessor's failure was showing neither.
  */
 export function GovernanceMeta({
   governance,
+  badge,
   replaces = [],
   markdownUrl,
   minutes,
 }: {
   governance: DocumentGovernance;
+  /** Why the machine surfaces decline this page, or null. */
+  badge: LifecycleBadge | null;
   /** Documents this one replaced — derived from the record, never declared. */
   replaces?: readonly Successor[];
-  /** The document's markdown twin, offered beside its governance. */
+  /** The document's markdown twin, offered beside its governance — only where one exists. */
   markdownUrl?: string;
   /**
    * How long the document takes to read, when this row is the only place for
@@ -127,30 +201,80 @@ export function GovernanceMeta({
    * because there the number belongs to the view you picked.
    */
   minutes?: number;
-}): ReactElement | null {
-  const { owner, effective } = governance;
-  const status = caveatStatus(governance.status);
-  const bare = status === null && owner === null && effective === null && replaces.length === 0;
-  if (bare && markdownUrl === undefined && minutes === undefined) return null;
+}): ReactElement {
+  const { status, owner, effectiveFrom, staleAfter, approval, deprecated } = governance;
+  const state = statusLabel(status);
+  // The badge is a SECOND chip only where it says something the status does
+  // not: `draft` and `deprecated` are both words, and printing either twice
+  // reads as two facts about one document.
+  const alsoBadge = badgeAddsToStatus(badge, status) ? badge : null;
+  const trust = trustSignal(governance.verified);
+  // …and where the badge carries the date, the fact beside it would repeat it.
+  const showEffective = effectiveFrom !== null && alsoBadge !== "effective-from";
 
+  // There is no "nothing to show" case any more: every concept has a trust
+  // tier, `unverified` included, and that is the whole point of printing it.
+  // The early return this replaced would have hidden the tier on exactly the
+  // documents whose tier is the only governance fact they have.
   return (
     <dl className="mb-7 flex flex-wrap items-baseline gap-x-8 gap-y-2.5 border-b border-fd-border pb-4">
-      {status === null ? null : (
+      {state === null && alsoBadge === null ? null : (
         <Fact label="Status">
-          <span
-            className={`rounded-sm border border-fd-border px-1.5 py-0.5 tracking-widest uppercase ${statusTone(status)}`}
-          >
-            {status}
+          <span className="flex flex-wrap items-baseline gap-1.5">
+            {state === null ? null : <Chip text={state} tone={statusTone(status)} />}
+            {alsoBadge === null ? null : (
+              <BadgeChip badge={alsoBadge} effectiveFrom={effectiveFrom} />
+            )}
           </span>
         </Fact>
       )}
+      {/* The tier OKF's own vocabulary names, on every document including the
+          unverified ones — that is the honest state of a stable, approved
+          concept nobody has reviewed, and hiding it would leave a reader unable
+          to tell "checked" from "never mentioned" (research/okf-native.md
+          §1.1). Never a colour: a tier is a fact about review, not a warning. */}
+      <Fact label="Trust">
+        <span className="flex flex-wrap items-baseline gap-1.5">
+          <Chip text={trust.tier} />
+          {trust.by === null ? null : (
+            <span className="font-normal text-fd-muted-foreground">
+              {trust.by}
+              {trust.at === null ? null : <> · {day(trust.at)}</>}
+            </span>
+          )}
+        </span>
+      </Fact>
       {owner === null ? null : <Fact label="Owner">{owner}</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
+          author. */}
+      {approval === null ? null : (
+        <Fact label="Approved">
+          <>
+            {approval.by} · {day(approval.at)}
+          </>
+        </Fact>
+      )}
+      {/* found live 2026-08-25: a deprecated page named its successor and said
+          nothing about WHO withdrew it, though `ksor.deprecated` is required on
+          every deprecated concept (record spec §2.2) and readGovernance already
+          refuses a document that omits it. Withdrawal is the most consequential
+          act in a document's life; publishing it unattributed is exactly the
+          gap the approver fact above closes at the other end. */}
+      {deprecated === null ? null : (
+        <Fact label="Withdrawn">
+          <>
+            {deprecated.by} · {day(deprecated.at)}
+          </>
+        </Fact>
+      )}
       {replaces.length === 0 ? null : (
         // The other half of a supersession. The withdrawn document names its
         // successor above the title; this is the successor naming what it
         // replaced, so the history the record kept is reachable from the
         // current document instead of only from the retired one.
-        <Fact label={replaces.length === 1 ? "Replaces" : "Replaces"}>
+        <Fact label="Replaces">
           <>
             {replaces.map((entry, index) => (
               <span key={entry.href ?? `${index}-${entry.label}`}>
@@ -170,39 +294,15 @@ export function GovernanceMeta({
           </>
         </Fact>
       )}
-      {effective === null ? null : (
-        <Fact label="Effective">
-          {/* The machine attribute is stamped only for a real day on the
-              calendar. A SHAPE test was not enough: the checker's own remedy
-              for `2026-06-31` is to QUOTE it, and quoted text arrives here — so
-              a shape test published `<time dateTime="2026-06-31">`, which is
-              invalid HTML and which a consumer reads as July 1st. That is the
-              precise hazard the record's date rule exists to prevent. */}
-          {isCalendarDate(effective) ? (
-            <time dateTime={effective}>{effective}</time>
-          ) : (
-            <span>{effective}</span>
-          )}
-        </Fact>
+      {effectiveFrom === null || !showEffective ? null : (
+        <Fact label="Effective from">{day(effectiveFrom)}</Fact>
       )}
+      {staleAfter === null ? null : <Fact label="Review by">{day(staleAfter)}</Fact>}
       {markdownUrl === undefined ? null : (
         // On the governance row, not as a footnote below the sources: it is
-        // how a reader hands this document to an agent, and it was previously
-        // the smallest text on the page, last (research/site-design.md F2).
-        // ONE control rather than two: opening the markdown and copying it are
-        // different acts, but two bare controls on a row of read-only facts
-        // made the row look half clickable. It wears neither the bordered badge
-        // (that means "a status the record declares") nor the accent at rest —
-        // the page had gone blue enough that the accent had stopped meaning
-        // anything (owner, 2026-08-22).
-        // RIGHT-ALIGNED (owner, and a reversal). The 2026-08-21 finding stands
-        // on its own terms: `ms-auto` once parked this 498px from the nearest
-        // thing on a two-fact document, where it read as belonging to nothing.
-        // What changed is the column beside it — the reading time now sits at
-        // the right end of the strip directly below, so the far edge is no
-        // longer empty space but a line the eye already follows. The two form
-        // a right-hand column of things you DO, against a left-hand row of
-        // things the record DECLARES.
+        // how a reader hands this document to an agent (research/site-design.md
+        // F2). Right-aligned: a column of things you DO, against a row of
+        // things the record DECLARES (owner, 2026-08-22).
         <span className="ms-auto">
           <DocumentActions href={markdownUrl} />
         </span>
@@ -217,36 +317,54 @@ export function GovernanceMeta({
   );
 }
 
+/** An instant as a day, stamped as machine-readable only when it is a real one. */
+function day(instant: string): ReactElement {
+  const value = dayOf(instant);
+  return isCalendarDate(value) ? <time dateTime={value}>{value}</time> : <span>{value}</span>;
+}
+
 /**
- * Where the document came from.
- *
- * One entry per source, each independently visible — that is the whole point
- * of `provenance` being a list: a citation has to be able to point at exactly
- * one of them. Rendering them as prose would take that away.
+ * Where the document came from: `sources`, one entry each — that is the whole
+ * point of it being a list: a footnote has to be able to point at exactly one
+ * of them. Rendering them as prose would take that away.
  */
-export function Provenance({ entries }: { entries: readonly string[] }): ReactElement | null {
+export function Provenance({
+  entries,
+}: {
+  entries: readonly {
+    readonly id: string | null;
+    readonly title: string | null;
+    readonly resource: string;
+  }[];
+}): ReactElement | null {
   if (entries.length === 0) return null;
 
   return (
     <section className="mt-10 border-t border-fd-border pt-5 text-sm">
       <h2 className="ksor-section-label mb-2">Sources</h2>
-      {/* break-words, because a citation is often a long unbroken URL: on a
+      {/* break-words, because a source is often a long unbroken URL: on a
           phone it overflowed its row by 175px under an ancestor with
           `overflow-x: clip`, so the middle of the source was clipped away with
           no ellipsis and nothing to scroll (measured, 2026-08-20). A source
           nobody can read is not provenance. */}
       <ul className="space-y-1 break-words text-fd-muted-foreground">
         {entries.map((entry, index) => {
-          // An entry that IS a URL becomes followable; a citation stays text.
-          // `rel="noreferrer"` because the destination is authored in the
-          // record, not chosen by this site.
-          const href = sourceHref(entry);
+          // A resource that IS a URL becomes followable; a bundle path or a
+          // scope descriptor stays text. `rel="noreferrer"` because the
+          // destination is authored in the record, not chosen by this site.
+          const href = sourceHref(entry.resource);
+          const label = entry.title ?? entry.resource;
           return (
             // Position, not text: a record may cite the same source twice, and
             // duplicate keys are a console error on a governed page.
-            <li key={`${index}-${entry}`}>
+            <li key={`${index}-${entry.resource}`}>
+              {entry.id === null ? null : (
+                <span className="me-2 font-mono text-xs text-fd-muted-foreground">
+                  [^{entry.id}]
+                </span>
+              )}
               {href === null ? (
-                entry
+                label
               ) : (
                 <a
                   href={href}
@@ -254,7 +372,7 @@ export function Provenance({ entries }: { entries: readonly string[] }): ReactEl
                   rel="noreferrer"
                   className="underline underline-offset-4 transition-colors hover:text-fd-foreground focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-fd-ring"
                 >
-                  {entry}
+                  {label}
                 </a>
               )}
             </li>

package/templates/scaffold/system/site/components/record-index.tsx

@@ -2,7 +2,7 @@ import { ArrowRight, FileText, Folder } from "lucide-react";
 import Link from "next/link";
 import type { ReactElement } from "react";
 
-import { statusTone } from "@/lib/governance";
+import { badgeLabel, badgeTone } from "@/lib/governance";
 import type { RecordEntry } from "@/lib/source";
 
 /**
@@ -28,7 +28,7 @@ import type { RecordEntry } from "@/lib/source";
  *
  * What survives from the register is the part that was never about looks: the
  * record's serif for its own words, mono for what the record says ABOUT them —
- * who owns it, how much it holds, whether it carries a caveat — and `approved`
+ * who owns it, how much it holds, whether it carries a caveat — and `stable`
  * staying silent, because a label on every row is a label nobody reads.
  *
  * Server-rendered plain markup — it survives print, a failed bundle and
@@ -70,11 +70,11 @@ export function RecordIndex({
                     <span className="font-display text-lg leading-snug font-semibold tracking-[-0.008em] transition-colors group-hover:text-fd-primary">
                       {entry.title}
                     </span>
-                    {entry.status === null ? null : (
+                    {entry.badge === null ? null : (
                       <span
-                        className={`rounded-sm border border-fd-border px-1.5 py-0.5 font-mono text-[10px] tracking-widest text-fd-foreground uppercase ${statusTone(entry.status)}`}
+                        className={`rounded-sm border border-fd-border px-1.5 py-0.5 font-mono text-[10px] tracking-widest text-fd-foreground uppercase ${badgeTone(entry.badge)}`}
                       >
-                        {entry.status}
+                        {badgeLabel(entry.badge)}
                       </span>
                     )}
                   </span>

package/templates/scaffold/system/site/components/record-stack.tsx

@@ -1,7 +1,8 @@
 import Link from "next/link";
 import type { ReactElement } from "react";
 
-import { statusTone } from "@/lib/governance";
+import { badgeLabel, badgeTone } from "@/lib/governance";
+import type { LifecycleBadge } from "@/lib/lifecycle-rule";
 import type { RecordEntry } from "@/lib/source";
 
 /**
@@ -53,7 +54,7 @@ export function RecordStack({
           <span className="font-mono text-[10px] tracking-[0.2em] text-[var(--ksor-cover-muted)] uppercase">
             Opens here
           </span>
-          {lead.status === null ? null : <StatusChip status={lead.status} />}
+          {lead.badge === null ? null : <StatusChip badge={lead.badge} />}
         </div>
 
         <h2 className="mt-4 font-display text-2xl leading-snug font-semibold tracking-[-0.008em] transition-colors group-hover:text-fd-primary">
@@ -99,7 +100,7 @@ export function RecordStack({
               {entry.documents === 0
                 ? null
                 : `${entry.documents} ${entry.documents === 1 ? "doc" : "docs"}`}
-              {entry.status === null ? null : <StatusChip status={entry.status} />}
+              {entry.badge === null ? null : <StatusChip badge={entry.badge} />}
             </span>
           </span>
         </Link>
@@ -116,16 +117,16 @@ export function RecordStack({
 }
 
 /**
- * A caveat status, in the same chip the record's listings use — only ever
- * `draft`, `review` or `superseded`, because a reader already assumes a
- * document in the record is current.
+ * A caveat badge, in the same chip the record's listings use — only ever a
+ * state the machine surfaces decline (record spec §2.5), because a reader
+ * already assumes a document in the record is current and stable.
  */
-function StatusChip({ status }: { status: string }): ReactElement {
+function StatusChip({ badge }: { badge: LifecycleBadge }): ReactElement {
   return (
     <span
-      className={`rounded-sm border border-[var(--ksor-cover-rule)] px-1.5 py-0.5 font-mono text-[10px] tracking-widest text-[var(--ksor-cover-foreground)] uppercase ${statusTone(status)}`}
+      className={`rounded-sm border border-[var(--ksor-cover-rule)] px-1.5 py-0.5 font-mono text-[10px] tracking-widest text-[var(--ksor-cover-foreground)] uppercase ${badgeTone(badge)}`}
     >
-      {status}
+      {badgeLabel(badge)}
     </span>
   );
 }