@cleocode/core 2026.9.8 → 2026.9.9

package/dist/tasks/reconcile-scope.js

@@ -0,0 +1,242 @@
+/**
+ * Containment-aware scope reconciliation across a saga or epic.
+ *
+ * ## Why this exists
+ *
+ * `duplicate-detector.ts` runs at INSERT time over a FLAT candidate set — it
+ * queries `{status: [pending, active, blocked], limit}` with no parent or saga
+ * scoping — and its verdict is binary: reject, or insert. Two consequences,
+ * both reported from the field on large projects:
+ *
+ *   1. **Partial overlap is invisible.** Two tasks that share part of their
+ *      scope are neither duplicates nor unrelated, and the insert-time check
+ *      has no vocabulary for that. They both get created and quietly compete.
+ *   2. **Nothing is ever re-examined.** Overlap mostly emerges AFTER filing, as
+ *      scope drifts during execution and several agents extend adjacent tasks
+ *      toward the same middle. The insert-time check has long since run.
+ *
+ * `cleo reconcile` already existed but only covers release tags. The `relates`
+ * vocabulary (`duplicates`, `absorbs`, `supersedes`) already existed too, and
+ * nothing produced or consumed it — it was declarable by hand and never by a
+ * workflow.
+ *
+ * This module supplies the missing sweep: retro-active, scoped to a container,
+ * and classifying each overlapping pair into a concrete ACTION rather than a
+ * duplicate yes/no.
+ *
+ * ## Deliberately deterministic
+ *
+ * Detection reuses `computeLexicalSimilarity` and `computeJaccardWordSimilarity`
+ * from the duplicate detector. No LLM call, no embedding provider. A sweep an
+ * agent is expected to run repeatedly must be cheap, offline, and give the same
+ * answer twice — an LLM-scored sweep that reshuffles its own findings between
+ * runs cannot be acted on incrementally.
+ *
+ * @task T12299
+ */
+import { ExitCode } from '@cleocode/contracts';
+import { engineSuccess } from '../engine-result.js';
+import { CleoError } from '../errors.js';
+import { cleoErrorToEngineResult } from '../errors-to-engine.js';
+import { getTaskAccessor } from '../store/data-accessor.js';
+import { computeJaccardWordSimilarity, computeLexicalSimilarity } from './duplicate-detector.js';
+/** Statuses that represent live work. Terminal rows are history, not competition. */
+const LIVE_STATUSES = new Set(['pending', 'active', 'blocked']);
+/**
+ * Pairs are O(n²). Above this many live nodes the sweep reports a bounded scan
+ * rather than silently comparing a subset — a truncated sweep that reads as
+ * complete is worse than one that says what it skipped.
+ */
+export const MAX_SWEEP_NODES = 400;
+/** At or above this combined score two tasks describe the same deliverable. */
+export const MERGE_THRESHOLD = 0.9;
+/**
+ * At or above this two tasks share enough scope to need a decision.
+ *
+ * Calibrated against real data, not chosen: swept saga T9977 in this repo (144
+ * live tasks, 10,160 pairs) and counted findings by threshold —
+ *
+ * ```
+ *   >= 0.55: 427   >= 0.70:  7
+ *   >= 0.60: 128   >= 0.75:  5
+ *   >= 0.65:  32   >= 0.85:  2
+ * ```
+ *
+ * 0.55 returns 427 findings, which is not a report anyone acts on. 0.65 returns
+ * 32 from 144 tasks, which is reviewable.
+ *
+ * The residual false positives are instructive and worth knowing before
+ * lowering this again: on a codebase with naming conventions, titles share
+ * vocabulary without sharing scope. `Route createAgentWorktree through core SDK`
+ * vs `Route destroyAgentWorktree through core SDK` scores 0.852 and is two
+ * genuinely different pieces of work. That is why high-confidence actions
+ * (`merge`/`absorb`) sit at {@link MERGE_THRESHOLD} and additionally require a
+ * tier/parent match — on that same real sweep they fired ZERO times, while
+ * firing correctly on a synthetic control with true duplicates.
+ */
+export const OVERLAP_THRESHOLD = 0.65;
+/**
+ * Classify one overlapping pair into an action.
+ *
+ * The tier and parent relationship decide the action, not the score alone. Two
+ * near-identical siblings are a merge; a near-identical pair in DIFFERENT
+ * containers is an absorb, because merging across containers silently moves
+ * work between epics; and moderate overlap is a split when the two sit apart
+ * (extract the shared part) or a link when they are already siblings under one
+ * parent, where the overlap is usually intended sequencing.
+ */
+function classify(a, b, score) {
+    const sameParent = (a.parentId ?? null) === (b.parentId ?? null);
+    const sameTier = (a.type ?? 'task') === (b.type ?? 'task');
+    if (score >= MERGE_THRESHOLD && sameParent && sameTier) {
+        return {
+            action: 'merge',
+            relation: 'duplicates',
+            rationale: `Same tier, same parent, ${(score * 100).toFixed(0)}% scope match — these describe one deliverable.`,
+        };
+    }
+    if (score >= MERGE_THRESHOLD) {
+        return {
+            action: 'absorb',
+            relation: 'absorbs',
+            rationale: `${(score * 100).toFixed(0)}% scope match across different containers — fold the later into the earlier rather than merging across parents.`,
+        };
+    }
+    if (!sameParent) {
+        return {
+            action: 'split',
+            relation: 'related',
+            rationale: `${(score * 100).toFixed(0)}% shared scope in different containers — extract the shared part so neither owns it by accident.`,
+        };
+    }
+    return {
+        action: 'link',
+        relation: 'related',
+        rationale: `${(score * 100).toFixed(0)}% shared scope between siblings — usually intended sequencing; record the link rather than restructuring.`,
+    };
+}
+/**
+ * Sweep a container for tasks whose scope overlaps, and propose what to do.
+ *
+ * Read-only unless `apply` is set. Even with `apply`, the ONLY mutation is
+ * writing `relates` edges — nothing is merged, retitled, reparented or deleted.
+ * A sweep that restructured the graph on its own reading of a similarity score
+ * would be acting on exactly the judgement it is least qualified to make; the
+ * edges make the overlap visible and leave the decision with the caller.
+ *
+ * Idempotent: `addRelation` upserts, so a second run over an unchanged graph
+ * writes the same edges and changes nothing.
+ *
+ * @param options - Sweep inputs; see {@link ReconcileScopeOptions}.
+ * @param cwd - Project root. Defaults to the resolved CLEO project.
+ * @param accessor - Optional pre-bound data accessor.
+ * @returns The overlaps found, worst first, and how many edges were written.
+ * @throws {@link CleoError} `E_NOT_FOUND` when the root does not exist.
+ *
+ * @example
+ * ```ts
+ * const r = await reconcileScope({ rootId: 'T12243' });
+ * for (const o of r.overlaps) console.log(o.action, o.keepId, o.otherId, o.rationale);
+ * ```
+ */
+export async function reconcileScope(options, cwd, accessor) {
+    const acc = accessor ?? (await getTaskAccessor(cwd));
+    const threshold = options.threshold ?? OVERLAP_THRESHOLD;
+    // Reject rather than clamp. A threshold that quietly became something else
+    // would make two runs of the same command disagree with no way to tell why,
+    // and this sweep is meant to be run repeatedly and compared.
+    if (!Number.isFinite(threshold) || threshold < 0 || threshold > 1) {
+        throw new CleoError(ExitCode.VALIDATION_ERROR, `threshold must be a number between 0 and 1 (got ${JSON.stringify(options.threshold)})`, {
+            fix: 'Pass --threshold with a value in [0,1], e.g. --threshold 0.6',
+            details: { field: 'threshold', expected: '0 <= threshold <= 1', actual: options.threshold },
+        });
+    }
+    const root = await acc.loadSingleTask(options.rootId);
+    if (!root) {
+        throw new CleoError(ExitCode.NOT_FOUND, `Task not found: ${options.rootId}`, {
+            fix: `cleo find "${options.rootId}"`,
+            details: { field: 'rootId', actual: options.rootId },
+        });
+    }
+    const subtree = await acc.getSubtree(options.rootId);
+    // The root itself is not a candidate — a container never competes with the
+    // work it contains, however closely its title matches.
+    const live = subtree
+        .filter((t) => t.id !== options.rootId && LIVE_STATUSES.has(t.status))
+        .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    const truncated = live.length > MAX_SWEEP_NODES ? { limit: MAX_SWEEP_NODES, liveNodes: live.length } : undefined;
+    const nodes = truncated ? live.slice(0, MAX_SWEEP_NODES) : live;
+    const overlaps = [];
+    let pairs = 0;
+    for (let i = 0; i < nodes.length; i++) {
+        for (let j = i + 1; j < nodes.length; j++) {
+            const a = nodes[i];
+            const b = nodes[j];
+            if (!a || !b)
+                continue;
+            // Containment is not competition: a subtask legitimately restates its
+            // parent's scope, which is what a decomposition IS.
+            if (a.parentId === b.id || b.parentId === a.id)
+                continue;
+            pairs++;
+            // Both scorers weight the title internally; description and labels add
+            // signal without letting a long shared boilerplate description swamp two
+            // genuinely different deliverables.
+            const score = Math.max(computeLexicalSimilarity(a.title, a.description ?? '', b.title, b.description ?? ''), computeJaccardWordSimilarity(a.title, a.description ?? '', a.labels ?? [], b.title, b.description ?? '', b.labels ?? []));
+            if (score < threshold)
+                continue;
+            // `nodes` is createdAt-ascending, so `a` is always the earlier task and
+            // therefore the survivor — a stable rule beats "whichever looks better",
+            // and it makes the sweep's output reproducible.
+            const { action, relation, rationale } = classify(a, b, score);
+            overlaps.push({
+                keepId: a.id,
+                keepTitle: a.title,
+                otherId: b.id,
+                otherTitle: b.title,
+                action,
+                score: Number(score.toFixed(4)),
+                relation,
+                rationale,
+                sameParent: (a.parentId ?? null) === (b.parentId ?? null),
+            });
+        }
+    }
+    overlaps.sort((x, y) => y.score - x.score);
+    let applied = 0;
+    if (options.apply) {
+        for (const o of overlaps) {
+            await acc.addRelation(o.otherId, o.keepId, o.relation, o.rationale);
+            applied++;
+        }
+    }
+    return {
+        rootId: options.rootId,
+        scanned: nodes.length,
+        pairs,
+        overlaps,
+        applied,
+        ...(truncated && { truncated }),
+    };
+}
+/**
+ * Dispatch-layer wrapper for {@link reconcileScope}.
+ *
+ * Mirrors `taskDecompose`: converts thrown {@link CleoError}s into an
+ * {@link EngineResult} so the gateway renders a LAFS envelope, preserving the
+ * original LAFS code rather than blanket-labelling every failure.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root.
+ * @param options - Sweep inputs; see {@link ReconcileScopeOptions}.
+ * @returns Engine result carrying the overlaps and applied-edge count.
+ */
+export async function taskReconcileScope(projectRoot, options) {
+    try {
+        const accessor = await getTaskAccessor(projectRoot);
+        return engineSuccess(await reconcileScope(options, projectRoot, accessor));
+    }
+    catch (err) {
+        return cleoErrorToEngineResult(err, 'E_INTERNAL', 'Failed to reconcile scope');
+    }
+}
+//# sourceMappingURL=reconcile-scope.js.map

package/dist/tasks/reconcile-scope.js.map

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

package/dist/tasks/req.d.ts

@@ -38,22 +38,37 @@ export interface MigrationProposal {
 }
 /** Result of `reqMigrate` with `apply: true`. */
 export interface MigrationApplyResult {
+    /** Proposed replacements evaluated against the transaction snapshot. */
     proposals: MigrationProposal[];
+    /** Number of free-text criteria replaced by validated gates. */
     applied: number;
 }
 /**
  * Add a typed `AcceptanceGate` (with a REQ-ID) to a task's acceptance array.
  *
- * Validates the gate JSON against the Zod schema before writing. Rejects
- * duplicate REQ-IDs within the same task.
+ * @remarks
+ * Validates before opening storage. Reading existing acceptance, checking REQ-ID
+ * uniqueness and persisting the task/AC projection share one transaction, so
+ * competing appends cannot overwrite each other. This records a gate; it does
+ * not execute it or record passing verification evidence.
+ *
+ * @returns The committed acceptance array and its owning task identity.
+ * @example
+ * ```typescript
+ * const gate: AcceptanceGate = {
+ *   kind: 'test', command: 'node', args: ['verify.mjs'], expect: 'exit0',
+ *   req: 'PARTNER-121', description: 'Task-specific checks pass',
+ * };
+ * await reqAdd(projectRoot, 'T121', gate, undefined);
+ * ```
  *
  * @param projectRoot - Absolute path to project root
  * @param taskId - Target task ID
- * @param gate - Parsed `AcceptanceGate` object (already validated)
+ * @param gate - Typed gate; runtime schema validation also applies to SDK callers
  * @param accessor - Optional pre-created accessor (for testing)
  *
- * @throws {CleoError} E_NOT_FOUND when the task does not exist
- * @throws {CleoError} E_VALIDATION when the REQ-ID already exists on the task
+ * @throws CleoError E_NOT_FOUND when the task does not exist
+ * @throws CleoError E_VALIDATION when the REQ-ID already exists on the task
  *
  * @task T782
  */
@@ -66,15 +81,21 @@ export declare function reqAdd(projectRoot: string, taskId: string, gate: Accept
 /**
  * List all REQ-ID–addressed acceptance gates on a task.
  *
- * Free-text strings (legacy) in the acceptance array are skipped because
- * they have no REQ-ID. Only structured `AcceptanceGate` items with a `req`
- * field are returned.
+ * @remarks
+ * Free-text strings are skipped because they have no REQ-ID. This summary does
+ * not execute gates or establish verification; full payloads remain on the task.
+ *
+ * @returns Requirement identity, index, kind and description for each named gate.
+ * @example
+ * ```typescript
+ * const { gates } = await reqList(projectRoot, 'T121', undefined);
+ * ```
  *
  * @param projectRoot - Absolute path to project root
  * @param taskId - Target task ID
  * @param accessor - Optional pre-created accessor (for testing)
  *
- * @throws {CleoError} E_NOT_FOUND when the task does not exist
+ * @throws CleoError E_NOT_FOUND when the task does not exist
  *
  * @task T782
  */
@@ -86,19 +107,27 @@ export declare function reqList(projectRoot: string, taskId: string, accessor?:
  * Heuristic migrator: reads free-text acceptance strings and proposes typed
  * `AcceptanceGate` replacements.
  *
+ * @remarks
  * Without `apply: true` only proposals are returned. With `apply: true` the
  * matched strings are replaced in the task's acceptance array and the updated
  * array is persisted.
  *
  * Auto-generated REQ-IDs use the pattern `MIGRATED-001`, `MIGRATED-002`, etc.
- * Strings that already contain a structured gate (object items) are skipped.
+ * Existing structured gates and their requirement identities are preserved.
+ * Apply plans and persists under one transaction; preview does not write.
+ *
+ * @returns Proposed replacements and, when applied, the committed replacement count.
+ * @example
+ * ```typescript
+ * const preview = await reqMigrate(projectRoot, 'T121', false, undefined);
+ * ```
  *
  * @param projectRoot - Absolute path to project root
  * @param taskId - Target task ID
  * @param apply - When true, writes the proposals back to the task
  * @param accessor - Optional pre-created accessor (for testing)
  *
- * @throws {CleoError} E_NOT_FOUND when the task does not exist
+ * @throws CleoError E_NOT_FOUND when the task does not exist
  *
  * @task T782
  */
@@ -112,9 +141,19 @@ export declare function reqMigrate(projectRoot: string, taskId: string, apply: b
  * Returns the parsed `AcceptanceGate` on success or throws a `CleoError`
  * with exit code `E_VALIDATION` on failure.
  *
+ * @remarks
+ * Uses the same schema boundary as direct SDK writes and rejects unsupported
+ * fields, including nested fields that the schema would otherwise strip.
+ *
+ * @returns The validated gate without executing its command.
+ * @example
+ * ```typescript
+ * const raw = '{"kind":"manual","description":"Review","prompt":"Approve?"}';
+ * const gate = parseGateJson(raw);
+ * ```
  * @param raw - Raw JSON string from `--gate` CLI flag
  *
- * @throws {CleoError} E_VALIDATION when JSON is malformed or schema invalid
+ * @throws CleoError E_VALIDATION when JSON is malformed or schema invalid
  *
  * @task T782
  */

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

@@ -1 +1 @@
-{"version":3,"file":"req.d.ts","sourceRoot":"","sources":["../../src/tasks/req.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAG1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAa9D,mCAAmC;AACnC,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,GAAG,EAAE,MAAM,CAAC;IACZ,8BAA8B;IAC9B,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IAC7B,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,qBAAqB;IACrB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,yCAAyC;AACzC,MAAM,WAAW,iBAAiB;IAChC,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IAChC,mDAAmD;IACnD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,uFAAuF;IACvF,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,iDAAiD;AACjD,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,iBAAiB,EAAE,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;CACjB;AAoHD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,MAAM,CAC1B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,cAAc,EACpB,QAAQ,CAAC,EAAE,YAAY,GACtB,OAAO,CAAC;IAAE,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,cAAc,EAAE,CAAA;KAAE,CAAA;CAAE,CAAC,CA2BjE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,OAAO,CAC3B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,YAAY,GACtB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,YAAY,EAAE,CAAA;CAAE,CAAC,CAsBpD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,UAAU,CAC9B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,EACd,QAAQ,CAAC,EAAE,YAAY,GACtB,OAAO,CAAC;IAAE,SAAS,EAAE,iBAAiB,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA4C/D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAuBzD"}
+{"version":3,"file":"req.d.ts","sourceRoot":"","sources":["../../src/tasks/req.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAuB,MAAM,qBAAqB,CAAC;AAG/F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAa9D,mCAAmC;AACnC,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,GAAG,EAAE,MAAM,CAAC;IACZ,8BAA8B;IAC9B,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IAC7B,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,qBAAqB;IACrB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,yCAAyC;AACzC,MAAM,WAAW,iBAAiB;IAChC,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IAChC,mDAAmD;IACnD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,uFAAuF;IACvF,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,iDAAiD;AACjD,MAAM,WAAW,oBAAoB;IACnC,wEAAwE;IACxE,SAAS,EAAE,iBAAiB,EAAE,CAAC;IAC/B,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;CACjB;AAkHD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,MAAM,CAC1B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,cAAc,EACpB,QAAQ,CAAC,EAAE,YAAY,GACtB,OAAO,CAAC;IAAE,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,cAAc,EAAE,CAAA;KAAE,CAAA;CAAE,CAAC,CA6BjE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,OAAO,CAC3B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,YAAY,GACtB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,YAAY,EAAE,CAAA;CAAE,CAAC,CAsBpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,UAAU,CAC9B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,EACd,QAAQ,CAAC,EAAE,YAAY,GACtB,OAAO,CAAC;IAAE,SAAS,EAAE,iBAAiB,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAsD/D;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAWzD"}