@deftai/directive-core 0.55.2 → 0.56.0

package/dist/triage/actions/candidates-log.d.ts

@@ -1,5 +1,16 @@
-import type { CandidatesLog } from "./types.js";
+import type { AuditEntry, CandidatesLog } from "./types.js";
 export declare const AUDIT_LOG_REL_PATH = "vbrief/.eval/candidates.jsonl";
+/** Read every well-formed audit-log row in insertion order (#1698 shared reader). */
+export declare function readAuditLog(logPath: string, repo?: string | null): AuditEntry[];
+/** Return every entry for ``(repo, issue_number)`` in insertion order. */
+export declare function findByIssue(issueNumber: number, repo: string, logPath: string): AuditEntry[];
+/**
+ * Canonical latest decision for ``(repo, issue_number)`` — no actor filter.
+ * Backfilled ``agent:bootstrap`` / ``agent:reconcile`` entries count equally.
+ */
+export declare function latestDecisionForIssue(issueNumber: number, repo: string, logPath: string): AuditEntry | null;
+/** Collapse audit-log entries to ``{(repo, issue_number): decision}`` by timestamp. */
+export declare function latestDecisions(entries: Iterable<AuditEntry | Record<string, unknown>>): Map<string, string>;
 /** Filesystem-backed candidates audit log (mirrors ``scripts/candidates_log.py``). */
 export declare function createCandidatesLog(defaultProjectRoot: string): CandidatesLog;
 /** Remove the audit-log line whose ``decision_id`` matches (rollback path). */

package/dist/triage/actions/candidates-log.js

@@ -113,7 +113,8 @@ function stableStringify(entry) {
     }
     return JSON.stringify(sorted);
 }
-function readAll(repo, logPath) {
+/** Read every well-formed audit-log row in insertion order (#1698 shared reader). */
+export function readAuditLog(logPath, repo = null) {
     if (!existsSync(logPath)) {
         return [];
     }
@@ -132,7 +133,47 @@ function readAll(repo, logPath) {
                 continue;
             out.push(row);
         }
-        catch { }
+        catch {
+            // tolerate malformed lines — mirrors candidates_log.read_all
+        }
+    }
+    return out;
+}
+/** Return every entry for ``(repo, issue_number)`` in insertion order. */
+export function findByIssue(issueNumber, repo, logPath) {
+    return readAuditLog(logPath, repo).filter((row) => row.issue_number === issueNumber);
+}
+/**
+ * Canonical latest decision for ``(repo, issue_number)`` — no actor filter.
+ * Backfilled ``agent:bootstrap`` / ``agent:reconcile`` entries count equally.
+ */
+export function latestDecisionForIssue(issueNumber, repo, logPath) {
+    const rows = findByIssue(issueNumber, repo, logPath);
+    if (rows.length === 0)
+        return null;
+    rows.sort((a, b) => String(a.timestamp).localeCompare(String(b.timestamp)));
+    return rows.at(-1) ?? null;
+}
+/** Collapse audit-log entries to ``{(repo, issue_number): decision}`` by timestamp. */
+export function latestDecisions(entries) {
+    const rows = [];
+    for (const entry of entries) {
+        const repo = entry.repo;
+        const issueNumber = entry.issue_number;
+        const decision = entry.decision;
+        const timestamp = entry.timestamp;
+        if (typeof repo === "string" &&
+            typeof issueNumber === "number" &&
+            Number.isInteger(issueNumber) &&
+            typeof decision === "string" &&
+            typeof timestamp === "string") {
+            rows.push([timestamp, repo, issueNumber, decision]);
+        }
+    }
+    rows.sort((a, b) => a[0].localeCompare(b[0]));
+    const out = new Map();
+    for (const [_ts, repo, n, decision] of rows) {
+        out.set(`${repo}\0${n}`, decision);
     }
     return out;
 }
@@ -148,11 +189,7 @@ export function createCandidatesLog(defaultProjectRoot) {
         },
         latestDecision(issueNumber, repo, options) {
             const logPath = resolveLogPath(defaultProjectRoot, options?.path);
-            const rows = readAll(repo, logPath).filter((row) => row.issue_number === issueNumber);
-            if (rows.length === 0)
-                return null;
-            rows.sort((a, b) => String(a.timestamp).localeCompare(String(b.timestamp)));
-            return rows.at(-1) ?? null;
+            return latestDecisionForIssue(issueNumber, repo, logPath);
         },
         newDecisionId() {
             return randomUUID();

package/dist/triage/actions/index.d.ts

@@ -1,5 +1,5 @@
 import type { AcceptOptions, AuditEntry, DeferOptions, RejectOptions, TriageActionsDeps } from "./types.js";
-export { AUDIT_LOG_REL_PATH, createCandidatesLog, resolveAuditLogPath, rollbackAuditEntry, } from "./candidates-log.js";
+export { AUDIT_LOG_REL_PATH, createCandidatesLog, findByIssue, latestDecisionForIssue, latestDecisions, readAuditLog, resolveAuditLogPath, rollbackAuditEntry, } from "./candidates-log.js";
 export { CandidatesLogError, ResumeGrammarError, TriageError, UpstreamCloseError, } from "./errors.js";
 export { parseResumeOn } from "./resume-on.js";
 export type { AcceptOptions, AuditEntry, CandidatesLog, DeferOptions, IssueIngest, RejectOptions, ScmRunner, TriageActionsDeps, } from "./types.js";
@@ -8,12 +8,36 @@ export declare const REJECTED_LABEL_COLOR = "B60205";
 export declare const REJECTED_LABEL_DESCRIPTION = "Issue rejected during deft triage";
 /** Default dependency bundle for production CLI use. */
 export declare function createDefaultDeps(projectRoot: string): TriageActionsDeps;
+/** Return audit entries for ``issueNumber`` ordered ascending by timestamp. */
+export declare function history(issueNumber: number, repo: string, _deps: TriageActionsDeps, options?: {
+    projectRoot?: string;
+}): AuditEntry[];
 /** Record an accept audit entry and delegate vBRIEF authoring to issue_ingest. */
 export declare function accept(issueNumber: number, repo: string, deps: TriageActionsDeps, options?: AcceptOptions): string;
 /** Close upstream, best-effort label, record reject audit entry. */
 export declare function reject(issueNumber: number, repo: string, reason: string, deps: TriageActionsDeps, options?: RejectOptions): string;
 /** Record a defer audit entry (#1123 -- structured reason + resume_on). */
 export declare function deferAction(issueNumber: number, repo: string, reason: string | null | undefined, deps: TriageActionsDeps, options?: DeferOptions): string;
+/** Record a needs-ac audit entry and best-effort post an AC-request comment upstream. */
+export declare function needsAc(issueNumber: number, repo: string, deps: TriageActionsDeps, options?: {
+    actor?: string | null;
+    comment?: string | null;
+    projectRoot?: string;
+}): string;
+/** Validate duplicate target in cache and record a mark-duplicate audit entry. */
+export declare function markDuplicate(issueNumber: number, repo: string, ofN: number, deps: TriageActionsDeps, options?: {
+    actor?: string | null;
+    projectRoot?: string;
+}): string;
+/** Return the latest decision for ``issueNumber`` in ``repo`` (null if none). */
+export declare function status(issueNumber: number, repo: string, deps: TriageActionsDeps, options?: {
+    projectRoot?: string;
+}): AuditEntry | null;
+/** Record a reset audit entry referencing the prior decision_id (history is never deleted). */
+export declare function reset(issueNumber: number, repo: string, deps: TriageActionsDeps, options?: {
+    actor?: string | null;
+    projectRoot?: string;
+}): string;
 /** Format a decision entry for CLI ``status`` / ``history`` output. */
 export declare function formatDecision(entry: AuditEntry | null): string;
 //# sourceMappingURL=index.d.ts.map

package/dist/triage/actions/index.js

@@ -1,12 +1,14 @@
 import { spawnSync } from "node:child_process";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { CacheNotFoundError } from "../../cache/errors.js";
+import { cacheGet } from "../../cache/operations.js";
 import { call } from "../../scm/call.js";
 import { ScmStubError } from "../../scm/errors.js";
-import { createCandidatesLog, resolveAuditLogPath, rollbackAuditEntry } from "./candidates-log.js";
+import { createCandidatesLog, findByIssue, resolveAuditLogPath, rollbackAuditEntry, } from "./candidates-log.js";
 import { TriageError, UpstreamCloseError } from "./errors.js";
 import { parseResumeOn } from "./resume-on.js";
-export { AUDIT_LOG_REL_PATH, createCandidatesLog, resolveAuditLogPath, rollbackAuditEntry, } from "./candidates-log.js";
+export { AUDIT_LOG_REL_PATH, createCandidatesLog, findByIssue, latestDecisionForIssue, latestDecisions, readAuditLog, resolveAuditLogPath, rollbackAuditEntry, } from "./candidates-log.js";
 export { CandidatesLogError, ResumeGrammarError, TriageError, UpstreamCloseError, } from "./errors.js";
 export { parseResumeOn } from "./resume-on.js";
 export const REJECTED_LABEL = "triage-rejected";
@@ -14,6 +16,8 @@ export const REJECTED_LABEL_COLOR = "B60205";
 export const REJECTED_LABEL_DESCRIPTION = "Issue rejected during deft triage";
 const TERMINAL_DECISIONS = new Set(["accept", "reject", "mark-duplicate"]);
 const DEFAULT_ACTOR = "agent:triage";
+const DEFAULT_NEEDS_AC_COMMENT = "This issue lacks acceptance criteria. Please add a Test/Acceptance " +
+    "narrative before this can be triaged. (deft #845)";
 function resolveDeftRoot() {
     if (process.env.DEFT_ROOT !== undefined && process.env.DEFT_ROOT.length > 0) {
         return resolve(process.env.DEFT_ROOT);
@@ -88,13 +92,24 @@ function defaultIssueIngest(deftRoot) {
 /** Default dependency bundle for production CLI use. */
 export function createDefaultDeps(projectRoot) {
     const deftRoot = resolveDeftRoot();
-    return {
+    const deps = {
         candidatesLog: createCandidatesLog(projectRoot),
         issueIngest: defaultIssueIngest(deftRoot),
         scm: defaultScmRunner(),
         nowIso: defaultNowIso,
         stderr: (message) => process.stderr.write(`${message}\n`),
     };
+    if (process.env.DEFT_TRIAGE_ACTIONS_PARITY === "1") {
+        return {
+            ...deps,
+            scm: {
+                call() {
+                    throw new UpstreamCloseError("gh disabled for parity");
+                },
+            },
+        };
+    }
+    return deps;
 }
 function buildEntry(deps, decision, issueNumber, repo, actor, extras = {}) {
     const entry = {
@@ -111,6 +126,16 @@ function buildEntry(deps, decision, issueNumber, repo, actor, extras = {}) {
 function logPathFor(projectRoot) {
     return resolveAuditLogPath(projectRoot);
 }
+function cacheRootFor(projectRoot) {
+    return join(projectRoot, ".deft-cache");
+}
+/** Return audit entries for ``issueNumber`` ordered ascending by timestamp. */
+export function history(issueNumber, repo, _deps, options = {}) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const entries = findByIssue(issueNumber, repo, logPathFor(projectRoot));
+    entries.sort((a, b) => String(a.timestamp).localeCompare(String(b.timestamp)));
+    return entries;
+}
 function isIdempotentRepeat(deps, issueNumber, repo, decision, projectRoot, linkedTo) {
     if (!TERMINAL_DECISIONS.has(decision))
         return null;
@@ -277,6 +302,72 @@ export function deferAction(issueNumber, repo, reason, deps, options = {}) {
     const logPath = logPathFor(projectRoot);
     return deps.candidatesLog.append(entry, { path: logPath });
 }
+/** Record a needs-ac audit entry and best-effort post an AC-request comment upstream. */
+export function needsAc(issueNumber, repo, deps, options = {}) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const body = options.comment ?? DEFAULT_NEEDS_AC_COMMENT;
+    const actor = resolveActor(options.actor);
+    const entry = buildEntry(deps, "needs-ac", issueNumber, repo, actor, { reason: body });
+    const logPath = logPathFor(projectRoot);
+    const decisionId = deps.candidatesLog.append(entry, { path: logPath });
+    const writeErr = deps.stderr ?? ((message) => process.stderr.write(`${message}\n`));
+    try {
+        runGh(deps, ["issue", "comment", String(issueNumber), "--repo", repo, "--body", body]);
+    }
+    catch (exc) {
+        writeErr(`triage_actions: needs-ac comment not posted for #${issueNumber} (${repo}): ${exc instanceof Error ? exc.message : String(exc)}`);
+    }
+    return decisionId;
+}
+/** Validate duplicate target in cache and record a mark-duplicate audit entry. */
+export function markDuplicate(issueNumber, repo, ofN, deps, options = {}) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    if (ofN === issueNumber) {
+        throw new TriageError(`mark-duplicate target #${ofN} cannot equal source #${issueNumber}`);
+    }
+    const key = `${repo}/${ofN}`;
+    try {
+        cacheGet("github-issue", key, { allowStale: true, cacheRoot: cacheRootFor(projectRoot) });
+    }
+    catch (exc) {
+        if (exc instanceof CacheNotFoundError) {
+            throw new TriageError(`mark-duplicate target #${ofN} not found in cache for ${repo}: ${exc.message}`);
+        }
+        throw exc;
+    }
+    const prior = isIdempotentRepeat(deps, issueNumber, repo, "mark-duplicate", projectRoot, ofN);
+    if (prior !== null) {
+        return prior.decision_id;
+    }
+    const actor = resolveActor(options.actor);
+    const entry = buildEntry(deps, "mark-duplicate", issueNumber, repo, actor, { linked_to: ofN });
+    const logPath = logPathFor(projectRoot);
+    return deps.candidatesLog.append(entry, { path: logPath });
+}
+/** Return the latest decision for ``issueNumber`` in ``repo`` (null if none). */
+export function status(issueNumber, repo, deps, options = {}) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    return deps.candidatesLog.latestDecision(issueNumber, repo, {
+        path: logPathFor(projectRoot),
+    });
+}
+/** Record a reset audit entry referencing the prior decision_id (history is never deleted). */
+export function reset(issueNumber, repo, deps, options = {}) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const logPath = logPathFor(projectRoot);
+    const prior = deps.candidatesLog.latestDecision(issueNumber, repo, { path: logPath });
+    if (prior === null) {
+        throw new TriageError(`cannot reset #${issueNumber}: no prior decision recorded for ${repo}`);
+    }
+    if (prior.decision === "reset") {
+        return prior.decision_id;
+    }
+    const actor = resolveActor(options.actor);
+    const entry = buildEntry(deps, "reset", issueNumber, repo, actor, {
+        prior_decision_id: prior.decision_id,
+    });
+    return deps.candidatesLog.append(entry, { path: logPath });
+}
 /** Format a decision entry for CLI ``status`` / ``history`` output. */
 export function formatDecision(entry) {
     if (entry === null) {

package/dist/triage/summary/index.d.ts

@@ -5,6 +5,7 @@ export { DEFAULT_WIP_CAP, PROJECT_DEFINITION_REL_PATH };
 export declare const CACHE_DIR_NAME = ".deft-cache";
 export declare const CACHE_SOURCE = "github-issue";
 export declare const CANDIDATES_LOG_REL_PATH = "vbrief/.eval/candidates.jsonl";
+export { latestDecisions, readAuditLog } from "../actions/candidates-log.js";
 export declare const SUMMARY_HISTORY_REL_PATH = "vbrief/.eval/summary-history.jsonl";
 export declare const SUMMARY_HISTORY_SCHEMA = "deft.triage.summary.v1";
 export declare const EMPTY_CACHE_LINE = "[triage] cache empty -- run task triage:bootstrap";
@@ -38,9 +39,6 @@ export declare function utcIso(date?: Date): string;
 export declare function isPosIntDirName(name: string): boolean;
 /** Walk `<cache_root>/github-issue/<owner>/<repo>/<N>/` cache entries. */
 export declare function iterCachedIssues(cacheRoot: string): Array<[string, number]>;
-export declare function readAuditLog(logPath: string): Record<string, unknown>[];
-/** Collapse audit-log entries to `{(repo, issue_number): decision}`. */
-export declare function latestDecisions(entries: Iterable<Record<string, unknown>>): Map<string, string>;
 /** Count filesystem-truth in-flight vBRIEFs (#1270). */
 export declare function countFilesystemInFlight(projectRoot: string): number;
 /** True iff `plan.policy.triageScope` is a non-empty list of dict rules. */

package/dist/triage/summary/index.js

@@ -2,6 +2,7 @@ import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from
 import { join, resolve as pathResolve } from "node:path";
 import { loadProjectDefinition, PROJECT_DEFINITION_REL_PATH } from "../../policy/resolve.js";
 import { countVbriefWip, DEFAULT_WIP_CAP, resolveWipCap } from "../../policy/wip.js";
+import { AUDIT_LOG_REL_PATH, latestDecisions, readAuditLog } from "../actions/candidates-log.js";
 import { countReconcilable } from "./reconcilable.js";
 import { computeScopeDriftTotal } from "./scope-drift.js";
 // ---------------------------------------------------------------------------
@@ -11,7 +12,8 @@ export const MAX_LINE_CHARS = 120;
 export { DEFAULT_WIP_CAP, PROJECT_DEFINITION_REL_PATH };
 export const CACHE_DIR_NAME = ".deft-cache";
 export const CACHE_SOURCE = "github-issue";
-export const CANDIDATES_LOG_REL_PATH = "vbrief/.eval/candidates.jsonl";
+export const CANDIDATES_LOG_REL_PATH = AUDIT_LOG_REL_PATH;
+export { latestDecisions, readAuditLog } from "../actions/candidates-log.js";
 export const SUMMARY_HISTORY_REL_PATH = "vbrief/.eval/summary-history.jsonl";
 export const SUMMARY_HISTORY_SCHEMA = "deft.triage.summary.v1";
 export const EMPTY_CACHE_LINE = "[triage] cache empty -- run task triage:bootstrap";
@@ -83,62 +85,6 @@ export function iterCachedIssues(cacheRoot) {
     }
     return out;
 }
-export function readAuditLog(logPath) {
-    if (!existsSync(logPath)) {
-        return [];
-    }
-    let text;
-    try {
-        text = readFileSync(logPath, { encoding: "utf8" });
-    }
-    catch {
-        return [];
-    }
-    const out = [];
-    for (const raw of text.split("\n")) {
-        const stripped = raw.trim();
-        if (stripped.length === 0) {
-            continue;
-        }
-        try {
-            const obj = JSON.parse(stripped);
-            if (typeof obj === "object" && obj !== null && !Array.isArray(obj)) {
-                out.push(obj);
-            }
-        }
-        catch {
-            // tolerate malformed lines
-        }
-    }
-    return out;
-}
-/** Collapse audit-log entries to `{(repo, issue_number): decision}`. */
-export function latestDecisions(entries) {
-    const rows = [];
-    for (const entry of entries) {
-        const repo = entry.repo;
-        const issueNumber = entry.issue_number;
-        const decision = entry.decision;
-        const timestamp = entry.timestamp;
-        if (typeof repo !== "string" ||
-            typeof issueNumber !== "number" ||
-            !Number.isInteger(issueNumber) ||
-            typeof decision !== "string" ||
-            typeof timestamp !== "string") {
-            continue;
-        }
-        rows.push([timestamp, repo, issueNumber, decision]);
-    }
-    rows.sort((a, b) => a[0].localeCompare(b[0]));
-    const out = new Map();
-    for (const [_ts, repo, n, decision] of rows) {
-        out.set(`${repo}\0${n}`, decision);
-    }
-    return out;
-}
-function decisionKey(repo, issueNumber) {
-    return `${repo}\0${issueNumber}`;
-}
 // ---------------------------------------------------------------------------
 // vBRIEF counters
 // ---------------------------------------------------------------------------
@@ -206,6 +152,9 @@ export function isTriageScopeExplicitlyConfigured(projectRoot) {
 export function resolveWipCapInt(projectRoot) {
     return resolveWipCap(projectRoot).cap;
 }
+function decisionKey(repo, issueNumber) {
+    return `${repo}\0${issueNumber}`;
+}
 // ---------------------------------------------------------------------------
 // compute / format / persist
 // ---------------------------------------------------------------------------

package/dist/triage/summary/reconcilable.js

@@ -1,8 +1,9 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { AUDIT_LOG_REL_PATH, readAuditLog } from "../actions/candidates-log.js";
 /** Lifecycle folders scanned for reconcilable vBRIEFs (#1468). */
 export const BACKFILL_FOLDERS = ["proposed", "pending", "active"];
-export const CANDIDATES_LOG_REL_PATH = "vbrief/.eval/candidates.jsonl";
+export const CANDIDATES_LOG_REL_PATH = AUDIT_LOG_REL_PATH;
 function parseGithubIssueUri(uri) {
     if (typeof uri !== "string" || uri.length === 0) {
         return [null, null];
@@ -47,38 +48,8 @@ function extractIssueRef(data) {
 }
 function existingAuditRefs(auditPath) {
     const seen = new Set();
-    if (!existsSync(auditPath)) {
-        return seen;
-    }
-    let text;
-    try {
-        text = readFileSync(auditPath, { encoding: "utf8" });
-    }
-    catch {
-        return seen;
-    }
-    for (const raw of text.split("\n")) {
-        const stripped = raw.trim();
-        if (stripped.length === 0) {
-            continue;
-        }
-        try {
-            const entry = JSON.parse(stripped);
-            if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
-                continue;
-            }
-            const obj = entry;
-            const repo = obj.repo;
-            const issueNumber = obj.issue_number;
-            if (typeof repo === "string" &&
-                typeof issueNumber === "number" &&
-                Number.isInteger(issueNumber)) {
-                seen.add(`${repo}\0${issueNumber}`);
-            }
-        }
-        catch {
-            // tolerate malformed lines
-        }
+    for (const entry of readAuditLog(auditPath)) {
+        seen.add(auditKey(entry.repo, entry.issue_number));
     }
     return seen;
 }

package/dist/triage/welcome/default-mode.d.ts

@@ -15,6 +15,7 @@ export interface DefaultModeOptions {
     readonly output?: (line: string) => void;
     readonly writeHistory?: boolean;
     readonly taskPrefix?: string | null;
+    readonly selfHealFn?: (projectRoot: string) => void;
 }
 /** Non-interactive default mode (#1309). */
 export declare function runDefaultMode(projectRoot: string, options?: DefaultModeOptions): WelcomeOutcome;

package/dist/triage/welcome/default-mode.js

@@ -1,4 +1,5 @@
 import { resolve } from "node:path";
+import { maybeSelfHealCache } from "../../cache/fetch.js";
 import { FIRST_TIME_NUDGE, INCOMPLETE_NUDGE_TEMPLATE } from "./constants.js";
 import { classifyOnboarding, detectPriorState } from "./prior-state.js";
 import { emitOneliner } from "./summary.js";
@@ -29,6 +30,11 @@ export function runDefaultMode(projectRoot, options = {}) {
         exitCode: 0,
         bootstrapAction: null,
     };
+    const heal = options.selfHealFn ??
+        ((root) => {
+            maybeSelfHealCache(resolve(root));
+        });
+    heal(projectRoot);
     emitOneliner(projectRoot, {
         writeHistory: options.writeHistory !== false,
         output: out,

package/dist/vbrief-validate/project-definition.js

@@ -1,72 +1,9 @@
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { pyStrRepr } from "../triage/scope/python-repr.js";
-import { isRelativeTo, resolveRefPath, scopeIdsForRefUri } from "./paths.js";
+import { isRelativeTo, resolveRefPath } from "./paths.js";
 import { runProjectDefinitionHooks } from "./plan-hooks.js";
+import { formatRegistryStatusMismatch, registryStatusScopeUris } from "./registry-status.js";
 import { validateProjectDefNarratives } from "./schema.js";
-function itemLocalScopeUris(item, plan) {
-    const uris = [];
-    const metadata = item.metadata;
-    if (typeof metadata === "object" && metadata !== null && !Array.isArray(metadata)) {
-        const meta = metadata;
-        const sourcePath = meta.source_path;
-        if (typeof sourcePath === "string" && sourcePath) {
-            uris.push(sourcePath);
-        }
-        const metadataRefs = meta.references;
-        if (Array.isArray(metadataRefs)) {
-            for (const ref of metadataRefs) {
-                if (typeof ref === "object" &&
-                    ref !== null &&
-                    !Array.isArray(ref) &&
-                    ref.type === "x-vbrief/plan") {
-                    const uri = ref.uri;
-                    if (typeof uri === "string" && uri) {
-                        uris.push(uri);
-                    }
-                }
-            }
-        }
-    }
-    const refs = item.references;
-    if (Array.isArray(refs)) {
-        for (const ref of refs) {
-            if (typeof ref === "object" &&
-                ref !== null &&
-                !Array.isArray(ref) &&
-                ref.type === "x-vbrief/plan") {
-                const uri = ref.uri;
-                if (typeof uri === "string" && uri) {
-                    uris.push(uri);
-                }
-            }
-        }
-    }
-    const itemId = item.id;
-    const itemTitle = item.title;
-    const planRefs = plan.references;
-    if (Array.isArray(planRefs)) {
-        for (const ref of planRefs) {
-            if (typeof ref !== "object" || ref === null || Array.isArray(ref)) {
-                continue;
-            }
-            const refObj = ref;
-            if (refObj.type !== "x-vbrief/plan") {
-                continue;
-            }
-            const uri = refObj.uri;
-            if (typeof uri !== "string" || !uri) {
-                continue;
-            }
-            const titleMatches = typeof itemTitle === "string" && refObj.title === itemTitle;
-            const idMatches = typeof itemId === "string" && scopeIdsForRefUri(uri).has(itemId);
-            if (titleMatches || idMatches) {
-                uris.push(uri);
-            }
-        }
-    }
-    return [...new Set(uris)];
-}
 function validateProjectRegistryScopeStatus(item, itemIndex, plan, filepath, vbriefDir) {
     const errors = [];
     const itemStatus = item.status;
@@ -74,7 +11,7 @@ function validateProjectRegistryScopeStatus(item, itemIndex, plan, filepath, vbr
         return errors;
     }
     const resolvedRoot = resolve(vbriefDir);
-    for (const uri of itemLocalScopeUris(item, plan)) {
+    for (const uri of registryStatusScopeUris(item, plan)) {
         if (uri.startsWith("http://") || uri.startsWith("https://") || uri.startsWith("#")) {
             continue;
         }
@@ -98,9 +35,7 @@ function validateProjectRegistryScopeStatus(item, itemIndex, plan, filepath, vbr
         }
         const scopeStatus = scopePlan.status;
         if (typeof scopeStatus === "string" && scopeStatus !== itemStatus) {
-            errors.push(`${filepath}: items[${itemIndex}] status is ${pyStrRepr(itemStatus)} ` +
-                `but referenced scope '${uri}' has plan.status ${pyStrRepr(scopeStatus)} ` +
-                "(D3 registry-status)");
+            errors.push(formatRegistryStatusMismatch(filepath, itemIndex, itemStatus, uri, scopeStatus));
         }
     }
     return errors;

package/dist/vbrief-validate/registry-status.d.ts

@@ -0,0 +1,20 @@
+import type { JsonObject } from "./schema.js";
+export declare const REGISTRY_SCOPE_LINK_TYPE = "x-vbrief/plan";
+/** Derive the registry item status from a scope vBRIEF (render side). */
+export declare function deriveRegistryItemStatus(planStatus: unknown, lifecycleFolder: string): string;
+/**
+ * References copied onto a registry item from a scope vBRIEF.
+ *
+ * Scope-local ``x-vbrief/plan`` links (decompose children, epic forward refs)
+ * stay on the scope file only; copying them into PROJECT-DEFINITION item
+ * metadata makes D3 registry-status falsely compare the item row against
+ * mixed-status siblings (#1696).
+ */
+export declare function registryMetadataReferencesFromScope(references: unknown): unknown[];
+/**
+ * Local scope URIs whose ``plan.status`` must agree with the registry item
+ * status (D3). Shared by render output expectations and the validator.
+ */
+export declare function registryStatusScopeUris(item: JsonObject, plan: JsonObject): string[];
+export declare function formatRegistryStatusMismatch(filepath: string, itemIndex: number, itemStatus: string, uri: string, scopeStatus: string): string;
+//# sourceMappingURL=registry-status.d.ts.map

package/dist/vbrief-validate/registry-status.js

@@ -0,0 +1,85 @@
+import { scopeIdsForRefUri } from "./paths.js";
+export const REGISTRY_SCOPE_LINK_TYPE = "x-vbrief/plan";
+/** Derive the registry item status from a scope vBRIEF (render side). */
+export function deriveRegistryItemStatus(planStatus, lifecycleFolder) {
+    if (typeof planStatus === "string" && planStatus.length > 0) {
+        return planStatus;
+    }
+    return lifecycleFolder;
+}
+function isScopeLinkRef(ref) {
+    return (typeof ref === "object" &&
+        ref !== null &&
+        !Array.isArray(ref) &&
+        ref.type === REGISTRY_SCOPE_LINK_TYPE);
+}
+/**
+ * References copied onto a registry item from a scope vBRIEF.
+ *
+ * Scope-local ``x-vbrief/plan`` links (decompose children, epic forward refs)
+ * stay on the scope file only; copying them into PROJECT-DEFINITION item
+ * metadata makes D3 registry-status falsely compare the item row against
+ * mixed-status siblings (#1696).
+ */
+export function registryMetadataReferencesFromScope(references) {
+    if (!Array.isArray(references)) {
+        return [];
+    }
+    return references.filter((ref) => !isScopeLinkRef(ref));
+}
+function pushPlanScopeLink(uris, ref) {
+    if (!isScopeLinkRef(ref)) {
+        return;
+    }
+    const uri = ref.uri;
+    if (typeof uri === "string" && uri.length > 0) {
+        uris.push(uri);
+    }
+}
+/**
+ * Local scope URIs whose ``plan.status`` must agree with the registry item
+ * status (D3). Shared by render output expectations and the validator.
+ */
+export function registryStatusScopeUris(item, plan) {
+    const uris = [];
+    const metadata = item.metadata;
+    if (typeof metadata === "object" && metadata !== null && !Array.isArray(metadata)) {
+        const meta = metadata;
+        const sourcePath = meta.source_path;
+        if (typeof sourcePath === "string" && sourcePath.length > 0) {
+            uris.push(sourcePath);
+        }
+    }
+    const itemRefs = item.references;
+    if (Array.isArray(itemRefs)) {
+        for (const ref of itemRefs) {
+            pushPlanScopeLink(uris, ref);
+        }
+    }
+    const itemId = item.id;
+    const itemTitle = item.title;
+    const planRefs = plan.references;
+    if (Array.isArray(planRefs)) {
+        for (const ref of planRefs) {
+            if (!isScopeLinkRef(ref)) {
+                continue;
+            }
+            const uri = ref.uri;
+            if (typeof uri !== "string" || uri.length === 0) {
+                continue;
+            }
+            const titleMatches = typeof itemTitle === "string" && ref.title === itemTitle;
+            const idMatches = typeof itemId === "string" && scopeIdsForRefUri(uri).has(itemId);
+            if (titleMatches || idMatches) {
+                uris.push(uri);
+            }
+        }
+    }
+    return [...new Set(uris)];
+}
+export function formatRegistryStatusMismatch(filepath, itemIndex, itemStatus, uri, scopeStatus) {
+    return (`${filepath}: items[${itemIndex}] status is '${itemStatus}' ` +
+        `but referenced scope '${uri}' has plan.status '${scopeStatus}' ` +
+        "(D3 registry-status)");
+}
+//# sourceMappingURL=registry-status.js.map