@cleocode/contracts 2026.10.12 → 2026.10.13

package/src/attachment.ts

@@ -177,7 +177,9 @@ export type AttachmentKind = Attachment['kind'];
 
 /**
  * Persisted metadata row for one attachment in the attachment registry
- * (`.cleo/attachments/index.db`).
+ * (the `attachments` table of the project `cleo.db`, twin-carried into
+ * `docs_attachments`; the legacy `.cleo/attachments/index.db` file is
+ * retired — T13362).
  *
  * The full {@link Attachment} value is stored as a JSON blob in the `attachment`
  * field so the registry does not need a column per variant.
@@ -217,7 +219,8 @@ export interface AttachmentMetadata {
 /**
  * Junction row linking one attachment to one owner.
  *
- * Stored in the `attachment_refs` table of `.cleo/attachments/index.db`.
+ * Stored in the `attachment_refs` table of the project `cleo.db`
+ * (twin-carried into `docs_attachment_refs`).
  * A single attachment can be referenced by multiple owners simultaneously
  * (e.g., the same RFC PDF attached to an epic and to every child task).
  */

package/src/branch-lock.ts

@@ -17,6 +17,8 @@
  * @adr ADR-062
  */
 
+import type { WorktreeDisposalBlockers } from './operations/worktree.js';
+
 // ---------------------------------------------------------------------------
 // L1 — Worktree lifecycle types
 // ---------------------------------------------------------------------------
@@ -85,6 +87,8 @@ export interface WorktreeMergeResult {
   rebased: boolean;
   /** Whether the worktree filesystem entry was removed. */
   worktreeRemoved: boolean;
+  /** Set when the worktree was kept because something still needs its files (T13696). */
+  worktreeKept?: WorktreeDisposalBlockers;
   /** Whether `task/<taskId>` was deleted post-merge. */
   branchDeleted: boolean;
   /** Error message if any step failed (non-fatal — caller decides). */

package/src/config.ts

@@ -10,6 +10,7 @@
  */
 
 import type { HeavyCommandHookMode } from './heavy-command-hook.js';
+import type { LeanConfig } from './lean.js';
 import type { ModelTransport } from './operations/llm.js';
 
 /** Output format options. */
@@ -895,6 +896,12 @@ export interface ResourcesConfig {
 
 /** CLEO project configuration (config.json). */
 export interface CleoConfig {
+  /**
+   * ct-lean rule level (T13663).
+   *
+   * @defaultValue undefined (level `full`)
+   */
+  lean?: LeanConfig;
   /** Configuration schema version string. */
   version: string;
   /** Output formatting preferences. */

package/src/dispatch/__tests__/operation-envelope-snapshots.test.ts

@@ -112,6 +112,14 @@ describe('operation envelope registry snapshots (T10615)', () => {
               "required": false,
               "type": "string",
             },
+            {
+              "cli": {
+                "flag": "base-version-uid",
+              },
+              "name": "baseVersionUid",
+              "required": false,
+              "type": "string",
+            },
             {
               "cli": undefined,
               "name": "message",

package/src/dispatch/operations-registry.ts

@@ -5038,6 +5038,35 @@ export const OPERATIONS: OperationDef[] = [
       },
     ] satisfies ParamDef[],
   },
+  {
+    gateway: 'mutate',
+    domain: 'pipeline',
+    operation: 'manifest.update',
+    description:
+      'pipeline.manifest.update (mutate) — change only the given fields of a manifest entry; linkTask adds a linked task (T13678)',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['id'],
+    params: [
+      { name: 'id', type: 'string', required: true, description: 'Manifest entry id' },
+      {
+        name: 'linkTask',
+        type: 'string',
+        required: false,
+        description: 'Task id to add to linked_tasks',
+      },
+      { name: 'title', type: 'string', required: false, description: 'New title' },
+      { name: 'topics', type: 'array', required: false, description: 'Replacement topics' },
+      {
+        name: 'key_findings',
+        type: 'array',
+        required: false,
+        description: 'Replacement key findings',
+      },
+      { name: 'status', type: 'string', required: false, description: 'New status' },
+    ] satisfies ParamDef[],
+  },
   {
     gateway: 'mutate',
     domain: 'pipeline',
@@ -8690,6 +8719,22 @@ export const OPERATIONS: OperationDef[] = [
       },
     ],
   },
+  // ── docs.stats (T13363 — Epic T13340 / Saga T13339) ───────────────────────
+  {
+    gateway: 'query',
+    domain: 'docs',
+    operation: 'stats',
+    description:
+      'docs.stats (query) — per-project CleoDocs adoption metrics (read-only): add:update ' +
+      'ratio from the docs audit log, loose-markdown count with scanned/excluded dirs, ' +
+      'docs_wikilinks edge count, and live decision_adr_links count. Emitted for the ' +
+      'Council pilot baseline comparisons.',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: [],
+    params: [],
+  },
   {
     gateway: 'mutate',
     domain: 'docs',
@@ -8697,8 +8742,10 @@ export const OPERATIONS: OperationDef[] = [
     description:
       'docs.doctor (mutate) — apply the docs doctor repairs: set docVersion from the audit ' +
       'log, backfill topics/related_tasks from content, archive dangling local-file rows, ' +
-      'rebuild docs_wikilinks. The dispatch layer creates a fresh backup (cleo backup add ' +
-      'path) and requires its receipt before any write.',
+      'rebuild docs_wikilinks, and backfill hash-verified legacy bytes into the blob store. ' +
+      'The dispatch layer creates a fresh backup (cleo backup add ' +
+      'path) and requires its receipt before any write. repair:true restricts the run to ' +
+      'the legacy-blob-coverage backfill only (T13653).',
     tier: 1,
     idempotent: false,
     sessionRequired: false,
@@ -8710,6 +8757,14 @@ export const OPERATIONS: OperationDef[] = [
         required: false,
         description: 'Execute repairs (default false — dry-run plan only)',
       },
+      {
+        name: 'repair',
+        type: 'boolean' as const,
+        required: false,
+        description:
+          'Execute ONLY the legacy-blob-coverage backfill: mirror hash-verified legacy ' +
+          'bytes into the blob store so unmigrated docs become readable (T13653)',
+      },
       {
         name: 'olderThanDays',
         type: 'number' as const,
@@ -8718,6 +8773,24 @@ export const OPERATIONS: OperationDef[] = [
       },
     ],
   },
+  // ── docs.migrate (T13360 — Epic T13340 / Saga T13339) ─────────────────────
+  {
+    gateway: 'mutate',
+    domain: 'docs',
+    operation: 'migrate',
+    description:
+      'docs.migrate (mutate) — the T13360 legacy docs migration (spec §5): import legacy ' +
+      'docs + history into the re-keyed conduit store inside the T13448 safety harness ' +
+      '(pre-step VACUUM INTO backup, before/after fingerprints, COMMIT only on full ' +
+      'verification). Imported rows are labeled origin:migrated; dangling-pointer docs are ' +
+      'content-captured or recorded dangling in conduit_doc_migration_ledger. Idempotent — ' +
+      'a re-run is a verified no-op.',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: [],
+    params: [],
+  },
   // ── docs.generate (T798) ─────────────────────────────────────────────────
   {
     gateway: 'query',
@@ -8826,6 +8899,20 @@ export const OPERATIONS: OperationDef[] = [
         required: false,
         description: 'Inline UTF-8 content (mutually exclusive with file)',
       },
+      {
+        name: 'baseVersionUid',
+        type: 'string' as const,
+        required: false,
+        description:
+          'Expected base version uid — the metadata.headVersionUid from the `cleo docs fetch <slug>` envelope the edit was authored against (T13674). ' +
+          'When the stored head has moved past it: append-shaped section edits are three-way merged through the section CRDT (both writers survive); ' +
+          'a non-mergeable section edit is recorded as a named section conflict — nothing is silently dropped. ' +
+          "A base that does not resolve to this doc's version history is refused with E_DOC_BASE_UNKNOWN before any write. " +
+          'Works with --content and with a UTF-8 text --file; a non-text --file with a base is refused with E_DOC_BASE_UNSUPPORTED. ' +
+          'The update result carries the new headVersionUid, so edits can chain without a re-fetch. ' +
+          'Omit only when the edit was not based on an earlier fetch (the current head is then assumed).',
+        cli: { flag: 'base-version-uid' },
+      },
       {
         name: 'message',
         type: 'string' as const,

package/src/done-plan.ts

@@ -66,6 +66,7 @@ export type DonePlanBlockerCode =
   | 'tool-unresolved'
   | 'tool-failed'
   | 'typed-gate-failed'
+  | 'typed-gate-not-run'
   | 'test-run-needed'
   | 'qa-run-needed'
   | 'ac-mapping-needed'

package/src/graph.ts

@@ -769,15 +769,36 @@ export interface GraphPublicationRows {
   generation?: string;
   /** Source provenance and coverage belonging to this generation. */
   assessment?: GraphIndexAssessment;
-  /** Complete replacement node generation. */
-  nodes: NexusNodeInsertRow[];
-  /** Complete replacement relationship generation. */
-  relations: NexusRelationInsertRow[];
+  /**
+   * Complete replacement node generation. May be serialized lazily as the
+   * publisher iterates it (once), so the graph is not held twice (T13656).
+   */
+  nodes: Iterable<NexusNodeInsertRow>;
+  /** Complete replacement relationship generation; may be lazy like `nodes`. */
+  relations: Iterable<NexusRelationInsertRow>;
   /**
    * Per-file extraction memo changes committed in the same transaction as the rows.
    * Absent when the producer does not maintain a parse cache.
    */
   parseCache?: GraphParseCacheUpdate;
+  /**
+   * The generation's retained references, already in their stored encoding
+   * (T13656). When present, `assessment.references` is absent and
+   * `assessment.referenceCount` equals `references.count`.
+   */
+  references?: GraphStoredReferences;
+}
+
+/**
+ * A reference list in its stored encoding: the JSON array, one reference per
+ * line, as concatenated gzip members (T13326). Producers stream references into
+ * it as they are reported, so the list is never held as objects (T13656).
+ */
+export interface GraphStoredReferences {
+  /** Number of references encoded. */
+  count: number;
+  /** The compressed list, stored verbatim. */
+  payload: Uint8Array;
 }
 
 /**

package/src/index.ts

@@ -774,6 +774,7 @@ export type {
   GraphPublicationRows,
   GraphRelation,
   GraphRelationType,
+  GraphStoredReferences,
   ImpactResult,
   InferredProvenance,
   KnowledgeGraph,
@@ -896,6 +897,8 @@ export {
   isLafsError,
   isLafsSuccess,
 } from './lafs.js';
+// === ct-lean levels (T13663 / Epic T13418) ===
+export type { LeanConfig, LeanLevel, LeanLevelSource } from './lean.js';
 // === Lease-IPC v1.1 (PARALLEL DbWriterLease contract — T11627 · SG-RUNTIME-UNIFICATION) ===
 export type {
   ChildKilledUnresponsiveResponse,
@@ -1357,6 +1360,8 @@ export type {
 export {
   DOCS_LIFECYCLE_STATUSES,
   type DocsLifecycleStatus,
+  type DocsSectionConflict,
+  type DocsSectionLeaseNotice,
   type DocsUpdateParams,
 } from './operations/docs.js';
 // === Ensures-schema Zod registry (T11762 ST-1 / T11900 — cantbook ensures.schema SSoT) ===
@@ -2028,11 +2033,13 @@ export type {
   PruneOrphanedWorktreesResult,
   PruneWorktreesOptions,
   PruneWorktreesResult,
+  WorktreeDisposalBlockers,
   WorktreeHook,
   WorktreeHookResult,
   WorktreeIncludePattern,
   WorktreeInfo,
   WorktreeInstallOutcome,
+  WorktreeKeepMarker,
   WorktreeLifecycleAction,
   WorktreeLifecycleAuditEntry,
   WorktreeListEntry,

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

@@ -462,21 +462,25 @@ export const SYNC_WRITE_INVARIANTS: readonly SyncWriteInvariant[] = Object.freez
       ['tasks_audit_log', 'audit_log'],
     ),
   ),
-  rule(
-    'sticky.status.one-way',
-    'T12942',
-    'brain_sticky_notes',
-    ['status', 'converted_to_json'],
-    ['SK2', 'SK3', 'B24'],
-    'active→{converted, archived} is one-way; converted_to_json is write-once',
+  implemented(
+    rule(
+      'sticky.status.one-way',
+      'T12942',
+      'brain_sticky_notes',
+      ['status', 'converted_to_json'],
+      ['SK2', 'SK3', 'B24'],
+      'active→{converted, archived} is one-way; converted_to_json is write-once',
+    ),
   ),
-  rule(
-    'release.status.absorbing',
-    'T12943',
-    'tasks_releases',
-    ['status'],
-    ['REL-2', 'REL-3', 'REL-4', 'REL-5', 'REL-6', 'REL-7', 'REL-8'],
-    'shipped release statuses are absorbing',
+  implemented(
+    rule(
+      'release.status.absorbing',
+      'T12943',
+      'tasks_releases',
+      ['status'],
+      ['REL-2', 'REL-3', 'REL-4', 'REL-5', 'REL-6', 'REL-7', 'REL-8'],
+      'shipped release statuses are absorbing',
+    ),
   ),
   implemented(
     rule(
@@ -489,13 +493,15 @@ export const SYNC_WRITE_INVARIANTS: readonly SyncWriteInvariant[] = Object.freez
       ['tasks_playbook_approvals', 'playbook_approvals'],
     ),
   ),
-  rule(
-    'docs.lifecycle.transitions',
-    'T12945',
-    'docs_attachments',
-    ['lifecycle_status'],
-    ['D04', 'D05', 'D31', 'D32', 'D39', 'D50'],
-    'superseded is sticky; lifecycle transitions follow a matrix',
+  implemented(
+    rule(
+      'docs.lifecycle.transitions',
+      'T12945',
+      'docs_attachments',
+      ['lifecycle_status'],
+      ['D04', 'D05', 'D31', 'D32', 'D39', 'D50'],
+      'superseded is sticky; lifecycle transitions follow a matrix',
+    ),
   ),
   // T13354 (D11165) — CleoDocs re-keyed history family; the typed merge rules
   // land with the write path (T13355).
@@ -523,14 +529,35 @@ export const SYNC_WRITE_INVARIANTS: readonly SyncWriteInvariant[] = Object.freez
     [],
     'alias rows carry natural identity over (slug, doc_uid); identical aliases merge to one row',
   ),
-  rule(
-    'docs.head.max-hlc',
-    'T13355',
-    'conduit_doc_heads',
-    ['*'],
-    [],
-    'the projection keeps the max-HLC head; a losing concurrent head is recorded (conflict_count/last_conflict_json), never silently shadowed',
-  ),
+  // T13355 (D11165): the write-path behavior is implemented at the writer
+  // chokepoint (`upsertConduitDocHead`, now reachable from the docs update
+  // write path); cross-device convergence rides the Stage C journal merge
+  // engine (T12344) and needs no second rule.
+  {
+    id: 'docs.head.max-hlc',
+    class: 'monotonic-merge-rule',
+    tables: ['conduit_doc_heads'],
+    sites: [],
+    mergeRule: { table: 'conduit_doc_heads', columns: ['*'] },
+    inventory: [],
+    runtimeGate: {
+      module: 'packages/core/src/store/conduit-doc-history.ts',
+      functionName: 'upsertConduitDocHead',
+    },
+    reason:
+      'the projection keeps the max-HLC head; a losing concurrent head is recorded (conflict_count/last_conflict_json), never silently shadowed',
+  },
+  // T13355 — the docs write path adopts a legacy doc into the conduit family
+  // once (identity shell keyed by the immutable uid); the read-back guard is
+  // a local write-confirmation, not a merge rule.
+  {
+    id: 'docs.doc.adopt-once',
+    class: 'not-sync-relevant',
+    tables: ['conduit_attachments'],
+    sites: [],
+    reason:
+      'adopting a legacy doc inserts one immutable-uid identity shell; losing the write is refused loudly at the writer, not merged',
+  },
   // 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

package/src/lean.ts

@@ -0,0 +1,36 @@
+/**
+ * ct-lean levels — shared types (T13663).
+ *
+ * The lean-change rules (the `ct-lean` skill, adapted from Ponytail 5.1.0,
+ * DietrichGebert, MIT) run at one of four levels. The level resolves from the
+ * `CLEO_LEAN_LEVEL` environment variable, then the session-scoped level set by
+ * `cleo lean level <l> --session`, then the `lean.level` config key (project
+ * over global), then `full`.
+ *
+ * @task T13663
+ * @epic T13418
+ */
+
+/**
+ * How strictly the lean-change rules apply.
+ *
+ * - `off` — no lean rules are emitted.
+ * - `lite` — build what was asked; name the smaller option in one line.
+ * - `full` — DEFAULT. The smallest complete change (the full ct-lean rules).
+ * - `ultra` — `full`, and also question the request before building.
+ */
+export type LeanLevel = 'off' | 'lite' | 'full' | 'ultra';
+
+/** Where a resolved lean level came from. */
+export type LeanLevelSource = 'env' | 'session' | 'config' | 'default';
+
+/** The `lean` section of `.cleo/config.json`. */
+export interface LeanConfig {
+  /**
+   * Default lean level for this project (or, in the global config, every
+   * project). `CLEO_LEAN_LEVEL` and a session-scoped level override it.
+   *
+   * @defaultValue 'full'
+   */
+  level?: LeanLevel;
+}