@cleocode/core 2026.9.8 → 2026.9.9

package/dist/orchestration/waves.d.ts

@@ -17,7 +17,7 @@ export interface Wave {
  * Enriched task reference within a wave.
  *
  * Carries all fields needed by the wave renderer so callers do not need a
- * secondary lookup.  `blockedBy` lists open (non-terminal) dependency IDs;
+ * secondary lookup.  `blockedBy` lists dependencies that do not satisfy spawn readiness;
  * `ready` is `true` when the task is immediately actionable.
  */
 export interface EnrichedWaveTask extends TaskRef {
@@ -30,9 +30,9 @@ export interface EnrichedWaveTask extends TaskRef {
      */
     depends: string[];
     /**
-     * Open (non-terminal) dependency IDs that are currently blocking this task.
+     * Dependency IDs that are currently blocking this task from spawning.
      *
-     * A dependency is open when its status is not `'done'` or `'cancelled'`.
+     * Only `'done'` and `'archived'` satisfy dependencies; missing records block.
      */
     blockedBy: string[];
     /**
@@ -75,19 +75,28 @@ export interface EnrichedWave {
 /**
  * Compute execution waves using topological sort.
  *
- * Tasks that are already done/cancelled are pre-seeded into the `completed` set
- * so their dependants can be scheduled in wave 1. Wave status is derived from
- * the live `task.status` field rather than the local `completed` set (which
- * excludes non-terminal tasks and would always yield `false` for in-flight work).
+ * @remarks
+ * Only done or archived dependencies satisfy readiness. Earlier planned waves
+ * establish ordering, not evidence that their tasks have already completed.
+ * Missing or unfinished dependencies outside the selected population remain
+ * unresolved and are retained in the final pending wave. Terminal tasks are
+ * excluded from scheduling; cancelled dependencies still block their dependants.
  *
- * @param tasks - All tasks to partition into dependency waves.
- * @returns Ordered waves where each wave's tasks can execute in parallel.
+ * @param tasks - Selected tasks to partition into dependency waves.
+ * @param dependencyLookup - Loaded dependency population, including external tasks.
+ * @returns Ordered planned waves, with unresolved work retained as pending.
+ *
+ * @example
+ * ```ts
+ * const waves = computeWaves(tasks, projectTaskMap);
+ * ```
  */
-export declare function computeWaves(tasks: Task[]): Wave[];
+export declare function computeWaves(tasks: Task[], dependencyLookup?: ReadonlyMap<string, Task>): Wave[];
 /**
- * Get enriched wave data for an epic.
+ * Get enriched wave data for an epic or a selected set of saga members.
  *
- * Resolves the epic's direct children, computes topological waves, enriches
+ * @remarks
+ * Resolves the selected parents' direct children, computes one topological plan, enriches
  * each wave's task list with dependency metadata, sorts tasks within each wave
  * by priority descending then open-dep count ascending, and attaches a
  * `completedAt` timestamp to completed waves.
@@ -95,8 +104,15 @@ export declare function computeWaves(tasks: Task[]): Wave[];
  * @param epicId   - The epic task ID to compute waves for.
  * @param cwd      - Optional project root (falls back to `getTaskAccessor` default).
  * @param accessor - Optional pre-constructed data accessor (useful in tests).
+ * @param parentIds - Containment parents to select; defaults to the requested epic.
+ * @returns Selected task counts and waves with current dependency readiness.
+ *
+ * @example
+ * ```ts
+ * const plan = await getEnrichedWaves(sagaId, root, accessor, memberEpicIds);
+ * ```
  */
-export declare function getEnrichedWaves(epicId: string, cwd?: string, accessor?: DataAccessor): Promise<{
+export declare function getEnrichedWaves(epicId: string, cwd?: string, accessor?: DataAccessor, parentIds?: readonly string[]): Promise<{
     epicId: string;
     waves: EnrichedWave[];
     totalWaves: number;

package/dist/orchestration/waves.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"waves.d.ts","sourceRoot":"","sources":["../../src/orchestration/waves.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAG9D,kEAAkE;AAClE,MAAM,WAAW,IAAI;IACnB,2BAA2B;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,8CAA8C;IAC9C,MAAM,EAAE,SAAS,GAAG,aAAa,GAAG,WAAW,CAAC;CACjD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAiB,SAAQ,OAAO;IAC/C,2BAA2B;IAC3B,QAAQ,EAAE,YAAY,CAAC;IACvB;;;;OAIG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;;;;OAIG;IACH,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB;;;;OAIG;IACH,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,2BAA2B;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,8CAA8C;IAC9C,MAAM,EAAE,SAAS,GAAG,aAAa,GAAG,WAAW,CAAC;IAChD;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAkFD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,CAyDlD;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,GAAG,CAAC,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,YAAY,GACtB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,YAAY,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,CAmC5F"}
+{"version":3,"file":"waves.d.ts","sourceRoot":"","sources":["../../src/orchestration/waves.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAO9D,kEAAkE;AAClE,MAAM,WAAW,IAAI;IACnB,2BAA2B;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,8CAA8C;IAC9C,MAAM,EAAE,SAAS,GAAG,aAAa,GAAG,WAAW,CAAC;CACjD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAiB,SAAQ,OAAO;IAC/C,2BAA2B;IAC3B,QAAQ,EAAE,YAAY,CAAC;IACvB;;;;OAIG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;;;;OAIG;IACH,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB;;;;OAIG;IACH,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,2BAA2B;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,8CAA8C;IAC9C,MAAM,EAAE,SAAS,GAAG,aAAa,GAAG,WAAW,CAAC;IAChD;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA8DD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,IAAI,EAAE,EACb,gBAAgB,GAAE,WAAW,CAAC,MAAM,EAAE,IAAI,CAAiD,GAC1F,IAAI,EAAE,CA2CR;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,GAAG,CAAC,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,YAAY,EACvB,SAAS,GAAE,SAAS,MAAM,EAAa,GACtC,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,YAAY,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,CAuC5F"}

package/dist/orchestration/waves.js

@@ -3,6 +3,7 @@
  * @task T4784
  */
 import { getTaskAccessor } from '../store/data-accessor.js';
+import { getReadinessDependencyBlockers, loadReadinessDependencyLookup, } from '../tasks/dependency-check.js';
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
@@ -28,12 +29,7 @@ function enrichTask(id, taskMap) {
     const status = task?.status ?? 'unknown';
     const priority = (task?.priority ?? 'medium');
     const depends = task?.depends ?? [];
-    const blockedBy = depends.filter((depId) => {
-        const dep = taskMap.get(depId);
-        if (!dep)
-            return false;
-        return dep.status !== 'done' && dep.status !== 'cancelled';
-    });
+    const blockedBy = getReadinessDependencyBlockers(depends, taskMap);
     const ready = blockedBy.length === 0 && (status === 'pending' || status === 'active');
     return { id, title, status, priority, depends, blockedBy, ready };
 }
@@ -61,68 +57,47 @@ function sortWaveTasks(tasks) {
         return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
     });
 }
-/** Build a dependency graph for tasks. */
-function buildDependencyGraph(tasks) {
-    const graph = new Map();
-    for (const task of tasks) {
-        if (!graph.has(task.id)) {
-            graph.set(task.id, new Set());
-        }
-        if (task.depends) {
-            for (const dep of task.depends) {
-                graph.get(task.id).add(dep);
-            }
-        }
-    }
-    return graph;
-}
 /**
  * Compute execution waves using topological sort.
  *
- * Tasks that are already done/cancelled are pre-seeded into the `completed` set
- * so their dependants can be scheduled in wave 1. Wave status is derived from
- * the live `task.status` field rather than the local `completed` set (which
- * excludes non-terminal tasks and would always yield `false` for in-flight work).
+ * @remarks
+ * Only done or archived dependencies satisfy readiness. Earlier planned waves
+ * establish ordering, not evidence that their tasks have already completed.
+ * Missing or unfinished dependencies outside the selected population remain
+ * unresolved and are retained in the final pending wave. Terminal tasks are
+ * excluded from scheduling; cancelled dependencies still block their dependants.
  *
- * @param tasks - All tasks to partition into dependency waves.
- * @returns Ordered waves where each wave's tasks can execute in parallel.
+ * @param tasks - Selected tasks to partition into dependency waves.
+ * @param dependencyLookup - Loaded dependency population, including external tasks.
+ * @returns Ordered planned waves, with unresolved work retained as pending.
+ *
+ * @example
+ * ```ts
+ * const waves = computeWaves(tasks, projectTaskMap);
+ * ```
  */
-export function computeWaves(tasks) {
-    const graph = buildDependencyGraph(tasks);
+export function computeWaves(tasks, dependencyLookup = new Map(tasks.map((task) => [task.id, task]))) {
     const waves = [];
-    const completed = new Set();
-    for (const task of tasks) {
-        if (task.status === 'done' || task.status === 'cancelled') {
-            completed.add(task.id);
-        }
-    }
-    let remaining = tasks.filter((t) => t.status !== 'done' && t.status !== 'cancelled');
+    const planned = new Set();
+    let remaining = tasks.filter((task) => !['done', 'cancelled', 'archived'].includes(task.status));
     let waveNumber = 1;
     const maxWaves = 50;
     while (remaining.length > 0 && waveNumber <= maxWaves) {
         const waveTasks = remaining.filter((t) => {
-            const deps = graph.get(t.id) || new Set();
-            return Array.from(deps).every((d) => completed.has(d));
+            return getReadinessDependencyBlockers(t.depends, dependencyLookup).every((id) => planned.has(id));
         });
         if (waveTasks.length === 0)
             break;
-        // Determine wave status from task.status directly.
-        // Note: `remaining` already excludes done/cancelled tasks, so checking
-        // `completed.has(t.id)` here would always be false — dead code prior to T1197.
-        const allDone = waveTasks.every((t) => t.status === 'done' || t.status === 'cancelled');
-        const anyActive = waveTasks.some((t) => t.status === 'active');
-        const waveStatus = allDone
-            ? 'completed'
-            : anyActive
-                ? 'in_progress'
-                : 'pending';
+        const waveStatus = waveTasks.some((task) => task.status === 'active')
+            ? 'in_progress'
+            : 'pending';
         waves.push({
             waveNumber,
             tasks: waveTasks.map((t) => t.id),
             status: waveStatus,
         });
         for (const t of waveTasks) {
-            completed.add(t.id);
+            planned.add(t.id);
         }
         remaining = remaining.filter((t) => !waveTasks.some((wt) => wt.id === t.id));
         waveNumber++;
@@ -137,9 +112,10 @@ export function computeWaves(tasks) {
     return waves;
 }
 /**
- * Get enriched wave data for an epic.
+ * Get enriched wave data for an epic or a selected set of saga members.
  *
- * Resolves the epic's direct children, computes topological waves, enriches
+ * @remarks
+ * Resolves the selected parents' direct children, computes one topological plan, enriches
  * each wave's task list with dependency metadata, sorts tasks within each wave
  * by priority descending then open-dep count ascending, and attaches a
  * `completedAt` timestamp to completed waves.
@@ -147,12 +123,24 @@ export function computeWaves(tasks) {
  * @param epicId   - The epic task ID to compute waves for.
  * @param cwd      - Optional project root (falls back to `getTaskAccessor` default).
  * @param accessor - Optional pre-constructed data accessor (useful in tests).
+ * @param parentIds - Containment parents to select; defaults to the requested epic.
+ * @returns Selected task counts and waves with current dependency readiness.
+ *
+ * @example
+ * ```ts
+ * const plan = await getEnrichedWaves(sagaId, root, accessor, memberEpicIds);
+ * ```
  */
-export async function getEnrichedWaves(epicId, cwd, accessor) {
+export async function getEnrichedWaves(epicId, cwd, accessor, parentIds = [epicId]) {
     const acc = accessor ?? (await getTaskAccessor(cwd));
-    const children = await acc.getChildren(epicId);
-    const waves = computeWaves(children);
-    const taskMap = new Map(children.map((t) => [t.id, t]));
+    const selected = new Map();
+    for (const parentId of new Set(parentIds)) {
+        for (const task of await acc.getChildren(parentId))
+            selected.set(task.id, task);
+    }
+    const children = [...selected.values()];
+    const taskMap = await loadReadinessDependencyLookup(children, acc);
+    const waves = computeWaves(children, taskMap);
     const enrichedWaves = waves.map((w) => {
         const enrichedTasks = sortWaveTasks(w.tasks.map((id) => enrichTask(id, taskMap)));
         const wave = {

package/dist/orchestration/waves.js.map

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

package/dist/paths.d.ts

@@ -14,71 +14,8 @@
  * @epic T4454
  * @task T4458
  */
-import { AsyncLocalStorage } from 'node:async_hooks';
-/**
- * Async context payload set by the spawn adapter when launching a subagent
- * inside a git worktree (ADR-041 §D3).
- *
- * @remarks
- * When `worktreeScope.run(scope, fn)` is active, `getProjectRoot()` returns
- * `scope.worktreeRoot` instead of walking ancestors. All DB path functions
- * that delegate to `getProjectRoot()` therefore direct their I/O to the
- * worktree's `.cleo/` directory, closing the T335 worktree-leak root cause.
- *
- * For processes that were spawned with `CLEO_WORKTREE_ROOT` in their
- * environment (but where AsyncLocalStorage is not in scope), callers should
- * populate the store via:
- * ```ts
- * worktreeScope.run(
- *   { worktreeRoot: process.env.CLEO_WORKTREE_ROOT, projectHash: process.env.CLEO_PROJECT_HASH },
- *   () => { ... }
- * );
- * ```
- *
- * @task T380
- * @public
- */
-export interface WorktreeScope {
-    /**
-     * Absolute path to the worktree directory (value of `CLEO_WORKTREE_ROOT`).
-     */
-    worktreeRoot: string;
-    /**
-     * Project hash used to scope the worktree under the XDG worktree root
-     * (value of `CLEO_PROJECT_HASH`).
-     */
-    projectHash: string;
-}
-/**
- * AsyncLocalStorage instance that carries the active {@link WorktreeScope}
- * for the current async execution context.
- *
- * @remarks
- * Set by the spawn adapter (or any caller that wants to redirect CLEO path
- * resolution to a worktree directory) before invoking subagent logic.
- * `getProjectRoot()` checks this store BEFORE the `CLEO_ROOT` env-var and
- * ancestor-walk, so scoped callers transparently receive the worktree root.
- *
- * Callers outside a worktree context receive `undefined` from
- * `worktreeScope.getStore()` and fall through to the existing resolution
- * order unchanged.
- *
- * @example
- * ```ts
- * import { worktreeScope } from '@cleocode/core/paths';
- *
- * worktreeScope.run(
- *   { worktreeRoot: '/path/to/worktree', projectHash: 'abc123' },
- *   async () => {
- *     const root = getProjectRoot(); // returns '/path/to/worktree'
- *   }
- * );
- * ```
- *
- * @task T380
- * @public
- */
-export declare const worktreeScope: AsyncLocalStorage<WorktreeScope>;
+export type { WorktreeScope } from './project-scope.js';
+export { getProjectRoot, validateProjectRoot, worktreeScope } from './project-scope.js';
 /**
  * Run `fn` inside a `worktreeScope.run()` AsyncLocalStorage frame derived
  * from the `CLEO_WORKTREE_ROOT` and `CLEO_PROJECT_HASH` environment variables.
@@ -284,6 +221,8 @@ export declare function getCleoDir(cwd?: string): string;
  * getCleoDirAbsolute('/tmp/new-project', { bootstrap: true }); // "/tmp/new-project/.cleo"
  * ```
  *
+ * @remarks Active worktree scope takes precedence over ambient CLEO_DIR, matching
+ * resolveCleoDir. Outside a scope, absolute CLEO_DIR retains its override behavior.
  * @deprecated Migrate to {@link resolveProjectByCwd} + {@link resolveCanonicalCleoDir}
  * @task T11009
  */
@@ -384,55 +323,6 @@ export declare function resolveCleoDir(cwd?: string): string;
  * @task T11280
  */
 export declare function tryResolveCleoDir(cwd?: string): string | null;
-/**
- * Validate that a candidate project root directory is a legitimate CLEO
- * project root and not a stray parent `.cleo/` directory that happened to
- * be found by the walk-up algorithm.
- *
- * ## Primary path (T1864 — project-info.json contract)
- *
- * A candidate is **accepted** when `.cleo/project-info.json` exists and
- * parses as JSON with a non-empty `projectId` string field.  This is the
- * canonical form written by `cleo init` and is the only form that guarantees
- * the directory is a proper CLEO project rather than a stray `.cleo/` left by
- * an old installation or a git worktree that auto-created its own `.cleo/`.
- *
- * ## Legacy fallback (backwards-compatibility)
- *
- * Projects initialized before `project-info.json` was introduced are still
- * accepted when **both** of the following are true:
- *   1. `.cleo/` exists in `candidate`
- *   2. `.git/` exists as a sibling of `.cleo/` in `candidate`
- *
- * A one-time stderr warning is emitted (guarded by `_legacyFallbackWarned`)
- * so operators know to re-run `cleo init` to upgrade the project metadata.
- *
- * **Breaking change vs. prior implementation**: bare `package.json` alone is
- * no longer sufficient.  The old check `existsSync(gitDir) || existsSync(pkgJson)`
- * accepted any Node.js package directory as a valid project root, which caused
- * the monorepo-package bug where sub-packages inside `packages/` created their
- * own empty `.cleo/` databases.
- *
- * @param candidate - Absolute path to the directory being considered as the
- *   project root (parent of the `.cleo/` directory).
- * @returns `true` when the candidate is a recognised CLEO project root.
- *
- * @example
- * ```typescript
- * // Project root with project-info.json — valid (primary path)
- * validateProjectRoot('/home/user/myproject'); // true
- *
- * // Legacy project root with .git/ but no project-info.json — valid + warning
- * validateProjectRoot('/home/user/legacy-project'); // true (+ stderr warning)
- *
- * // Stray .cleo in home dir with no markers — invalid
- * validateProjectRoot('/home/user'); // false
- * ```
- *
- * @task T1463
- * @task T1864
- */
-export declare function validateProjectRoot(candidate: string): boolean;
 /**
  * Assert that the given directory is an initialized CLEO project root,
  * throwing a `CleoError` if it is not.
@@ -456,54 +346,6 @@ export declare function validateProjectRoot(candidate: string): boolean;
  * @task T1864
  */
 export declare function assertProjectInitialized(projectRoot: string): void;
-/**
- * Get the project root by walking ancestor directories for `.cleo/` or `.git/`.
- *
- * Stops at the **first** ancestor directory that contains either sentinel
- * directory and never drifts past it — even when multiple nested projects
- * exist above the starting directory.
- *
- * Resolution order:
- *   1. `CLEO_ROOT` env var — bypasses walk entirely (CI / test override)
- *   2. `CLEO_DIR` env var (absolute path only) — derives project root from dirname
- *   3. Walk ancestors from `cwd` (or `process.cwd()`) toward filesystem root:
- *      - `.cleo/` found with a sibling `.git/` or `package.json` → accept as root
- *      - `.cleo/` found but **no** sibling marker → skip (stray/parent `.cleo/`)
- *      - `.git/` found (without `.cleo/` sibling) → throw `E_NOT_INITIALIZED`
- *   4. Filesystem root reached without a valid root → throw `E_INVALID_PROJECT_ROOT`
- *      (if at least one `.cleo/` was skipped) or `E_NO_PROJECT` (none found)
- *
- * @param cwd - Optional starting directory; defaults to `process.cwd()`
- * @returns Absolute path to the project root directory (parent of `.cleo/`)
- * @throws {CleoError} `ExitCode.CONFIG_ERROR` (`E_NOT_INITIALIZED`) when a
- *   `.git/` is found but no `.cleo/` is present at that level.
- * @throws {CleoError} `ExitCode.CONFIG_ERROR` (`E_INVALID_PROJECT_ROOT`) when
- *   one or more `.cleo/` directories are found but none have the required sibling
- *   markers (`.git/` or `package.json`). This prevents accidental operations on
- *   the wrong project when a stray parent `.cleo/` exists higher in the filesystem.
- * @throws {CleoError} `ExitCode.NOT_FOUND` (`E_NO_PROJECT`) when neither
- *   sentinel is found in any ancestor.
- *
- * @remarks
- * `CLEO_ROOT` is an absolute-path escape hatch for environments where the
- * working directory is unrelated to the project (CI tmpdirs, monorepo scripts,
- * test harnesses). When set it is returned as-is without scanning ancestors.
- *
- * `CLEO_DIR` set to an absolute path (e.g. `/project/.cleo`) also bypasses
- * the walk: the project root is derived as its `dirname`. This preserves
- * backward compatibility for test harnesses that use `CLEO_DIR` to pin the
- * project root.
- *
- * NEVER auto-creates `.cleo/`. Project initialisation is an explicit opt-in
- * via `cleo init`.
- *
- * @example
- * ```typescript
- * // Running from packages/core inside the monorepo:
- * const root = getProjectRoot(); // "/mnt/projects/cleocode"
- * ```
- */
-export declare function getProjectRoot(cwd?: string): string;
 /**
  * Resolve an optional caller-provided root, falling back to canonical project root.
  *
@@ -1157,6 +999,18 @@ export interface ProjectRegistryEntry {
 }
 /** Look up a project by canonical or legacy projectId (AC1, AC4). */
 export declare function resolveProjectById(projectId: string): Promise<ProjectRegistryEntry | null>;
-/** Auto-register a project on first encounter (AC2, AC3, AC5, AC6). */
+/**
+ * Register an encountered project's immutable identity in its captured global registry.
+ * @param projectRoot - Explicit project ownership captured before asynchronous work.
+ * @param infoProjectId - Existing immutable project identity, never inferred from similarity.
+ * @returns Completion of the fully tracked operation, including any failure.
+ * @remarks Lazy work obeys the existing transaction/queue boundary and shares the
+ * original execution deadline. Registry writes never initialize the project graph.
+ * Cancellation is checked before the actual synchronous registry transaction commits.
+ * @example
+ * ```ts
+ * await registerProjectOnEncounter(projectRoot, projectId);
+ * ```
+ */
 export declare function registerProjectOnEncounter(projectRoot: string, infoProjectId: string): Promise<void>;
 //# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

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