@b00dea/cockpit 0.1.0 → 0.1.1

package/dist/config/load.js

@@ -1,10 +1,12 @@
 import { createHash } from 'node:crypto';
 import { realpath } from 'node:fs/promises';
 import { basename, dirname, join, resolve } from 'node:path';
-import { parse } from 'smol-toml';
+import { parse, TomlError } from 'smol-toml';
 import { RefusalError, ENVIRONMENT_CODES, snapshotJson, } from '../environment/contract.js';
 import { effectivePolicy, readRecordedPolicy } from '../autonomy.js';
-import { CockpitConfig, EVALUATOR_COMMANDS, runtimeDeclarationSha256 } from '../schema.js';
+import { browserDataQualifies, CockpitConfig, EVALUATOR_COMMANDS, runtimeDeclarationSha256 } from '../schema.js';
+/** An explicit request_preapproval wins; otherwise preapproval follows the declared data posture. */
+export const browserPreapprovalRequested = (browser) => browser.request_preapproval ?? browserDataQualifies(browser.data);
 import { formatShellCommand } from '../fix-catalogue.js';
 import { readBoundedFile } from '../bounded-read.js';
 export const STRUCTURED_INPUT_BYTE_LIMIT = 1_048_576;
@@ -42,7 +44,7 @@ function projectBrowserConfig(declaredBrowser) {
             isolated: declaredBrowser.data.isolated,
             reachesProduction: declaredBrowser.data.reaches_production,
         },
-        requestPreapproval: declaredBrowser.request_preapproval,
+        requestPreapproval: browserPreapprovalRequested(declaredBrowser),
         artifacts: { ...declaredBrowser.artifacts },
     };
 }
@@ -65,6 +67,7 @@ function projectTestingConfig(declaredTesting) {
             })),
         },
         nativeHookInstall: declaredTesting.native_hooks.install,
+        ...(declaredTesting.test_files === undefined ? {} : { testFiles: [...declaredTesting.test_files] }),
         ...(declaredTesting.native_hook_policy === undefined ? {} : {
             nativeHookPolicy: { ...declaredTesting.native_hook_policy },
         }),
@@ -99,6 +102,10 @@ export function projectWorkEnvironmentConfig(configuration) {
         generatedHostPaths: Object.freeze([...loaded.config.environment.generated_host_paths]),
         ...(browser === undefined ? {} : { browser }),
         ...(testing === undefined ? {} : { testing }),
+        ...(loaded.config.docs === undefined ? {} : { docs: Object.freeze({
+                ...(loaded.config.docs.decisions === undefined ? {} : { decisions: loaded.config.docs.decisions }),
+                ...(loaded.config.docs.decisions_index === undefined ? {} : { decisionsIndex: loaded.config.docs.decisions_index })
+            }) }),
     }));
     return result;
 }
@@ -268,6 +275,21 @@ export async function loadAutonomyPolicy(configPath) {
     const recorded = await readRecordedPolicy(root);
     return { root, current: effectivePolicy(loaded.result.config), ...recorded ? { recorded } : {} };
 }
+/** The configuration `bytes` declare, or undefined when they are not UTF-8 TOML the schema accepts. */
+export function parseCockpitConfigBytes(bytes) {
+    let parsed;
+    try {
+        parsed = parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+    }
+    catch (error) {
+        // Invalid UTF-8 or TOML is the answer; anything else is a fault to surface.
+        if (error instanceof TypeError || error instanceof TomlError)
+            return undefined;
+        throw error;
+    }
+    const validated = CockpitConfig.safeParse(parsed);
+    return validated.success ? validated.data : undefined;
+}
 export async function loadCockpitConfig(inputPath) {
     const observed = await readConfigSource(inputPath);
     if (observed.kind === 'unavailable') {

package/dist/config/unconfirmed-toml.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Owns the text edit `confirm` makes to cockpit.toml: drop one answer from the top-level
+ * `unconfirmed = [...]` line, or the whole line once the list empties. Every other byte, comments
+ * included, is left alone. The verified write re-parses the result and refuses anything beyond that
+ * change; a layout this module cannot locate the list in (a multi-line array, a list inside a table)
+ * is refused by name rather than guessed at.
+ */
+import { type SiblingEdit } from './sibling-toml.js';
+export declare function removeUnconfirmedAnswer(text: string, answer: string): SiblingEdit;

package/dist/config/unconfirmed-toml.js

@@ -0,0 +1,29 @@
+/**
+ * Owns the text edit `confirm` makes to cockpit.toml: drop one answer from the top-level
+ * `unconfirmed = [...]` line, or the whole line once the list empties. Every other byte, comments
+ * included, is left alone. The verified write re-parses the result and refuses anything beyond that
+ * change; a layout this module cannot locate the list in (a multi-line array, a list inside a table)
+ * is refused by name rather than guessed at.
+ */
+import { scanHeaders } from './sibling-toml.js';
+const UNCONFIRMED_KEY = /^\s*unconfirmed\s*=/;
+const SINGLE_LINE_ARRAY = /^(\s*unconfirmed\s*=\s*)\[([^\]#]*)\](\s*(?:#.*)?)$/;
+export function removeUnconfirmedAnswer(text, answer) {
+    const lines = text.split('\n');
+    const firstHeader = scanHeaders(lines)[0]?.line ?? lines.length;
+    const keys = lines.slice(0, firstHeader).flatMap((row, index) => UNCONFIRMED_KEY.test(row) ? [index] : []);
+    const at = keys[0];
+    const current = at === undefined ? null : SINGLE_LINE_ARRAY.exec(lines[at]);
+    if (keys.length !== 1 || !current) {
+        return { kind: 'unsupported', reason: 'the unconfirmed list is not written on one line as unconfirmed = [...] before the first table' };
+    }
+    const rows = current[2].split(',').map(row => row.trim()).filter(row => row !== '');
+    const kept = rows.filter(row => row !== JSON.stringify(answer) && row !== `'${answer}'`);
+    if (kept.length === rows.length)
+        return { kind: 'unsupported', reason: `the unconfirmed list does not spell ${answer} as a plain string` };
+    if (kept.length === 0)
+        lines.splice(at, 1);
+    else
+        lines[at] = `${current[1]}[${kept.join(', ')}]${current[3]}`;
+    return { kind: 'edited', text: lines.join('\n') };
+}

package/dist/diagnostics.js

@@ -187,6 +187,13 @@ function lifecycleSummary(command, result) {
             + resetTargetLines(targets)
             + 'The next up recreates the removed volumes and, where environment.seed is declared, runs the seed to fill them.\n';
     }
+    if (command === 'ps' && Array.isArray(result.services)) {
+        return result.services
+            .map(row => `${escapeForTerminal(`${String(row.service)}  ${String(row.state)}${typeof row.status === 'string' ? `  ${row.status}` : ''}`)}\n`).join('');
+    }
+    if ((command === 'restart' || command === 'rebuild') && typeof result.service === 'string' && typeof result.change === 'string') {
+        return `${escapeForTerminal(`Service ${result.service} ${result.change} and healthy.`)}\n`;
+    }
     const headline = Object.hasOwn(LIFECYCLE_CHANGES, command) && typeof result.change === 'string'
         && Object.hasOwn(LIFECYCLE_CHANGES[command], result.change) ? LIFECYCLE_CHANGES[command][result.change] : undefined;
     if (headline === undefined || typeof result.stackId !== 'string')
@@ -243,6 +250,8 @@ function doctorSummary(result, diagnostics, fixContext) {
         const declared = named('declared');
         const absent = named('not-declared');
         lines.push(`Declared: ${declared.join(', ') || 'nothing'}${absent.length === 0 ? '' : `; not declared: ${absent.join(', ')}`}.`);
+        if (declared.includes('docs'))
+            lines.push(`Documents: ${bindConfigPath(cockpitCommand('docs check'), fixContext)} checks them; doctor does not.`);
     }
     const readiness = result.readiness;
     if (readiness && Array.isArray(readiness.gaps)) {
@@ -297,7 +306,7 @@ export function renderHumanDiagnostics(diagnostics, review, fixContext, usageHin
         if (command === 'doctor') {
             return doctorSummary(outcome.result, outcome.diagnostics ?? [], fixContext);
         }
-        if (command === 'selftest' || command === 'upgrade' || command === 'init') {
+        if (command === 'selftest' || command === 'upgrade' || command === 'init' || command === 'stacks') {
             return renderHumanValue(outcome.result);
         }
         return command === undefined ? '' : lifecycleSummary(command, outcome.result);

package/dist/docs/check.d.ts

@@ -0,0 +1,16 @@
+import type { ExecuteProbeOutcome } from '../environment-exec/execute.js';
+import { type Diagnostic, type ExecutionStep } from '../environment/contract.js';
+interface DocsCheckInput {
+    readonly configPath: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+}
+interface DocsCheckOutcome {
+    readonly status: number;
+    readonly diagnostics: readonly Diagnostic[];
+    readonly result: unknown;
+}
+type Execute = (step: ExecutionStep) => Promise<ExecuteProbeOutcome>;
+export declare function runDocsCheck(input: DocsCheckInput, dependencies: Readonly<{
+    execute: Execute;
+}>): Promise<DocsCheckOutcome>;
+export {};

package/dist/docs/check.js

@@ -0,0 +1,197 @@
+// `cockpit docs check`: the living documents and decision records [docs] declares, checked against
+// each repository's files and history. It reads and runs read-only Git; it writes nothing.
+import { lstatIfPresentSync } from '../environment/presence.js';
+import { posix, resolve } from 'node:path';
+import { readBoundedFile } from '../bounded-read.js';
+import { loadCockpitConfig } from '../config/load.js';
+import { ENVIRONMENT_CODES, errorCause } from '../environment/contract.js';
+import { gitRepositoryRefusal } from '../environment/git-observation.js';
+import { redactSensitiveMessage } from '../environment/sensitive.js';
+import { createGitRunner, loadServedSiblings, missingServedCheckout, servedPath } from '../environment/sibling-checkouts.js';
+import { refusalOutcome } from '../refusal.js';
+import { splitRepositoryPath } from '../repository-path.js';
+import { scopeMatcher } from '../work-orders/contract.js';
+import { inspectDecisionRecords } from './decisions.js';
+import { walkMarkdownProse } from './markdown.js';
+import { historicalMakeTargets, makeTargets, parseRemovedPaths, staleReferences } from './references.js';
+const GIT_TIMEOUT_MS = 60_000;
+// The executor's ceiling; a history longer than this is refused rather than read in part.
+const GIT_OUTPUT_LIMIT = 16_777_216;
+const DOCUMENT_LIMIT = 4_194_304;
+const MARKDOWN = /\.(?:md|markdown|mdx)$/i;
+const MAKEFILE = /(?:^|\/)(?:GNUmakefile|[Mm]akefile|[^/]+\.mk)$/;
+const MAKEFILE_PATHSPECS = [':(glob)**/GNUmakefile', ':(glob)**/Makefile', ':(glob)**/makefile', ':(glob)**/*.mk'];
+class EvidenceUnavailable extends Error {
+}
+async function git(runner, root, args) {
+    const command = `git -C ${root} ${args.join(' ')}`;
+    const ran = await runner.run(root, `git:docs-check:${args[0]}`, args, { timeoutMs: GIT_TIMEOUT_MS, stdoutLimitBytes: GIT_OUTPUT_LIMIT });
+    if (ran.kind === 'complete')
+        return ran.stdout;
+    if (ran.code === ENVIRONMENT_CODES.EXECUTION_STEP_FAILED) {
+        // A repository made with `sibling add --create` has no commit yet, so it has no history to read.
+        if (args[0] === 'log' && /does not have any commits yet/.test(ran.stderr))
+            return '';
+        const refused = gitRepositoryRefusal(Buffer.from(ran.stderr));
+        throw new EvidenceUnavailable(refused.kind === 'not-a-repository' ? `${root} is not a Git repository` : `${command}: ${redactSensitiveMessage(refused.reason) ?? 'Git printed text that could not be redacted, so it is withheld'}`);
+    }
+    throw new EvidenceUnavailable(ran.code === ENVIRONMENT_CODES.EXECUTION_STDOUT_LIMIT
+        ? `${command} printed more than ${GIT_OUTPUT_LIMIT} bytes` : `${command} did not complete (${ran.detail})`);
+}
+function read(root, path) {
+    let bytes;
+    try {
+        bytes = readBoundedFile(resolve(root, path), DOCUMENT_LIMIT);
+    }
+    catch (error) {
+        throw new EvidenceUnavailable(`${path} could not be read (${errorCause(error)})`);
+    }
+    if (bytes.kind === 'too-large')
+        throw new EvidenceUnavailable(`${path} is larger than ${DOCUMENT_LIMIT} bytes`);
+    // Fatal decoding throws only for invalid UTF-8.
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(bytes.bytes);
+    }
+    catch {
+        throw new EvidenceUnavailable(`${path} is not valid UTF-8`);
+    }
+}
+function present(root, path) {
+    try {
+        return lstatIfPresentSync(resolve(root, path)) !== undefined;
+    }
+    catch (error) {
+        throw new EvidenceUnavailable(`${path} could not be inspected (${errorCause(error)})`);
+    }
+}
+function removedPaths(output) {
+    try {
+        return parseRemovedPaths(output);
+    }
+    catch (error) {
+        throw new EvidenceUnavailable(error.message);
+    }
+}
+// `<slug>:path` names a sibling's repository; a bare path names the cockpit's own, keyed ''.
+function split(reference) {
+    const { slug, path } = splitRepositoryPath(reference);
+    return { repository: slug ?? '', path };
+}
+export async function runDocsCheck(input, dependencies) {
+    const loaded = await loadCockpitConfig(input.configPath);
+    if (loaded.kind !== 'complete')
+        return loaded;
+    const { config, source } = loaded.result;
+    const docs = config.docs;
+    if (docs === undefined) {
+        return refusalOutcome('DOCS_NOT_DECLARED', `${source.path} has no [docs] table, so there are no living documents or decision records to check`, 'docs', 'add a [docs] table to cockpit.toml: living = ["README.md", "docs/**/*.md"] lists the documents that must stay true, and the optional decisions = "docs/adr" and decisions_index = "docs/adr/README.md" name the decision records and their index; then rerun npx --no cockpit docs check --config <your cockpit.toml>');
+    }
+    const runner = await createGitRunner(input.env, dependencies.execute);
+    if ('unavailable' in runner) {
+        return refusalOutcome(ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE, `docs check reads repository history with Git, which is unavailable: ${runner.unavailable}`, 'git', 'install Git or put it on PATH, then rerun npx --no cockpit docs check --config <your cockpit.toml>');
+    }
+    const cockpitRoot = posix.dirname(source.path);
+    // A sibling `cockpit use` serves from another checkout is checked there, where the stack runs it.
+    const served = await loadServedSiblings(cockpitRoot, config);
+    if (served.kind !== 'complete')
+        return { status: 2, diagnostics: [served.diagnostic], result: null };
+    const gone = await missingServedCheckout(served.siblings);
+    if (gone)
+        return { status: 2, diagnostics: [gone], result: null };
+    const rootOf = (repository) => repository === '' ? cockpitRoot : servedPath(served.siblings, repository);
+    const decisions = docs.decisions === undefined ? undefined : split(docs.decisions);
+    const living = docs.living.map(split);
+    const repositories = [...new Set([...living.map(entry => entry.repository), ...decisions ? [decisions.repository] : []])];
+    const checked = await Promise.all(repositories.map(repository => checkRepository({
+        repository, root: rootOf(repository), runner,
+        globs: living.filter(entry => entry.repository === repository).map(entry => entry.path),
+        ...decisions?.repository === repository ? { decisions: { directory: decisions.path,
+                ...docs.decisions_index === undefined ? {} : { index: split(docs.decisions_index).path } } } : {},
+    })));
+    // Joined in declaration order, so the report does not depend on which repository Git answered first.
+    const findings = checked.flatMap(row => row.findings);
+    return { status: findings.length === 0 ? 0 : 2, diagnostics: findings,
+        result: { repositories: checked.map(row => row.summary), findings: findings.length } };
+}
+async function checkRepository(input) {
+    const { repository, root, globs } = input;
+    const prefix = repository === '' ? '' : `${repository}:`;
+    const findings = [];
+    const unavailable = (error) => {
+        if (!(error instanceof EvidenceUnavailable))
+            throw error;
+        findings.push({ severity: 'error', code: ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE,
+            message: `the documents in ${repository === '' ? 'the cockpit repository' : `sibling ${repository}`} could not be checked: ${error.message}`,
+            target: repository === '' ? 'docs' : `sibling:${repository}`,
+            fix: 'fix what the message names (for a missing sibling checkout, run npx --no cockpit setup --config <your cockpit.toml>), then rerun npx --no cockpit docs check --config <your cockpit.toml>' });
+    };
+    let livingDocuments = 0;
+    let decisionFiles = 0;
+    try {
+        // Untracked files that are not ignored count, so a document added in this change is checked before its commit.
+        const [listed, history] = await Promise.all([
+            git(input.runner, root, ['ls-files', '-z', '--cached', '--others', '--exclude-standard']),
+            globs.length > 0 ? Promise.all([
+                git(input.runner, root, ['log', '--relative', '--format=', '--name-status', '-z', '-M', '--diff-filter=DR']),
+                git(input.runner, root, ['log', '--relative', '-p', '--format=', '--no-color', '--no-ext-diff', '--no-textconv', '--', ...MAKEFILE_PATHSPECS]),
+            ]) : undefined,
+        ]);
+        const all = listed.split('\0').filter(Boolean);
+        const files = new Set(all);
+        const markdown = all.filter(file => MARKDOWN.test(file));
+        if (history) {
+            const [names, patch] = history;
+            for (const glob of globs) {
+                if (!markdown.some(scopeMatcher([glob]))) {
+                    findings.push({ severity: 'error', code: 'DOCS_DECLARATION_UNMATCHED', target: `${prefix}${glob}`,
+                        message: `[docs] living entry ${prefix}${glob} matches no Markdown file, so it checks nothing`,
+                        fix: 'correct the glob under [docs] living in cockpit.toml to match the documents, or remove it; then rerun npx --no cockpit docs check --config <your cockpit.toml>' });
+                }
+            }
+            const documents = [];
+            for (const path of markdown.filter(scopeMatcher(globs)).sort()) {
+                let body;
+                try {
+                    body = read(root, path);
+                }
+                catch (error) {
+                    unavailable(error);
+                    continue;
+                }
+                // The walker throws only for an HTML comment that never closes.
+                try {
+                    documents.push({ path, walked: walkMarkdownProse(body) });
+                }
+                catch (error) {
+                    unavailable(new EvidenceUnavailable(`${path}: ${error.message}`));
+                }
+            }
+            livingDocuments = documents.length;
+            const current = makeTargets(all.filter(file => MAKEFILE.test(file)).flatMap(file => read(root, file).split('\n')));
+            findings.push(...staleReferences({ repository: prefix, documents, files, targets: current, present: path => present(root, path),
+                history: { removed: removedPaths(names), targets: historicalMakeTargets(patch) } }));
+        }
+        if (input.decisions) {
+            const directory = posix.normalize(input.decisions.directory).replace(/\/$/, '');
+            const index = input.decisions.index === undefined ? undefined : posix.normalize(input.decisions.index);
+            const records = markdown.filter(file => posix.dirname(file) === directory);
+            const missing = records.length === 0 ? { target: directory, message: `[docs] decisions ${prefix}${directory} holds no Markdown file` }
+                : index !== undefined && !files.has(index) ? { target: index, message: `[docs] decisions_index ${prefix}${index} does not exist` } : undefined;
+            if (missing) {
+                findings.push({ severity: 'error', code: 'DOCS_DECLARATION_UNMATCHED',
+                    target: `${prefix}${missing.target}`, message: `${missing.message}, so it checks nothing`,
+                    fix: 'correct decisions or decisions_index under [docs] in cockpit.toml to the directory of decision records and the file that lists them, or remove the key; then rerun npx --no cockpit docs check --config <your cockpit.toml>' });
+            }
+            else {
+                decisionFiles = records.length;
+                findings.push(...inspectDecisionRecords({ repository: prefix, directory,
+                    files: new Map(records.map(name => [posix.basename(name), read(root, name)])),
+                    ...index === undefined ? {} : { index: { path: index, body: read(root, index) } } }));
+            }
+        }
+    }
+    catch (error) {
+        unavailable(error);
+    }
+    return { summary: { repository: repository === '' ? '.' : repository, root, livingDocuments, decisionFiles }, findings };
+}

package/dist/docs/decision-record.d.ts

@@ -0,0 +1,34 @@
+/** Whether a record file is named by date, and so carries no number. */
+export declare const isDatedRecordName: (name: string) => boolean;
+/** The digits a record file is numbered by, or undefined for a dated or unnumbered name. */
+export declare function recordNumber(name: string): string | undefined;
+/** The first word of a status, lowercased: `accepted` for "**Accepted** (2026-01-02)". */
+export declare function leadingWord(value: string): string;
+type SupersedesReference = Readonly<{
+    line: number;
+    text: string;
+    full: boolean;
+    number?: number;
+    file?: string;
+}>;
+/** Where a status is stated: a front-matter field, a `Status:` line, or the line under a `## Status` heading. */
+type RecordStatus = Readonly<{
+    line: number;
+    value: string;
+    form: 'front-matter' | 'line' | 'heading';
+}>;
+export interface ParsedRecord {
+    readonly status?: RecordStatus;
+    readonly supersedes: readonly SupersedesReference[];
+}
+/** A record's status and supersedes references, or why it cannot be read. `name` is its path inside the records' directory. */
+export declare function parseDecisionRecord(name: string, body: string): ParsedRecord | Readonly<{
+    unreadable: string;
+}>;
+/**
+ * The record's text with its status set to `status`, where `parseDecisionRecord` finds it and in the
+ * same form; undefined when the record states no status, or states it on a line this cannot rewrite
+ * in place (one an HTML comment shares).
+ */
+export declare function withStatus(text: string, status: string): string | undefined;
+export {};

package/dist/docs/decision-record.js

@@ -0,0 +1,135 @@
+// The grammar of one decision record: how its file name numbers it, where its status is stated and
+// which records it supersedes. `docs check` reads records with it and `work decide` writes them with
+// it, so a record one accepts is a record the other can number and mark superseded.
+import { posix } from 'node:path';
+import { parseDocument } from 'yaml';
+import { resolveLinkTarget, walkMarkdownProse } from './markdown.js';
+// Dated names (2026-09-<slug>.md) order by date and carry no number to collide.
+const DATED = /^(?:19|20)\d{2}-\d{2}(?:-\d{2})?(?=[-_.])/;
+const NUMBERED = /^(\d+)(?=[-_. ])/;
+const STATUS_LINE = /^(\s*(?:[-*]\s+)?(?:\*\*|__)?status(?:\*\*|__)?\s*:\s*(?:\*\*|__)?\s*)(.*)$/i;
+const STATUS_HEADING = /^#{1,6}\s+status\s*$/i;
+const FRONT_MATTER_STATUS = /^(status\s*:\s*)/i;
+const KEYWORD = /\b(supersedes|superseded\s+by)\b/gi;
+// A link (rewritten to [[target]]), a file name, `ADR-12`, `#12`, or a zero-padded `of 0012`; a bare
+// number counts only right after the keyword, so a year later in the sentence is not read as a record.
+const REFERENCE = /\[\[([^\]]+)\]\]|(?:\b(?:adr|decision|record)s?[-\s]?#?|#|\b(?:of|in)\s+(?=0))(\d{1,5})\b|([\w./-]+\.md)\b/gi;
+/** Whether a record file is named by date, and so carries no number. */
+export const isDatedRecordName = (name) => DATED.test(name);
+/** The digits a record file is numbered by, or undefined for a dated or unnumbered name. */
+export function recordNumber(name) {
+    return DATED.test(name) ? undefined : NUMBERED.exec(name)?.[1];
+}
+/** The first word of a status, lowercased: `accepted` for "**Accepted** (2026-01-02)". */
+export function leadingWord(value) {
+    return value.replace(/[*_`[\]]/g, '').trim().split(/[\s,.;:()]/, 1)[0].toLowerCase();
+}
+// A link becomes [[target]] so its target survives as one token; code spans keep their text.
+function referenceText(prose) {
+    return prose.replace(/\[([^\]]*)\]\(([^)\s]*)[^)]*\)/g, (_match, _label, target) => ` [[${target}]] `).replace(/`/g, ' ');
+}
+function referencesIn(line, text, record) {
+    const found = [];
+    const keywords = [...text.matchAll(KEYWORD)];
+    keywords.forEach((keyword, position) => {
+        const start = keyword.index + keyword[0].length;
+        // The clause the keyword governs: up to the next keyword, a semicolon or a sentence end.
+        const end = Math.min(keywords[position + 1]?.index ?? text.length, ...[/;/, /\.(?:\s|$)/].map(pattern => { const at = text.slice(start).search(pattern); return at === -1 ? text.length : start + at; }));
+        const clause = text.slice(start, end);
+        const outgoing = keyword[1].toLowerCase() === 'supersedes';
+        // "Supersedes 0012" names the whole record; "supersedes the cache clause of 0012" only a part.
+        // A number that runs on into a name (`2026-09-cache.md`, `0012-x.md`) is a file name, read below.
+        const bare = /^\s*:?\s*(\d{1,5})\b(?![-.]\w)/.exec(clause);
+        const leading = /^\s*:?\s*(?:\[\[|(?:adr|decision|record)s?\b|#|[\w./-]+\.md\b)/i.test(clause) || bare !== null;
+        // "Supersedes 0012 (ADR-0012)" names one record twice; it is one reference.
+        const add = (reference, text) => {
+            if (!found.some(row => row.number === reference.number && row.file === reference.file))
+                found.push({ line, text, full: outgoing && leading, ...reference });
+        };
+        if (bare)
+            add({ number: Number(bare[1]) }, bare[1]);
+        for (const match of clause.matchAll(REFERENCE)) {
+            const target = match[1] ?? match[3];
+            if (target !== undefined) {
+                const file = resolveLinkTarget(posix.dirname(record), target);
+                if (file?.endsWith('.md'))
+                    add({ file }, target);
+            }
+            else
+                add({ number: Number(match[2]) }, match[0].trim());
+        }
+    });
+    return found;
+}
+/** A record's status and supersedes references, or why it cannot be read. `name` is its path inside the records' directory. */
+export function parseDecisionRecord(name, body) {
+    let walked;
+    try {
+        walked = walkMarkdownProse(body);
+    }
+    catch (error) {
+        return { unreadable: error.message };
+    }
+    const rows = body.split(/\r?\n/);
+    let status;
+    const supersedes = [];
+    if (rows[0] === '---') {
+        const end = rows.indexOf('---', 1);
+        const front = rows.slice(1, end === -1 ? 1 : end);
+        const parsed = parseDocument(front.join('\n'));
+        if (parsed.errors.length > 0)
+            return { unreadable: `its front matter is not valid YAML (${parsed.errors[0].message.split('\n', 1)[0]})` };
+        const data = parsed.toJS();
+        if (data && typeof data === 'object') {
+            if (typeof data.status === 'string') {
+                // Counted from the opening `---`; 0 where the field is not written on a line of its own.
+                const at = front.findIndex(row => FRONT_MATTER_STATUS.test(row));
+                status = { line: at === -1 ? 0 : at + 2, value: data.status, form: 'front-matter' };
+            }
+            for (const [field, text] of [['supersedes', 'Supersedes'], ['superseded_by', 'Superseded by']]) {
+                for (const value of [data[field]].flat()) {
+                    if (typeof value === 'string' || typeof value === 'number') {
+                        supersedes.push(...referencesIn(rows.findIndex(row => row.startsWith(`${field}:`)) + 1, `${text} ${value}`, name));
+                    }
+                }
+            }
+        }
+    }
+    walked.lines.forEach((row, position) => {
+        const prose = row.prose;
+        if (status === undefined) {
+            const line = STATUS_LINE.exec(prose);
+            if (line && line[2].trim() !== '')
+                status = { line: row.line, value: line[2], form: 'line' };
+            else if (STATUS_HEADING.test(prose)) {
+                const next = walked.lines.slice(position + 1).find(candidate => candidate.prose.trim() !== '');
+                if (next && !/^#/.test(next.prose))
+                    status = { line: next.line, value: next.prose, form: 'heading' };
+            }
+        }
+        supersedes.push(...referencesIn(row.line, referenceText(prose), name));
+    });
+    return { ...status ? { status } : {}, supersedes };
+}
+/**
+ * The record's text with its status set to `status`, where `parseDecisionRecord` finds it and in the
+ * same form; undefined when the record states no status, or states it on a line this cannot rewrite
+ * in place (one an HTML comment shares).
+ */
+export function withStatus(text, status) {
+    const parsed = parseDecisionRecord('', text);
+    if ('unreadable' in parsed || parsed.status === undefined)
+        return undefined;
+    const rows = text.split('\n');
+    const index = parsed.status.line - 1;
+    const row = rows[index];
+    if (row === undefined)
+        return undefined;
+    const ending = row.endsWith('\r') ? '\r' : '';
+    const raw = ending ? row.slice(0, -1) : row;
+    const prefix = parsed.status.form === 'heading' ? '' : (parsed.status.form === 'line' ? STATUS_LINE : FRONT_MATTER_STATUS).exec(raw)?.[1];
+    if (prefix === undefined)
+        return undefined;
+    rows[index] = `${prefix}${status}${ending}`;
+    return rows.join('\n');
+}

package/dist/docs/decisions.d.ts

@@ -0,0 +1,16 @@
+import { type Diagnostic } from '../environment/contract.js';
+interface DecisionRecordSet {
+    /** Prefixed onto every reported path: '' in the cockpit's own repository, `<slug>:` in a sibling. */
+    readonly repository: string;
+    /** The records' directory, relative to the repository root. */
+    readonly directory: string;
+    /** Each Markdown file directly inside the directory, by file name. */
+    readonly files: ReadonlyMap<string, string>;
+    readonly index?: Readonly<{
+        path: string;
+        body: string;
+    }>;
+}
+/** Every integrity finding in one decision-record set. Index and template files are not records. */
+export declare function inspectDecisionRecords(set: DecisionRecordSet): Diagnostic[];
+export {};

package/dist/docs/decisions.js

@@ -0,0 +1,103 @@
+// The integrity of a decision-record set: numbering, the index, statuses and supersedes links.
+// Decision records drift in ways nothing else notices: concurrent branches each take the next
+// free number, a record lands without an index line, and a record superseded in full keeps
+// reading "Accepted" because only the newer one was edited.
+import { posix } from 'node:path';
+import { ENVIRONMENT_CODES } from '../environment/contract.js';
+import { leadingWord, parseDecisionRecord, recordNumber } from './decision-record.js';
+import { resolveLinkTarget, walkMarkdownProse } from './markdown.js';
+const DECISION_STATUSES = ['proposed', 'accepted', 'superseded', 'deprecated', 'rejected'];
+const numberOf = (name) => { const digits = recordNumber(name); return digits === undefined ? undefined : Number(digits); };
+/** Every integrity finding in one decision-record set. Index and template files are not records. */
+export function inspectDecisionRecords(set) {
+    const findings = [];
+    const at = (name, line) => `${set.repository}${posix.join(set.directory, name)}${line ? `:${line}` : ''}`;
+    const indexName = set.index && posix.dirname(set.index.path) === set.directory ? posix.basename(set.index.path) : undefined;
+    // A README or index page lists the records, and a template is the shape of one; neither decides anything.
+    const names = [...set.files.keys()].filter(name => name !== indexName && !/^(?:readme|index)\.md$/i.test(name) && !/template/i.test(name)).sort();
+    const records = new Map();
+    for (const name of names) {
+        const parsed = parseDecisionRecord(name, set.files.get(name));
+        if ('unreadable' in parsed) {
+            findings.push({ severity: 'error', code: ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE,
+                message: `decision record ${at(name)} could not be read: ${parsed.unreadable}`, target: at(name),
+                fix: 'correct the record so it parses as Markdown with optional YAML front matter, then rerun npx --no cockpit docs check --config <your cockpit.toml>' });
+            continue;
+        }
+        records.set(name, parsed);
+    }
+    const byNumber = new Map();
+    for (const name of names) {
+        const number = numberOf(name);
+        if (number !== undefined)
+            byNumber.set(number, [...byNumber.get(number) ?? [], name]);
+    }
+    for (const [number, shared] of byNumber) {
+        if (shared.length < 2)
+            continue;
+        // Not "_DUPLICATE": the CLI reads that suffix as a repeated option and prints a usage hint.
+        findings.push({ severity: 'error', code: 'DECISION_NUMBER_REUSED', target: at(shared[1]),
+            message: `decision records ${shared.map(name => at(name)).join(' and ')} share number ${number}`,
+            fix: 'renumber the later record to the next free number, then update the index and every supersedes line that cites it' });
+    }
+    for (const [name, record] of records) {
+        const status = record.status === undefined ? undefined : leadingWord(record.status.value);
+        if (!DECISION_STATUSES.some(known => known === status)) {
+            findings.push({ severity: 'error', code: 'DECISION_STATUS_MISSING', target: at(name, record.status?.line),
+                message: record.status === undefined ? `decision record ${at(name)} states no status`
+                    : `decision record ${at(name)} has status "${record.status.value.trim()}", which starts with none of ${DECISION_STATUSES.join(', ')}`,
+                fix: `give the record a status line such as "Status: Accepted", or status: accepted in its front matter, starting with one of ${DECISION_STATUSES.join(', ')}` });
+        }
+        for (const reference of record.supersedes) {
+            const target = reference.file !== undefined
+                ? posix.dirname(reference.file) === '.' && records.has(reference.file) ? reference.file : undefined
+                : names.find(candidate => numberOf(candidate) === reference.number);
+            if (target === undefined) {
+                findings.push({ severity: 'error', code: 'DECISION_LINK_UNRESOLVED', target: at(name, reference.line),
+                    message: `decision record ${at(name, reference.line)} cites ${reference.text}, which names no record in ${set.repository}${set.directory}`,
+                    fix: 'correct the number or link to name an existing record, or restore the record it names' });
+                continue;
+            }
+            const superseded = records.get(target)?.status;
+            // Only an accepted record replaces another; a proposed or rejected one leaves it standing.
+            if (reference.full && ['accepted', 'superseded', 'deprecated'].includes(status ?? '') && superseded && leadingWord(superseded.value) === 'accepted') {
+                findings.push({ severity: 'error', code: 'DECISION_SUPERSEDED_STALE', target: at(target, superseded.line),
+                    message: `decision record ${at(target)} still has status "${superseded.value.trim()}", but ${at(name, reference.line)} supersedes it`,
+                    fix: `change the superseded record's status to "Superseded by" the newer record; if only part of it is replaced, say which part in the newer record's supersedes line, such as "supersedes the retry clause of ${target}"` });
+            }
+        }
+    }
+    if (set.index) {
+        let links;
+        try {
+            links = walkMarkdownProse(set.index.body).links;
+        }
+        catch (error) {
+            findings.push({ severity: 'error', code: ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE,
+                message: `decision index ${set.repository}${set.index.path} could not be read: ${error.message}`, target: `${set.repository}${set.index.path}`,
+                fix: 'close the HTML comment the message names, then rerun npx --no cockpit docs check --config <your cockpit.toml>' });
+            return findings;
+        }
+        const linked = new Set();
+        for (const link of links) {
+            const resolved = resolveLinkTarget(posix.dirname(set.index.path), link.target);
+            if (resolved === undefined || !resolved.endsWith('.md') || posix.dirname(resolved) !== set.directory)
+                continue;
+            const name = posix.basename(resolved);
+            linked.add(name);
+            if (!set.files.has(name)) {
+                findings.push({ severity: 'error', code: 'DECISION_INDEX_ENTRY_MISSING', target: `${set.repository}${set.index.path}:${link.line}`,
+                    message: `decision index ${set.repository}${set.index.path}:${link.line} links ${link.target}, which does not exist`,
+                    fix: 'correct the link to the record\'s current file name, or remove the entry if the record was deleted on purpose' });
+            }
+        }
+        for (const name of names) {
+            if (linked.has(name))
+                continue;
+            findings.push({ severity: 'error', code: 'DECISION_UNINDEXED', target: at(name),
+                message: `decision record ${at(name)} is not linked from ${set.repository}${set.index.path}`,
+                fix: 'add a line linking the record to the decision index' });
+        }
+    }
+    return findings;
+}