@cleocode/cleo 2026.5.111 → 2026.5.112

package/dist/cli/index.js

@@ -1079,6 +1079,33 @@ var init_braille = __esm({
   }
 });
 
+// packages/animations/src/render/legend.ts
+function renderLegend(input2) {
+  if (!input2.ctx.enabled) return "";
+  if (input2.items.length === 0) return "";
+  const threshold = input2.multiLineThreshold ?? DEFAULT_MULTILINE_THRESHOLD;
+  const formatted = input2.items.map((item) => `${item.icon} ${item.label}`);
+  if (input2.items.length <= threshold) {
+    return formatted.join("  ");
+  }
+  return formatted.join("\n");
+}
+function renderSummary(input2) {
+  if (!input2.ctx.enabled) return "";
+  if (input2.counts.length === 0) return "";
+  const separator = input2.ctx.inputs.noColor ? SUMMARY_SEPARATOR_ASCII : SUMMARY_SEPARATOR;
+  return input2.counts.map((c) => `${c.n} ${c.label}`).join(separator);
+}
+var DEFAULT_MULTILINE_THRESHOLD, SUMMARY_SEPARATOR, SUMMARY_SEPARATOR_ASCII;
+var init_legend = __esm({
+  "packages/animations/src/render/legend.ts"() {
+    "use strict";
+    DEFAULT_MULTILINE_THRESHOLD = 8;
+    SUMMARY_SEPARATOR = " \xB7 ";
+    SUMMARY_SEPARATOR_ASCII = " | ";
+  }
+});
+
 // packages/animations/src/render/tree.ts
 import { ascii, KindIcon, StatusIcon } from "@cleocode/contracts/render/icon.js";
 function renderTree(resp, opts) {
@@ -1192,6 +1219,8 @@ var init_tree = __esm({
 // packages/animations/src/render/index.ts
 var init_render = __esm({
   "packages/animations/src/render/index.ts"() {
+    "use strict";
+    init_legend();
     init_tree();
   }
 });
@@ -1308,7 +1337,6 @@ var init_spinner_handle = __esm({
 var init_src = __esm({
   "packages/animations/src/index.ts"() {
     init_animate_context();
-    init_render();
     init_spinner_handle();
   }
 });
@@ -10184,59 +10212,139 @@ var init_errors = __esm({
   }
 });
 
-// packages/contracts/src/evidence-record-schema.ts
+// packages/contracts/src/evidence-atom-schema.ts
 import { z as z4 } from "zod";
+var commitAtomSchema, filesAtomSchema, testRunAtomSchema, toolAtomSchema, urlAtomSchema, noteAtomSchema, decisionAtomSchema, prAtomSchema, locDropAtomSchema, callsiteCoverageAtomSchema, EvidenceAtomSchema, GATE_EVIDENCE_REQUIREMENTS;
+var init_evidence_atom_schema = __esm({
+  "packages/contracts/src/evidence-atom-schema.ts"() {
+    "use strict";
+    commitAtomSchema = z4.object({
+      kind: z4.literal("commit"),
+      sha: z4.string().regex(/^[0-9a-f]{7,40}$/i, "commit sha must be 7-40 hex characters")
+    });
+    filesAtomSchema = z4.object({
+      kind: z4.literal("files"),
+      paths: z4.array(z4.string().min(1)).min(1, "files atom requires at least one path")
+    });
+    testRunAtomSchema = z4.object({
+      kind: z4.literal("test-run"),
+      path: z4.string().min(1, "test-run atom requires a non-empty path")
+    });
+    toolAtomSchema = z4.object({
+      kind: z4.literal("tool"),
+      tool: z4.string().min(1, "tool atom requires a non-empty tool name")
+    });
+    urlAtomSchema = z4.object({
+      kind: z4.literal("url"),
+      url: z4.string().min(1).regex(/^https?:\/\//, "url atom must start with http:// or https://")
+    });
+    noteAtomSchema = z4.object({
+      kind: z4.literal("note"),
+      note: z4.string().min(1, "note atom must be non-empty").max(512, "note atom is too long (max 512 chars)")
+    });
+    decisionAtomSchema = z4.object({
+      kind: z4.literal("decision"),
+      decisionId: z4.string().min(1, "decision atom requires a non-empty decision ID")
+    });
+    prAtomSchema = z4.object({
+      kind: z4.literal("pr"),
+      prNumber: z4.number().int().positive("pr atom requires a positive integer PR number")
+    });
+    locDropAtomSchema = z4.object({
+      kind: z4.literal("loc-drop"),
+      fromLines: z4.number().int().nonnegative("loc-drop fromLines must be \u2265 0"),
+      toLines: z4.number().int().nonnegative("loc-drop toLines must be \u2265 0")
+    });
+    callsiteCoverageAtomSchema = z4.object({
+      kind: z4.literal("callsite-coverage"),
+      symbolName: z4.string().min(1, "callsite-coverage atom requires a non-empty symbolName"),
+      relativeSourcePath: z4.string().min(1, "callsite-coverage atom requires a non-empty relativeSourcePath")
+    });
+    EvidenceAtomSchema = z4.discriminatedUnion("kind", [
+      commitAtomSchema,
+      filesAtomSchema,
+      testRunAtomSchema,
+      toolAtomSchema,
+      urlAtomSchema,
+      noteAtomSchema,
+      decisionAtomSchema,
+      prAtomSchema,
+      locDropAtomSchema,
+      callsiteCoverageAtomSchema
+    ]);
+    GATE_EVIDENCE_REQUIREMENTS = Object.freeze({
+      implemented: {
+        oneOf: [
+          ["commit", "files"],
+          ["commit", "note"],
+          ["decision", "files"],
+          ["decision", "note"],
+          ["pr"]
+        ]
+      },
+      testsPassed: { oneOf: [["test-run"], ["tool"], ["pr"]] },
+      qaPassed: { oneOf: [["tool"], ["pr"]] },
+      documented: { oneOf: [["files"], ["url"]] },
+      securityPassed: { oneOf: [["tool"], ["note"]] },
+      cleanupDone: { oneOf: [["note"]] },
+      nexusImpact: { oneOf: [["tool"], ["note"]] }
+    });
+  }
+});
+
+// packages/contracts/src/evidence-record-schema.ts
+import { z as z5 } from "zod";
 var evidenceBaseSchema, implDiffRecordSchema, validateSpecCheckRecordSchema, testOutputRecordSchema, lintReportRecordSchema, commandOutputRecordSchema, evidenceRecordSchema;
 var init_evidence_record_schema = __esm({
   "packages/contracts/src/evidence-record-schema.ts"() {
     "use strict";
-    evidenceBaseSchema = z4.object({
+    evidenceBaseSchema = z5.object({
       /** Identity string of the agent that produced this record. */
-      agentIdentity: z4.string().min(1),
+      agentIdentity: z5.string().min(1),
       /** SHA-256 hex digest (64 chars) of the attached artifact. */
-      attachmentSha256: z4.string().length(64),
+      attachmentSha256: z5.string().length(64),
       /** ISO 8601 timestamp at which the action ran. */
-      ranAt: z4.string().datetime(),
+      ranAt: z5.string().datetime(),
       /** Wall-clock duration of the action in milliseconds. */
-      durationMs: z4.number().nonnegative()
+      durationMs: z5.number().nonnegative()
     });
     implDiffRecordSchema = evidenceBaseSchema.extend({
-      kind: z4.literal("impl-diff"),
-      phase: z4.literal("implement"),
-      filesChanged: z4.array(z4.string().min(1)).min(1),
-      linesAdded: z4.number().int().nonnegative(),
-      linesRemoved: z4.number().int().nonnegative()
+      kind: z5.literal("impl-diff"),
+      phase: z5.literal("implement"),
+      filesChanged: z5.array(z5.string().min(1)).min(1),
+      linesAdded: z5.number().int().nonnegative(),
+      linesRemoved: z5.number().int().nonnegative()
     });
     validateSpecCheckRecordSchema = evidenceBaseSchema.extend({
-      kind: z4.literal("validate-spec-check"),
-      phase: z4.literal("validate"),
-      reqIdsChecked: z4.array(z4.string().min(1)).min(1),
-      passed: z4.boolean(),
-      details: z4.string().min(1)
+      kind: z5.literal("validate-spec-check"),
+      phase: z5.literal("validate"),
+      reqIdsChecked: z5.array(z5.string().min(1)).min(1),
+      passed: z5.boolean(),
+      details: z5.string().min(1)
     });
     testOutputRecordSchema = evidenceBaseSchema.extend({
-      kind: z4.literal("test-output"),
-      phase: z4.literal("test"),
-      command: z4.string().min(1),
-      exitCode: z4.number().int(),
-      testsPassed: z4.number().int().nonnegative(),
-      testsFailed: z4.number().int().nonnegative()
+      kind: z5.literal("test-output"),
+      phase: z5.literal("test"),
+      command: z5.string().min(1),
+      exitCode: z5.number().int(),
+      testsPassed: z5.number().int().nonnegative(),
+      testsFailed: z5.number().int().nonnegative()
     });
     lintReportRecordSchema = evidenceBaseSchema.extend({
-      kind: z4.literal("lint-report"),
-      phase: z4.enum(["implement", "test"]),
-      tool: z4.string().min(1),
-      passed: z4.boolean(),
-      warnings: z4.number().int().nonnegative(),
-      errors: z4.number().int().nonnegative()
+      kind: z5.literal("lint-report"),
+      phase: z5.enum(["implement", "test"]),
+      tool: z5.string().min(1),
+      passed: z5.boolean(),
+      warnings: z5.number().int().nonnegative(),
+      errors: z5.number().int().nonnegative()
     });
     commandOutputRecordSchema = evidenceBaseSchema.extend({
-      kind: z4.literal("command-output"),
-      phase: z4.enum(["implement", "validate", "test"]),
-      cmd: z4.string().min(1),
-      exitCode: z4.number().int()
+      kind: z5.literal("command-output"),
+      phase: z5.enum(["implement", "validate", "test"]),
+      cmd: z5.string().min(1),
+      exitCode: z5.number().int()
     });
-    evidenceRecordSchema = z4.discriminatedUnion("kind", [
+    evidenceRecordSchema = z5.discriminatedUnion("kind", [
       implDiffRecordSchema,
       validateSpecCheckRecordSchema,
       testOutputRecordSchema,
@@ -10260,6 +10368,154 @@ var init_graph = __esm({
   }
 });
 
+// packages/contracts/src/invariants/adr-073-saga.ts
+var SAGA_ENFORCEMENT_MODULE, SAGA_ENFORCEMENT_TESTS, ADR_073_INVARIANTS;
+var init_adr_073_saga = __esm({
+  "packages/contracts/src/invariants/adr-073-saga.ts"() {
+    "use strict";
+    SAGA_ENFORCEMENT_MODULE = "packages/core/src/sagas/enforcement.ts";
+    SAGA_ENFORCEMENT_TESTS = "packages/core/src/sagas/__tests__/enforcement.test.ts";
+    ADR_073_INVARIANTS = 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 \u2014 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 \xA7"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 \u2192 Task \u2192 Epic is fixed at depth 3 (hierarchy.maxDepth=3). Sagas do NOT consume depth \u2014 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 \u2014 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: []
+      }
+    ]);
+  }
+});
+
+// packages/contracts/src/invariants/index.ts
+function buildKey(invariant) {
+  return `${invariant.adr}.${invariant.code}`;
+}
+function buildRegistry() {
+  const entries = [...ADR_073_INVARIANTS];
+  const record = {};
+  for (const entry of entries) {
+    const key = buildKey(entry);
+    if (record[key] !== void 0) {
+      throw new Error(`Duplicate invariant key registered: ${key}`);
+    }
+    record[key] = entry;
+  }
+  return Object.freeze(record);
+}
+var INVARIANTS_REGISTRY;
+var init_invariants = __esm({
+  "packages/contracts/src/invariants/index.ts"() {
+    "use strict";
+    init_adr_073_saga();
+    init_adr_073_saga();
+    INVARIANTS_REGISTRY = buildRegistry();
+  }
+});
+
 // packages/contracts/src/lafs.ts
 var init_lafs = __esm({
   "packages/contracts/src/lafs.ts"() {
@@ -11066,31 +11322,31 @@ var init_peer = __esm({
 });
 
 // packages/contracts/src/release/evidence-atoms.ts
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 var parsedPrEvidenceAtomSchema, prEvidenceStateModifierSchema, ghPrViewSchema, PR_REQUIRED_WORKFLOWS;
 var init_evidence_atoms = __esm({
   "packages/contracts/src/release/evidence-atoms.ts"() {
     "use strict";
-    parsedPrEvidenceAtomSchema = z5.object({
-      kind: z5.literal("pr"),
-      prNumber: z5.number().int().positive()
-    });
-    prEvidenceStateModifierSchema = z5.object({
-      kind: z5.literal("state"),
-      value: z5.literal("MERGED")
-    });
-    ghPrViewSchema = z5.object({
-      state: z5.enum(["OPEN", "CLOSED", "MERGED"]),
-      mergedAt: z5.string().nullable(),
-      headRefOid: z5.string().optional(),
-      mergeable: z5.string().optional(),
-      statusCheckRollup: z5.array(
-        z5.object({
-          __typename: z5.string().optional(),
-          name: z5.string().optional(),
-          workflowName: z5.string().optional(),
-          conclusion: z5.string().nullable().optional(),
-          status: z5.string().optional()
+    parsedPrEvidenceAtomSchema = z6.object({
+      kind: z6.literal("pr"),
+      prNumber: z6.number().int().positive()
+    });
+    prEvidenceStateModifierSchema = z6.object({
+      kind: z6.literal("state"),
+      value: z6.literal("MERGED")
+    });
+    ghPrViewSchema = z6.object({
+      state: z6.enum(["OPEN", "CLOSED", "MERGED"]),
+      mergedAt: z6.string().nullable(),
+      headRefOid: z6.string().optional(),
+      mergeable: z6.string().optional(),
+      statusCheckRollup: z6.array(
+        z6.object({
+          __typename: z6.string().optional(),
+          name: z6.string().optional(),
+          workflowName: z6.string().optional(),
+          conclusion: z6.string().nullable().optional(),
+          status: z6.string().optional()
         }).passthrough()
       ).optional().default([])
     }).passthrough();
@@ -11103,7 +11359,7 @@ var init_evidence_atoms = __esm({
 });
 
 // packages/contracts/src/release/plan.ts
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 var RELEASE_CHANNEL, RELEASE_SCHEME, RELEASE_KIND, RELEASE_STATUS, GATE_STATUS, GATE_NAME, PLATFORM_TUPLE, PUBLISHER, TASK_KIND, IMPACT, RESOLVED_SOURCE, ReleaseChannelSchema, ReleaseSchemeSchema, ReleaseKindSchema, ReleaseStatusSchema, GateStatusSchema, GateNameSchema, PlatformTupleSchema, PublisherSchema, TaskKindSchema, ImpactSchema, ResolvedSourceSchema, Iso8601, NonEmptyString, ReleasePlanTaskSchema, ReleaseGateSchema, ReleasePlatformMatrixEntrySchema, ReleasePreflightSummarySchema, ReleasePlanChangelogSchema, ReleasePlanMetaSchema, ReleasePlanSchema;
 var init_plan = __esm({
   "packages/contracts/src/release/plan.ts"() {
@@ -11146,20 +11402,20 @@ var init_plan = __esm({
     ];
     IMPACT = ["major", "minor", "patch"];
     RESOLVED_SOURCE = ["project-context", "language-default", "legacy-alias"];
-    ReleaseChannelSchema = z6.enum(RELEASE_CHANNEL);
-    ReleaseSchemeSchema = z6.enum(RELEASE_SCHEME);
-    ReleaseKindSchema = z6.enum(RELEASE_KIND);
-    ReleaseStatusSchema = z6.enum(RELEASE_STATUS);
-    GateStatusSchema = z6.enum(GATE_STATUS);
-    GateNameSchema = z6.enum(GATE_NAME);
-    PlatformTupleSchema = z6.enum(PLATFORM_TUPLE);
-    PublisherSchema = z6.enum(PUBLISHER);
-    TaskKindSchema = z6.enum(TASK_KIND);
-    ImpactSchema = z6.enum(IMPACT);
-    ResolvedSourceSchema = z6.enum(RESOLVED_SOURCE);
-    Iso8601 = z6.iso.datetime({ offset: true });
-    NonEmptyString = z6.string().min(1);
-    ReleasePlanTaskSchema = z6.object({
+    ReleaseChannelSchema = z7.enum(RELEASE_CHANNEL);
+    ReleaseSchemeSchema = z7.enum(RELEASE_SCHEME);
+    ReleaseKindSchema = z7.enum(RELEASE_KIND);
+    ReleaseStatusSchema = z7.enum(RELEASE_STATUS);
+    GateStatusSchema = z7.enum(GATE_STATUS);
+    GateNameSchema = z7.enum(GATE_NAME);
+    PlatformTupleSchema = z7.enum(PLATFORM_TUPLE);
+    PublisherSchema = z7.enum(PUBLISHER);
+    TaskKindSchema = z7.enum(TASK_KIND);
+    ImpactSchema = z7.enum(IMPACT);
+    ResolvedSourceSchema = z7.enum(RESOLVED_SOURCE);
+    Iso8601 = z7.iso.datetime({ offset: true });
+    NonEmptyString = z7.string().min(1);
+    ReleasePlanTaskSchema = z7.object({
       /** Task ID (e.g. "T10001"). Format intentionally loose so historical IDs validate. */
       id: NonEmptyString,
       /** Conventional-commit-aligned task classification. */
@@ -11167,20 +11423,20 @@ var init_plan = __esm({
       /** SemVer impact classification. */
       impact: ImpactSchema,
       /** Human-readable changelog line for this task. */
-      userFacingSummary: z6.string(),
+      userFacingSummary: z7.string(),
       /**
        * ADR-051 evidence atoms attesting the task's gate results. Format is
        * `kind:value` (e.g. `commit:abc123`, `test-run:vitest.json`). The contract
        * accepts empty arrays so legacy plans validate; `cleo release plan`
        * enforces non-empty via R-301.
        */
-      evidenceAtoms: z6.array(NonEmptyString),
+      evidenceAtoms: z7.array(NonEmptyString),
       /** IVTR phase at plan time — informational only per R-316. */
-      ivtrPhaseAtPlan: z6.string().optional(),
+      ivtrPhaseAtPlan: z7.string().optional(),
       /** Epic this task rolls up to, locked at plan time per R-303. */
       epicAncestor: NonEmptyString
     });
-    ReleaseGateSchema = z6.object({
+    ReleaseGateSchema = z7.object({
       /** Canonical gate name. */
       name: GateNameSchema,
       /** ADR-051 atom string identifying the resolved tool (e.g. `tool:test`). */
@@ -11190,11 +11446,11 @@ var init_plan = __esm({
       /** ISO-8601 timestamp the gate was last verified. */
       lastVerifiedAt: Iso8601,
       /** Resolved shell command (e.g. `pnpm run test`). Optional for unresolved gates. */
-      resolvedCommand: z6.string().optional(),
+      resolvedCommand: z7.string().optional(),
       /** Provenance of the resolved command. Optional for unresolved gates. */
       resolvedSource: ResolvedSourceSchema.optional()
     });
-    ReleasePlatformMatrixEntrySchema = z6.object({
+    ReleasePlatformMatrixEntrySchema = z7.object({
       /** Target platform tuple. */
       platform: PlatformTupleSchema,
       /** Distribution backend. */
@@ -11202,47 +11458,47 @@ var init_plan = __esm({
       /** Package identifier on the target backend (e.g. `@cleocode/cleo`). */
       package: NonEmptyString,
       /** Whether to run the GHA smoke job for this matrix entry. */
-      smoke: z6.boolean().default(true).optional()
+      smoke: z7.boolean().default(true).optional()
     });
-    ReleasePreflightSummarySchema = z6.object({
+    ReleasePreflightSummarySchema = z7.object({
       /** True if esbuild externals are out of sync with package.json. */
-      esbuildExternalsDrift: z6.boolean(),
+      esbuildExternalsDrift: z7.boolean(),
       /** True if `pnpm-lock.yaml` diverges from the workspace manifest. */
-      lockfileDrift: z6.boolean(),
+      lockfileDrift: z7.boolean(),
       /** True if all epic children are in terminal lifecycle states. */
-      epicCompletenessClean: z6.boolean(),
+      epicCompletenessClean: z7.boolean(),
       /** True if no task appears in multiple in-flight release plans. */
-      doubleListingClean: z6.boolean(),
+      doubleListingClean: z7.boolean(),
       /** Non-fatal preflight warnings (e.g. unresolved tools per R-024). */
-      preflightWarnings: z6.array(z6.string()).default([]).optional()
+      preflightWarnings: z7.array(z7.string()).default([]).optional()
     });
-    ReleasePlanChangelogSchema = z6.object({
+    ReleasePlanChangelogSchema = z7.object({
       /** `kind=feat` tasks. */
-      features: z6.array(NonEmptyString).default([]),
+      features: z7.array(NonEmptyString).default([]),
       /** `kind=fix` or `kind=hotfix` tasks. */
-      fixes: z6.array(NonEmptyString).default([]),
+      fixes: z7.array(NonEmptyString).default([]),
       /** `kind=chore`, `docs`, `refactor`, `test`, `perf` tasks. */
-      chores: z6.array(NonEmptyString).default([]),
+      chores: z7.array(NonEmptyString).default([]),
       /** `kind=breaking` or `kind=revert` tasks. */
-      breaking: z6.array(NonEmptyString).default([])
+      breaking: z7.array(NonEmptyString).default([])
     });
-    ReleasePlanMetaSchema = z6.object({
+    ReleasePlanMetaSchema = z7.object({
       /** True if this is the project's first ever release. */
-      firstEverRelease: z6.boolean().optional(),
+      firstEverRelease: z7.boolean().optional(),
       /** Canonical tool names that could not be resolved at plan time. */
-      unresolvedTools: z6.array(z6.string()).optional(),
+      unresolvedTools: z7.array(z7.string()).optional(),
       /** Project archetype detected at plan time. */
-      archetype: z6.string().optional()
-    }).catchall(z6.unknown());
-    ReleasePlanSchema = z6.object({
+      archetype: z7.string().optional()
+    }).catchall(z7.unknown());
+    ReleasePlanSchema = z7.object({
       /** Schema URL for this plan version. */
-      $schema: z6.string().optional(),
+      $schema: z7.string().optional(),
       /** Requested version string (e.g. "v2026.6.0"). Includes the leading `v`. */
       version: NonEmptyString,
       /** Resolved version string after suffix application (e.g. "v2026.6.0.2"). */
       resolvedVersion: NonEmptyString,
       /** True if a `calver-suffix` was applied to disambiguate a same-day hotfix. */
-      suffixApplied: z6.boolean(),
+      suffixApplied: z7.boolean(),
       /** Versioning scheme governing `version` / `resolvedVersion`. */
       scheme: ReleaseSchemeSchema,
       /** npm dist-tag channel for this release. */
@@ -11259,27 +11515,27 @@ var init_plan = __esm({
        * Version of the previous release on the same channel. MUST be `null` only
        * for first-ever releases (R-300, enforced at the verb layer).
        */
-      previousVersion: z6.string().nullable(),
+      previousVersion: z7.string().nullable(),
       /** Git tag of the previous release (typically `previousVersion` prefixed). */
-      previousTag: z6.string().nullable(),
+      previousTag: z7.string().nullable(),
       /** ISO-8601 timestamp the previous release was published. */
       previousShippedAt: Iso8601.nullable(),
       /** Tasks rolled into this release. */
-      tasks: z6.array(ReleasePlanTaskSchema),
+      tasks: z7.array(ReleasePlanTaskSchema),
       /** Bucketed changelog. */
       changelog: ReleasePlanChangelogSchema,
       /** Per-gate verification status. */
-      gates: z6.array(ReleaseGateSchema),
+      gates: z7.array(ReleaseGateSchema),
       /** Platform / publisher matrix. */
-      platformMatrix: z6.array(ReleasePlatformMatrixEntrySchema),
+      platformMatrix: z7.array(ReleasePlatformMatrixEntrySchema),
       /** Preflight summary from `cleo release plan`. */
       preflightSummary: ReleasePreflightSummarySchema,
       /** URL of the GHA workflow run (populated by `release-prepare.yml`). */
-      workflowRunUrl: z6.string().nullable(),
+      workflowRunUrl: z7.string().nullable(),
       /** URL of the bump PR (populated by `cleo release open`). */
-      prUrl: z6.string().nullable(),
+      prUrl: z7.string().nullable(),
       /** Merge commit SHA on `main` (populated by `release-publish.yml`). */
-      mergeCommitSha: z6.string().nullable(),
+      mergeCommitSha: z7.string().nullable(),
       /** Current FSM state per R-302. */
       status: ReleaseStatusSchema,
       /** Informational / forward-compat metadata. */
@@ -11335,52 +11591,52 @@ var init_session2 = __esm({
 });
 
 // packages/contracts/src/session-journal.ts
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 var SESSION_JOURNAL_SCHEMA_VERSION, sessionJournalDoctorSummarySchema, sessionJournalDebriefSummarySchema, sessionJournalEntrySchema;
 var init_session_journal = __esm({
   "packages/contracts/src/session-journal.ts"() {
     "use strict";
     SESSION_JOURNAL_SCHEMA_VERSION = "1.0";
-    sessionJournalDoctorSummarySchema = z7.object({
+    sessionJournalDoctorSummarySchema = z8.object({
       /** `true` when zero noise patterns were detected. */
-      isClean: z7.boolean(),
+      isClean: z8.boolean(),
       /** Total number of noise findings across all patterns. */
-      findingsCount: z7.number().int().nonnegative(),
+      findingsCount: z8.number().int().nonnegative(),
       /** Pattern names that were detected (empty when isClean). */
-      patterns: z7.array(z7.string()),
+      patterns: z8.array(z8.string()),
       /** Total brain entries scanned. `0` = empty or unavailable. */
-      totalScanned: z7.number().int().nonnegative()
+      totalScanned: z8.number().int().nonnegative()
     });
-    sessionJournalDebriefSummarySchema = z7.object({
+    sessionJournalDebriefSummarySchema = z8.object({
       /** First 200 characters of the session end note (if provided). */
-      noteExcerpt: z7.string().max(200).optional(),
+      noteExcerpt: z8.string().max(200).optional(),
       /** Number of tasks completed during the session. */
-      tasksCompletedCount: z7.number().int().nonnegative(),
+      tasksCompletedCount: z8.number().int().nonnegative(),
       /** Up to 5 task IDs (not titles) that were the focus of the session. */
-      tasksFocused: z7.array(z7.string()).max(5).optional()
+      tasksFocused: z8.array(z8.string()).max(5).optional()
     });
-    sessionJournalEntrySchema = z7.object({
+    sessionJournalEntrySchema = z8.object({
       // Identity
       /** Schema version for forward-compatibility. Always `'1.0'` in this release. */
-      schemaVersion: z7.literal(SESSION_JOURNAL_SCHEMA_VERSION),
+      schemaVersion: z8.literal(SESSION_JOURNAL_SCHEMA_VERSION),
       /** ISO 8601 timestamp when the entry was written. */
-      timestamp: z7.string(),
+      timestamp: z8.string(),
       /** CLEO session ID (e.g. `ses_20260424055456_ede571`). */
-      sessionId: z7.string(),
+      sessionId: z8.string(),
       /** Event type that triggered this journal entry. */
-      eventType: z7.enum(["session_start", "session_end", "observation", "decision", "error"]),
+      eventType: z8.enum(["session_start", "session_end", "observation", "decision", "error"]),
       // Session metadata (set on session_start / session_end)
       /** Agent identifier (e.g. `cleo-prime`, `claude-code`). */
-      agentIdentifier: z7.string().optional(),
+      agentIdentifier: z8.string().optional(),
       /** Provider adapter ID active for this session. */
-      providerId: z7.string().optional(),
+      providerId: z8.string().optional(),
       /** Session scope string (e.g. `'global'` or `'epic:T1263'`). */
-      scope: z7.string().optional(),
+      scope: z8.string().optional(),
       // Session-end fields
       /** Duration of the session in seconds (session_end only). */
-      duration: z7.number().int().nonnegative().optional(),
+      duration: z8.number().int().nonnegative().optional(),
       /** Task IDs (not titles) completed during the session. */
-      tasksCompleted: z7.array(z7.string()).optional(),
+      tasksCompleted: z8.array(z8.string()).optional(),
       // Doctor summary (T1262 absorbed)
       /** Compact result of `scanBrainNoise` run at session-end. */
       doctorSummary: sessionJournalDoctorSummarySchema.optional(),
@@ -11389,7 +11645,7 @@ var init_session_journal = __esm({
       debriefSummary: sessionJournalDebriefSummarySchema.optional(),
       // Optional hash chain
       /** SHA-256 hex of the previous entry's raw JSON string (for integrity chain). */
-      prevEntryHash: z7.string().optional()
+      prevEntryHash: z8.string().optional()
     });
   }
 });
@@ -11409,52 +11665,52 @@ var init_task = __esm({
 });
 
 // packages/contracts/src/task-evidence.ts
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 var fileEvidenceSchema, logEvidenceSchema, screenshotEvidenceSchema, testOutputEvidenceSchema, commandOutputEvidenceSchema, taskEvidenceSchema;
 var init_task_evidence = __esm({
   "packages/contracts/src/task-evidence.ts"() {
     "use strict";
-    fileEvidenceSchema = z8.object({
-      kind: z8.literal("file"),
-      sha256: z8.string().length(64),
-      timestamp: z8.string().datetime(),
-      path: z8.string().min(1),
-      mime: z8.string().optional(),
-      description: z8.string().optional()
-    });
-    logEvidenceSchema = z8.object({
-      kind: z8.literal("log"),
-      sha256: z8.string().length(64),
-      timestamp: z8.string().datetime(),
-      source: z8.string().min(1),
-      description: z8.string().optional()
-    });
-    screenshotEvidenceSchema = z8.object({
-      kind: z8.literal("screenshot"),
-      sha256: z8.string().length(64),
-      timestamp: z8.string().datetime(),
-      mime: z8.enum(["image/png", "image/jpeg", "image/webp"]).optional(),
-      description: z8.string().optional()
-    });
-    testOutputEvidenceSchema = z8.object({
-      kind: z8.literal("test-output"),
-      sha256: z8.string().length(64),
-      timestamp: z8.string().datetime(),
-      passed: z8.number().int().nonnegative(),
-      failed: z8.number().int().nonnegative(),
-      skipped: z8.number().int().nonnegative(),
-      exitCode: z8.number().int(),
-      description: z8.string().optional()
-    });
-    commandOutputEvidenceSchema = z8.object({
-      kind: z8.literal("command-output"),
-      sha256: z8.string().length(64),
-      timestamp: z8.string().datetime(),
-      cmd: z8.string().min(1),
-      exitCode: z8.number().int(),
-      description: z8.string().optional()
-    });
-    taskEvidenceSchema = z8.discriminatedUnion("kind", [
+    fileEvidenceSchema = z9.object({
+      kind: z9.literal("file"),
+      sha256: z9.string().length(64),
+      timestamp: z9.string().datetime(),
+      path: z9.string().min(1),
+      mime: z9.string().optional(),
+      description: z9.string().optional()
+    });
+    logEvidenceSchema = z9.object({
+      kind: z9.literal("log"),
+      sha256: z9.string().length(64),
+      timestamp: z9.string().datetime(),
+      source: z9.string().min(1),
+      description: z9.string().optional()
+    });
+    screenshotEvidenceSchema = z9.object({
+      kind: z9.literal("screenshot"),
+      sha256: z9.string().length(64),
+      timestamp: z9.string().datetime(),
+      mime: z9.enum(["image/png", "image/jpeg", "image/webp"]).optional(),
+      description: z9.string().optional()
+    });
+    testOutputEvidenceSchema = z9.object({
+      kind: z9.literal("test-output"),
+      sha256: z9.string().length(64),
+      timestamp: z9.string().datetime(),
+      passed: z9.number().int().nonnegative(),
+      failed: z9.number().int().nonnegative(),
+      skipped: z9.number().int().nonnegative(),
+      exitCode: z9.number().int(),
+      description: z9.string().optional()
+    });
+    commandOutputEvidenceSchema = z9.object({
+      kind: z9.literal("command-output"),
+      sha256: z9.string().length(64),
+      timestamp: z9.string().datetime(),
+      cmd: z9.string().min(1),
+      exitCode: z9.number().int(),
+      description: z9.string().optional()
+    });
+    taskEvidenceSchema = z9.discriminatedUnion("kind", [
       fileEvidenceSchema,
       logEvidenceSchema,
       screenshotEvidenceSchema,
@@ -11465,12 +11721,12 @@ var init_task_evidence = __esm({
 });
 
 // packages/contracts/src/tasks/archive.ts
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 var ArchiveReason, ARCHIVE_REASON_VALUES;
 var init_archive = __esm({
   "packages/contracts/src/tasks/archive.ts"() {
     "use strict";
-    ArchiveReason = z9.enum([
+    ArchiveReason = z10.enum([
       "verified",
       "reconciled",
       "superseded",
@@ -11499,10 +11755,12 @@ var init_src2 = __esm({
     init_engine_result();
     init_enums();
     init_errors();
+    init_evidence_atom_schema();
     init_evidence_record_schema();
     init_exit_codes();
     init_facade();
     init_graph();
+    init_invariants();
     init_lafs();
     init_plugin_llm();
     init_observe();
@@ -41190,7 +41448,13 @@ var init_colors = __esm({
 });
 
 // packages/cleo/src/cli/renderers/generic-tree.ts
-import { ascii as ascii2, KindIcon as KindIcon2, pickIcon, RelationIcon } from "@cleocode/contracts/render/icon.js";
+import {
+  ascii as ascii2,
+  KindIcon as KindIcon2,
+  pickIcon,
+  RelationIcon,
+  StatusIcon as StatusIcon2
+} from "@cleocode/contracts/render/icon.js";
 function renderGenericTree(result, opts) {
   const explicitCtx = opts.ctx !== void 0;
   const ctx = opts.ctx ?? resolveAnimateContext();
@@ -41209,8 +41473,74 @@ function renderGenericTree(result, opts) {
     const annotations = renderAnnotations(result.tree, opts);
     if (annotations) lines.push(annotations);
   }
+  const footer = renderFooterLegend(result, ctx, useAscii);
+  if (footer) {
+    lines.push("");
+    lines.push(footer);
+  }
   return lines.join("\n");
 }
+function renderFooterLegend(result, ctx, useAscii) {
+  if (!ctx.enabled) return "";
+  const kindsSeen = /* @__PURE__ */ new Set();
+  const statusesSeen = /* @__PURE__ */ new Set();
+  let hasGroupsEdge = false;
+  for (const node of result.tree.tree) {
+    kindsSeen.add(node.kind);
+    statusesSeen.add(node.status);
+    if (node.metadata.edgeType === "groups") hasGroupsEdge = true;
+  }
+  const items = [];
+  const KIND_ORDER = [
+    ["saga", "saga"],
+    ["epic", "epic"],
+    ["task", "task"],
+    ["subtask", "subtask"]
+  ];
+  for (const [kind, label] of KIND_ORDER) {
+    if (!kindsSeen.has(kind)) continue;
+    items.push({ icon: pickIcon(kindIconOf(kind), { noColor: useAscii }), label });
+  }
+  if (hasGroupsEdge) {
+    items.push({
+      icon: useAscii ? ascii2(RelationIcon.GROUPS) : RelationIcon.GROUPS,
+      label: "groups-edge"
+    });
+  }
+  const STATUS_ORDER = [
+    ["done", StatusIcon2.DONE],
+    ["in_progress", StatusIcon2.ACTIVE],
+    ["pending", StatusIcon2.PENDING],
+    ["blocked", StatusIcon2.BLOCKED],
+    ["archived", StatusIcon2.ARCHIVED],
+    ["cancelled", StatusIcon2.CANCELLED]
+  ];
+  const STATUS_LABEL = {
+    done: "done",
+    in_progress: "active",
+    pending: "pending",
+    blocked: "blocked",
+    archived: "archived",
+    cancelled: "cancelled"
+  };
+  for (const [status, icon] of STATUS_ORDER) {
+    if (!statusesSeen.has(status)) continue;
+    items.push({
+      icon: pickIcon(icon, { noColor: useAscii }),
+      label: STATUS_LABEL[status] ?? status
+    });
+  }
+  const legend = renderLegend({ items, ctx });
+  const sagaMembers2 = result.tree.tree.filter((n) => n.metadata.edgeType === "groups").length;
+  const counts2 = [
+    { label: "nodes", n: result.tree.totalNodes },
+    { label: "depth", n: result.tree.maxDepth }
+  ];
+  if (sagaMembers2 > 0) counts2.push({ label: "saga members", n: sagaMembers2 });
+  const summary = renderSummary({ counts: counts2, ctx });
+  const divider = `${DIM}\u2500\u2500\u2500 Legend \u2500\u2500\u2500${NC}`;
+  return [divider, legend, summary].filter(Boolean).join("\n");
+}
 function decorateGroupsEdges(tree, useAscii) {
   const glyph = useAscii ? ascii2(RelationIcon.GROUPS) : RelationIcon.GROUPS;
   const prefix = `${glyph} `;