@cleocode/contracts 2026.5.111 → 2026.5.113

package/src/docs-taxonomy.ts

@@ -98,6 +98,20 @@ export interface DocKindMetadata {
    * Built-in kinds leave this unset; extensions set it to `true`.
    */
   readonly isExtension?: boolean;
+  /**
+   * Optional list of H2 section titles that MUST appear in the document
+   * body. Validated by `validateDocBody(kind, body)` (T10160).
+   *
+   * Match is case-insensitive and tolerant of hyphen-vs-space variants
+   * (e.g. `## Next Steps` and `## next-steps` both satisfy a required
+   * section of `Next Steps`).
+   *
+   * Empty or omitted → no body schema requirements for this kind.
+   *
+   * @task T10160 (E12.C3 · absorbs T10154)
+   * @epic T10157
+   */
+  readonly requiredSections?: ReadonlyArray<string>;
 }
 
 // ---------------------------------------------------------------------------
@@ -125,6 +139,7 @@ export const BUILTIN_DOC_KINDS: ReadonlyArray<DocKindMetadata> = [
     publishDir: 'docs/adr',
     requiresEntityId: true,
     entityIdPattern: /^adr-\d{3,4}-[a-z0-9-]+$/,
+    requiredSections: ['Status', 'Date', 'Context', 'Decision', 'Consequences'],
   },
   {
     kind: 'spec',
@@ -133,6 +148,7 @@ export const BUILTIN_DOC_KINDS: ReadonlyArray<DocKindMetadata> = [
     defaultOwnerKind: 'task',
     publishDir: 'docs/spec',
     requiresEntityId: false,
+    requiredSections: ['Goal', 'Non-Goals', 'Requirements', 'Out-of-Scope'],
   },
   {
     kind: 'research',
@@ -141,6 +157,7 @@ export const BUILTIN_DOC_KINDS: ReadonlyArray<DocKindMetadata> = [
     defaultOwnerKind: 'task',
     publishDir: 'docs/research',
     requiresEntityId: false,
+    requiredSections: ['Question', 'Findings', 'Sources'],
   },
   {
     kind: 'handoff',
@@ -149,6 +166,7 @@ export const BUILTIN_DOC_KINDS: ReadonlyArray<DocKindMetadata> = [
     defaultOwnerKind: 'session',
     publishDir: 'docs/handoff',
     requiresEntityId: false,
+    requiredSections: ['Context', 'State', 'Next-Steps'],
   },
   {
     kind: 'note',
@@ -157,6 +175,7 @@ export const BUILTIN_DOC_KINDS: ReadonlyArray<DocKindMetadata> = [
     defaultOwnerKind: 'observation',
     publishDir: 'docs/note',
     requiresEntityId: false,
+    requiredSections: [],
   },
   {
     kind: 'llm-readme',
@@ -165,6 +184,7 @@ export const BUILTIN_DOC_KINDS: ReadonlyArray<DocKindMetadata> = [
     defaultOwnerKind: 'project',
     publishDir: '.',
     requiresEntityId: false,
+    requiredSections: [],
   },
   {
     kind: 'changeset',
@@ -174,6 +194,7 @@ export const BUILTIN_DOC_KINDS: ReadonlyArray<DocKindMetadata> = [
     publishDir: '.changeset',
     requiresEntityId: true,
     entityIdPattern: /^t\d+-[a-z0-9-]+$/,
+    requiredSections: [],
   },
   {
     kind: 'release-note',
@@ -183,6 +204,7 @@ export const BUILTIN_DOC_KINDS: ReadonlyArray<DocKindMetadata> = [
     publishDir: 'docs/release',
     requiresEntityId: true,
     entityIdPattern: /^v\d{4}\.\d+\.\d+(-[a-z0-9-]+)?$/,
+    requiredSections: ['Changes', 'Migration'],
   },
   {
     kind: 'plan',
@@ -191,6 +213,7 @@ export const BUILTIN_DOC_KINDS: ReadonlyArray<DocKindMetadata> = [
     defaultOwnerKind: 'task',
     publishDir: 'docs/plan',
     requiresEntityId: false,
+    requiredSections: ['Goal', 'Steps', 'Owners'],
   },
   {
     kind: 'rcasd',
@@ -200,6 +223,7 @@ export const BUILTIN_DOC_KINDS: ReadonlyArray<DocKindMetadata> = [
     publishDir: '.cleo/rcasd',
     requiresEntityId: true,
     entityIdPattern: /^t\d+(-.+)?$/,
+    requiredSections: ['Root-Cause', 'Action', 'Schedule', 'Detection'],
   },
 ];
 
@@ -253,6 +277,16 @@ export interface DocKindExtensionConfig {
    * a malformed config can't trigger pathological backtracking.
    */
   readonly entityIdPattern?: string;
+  /**
+   * Optional list of required H2 section titles for this extension kind.
+   *
+   * Same semantics as {@link DocKindMetadata.requiredSections} — matched
+   * case-insensitively with hyphen/space normalisation. Omit or pass
+   * `[]` for kinds that have no body schema.
+   *
+   * @task T10160
+   */
+  readonly requiredSections?: ReadonlyArray<string>;
 }
 
 /**
@@ -596,6 +630,25 @@ function validateExtensionEntry(
     );
   }
 
+  let requiredSections: ReadonlyArray<string> | undefined;
+  if (obj.requiredSections !== undefined) {
+    if (!Array.isArray(obj.requiredSections)) {
+      throw new DocKindConfigError(`${where}: 'requiredSections' must be an array`, source);
+    }
+    const sections: string[] = [];
+    for (let i = 0; i < obj.requiredSections.length; i++) {
+      const item = obj.requiredSections[i];
+      if (typeof item !== 'string' || item.length === 0) {
+        throw new DocKindConfigError(
+          `${where}: 'requiredSections[${i}]' must be a non-empty string`,
+          source,
+        );
+      }
+      sections.push(item);
+    }
+    requiredSections = sections;
+  }
+
   return {
     kind,
     label,
@@ -604,6 +657,7 @@ function validateExtensionEntry(
     publishDir,
     requiresEntityId,
     ...(entityIdPattern !== undefined ? { entityIdPattern } : {}),
+    ...(requiredSections !== undefined ? { requiredSections } : {}),
   };
 }
 
@@ -633,6 +687,7 @@ function compileExtension(ext: DocKindExtensionConfig, source: string): DocKindM
     publishDir: ext.publishDir,
     requiresEntityId: ext.requiresEntityId,
     ...(entityIdPattern !== undefined ? { entityIdPattern } : {}),
+    ...(ext.requiredSections !== undefined ? { requiredSections: ext.requiredSections } : {}),
     isExtension: true,
   };
 }

package/src/doctor.ts

@@ -20,6 +20,8 @@
  * @epic T9808
  */
 
+import type { InvariantSeverity } from './invariants/index.js';
+
 /**
  * One orphan `.cleo/` directory discovered under
  * `<projectRoot>/.claude/worktrees/`.
@@ -286,6 +288,115 @@ export interface SagaAuditResult {
   driftCount: number;
 }
 
+// ============================================================================
+// Invariant Registry Audit (T10340 — Saga T10326 SG-SUBSTRATE-RECONCILIATION /
+// Epic T10327 E-INVARIANT-REGISTRY-SSOT / R6)
+// ============================================================================
+
+/**
+ * Per-entry status reported by {@link auditInvariantRegistry}.
+ *
+ * - `'pass'` — the entry has an adapter that executed against the current
+ *   `.cleo/tasks.db` state and observed zero violations.
+ * - `'fail'` — the entry has an adapter that executed and observed one or
+ *   more violations (forwarded into {@link InvariantAuditEntry.violations}).
+ * - `'not-applicable'` — the entry's `runtimeGate` is spawn-bound,
+ *   session-bound, or release-tag-bound, so there is no "scan current DB"
+ *   interpretation. Reported for completeness so the registry walk is
+ *   visible end-to-end.
+ * - `'documented'` — the entry has `runtimeGate === null` by design (the
+ *   invariant is a display/storage/process concern enforced elsewhere).
+ *   No check performed; surfaced so operators can audit gap coverage.
+ *
+ * @task T10340
+ */
+export type InvariantAuditStatus = 'pass' | 'fail' | 'not-applicable' | 'documented';
+
+/**
+ * One violation surfaced by {@link auditInvariantRegistry}.
+ *
+ * The shape intentionally mirrors {@link SagaAuditViolation} (so the saga
+ * audit pipeline can adapt its findings into this envelope without an
+ * intermediate transform), but the `invariantKey` field is the registry
+ * key (`${adr}.${code}`, e.g. `'ADR-073.I5'`) instead of a saga-only
+ * `kind` discriminator.
+ *
+ * @task T10340
+ */
+export interface InvariantAuditViolation {
+  /** Registry key — `${adr}.${code}`. */
+  invariantKey: string;
+  /** The offending task / row / resource identifier. */
+  offendingId: string;
+  /** Human-readable message naming the offender + repair command. */
+  message: string;
+  /** Canonical `cleo` command an operator should run to resolve. */
+  repairCommand: string;
+}
+
+/**
+ * Per-invariant audit entry produced by {@link auditInvariantRegistry}.
+ *
+ * One entry per registered invariant. `status` summarises the outcome of
+ * the adapter (or the lack thereof). `violations` is always present —
+ * empty when `status !== 'fail'`.
+ *
+ * @task T10340
+ */
+export interface InvariantAuditEntry {
+  /** Registry key — `${adr}.${code}`. */
+  invariantKey: string;
+  /** Source ADR identifier, e.g. `'ADR-073'`. */
+  adr: string;
+  /** Invariant code within the ADR, e.g. `'I3'` or `'ORC-001'`. */
+  code: string;
+  /** Short human-readable name. */
+  name: string;
+  /** Severity tier — drives exit code in the CLI surface. */
+  severity: InvariantSeverity;
+  /** Adapter outcome. See {@link InvariantAuditStatus}. */
+  status: InvariantAuditStatus;
+  /** Free-form note for `'not-applicable'` / `'documented'` entries. */
+  note: string;
+  /** Runtime-gate function name, when one is registered. `null` otherwise. */
+  runtimeGate: string | null;
+  /** Violations observed by the adapter. Empty when `status !== 'fail'`. */
+  violations: InvariantAuditViolation[];
+}
+
+/**
+ * Aggregated audit result returned by {@link auditInvariantRegistry}.
+ *
+ * `entries` carries one entry per registered invariant, sorted first by
+ * ADR (alphabetical), then by code. `errorCount` is the count of
+ * `severity: 'error'` entries whose status is `'fail'` — the only
+ * dimension that should drive a non-zero exit code in the CLI surface.
+ *
+ * Aggregates `warningCount` + `infoCount` cover the corresponding
+ * severities for `'fail'` entries. `notApplicableCount` + `documentedCount`
+ * surface the gap analysis (how many invariants are registry-only).
+ *
+ * @task T10340
+ */
+export interface InvariantAuditResult {
+  /** Per-invariant audit entries. Sorted by ADR then code. */
+  entries: InvariantAuditEntry[];
+  /** Total registered invariants walked. */
+  totalCount: number;
+  /** Entries with status='fail' AND severity='error'. */
+  errorCount: number;
+  /** Entries with status='fail' AND severity='warning'. */
+  warningCount: number;
+  /** Entries with status='fail' AND severity='info'. */
+  infoCount: number;
+  /** Entries with status='not-applicable' (spawn/session/release-bound). */
+  notApplicableCount: number;
+  /** Entries with status='documented' (runtimeGate:null by design). */
+  documentedCount: number;
+  /** ADR filter applied (e.g. `'ADR-073'`), or `null` when the walk was unfiltered. */
+  filteredByAdr: string | null;
+}
+
 // ============================================================================
 // DB-Substrate Survey (T10307 — Saga T10281 SG-BRAIN-DB-RESILIENCE / Epic T10282)
 // ============================================================================

package/src/errors.ts

@@ -29,6 +29,8 @@ import { ExitCode } from './exit-codes.js';
  *
  * @task T889 Orchestration Coherence v3
  * @task T907 Thin-agent enforcement
+ * @see INVARIANTS_REGISTRY['ADR-070.ORC-012'] — central-registry entry
+ *   for this invariant. Source: `./invariants/adr-070-orchestration.ts`.
  */
 export class ThinAgentViolationError extends Error {
   /** Stable LAFS error code string for envelope emission. */
@@ -209,6 +211,8 @@ export class DecisionValidatorFailedError extends Error {
  * @codeName E_LEAD_BYPASS_DETECTED
  * @task T9230
  * @adr ADR-070
+ * @see INVARIANTS_REGISTRY['ADR-070.ORC-014'] — central-registry entry
+ *   for this invariant. Source: `./invariants/adr-070-orchestration.ts`.
  */
 export class LeadBypassDetectedError extends Error {
   /** Stable LAFS error code string for envelope emission. */