@cleocode/core 2026.6.6 → 2026.6.8

package/dist/store/repair-malformed-dbs.js

@@ -0,0 +1,188 @@
+/**
+ * `cleo doctor repair` orchestrator — detect malformed CLEO databases and
+ * restore each from its freshest validated snapshot (T11829 · DHQ-060).
+ *
+ * ## Why this exists
+ *
+ * The corruption-resilience pipeline ALREADY existed before T11829:
+ *
+ *  - {@link recoverMalformedDb} (quarantine → snapshot-restore → `quick_check`),
+ *  - `autoRecoverFromBackup` (catches `"database disk image is malformed"` at
+ *    open and restores the freshest VACUUM snapshot), and
+ *  - the operator verb `cleo backup recover <role>` ({@link runBackupRecover}).
+ *
+ * The ONLY gap vs the DHQ-060 ask was a discoverable `cleo doctor` entry point
+ * that DETECTS corruption across the fleet and repairs only what is broken. This
+ * module is that orchestrator — it adds NO new recovery logic. It probes each
+ * role's live DB with `PRAGMA quick_check` (the same probe the pipeline runs on
+ * snapshot candidates, via {@link probeSnapshot}) and delegates every actual
+ * repair to {@link runBackupRecover} → {@link recoverMalformedDb}.
+ *
+ * ## WAL-specific corruption is covered
+ *
+ * A torn WAL frame surfaces as `"database disk image is malformed"` and makes
+ * `PRAGMA quick_check` return a non-`ok` result — so {@link probeSnapshot}
+ * detects it. The quarantine step ({@link quarantineCorruptDb}) already moves the
+ * `-wal`/`-shm` sidecars alongside the main file, so the WAL case is fully
+ * handled by the existing pipeline; this orchestrator does not need to special-case it.
+ *
+ * @module
+ * @task T11829 (DHQ-060 — `cleo doctor repair` entry point over the recovery pipeline)
+ * @epic T11833
+ * @saga T11242 (SG-DB-SUBSTRATE-V2)
+ * @see packages/core/src/store/recover-malformed-db.ts — the recovery pipeline
+ * @see packages/core/src/store/backup-recover.ts — `cleo backup recover <role>` wrapper
+ */
+import { existsSync } from 'node:fs';
+import { DB_INVENTORY } from '@cleocode/contracts';
+import { BackupRecoverError, runBackupRecover } from './backup-recover.js';
+import { probeSnapshot, resolveRoleDbPath } from './recover-malformed-db.js';
+/**
+ * Probe a single role's live DB and, when malformed, repair it from snapshot.
+ *
+ * Pure delegation: detection via {@link probeSnapshot} (`PRAGMA quick_check`),
+ * repair via {@link runBackupRecover}. Never throws — a recovery failure is
+ * captured in the returned record's `action: 'failed'`.
+ *
+ * @internal
+ */
+function repairOneRole(role, opts) {
+    const dbPath = resolveRoleDbPath(role, { projectRoot: opts.projectRoot });
+    const present = existsSync(dbPath);
+    if (!present) {
+        return {
+            role,
+            dbPath,
+            present: false,
+            healthy: true,
+            action: 'skipped',
+            restoredFrom: null,
+            quarantinedTo: null,
+            dataLossWindowHours: null,
+            detail: 'live DB file not present on disk (nothing to repair)',
+        };
+    }
+    // DETECT — the same `PRAGMA quick_check` the pipeline runs on snapshots. A
+    // torn WAL frame ("database disk image is malformed") fails this probe.
+    const probe = probeSnapshot(dbPath);
+    if (probe.ok) {
+        return {
+            role,
+            dbPath,
+            present: true,
+            healthy: true,
+            action: 'skipped',
+            restoredFrom: null,
+            quarantinedTo: null,
+            dataLossWindowHours: null,
+            detail: 'PRAGMA quick_check passed — DB is healthy',
+        };
+    }
+    // MALFORMED — plan or repair.
+    if (opts.dryRun === true) {
+        try {
+            // Dry-run delegates to the SAME pipeline (no mutation) for an honest plan.
+            const plan = runBackupRecover({
+                role,
+                projectRoot: opts.projectRoot,
+                logger: opts.logger,
+                dryRun: true,
+            });
+            return {
+                role,
+                dbPath,
+                present: true,
+                healthy: false,
+                action: 'would-repair',
+                restoredFrom: plan.restoredFrom || null,
+                quarantinedTo: null,
+                dataLossWindowHours: plan.dataLossWindowHours,
+                detail: `malformed — would restore from ${plan.restoredFrom} (re-run without --dry-run to repair)`,
+            };
+        }
+        catch (err) {
+            return {
+                role,
+                dbPath,
+                present: true,
+                healthy: false,
+                action: 'failed',
+                restoredFrom: null,
+                quarantinedTo: null,
+                dataLossWindowHours: null,
+                detail: `malformed but NO valid snapshot to restore from: ${err instanceof BackupRecoverError ? err.message : String(err)}`,
+            };
+        }
+    }
+    // EXECUTE — quarantine + restore + verify via the existing pipeline.
+    try {
+        const result = runBackupRecover({
+            role,
+            projectRoot: opts.projectRoot,
+            logger: opts.logger,
+            dryRun: false,
+        });
+        return {
+            role,
+            dbPath,
+            present: true,
+            healthy: false,
+            action: 'repaired',
+            restoredFrom: result.restoredFrom || null,
+            quarantinedTo: result.quarantinedTo || null,
+            dataLossWindowHours: result.dataLossWindowHours,
+            detail: `repaired — restored from ${result.restoredFrom}; corrupt DB quarantined at ${result.quarantinedTo}`,
+        };
+    }
+    catch (err) {
+        return {
+            role,
+            dbPath,
+            present: true,
+            healthy: false,
+            action: 'failed',
+            restoredFrom: null,
+            quarantinedTo: null,
+            dataLossWindowHours: null,
+            detail: `malformed — recovery FAILED: ${err instanceof BackupRecoverError ? err.message : String(err)}`,
+        };
+    }
+}
+/**
+ * Detect and repair malformed CLEO databases across the fleet (T11829 · DHQ-060).
+ *
+ * For each requested role (or every present role in {@link DB_INVENTORY} when none
+ * are specified) this probes the live DB with `PRAGMA quick_check` and, when
+ * corruption is found, restores the freshest validated snapshot via the existing
+ * {@link runBackupRecover} pipeline. No new recovery logic is introduced — this is
+ * the discoverable `cleo doctor repair` entry point requested by DHQ-060.
+ *
+ * @param opts - Repair inputs (project root, optional role filter, dry-run, logger).
+ * @returns A {@link DoctorRepairResult} aggregate with per-role outcomes.
+ *
+ * @example
+ * ```ts
+ * const report = repairMalformedDbs({ projectRoot: '/repo', logger });
+ * if (report.failedCount > 0) process.exitCode = 1;
+ * ```
+ *
+ * @task T11829
+ * @epic T11833
+ * @saga T11242
+ * @public
+ */
+export function repairMalformedDbs(opts) {
+    const explicit = opts.roles !== undefined && opts.roles.length > 0;
+    const candidateRoles = explicit
+        ? opts.roles
+        : DB_INVENTORY.map((e) => e.role).filter((role) => existsSync(resolveRoleDbPath(role, { projectRoot: opts.projectRoot })));
+    const roles = candidateRoles.map((role) => repairOneRole(role, opts));
+    return {
+        dryRun: opts.dryRun === true,
+        roles,
+        malformedCount: roles.filter((r) => !r.healthy).length,
+        repairedCount: roles.filter((r) => r.action === 'repaired').length,
+        failedCount: roles.filter((r) => r.action === 'failed').length,
+    };
+}
+//# sourceMappingURL=repair-malformed-dbs.js.map

package/dist/store/repair-malformed-dbs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repair-malformed-dbs.js","sourceRoot":"","sources":["../../src/store/repair-malformed-dbs.ts"],"names":[],"mappings":"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"}

package/dist/store/schema/attachments.d.ts

@@ -391,8 +391,141 @@ export declare const attachmentRefs: import("drizzle-orm/sqlite-core").SQLiteTab
     };
     dialect: "sqlite";
 }>;
+/**
+ * Allowed relations for a `docs_wikilinks` edge.
+ *
+ * A wikilink is a DERIVED, slug-addressed edge between two docs (or a doc and a
+ * task) reconstructed from the authoritative provenance columns on
+ * `attachments` — there is no hand-authored edge here. The relation enumerates
+ * which source column produced the edge:
+ *
+ *   - `supersedes`     — `attachments.supersedes` (newer → older)
+ *   - `superseded-by`  — `attachments.superseded_by` (older → newer)
+ *   - `related-task`   — `attachments.related_tasks` JSON membership (doc → T####)
+ *   - `topic`          — `attachments.topics` JSON co-membership (doc ↔ doc sharing a topic)
+ *
+ * Kept slug-primary so the edge table is Obsidian-grade (vault links are
+ * slug-addressed) and survives attachment-id churn across versions.
+ *
+ * @task T11826 (Epic T11781 / Saga T11778)
+ */
+export declare const DOCS_WIKILINK_RELATIONS: readonly ["supersedes", "superseded-by", "related-task", "topic"];
+/** Discriminated union of `docs_wikilinks.relation` values. */
+export type DocsWikilinkRelation = (typeof DOCS_WIKILINK_RELATIONS)[number];
+/**
+ * `docs_wikilinks` — DERIVED, slug-addressed edge table for the docs graph.
+ *
+ * Per the ratified Docs-SSoT model (saga T11778): `cleo.db` is the SOLE doc
+ * authority, and `docs_wikilinks` is a *minimal edge table derived from*
+ * `supersedes` + `relatedTasks` + `topics` on `attachments`. It is NOT an
+ * authoritative input surface — it is rebuilt idempotently from the provenance
+ * columns by {@link import('../../docs/wikilinks.js').rebuildDocsWikilinks}.
+ *
+ * The table makes the bidirectional backlink graph queryable in O(edges)
+ * without recomputing the BFS, which is what the Obsidian plugin (T11827)
+ * renders. `cleo docs graph` (T10164) continues to compute the provenance BFS
+ * but hydrates persisted backlinks from this table when present.
+ *
+ * Edges are slug-primary; `to_slug` carries a doc slug for `topic` /
+ * `supersedes` / `superseded-by` edges and a `T####` task id for `related-task`
+ * edges (`to_is_task = 1`). No markdown body `[[link]]` parsing is performed
+ * (AC4) — the edges derive purely from structured provenance columns.
+ *
+ * @task T11826 (Epic T11781 / Saga T11778)
+ */
+export declare const docsWikilinks: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "docs_wikilinks";
+    schema: undefined;
+    columns: {
+        fromSlug: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "docs_wikilinks";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        toSlug: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "docs_wikilinks";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        relation: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "docs_wikilinks";
+            dataType: "string enum";
+            data: "topic" | "supersedes" | "superseded-by" | "related-task";
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["supersedes", "superseded-by", "related-task", "topic"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        toIsTask: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "docs_wikilinks";
+            dataType: "boolean";
+            data: boolean;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        derivedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "docs_wikilinks";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+    };
+    dialect: "sqlite";
+}>;
 export type AttachmentRow = typeof attachments.$inferSelect;
 export type NewAttachmentRow = typeof attachments.$inferInsert;
 export type AttachmentRefRow = typeof attachmentRefs.$inferSelect;
 export type NewAttachmentRefRow = typeof attachmentRefs.$inferInsert;
+/** Row type for `docs_wikilinks` SELECT queries. */
+export type DocsWikilinkRow = typeof docsWikilinks.$inferSelect;
+/** Row type for `docs_wikilinks` INSERT operations. */
+export type NewDocsWikilinkRow = typeof docsWikilinks.$inferInsert;
 //# sourceMappingURL=attachments.d.ts.map

package/dist/store/schema/attachments.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attachments.d.ts","sourceRoot":"","sources":["../../../src/store/schema/attachments.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,gFAOzB,CAAC;AAEX;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,6BAA6B,oFAOhC,CAAC;AAEX,0DAA0D;AAC1D,MAAM,MAAM,yBAAyB,GAAG,CAAC,OAAO,6BAA6B,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvF;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+HvB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqB1B,CAAC;AAIF,MAAM,MAAM,aAAa,GAAG,OAAO,WAAW,CAAC,YAAY,CAAC;AAC5D,MAAM,MAAM,gBAAgB,GAAG,OAAO,WAAW,CAAC,YAAY,CAAC;AAC/D,MAAM,MAAM,gBAAgB,GAAG,OAAO,cAAc,CAAC,YAAY,CAAC;AAClE,MAAM,MAAM,mBAAmB,GAAG,OAAO,cAAc,CAAC,YAAY,CAAC"}
+{"version":3,"file":"attachments.d.ts","sourceRoot":"","sources":["../../../src/store/schema/attachments.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,gFAOzB,CAAC;AAEX;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,6BAA6B,oFAOhC,CAAC;AAEX,0DAA0D;AAC1D,MAAM,MAAM,yBAAyB,GAAG,CAAC,OAAO,6BAA6B,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvF;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+HvB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqB1B,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,uBAAuB,mEAK1B,CAAC;AAEX,+DAA+D;AAC/D,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoBzB,CAAC;AAIF,MAAM,MAAM,aAAa,GAAG,OAAO,WAAW,CAAC,YAAY,CAAC;AAC5D,MAAM,MAAM,gBAAgB,GAAG,OAAO,WAAW,CAAC,YAAY,CAAC;AAC/D,MAAM,MAAM,gBAAgB,GAAG,OAAO,cAAc,CAAC,YAAY,CAAC;AAClE,MAAM,MAAM,mBAAmB,GAAG,OAAO,cAAc,CAAC,YAAY,CAAC;AACrE,oDAAoD;AACpD,MAAM,MAAM,eAAe,GAAG,OAAO,aAAa,CAAC,YAAY,CAAC;AAChE,uDAAuD;AACvD,MAAM,MAAM,kBAAkB,GAAG,OAAO,aAAa,CAAC,YAAY,CAAC"}

package/dist/store/schema/attachments.js

@@ -4,6 +4,7 @@
  * @epic T760
  * @task T796
  */
+import { sql } from 'drizzle-orm';
 import { index, integer, primaryKey, sqliteTable, text, } from 'drizzle-orm/sqlite-core';
 /**
  * Allowed owner-entity types for `attachment_refs.owner_type`.
@@ -196,4 +197,66 @@ export const attachmentRefs = sqliteTable('attachment_refs', {
     index('idx_attachment_refs_attachment_id').on(table.attachmentId),
     index('idx_attachment_refs_owner').on(table.ownerType, table.ownerId),
 ]);
+/**
+ * Allowed relations for a `docs_wikilinks` edge.
+ *
+ * A wikilink is a DERIVED, slug-addressed edge between two docs (or a doc and a
+ * task) reconstructed from the authoritative provenance columns on
+ * `attachments` — there is no hand-authored edge here. The relation enumerates
+ * which source column produced the edge:
+ *
+ *   - `supersedes`     — `attachments.supersedes` (newer → older)
+ *   - `superseded-by`  — `attachments.superseded_by` (older → newer)
+ *   - `related-task`   — `attachments.related_tasks` JSON membership (doc → T####)
+ *   - `topic`          — `attachments.topics` JSON co-membership (doc ↔ doc sharing a topic)
+ *
+ * Kept slug-primary so the edge table is Obsidian-grade (vault links are
+ * slug-addressed) and survives attachment-id churn across versions.
+ *
+ * @task T11826 (Epic T11781 / Saga T11778)
+ */
+export const DOCS_WIKILINK_RELATIONS = [
+    'supersedes',
+    'superseded-by',
+    'related-task',
+    'topic',
+];
+/**
+ * `docs_wikilinks` — DERIVED, slug-addressed edge table for the docs graph.
+ *
+ * Per the ratified Docs-SSoT model (saga T11778): `cleo.db` is the SOLE doc
+ * authority, and `docs_wikilinks` is a *minimal edge table derived from*
+ * `supersedes` + `relatedTasks` + `topics` on `attachments`. It is NOT an
+ * authoritative input surface — it is rebuilt idempotently from the provenance
+ * columns by {@link import('../../docs/wikilinks.js').rebuildDocsWikilinks}.
+ *
+ * The table makes the bidirectional backlink graph queryable in O(edges)
+ * without recomputing the BFS, which is what the Obsidian plugin (T11827)
+ * renders. `cleo docs graph` (T10164) continues to compute the provenance BFS
+ * but hydrates persisted backlinks from this table when present.
+ *
+ * Edges are slug-primary; `to_slug` carries a doc slug for `topic` /
+ * `supersedes` / `superseded-by` edges and a `T####` task id for `related-task`
+ * edges (`to_is_task = 1`). No markdown body `[[link]]` parsing is performed
+ * (AC4) — the edges derive purely from structured provenance columns.
+ *
+ * @task T11826 (Epic T11781 / Saga T11778)
+ */
+export const docsWikilinks = sqliteTable('docs_wikilinks', {
+    /** Source doc slug (→ `attachments.slug`). Always a doc. */
+    fromSlug: text('from_slug').notNull(),
+    /** Target slug — a doc slug, or a `T####` task id when `toIsTask = 1`. */
+    toSlug: text('to_slug').notNull(),
+    /** Which provenance column produced this edge — dispatch-validated, no SQL CHECK. */
+    relation: text('relation', { enum: DOCS_WIKILINK_RELATIONS }).notNull(),
+    /** 1 when `to_slug` is a task id (`related-task` edges); 0 for doc→doc edges. */
+    toIsTask: integer('to_is_task', { mode: 'boolean' }).notNull().default(false),
+    /** ISO-8601 UTC instant this edge was last (re)derived. */
+    derivedAt: text('derived_at').notNull().default(sql `(datetime('now'))`),
+}, (table) => [
+    primaryKey({ columns: [table.fromSlug, table.toSlug, table.relation] }),
+    index('idx_docs_wikilinks_from').on(table.fromSlug),
+    index('idx_docs_wikilinks_to').on(table.toSlug),
+    index('idx_docs_wikilinks_relation').on(table.relation),
+]);
 //# sourceMappingURL=attachments.js.map

package/dist/store/schema/attachments.js.map

@@ -1 +1 @@
-{"version":3,"file":"attachments.js","sourceRoot":"","sources":["../../../src/store/schema/attachments.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"attachments.js","sourceRoot":"","sources":["../../../src/store/schema/attachments.ts"],"names":[],"mappings":"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"}

package/dist/tasks/add.d.ts

@@ -60,6 +60,19 @@ export interface AddTaskOptions {
      * @task T1633
      */
     forceDuplicate?: boolean;
+    /**
+     * Bypass the T11811 write-time containment invariant (orphan / terminal-parent
+     * / wrong-tier rejection).
+     *
+     * MUST be set ONLY by historical data-movement paths — exodus migration,
+     * `cleo import`, restore/JSON-merge replay — which legitimately re-insert
+     * rows that predate the strict-spine rule (the fleet still carries legacy
+     * orphans). Agent-facing `cleo add` / `add-batch` MUST NOT set this; the
+     * invariant is the whole point of the guard for net-new work.
+     *
+     * @task T11811
+     */
+    skipContainmentInvariant?: boolean;
 }
 /** Result of adding a task. */
 export interface AddTaskResult {

package/dist/tasks/add.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../../src/tasks/add.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAEV,IAAI,EACJ,QAAQ,EACR,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,gBAAgB,EACjB,MAAM,qBAAqB,CAAC;AAS7B,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,2BAA2B,CAAC;AAoBnF;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,uFAAuF;IACvF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB;;;;OAIG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,+BAA+B;AAC/B,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,IAAI,CAAC;IACX,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,iFAAiF;IACjF,UAAU,CAAC,EAAE;QACX,KAAK,EAAE,MAAM,EAAE,CAAC;QAChB,kBAAkB,EAAE,MAAM,EAAE,CAAC;KAC9B,CAAC;IACF,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC9B;AAED,sFAAsF;AACtF,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GACxC,MAAM,EAAE,GAAG,SAAS,CAItB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,wBAAwB,CAAC,aAAa,EAAE,MAAM,GAAG,gBAAgB,CAchF;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAajD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,UAAU,CAW3E;AAmBD,oCAAoC;AACpC,eAAO,MAAM,gBAAgB,EAAE,SAAS,YAAY,EAK1C,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,YAAY,CAqCzE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,IAAI,YAAY,CAEnF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,IAAI,QAAQ,CAYvE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,IAAI,QAAQ,CAYnE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAoBrD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAWvD;AA6DD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI,CAqBtE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,IAAI,EAAE,EACb,QAAQ,GAAE,MAAU,EACpB,WAAW,GAAE,MAAU,GACtB,IAAI,CA0CN;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,CAclE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,QAAQ,CAM1F;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,CAW1F;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,QAAQ,CAAC,EAAE,OAAO,2BAA2B,EAAE,YAAY,GAC1D,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,KAAK,EAAE,IAAI,EAAE,EACb,aAAa,GAAE,MAAW,GACzB,IAAI,GAAG,IAAI,CAeb;AAED;;;GAGG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,cAAc,EACvB,GAAG,CAAC,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,YAAY,GACtB,OAAO,CAAC,aAAa,CAAC,CA8yBxB"}
+{"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../../src/tasks/add.ts"],"names":[],"mappings":"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"}

package/dist/tasks/add.js

@@ -6,7 +6,7 @@
  */
 import { randomBytes } from 'node:crypto';
 // setMetaValue now called via tx.setMetaValue inside transaction (T023)
-import { ExitCode, isAllowedWorkGraphParentType, TASK_STATUSES } from '@cleocode/contracts';
+import { ExitCode, isAllowedWorkGraphParentType, TASK_STATUSES, TERMINAL_TASK_STATUSES, } from '@cleocode/contracts';
 import { loadConfig } from '../config.js';
 import { CleoError } from '../errors.js';
 import { resolveOrCwd } from '../paths.js';
@@ -15,7 +15,7 @@ import { requireActiveSession } from '../sessions/session-enforcement.js';
 import { trackBackgroundOp } from '../store/background-ops.js';
 import { acItemToText, applyAcPlan, buildAcRowId, buildChildProjectionAcText, buildFreshAcRows, childProjectionFreshnessFingerprint, childProjectionSourceKey, } from './ac-table.js';
 import { createAcceptanceEnforcement } from './enforcement.js';
-import { findEpicAncestor, getLifecycleMode, validateChildStageCeiling, validateEpicCreation, } from './epic-enforcement.js';
+import { findEpicAncestor, validateChildStageCeiling, validateEpicCreation, } from './epic-enforcement.js';
 import { resolveHierarchyPolicy } from './hierarchy-policy.js';
 import { resolveDefaultPipelineStage, validatePipelineStage } from './pipeline-stage.js';
 /** Normalize AC arrays once so legacy JSON, AC rows, and projections stay aligned. */
@@ -524,23 +524,34 @@ export async function addTask(options, cwd, accessor) {
             fix: 'Provide --desc with a description different from the title',
         });
     }
-    // Orphan prevention (T101): non-epic tasks must have a parent in strict mode.
-    // Epics are root containers and are exempt. Only enforced in strict lifecycle mode.
-    // Skip for dry-run — no data is written.
+    // Orphan prevention (T101 → hardened by T11811 AC1).
+    //
+    // Write-time containment invariant — the strict-spine rule (owner decision 1):
+    // EVERY net-new node must attach to a parent unless it is a `saga`. Only sagas
+    // may be roots. A `task` / `subtask` / `epic` with a null/absent parent is a
+    // NET-NEW ORPHAN and is HARD-REJECTED regardless of lifecycle mode — the prior
+    // strict-mode-only gate let advisory-mode installs silently manufacture the
+    // exact orphan the doctor/CI gate then flags.
+    //
+    // Escape hatch: historical data-movement paths (exodus, import, restore replay)
+    // set `skipContainmentInvariant` so legacy rows that predate the rule are not
+    // self-blocked. Dry-run is exempt (no data is written).
+    //
+    // The effective type mirrors the later inference: an unset type with no parent
+    // resolves to `task`, so a bare `cleo add "X"` (no parent, no type) is rejected.
     const parentId = options.parentId ?? null;
-    if (!options.dryRun && !parentId && options.type !== 'epic') {
-        const lifecycleMode = await getLifecycleMode(cwd);
-        if (lifecycleMode === 'strict') {
-            issues.push({
-                field: 'parentId',
-                message: 'Tasks must have a parent (epic or task) in strict mode. Use --parent <epicId>, --type epic for a root-level epic, or set lifecycle.mode to "advisory".',
-                fix: 'cleo add "Task title" --parent T### --acceptance "AC1|AC2|AC3"',
-            });
-        }
-        else {
-            // Advisory mode: warn about parentless task creation (T089)
-            warnings.push('Task created without a parent. Use --parent <epicId> to assign to an epic hierarchy.');
-        }
+    const effectiveRootType = options.type ?? 'task';
+    if (!options.dryRun &&
+        !options.skipContainmentInvariant &&
+        !parentId &&
+        effectiveRootType !== 'saga') {
+        issues.push({
+            field: 'parentId',
+            message: `A ${effectiveRootType} must attach to a parent — only a saga may be a root ` +
+                `(strict-spine containment, T11811). Use --parent <id> to file it under the ` +
+                `correct container (saga→epic, epic→task, task→subtask).`,
+            fix: 'cleo add "Task title" --parent T### --acceptance "AC1|AC2|AC3"',
+        });
     }
     // Always use accessor (SQLite canonical storage per ADR-006)
     const dataAccessor = accessor ?? (await (await import('../store/data-accessor.js')).getTaskAccessor(cwd));
@@ -686,6 +697,27 @@ export async function addTask(options, cwd, accessor) {
                 details: { field: 'parentId', actual: parentId },
             });
         }
+        // T11811 AC1 — reject filing NET-NEW work under an IRREVERSIBLY-TERMINAL
+        // parent (`cancelled` / `archived`). A child added under such a parent is
+        // born stranded — the parent can never be auto-reopened to satisfy it.
+        //
+        // `done` is deliberately EXCLUDED: PM-Core V2 design-point 5 (saga T10538)
+        // reopens a `done` parent (and done ancestors) when a child is filed under
+        // it, so the child is NOT stranded — see the reopen logic below. Mirrors the
+        // `s !== 'done'` carve-out already in satisfies-validator.ts. Skip entirely
+        // for the historical-replay escape hatch (legacy rows reference terminals).
+        const parentIsIrreversiblyTerminal = TERMINAL_TASK_STATUSES.has(parentTask.status) && parentTask.status !== 'done';
+        if (!options.skipContainmentInvariant && parentIsIrreversiblyTerminal) {
+            throw new CleoError(ExitCode.VALIDATION_ERROR, `Cannot file new work under ${parentId}: its status is '${parentTask.status}' (terminal). ` +
+                `A child under a terminal parent is born stranded.`, {
+                fix: `Pick a non-terminal parent (cleo find), or reopen ${parentId} first (cleo restore task ${parentId}).`,
+                details: {
+                    field: 'parentId',
+                    expected: 'non-terminal parent (pending|active|blocked|done)',
+                    actual: parentTask.status,
+                },
+            });
+        }
         parentTaskForProjection = parentTask;
         // Read hierarchy limits from config via policy module
         const config = await loadConfig(cwd);