@cleocode/cleo 2026.5.89 → 2026.5.92

package/dist/cli/index.js

@@ -2582,8 +2582,41 @@ var init_peer = __esm({
   }
 });
 
-// packages/contracts/src/release/plan.ts
+// packages/contracts/src/release/evidence-atoms.ts
 import { z as z5 } from "zod";
+var parsedPrEvidenceAtomSchema, 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()
+    });
+    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()
+        }).passthrough()
+      ).optional().default([])
+    }).passthrough();
+    PR_REQUIRED_WORKFLOWS = Object.freeze([
+      "CI",
+      "Lockfile Check",
+      "Contracts Dep Lint"
+    ]);
+  }
+});
+
+// packages/contracts/src/release/plan.ts
+import { z as z6 } 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"() {
@@ -2626,20 +2659,20 @@ var init_plan = __esm({
     ];
     IMPACT = ["major", "minor", "patch"];
     RESOLVED_SOURCE = ["project-context", "language-default", "legacy-alias"];
-    ReleaseChannelSchema = z5.enum(RELEASE_CHANNEL);
-    ReleaseSchemeSchema = z5.enum(RELEASE_SCHEME);
-    ReleaseKindSchema = z5.enum(RELEASE_KIND);
-    ReleaseStatusSchema = z5.enum(RELEASE_STATUS);
-    GateStatusSchema = z5.enum(GATE_STATUS);
-    GateNameSchema = z5.enum(GATE_NAME);
-    PlatformTupleSchema = z5.enum(PLATFORM_TUPLE);
-    PublisherSchema = z5.enum(PUBLISHER);
-    TaskKindSchema = z5.enum(TASK_KIND);
-    ImpactSchema = z5.enum(IMPACT);
-    ResolvedSourceSchema = z5.enum(RESOLVED_SOURCE);
-    Iso8601 = z5.iso.datetime({ offset: true });
-    NonEmptyString = z5.string().min(1);
-    ReleasePlanTaskSchema = z5.object({
+    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({
       /** Task ID (e.g. "T10001"). Format intentionally loose so historical IDs validate. */
       id: NonEmptyString,
       /** Conventional-commit-aligned task classification. */
@@ -2647,20 +2680,20 @@ var init_plan = __esm({
       /** SemVer impact classification. */
       impact: ImpactSchema,
       /** Human-readable changelog line for this task. */
-      userFacingSummary: z5.string(),
+      userFacingSummary: z6.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: z5.array(NonEmptyString),
+      evidenceAtoms: z6.array(NonEmptyString),
       /** IVTR phase at plan time — informational only per R-316. */
-      ivtrPhaseAtPlan: z5.string().optional(),
+      ivtrPhaseAtPlan: z6.string().optional(),
       /** Epic this task rolls up to, locked at plan time per R-303. */
       epicAncestor: NonEmptyString
     });
-    ReleaseGateSchema = z5.object({
+    ReleaseGateSchema = z6.object({
       /** Canonical gate name. */
       name: GateNameSchema,
       /** ADR-051 atom string identifying the resolved tool (e.g. `tool:test`). */
@@ -2670,11 +2703,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: z5.string().optional(),
+      resolvedCommand: z6.string().optional(),
       /** Provenance of the resolved command. Optional for unresolved gates. */
       resolvedSource: ResolvedSourceSchema.optional()
     });
-    ReleasePlatformMatrixEntrySchema = z5.object({
+    ReleasePlatformMatrixEntrySchema = z6.object({
       /** Target platform tuple. */
       platform: PlatformTupleSchema,
       /** Distribution backend. */
@@ -2682,47 +2715,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: z5.boolean().default(true).optional()
+      smoke: z6.boolean().default(true).optional()
     });
-    ReleasePreflightSummarySchema = z5.object({
+    ReleasePreflightSummarySchema = z6.object({
       /** True if esbuild externals are out of sync with package.json. */
-      esbuildExternalsDrift: z5.boolean(),
+      esbuildExternalsDrift: z6.boolean(),
       /** True if `pnpm-lock.yaml` diverges from the workspace manifest. */
-      lockfileDrift: z5.boolean(),
+      lockfileDrift: z6.boolean(),
       /** True if all epic children are in terminal lifecycle states. */
-      epicCompletenessClean: z5.boolean(),
+      epicCompletenessClean: z6.boolean(),
       /** True if no task appears in multiple in-flight release plans. */
-      doubleListingClean: z5.boolean(),
+      doubleListingClean: z6.boolean(),
       /** Non-fatal preflight warnings (e.g. unresolved tools per R-024). */
-      preflightWarnings: z5.array(z5.string()).default([]).optional()
+      preflightWarnings: z6.array(z6.string()).default([]).optional()
     });
-    ReleasePlanChangelogSchema = z5.object({
+    ReleasePlanChangelogSchema = z6.object({
       /** `kind=feat` tasks. */
-      features: z5.array(NonEmptyString).default([]),
+      features: z6.array(NonEmptyString).default([]),
       /** `kind=fix` or `kind=hotfix` tasks. */
-      fixes: z5.array(NonEmptyString).default([]),
+      fixes: z6.array(NonEmptyString).default([]),
       /** `kind=chore`, `docs`, `refactor`, `test`, `perf` tasks. */
-      chores: z5.array(NonEmptyString).default([]),
+      chores: z6.array(NonEmptyString).default([]),
       /** `kind=breaking` or `kind=revert` tasks. */
-      breaking: z5.array(NonEmptyString).default([])
+      breaking: z6.array(NonEmptyString).default([])
     });
-    ReleasePlanMetaSchema = z5.object({
+    ReleasePlanMetaSchema = z6.object({
       /** True if this is the project's first ever release. */
-      firstEverRelease: z5.boolean().optional(),
+      firstEverRelease: z6.boolean().optional(),
       /** Canonical tool names that could not be resolved at plan time. */
-      unresolvedTools: z5.array(z5.string()).optional(),
+      unresolvedTools: z6.array(z6.string()).optional(),
       /** Project archetype detected at plan time. */
-      archetype: z5.string().optional()
-    }).catchall(z5.unknown());
-    ReleasePlanSchema = z5.object({
+      archetype: z6.string().optional()
+    }).catchall(z6.unknown());
+    ReleasePlanSchema = z6.object({
       /** Schema URL for this plan version. */
-      $schema: z5.string().optional(),
+      $schema: z6.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: z5.boolean(),
+      suffixApplied: z6.boolean(),
       /** Versioning scheme governing `version` / `resolvedVersion`. */
       scheme: ReleaseSchemeSchema,
       /** npm dist-tag channel for this release. */
@@ -2739,27 +2772,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: z5.string().nullable(),
+      previousVersion: z6.string().nullable(),
       /** Git tag of the previous release (typically `previousVersion` prefixed). */
-      previousTag: z5.string().nullable(),
+      previousTag: z6.string().nullable(),
       /** ISO-8601 timestamp the previous release was published. */
       previousShippedAt: Iso8601.nullable(),
       /** Tasks rolled into this release. */
-      tasks: z5.array(ReleasePlanTaskSchema),
+      tasks: z6.array(ReleasePlanTaskSchema),
       /** Bucketed changelog. */
       changelog: ReleasePlanChangelogSchema,
       /** Per-gate verification status. */
-      gates: z5.array(ReleaseGateSchema),
+      gates: z6.array(ReleaseGateSchema),
       /** Platform / publisher matrix. */
-      platformMatrix: z5.array(ReleasePlatformMatrixEntrySchema),
+      platformMatrix: z6.array(ReleasePlatformMatrixEntrySchema),
       /** Preflight summary from `cleo release plan`. */
       preflightSummary: ReleasePreflightSummarySchema,
       /** URL of the GHA workflow run (populated by `release-prepare.yml`). */
-      workflowRunUrl: z5.string().nullable(),
+      workflowRunUrl: z6.string().nullable(),
       /** URL of the bump PR (populated by `cleo release open`). */
-      prUrl: z5.string().nullable(),
+      prUrl: z6.string().nullable(),
       /** Merge commit SHA on `main` (populated by `release-publish.yml`). */
-      mergeCommitSha: z5.string().nullable(),
+      mergeCommitSha: z6.string().nullable(),
       /** Current FSM state per R-302. */
       status: ReleaseStatusSchema,
       /** Informational / forward-compat metadata. */
@@ -2776,52 +2809,52 @@ var init_session2 = __esm({
 });
 
 // packages/contracts/src/session-journal.ts
-import { z as z6 } from "zod";
+import { z as z7 } 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 = z6.object({
+    sessionJournalDoctorSummarySchema = z7.object({
       /** `true` when zero noise patterns were detected. */
-      isClean: z6.boolean(),
+      isClean: z7.boolean(),
       /** Total number of noise findings across all patterns. */
-      findingsCount: z6.number().int().nonnegative(),
+      findingsCount: z7.number().int().nonnegative(),
       /** Pattern names that were detected (empty when isClean). */
-      patterns: z6.array(z6.string()),
+      patterns: z7.array(z7.string()),
       /** Total brain entries scanned. `0` = empty or unavailable. */
-      totalScanned: z6.number().int().nonnegative()
+      totalScanned: z7.number().int().nonnegative()
     });
-    sessionJournalDebriefSummarySchema = z6.object({
+    sessionJournalDebriefSummarySchema = z7.object({
       /** First 200 characters of the session end note (if provided). */
-      noteExcerpt: z6.string().max(200).optional(),
+      noteExcerpt: z7.string().max(200).optional(),
       /** Number of tasks completed during the session. */
-      tasksCompletedCount: z6.number().int().nonnegative(),
+      tasksCompletedCount: z7.number().int().nonnegative(),
       /** Up to 5 task IDs (not titles) that were the focus of the session. */
-      tasksFocused: z6.array(z6.string()).max(5).optional()
+      tasksFocused: z7.array(z7.string()).max(5).optional()
     });
-    sessionJournalEntrySchema = z6.object({
+    sessionJournalEntrySchema = z7.object({
       // Identity
       /** Schema version for forward-compatibility. Always `'1.0'` in this release. */
-      schemaVersion: z6.literal(SESSION_JOURNAL_SCHEMA_VERSION),
+      schemaVersion: z7.literal(SESSION_JOURNAL_SCHEMA_VERSION),
       /** ISO 8601 timestamp when the entry was written. */
-      timestamp: z6.string(),
+      timestamp: z7.string(),
       /** CLEO session ID (e.g. `ses_20260424055456_ede571`). */
-      sessionId: z6.string(),
+      sessionId: z7.string(),
       /** Event type that triggered this journal entry. */
-      eventType: z6.enum(["session_start", "session_end", "observation", "decision", "error"]),
+      eventType: z7.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: z6.string().optional(),
+      agentIdentifier: z7.string().optional(),
       /** Provider adapter ID active for this session. */
-      providerId: z6.string().optional(),
+      providerId: z7.string().optional(),
       /** Session scope string (e.g. `'global'` or `'epic:T1263'`). */
-      scope: z6.string().optional(),
+      scope: z7.string().optional(),
       // Session-end fields
       /** Duration of the session in seconds (session_end only). */
-      duration: z6.number().int().nonnegative().optional(),
+      duration: z7.number().int().nonnegative().optional(),
       /** Task IDs (not titles) completed during the session. */
-      tasksCompleted: z6.array(z6.string()).optional(),
+      tasksCompleted: z7.array(z7.string()).optional(),
       // Doctor summary (T1262 absorbed)
       /** Compact result of `scanBrainNoise` run at session-end. */
       doctorSummary: sessionJournalDoctorSummarySchema.optional(),
@@ -2830,7 +2863,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: z6.string().optional()
+      prevEntryHash: z7.string().optional()
     });
   }
 });
@@ -2876,52 +2909,52 @@ var init_task = __esm({
 });
 
 // packages/contracts/src/task-evidence.ts
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 var fileEvidenceSchema, logEvidenceSchema, screenshotEvidenceSchema, testOutputEvidenceSchema, commandOutputEvidenceSchema, taskEvidenceSchema;
 var init_task_evidence = __esm({
   "packages/contracts/src/task-evidence.ts"() {
     "use strict";
-    fileEvidenceSchema = z7.object({
-      kind: z7.literal("file"),
-      sha256: z7.string().length(64),
-      timestamp: z7.string().datetime(),
-      path: z7.string().min(1),
-      mime: z7.string().optional(),
-      description: z7.string().optional()
-    });
-    logEvidenceSchema = z7.object({
-      kind: z7.literal("log"),
-      sha256: z7.string().length(64),
-      timestamp: z7.string().datetime(),
-      source: z7.string().min(1),
-      description: z7.string().optional()
-    });
-    screenshotEvidenceSchema = z7.object({
-      kind: z7.literal("screenshot"),
-      sha256: z7.string().length(64),
-      timestamp: z7.string().datetime(),
-      mime: z7.enum(["image/png", "image/jpeg", "image/webp"]).optional(),
-      description: z7.string().optional()
-    });
-    testOutputEvidenceSchema = z7.object({
-      kind: z7.literal("test-output"),
-      sha256: z7.string().length(64),
-      timestamp: z7.string().datetime(),
-      passed: z7.number().int().nonnegative(),
-      failed: z7.number().int().nonnegative(),
-      skipped: z7.number().int().nonnegative(),
-      exitCode: z7.number().int(),
-      description: z7.string().optional()
-    });
-    commandOutputEvidenceSchema = z7.object({
-      kind: z7.literal("command-output"),
-      sha256: z7.string().length(64),
-      timestamp: z7.string().datetime(),
-      cmd: z7.string().min(1),
-      exitCode: z7.number().int(),
-      description: z7.string().optional()
-    });
-    taskEvidenceSchema = z7.discriminatedUnion("kind", [
+    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,
       logEvidenceSchema,
       screenshotEvidenceSchema,
@@ -2932,12 +2965,12 @@ var init_task_evidence = __esm({
 });
 
 // packages/contracts/src/tasks/archive.ts
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 var ArchiveReason, ARCHIVE_REASON_VALUES;
 var init_archive = __esm({
   "packages/contracts/src/tasks/archive.ts"() {
     "use strict";
-    ArchiveReason = z8.enum([
+    ArchiveReason = z9.enum([
       "verified",
       "reconciled",
       "superseded",
@@ -2969,6 +3002,7 @@ var init_src2 = __esm({
     init_nexus_scope_map();
     init_params();
     init_peer();
+    init_evidence_atoms();
     init_plan();
     init_session2();
     init_session_journal();
@@ -3234,8 +3268,10 @@ function emitLafsViolation(err) {
       timestamp: (/* @__PURE__ */ new Date()).toISOString()
     }
   };
-  process.stderr.write(`${JSON.stringify(envelope)}
+  if (process.env["CLEO_DEBUG"]) {
+    process.stderr.write(`${JSON.stringify(envelope)}
 `);
+  }
   process.exitCode = 104 /* LAFS_VIOLATION */;
 }
 var ENVELOPE_SUCCESS_KEY, ENVELOPE_DATA_KEY, ENVELOPE_META_KEY, LafsViolationError;
@@ -5181,7 +5217,7 @@ __export(renderers_exports, {
   renderWaves: () => renderWaves
 });
 import { randomUUID } from "node:crypto";
-import { formatSuccess } from "@cleocode/core";
+import { drainWarnings, formatSuccess } from "@cleocode/core";
 import { applyFieldFilter, extractFieldFromResult } from "@cleocode/lafs";
 function generateRequestId() {
   return randomUUID();
@@ -5369,6 +5405,11 @@ function cliError(message, code, details, meta) {
     timestamp: meta?.timestamp ?? (/* @__PURE__ */ new Date()).toISOString(),
     ...meta
   };
+  const drained = drainWarnings();
+  if (drained && drained.length > 0) {
+    const existing = errorMeta.warnings;
+    errorMeta.warnings = Array.isArray(existing) ? [...existing, ...drained] : drained;
+  }
   const envelope = {
     success: false,
     error: errorObj,
@@ -37763,6 +37804,7 @@ __export(briefing_exports, {
 });
 import { existsSync as existsSync8, readFileSync as readFileSync8 } from "node:fs";
 import { join as join9 } from "node:path";
+import { pushWarning } from "@cleocode/core";
 import { resolveLegacyCleoDir } from "@cleocode/paths";
 function resolveInjectionTemplatePath() {
   const xdgConfig = resolveLegacyCleoDir(process.env["XDG_CONFIG_HOME"]);
@@ -37794,8 +37836,19 @@ function renderForAdapter(sectionName, content, format) {
 async function runBriefingInject(sectionName, formatStr) {
   const templatePath = resolveInjectionTemplatePath();
   if (!existsSync8(templatePath)) {
-    process.stderr.write(`[briefing inject] CLEO-INJECTION.md not found at ${templatePath}
-`);
+    pushWarning({
+      code: "W_TEMPLATE_INJECT_FAILED",
+      message: `CLEO-INJECTION.md not found at ${templatePath}`
+    });
+    cliError(
+      `CLEO-INJECTION.md not found at ${templatePath}`,
+      1,
+      {
+        name: "E_TEMPLATE_NOT_FOUND",
+        fix: "Re-run `cleo init` or restore the templates directory."
+      },
+      { operation: "briefing.inject" }
+    );
     process.exitCode = 1;
     return;
   }
@@ -37803,10 +37856,18 @@ async function runBriefingInject(sectionName, formatStr) {
   const section = extractSection(content, sectionName);
   if (section === null) {
     const available = INJECTION_SECTION_NAMES.join(", ");
-    process.stderr.write(
-      `[briefing inject] Section "${sectionName}" not found in CLEO-INJECTION.md.
-Available sections: ${available}
-`
+    pushWarning({
+      code: "W_TEMPLATE_INJECT_FAILED",
+      message: `Section "${sectionName}" not found in CLEO-INJECTION.md.`
+    });
+    cliError(
+      `Section "${sectionName}" not found in CLEO-INJECTION.md. Available sections: ${available}`,
+      1,
+      {
+        name: "E_VALIDATION",
+        fix: `Pass one of: ${available}`
+      },
+      { operation: "briefing.inject" }
     );
     process.exitCode = 1;
     return;
@@ -37815,9 +37876,19 @@ Available sections: ${available}
   if (formatStr.startsWith("adapter:")) {
     const adapterName = formatStr.slice("adapter:".length);
     if (!ADAPTER_FORMATS.includes(adapterName)) {
-      process.stderr.write(
-        `[briefing inject] Unknown adapter format "${adapterName}". Supported: ${ADAPTER_FORMATS.join(", ")}
-`
+      const supported = ADAPTER_FORMATS.join(", ");
+      pushWarning({
+        code: "W_TEMPLATE_INJECT_FAILED",
+        message: `Unknown adapter format "${adapterName}".`
+      });
+      cliError(
+        `Unknown adapter format "${adapterName}". Supported: ${supported}`,
+        1,
+        {
+          name: "E_VALIDATION",
+          fix: `Pass one of: ${supported}`
+        },
+        { operation: "briefing.inject" }
       );
       process.exitCode = 1;
       return;
@@ -37833,6 +37904,7 @@ var init_briefing = __esm({
     init_dist();
     init_cli();
     init_subcommand_guard();
+    init_renderers();
     INJECTION_SECTION_NAMES = [
       "session-start",
       "work-loop",
@@ -48051,6 +48123,7 @@ var init_llm_stream = __esm({
   "packages/cleo/src/cli/commands/llm-stream.ts"() {
     "use strict";
     init_dist();
+    init_renderers();
     streamCommand = defineCommand({
       meta: {
         name: "stream",
@@ -48094,11 +48167,21 @@ var init_llm_stream = __esm({
         const provider = String(a["provider"] ?? "").trim();
         const prompt = String(a["prompt"] ?? "").trim();
         if (!provider) {
-          process.stderr.write("[error] cleo llm stream: <provider> is required.\n");
+          cliError(
+            "cleo llm stream: <provider> is required.",
+            2,
+            { name: "E_VALIDATION", fix: "Pass a provider as the first positional argument." },
+            { operation: "llm.stream" }
+          );
           process.exit(2);
         }
         if (!prompt) {
-          process.stderr.write("[error] cleo llm stream: <prompt> is required.\n");
+          cliError(
+            "cleo llm stream: <prompt> is required.",
+            2,
+            { name: "E_VALIDATION", fix: "Pass a prompt as the second positional argument." },
+            { operation: "llm.stream" }
+          );
           process.exit(2);
         }
         const model = typeof a["model"] === "string" && a["model"] ? a["model"] : void 0;
@@ -48114,8 +48197,12 @@ var init_llm_stream = __esm({
           await runLlmStream({ provider, prompt, model, maxTokens, temperature, showThink, system });
         } catch (err) {
           const msg = err instanceof Error ? err.message : String(err);
-          process.stderr.write(`[error] cleo llm stream: ${msg}
-`);
+          cliError(
+            `cleo llm stream: ${msg}`,
+            1,
+            { name: "E_LLM_STREAM_FAILED" },
+            { operation: "llm.stream" }
+          );
           process.exit(1);
         }
       }
@@ -48525,6 +48612,7 @@ var llm_exports = {};
 __export(llm_exports, {
   llmCommand: () => llmCommand
 });
+import { pushWarning as pushWarning2 } from "@cleocode/core";
 async function getListProviders() {
   const { listProviders } = await import(
     /* webpackIgnore: true */
@@ -48629,8 +48717,11 @@ var init_llm3 = __esm({
           apiKey = await readApiKeyFromStdin();
           source = "stdin";
           if (!apiKey) {
-            process.stderr.write(
-              '[error] --api-key-stdin set but stdin is empty or a TTY. Pipe the secret in, e.g. `echo "$KEY" | cleo llm add ...`.\n'
+            cliError(
+              '--api-key-stdin set but stdin is empty or a TTY. Pipe the secret in, e.g. `echo "$KEY" | cleo llm add ...`.',
+              2,
+              { name: "E_VALIDATION", fix: "Pipe the secret to stdin or use --api-key-env=NAME." },
+              { operation: "llm.add" }
             );
             process.exit(2);
           }
@@ -48638,20 +48729,37 @@ var init_llm3 = __esm({
           const envName = a["api-key-env"];
           const envValue = process.env[envName];
           if (!envValue) {
-            process.stderr.write(`[error] --api-key-env=${envName} is not set in the environment.
-`);
+            cliError(
+              `--api-key-env=${envName} is not set in the environment.`,
+              2,
+              {
+                name: "E_VALIDATION",
+                fix: `Export ${envName} before running, or use --api-key-stdin.`
+              },
+              { operation: "llm.add" }
+            );
             process.exit(2);
           }
           apiKey = envValue;
           source = "env";
         } else if (typeof a["api-key"] === "string" && a["api-key"]) {
-          process.stderr.write(`${API_KEY_FLAG_DEPRECATION}
-`);
+          pushWarning2({
+            code: "W_DEPRECATED_FLAG",
+            message: API_KEY_FLAG_DEPRECATION,
+            deprecated: "--api-key=<value>",
+            replacement: "--api-key-stdin or --api-key-env=NAME"
+          });
           apiKey = a["api-key"];
           source = "flag";
         } else {
-          process.stderr.write(
-            "[error] cleo llm add requires one of --api-key-stdin (recommended), --api-key-env=NAME, or --api-key=<value> (deprecated).\n"
+          cliError(
+            "cleo llm add requires one of --api-key-stdin (recommended), --api-key-env=NAME, or --api-key=<value> (deprecated).",
+            2,
+            {
+              name: "E_VALIDATION",
+              fix: "Provide the credential via --api-key-stdin, --api-key-env=NAME, or --api-key=<value>."
+            },
+            { operation: "llm.add" }
           );
           process.exit(2);
         }
@@ -48913,8 +49021,12 @@ var init_llm3 = __esm({
             `Logged in to ${result.data.provider} as '${result.data.label}'` + (result.data.expiresIn != null ? ` (expires in ${Math.round(result.data.expiresIn / 60)} min)` : "") + "\n"
           );
         } else if (result.error) {
-          process.stderr.write(`[error] ${result.error.message}
-`);
+          cliError(
+            result.error.message,
+            result.error.code || 1,
+            { name: result.error.codeName },
+            { operation: "llm.login" }
+          );
           process.exit(1);
         }
       }
@@ -48943,8 +49055,12 @@ var init_llm3 = __esm({
 `
           );
         } else if (!result.success) {
-          process.stderr.write(`[error] ${result.error?.message ?? "refresh failed"}
-`);
+          cliError(
+            result.error?.message ?? "refresh failed",
+            result.error?.code ?? 1,
+            { name: "E_REFRESH_FAILED" },
+            { operation: "llm.refreshCatalog" }
+          );
           process.exit(1);
         }
       }
@@ -56399,7 +56515,7 @@ __export(release_exports, {
   SHIP_DEPRECATION_NOTICE: () => SHIP_DEPRECATION_NOTICE,
   releaseCommand: () => releaseCommand
 });
-import { release as release2 } from "@cleocode/core";
+import { pushWarning as pushWarning3, release as release2 } from "@cleocode/core";
 var SHIP_DEPRECATION_NOTICE, shipCommand, listCommand18, showCommand10, cancelCommand2, changelogCommand, rollbackCommand, rollbackFullCommand, prStatusCommand, channelCommand, planCommand3, openCommand2, reconcileCommand4, releaseCommand;
 var init_release3 = __esm({
   "packages/cleo/src/cli/commands/release.ts"() {
@@ -56430,8 +56546,12 @@ var init_release3 = __esm({
         }
       },
       async run({ args }) {
-        process.stderr.write(`${SHIP_DEPRECATION_NOTICE}
-`);
+        pushWarning3({
+          code: "W_DEPRECATED_COMMAND",
+          message: SHIP_DEPRECATION_NOTICE,
+          deprecated: "cleo release ship",
+          replacement: "cleo release plan <version> --epic <id> && cleo release open <version>"
+        });
         await dispatchFromCli(
           "mutate",
           "release",
@@ -66444,6 +66564,32 @@ function resolveFormat(opts, defaults) {
   return resolveOutputFormat(input2);
 }
 
+// packages/cleo/src/cli/resolve-subcommand.ts
+async function resolveLazyValue(input2) {
+  if (typeof input2 === "function") {
+    return resolveLazyValue(input2());
+  }
+  return Promise.resolve(input2);
+}
+async function resolveSubCommandForHelp(cmd, rawArgs) {
+  let current = cmd;
+  let parent;
+  let remaining = [...rawArgs];
+  while (true) {
+    const subCommands2 = await resolveLazyValue(current.subCommands);
+    if (!subCommands2 || Object.keys(subCommands2).length === 0) return [current, parent];
+    const subIndex = remaining.findIndex((arg) => !arg.startsWith("-"));
+    if (subIndex < 0) return [current, parent];
+    const subName = remaining[subIndex];
+    if (subName === void 0 || !(subName in subCommands2)) return [current, parent];
+    const next = await resolveLazyValue(subCommands2[subName]);
+    if (!next) return [current, parent];
+    parent = current;
+    current = next;
+    remaining = remaining.slice(subIndex + 1);
+  }
+}
+
 // packages/cleo/src/cli/index.ts
 {
   const [major] = process.versions.node.split(".").map(Number);
@@ -66577,7 +66723,8 @@ async function runMainWithLafsEnvelope(cmd, rawArgs, showUsage2) {
   const helpFlags = ["--help", "-h"];
   const versionFlags = ["--version", "-V"];
   if (rawArgs.some((a) => helpFlags.includes(a))) {
-    await showUsage2(cmd);
+    const [leafCmd, parentCmd] = await resolveSubCommandForHelp(cmd, rawArgs);
+    await showUsage2(leafCmd, parentCmd);
     process.exit(0);
   }
   if (rawArgs.length === 1 && versionFlags.includes(rawArgs[0])) {
@@ -66592,22 +66739,26 @@ async function runMainWithLafsEnvelope(cmd, rawArgs, showUsage2) {
 `);
     process.exit(0);
   }
-  try {
-    await runCommand(cmd, { rawArgs });
-  } catch (err) {
-    const { cliError: cliError2 } = await Promise.resolve().then(() => (init_renderers(), renderers_exports));
-    const cittyCliError = asCittyCliError(err);
-    if (cittyCliError) {
-      cliError2(cittyCliError.message, 1, {
-        name: cittyCliError.code === "EARG" ? "E_VALIDATION" : `E_${cittyCliError.code}`,
-        fix: `Run 'cleo <command> --help' to see required arguments.`
-      });
+  const { WarningCollector, withWarningCollector } = await import("@cleocode/lafs");
+  const collector = new WarningCollector();
+  await withWarningCollector(collector, async () => {
+    try {
+      await runCommand(cmd, { rawArgs });
+    } catch (err) {
+      const { cliError: cliError2 } = await Promise.resolve().then(() => (init_renderers(), renderers_exports));
+      const cittyCliError = asCittyCliError(err);
+      if (cittyCliError) {
+        cliError2(cittyCliError.message, 1, {
+          name: cittyCliError.code === "EARG" ? "E_VALIDATION" : `E_${cittyCliError.code}`,
+          fix: `Run 'cleo <command> --help' to see required arguments.`
+        });
+        process.exit(1);
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      cliError2(message, 1, { name: "E_CLI_UNCAUGHT" });
       process.exit(1);
     }
-    const message = err instanceof Error ? err.message : String(err);
-    cliError2(message, 1, { name: "E_CLI_UNCAUGHT" });
-    process.exit(1);
-  }
+  });
 }
 async function runStartupMaintenance() {
   const {