@cleocode/contracts 2026.5.111 → 2026.5.112

package/src/invariants/__tests__/registry.test.ts

@@ -0,0 +1,136 @@
+/**
+ * Unit tests for the central invariants registry (T10335).
+ *
+ * The registry is the SSoT for system-wide invariants surfaced via the
+ * SG-SUBSTRATE-RECONCILIATION saga. Downstream R-tasks (R2 ORC codes,
+ * R4 CI gate, R5 release refactor, R6 doctor audit, R8 docs renderer)
+ * all key off the metadata shape asserted below.
+ *
+ * @epic T10327 — E-INVARIANT-REGISTRY-SSOT
+ * @saga T10326 — SG-SUBSTRATE-RECONCILIATION
+ * @task T10335 — R1: registry + ADR-073 I1-I8
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  E_SAGA_INVARIANT_VIOLATION_I3,
+  E_SAGA_INVARIANT_VIOLATION_I5,
+  E_SAGA_INVARIANT_VIOLATION_I7,
+} from '../../errors.js';
+import {
+  ADR_073_INVARIANTS,
+  getInvariant,
+  getInvariantsByAdr,
+  INVARIANTS_REGISTRY,
+  type RegisteredInvariant,
+} from '../index.js';
+
+/**
+ * Map from ADR-073 invariant code → expected LAFS error code in
+ * `packages/contracts/src/errors.ts`. R2/R4 will extend this mapping with
+ * ADR-070 ORC codes once they land — for now the registry only knows
+ * about the three saga-runtime guards.
+ *
+ * NOTE: I4 / I6 / I8 deliberately have no error code today — they are
+ * UNENFORCED warnings. The R4 CI gate (T10338) is the right home for the
+ * strict "every error has an error code" assertion; this test only
+ * validates the subset we already have wired.
+ */
+const ADR_073_ERROR_CODE_MAP: Record<string, string> = {
+  I3: E_SAGA_INVARIANT_VIOLATION_I3,
+  I5: E_SAGA_INVARIANT_VIOLATION_I5,
+  I7: E_SAGA_INVARIANT_VIOLATION_I7,
+};
+
+describe('INVARIANTS_REGISTRY — central registry shape', () => {
+  it('exposes at least 8 entries (ADR-073 I1-I8 baseline)', () => {
+    const entries = Object.values(INVARIANTS_REGISTRY);
+    expect(entries.length).toBeGreaterThanOrEqual(8);
+  });
+
+  it('registers all eight ADR-073 invariants under predictable keys', () => {
+    for (let i = 1; i <= 8; i++) {
+      const key = `ADR-073.I${i}`;
+      expect(INVARIANTS_REGISTRY[key]).toBeDefined();
+      expect(INVARIANTS_REGISTRY[key]?.adr).toBe('ADR-073');
+      expect(INVARIANTS_REGISTRY[key]?.code).toBe(`I${i}`);
+    }
+  });
+
+  it('every entry carries a non-empty name and description', () => {
+    for (const entry of Object.values(INVARIANTS_REGISTRY)) {
+      expect(entry.name.length).toBeGreaterThan(0);
+      expect(entry.description.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('every severity:"error" invariant has a non-null runtimeGate', () => {
+    const errorTier: RegisteredInvariant[] = Object.values(INVARIANTS_REGISTRY).filter(
+      (e) => e.severity === 'error',
+    );
+    expect(errorTier.length).toBeGreaterThan(0);
+    for (const entry of errorTier) {
+      expect(entry.runtimeGate).not.toBeNull();
+      // Triple is fully populated when present.
+      if (entry.runtimeGate !== null) {
+        expect(entry.runtimeGate.module.length).toBeGreaterThan(0);
+        expect(entry.runtimeGate.functionName.length).toBeGreaterThan(0);
+      }
+    }
+  });
+});
+
+describe('getInvariant — lookup helper', () => {
+  it('returns the ADR-073.I3 entry with the expected runtime guard', () => {
+    const i3 = getInvariant('ADR-073.I3');
+    expect(i3).toBeDefined();
+    expect(i3?.adr).toBe('ADR-073');
+    expect(i3?.code).toBe('I3');
+    expect(i3?.severity).toBe('error');
+    expect(i3?.runtimeGate?.functionName).toBe('assertSagaInvariantI3');
+    expect(i3?.runtimeGate?.module).toBe('packages/core/src/sagas/enforcement.ts');
+  });
+
+  it('returns undefined for an unregistered key', () => {
+    expect(getInvariant('ADR-999.X1')).toBeUndefined();
+  });
+});
+
+describe('getInvariantsByAdr — per-ADR enumeration', () => {
+  it('returns all eight ADR-073 invariants in declaration order', () => {
+    const adr073 = getInvariantsByAdr('ADR-073');
+    expect(adr073).toHaveLength(8);
+    expect(adr073.map((e) => e.code)).toEqual(['I1', 'I2', 'I3', 'I4', 'I5', 'I6', 'I7', 'I8']);
+  });
+
+  it('returns an empty array for an unknown ADR', () => {
+    expect(getInvariantsByAdr('ADR-DOES-NOT-EXIST')).toEqual([]);
+  });
+});
+
+describe('ADR_073_INVARIANTS — exported convenience binding', () => {
+  it('matches the entries surfaced via getInvariantsByAdr', () => {
+    expect(ADR_073_INVARIANTS).toHaveLength(8);
+    const enumerated = getInvariantsByAdr('ADR-073');
+    expect(enumerated).toHaveLength(ADR_073_INVARIANTS.length);
+    for (let i = 0; i < ADR_073_INVARIANTS.length; i++) {
+      expect(enumerated[i]?.code).toBe(ADR_073_INVARIANTS[i]?.code);
+    }
+  });
+});
+
+describe('error-code cross-reference (subset — R4 T10338 owns full strict gate)', () => {
+  it('every ADR-073 invariant with a runtimeGate has a known LAFS error code', () => {
+    // TODO(T10338 / R4): replace this targeted subset with a strict registry-wide
+    // assertion that walks every severity:"error" entry and confirms a matching
+    // LAFS error code (E_<ADR>_INVARIANT_VIOLATION_<CODE>) exists in errors.ts.
+    const adr073 = getInvariantsByAdr('ADR-073');
+    for (const entry of adr073) {
+      if (entry.runtimeGate !== null) {
+        const expected = ADR_073_ERROR_CODE_MAP[entry.code];
+        expect(expected).toBeDefined();
+        expect(typeof expected).toBe('string');
+      }
+    }
+  });
+});

package/src/invariants/adr-073-saga.ts

@@ -0,0 +1,167 @@
+/**
+ * ADR-073 §1.2 invariants I1-I8 registered against the central invariants
+ * registry (`./index.ts`).
+ *
+ * The eight invariants govern the 4-tier task hierarchy (Saga → Epic → Task
+ * → Subtask) and the cross-tier rules that keep it healthy. I3, I5, I7 carry
+ * runtime guards (the `assertSagaInvariant{I3,I5,I7}` functions in
+ * `@cleocode/core` saga module) and surface as `E_SAGA_INVARIANT_VIOLATION_*`
+ * LAFS error codes. I1 + I2 are display/storage concerns enforced by DB
+ * CHECK constraints (added in W1.B T10329 migration) and ID generation
+ * conventions rather than runtime functions. I4, I6, I8 are
+ * orchestration/process invariants that lack a unified runtime guard today
+ * — they are marked `warning` and explicitly tagged as UNENFORCED
+ * (load-bearing) so downstream R6 doctor audits surface them visibly.
+ *
+ * @epic T10327 — E-INVARIANT-REGISTRY-SSOT
+ * @saga T10326 — SG-SUBSTRATE-RECONCILIATION
+ * @task T10335 — R1 (registry + ADR-073 I1-I8)
+ * @see ADR-073-above-epic-naming.md §1.2
+ */
+
+import type { RegisteredInvariant } from './index.js';
+
+/**
+ * Module path that hosts the saga runtime-guard exports
+ * (`assertSagaInvariantI3`, `assertSagaInvariantI5`, `assertSagaInvariantI7`).
+ *
+ * Held as a constant so all four entries share the same source-of-truth
+ * pointer — touching the module path once propagates to every guard ref.
+ */
+const SAGA_ENFORCEMENT_MODULE = 'packages/core/src/sagas/enforcement.ts';
+
+/**
+ * Path to the canonical enforcement-tests file. Used as the `tests` ref
+ * for every I3 / I5 / I7 entry below.
+ */
+const SAGA_ENFORCEMENT_TESTS = 'packages/core/src/sagas/__tests__/enforcement.test.ts';
+
+/**
+ * ADR-073 invariants I1-I8 in declaration order.
+ *
+ * Severity mapping (see `RegisteredInvariant` JSDoc for tier semantics):
+ * - I1, I2 → `info` (display/storage; enforced by DB CHECK + ID convention).
+ * - I3, I5, I7 → `error` (LAFS error code + runtime guard mandatory).
+ * - I4, I6, I8 → `warning` (orchestration/process; UNENFORCED at runtime
+ *   today, doctor audit only).
+ */
+export const ADR_073_INVARIANTS: readonly RegisteredInvariant[] = Object.freeze([
+  {
+    adr: 'ADR-073',
+    code: 'I1',
+    name: 'Storage uniformity',
+    description:
+      'All task IDs are stored as T#### and the type column is the canonical tier discriminator. There is no separate ID space for Sagas, Epics, Tasks, or Subtasks; label="saga" elevates a type="epic" row to Saga semantics.',
+    severity: 'info',
+    // I1 is enforced by the DB CHECK constraints introduced in W1.B (T10329)
+    // and by TASK_ID_PATTERN in packages/core/src/tasks/id-generator.ts —
+    // not by a single runtime function.
+    runtimeGate: null,
+    lintRule: null,
+    doctorAudit: null,
+    tests: ['packages/core/src/tasks/__tests__/id-generator.test.ts'],
+  },
+  {
+    adr: 'ADR-073',
+    code: 'I2',
+    name: 'Conceptual prefixes are display + import only',
+    description:
+      "SG-, E-, T- (and Subtask's implicit absence) are documentation, CLI display, and import-mapping conventions only. They MUST NOT be used as DB primary keys — display-only with no runtime enforcement.",
+    severity: 'info',
+    // I2 is a display convention; the SG- prefix preservation snapshot
+    // (T10333) protects the display contract but there is no runtime guard.
+    runtimeGate: null,
+    lintRule: null,
+    doctorAudit: null,
+    tests: [],
+  },
+  {
+    adr: 'ADR-073',
+    code: 'I3',
+    name: 'Tier promotion mandatory when scope outgrows the tier',
+    description:
+      'A Subtask whose change exceeds 2 files or crosses a module boundary MUST be split or promoted to a sibling Task. A Task that requires more than one PR or wave MUST be split. An Epic that spans more than one release MUST be regrouped under a Saga.',
+    severity: 'error',
+    runtimeGate: {
+      module: SAGA_ENFORCEMENT_MODULE,
+      functionName: 'assertSagaInvariantI3',
+    },
+    lintRule: null,
+    doctorAudit: null,
+    tests: [SAGA_ENFORCEMENT_TESTS],
+  },
+  {
+    adr: 'ADR-073',
+    code: 'I4',
+    name: 'Ownership non-overlapping',
+    description:
+      'A single tier maps to a single orchestration role (per ADR-070). Workers MUST NOT spawn other Workers. Phase Leads MUST NOT own multiple Epics simultaneously. The Orchestrator MUST NOT spawn Workers directly when fan-out exceeds the ADR-070 migration threshold.',
+    severity: 'warning',
+    // I4 is partially covered by ADR-070 spawn guards but the unification
+    // with the registry happens in R2 (T10336 — ORC codes). For now this
+    // entry stays warning + runtimeGate:null to mark the gap explicitly.
+    runtimeGate: null,
+    lintRule: null,
+    doctorAudit: null,
+    tests: [],
+  },
+  {
+    adr: 'ADR-073',
+    code: 'I5',
+    name: 'Sagas link via groups, not parent',
+    description:
+      'task_relations.type="groups" is the ONLY relation type that links a Saga to its member Epics. The Saga row\'s parent_id MUST be NULL. Enforced at runtime by assertSagaInvariantI5 AND by the DB CHECK constraint from W1.B (T10329) on label="saga" rows.',
+    severity: 'error',
+    runtimeGate: {
+      module: SAGA_ENFORCEMENT_MODULE,
+      functionName: 'assertSagaInvariantI5',
+    },
+    lintRule: null,
+    doctorAudit: null,
+    tests: [SAGA_ENFORCEMENT_TESTS],
+  },
+  {
+    adr: 'ADR-073',
+    code: 'I6',
+    name: 'Acceptance criteria required at every tier',
+    description:
+      'Per ADR-066 §"Ownership Matrix" invariant #5, all tasks regardless of type or kind MUST have --acceptance set at creation time. No tier exemption exists. Delegated to the ADR-066 --acceptance requirement on cleo add/add-batch.',
+    severity: 'warning',
+    // I6 is enforced by ADR-066's CLI requirement, not by a saga runtime
+    // function. UNENFORCED in the saga module — left as a warning so R6
+    // doctor audit reminds operators of the upstream guard's location.
+    runtimeGate: null,
+    lintRule: null,
+    doctorAudit: null,
+    tests: [],
+  },
+  {
+    adr: 'ADR-073',
+    code: 'I7',
+    name: 'Maximum parent depth is 3',
+    description:
+      'The parent ladder Subtask → Task → Epic is fixed at depth 3 (hierarchy.maxDepth=3). Sagas do NOT consume depth — they attach via groups relations, not parent edges. Enforced at runtime by assertSagaInvariantI7.',
+    severity: 'error',
+    runtimeGate: {
+      module: SAGA_ENFORCEMENT_MODULE,
+      functionName: 'assertSagaInvariantI7',
+    },
+    lintRule: null,
+    doctorAudit: null,
+    tests: [SAGA_ENFORCEMENT_TESTS],
+  },
+  {
+    adr: 'ADR-073',
+    code: 'I8',
+    name: 'Subtask-to-PR aggregation rule',
+    description:
+      "A Task ships as exactly one PR. The PR's commit history is the union of the Task's Subtask commits. A Subtask never produces its own PR; if a unit of work warrants its own PR, it is a Task, not a Subtask. UNENFORCED at runtime today — load-bearing convention enforced via code review and the lifecycle decision table.",
+    severity: 'warning',
+    // I8 is explicitly "UNENFORCED, load-bearing" — there is no automated
+    // gate. R6 doctor audit surfaces this entry so it stays visible.
+    runtimeGate: null,
+    lintRule: null,
+    doctorAudit: null,
+    tests: [],
+  },
+]);

package/src/invariants/index.ts

@@ -0,0 +1,213 @@
+/**
+ * Central invariants registry — SSoT for system-wide invariants surfaced via
+ * the SaGa T10326 SG-SUBSTRATE-RECONCILIATION programme (Epic T10327
+ * E-INVARIANT-REGISTRY-SSOT, Task T10335 R1).
+ *
+ * Every registered invariant carries the metadata needed to:
+ * 1. Reference its source ADR (e.g. `ADR-073` §1.2 for I1-I8).
+ * 2. Locate the runtime guard that enforces it (when one exists).
+ * 3. Bind the CI lint rule that protects it (when one exists).
+ * 4. Cross-reference test files that exercise it.
+ * 5. Render documentation via the downstream R8 auto-render pipeline.
+ *
+ * Downstream consumers:
+ * - R2 (T10336): register ADR-070 ORC codes into this same registry.
+ * - R4 (T10338): CI gate validates that every `severity:'error'` entry has
+ *   a non-null `runtimeGate` AND a matching error-code in `errors.ts`.
+ * - R5 (T10339): refactor `packages/core/src/release/invariants/registry.ts`
+ *   to consume the central registry instead of carrying its own list.
+ * - R6 (T10340): `cleo doctor --audit-invariants` walks the registry to
+ *   produce a per-invariant audit report.
+ * - R8 (T10342): auto-render docs page from the registry.
+ *
+ * @epic T10327 — E-INVARIANT-REGISTRY-SSOT
+ * @saga T10326 — SG-SUBSTRATE-RECONCILIATION
+ * @task T10335 — R1: registry + ADR-073 I1-I8
+ * @see ADR-073-above-epic-naming.md §1.2
+ */
+
+import { ADR_073_INVARIANTS } from './adr-073-saga.js';
+
+// Re-exported so consumers can import either the per-ADR list or the merged
+// registry from one place.
+export { ADR_073_INVARIANTS } from './adr-073-saga.js';
+
+/**
+ * Severity tier for a registered invariant.
+ *
+ * - `'error'` — runtime gate MUST exist; violation surfaces as LAFS error
+ *   code (cross-checked by R4 CI gate).
+ * - `'warning'` — orchestration/process concern; surfaces via doctor audit
+ *   but does not throw at runtime.
+ * - `'info'` — display or storage concern; enforced (if at all) by DB
+ *   constraints or convention rather than a runtime function.
+ */
+export type InvariantSeverity = 'info' | 'warning' | 'error';
+
+/**
+ * Pointer to a runtime guard function that enforces an invariant.
+ *
+ * The `module` field is the package-relative import specifier
+ * (e.g. `packages/core/src/sagas/enforcement.ts`). The `functionName` is the
+ * exported identifier (e.g. `assertSagaInvariantI3`).
+ *
+ * R4 CI gate uses this triple to assert the guard actually exists and is
+ * exported with the expected name. R6 doctor audit uses it to render
+ * per-invariant enforcement provenance.
+ */
+export interface InvariantRuntimeGate {
+  readonly module: string;
+  readonly functionName: string;
+}
+
+/**
+ * Pointer to a CI lint script that protects an invariant.
+ *
+ * The path is repo-rooted (e.g. `scripts/lint-saga-label-anti-pattern.mjs`).
+ */
+export interface InvariantLintRule {
+  readonly lintScript: string;
+}
+
+/**
+ * Pointer to a `cleo doctor` audit that surfaces invariant violations.
+ *
+ * The lintScript field mirrors the CI gate pointer — many invariants share
+ * the same script between CI and doctor (e.g. saga-label anti-pattern).
+ */
+export interface InvariantDoctorAudit {
+  readonly lintScript: string;
+}
+
+/**
+ * A registered invariant — one entry per `(adr, code)` pair.
+ *
+ * The `adr` + `code` combination forms the registry key
+ * (`${adr}.${code}`, e.g. `'ADR-073.I3'`). Lookups via `getInvariant`
+ * and per-ADR enumeration via `getInvariantsByAdr` use this convention.
+ *
+ * @see ADR-073-above-epic-naming.md §1.2 — original I1-I8 source.
+ */
+export interface RegisteredInvariant {
+  /** Source ADR identifier, e.g. `'ADR-073'`. */
+  readonly adr: string;
+  /** Invariant code within the ADR, e.g. `'I3'` or `'ORC-001'`. */
+  readonly code: string;
+  /** Short human-readable name, e.g. `'Tier promotion mandatory'`. */
+  readonly name: string;
+  /** Full description (one or two sentences, no markdown). */
+  readonly description: string;
+  /** Severity tier — drives R4 CI gate strictness. */
+  readonly severity: InvariantSeverity;
+  /**
+   * Runtime guard function, or `null` when the invariant has no
+   * runtime-checkable form (display/storage/process concerns).
+   *
+   * Every `severity:'error'` invariant MUST set a non-null
+   * `runtimeGate` — enforced by the registry test suite (T10335 AC5)
+   * and by the R4 CI gate (T10338).
+   */
+  readonly runtimeGate: InvariantRuntimeGate | null;
+  /**
+   * Optional CI lint rule reference. Distinct from `runtimeGate` —
+   * `runtimeGate` runs in dispatch code, `lintRule` runs in CI.
+   */
+  readonly lintRule?: InvariantLintRule | null;
+  /**
+   * Optional `cleo doctor` audit reference. R6 consumes this field to
+   * decide which invariants surface in `cleo doctor --audit-invariants`.
+   */
+  readonly doctorAudit?: InvariantDoctorAudit | null;
+  /**
+   * Paths of test files that exercise the invariant. Used by R8 to render
+   * documentation pages with live test cross-references.
+   */
+  readonly tests: readonly string[];
+  /**
+   * Optional flag — set to `true` when the invariant is superseded but
+   * preserved for historical/import-mapping reasons. Defaults to `false`.
+   */
+  readonly deprecated?: boolean;
+}
+
+/**
+ * Compute the canonical registry key for an invariant.
+ *
+ * @internal
+ */
+function buildKey(invariant: RegisteredInvariant): string {
+  return `${invariant.adr}.${invariant.code}`;
+}
+
+/**
+ * Build the merged registry record from all per-ADR invariant modules.
+ *
+ * Future ADR modules (ADR-070 ORC codes via R2 T10336, etc.) append to
+ * the spread list below. Each module exports a `readonly RegisteredInvariant[]`
+ * — this index assembles them into a keyed record at module load time.
+ *
+ * @internal
+ */
+function buildRegistry(): Readonly<Record<string, RegisteredInvariant>> {
+  const entries: RegisteredInvariant[] = [...ADR_073_INVARIANTS];
+  const record: Record<string, RegisteredInvariant> = {};
+  for (const entry of entries) {
+    const key = buildKey(entry);
+    if (record[key] !== undefined) {
+      throw new Error(`Duplicate invariant key registered: ${key}`);
+    }
+    record[key] = entry;
+  }
+  return Object.freeze(record);
+}
+
+/**
+ * Central invariants registry — keyed by `${adr}.${code}`.
+ *
+ * Treat as read-only at runtime. Mutating this record is a contract
+ * violation; downstream consumers (R5 release-registry refactor, R6
+ * doctor audit, R8 docs renderer) assume immutability.
+ *
+ * @example
+ * ```ts
+ * import { INVARIANTS_REGISTRY } from '@cleocode/contracts';
+ * const i3 = INVARIANTS_REGISTRY['ADR-073.I3'];
+ * if (i3?.runtimeGate) {
+ *   console.log(`Guard: ${i3.runtimeGate.functionName}`);
+ * }
+ * ```
+ */
+export const INVARIANTS_REGISTRY: Readonly<Record<string, RegisteredInvariant>> = buildRegistry();
+
+/**
+ * Look up a single invariant by its `${adr}.${code}` key.
+ *
+ * @example
+ * ```ts
+ * const i3 = getInvariant('ADR-073.I3');
+ * // → RegisteredInvariant for ADR-073 invariant I3
+ * ```
+ */
+export function getInvariant(adrCode: string): RegisteredInvariant | undefined {
+  return INVARIANTS_REGISTRY[adrCode];
+}
+
+/**
+ * Return every invariant registered against a given ADR, in declaration order.
+ *
+ * @example
+ * ```ts
+ * const adr073 = getInvariantsByAdr('ADR-073');
+ * // → array of I1..I8 entries
+ * ```
+ */
+export function getInvariantsByAdr(adr: string): RegisteredInvariant[] {
+  const result: RegisteredInvariant[] = [];
+  for (const key of Object.keys(INVARIANTS_REGISTRY)) {
+    const entry = INVARIANTS_REGISTRY[key];
+    if (entry !== undefined && entry.adr === adr) {
+      result.push(entry);
+    }
+  }
+  return result;
+}