@deftai/directive-core 0.73.1 → 0.75.0

package/dist/preflight-cache/evaluate.js

@@ -27,7 +27,14 @@ export const CANDIDATES_RELPATH = join("xbrief", ".triage-cache", "candidates.js
 export const DEFAULT_MAX_AGE_HOURS = 24;
 export const ENV_MAX_AGE_HOURS = "DEFT_CACHE_MAX_AGE_HOURS";
 export const ENV_TRIAGE_REPO = "DEFT_TRIAGE_REPO";
+/** Set by releaseSubprocessEnv() during task release Step 5 (#2386). */
+export const ENV_RELEASE_PREFLIGHT = "DEFT_RELEASE_PREFLIGHT";
 export const REQUIRED_DECISION = "accept";
+const TRUTHY = new Set(["1", "true", "yes", "on"]);
+function releasePreflightBypassActive() {
+    const raw = process.env[ENV_RELEASE_PREFLIGHT] ?? "";
+    return TRUTHY.has(raw.trim().toLowerCase());
+}
 // ---------------------------------------------------------------------------
 // Repo discovery helpers
 // ---------------------------------------------------------------------------
@@ -327,6 +334,7 @@ const REMEDIATION_NO_CANDIDATES = [
 export function evaluate(projectRoot, options = {}) {
     const source = options.source ?? DEFAULT_SOURCE;
     const allowStale = options.allowStale ?? false;
+    const releasePreflightStaleBypass = releasePreflightBypassActive();
     const allowMissingBootstrap = options.allowMissingBootstrap ?? false;
     const nowFn = options.nowFn ?? (() => new Date());
     const envMaxAge = process.env[ENV_MAX_AGE_HOURS];
@@ -423,11 +431,14 @@ export function evaluate(projectRoot, options = {}) {
     // empty-cache case (no entries at all) preserves its prior staleness result.
     const allCandidatesClosed = minFetchedAt === null && rawCandidatePaths.length > 0;
     const stale = allCandidatesClosed ? false : ageH > maxAgeHours;
-    // Step 5b: --allow-stale bypass
-    if (stale && allowStale) {
+    // Step 5b: --allow-stale bypass (or release Step-5 age bypass only, #2386)
+    if (stale && (allowStale || releasePreflightStaleBypass)) {
+        const bypassReason = options.allowStale
+            ? "--allow-stale is set"
+            : `${ENV_RELEASE_PREFLIGHT} is set (release pre-flight)`;
         const warning = [
             `⚠ deft cache-fresh: cache is ${ageH.toFixed(1)}h old (max-age=${maxAgeHours}h) but`,
-            `  --allow-stale is set -- proceeding with audit-trail warning.`,
+            `  ${bypassReason} -- proceeding with audit-trail warning.`,
         ].join("\n");
         if (options.forIssue !== undefined && options.forIssue !== null) {
             const forResult = evaluateForIssue(resolvedRepo, options.forIssue, candidatesPath, cacheRoot, source, scopeRules, projectRoot);

package/dist/preflight-cache/index.d.ts

@@ -1,3 +1,3 @@
 export type { EvaluateOptions, GateResult } from "./evaluate.js";
-export { CACHE_DIR_NAME, CANDIDATES_RELPATH, DEFAULT_MAX_AGE_HOURS, DEFAULT_SOURCE, ENV_MAX_AGE_HOURS, ENV_TRIAGE_REPO, evaluate, REQUIRED_DECISION, } from "./evaluate.js";
+export { CACHE_DIR_NAME, CANDIDATES_RELPATH, DEFAULT_MAX_AGE_HOURS, DEFAULT_SOURCE, ENV_MAX_AGE_HOURS, ENV_RELEASE_PREFLIGHT, ENV_TRIAGE_REPO, evaluate, REQUIRED_DECISION, } from "./evaluate.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/preflight-cache/index.js

@@ -1,2 +1,2 @@
-export { CACHE_DIR_NAME, CANDIDATES_RELPATH, DEFAULT_MAX_AGE_HOURS, DEFAULT_SOURCE, ENV_MAX_AGE_HOURS, ENV_TRIAGE_REPO, evaluate, REQUIRED_DECISION, } from "./evaluate.js";
+export { CACHE_DIR_NAME, CANDIDATES_RELPATH, DEFAULT_MAX_AGE_HOURS, DEFAULT_SOURCE, ENV_MAX_AGE_HOURS, ENV_RELEASE_PREFLIGHT, ENV_TRIAGE_REPO, evaluate, REQUIRED_DECISION, } from "./evaluate.js";
 //# sourceMappingURL=index.js.map

package/dist/release/constants.d.ts

@@ -16,6 +16,8 @@ export declare const VERIFY_DRAFT_INTERVAL_SECONDS = 1;
 export declare const RELEASE_ARTIFACTS: readonly ["CHANGELOG.md", "ROADMAP.md"];
 export declare const BRANCH_GATE_BYPASS_ENV = "DEFT_ALLOW_DEFAULT_BRANCH_COMMIT";
 export declare const DESTRUCTIVE_GH_GATE_BYPASS_ENV = "DEFT_ALLOW_DESTRUCTIVE_GH_VERBS";
+/** Set by releaseSubprocessEnv() so Step-5 pre-flight skips triage-cache staleness (#2386). */
+export declare const RELEASE_PREFLIGHT_ENV = "DEFT_RELEASE_PREFLIGHT";
 export declare const PYPROJECT_VERSION_LINE_RE: RegExp;
 /** Byte-identical argparse --help from scripts/release.py (Python 3.12). */
 export declare const RELEASE_HELP: string;

package/dist/release/constants.js

@@ -24,6 +24,8 @@ export const VERIFY_DRAFT_INTERVAL_SECONDS = 1.0;
 export const RELEASE_ARTIFACTS = ["CHANGELOG.md", "ROADMAP.md"];
 export const BRANCH_GATE_BYPASS_ENV = "DEFT_ALLOW_DEFAULT_BRANCH_COMMIT";
 export const DESTRUCTIVE_GH_GATE_BYPASS_ENV = "DEFT_ALLOW_DESTRUCTIVE_GH_VERBS";
+/** Set by releaseSubprocessEnv() so Step-5 pre-flight skips triage-cache staleness (#2386). */
+export const RELEASE_PREFLIGHT_ENV = "DEFT_RELEASE_PREFLIGHT";
 export const PYPROJECT_VERSION_LINE_RE = /version\s*=\s*"[^"]*"/;
 /** Byte-identical argparse --help from scripts/release.py (Python 3.12). */
 export const RELEASE_HELP = "usage: release [-h] [--dry-run] [--skip-tag] [--skip-release] [--allow-dirty]\n" +

package/dist/release/preflight.d.ts

@@ -8,6 +8,8 @@
  * dispatches `check:framework-source`.
  */
 import { type CheckOrchestratorSeams } from "../check/orchestrator.js";
+/** Step-5-only env: branch bypass plus release pre-flight cache staleness tolerance (#2386). */
+export declare function releaseCheckEnv(base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 /** Seams for test isolation of the native release pre-flight. */
 export interface ReleasePreflightSeams {
     /** Override the check dispatcher (default: dispatchTaskCheck from check/orchestrator). */

package/dist/release/preflight.js

@@ -8,6 +8,15 @@
  * dispatches `check:framework-source`.
  */
 import { dispatchTaskCheck } from "../check/orchestrator.js";
+import { RELEASE_PREFLIGHT_ENV } from "./constants.js";
+import { releaseSubprocessEnv } from "./git.js";
+/** Step-5-only env: branch bypass plus release pre-flight cache staleness tolerance (#2386). */
+export function releaseCheckEnv(base = process.env) {
+    return {
+        ...releaseSubprocessEnv(base),
+        [RELEASE_PREFLIGHT_ENV]: "1",
+    };
+}
 /**
  * Run the native TypeScript `task check` as the release pre-flight.
  *
@@ -18,7 +27,11 @@ import { dispatchTaskCheck } from "../check/orchestrator.js";
  */
 export function runReleaseCheck(projectRoot, seams = {}) {
     const dispatch = seams.dispatchCheck ?? dispatchTaskCheck;
-    const code = dispatch(projectRoot, projectRoot, seams.checkSeams);
+    const checkSeams = {
+        ...seams.checkSeams,
+        env: releaseCheckEnv(seams.checkSeams?.env ?? process.env),
+    };
+    const code = dispatch(projectRoot, projectRoot, checkSeams);
     if (code === 0) {
         return [true, "ran native TypeScript task check"];
     }

package/dist/release/spawn.js

@@ -1,12 +1,14 @@
 import { spawnSync } from "node:child_process";
 import { SUBPROCESS_MAX_BUFFER } from "../subprocess/max-buffer.js";
 export function defaultWhich(name) {
-    const result = spawnSync("which", [name], { encoding: "utf8" });
+    const locator = process.platform === "win32" ? "where" : "which";
+    const result = spawnSync(locator, [name], { encoding: "utf8" });
     if (result.status !== 0) {
         return null;
     }
-    const path = (result.stdout ?? "").trim();
-    return path || null;
+    // `where` on Windows may return multiple lines; take the first non-empty match.
+    const first = (result.stdout ?? "").split(/\r?\n/).find((line) => line.trim().length > 0);
+    return first ? first.trim() : null;
 }
 export function spawnText(cmd, args, options = {}) {
     const result = spawnSync(cmd, [...args], {

package/dist/scope/decompose.js

@@ -7,7 +7,7 @@
  * that draft, writes the child story vBRIEFs, and updates the parent scope references.
  */
 import { accessSync, constants, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { referenceTypeMatches } from "@deftai/directive-types";
 import { hasArtifactSuffix, LEGACY_ARTIFACT_DIR, MIGRATED_ARTIFACT_DIR, resolveLifecycleRoot, } from "../layout/resolve.js";
 import { referenceWithDefaultTrust, slugify } from "../vbrief-build/build.js";
@@ -415,7 +415,7 @@ function vbriefDir(projectRoot) {
 function relToVbrief(vbriefDirPath, path) {
     const resolvedPath = resolve(path);
     const resolvedVbrief = resolve(vbriefDirPath);
-    if (resolvedPath.startsWith(`${resolvedVbrief}/`) || resolvedPath === resolvedVbrief) {
+    if (resolvedPath.startsWith(resolvedVbrief + sep) || resolvedPath === resolvedVbrief) {
         return resolvedPath.slice(resolvedVbrief.length + 1).replace(/\\/g, "/");
     }
     throw new DecompositionError(`${path}: path must be inside ${vbriefDirPath}`);
@@ -823,7 +823,8 @@ export function applyDecomposition(opts) {
     if (!LIFECYCLE_FOLDERS.has(outputFolderName)) {
         throw new DecompositionError("output_dir must be a vbrief lifecycle folder");
     }
-    if (!outputDir.startsWith(`${resolve(vbriefDirPath)}/`) && outputDir !== resolve(vbriefDirPath)) {
+    const resolvedVbriefDir = resolve(vbriefDirPath);
+    if (!outputDir.startsWith(resolvedVbriefDir + sep) && outputDir !== resolvedVbriefDir) {
         throw new DecompositionError("output_dir must be inside vbrief/");
     }
     if (outputFolderName === "active") {

package/dist/scope/index.d.ts

@@ -3,6 +3,7 @@ export * from "./constants.js";
 export * from "./decomposed-refs.js";
 export * from "./demote.js";
 export * from "./main.js";
+export * from "./open-umbrella-warning.js";
 export * from "./project-context.js";
 export * from "./transition.js";
 export * from "./undo.js";

package/dist/scope/index.js

@@ -3,6 +3,7 @@ export * from "./constants.js";
 export * from "./decomposed-refs.js";
 export * from "./demote.js";
 export * from "./main.js";
+export * from "./open-umbrella-warning.js";
 export * from "./project-context.js";
 export * from "./transition.js";
 export * from "./undo.js";

package/dist/scope/main.js

@@ -1,8 +1,10 @@
 import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { reconcileUmbrellas, renderUmbrellasReport } from "../vbrief-reconcile/umbrellas.js";
 import { canonicalLogPath, readAll } from "./audit-log.js";
 import { TRANSITIONS } from "./constants.js";
 import { batchDemote, DEFAULT_OLDER_THAN_DAYS, demoteOne, resolveDemoteFilePath, resolveFilePath, resolveProjectRootStrict, } from "./demote.js";
+import { completedPathForScopeMove, findOpenUmbrellaReferences, renderOpenUmbrellaWarning, } from "./open-umbrella-warning.js";
 import { resolveProjectRoot } from "./project-context.js";
 import { recordWipCapOverride, runTransition } from "./transition.js";
 import { findByDecisionId, isAlreadyUndone, REVERSIBLE_ACTIONS, undoBatch, undoOne, } from "./undo.js";
@@ -88,6 +90,27 @@ export function lifecycleMain(argv) {
                 "audit: vbrief/.eval/scope-lifecycle.jsonl entry tagged wip_cap_override (#1124).\n");
         }
         process.stdout.write(`${result.message}\n`);
+        if (action === "complete") {
+            try {
+                const completedPath = completedPathForScopeMove(filePath);
+                const rootForWarning = resolveProjectRoot(projectRoot) ?? dirname(dirname(dirname(completedPath)));
+                const refs = findOpenUmbrellaReferences(rootForWarning, completedPath);
+                const warning = renderOpenUmbrellaWarning(refs);
+                if (warning.length > 0) {
+                    process.stderr.write(`${warning}\n`);
+                    const [, outcome] = reconcileUmbrellas(rootForWarning);
+                    // Only surface a report when reconcile actually changed something or
+                    // recorded per-epic errors — skip vacuous setup failures (exit 2 with
+                    // empty buckets) so a missing lifecycle root does not spam stderr.
+                    if (outcome.changed.length > 0 || outcome.errors.length > 0) {
+                        process.stderr.write(`${renderUmbrellasReport(outcome)}\n`);
+                    }
+                }
+            }
+            catch {
+                /* best-effort drift warning + reconcile; lifecycle success remains authoritative */
+            }
+        }
         return 0;
     }
     process.stderr.write(`Error: ${result.message}\n`);

package/dist/scope/open-umbrella-warning.d.ts

@@ -0,0 +1,12 @@
+export interface OpenUmbrellaReference {
+    readonly repo: string | null;
+    readonly issueNumber: number | null;
+    readonly title: string;
+    readonly path: string | null;
+    readonly sources: readonly string[];
+}
+/** Find open umbrella/tracker surfaces that still mention a just-completed scope. */
+export declare function findOpenUmbrellaReferences(projectRoot: string, completedScopePath: string): OpenUmbrellaReference[];
+export declare function renderOpenUmbrellaWarning(refs: readonly OpenUmbrellaReference[]): string;
+export declare function completedPathForScopeMove(filePath: string): string;
+//# sourceMappingURL=open-umbrella-warning.d.ts.map

package/dist/scope/open-umbrella-warning.js

@@ -0,0 +1,403 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { referenceTypeMatches } from "@deftai/directive-types";
+import { hasArtifactSuffix } from "../layout/resolve.js";
+import { CACHE_DIR_NAME, CACHE_SOURCE_GITHUB_ISSUE } from "../triage/queue/constants.js";
+import { parseGithubIssueUri } from "../triage/reconcile/parse-uri.js";
+import { collectPlanRefs, resolveVbriefRef } from "./vbrief-ref.js";
+const OPEN_FOLDERS = ["proposed", "pending", "active"];
+const TRACKER_LABELS = new Set(["epic", "meta", "tracker", "type:tracker", "status:tracker"]);
+function readJson(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function planOf(data) {
+    const plan = data?.plan;
+    return typeof plan === "object" && plan !== null && !Array.isArray(plan)
+        ? plan
+        : null;
+}
+function issueRefsFromPlan(plan) {
+    const refs = plan?.references;
+    if (!Array.isArray(refs)) {
+        return [];
+    }
+    const out = [];
+    const seen = new Set();
+    for (const ref of refs) {
+        if (typeof ref !== "object" || ref === null || Array.isArray(ref)) {
+            continue;
+        }
+        const typed = ref;
+        if (!referenceTypeMatches(String(typed.type ?? ""), "github-issue")) {
+            continue;
+        }
+        const [repo, number] = parseGithubIssueUri(typed.uri);
+        if (number === null) {
+            continue;
+        }
+        const key = repo === null ? `bare:${number}` : `${repo}:${number}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        out.push({ repo, number });
+    }
+    return out;
+}
+function labelsFromRaw(raw) {
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    const out = [];
+    for (const label of raw) {
+        if (typeof label === "string") {
+            out.push(label);
+        }
+        else if (typeof label === "object" && label !== null && !Array.isArray(label)) {
+            const name = label.name;
+            if (typeof name === "string") {
+                out.push(name);
+            }
+        }
+    }
+    return out;
+}
+function subIssueTotal(raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return 0;
+    }
+    const total = raw.total;
+    return typeof total === "number" && Number.isFinite(total) ? total : 0;
+}
+function readTextIfPresent(path) {
+    if (!existsSync(path)) {
+        return "";
+    }
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+function readCachedIssue(projectRoot, repo, number) {
+    const [owner, name] = repo.split("/", 2);
+    if (!owner || !name) {
+        return null;
+    }
+    const issueDir = join(projectRoot, CACHE_DIR_NAME, CACHE_SOURCE_GITHUB_ISSUE, owner, name, String(number));
+    const rawPath = join(issueDir, "raw.json");
+    const raw = readJson(rawPath);
+    if (raw === null) {
+        return null;
+    }
+    const body = typeof raw.body === "string" ? raw.body : "";
+    const content = readTextIfPresent(join(issueDir, "content.md"));
+    return {
+        repo,
+        number: typeof raw.number === "number" && Number.isFinite(raw.number) ? raw.number : number,
+        title: typeof raw.title === "string" ? raw.title : `#${number}`,
+        state: typeof raw.state === "string" ? raw.state.toLowerCase() : "open",
+        body: content.length > 0 ? `${body}\n${content}` : body,
+        labels: labelsFromRaw(raw.labels).map((label) => label.toLowerCase()),
+        subIssuesTotal: subIssueTotal(raw.sub_issues_summary),
+    };
+}
+function cachedState(projectRoot, ref) {
+    if (ref.repo === null) {
+        return null;
+    }
+    const cached = readCachedIssue(projectRoot, ref.repo, ref.number);
+    if (cached === null) {
+        return null;
+    }
+    return cached.state === "closed" ? "closed" : "open";
+}
+function chooseOpenIssueRef(projectRoot, refs) {
+    if (refs.length === 0) {
+        return null;
+    }
+    let firstUnknown = null;
+    for (const ref of refs) {
+        const state = cachedState(projectRoot, ref);
+        if (state === "open") {
+            return ref;
+        }
+        if (state === null && firstUnknown === null) {
+            firstUnknown = ref;
+        }
+    }
+    return firstUnknown;
+}
+function refUriMatchesPath(uri, targetPaths, vbriefRoot) {
+    if (typeof uri !== "string" || uri.length === 0) {
+        return false;
+    }
+    const resolved = resolveVbriefRef(uri, vbriefRoot);
+    if (resolved === null) {
+        return false;
+    }
+    return targetPaths.has(resolve(resolved));
+}
+function planReferenceMatchesTarget(ref, targetPaths, vbriefRoot) {
+    if (typeof ref !== "object" || ref === null || Array.isArray(ref)) {
+        return false;
+    }
+    const typed = ref;
+    if (!referenceTypeMatches(String(typed.type ?? ""), "plan")) {
+        return false;
+    }
+    return refUriMatchesPath(typed.uri, targetPaths, vbriefRoot);
+}
+function planReferencesTarget(plan, targetPaths, vbriefRoot) {
+    const refs = plan.references;
+    if (!Array.isArray(refs)) {
+        return false;
+    }
+    return refs.some((ref) => planReferenceMatchesTarget(ref, targetPaths, vbriefRoot));
+}
+function planRefsTarget(plan, targetPaths, vbriefRoot) {
+    return collectPlanRefs(plan).some((uri) => refUriMatchesPath(uri, targetPaths, vbriefRoot));
+}
+function relToRoot(path, root) {
+    return relative(resolve(root), resolve(path)).replace(/\\/g, "/");
+}
+function addReference(out, ref) {
+    const key = ref.repo !== null && ref.issueNumber !== null
+        ? `${ref.repo}#${ref.issueNumber}`
+        : (ref.path ?? ref.title);
+    const existing = out.get(key);
+    if (existing !== undefined) {
+        existing.sources.add(ref.source);
+        if (existing.title.startsWith("#") && !ref.title.startsWith("#")) {
+            existing.title = ref.title;
+        }
+        return;
+    }
+    out.set(key, {
+        repo: ref.repo,
+        issueNumber: ref.issueNumber,
+        title: ref.title,
+        path: ref.path,
+        sources: new Set([ref.source]),
+    });
+}
+function titleForLocalCandidate(plan, issueRef, projectRoot) {
+    if (issueRef?.repo !== null && issueRef?.repo !== undefined) {
+        const cached = readCachedIssue(projectRoot, issueRef.repo, issueRef.number);
+        if (cached !== null) {
+            return cached.title;
+        }
+    }
+    return typeof plan.title === "string" && plan.title.length > 0
+        ? plan.title
+        : issueRef !== null
+            ? `#${issueRef.number}`
+            : "open scope";
+}
+function findLocalReferences(projectRoot, completedScopePath, completedPlan, out) {
+    const vbriefRoot = dirname(dirname(resolve(completedScopePath)));
+    const targetScopePaths = new Set([
+        completedScopePath,
+        ...OPEN_FOLDERS.map((folder) => join(vbriefRoot, folder, basename(completedScopePath))),
+    ].map((path) => resolve(path)));
+    const targetParentPaths = collectPlanRefs(completedPlan)
+        .map((uri) => resolveVbriefRef(uri, vbriefRoot))
+        .filter((path) => path !== null)
+        .map((path) => resolve(path));
+    for (const folder of OPEN_FOLDERS) {
+        const folderPath = join(vbriefRoot, folder);
+        if (!existsSync(folderPath)) {
+            continue;
+        }
+        for (const name of readdirSync(folderPath)
+            .filter((entry) => hasArtifactSuffix(entry))
+            .sort()) {
+            const path = join(folderPath, name);
+            const plan = planOf(readJson(path));
+            if (plan === null) {
+                continue;
+            }
+            const sources = [];
+            if (planReferencesTarget(plan, targetScopePaths, vbriefRoot)) {
+                sources.push("plan.references");
+            }
+            if (planRefsTarget(plan, targetScopePaths, vbriefRoot)) {
+                sources.push("planRef");
+            }
+            if (targetParentPaths.includes(resolve(path))) {
+                sources.push("completed planRef");
+            }
+            if (sources.length === 0) {
+                continue;
+            }
+            const issueRefs = issueRefsFromPlan(plan);
+            const issueRef = chooseOpenIssueRef(projectRoot, issueRefs);
+            if (issueRefs.length > 0 && issueRef === null) {
+                continue;
+            }
+            const relPath = relToRoot(path, projectRoot);
+            for (const source of sources) {
+                addReference(out, {
+                    repo: issueRef?.repo ?? null,
+                    issueNumber: issueRef?.number ?? null,
+                    title: titleForLocalCandidate(plan, issueRef, projectRoot),
+                    path: relPath,
+                    source,
+                });
+            }
+        }
+    }
+}
+function cachedRepoDirs(projectRoot) {
+    const base = join(projectRoot, CACHE_DIR_NAME, CACHE_SOURCE_GITHUB_ISSUE);
+    if (!existsSync(base)) {
+        return [];
+    }
+    const repos = [];
+    for (const ownerEntry of readdirSync(base, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!ownerEntry.isDirectory()) {
+            continue;
+        }
+        const owner = ownerEntry.name;
+        const ownerPath = join(base, owner);
+        for (const repoEntry of readdirSync(ownerPath, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            if (!repoEntry.isDirectory()) {
+                continue;
+            }
+            const name = repoEntry.name;
+            repos.push(`${owner}/${name}`);
+        }
+    }
+    return repos;
+}
+function issueNumberToken(issueNumber) {
+    return Number.isSafeInteger(issueNumber) && issueNumber > 0 ? String(issueNumber) : null;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function textMentionsIssue(text, ref, cachedRepo) {
+    const token = issueNumberToken(ref.number);
+    if (token === null) {
+        return false;
+    }
+    const hash = new RegExp(`(^|[^A-Za-z0-9_#])#${token}(?!\\d)`);
+    if (ref.repo === cachedRepo && hash.test(text)) {
+        return true;
+    }
+    if (ref.repo === null) {
+        return false;
+    }
+    const repo = escapeRegExp(ref.repo);
+    const qualifiedUrl = new RegExp(`(?:github\\.com|api\\.github\\.com/repos)/${repo}/issues/${token}(?:\\D|$)`);
+    return qualifiedUrl.test(text);
+}
+function looksLikeTracker(issue) {
+    if (issue.subIssuesTotal > 0) {
+        return true;
+    }
+    if (issue.labels.some((label) => TRACKER_LABELS.has(label) || label.includes("umbrella"))) {
+        return true;
+    }
+    return /\b(epic|omnibus|tracker|umbrella)\b/i.test(issue.title);
+}
+function findCachedIssueBodyReferences(projectRoot, targetIssueRefs, out) {
+    const targetNumbers = new Set(targetIssueRefs.map((ref) => ref.number));
+    if (targetNumbers.size === 0) {
+        return;
+    }
+    if (!targetIssueRefs.some((ref) => ref.repo !== null)) {
+        return;
+    }
+    for (const repo of cachedRepoDirs(projectRoot)) {
+        const [owner, name] = repo.split("/", 2);
+        if (!owner || !name) {
+            continue;
+        }
+        const repoDir = join(projectRoot, CACHE_DIR_NAME, CACHE_SOURCE_GITHUB_ISSUE, owner, name);
+        for (const entry of readdirSync(repoDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            if (!entry.isDirectory() || !/^\d+$/.test(entry.name)) {
+                continue;
+            }
+            const issueNumber = Number(entry.name);
+            if (targetNumbers.has(issueNumber)) {
+                continue;
+            }
+            const issue = readCachedIssue(projectRoot, repo, issueNumber);
+            if (issue === null || issue.state !== "open" || !looksLikeTracker(issue)) {
+                continue;
+            }
+            const haystack = `${issue.title}\n${issue.body}`;
+            if (!targetIssueRefs.some((ref) => textMentionsIssue(haystack, ref, repo))) {
+                continue;
+            }
+            addReference(out, {
+                repo,
+                issueNumber: issue.number,
+                title: issue.title,
+                path: null,
+                source: "cached issue body",
+            });
+        }
+    }
+}
+/** Find open umbrella/tracker surfaces that still mention a just-completed scope. */
+export function findOpenUmbrellaReferences(projectRoot, completedScopePath) {
+    const data = readJson(completedScopePath);
+    const completedPlan = planOf(data);
+    if (completedPlan === null) {
+        return [];
+    }
+    const out = new Map();
+    findLocalReferences(projectRoot, completedScopePath, completedPlan, out);
+    findCachedIssueBodyReferences(projectRoot, issueRefsFromPlan(completedPlan), out);
+    return [...out.values()]
+        .map((ref) => ({
+        repo: ref.repo,
+        issueNumber: ref.issueNumber,
+        title: ref.title,
+        path: ref.path,
+        sources: [...ref.sources].sort(),
+    }))
+        .sort((a, b) => {
+        const aKey = a.issueNumber !== null
+            ? a.repo === null
+                ? `bare:#${a.issueNumber}`
+                : `${a.repo}#${a.issueNumber}`
+            : (a.path ?? "");
+        const bKey = b.issueNumber !== null
+            ? b.repo === null
+                ? `bare:#${b.issueNumber}`
+                : `${b.repo}#${b.issueNumber}`
+            : (b.path ?? "");
+        return aKey.localeCompare(bKey);
+    });
+}
+function displayReference(ref) {
+    const issue = ref.issueNumber !== null ? `#${ref.issueNumber}${ref.repo ? ` (${ref.repo})` : ""}` : null;
+    const path = ref.path !== null ? ref.path : null;
+    const name = issue ?? path ?? ref.title;
+    return `${name}: ${ref.title}`;
+}
+export function renderOpenUmbrellaWarning(refs) {
+    if (refs.length === 0) {
+        return "";
+    }
+    const names = refs.map(displayReference).join("; ");
+    return (`Warning: scope:complete found open umbrella/tracker reference(s) to the completed scope: ${names}. ` +
+        "Run `task vbrief:reconcile:umbrellas` to refresh current-shape comments.");
+}
+export function completedPathForScopeMove(filePath) {
+    const resolved = resolve(filePath);
+    return join(dirname(dirname(resolved)), "completed", basename(resolved));
+}
+//# sourceMappingURL=open-umbrella-warning.js.map

package/dist/scope/vbrief-ref.js

@@ -1,4 +1,4 @@
-import { resolve } from "node:path";
+import { resolve, sep } from "node:path";
 import { referenceTypeMatches } from "@deftai/directive-types";
 import { resolveLifecycleArtifactRef, } from "../layout/lifecycle-ref.js";
 import { hasArtifactSuffix, stripArtifactSuffix } from "../layout/resolve.js";
@@ -87,7 +87,7 @@ export function scopeIdsForFilename(filename) {
 export function relativeToVbrief(path, vbriefRoot) {
     const resolved = resolve(path);
     const root = resolve(vbriefRoot);
-    if (!resolved.startsWith(`${root}/`) && resolved !== root) {
+    if (!resolved.startsWith(root + sep) && resolved !== root) {
         return null;
     }
     return resolved.slice(root.length + 1).replace(/\\/g, "/");
@@ -95,7 +95,7 @@ export function relativeToVbrief(path, vbriefRoot) {
 export function canonicalRelpath(filePath, projectRoot) {
     const resolved = resolve(filePath);
     const root = resolve(projectRoot);
-    if (resolved.startsWith(`${root}/`) || resolved === root) {
+    if (resolved.startsWith(root + sep) || resolved === root) {
         return resolved.slice(root.length + (resolved === root ? 0 : 1)).replace(/\\/g, "/");
     }
     return resolved.replace(/\\/g, "/");