@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/diagnostics.js

@@ -0,0 +1,344 @@
+import { snapshotJson } from './environment/contract.js';
+import { admitDiagnosticFix, bindConfigPath, cockpitCommand, initCommand } from './fix-catalogue.js';
+const COMMON_REFUSAL_GUIDANCE = Object.freeze({
+    INIT_CANONICAL_OWNERSHIP_MISSING: Object.freeze({
+        why: 'init cannot safely resume when its recorded bootstrap state and generated ownership disagree',
+        fix: `restore the committed ownership metadata, then rerun ${initCommand()} with the root, target and options you ran it with`,
+    }),
+    SURFACE_SOURCE_UNAVAILABLE: Object.freeze({
+        why: 'generated instructions cannot be trusted without the declared sibling source',
+        fix: `restore the named sibling checkout at its declared path, then rerun ${cockpitCommand('sync')}`,
+    }),
+    SURFACE_OWNERSHIP_INVALID: Object.freeze({
+        why: 'cockpit cannot prove which generated settings it is allowed to replace',
+        fix: `restore the last committed generated ownership metadata, then rerun ${cockpitCommand('sync')}`,
+    }),
+    SURFACE_STATE_CONFLICT: Object.freeze({
+        why: 'sync would overwrite content that cockpit did not write',
+        fix: `for a generated file you edited, move the change into cockpit.toml or a surface overlay, then ask the person who owns the cockpit before you undo the edit or delete the file, and rerun ${cockpitCommand('sync')}; for the team's own .claude/settings.json, .codex/config.toml or .codex/hooks.json, have a human approve ${cockpitCommand('sync', { args: '--adopt <path>' })}`,
+    }),
+    GENERATED_ARTIFACT_DRIFT: Object.freeze({
+        why: 'generated files no longer match the canonical cockpit configuration',
+        fix: `run ${cockpitCommand('sync')}, then retry`,
+    }),
+    GENERATED_OWNERSHIP_INVALID: Object.freeze({
+        why: 'publication cannot safely update files without authenticated ownership metadata',
+        fix: `restore the committed ownership metadata and rerun ${cockpitCommand('sync')}`,
+    }),
+    GUARD_AUTHORITY_UNAVAILABLE: Object.freeze({
+        why: 'the guard cannot make a safe allow or deny decision without current generated authority',
+        fix: `restore cockpit.toml and the generated guard files, then have a human run ${cockpitCommand('sync')}`,
+    }),
+    GUARD_REFUSED: Object.freeze({
+        why: 'the requested command is outside the current cockpit guard policy',
+        fix: `follow the refusal reason or ask a human to change cockpit.toml and run ${cockpitCommand('sync')}`,
+    }),
+    RUNTIME_UNAVAILABLE: Object.freeze({
+        why: 'cockpit cannot start or inspect the declared environment without a container runtime it can reach and identify',
+        fix: 'start the configured container runtime and verify docker info succeeds, then retry',
+    }),
+    RUNTIME_UNMEASURED: Object.freeze({
+        why: 'this machine has no passing measurement for the current runtime, so cockpit cannot vouch for its mounts, labels, health and teardown',
+        fix: `run ${cockpitCommand('runtime measure', { args: '--image <local-image>' })}, which records the result for this machine only, then retry`,
+    }),
+    CLAIM_CO_TENANT: Object.freeze({
+        why: 'another holder still owns or is using the same stack',
+        fix: `for a failed up attempt, run ${cockpitCommand('up')} to resume or ${cockpitCommand('down')} to release; otherwise end each cockpit session the message names (let its command finish, or stop the named process), then retry; a session whose process is gone is released by the next up, sleep, down or reset`,
+    }),
+    PORT_FAMILY_COLLISION: Object.freeze({
+        why: 'one or more ports selected for this stack are already in use',
+        fix: 'stop the named listener or release the inactive stack, then retry',
+    }),
+    PORT_LEASE_EXHAUSTED: Object.freeze({
+        why: 'every declared port family is leased or occupied',
+        fix: 'release an inactive stack or extend ports.count after checking host capacity',
+    }),
+    SETUP_MANUAL_MISSING: Object.freeze({
+        why: 'a manually managed sibling must already exist before cockpit can wire it',
+        fix: `create the named checkout at its declared path, then run ${cockpitCommand('setup')} again`,
+    }),
+    SETUP_REMOTE_MISMATCH: Object.freeze({
+        why: 'rewiring an existing checkout to a different repository could replace the wrong source',
+        fix: `correct the checkout remote or the sibling declaration, then run ${cockpitCommand('setup')} again`,
+    }),
+    SETUP_REMOTE_UNRESOLVABLE: Object.freeze({
+        why: 'a relative local remote that cannot be resolved cannot be compared with, or cloned into, a checkout',
+        fix: `make the remote path readable or declare an absolute path or URL, then run ${cockpitCommand('setup')} again`,
+    }),
+});
+// Command-line mistakes (as opposed to failed work) get a pointer to the relevant --help.
+const USAGE_ERROR_CODE = /^CLI_(?:USAGE_INVALID|UNKNOWN_COMMAND|COMMAND_REQUIRED)$|_(?:DUPLICATE|UNSUPPORTED)$/;
+function escapeForTerminal(value) {
+    return value.replace(/[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u2028-\u202e\u2066-\u2069]/g, (character) => {
+        if (/[\u0080-\u009f\u061c\u200e\u200f\u2028-\u202e\u2066-\u2069]/.test(character)) {
+            return `\\u${character.codePointAt(0).toString(16).padStart(4, '0')}`;
+        }
+        const escaped = JSON.stringify(character);
+        return escaped.slice(1, -1);
+    });
+}
+function terminalSafeJson(value, space) {
+    // JSON already escapes C0; the remaining terminal controls must retain their JSON value.
+    return JSON.stringify(value, null, space).replace(/[\u007f-\u009f\u061c\u200e\u200f\u2028-\u202e\u2066-\u2069]/g, (character) => `\\u${character.codePointAt(0).toString(16).padStart(4, '0')}`);
+}
+function humanLines(value, depth) {
+    const indent = '  '.repeat(depth);
+    if (value === null)
+        return [`${indent}none`];
+    if (typeof value === 'string')
+        return [`${indent}${escapeForTerminal(value)}`];
+    if (typeof value === 'boolean' || typeof value === 'number')
+        return [`${indent}${String(value)}`];
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return [`${indent}(none)`];
+        return value.flatMap((item) => {
+            if (item === null || typeof item !== 'object') {
+                const [line] = humanLines(item, 0);
+                return [`${indent}- ${line}`];
+            }
+            return [`${indent}-`, ...humanLines(item, depth + 1)];
+        });
+    }
+    const entries = Object.entries(value);
+    if (entries.length === 0)
+        return [`${indent}(none)`];
+    return entries.flatMap(([key, item]) => {
+        const label = `${indent}${escapeForTerminal(key)}:`;
+        if (item === null || typeof item !== 'object') {
+            const [line] = humanLines(item, 0);
+            return [`${label} ${line}`];
+        }
+        return [label, ...humanLines(item, depth + 1)];
+    });
+}
+export function renderHumanValue(value) {
+    const captured = snapshotJson(value);
+    return captured === undefined ? 'Result is not available as bounded human-readable text.\n'
+        : `${humanLines(captured, 0).join('\n')}\n`;
+}
+function projectDiagnostics(input, context) {
+    const diagnostics = new Map();
+    const guidance = new Map();
+    for (const source of input) {
+        const { severity, code, target, fix } = source;
+        const admitted = admitDiagnosticFix(source, context);
+        const identity = { code, ...(target === undefined ? {} : { target }) };
+        const message = bindConfigPath(source.message, context);
+        const diagnostic = { severity, ...identity, message, ...(admitted ? { fix: admitted.command } : {}) };
+        diagnostics.set(JSON.stringify(diagnostic), diagnostic);
+        if (fix !== undefined && !admitted) {
+            const row = { ...identity, text: bindConfigPath(fix, context) };
+            guidance.set(JSON.stringify(row), row);
+        }
+        else if (fix === undefined && Object.prototype.hasOwnProperty.call(COMMON_REFUSAL_GUIDANCE, code)) {
+            const row = { ...identity, text: bindConfigPath(COMMON_REFUSAL_GUIDANCE[code].fix, context) };
+            guidance.set(JSON.stringify(row), row);
+        }
+    }
+    return { diagnostics: [...diagnostics.values()], guidance: [...guidance.values()] };
+}
+// What each lifecycle `change` means to the person who ran the command; `--json` keeps the raw value.
+const LIFECYCLE_CHANGES = Object.freeze({
+    up: Object.freeze({ started: 'Stack started', resumed: 'Stack resumed', unchanged: 'Stack already running' }),
+    sleep: Object.freeze({
+        stopped: 'Stack stopped',
+        retained: "Released this checkout's hold; another holder keeps the stack running",
+        unchanged: 'Nothing to stop: no session holds the stack',
+    }),
+    down: Object.freeze({ removed: 'Stack removed' }),
+    reset: Object.freeze({ unchanged: 'Nothing to reset' }),
+});
+function resetTargetLines(targets) {
+    return targets.map(({ kind, identity, declaration }) => `  ${escapeForTerminal(`${String(kind)} ${String(identity)}${declaration === identity ? '' : ` (${String(declaration)})`}`)}\n`).join('');
+}
+// A successful up, sleep, down or preflight printed nothing in human mode, so a person could not
+// tell success from a command that never ran. One line says what happened; anything outside the
+// known result shape prints nothing rather than a guess.
+function lifecycleSummary(command, result) {
+    if (command === 'preflight') {
+        if (typeof result.verdict !== 'string' || !Array.isArray(result.checks))
+            return '';
+        const counts = new Map();
+        for (const check of result.checks) {
+            const verdict = String(check?.verdict).replaceAll('-', ' ');
+            counts.set(verdict, (counts.get(verdict) ?? 0) + 1);
+        }
+        const tally = [...counts].map(([verdict, count]) => `${count} ${verdict === 'pass' ? count === 1 ? 'check passes' : 'checks pass' : verdict}`);
+        return escapeForTerminal(`Preflight ${result.verdict === 'pass' ? 'passed' : result.verdict}: ${tally.join(', ') || 'no checks'}.`) + '\n';
+    }
+    // A plain reset only previews; printing nothing left a person unable to tell an empty plan from
+    // one that would delete their data volume.
+    if (command === 'reset' && typeof result.planDigest === 'string' && Array.isArray(result.targets)) {
+        if (typeof result.stackId !== 'string')
+            return '';
+        const targets = result.targets;
+        if (targets.length === 0)
+            return `${escapeForTerminal(`Nothing to reset (${result.stackId}).`)}\n`;
+        return `${escapeForTerminal(`Reset would remove ${targets.length} ${targets.length === 1 ? 'target' : 'targets'} (${result.stackId}); plan ${result.planDigest}:`)}\n`
+            + `${resetTargetLines(targets)}Nothing was changed. To apply this plan, run the same command with --interactive and approve it.\n`;
+    }
+    // An applied reset printed nothing, so a person could not tell that their data was gone.
+    if (command === 'reset' && result.change === 'reset' && Array.isArray(result.targets)) {
+        if (typeof result.stackId !== 'string')
+            return '';
+        const targets = result.targets;
+        return `${escapeForTerminal(`Reset removed ${targets.length} ${targets.length === 1 ? 'target' : 'targets'} (${result.stackId}):`)}\n`
+            + 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')
+        return '';
+    const cold = result.coldStart;
+    const timing = typeof cold?.measuredMillis === 'number' && typeof cold.limitMillis === 'number'
+        ? `; cold start ${(cold.measuredMillis / 1000).toFixed(1)}s of the ${Math.round(cold.limitMillis / 1000)}s limit` : '';
+    const entrypoints = Array.isArray(result.entrypoints) ? result.entrypoints
+        .filter(({ name, value }) => typeof name === 'string' && typeof value === 'string')
+        .map(({ name, value }) => `  ${escapeForTerminal(String(name))}: ${escapeForTerminal(String(value))}\n`) : [];
+    return `${escapeForTerminal(`${headline} (${result.stackId})${timing}.`)}\n${entrypoints.join('')}`;
+}
+function plural(count, one, many = `${one}s`) {
+    return `${count} ${count === 1 ? one : many}`;
+}
+// Doctor's full result is a structured report for scripts; printed whole it buried the findings
+// under thousands of lines. A person gets one line per area and the commands that show the detail.
+function doctorSummary(result, diagnostics, fixContext) {
+    if (typeof result.verdict !== 'string' || !Array.isArray(result.checks))
+        return renderHumanValue(result);
+    const lines = [];
+    const errors = diagnostics.filter(({ severity }) => severity === 'error').length;
+    const warnings = diagnostics.filter(({ severity }) => severity === 'warning').length;
+    const findings = [errors > 0 ? plural(errors, 'error') : '', warnings > 0 ? plural(warnings, 'warning') : ''].filter(Boolean);
+    lines.push(`Doctor: ${result.verdict}. ${findings.length === 0 ? 'No findings.' : `Findings: ${findings.join(' and ')}, listed below.`}`);
+    const tally = new Map();
+    for (const check of result.checks) {
+        const verdict = String(check?.verdict).replaceAll('-', ' ');
+        tally.set(verdict, (tally.get(verdict) ?? 0) + 1);
+    }
+    lines.push(`Checks: ${[...tally].map(([verdict, count]) => `${count} ${verdict}`).join(', ') || 'none ran'}.`);
+    if (Array.isArray(result.comparisons) && result.comparisons.length > 0)
+        lines.push(`Remote comparisons: ${result.comparisons.length}.`);
+    const freshness = result.freshness;
+    if (freshness?.local) {
+        const changes = Array.isArray(freshness.changes) ? freshness.changes.length : 0;
+        const refused = freshness.local.kind !== 'complete' && Array.isArray(freshness.local.diagnostics)
+            ? freshness.local.diagnostics.map(({ code }) => String(code)) : [];
+        lines.push(`Generated files: ${refused.length > 0 ? `check refused (${refused.join(', ')})`
+            : changes === 0 ? 'current' : `${plural(changes, 'change')} pending`}.`);
+    }
+    const overrides = result.surfaceOverrides;
+    if (overrides?.kind === 'complete' && Array.isArray(overrides.activeOverrides) && Array.isArray(overrides.changedOverrideOriginals)) {
+        const active = overrides.activeOverrides.map(({ name }) => String(name));
+        const changed = overrides.changedOverrideOriginals.map(({ name }) => String(name));
+        lines.push(`Surface overrides: ${active.length === 0 ? 'none' : `${active.length} active (${active.join(', ')})`}`
+            + `${changed.length === 0 ? '' : `; ${changed.length} changed upstream (${changed.join(', ')})`}.`);
+    }
+    else if (overrides)
+        lines.push(`Surface overrides: not inspected (${String(overrides.code)}).`);
+    if (Array.isArray(result.declarations) && result.declarations.length > 0) {
+        const rows = result.declarations;
+        const named = (state) => rows.filter(row => row.state === state).map(row => String(row.subject).replaceAll('-', ' '));
+        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)) {
+        const gaps = readiness.gaps;
+        const clear = Array.isArray(readiness.noFinding) ? readiness.noFinding.length : 0;
+        lines.push(`Readiness: ${gaps.length === 0 ? 'no gaps' : plural(gaps.length, 'gap')}; ${plural(clear, 'other prerequisite')} with no finding.`);
+        for (const gap of gaps) {
+            const codes = Array.isArray(gap.findings) ? [...new Set(gap.findings.map(({ code }) => String(code)))] : [];
+            lines.push(`  ${String(gap.level)} ${String(gap.id)}: ${String(gap.needs)} (${codes.join(', ')})`);
+        }
+    }
+    const release = freshness?.release;
+    if (release?.kind === 'known') {
+        lines.push(`Release: ${release.currency === 'same-version' ? `${String(release.installedVersion)} is the latest`
+            : `${String(release.latestVersion)} is published; ${String(release.installedVersion)} is installed`}.`);
+    }
+    else if (release?.kind === 'unknown')
+        lines.push(`Release: unknown (${String(release.reason)}).`);
+    lines.push(`Full report: ${bindConfigPath(cockpitCommand('doctor', { args: '--json' }), fixContext)}`);
+    lines.push(`Generated file detail: ${bindConfigPath(cockpitCommand('check'), fixContext)}`);
+    return `${lines.map(escapeForTerminal).join('\n')}\n`;
+}
+export function renderHumanDiagnostics(diagnostics, review, fixContext, usageHint) {
+    if (review) {
+        const { command, outcome } = review;
+        if (outcome.result === null || typeof outcome.result !== 'object')
+            return '';
+        // Work, grade, browser and test commands return their whole result as the answer, and an unmet gate,
+        // grade or step returns one with a failing status: the person needs that evidence either way.
+        if (command !== undefined && /^(?:(?:work|browser) |test-run$|grade$)/.test(command))
+            return renderHumanValue(outcome.result);
+        if (outcome.status !== 0)
+            return '';
+        if (command === 'sync' && 'dryRun' in outcome.result && outcome.result.dryRun === true
+            && 'changes' in outcome.result && Array.isArray(outcome.result.changes)) {
+            const changes = outcome.result.changes;
+            if (!changes.every((change) => change && (change.operation === 'write' || change.operation === 'remove')
+                && typeof change.path === 'string'))
+                return '';
+            const stale = 'staleRemoval' in outcome.result ? outcome.result.staleRemoval : undefined;
+            const approval = typeof stale?.digest === 'string' && /^[a-f0-9]{64}$/.test(stale.digest)
+                ? `${escapeForTerminal(`Stale-removal digest ${stale.digest}: to approve these removals, a person runs `
+                    + `${bindConfigPath(cockpitCommand('sync', { args: '--interactive' }), fixContext)} in a terminal and types it.`)}\n` : '';
+            return (changes.length === 0 ? 'No generated changes.\n'
+                : `${changes.map((change) => `${change.operation} ${terminalSafeJson(change.path)}`).join('\n')}\n`) + approval;
+        }
+        if (command === 'logs' && 'records' in outcome.result && Array.isArray(outcome.result.records)) {
+            const records = outcome.result.records;
+            return records.length === 0 ? 'No log records.\n'
+                : `${records.map(record => escapeForTerminal(`${String(record.timestamp)} ${String(record.stream)} ${String(record.message)}`)).join('\n')}\n`;
+        }
+        if (command === 'doctor') {
+            return doctorSummary(outcome.result, outcome.diagnostics ?? [], fixContext);
+        }
+        if (command === 'selftest' || command === 'upgrade' || command === 'init' || command === 'stacks') {
+            return renderHumanValue(outcome.result);
+        }
+        return command === undefined ? '' : lifecycleSummary(command, outcome.result);
+    }
+    if (diagnostics.length === 0)
+        return '';
+    const projected = projectDiagnostics(diagnostics, fixContext);
+    const hint = usageHint !== undefined && diagnostics.some(({ code }) => USAGE_ERROR_CODE.test(code)) ? usageHint : '';
+    return `${projected.diagnostics
+        .map((diagnostic) => {
+        const target = diagnostic.target ? ` [${escapeForTerminal(diagnostic.target)}]` : '';
+        const guidance = projected.guidance.filter(row => row.code === diagnostic.code && row.target === diagnostic.target);
+        const common = Object.prototype.hasOwnProperty.call(COMMON_REFUSAL_GUIDANCE, diagnostic.code)
+            ? COMMON_REFUSAL_GUIDANCE[diagnostic.code]
+            : undefined;
+        if (common) {
+            const fix = diagnostic.fix ?? guidance[0]?.text ?? bindConfigPath(common.fix, fixContext);
+            return `${diagnostic.severity.toUpperCase()} ${escapeForTerminal(diagnostic.code)}${target}\n`
+                + `What failed: ${escapeForTerminal(diagnostic.message)}\n`
+                + `Why it matters: ${escapeForTerminal(common.why)}\n`
+                + `Fix: ${escapeForTerminal(fix)}`;
+        }
+        const fix = diagnostic.fix ? ` Fix: ${escapeForTerminal(diagnostic.fix)}` : '';
+        const renderedGuidance = guidance.map(row => ` Guidance: ${escapeForTerminal(row.text)}`).join('');
+        return `${diagnostic.severity.toUpperCase()} ${escapeForTerminal(diagnostic.code)}${target}: ${escapeForTerminal(diagnostic.message)}${fix}${renderedGuidance}`;
+    })
+        .join('\n')}\n${hint}`;
+}
+export function renderJsonResponse(outcome, fixContext) {
+    const { result, diagnostics, evidence, progress, invocation } = outcome;
+    const projected = projectDiagnostics(diagnostics, fixContext);
+    return `${terminalSafeJson({ result, diagnostics: projected.diagnostics,
+        ...(projected.guidance.length === 0 ? {} : { guidance: projected.guidance }), ...(evidence === undefined ? {} : { evidence }),
+        ...(progress === undefined ? {} : { progress }), ...(invocation === undefined ? {} : { invocation }) })}\n`;
+}

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 {};