@cleocode/core 2026.9.8 → 2026.9.9

package/dist/tasks/add.js

@@ -13,17 +13,62 @@ import { resolveOrCwd } from '../paths.js';
 import { allocateNextTaskId } from '../sequence/index.js';
 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 { applyAcPlan, buildAcRowId, buildChildProjectionAcText, buildFreshAcRows, childProjectionFreshnessFingerprint, childProjectionSourceKey, } from './ac-table.js';
+import { normalizeAcceptance } from './acceptance-input.js';
 import { createAcceptanceEnforcement } from './enforcement.js';
 import { findEpicAncestor, validateChildStageCeiling, validateEpicCreation, } from './epic-enforcement.js';
-import { resolveHierarchyPolicy } from './hierarchy-policy.js';
+import { childTypeForParentType } from './hierarchy.js';
+import { exceedsMaxDepth, 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. */
-export function normalizeAcceptance(acceptance) {
-    if (!acceptance)
-        return undefined;
-    const normalized = acceptance.map((item) => item.trim()).filter((item) => item.length > 0);
-    return normalized.length > 0 ? normalized : undefined;
+import { prepareSignedSeverityAttestation } from './severity-attestation.js';
+export { normalizeAcceptance } from './acceptance-input.js';
+/**
+ * Translate canonical creation input into core options without dropping fields.
+ * @param params - Canonical task creation input.
+ * @returns Core options with the parent alias and enum boundaries resolved.
+ * @remarks Entry points share this boundary; CLI parsing does not establish authorization.
+ * @example
+ * ```ts
+ * toTaskAddOptions({ title: 'Fix persistence', description: 'Verify durable task writes' });
+ * ```
+ */
+export function toTaskAddOptions(params) {
+    const { parent, ...fields } = params;
+    return {
+        ...fields,
+        parentId: parent,
+        priority: params.priority,
+        size: params.size,
+        kind: params.kind,
+        scope: params.scope,
+        severity: params.severity,
+    };
+}
+/**
+ * Enforce the established explicit-critical dependency policy before mutation.
+ * @param priority - Explicit requested priority; waivers require critical.
+ * @param justification - Original reason, retained verbatim in transaction audit details.
+ * @param dependencies - Effective dependencies after applying the requested changes.
+ * @throws CleoError for invalid waivers or critical mutations without dependencies.
+ * @remarks Entry points share this boundary; CLI parsing does not establish authorization.
+ * @example
+ * ```ts
+ * validateDependencyWaiver('critical', 'Independent restoration', []);
+ * ```
+ */
+export function validateDependencyWaiver(priority, justification, dependencies) {
+    if (justification !== undefined &&
+        (typeof justification !== 'string' ||
+            justification.trim().length === 0 ||
+            priority !== 'critical')) {
+        throw new CleoError(ExitCode.VALIDATION_ERROR, 'Dependency waiver requires a non-empty justification and an explicit critical-priority mutation', {
+            details: { field: 'dependsWaiver' },
+            fix: 'Supply a non-empty --depends-waiver with --priority critical, or omit the waiver',
+        });
+    }
+    if (priority === 'critical' && dependencies.length === 0 && justification === undefined) {
+        throw new CleoError(ExitCode.VALIDATION_ERROR, 'Critical tasks must declare at least one dependency or supply a dependency waiver', { details: { field: 'depends' }, fix: 'Supply --depends or a non-empty --depends-waiver' });
+    }
 }
 /**
  * Build the default verification metadata applied to every new task.
@@ -322,12 +367,14 @@ export function validateParent(parentId, tasks, maxDepth = 3, maxSiblings = 0) {
     if (parent.type === 'subtask') {
         throw new CleoError(ExitCode.INVALID_PARENT_TYPE, `Cannot add child to ${parentId}: subtasks cannot have children`, { fix: `Create as standalone task or add to parent's parent instead` });
     }
-    // Check depth
+    // Check depth. Behaviourally identical to the previous `depth >= maxDepth`
+    // (this helper was always one of the two correct implementations); routed
+    // through the shared rule so there is exactly one copy of the comparison.
     const depth = getTaskDepth(parentId, tasks);
-    if (depth >= maxDepth) {
+    if (exceedsMaxDepth(depth, maxDepth)) {
         throw new CleoError(ExitCode.DEPTH_EXCEEDED, `Cannot add child to ${parentId}: max hierarchy depth (${maxDepth}) would be exceeded`, {
             fix: 'Reparent this task under a higher-level epic',
-            details: { field: 'parentId', expected: `depth < ${maxDepth}`, actual: depth },
+            details: { field: 'parentId', expected: `depth <= ${maxDepth}`, actual: depth + 1 },
         });
     }
     // Check sibling count
@@ -404,6 +451,23 @@ export function getTaskDepth(taskId, tasks) {
  * console.assert(inferTaskType('T002', tasks) === 'subtask', 'task parent → subtask');
  * ```
  */
+/**
+ * Human-readable list of the tiers that may legally contain `childType`, per the
+ * PM-Core V2 containment matrix.
+ *
+ * Used to explain a refusal in the caller's own vocabulary ("a subtask can only
+ * be filed under a task") rather than quoting a numeric depth the caller never
+ * configured.
+ *
+ * @param childType - The tier the caller asked to create.
+ * @returns Comma-joined parent tier names, or `'nothing (it is a root tier)'`.
+ */
+function describeLegalParents(childType) {
+    const allowed = ['saga', 'epic', 'task', 'subtask']
+        .filter((parent) => isAllowedWorkGraphParentType(childType, parent))
+        .map((parent) => `${/^[aeiou]/.test(parent) ? 'an' : 'a'} ${parent}`);
+    return allowed.length === 0 ? 'nothing (it is a root tier)' : allowed.join(' or ');
+}
 export function inferTaskType(parentId, tasks) {
     if (!parentId)
         return 'task';
@@ -526,8 +590,12 @@ async function hasNoTasks(cwd, accessor) {
  * @task T4460
  */
 export async function addTask(options, cwd, accessor) {
+    const normalizedAcceptance = normalizeAcceptance(options.acceptance);
     // Validate title (early-exit — can't proceed without a title)
     validateTitle(options.title);
+    validateDependencyWaiver(options.priority, options.dependsWaiver, options.depends ?? []);
+    /** Set when `autoDecompose` converted a text-AC leaf parent into a container. */
+    let autoDecomposed;
     // Skip session enforcement for dry-run — no data is written
     if (!options.dryRun) {
         await requireActiveSession('tasks.add', cwd);
@@ -537,7 +605,6 @@ export async function addTask(options, cwd, accessor) {
     // preventing the common failure mode where agents drop flags like --parent.
     const issues = [];
     const warnings = [];
-    const normalizedAcceptance = normalizeAcceptance(options.acceptance);
     // Anti-hallucination: title and description must be different (T5698)
     if (options.description &&
         options.title.trim().toLowerCase() === options.description.trim().toLowerCase()) {
@@ -765,12 +832,17 @@ export async function addTask(options, cwd, accessor) {
         // Depth check using ancestor chain
         const ancestors = await dataAccessor.getAncestorChain(parentId);
         const parentDepth = ancestors.length;
-        if (parentDepth + 1 >= policy.maxDepth) {
+        if (exceedsMaxDepth(parentDepth, policy.maxDepth)) {
             // T11491 — DHQ-044: produce a clear actionable message that names the
-            // parent epic the user SHOULD target instead. The ancestor chain is
-            // ordered [immediateParent, grandparent, …, root]. When the parent is a
-            // task (depth 2), ancestors[0] is the epic (depth 1) — tell the user
-            // to file under THAT epic instead.
+            // container the caller SHOULD target instead.
+            //
+            // The ancestor chain is ordered [root, …, immediateParent]:
+            // `sqlite-data-accessor.ts` builds it with `ORDER BY depth DESC` and
+            // re-sorts "ancestors from root down", so the LAST element is the
+            // prospective parent's own parent — the grandparent of the node being
+            // added. (A prior comment here claimed the reverse order and pointed at
+            // ancestors[0]; the code was always right, the comment was not. Stated
+            // explicitly so nobody "fixes" the index to match the prose.)
             //
             // T11293: NEVER suggest "omit --parent to create a standalone task."
             // Under strict-spine containment (T11811) only sagas may be root-level,
@@ -778,13 +850,28 @@ export async function addTask(options, cwd, accessor) {
             // (so the user never supplied --parent in the first place). Point to a
             // concrete higher-level container, or to --parent none to escape
             // auto-inference (the task will still need a valid parent).
-            const grandparentEpic = ancestors.length > 0 ? ancestors[ancestors.length - 1] : ancestors[0];
+            const grandparent = ancestors.length > 0 ? ancestors[ancestors.length - 1] : undefined;
+            // The tier the caller actually asked for. `taskType` is still the raw
+            // `--type` here (inference runs further down), so an unset type means
+            // "whatever this parent implies" — the same derivation the containment
+            // check below applies.
+            const requestedChildType = taskType ?? childTypeForParentType(parentTask.type ?? 'task');
+            // A suggestion that cannot be executed is worse than no suggestion. The
+            // previous version always offered `--parent <grandparent>` on the grounds
+            // that it is shallower, and said nothing about TYPE. But the caller's
+            // `--type` travels with the retry, and the containment matrix only admits
+            // saga→epic, epic→task, task→subtask — so `--type subtask --parent <epic>`
+            // clears this depth check and is then refused by the matrix below. Two
+            // field reports (GH: a user on 2026.9.5, and an agent that burned three
+            // `cleo add` calls) followed that hint from exit 11 straight into exit 6.
+            // Only offer the grandparent when it can legally hold what was asked for.
+            const grandparentAccepts = grandparent !== undefined &&
+                isAllowedWorkGraphParentType(requestedChildType, grandparent.type ?? 'task');
             // T12136 (GH #1232/#1238) — when the parent was INHERITED rather than
             // named, say so FIRST. Otherwise the message reads as though the caller
-            // asked to file under `parentId`, and the "use --parent <epic>" advice
-            // — the only actionable-looking line — points into a hierarchy the
-            // caller never intended to touch. Naming the inference converts the
-            // suggestion from misleading to optional.
+            // asked to file under `parentId`, and the only actionable-looking line
+            // points into a hierarchy the caller never intended to touch. Naming the
+            // inference converts the suggestion from misleading to optional.
             const wasInherited = options.parentSource === 'session-inference';
             const provenance = wasInherited
                 ? `You did not pass --parent: ${parentId} was inherited from the active session ` +
@@ -793,20 +880,28 @@ export async function addTask(options, cwd, accessor) {
             const escapeHint = wasInherited
                 ? ' Or pass --parent <id> explicitly to override the session pointer, or --parent none to suppress inference.'
                 : '';
-            const epicSuggestion = grandparentEpic
-                ? ` Use --parent ${grandparentEpic.id} (the parent epic) instead.`
-                : ' Reparent under a higher-level container, or use --parent none to suppress session-based parent inference.';
-            throw new CleoError(ExitCode.DEPTH_EXCEEDED, `${provenance}Cannot add a child to ${parentId}: the hierarchy depth cap (${policy.maxDepth}) would be exceeded. ` +
-                `Tasks at depth ${parentDepth} cannot have children.${epicSuggestion}${escapeHint}`, {
-                fix: grandparentEpic
-                    ? `cleo add --parent ${grandparentEpic.id} --title "..." --acceptance "..."`
-                    : 'Reparent this task under a higher-level epic',
+            // T11293: NEVER suggest "omit --parent to create a standalone task" —
+            // under strict-spine containment only a saga may be a root.
+            const suggestion = grandparentAccepts
+                ? ` File it under --parent ${grandparent?.id} as --type ${requestedChildType} instead.`
+                : ` A ${requestedChildType} can only be filed under ${describeLegalParents(requestedChildType)}, ` +
+                    `and every one of those is already at or past the cap here. Re-scope the work so it ` +
+                    `belongs to an existing container, or raise hierarchy.maxDepth in .cleo/config.json.`;
+            throw new CleoError(ExitCode.DEPTH_EXCEEDED, `${provenance}Cannot add a ${requestedChildType} under ${parentId}: it is a ` +
+                `${parentTask.type ?? 'task'} at depth ${parentDepth}, and a child would sit at depth ` +
+                `${parentDepth + 1}, past the hierarchy cap of ${policy.maxDepth} ` +
+                `(saga 0, epic 1, task 2, subtask 3).${suggestion}${escapeHint}`, {
+                fix: grandparentAccepts
+                    ? `cleo add --type ${requestedChildType} --parent ${grandparent?.id} --title "..." --acceptance "..."`
+                    : `Re-scope under an existing container, or raise hierarchy.maxDepth above ${policy.maxDepth}`,
                 details: {
                     field: 'parentId',
-                    expected: `depth < ${policy.maxDepth}`,
+                    expected: `depth <= ${policy.maxDepth}`,
                     actual: parentDepth + 1,
-                    suggestedParentId: grandparentEpic?.id,
-                    suggestedParentTitle: grandparentEpic?.title,
+                    requestedChildType,
+                    // Only ever names a parent that can legally hold `requestedChildType`.
+                    suggestedParentId: grandparentAccepts ? grandparent?.id : undefined,
+                    suggestedParentTitle: grandparentAccepts ? grandparent?.title : undefined,
                     parentSource: options.parentSource ?? 'explicit',
                 },
             });
@@ -841,12 +936,11 @@ export async function addTask(options, cwd, accessor) {
             });
         }
         const parentTypeForValidation = parentTask.type ?? 'task';
-        const childTypeForParent = taskType ??
-            (parentTypeForValidation === 'saga'
-                ? 'epic'
-                : parentTypeForValidation === 'task'
-                    ? 'subtask'
-                    : 'task');
+        // An explicit `--type` is honoured verbatim so the containment check below
+        // can REJECT it. Passing it as `currentType` instead would let the helper's
+        // reparent fallback rewrite it (`--type subtask` under an epic would become
+        // `task`) and silently create the wrong tier rather than refusing.
+        const childTypeForParent = taskType ?? childTypeForParentType(parentTypeForValidation);
         if (!isAllowedWorkGraphParentType(childTypeForParent, parentTypeForValidation)) {
             throw new CleoError(ExitCode.VALIDATION_ERROR, `Invalid parent type for ${taskType}: parent ${parentId} has type '${parentTask.type}'.`, {
                 fix: 'Use Saga→Epic, Epic→Task, and Task→Subtask containment.',
@@ -915,22 +1009,38 @@ export async function addTask(options, cwd, accessor) {
     // pure single-mode leaves are unaffected — the guard fires only when a
     // text-AC-bearing non-container leaf is about to gain its first child.
     if (parentId &&
+        !options.skipMixedAcParentGuard &&
         parentTaskForProjection &&
         parentTaskForProjection.type !== 'epic' &&
         parentTaskForProjection.type !== 'saga') {
         const parentAcRows = await dataAccessor.getAcRows(parentId);
         const parentHasTextAc = parentAcRows.some((row) => row.kind === 'text');
-        if (parentHasTextAc) {
+        if (parentHasTextAc && options.autoDecompose && !options.dryRun) {
+            // Resolve the guard instead of reporting it. Dynamic import because
+            // `decompose.ts` imports `addTask` from here — a static import would close
+            // the cycle. The decompose runs BEFORE the projection write below, so by
+            // the time this add inserts, the parent is a pure container and
+            // design-point 3 holds for real rather than being waived.
+            const { decomposeTask } = await import('./decompose.js');
+            const moved = await decomposeTask({ taskId: parentId }, cwd, dataAccessor);
+            if (moved.childId) {
+                autoDecomposed = { childId: moved.childId, movedAcceptance: moved.movedAcceptance };
+            }
+        }
+        else if (parentHasTextAc) {
             throw new CleoError(ExitCode.VALIDATION_ERROR, `Cannot add child under ${parentId}: it is a ${parentTaskForProjection.type} with its ` +
                 `own free-text acceptance criteria, and adding a child would mix hand-authored text ` +
                 `ACs with machine-managed child_task projections (PM-Core V2 design-point 3). A ` +
                 `${parentTaskForProjection.type} must be either a leaf defined by its own text ACs OR ` +
                 `a container defined by its children, not both. (Epics and sagas are exempt — they are ` +
                 `containers by design.)`, {
-                fix: `Either (a) move ${parentId}'s text acceptance criteria onto a new child task and ` +
-                    `add work under that child, (b) clear ${parentId}'s text ACs ` +
-                    `(\`cleo update ${parentId} --acceptance ""\`) so it becomes a pure container, or ` +
-                    `(c) promote ${parentId} to an epic if it is meant to hold children.`,
+                fix: `Re-run this add with --auto-decompose to do it in one step, or run ` +
+                    `\`cleo decompose ${parentId}\` first — either moves ${parentId}'s text acceptance ` +
+                    `criteria onto a new first child in one step, leaving ${parentId} a pure ` +
+                    `container, after which this add succeeds. (Or promote ${parentId} to an epic ` +
+                    `if it is meant to hold children.) Note that clearing the ACs by hand with ` +
+                    `\`cleo update ${parentId} --acceptance ""\` does NOT work: acceptance ` +
+                    `enforcement rejects an empty criteria list.`,
                 details: {
                     field: 'parentId',
                     parentId,
@@ -943,7 +1053,9 @@ export async function addTask(options, cwd, accessor) {
     }
     // BRAIN-powered duplicate detection (T1633) — query active tasks for semantic similarity.
     // Runs before the exact-title duplicate check so warnings/rejections surface early.
-    // Skip on dry-run (no data written) and skip when forceDuplicate bypasses rejection.
+    // Capture the decision now; persist committed provenance with the task.
+    let duplicateBypass;
+    // Skip on dry-run (no data written).
     if (!options.dryRun) {
         const { checkDuplicatesBounded, buildWarnMessage, buildRejectMessage } = await import('./duplicate-detector.js');
         // T12117 (#1244): bounded and fail-OPEN. This runs BEFORE the insert, so a
@@ -963,16 +1075,14 @@ export async function addTask(options, cwd, accessor) {
             });
         }
         if (dupCheck.shouldReject && options.forceDuplicate) {
-            // User forced past the rejection — audit the bypass
-            const { appendDuplicateBypassAudit } = await import('./duplicate-bypass-audit.js');
-            await appendDuplicateBypassAudit({
+            duplicateBypass = {
                 incomingTitle: options.title,
                 incomingDescription: options.description ?? '',
                 matchedCandidates: dupCheck.candidates,
                 maxScore: dupCheck.maxScore,
                 timestamp: new Date().toISOString(),
                 agent: 'system',
-            }, resolveOrCwd(cwd));
+            };
         }
         if (dupCheck.shouldWarn) {
             // Emit warning to stderr; does not block insertion.
@@ -985,7 +1095,16 @@ export async function addTask(options, cwd, accessor) {
         search: options.title,
         limit: 50,
     });
-    const duplicate = findRecentDuplicate(options.title, phase, candidateDupes);
+    // `forceDuplicate` is honoured here as well as by the semantic check above.
+    // This 60-second window exists to absorb accidental double-submits, but it
+    // returned the EXISTING task without inserting and without throwing, so a
+    // caller that had explicitly said "yes, create it anyway" silently got back a
+    // row it did not create. `cleo decompose` hits this every time it runs on a
+    // task filed moments earlier — the common case — because the child it creates
+    // deliberately inherits the parent's title.
+    const duplicate = options.forceDuplicate
+        ? null
+        : findRecentDuplicate(options.title, phase, candidateDupes);
     if (duplicate) {
         return { task: duplicate, duplicate: true };
     }
@@ -1184,6 +1303,15 @@ export async function addTask(options, cwd, accessor) {
     const createdAcceptanceCriteriaIds = [];
     const reopenedAncestorIds = [];
     await dataAccessor.transaction(async (tx) => {
+        const severityAttestation = options.severity === undefined
+            ? undefined
+            : await prepareSignedSeverityAttestation({
+                timestamp: now,
+                title: task.title,
+                severity: options.severity,
+                taskId,
+                ...(parentId ? { epic: parentId } : {}),
+            }, { cwd });
         // Position shuffling via bulk SQL update (T025)
         if (options.position !== undefined) {
             await dataAccessor.shiftPositions(parentId, options.position, 1);
@@ -1204,14 +1332,13 @@ export async function addTask(options, cwd, accessor) {
         // PM-Core V2 WorkGraph projection sync: parent_id is the containment edge,
         // and each newly-added direct child is mirrored as a parent-owned AC row so
         // completion criteria readers can resolve child work without inspecting
-        // task_relations. Keep the legacy parent acceptance JSON in sync as a
-        // text-only compatibility projection while the row table carries typed
-        // child_task, source_key, and target_task_id state.
+        // task_relations. Preserve existing gate objects in the parent JSON while
+        // the row table carries child_task, source_key, and target_task_id state.
         if (parentId && parentTaskForProjection) {
             const parentAcRows = await tx.getAcRows(parentId);
-            // PM-Core V2 typed child_task AC projection. The legacy parent
-            // acceptance JSON remains text-only compatibility state, but the row
-            // table now carries machine-checkable target_task_id/source_key fields.
+            // PM-Core V2 child_task rows carry target_task_id/source_key fields.
+            // The mixed JSON view retains existing typed gates and appends only the
+            // new child projection as text. Text-input normalization is not a reader.
             const parentChildAcText = buildChildProjectionAcText(taskId, options.title);
             const parentChildOrdinal = parentAcRows.reduce((max, row) => Math.max(max, row.ordinal), 0) + 1;
             const parentChildSourceKey = childProjectionSourceKey(taskId);
@@ -1228,12 +1355,14 @@ export async function addTask(options, cwd, accessor) {
             };
             await tx.insertAcRows([parentChildAcRow]);
             createdAcceptanceCriteriaIds.push(parentChildAcRow.id);
-            const parentAcceptance = normalizeAcceptance([
-                ...(parentTaskForProjection.acceptance ?? []).map(acItemToText),
-                parentChildAcText,
-            ]);
+            // Re-read under the transaction: sibling creators may have appended
+            // their parent projection after the initial validation snapshot.
+            const currentParent = await dataAccessor.loadSingleTask(parentId);
+            if (!currentParent)
+                throw new CleoError(ExitCode.NOT_FOUND, `Parent task not found: ${parentId}`);
+            const parentAcceptance = [...(currentParent.acceptance ?? []), parentChildAcText];
             await tx.updateTaskFields(parentId, {
-                acceptanceJson: JSON.stringify(parentAcceptance ?? []),
+                acceptanceJson: JSON.stringify(parentAcceptance),
                 updatedAt: now,
             });
         }
@@ -1241,15 +1370,20 @@ export async function addTask(options, cwd, accessor) {
         // holds the unsatisfied child injected above. Mirrors coreTaskReopen:
         // status→pending, clear completedAt, preserve completion history in notes.
         for (const ancestor of ancestorsToReopen) {
+            const currentAncestor = await dataAccessor.loadSingleTask(ancestor.id);
+            if (!currentAncestor)
+                throw new CleoError(ExitCode.NOT_FOUND, `Ancestor task not found: ${ancestor.id}`);
+            if (currentAncestor.status !== 'done')
+                continue;
             const reopened = {
-                ...ancestor,
+                ...currentAncestor,
                 status: 'pending',
                 completedAt: undefined,
                 updatedAt: now,
                 notes: [
-                    ...(ancestor.notes ?? []),
-                    ...(ancestor.completedAt
-                        ? [`[${now}] completion-history: completedAt=${ancestor.completedAt}`]
+                    ...(currentAncestor.notes ?? []),
+                    ...(currentAncestor.completedAt
+                        ? [`[${now}] completion-history: completedAt=${currentAncestor.completedAt}`]
                         : []),
                     `[${now}] Reopened by add of child ${taskId} (done parent gained an unsatisfied child)`,
                 ],
@@ -1268,11 +1402,65 @@ export async function addTask(options, cwd, accessor) {
             action: 'task_created',
             taskId,
             actor: 'system',
-            details: { title: options.title, status, priority },
+            details: {
+                title: options.title,
+                status,
+                priority,
+                ...(severityAttestation
+                    ? { severityAttestation: { ...severityAttestation, status: 'committed' } }
+                    : {}),
+                ...(options.forceDuplicate
+                    ? {
+                        forceDuplicate: {
+                            ...duplicateBypass,
+                            requested: true,
+                            bypassed: duplicateBypass !== undefined,
+                            status: 'committed',
+                        },
+                    }
+                    : {}),
+                ...(options.dependsWaiver !== undefined ? { dependsWaiver: options.dependsWaiver } : {}),
+            },
             before: null,
             after: { title: options.title, status, priority },
         });
+        // T945 Stage A — mint a `task:T###` brain graph node at creation, not at
+        // completion. Lazy registration defers execution until the actual outer commit,
+        // including batch transactions; rollback never starts these graph effects.
+        // Tracked (T10490) so the test harness can flush it before tearing down the
+        // shared SQLite singleton; production still runs it fully detached.
+        trackBackgroundOp(() => import('../memory/graph-auto-populate.js')
+            .then(({ ensureTaskNode }) => ensureTaskNode(resolveOrCwd(cwd), taskId, options.title, {
+            status,
+            priority,
+            type: taskType,
+            ...(parentId ? { parentId } : {}),
+        }))
+            .catch(() => {
+            /* Graph population is best-effort — never fail addTask. */
+        }));
+        // T1634 — LOOM auto-init for new epics.
+        // Every new epic automatically initializes the RCASD-IVTR lifecycle pipeline
+        // at the 'research' stage so 'cleo orchestrate ready --epic <id>' always
+        // has a LOOM context (and never returns 'epic has no children' due to an
+        // uninitialized pipeline). Fire-and-forget: failures are swallowed inside
+        // initLoomForEpic so LOOM init never blocks or fails epic creation.
+        if (taskType === 'epic') {
+            // Tracked (T10490) — initLoomForEpic touches the shared tasks singleton via
+            // getDb(); flushing it before a test teardown prevents cross-test races.
+            trackBackgroundOp(() => import('../orchestrate/lifecycle-ops.js')
+                .then(({ initLoomForEpic }) => initLoomForEpic(taskId, resolveOrCwd(cwd)))
+                .catch(() => {
+                /* LOOM init is best-effort — never fail addTask. */
+            }));
+        }
     });
+    if (duplicateBypass) {
+        // Compatibility mirror only; the task transaction contains authoritative evidence.
+        const { appendDuplicateBypassAudit } = await import('./duplicate-bypass-audit.js');
+        const committedBypass = { ...duplicateBypass, taskId, status: 'committed' };
+        await appendDuplicateBypassAudit(committedBypass, resolveOrCwd(cwd));
+    }
     // T10538 / design-point 5: surface the ancestor reopen on the add result so
     // the operator is never surprised by a parent silently transitioning out of
     // `done`. The reopen itself already happened inside the transaction above.
@@ -1282,42 +1470,12 @@ export async function addTask(options, cwd, accessor) {
             `because new child ${taskId} added unsatisfied work under a completed parent. ` +
             `Re-complete the ancestor(s) once ${taskId} is done.`);
     }
-    // T945 Stage A — mint a `task:T###` brain graph node at creation, not at
-    // completion. Prior to this hook, addTask never wrote to the graph, so new
-    // tasks were invisible until completeTask ran. Fire-and-forget: any failure
-    // is swallowed inside ensureTaskNode so graph writes never fail task creation.
-    // Tracked (T10490) so the test harness can flush it before tearing down the
-    // shared SQLite singleton; production still runs it fully detached.
-    trackBackgroundOp(import('../memory/graph-auto-populate.js')
-        .then(({ ensureTaskNode }) => ensureTaskNode(resolveOrCwd(cwd), taskId, options.title, {
-        status,
-        priority,
-        type: taskType,
-        ...(parentId ? { parentId } : {}),
-    }))
-        .catch(() => {
-        /* Graph population is best-effort — never fail addTask. */
-    }));
-    // T1634 — LOOM auto-init for new epics.
-    // Every new epic automatically initializes the RCASD-IVTR lifecycle pipeline
-    // at the 'research' stage so 'cleo orchestrate ready --epic <id>' always
-    // has a LOOM context (and never returns 'epic has no children' due to an
-    // uninitialized pipeline). Fire-and-forget: failures are swallowed inside
-    // initLoomForEpic so LOOM init never blocks or fails epic creation.
-    if (taskType === 'epic') {
-        // Tracked (T10490) — initLoomForEpic touches the shared tasks singleton via
-        // getDb(); flushing it before a test teardown prevents cross-test races.
-        trackBackgroundOp(import('../orchestrate/lifecycle-ops.js')
-            .then(({ initLoomForEpic }) => initLoomForEpic(taskId, resolveOrCwd(cwd)))
-            .catch(() => {
-            /* LOOM init is best-effort — never fail addTask. */
-        }));
-    }
     return {
         task,
         createdIds: { tasks: [taskId], acceptanceCriteria: createdAcceptanceCriteriaIds },
         ...(warnings.length > 0 && { warnings }),
         ...(reopenedAncestorIds.length > 0 && { reopenedAncestors: reopenedAncestorIds }),
+        ...(autoDecomposed && { autoDecomposed }),
     };
 }
 //# sourceMappingURL=add.js.map