@cleocode/contracts 2026.10.10-canary.2 → 2026.10.10

package/src/dispatch/operations-registry.ts

@@ -8169,6 +8169,61 @@ export const OPERATIONS: OperationDef[] = [
       },
     ],
   },
+  // ── docs.link-decision / docs.unlink-decision (T13598) ──────────────────
+  {
+    gateway: 'mutate',
+    domain: 'docs',
+    operation: 'link-decision',
+    description:
+      'docs.link-decision (mutate) — link a D#### decision to the ADR doc that ratifies it (decision_adr_links); idempotent, refuses a revoked pair (T13598)',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['adrSlug', 'decisionId'],
+    params: [
+      {
+        name: 'adrSlug',
+        type: 'string' as const,
+        required: true,
+        description: 'Slug of the ADR doc',
+        cli: { positional: true },
+      },
+      {
+        name: 'decisionId',
+        type: 'string' as const,
+        required: true,
+        description: 'The D#### brain ledger decision id the ADR ratifies',
+        cli: { positional: true },
+      },
+    ],
+  },
+  {
+    gateway: 'mutate',
+    domain: 'docs',
+    operation: 'unlink-decision',
+    description:
+      'docs.unlink-decision (mutate) — revoke a decision-to-ADR link as a permanent tombstone; the pair can never be re-linked (T13598)',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['adrSlug', 'decisionId'],
+    params: [
+      {
+        name: 'adrSlug',
+        type: 'string' as const,
+        required: true,
+        description: 'Slug of the ADR doc',
+        cli: { positional: true },
+      },
+      {
+        name: 'decisionId',
+        type: 'string' as const,
+        required: true,
+        description: 'The D#### brain ledger decision id to unlink',
+        cli: { positional: true },
+      },
+    ],
+  },
   // ── docs.supersede (T10162) ──────────────────────────────────────────────
   {
     gateway: 'mutate',
@@ -9477,6 +9532,13 @@ export const OPERATIONS: OperationDef[] = [
         required: false,
         description: 'Require the unified-hooks pilot for this stable promotion',
       },
+      {
+        name: 'hooksV1Waiver',
+        type: 'string',
+        required: false,
+        description:
+          'Audited reason to ship a source change that opens the hooks-v1 gate without the promotion',
+      },
       {
         name: 'dryRun',
         type: 'boolean',

package/src/invariants/sync-write-invariants.ts

@@ -519,6 +519,21 @@ export const SYNC_WRITE_INVARIANTS: readonly SyncWriteInvariant[] = Object.freez
     [],
     'the projection keeps the max-HLC head; a losing concurrent head is recorded (conflict_count/last_conflict_json), never silently shadowed',
   ),
+  // T13359 (D11165) — decisions-vs-ADRs link table; the natural composite key
+  // makes identical links merge to one row, and the revoke is a one-way latch.
+  // T13597: enforced at merge, not just by the local accessor — 'revoked' is an
+  // absorbing state with no leave op, so a concurrent same-uid link op cannot
+  // flip a tombstoned row back to 'linked' on any replica.
+  implemented(
+    rule(
+      'docs.decision-adr-links.revoke-monotonic',
+      'T13597',
+      'decision_adr_links',
+      ['status', 'revoked_by'],
+      [],
+      'status flips linked→revoked exactly once (the row is the tombstone, never DELETEd); the merge engine refuses a non-absorbing status write onto a revoked row, so a concurrent re-link can never resurrect the pair',
+    ),
+  ),
 
   // §3.6.0 identity-layer rows.
   {

package/src/operations/docs.ts

@@ -371,6 +371,15 @@ export interface DocsFetchResult {
   inlined: boolean;
   /** Current attachment backend in use. */
   attachmentBackend?: AttachmentBackend;
+  /**
+   * `D####` brain ledger decisions linked to this ADR doc through
+   * `decision_adr_links` (T13359, spec `cleodocs-rearch-design` §4/§10,
+   * D11165) — the ADR→decision direction of the two-way trace. Present only
+   * for fetched docs that have live (non-revoked) links; the ledger stays
+   * the operational authority, so an ADR always names the decisions it
+   * ratifies.
+   */
+  linkedDecisions?: string[];
 }
 
 // --------------------------------------------------------------------------
@@ -899,6 +908,38 @@ export interface DocsSupersedeResult {
   reason?: string;
 }
 
+// --------------------------------------------------------------------------
+// docs.link-decision / docs.unlink-decision — decision_adr_links writers (T13598)
+// --------------------------------------------------------------------------
+
+/**
+ * Parameters for `docs.link-decision` and `docs.unlink-decision`.
+ *
+ * @task T13598
+ */
+export interface DocsDecisionLinkParams {
+  /** The ADR doc slug (`adr-NNN-…`). */
+  adrSlug: string;
+  /** The `D####` brain ledger decision id. */
+  decisionId: string;
+}
+
+/**
+ * Result of `docs.link-decision` and `docs.unlink-decision`.
+ *
+ * @task T13598
+ */
+export interface DocsDecisionLinkResult {
+  /** The ADR doc slug. */
+  adrSlug: string;
+  /** The `D####` decision id. */
+  decisionId: string;
+  /** The link's state after the call. */
+  status: 'linked' | 'revoked';
+  /** False for an idempotent repeat (already linked, or already revoked). */
+  changed: boolean;
+}
+
 // --------------------------------------------------------------------------
 // docs.doctor — store health diagnostics + safe repairs (T13447)
 // --------------------------------------------------------------------------
@@ -1006,6 +1047,8 @@ export type DocsOps =
   | { op: 'docs.remove'; params: DocsRemoveParams; result: DocsRemoveResult }
   | { op: 'docs.update'; params: DocsUpdateParams; result: DocsUpdateResult }
   | { op: 'docs.supersede'; params: DocsSupersedeParams; result: DocsSupersedeResult }
+  | { op: 'docs.link-decision'; params: DocsDecisionLinkParams; result: DocsDecisionLinkResult }
+  | { op: 'docs.unlink-decision'; params: DocsDecisionLinkParams; result: DocsDecisionLinkResult }
   | { op: 'docs.doctor'; params: DocsDoctorParams; result: DocsDoctorResult };
 
 /**
@@ -1024,4 +1067,6 @@ export type DocsOp =
   | 'docs.remove'
   | 'docs.update'
   | 'docs.supersede'
+  | 'docs.link-decision'
+  | 'docs.unlink-decision'
   | 'docs.doctor';

package/src/release/plan.ts

@@ -379,6 +379,8 @@ export const ReleasePlanSchema = z
     releaseKind: ReleaseKindSchema,
     /** Explicit hooks-v1 stable promotion; ordinary and hotfix releases are exempt. */
     hooksV1Promotion: z.boolean().optional(),
+    /** Audited reason for shipping a source change that opens the hooks-v1 gate without the promotion (T13555). */
+    hooksV1Waiver: NonEmptyString.optional(),
     /** ISO-8601 timestamp the plan was written. */
     createdAt: Iso8601,
     /** Identifier of the actor that wrote the plan (agent name or operator). */

package/src/task.ts

@@ -344,6 +344,10 @@ export type EvidenceAtom =
       treeHash?: string;
       /** Tracked `evidence.runtimePaths` files the tree hash left out (T13554). */
       runtimeExcluded?: string[];
+      /** Changed code paths this receipt's roots leave uncovered; judged with its kind's other receipts (T13580). */
+      uncovered?: string[];
+      /** Dependent packages this receipt's roots leave uncovered (T13580). */
+      uncoveredPackages?: string[];
     }
   | {
       kind: 'tool';