@cleocode/contracts 2026.9.21 → 2026.9.22

package/src/__tests__/evidence-atom-schema.test.ts

@@ -499,6 +499,28 @@ describe('parseEvidenceString (T10337)', () => {
 
 // ─── GATE_EVIDENCE_REQUIREMENTS — gate-to-atom mapping ─────────────────────
 
+describe('pr:/ci: component references (T12671)', () => {
+  it('pr:<component>@<integration> names the integration PR and its component', () => {
+    expect(parseEvidenceString('pr:42@41')).toEqual([
+      { kind: 'pr', prNumber: 41, componentPrNumber: 42 },
+    ]);
+    expect(parseEvidenceString('ci:42@41')).toEqual([
+      { kind: 'ci', prNumber: 41, componentPrNumber: 42 },
+    ]);
+    expect(parseEvidenceString('pr:41')).toEqual([{ kind: 'pr', prNumber: 41 }]);
+  });
+
+  it.each(['pr:42@42', 'pr:42@', 'pr:@41', 'ci:0@41', 'pr:42@4x'])('rejects %s', (raw) => {
+    expect(() => parseEvidenceString(raw)).toThrow(EvidenceParseError);
+  });
+
+  it('the schema accepts the component field', () => {
+    expect(
+      EvidenceAtomSchema.safeParse({ kind: 'ci', prNumber: 41, componentPrNumber: 42 }).success,
+    ).toBe(true);
+  });
+});
+
 describe('GATE_EVIDENCE_REQUIREMENTS (T10337)', () => {
   it('covers every VerificationGate', () => {
     const expected: VerificationGate[] = [

package/src/dispatch/operations-registry.ts

@@ -8456,6 +8456,7 @@ export const OPERATIONS: OperationDef[] = [
         enum: DOCS_LIFECYCLE_STATUSES,
         description:
           'Override the new lifecycle status. Defaults to "draft" on every update. ' +
+          'Alone (no file or content) it changes only the lifecycle status. ' +
           `Valid: ${DOCS_LIFECYCLE_STATUSES.join('|')}.`,
       },
       {

package/src/done-plan.ts

@@ -119,6 +119,11 @@ export interface TaskChangeSet {
   executionRoot: string;
   /** Why {@link executionRoot} was chosen. */
   rootSource: ChangeSetRootSource;
+  /**
+   * Component PR whose change the (integration) `prNumber` landed on the
+   * default branch (T12671). Evidence is then `pr:<component>@<prNumber>`.
+   */
+  componentPrNumber?: number;
   /** Merged PR number (`source === 'pr'`). */
   prNumber?: number;
   /**
@@ -168,8 +173,23 @@ export interface TaskChangeSet {
   blockers: DonePlanBlocker[];
   /** Non-blocking observations, e.g. PR discovery that could not reach `gh`. */
   warnings: string[];
+  /**
+   * The merged-PR lookup failed (e.g. `gh` unavailable), so a non-PR change set
+   * does not prove the change is unmerged (T12656).
+   */
+  prDiscoveryFailed?: boolean;
+  /**
+   * Whether the task's PR has merged to the default branch, as the PR lookup
+   * found it — independent of `source` (T12656 review): a merged PR whose
+   * `pr:` check was refused still falls back to the task branch, and the
+   * branch outlives a squash merge. Absent when no PR was examined.
+   */
+  mergeState?: ChangeSetMergeState;
 }
 
+/** Whether a task's change has merged to the default branch. */
+export type ChangeSetMergeState = 'merged' | 'unmerged' | 'unknown';
+
 /** Planned state of one verification gate. */
 export interface DonePlanGate {
   /** Gate name. */

package/src/evidence-atom-schema.ts

@@ -198,7 +198,11 @@ export const decisionAtomSchema = z.object({
  * checks task relationship and changed artifacts. Implementation also needs
  * inspected file evidence; testing and review require actual result atoms.
  *
- * Format: `pr:<positive integer>` (e.g. `pr:357`).
+ * Format: `pr:<positive integer>` (e.g. `pr:357`), or
+ * `pr:<component>@<integration>` (e.g. `pr:356@357`, T12671): component PR
+ * #356 merged into an integration branch that PR #357 landed on the default
+ * branch. The integration PR supplies the merge commit; the component PR
+ * supplies the task linkage and the changed files.
  *
  * @task T9764
  * @task T9838
@@ -206,6 +210,7 @@ export const decisionAtomSchema = z.object({
 export const prAtomSchema = z.object({
   kind: z.literal('pr'),
   prNumber: z.number().int().positive('pr atom requires a positive integer PR number'),
+  componentPrNumber: z.number().int().positive().optional(),
 });
 
 /**
@@ -214,13 +219,16 @@ export const prAtomSchema = z.object({
  * `qaPassed` only when the project opts in with `evidence.ciSatisfies`
  * (owner decision D11149).
  *
- * Format: `ci:<positive integer>` (e.g. `ci:357`).
+ * Format: `ci:<positive integer>` (e.g. `ci:357`), or
+ * `ci:<component>@<integration>` (e.g. `ci:356@357`, T12671): the integration
+ * PR's merge-commit CI, for a task linked through its component PR.
  *
  * @task T12634
  */
 export const ciAtomSchema = z.object({
   kind: z.literal('ci'),
   prNumber: z.number().int().positive('ci atom requires a positive integer PR number'),
+  componentPrNumber: z.number().int().positive().optional(),
 });
 
 /**
@@ -771,6 +779,21 @@ export class EvidenceParseError extends Error {
  * @task T10337
  * @adr ADR-051
  */
+/**
+ * `<n>` or `<component>@<integration>` (T12671), each a positive integer.
+ * The integration PR is the atom's `prNumber`.
+ */
+function parsePrReference(
+  payload: string,
+): { prNumber: number; componentPrNumber?: number } | null {
+  const match = /^(\d+)(?:@(\d+))?$/.exec(payload);
+  if (!match) return null;
+  const first = Number(match[1]);
+  const second = match[2] === undefined ? null : Number(match[2]);
+  if (first <= 0 || (second !== null && (second <= 0 || second === first))) return null;
+  return second === null ? { prNumber: first } : { prNumber: second, componentPrNumber: first };
+}
+
 export function parseEvidenceString(raw: string): EvidenceAtom[] {
   if (!raw || typeof raw !== 'string') {
     throw new EvidenceParseError(
@@ -840,26 +863,16 @@ export function parseEvidenceString(raw: string): EvidenceAtom[] {
         atoms.push({ kind: 'decision', decisionId: payload });
         break;
       }
-      case 'pr': {
-        const prNumber = Number(payload);
-        if (!Number.isInteger(prNumber) || prNumber <= 0) {
-          throw new EvidenceParseError(
-            `pr atom requires a positive integer PR number, got "${payload}" in "${chunk}"`,
-            'Use format: pr:<number> e.g. pr:357',
-          );
-        }
-        atoms.push({ kind: 'pr', prNumber });
-        break;
-      }
+      case 'pr':
       case 'ci': {
-        const prNumber = Number(payload);
-        if (!Number.isInteger(prNumber) || prNumber <= 0) {
+        const ref = parsePrReference(payload);
+        if (!ref) {
           throw new EvidenceParseError(
-            `ci atom requires a positive integer PR number, got "${payload}" in "${chunk}"`,
-            'Use format: ci:<number> e.g. ci:357',
+            `${kind} atom requires a positive integer PR number, got "${payload}" in "${chunk}"`,
+            `Use format: ${kind}:<number> e.g. ${kind}:357, or ${kind}:<component>@<integration> e.g. ${kind}:356@357`,
           );
         }
-        atoms.push({ kind: 'ci', prNumber });
+        atoms.push(kind === 'pr' ? { kind: 'pr', ...ref } : { kind: 'ci', ...ref });
         break;
       }
       case 'loc-drop': {

package/src/index.ts

@@ -516,6 +516,7 @@ export type {
 // === Done planner: read-only `cleo done --plan` evidence plan (T12623, T12624) ===
 export type {
   ChangeSetDoc,
+  ChangeSetMergeState,
   ChangeSetPrCandidate,
   ChangeSetRootSource,
   ChangeSetSource,

package/src/operations/docs.ts

@@ -715,7 +715,9 @@ export type DocsLifecycleStatus = (typeof DOCS_LIFECYCLE_STATUSES)[number];
  * {@link DocsSupersedeParams}-style flows, NO supersession edge is created
  * (callers wanting an explicit lineage edge should use `cleo docs supersede`).
  *
- * Exactly one of `file` or `content` MUST be provided.
+ * At most one of `file` or `content` may be provided. With neither, `status`
+ * is required and the update changes only the lifecycle status, keeping the
+ * stored bytes (T12654).
  *
  * @task T10161 (Epic T10157 / Saga T9855 — E12.C4)
  */
@@ -738,7 +740,8 @@ export interface DocsUpdateParams {
   /**
    * Override the new lifecycle status. Defaults to `'draft'` on every update
    * so an explicit `accepted` doc gets back-pressured to draft on edit. Pass
-   * `--status accepted` (or any other valid status) to override.
+   * `--status accepted` (or any other valid status) to override. Passed alone
+   * (no `file`/`content`), it changes only the lifecycle status.
    */
   status?: DocsLifecycleStatus;
   /** Validate/preflight only; do not mutate attachment rows, blob storage, or audit logs. */

package/src/task.ts

@@ -170,6 +170,12 @@ export interface EvidenceValidationContext {
   criteria: ReadonlyArray<Pick<AcRow, 'id' | 'text' | 'updatedAt'>>;
   /** Verified PR merge whose immutable artifact bytes must be inspected. */
   artifactCommitSha?: string;
+  /**
+   * Validate without persisting anything: `pr:`/`ci:` lookups write neither
+   * the PR-result cache nor the branch-protection cache (T12671 review — the
+   * `cleo done --plan` preview must leave `.cleo/` untouched).
+   */
+  readOnly?: boolean;
 }
 
 /** Explicit criterion link to inspected artifacts and validated results in one gate receipt. */
@@ -371,10 +377,19 @@ export type EvidenceAtom =
       successCount: number;
       /** Total number of checks evaluated in the rollup. */
       totalChecks: number;
-      /** Complete PR changed-file inventory retained for task-scope checks and display. */
+      /**
+       * Changed-file inventory retained for task-scope checks and display. With
+       * `componentPrNumber`, the component PR's files that survive in this
+       * PR's merge commit — never the whole integration PR.
+       */
       changedPaths?: string[];
       /** Explicit task relationship established when this atom was accepted. */
       taskId?: string;
+      /**
+       * Component PR this (integration) PR landed on the default branch
+       * (T12671): the task is linked through it and its files are the change.
+       */
+      componentPrNumber?: number;
     }
   | {
       /**
@@ -410,6 +425,8 @@ export type EvidenceAtom =
       testedTree?: string;
       /** Task the PR was verified to be linked to (T12634). */
       taskId?: string;
+      /** Component PR the task is linked through; its CI ran as this integration PR's (T12671). */
+      componentPrNumber?: number;
       /** Which configured checks attest each gate (`evidence.ciChecks`). */
       gateChecks?: { testsPassed?: string[]; qaPassed?: string[] };
       /** Where the required-check list came from (env, project context, branch protection). */