@deftai/directive-core 0.78.0 → 0.79.1

package/dist/init-deposit/prettierignore.js

@@ -0,0 +1,83 @@
+/**
+ * Consumer `.prettierignore` upkeep for install and npm-managed update (#2534).
+ *
+ * Managed `.deft/core/` is outside the consumer Prettier format gate. Official
+ * install and `directive update` heal the ignore entry idempotently without
+ * reformatting the vendored deposit.
+ *
+ * Refs #2534, #670.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { assertProjectionContained } from "../fs/projection-containment.js";
+import { stripGitignoreInlineComment } from "../triage/bootstrap/gitignore.js";
+/** Directory ignore entry for the hybrid deposit. */
+export const PRETTIERIGNORE_DEFT_CORE_LINE = ".deft/core/";
+/** Alternate spellings that already cover the deposit ignore entry. */
+const DEFT_CORE_COVERING_LINES = new Set([".deft/core/", ".deft/core", ".deft/core/**"]);
+const DEFT_FRAMEWORK_PRETTIERIGNORE_HEADER = "# Deft framework: the vendored payload is outside the consumer Prettier gate (#2534).\n";
+function projectionTarget(projectDir) {
+    const target = join(projectDir, ".prettierignore");
+    assertProjectionContained(projectDir, target);
+    return target;
+}
+function prettierIgnoreCoversLine(present, line) {
+    if (present.has(line))
+        return true;
+    if (line === PRETTIERIGNORE_DEFT_CORE_LINE) {
+        return [...DEFT_CORE_COVERING_LINES].some((candidate) => present.has(candidate));
+    }
+    return false;
+}
+function collectPresentPrettierIgnoreLines(existing) {
+    const present = new Set();
+    for (const raw of existing.split("\n")) {
+        const stripped = stripGitignoreInlineComment(raw);
+        if (stripped)
+            present.add(stripped);
+    }
+    return present;
+}
+/**
+ * Ensure the consumer `.prettierignore` excludes managed `.deft/core/` from
+ * Prettier. Idempotent; preserves consumer preamble.
+ */
+export function ensurePrettierIgnoreLines(projectDir, io) {
+    const path = projectionTarget(projectDir);
+    let existing = "";
+    if (existsSync(path)) {
+        try {
+            existing = readFileSync(path, { encoding: "utf8" });
+        }
+        catch (cause) {
+            throw new Error(`could not read .prettierignore: ${String(cause)}`);
+        }
+    }
+    const present = collectPresentPrettierIgnoreLines(existing);
+    const targetLines = [PRETTIERIGNORE_DEFT_CORE_LINE];
+    const additions = targetLines.filter((line) => !prettierIgnoreCoversLine(present, line));
+    if (additions.length === 0) {
+        io.printf(".prettierignore already excludes the managed deft framework deposit — skipping.\n");
+        return { changed: false };
+    }
+    let body = existing;
+    if (body !== "" && !body.endsWith("\n")) {
+        body += "\n";
+    }
+    if (body !== "" && !body.endsWith("\n\n")) {
+        body += "\n";
+    }
+    body += DEFT_FRAMEWORK_PRETTIERIGNORE_HEADER;
+    for (const add of additions) {
+        body += `${add}\n`;
+    }
+    try {
+        writeFileSync(path, body, { encoding: "utf8", mode: 0o644 });
+    }
+    catch (cause) {
+        throw new Error(`could not write .prettierignore: ${String(cause)}`);
+    }
+    io.printf(`.prettierignore updated with Deft framework exclusions: ${additions.join(", ")}\n`);
+    return { changed: true };
+}
+//# sourceMappingURL=prettierignore.js.map

package/dist/init-deposit/refresh.d.ts

@@ -12,7 +12,7 @@ import { type ClassifySeams, type EngineInstallRunner, type EngineResolution, ty
 import { type GitLsFiles } from "./gitignore.js";
 import { type InitDepositArgs } from "./init-deposit.js";
 import { type LegacyLayoutDetection } from "./legacy-detect.js";
-import { type InitDepositIo } from "./scaffold.js";
+import { type GitHooksSeams, type InitDepositIo } from "./scaffold.js";
 export interface RefreshDepositArgs extends InitDepositArgs {
     readonly upgrade: boolean;
 }
@@ -45,6 +45,8 @@ export interface RefreshDepositSeams {
      * upkeep so the refresh never invokes a destructive `git rm --cached` path.
      */
     gitLsFiles?: GitLsFiles;
+    /** #2530: injected git config seams for {@link writeConsumerGitHooks}. */
+    gitHooks?: GitHooksSeams;
 }
 /**
  * The four states `directive update` classifies an EXISTING install into BEFORE

package/dist/init-deposit/refresh.js

@@ -8,7 +8,7 @@
  * Refs #1942, #1430, #1671.
  */
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, renameSync, statSync } from "node:fs";
 import { platform as osPlatform } from "node:os";
 import { join, resolve } from "node:path";
 import { assertDepositContained } from "../deposit/contain.js";
@@ -18,7 +18,6 @@ import { resolveInstalledContentRoot } from "../deposit/resolve-content.js";
 import { manifestTagToVersion, parseInstallManifest } from "../doctor/manifest.js";
 import { readCorePackageVersion } from "../engine-version.js";
 import { resolveLifecycleRoot } from "../layout/resolve.js";
-import { DEV_FALLBACK } from "../platform/constants.js";
 import { checkLocalEngineIntegrity, classify, ENGINE_PACKAGE, plan, renderGlobalInstall, resolveEngine, } from "../resolution/index.js";
 import { gitPorcelain } from "../story-ready/git.js";
 import { writeAgentHookDeposit } from "./agent-hooks.js";
@@ -27,7 +26,18 @@ import { depositStagePaths, isInstallerManagedPath, printCommitGuidance, pruneSt
 import { parseInitArgv } from "./init-deposit.js";
 import { buildLegacyRefusalJson, buildLegacyRefusalMessage, detectLegacyLayout, LEGACY_LAYOUT_REFUSED_EXIT_CODE, LegacyLayoutRefusedError, } from "./legacy-detect.js";
 import { printMigrateNudgeIfNeeded } from "./migrate.js";
-import { CANONICAL_INSTALL_ROOT, depositNeutralization, ensureTaskfile, writeAgentsMd, writeInstallManifest, } from "./scaffold.js";
+import { ensurePrettierIgnoreLines } from "./prettierignore.js";
+import { CANONICAL_INSTALL_ROOT, depositNeutralization, ensureTaskfile, writeAgentsMd, writeConsumerGitHooks, writeInstallManifest, } from "./scaffold.js";
+import { syncBareVersionMarker, syncConsumerXbriefSchemas, syncExistingBareVersionMarker, } from "./xbrief-projections.js";
+function hasCanonicalXbriefLifecycle(projectDir) {
+    try {
+        resolveLifecycleRoot(projectDir);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /** The exact refusal shown when `update` runs against an un-initialized project. */
 export const NOT_INITIALIZED_MESSAGE = "This project is not initialized. Run directive init.";
 /** `update` refused because the project has no install / needs a different verb. */
@@ -147,39 +157,6 @@ function readRecordedManagedBy(deftDir) {
         return null;
     }
 }
-/**
- * Regenerate the bare `.deft-version` derivative from the deposited content
- * version in the same transaction as the payload swap (#2055). The canonical
- * marker lives at `vbrief/.deft-version`; fall back to the project root only
- * when `vbrief/` is absent. Never persist the dev fallback.
- */
-function syncBareVersionMarker(projectDir, version) {
-    const normalized = normalizeVersion(version);
-    if (!normalized || normalized === DEV_FALLBACK)
-        return;
-    let vbriefDir = null;
-    try {
-        vbriefDir = resolveLifecycleRoot(projectDir);
-    }
-    catch {
-        // No xbrief/ layout present — write the root-level derivative instead.
-    }
-    let targetDir = projectDir;
-    try {
-        if (vbriefDir !== null && statSync(vbriefDir).isDirectory())
-            targetDir = vbriefDir;
-    }
-    catch {
-        // xbrief/ absent — write the root-level derivative instead
-    }
-    try {
-        mkdirSync(targetDir, { recursive: true });
-        writeFileSync(join(targetDir, ".deft-version"), `${normalized}\n`, "utf8");
-    }
-    catch {
-        // best-effort, mirrors install-upgrade marker write
-    }
-}
 /**
  * Retire a stale legacy `.deft/VERSION` after the canonical `.deft/core/VERSION`
  * has been (re)written (#2064). Folded in from the former `install-upgrade`
@@ -451,14 +428,25 @@ export async function runRefreshDeposit(args, io, seams = {}) {
         // .deft/core/VERSION has been rewritten (folded in from install-upgrade so no
         // manifest behavior is lost by the redirect). Best-effort; never fatal.
         migrateLegacyInstallManifest(projectDir, writtenManifestPath);
-        // #2055: regenerate the bare .deft-version derivative so it agrees with the
-        // freshly written manifest tag (otherwise doctor's manifest-agreement check
-        // fails and the operator must hand-edit the marker). No-op refreshes skip
-        // this projection because the manifest tag was not rewritten (#2118).
+    }
+    // #2595: payload freshness and consumer derivative freshness are independent.
+    // Always repair these cheap projections, including on the #2118 no-op path.
+    if (alreadyCurrent) {
+        syncExistingBareVersionMarker(projectDir, contentVersion);
+    }
+    else {
         syncBareVersionMarker(projectDir, contentVersion);
     }
+    // Do not turn a legacy-only or cache-only support tree into canonical
+    // lifecycle content before migrate:xbrief can transactionally converge it.
+    if (hasCanonicalXbriefLifecycle(projectDir)) {
+        syncConsumerXbriefSchemas(projectDir, deftDir);
+    }
     const agentsMdUpdated = writeAgentsMd(projectDir, deftDir, io);
     writeAgentHookDeposit(projectDir, io);
+    // #2530: root `.githooks/` is a consumer derivative like #2595 marker/schemas —
+    // repair on every refresh, including the already-current no-op path.
+    writeConsumerGitHooks(projectDir, deftDir, io, seams.gitHooks);
     // #2148: the deft-core-guard CI workflow is only meaningful when the deposit
     // is git-tracked (committed vendor layout). On an npm-managed (gitignored)
     // deposit it creates untracked noise after every `directive update`. Probe
@@ -472,6 +460,7 @@ export async function runRefreshDeposit(args, io, seams = {}) {
     // destructive `git rm --cached .deft/core` un-track is the deliberate
     // `migrate --untrack-core` step (#2269), not `update`.
     ensureInitGitignoreLines(projectDir, io, { gitLsFiles: seams.gitLsFiles });
+    ensurePrettierIgnoreLines(projectDir, io);
     let taskfileWired = false;
     if (args.nonInteractive) {
         taskfileWired = ensureTaskfile(projectDir, io);

package/dist/init-deposit/scaffold.js

@@ -9,12 +9,12 @@ import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, statSync,
 import { mkdir, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { platform } from "node:os";
 import { dirname, join, relative } from "node:path";
-import { copyTree } from "../deposit/copy-tree.js";
 import { assertProjectionContained, ProjectionContainmentError, } from "../fs/projection-containment.js";
 import { agentsRefreshPlan } from "../platform/agents-md.js";
 import { MIGRATED_ARTIFACT_DIR } from "../xbrief-migrate/constants.js";
 import { CANONICAL_INSTALL_ROOT } from "./constants.js";
 import { installerManagedGuardEre } from "./hygiene.js";
+import { syncConsumerXbriefSchemas } from "./xbrief-projections.js";
 export { CANONICAL_INSTALL_ROOT };
 export const CORE_GLOB = ".deft/core/**";
 /** Refuse init/update projection writes that escape via repo-controlled symlinks (#2446). */
@@ -336,20 +336,14 @@ export async function writeConsumerVbrief(projectDir, deftDir, io) {
     const schemasPresent = existsSync(schemasDst) && statSync(schemasDst).isDirectory();
     const vbriefMdPresent = existsSync(vbriefMdDst) && statSync(vbriefMdDst).isFile();
     const lifecyclePresent = vbriefLifecycleDirsPresent(consumerVbrief);
+    const schemasChanged = syncConsumerXbriefSchemas(projectDir, deftDir);
     if (schemasPresent && vbriefMdPresent && lifecyclePresent) {
-        io.printf("vbrief/ already present at project root — skipping.\n");
-        return false;
+        io.printf(schemasChanged
+            ? "vbrief/ schemas refreshed at project root.\n"
+            : "vbrief/ already present at project root — skipping.\n");
+        return schemasChanged;
     }
     mkdirSync(consumerVbrief, { recursive: true });
-    if (!schemasPresent) {
-        const fwSchemas = join(deftDir, "vbrief", "schemas");
-        if (existsSync(fwSchemas) && statSync(fwSchemas).isDirectory()) {
-            await copyTree(fwSchemas, schemasDst);
-        }
-        else {
-            mkdirSync(schemasDst, { recursive: true });
-        }
-    }
     if (!vbriefMdPresent) {
         const fwVbriefMd = join(deftDir, "vbrief", "vbrief.md");
         if (existsSync(fwVbriefMd)) {

package/dist/init-deposit/xbrief-projections.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Idempotent consumer xBRIEF derivatives maintained by init/update (#2595).
+ *
+ * The framework payload manifest and consumer projections have independent
+ * freshness. A current `.deft/core/VERSION` therefore cannot short-circuit
+ * these repairs.
+ */
+/**
+ * Synchronize framework-owned xBRIEF schemas while preserving unknown consumer
+ * files. The obsolete v0.6 root schema is the only destination-only file this
+ * repair removes.
+ */
+export declare function syncConsumerXbriefSchemas(projectDir: string, deftDir: string): boolean;
+/** Regenerate the bare consumer version derivative, retaining the historical root fallback. */
+export declare function syncBareVersionMarker(projectDir: string, version: string): boolean;
+/** Repair an existing marker without creating root state when no lifecycle artifact exists. */
+export declare function syncExistingBareVersionMarker(projectDir: string, version: string): boolean;
+//# sourceMappingURL=xbrief-projections.d.ts.map

package/dist/init-deposit/xbrief-projections.js

@@ -0,0 +1,117 @@
+/**
+ * Idempotent consumer xBRIEF derivatives maintained by init/update (#2595).
+ *
+ * The framework payload manifest and consumer projections have independent
+ * freshness. A current `.deft/core/VERSION` therefore cannot short-circuit
+ * these repairs.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { join, relative } from "node:path";
+import { assertProjectionContained } from "../fs/projection-containment.js";
+import { resolveLifecycleRoot } from "../layout/resolve.js";
+import { DEV_FALLBACK } from "../platform/constants.js";
+import { MIGRATED_ARTIFACT_DIR } from "../xbrief-migrate/constants.js";
+const OBSOLETE_CORE_SCHEMA = "vbrief-core.schema.json";
+const CURRENT_CORE_SCHEMA = "xbrief-core-0.8.schema.json";
+function normalizeVersion(version) {
+    return version.trim().replace(/^v/, "");
+}
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function collectSchemaFiles(root, dir = root, files = []) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isSymbolicLink()) {
+            throw new Error(`refusing xbrief schema projection from symlink: ${full}`);
+        }
+        if (entry.isDirectory()) {
+            collectSchemaFiles(root, full, files);
+        }
+        else if (entry.isFile()) {
+            files.push(relative(root, full));
+        }
+    }
+    return files;
+}
+function writeFileIfChanged(projectDir, target, content) {
+    assertProjectionContained(projectDir, target);
+    const desired = Buffer.isBuffer(content) ? content : Buffer.from(content, "utf8");
+    try {
+        if (readFileSync(target).equals(desired))
+            return false;
+    }
+    catch {
+        // Missing or unreadable target is replaced below.
+    }
+    mkdirSync(join(target, ".."), { recursive: true });
+    writeFileSync(target, desired);
+    return true;
+}
+/**
+ * Synchronize framework-owned xBRIEF schemas while preserving unknown consumer
+ * files. The obsolete v0.6 root schema is the only destination-only file this
+ * repair removes.
+ */
+export function syncConsumerXbriefSchemas(projectDir, deftDir) {
+    const sourceDir = join(deftDir, "vbrief", "schemas");
+    const currentSource = join(sourceDir, CURRENT_CORE_SCHEMA);
+    if (!isDirectory(sourceDir) || !existsSync(currentSource) || !statSync(currentSource).isFile()) {
+        throw new Error(`cannot project xbrief schemas: framework payload is missing ${CURRENT_CORE_SCHEMA}`);
+    }
+    const destinationDir = join(projectDir, MIGRATED_ARTIFACT_DIR, "schemas");
+    assertProjectionContained(projectDir, destinationDir);
+    mkdirSync(destinationDir, { recursive: true });
+    let changed = false;
+    for (const rel of collectSchemaFiles(sourceDir)) {
+        if (rel === OBSOLETE_CORE_SCHEMA)
+            continue;
+        const source = join(sourceDir, rel);
+        const destination = join(destinationDir, rel);
+        changed = writeFileIfChanged(projectDir, destination, readFileSync(source)) || changed;
+    }
+    const obsoleteDestination = join(destinationDir, OBSOLETE_CORE_SCHEMA);
+    assertProjectionContained(projectDir, obsoleteDestination);
+    if (existsSync(obsoleteDestination)) {
+        rmSync(obsoleteDestination, { force: true });
+        changed = true;
+    }
+    return changed;
+}
+function syncBareVersionMarkerWithPolicy(projectDir, version, allowRootFallback) {
+    const normalized = normalizeVersion(version);
+    if (!normalized || normalized === DEV_FALLBACK)
+        return false;
+    const canonicalRoot = join(projectDir, MIGRATED_ARTIFACT_DIR);
+    if (existsSync(canonicalRoot)) {
+        assertProjectionContained(projectDir, join(canonicalRoot, ".deft-version"));
+    }
+    let targetDir = projectDir;
+    try {
+        targetDir = resolveLifecycleRoot(projectDir);
+    }
+    catch {
+        // Preserve the historical root fallback for payload-changing refreshes,
+        // and repair an existing fallback on no-op refreshes without creating new
+        // untracked state (#2118 / #2595).
+        const rootMarker = join(projectDir, ".deft-version");
+        if (!allowRootFallback && !existsSync(rootMarker))
+            return false;
+    }
+    const target = join(targetDir, ".deft-version");
+    return writeFileIfChanged(projectDir, target, `${normalized}\n`);
+}
+/** Regenerate the bare consumer version derivative, retaining the historical root fallback. */
+export function syncBareVersionMarker(projectDir, version) {
+    return syncBareVersionMarkerWithPolicy(projectDir, version, true);
+}
+/** Repair an existing marker without creating root state when no lifecycle artifact exists. */
+export function syncExistingBareVersionMarker(projectDir, version) {
+    return syncBareVersionMarkerWithPolicy(projectDir, version, false);
+}
+//# sourceMappingURL=xbrief-projections.js.map

package/dist/intake/reconcile-issues.d.ts

@@ -30,10 +30,15 @@ export interface FetchIssueStatesOptions extends FetchIssuesOptions {
     readonly batchSize?: number;
 }
 export declare function fetchIssueStates(repo: string, issueNumbers: ReadonlySet<number>, options?: FetchIssueStatesOptions): Map<number, IssueState> | null;
+export interface CompletedStatusDriftEntry {
+    readonly rel_path: string;
+    readonly status: string;
+}
 export interface ReconcileReport {
     linked: Record<string, unknown>[];
     no_open_issue: Record<string, unknown>[];
     unlinked?: Record<string, unknown>[];
+    completed_status_drift?: CompletedStatusDriftEntry[];
     summary: Record<string, number>;
 }
 export declare function reconcile(issueToVbriefs: Map<number, string[]>, issueStateMap: Map<number, IssueState | string>): ReconcileReport;
@@ -43,10 +48,15 @@ export declare function parseParentIssue(data: Record<string, unknown>): number
 export declare function parseDecompositionOrigin(data: Record<string, unknown>): number | null;
 export declare function resolveLifecycleAnchor(data: Record<string, unknown>): [number | null, string];
 export declare function scanLifecycleAnchors(vbriefDir: string): Record<string, unknown>[];
+/** Scan completed/ for xBRIEFs whose plan.status is not terminal (D2 drift, #2578). */
+export declare function scanCompletedStatusDrift(vbriefDir: string): CompletedStatusDriftEntry[];
+export declare function attachCompletedStatusDrift(report: ReconcileReport, drift: CompletedStatusDriftEntry[]): ReconcileReport;
 export declare function buildLifecycleReport(anchors: Record<string, unknown>[], issueStateMap: Map<number, IssueState | string>, log?: boolean): ReconcileReport;
 export declare function formatJson(report: ReconcileReport): string;
 export declare function formatMarkdown(report: ReconcileReport): string;
 export declare function applyLifecycleFixes(vbriefDir: string, report: ReconcileReport, projectRoot?: string | null): [number, number, string[]];
+/** Repair completed/ files whose plan.status is not terminal (#2578). */
+export declare function repairCompletedStatusDrift(vbriefDir: string, drift: readonly CompletedStatusDriftEntry[]): [number, number, string[]];
 export declare function detectRepo(): string | null;
 export interface ReconcileCliArgs {
     vbriefDir?: string;

package/dist/intake/reconcile-issues.js

@@ -6,6 +6,7 @@ import { call } from "../scm/call.js";
 import { updateDecomposedChildBackReferences } from "../scope/decomposed-refs.js";
 import { resolveProjectRoot } from "../scope/project-context.js";
 import { resolveProjectRepo } from "../slice/project-context.js";
+import { FOLDER_ALLOWED_STATUSES } from "../vbrief-validate/constants.js";
 import { LEGACY_INFO_ROOT_KEY, MIGRATED_INFO_ROOT_KEY } from "../xbrief-migrate/constants.js";
 export const LIFECYCLE_FOLDERS = [
     "proposed",
@@ -435,6 +436,52 @@ export function scanLifecycleAnchors(vbriefDir) {
     }
     return anchors;
 }
+const COMPLETED_TERMINAL_STATUSES = FOLDER_ALLOWED_STATUSES.completed ?? new Set(["completed", "failed"]);
+/** Scan completed/ for xBRIEFs whose plan.status is not terminal (D2 drift, #2578). */
+export function scanCompletedStatusDrift(vbriefDir) {
+    const completedDir = join(vbriefDir, "completed");
+    const drift = [];
+    try {
+        if (!statSync(completedDir).isDirectory()) {
+            return drift;
+        }
+    }
+    catch {
+        return drift;
+    }
+    for (const filename of readdirSync(completedDir)
+        .filter((f) => hasArtifactSuffix(f))
+        .sort()) {
+        const relPath = `completed/${filename}`;
+        let data;
+        try {
+            data = JSON.parse(readFileSync(join(completedDir, filename), "utf8"));
+        }
+        catch {
+            continue;
+        }
+        const plan = data.plan;
+        if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+            continue;
+        }
+        const status = String(plan.status ?? "");
+        if (status.length === 0 || COMPLETED_TERMINAL_STATUSES.has(status)) {
+            continue;
+        }
+        drift.push({ rel_path: relPath, status });
+    }
+    return drift;
+}
+export function attachCompletedStatusDrift(report, drift) {
+    return {
+        ...report,
+        completed_status_drift: drift,
+        summary: {
+            ...report.summary,
+            completed_status_drift_count: drift.length,
+        },
+    };
+}
 export function buildLifecycleReport(anchors, issueStateMap, log = true) {
     const linked = [];
     const noOpenIssue = [];
@@ -527,6 +574,18 @@ export function formatMarkdown(report) {
         lines.push("None.");
     }
     lines.push("");
+    lines.push("## (d) completed/ xBRIEFs with non-terminal plan.status (D2 drift)", "");
+    const drift = report.completed_status_drift ?? [];
+    if (drift.length > 0) {
+        for (const entry of drift) {
+            const safeStatus = entry.status.replace(/\r?\n/g, " ");
+            lines.push(`- \`${entry.rel_path}\` -- plan.status='${safeStatus}'`);
+        }
+    }
+    else {
+        lines.push("None.");
+    }
+    lines.push("");
     return lines.join("\n");
 }
 function utcNowIso() {
@@ -625,7 +684,12 @@ export function applyLifecycleFixes(vbriefDir, report, projectRoot = null) {
         mkdirSync(join(vbriefDir, destFolder), { recursive: true });
         try {
             statSync(dst);
-            failures.push(`target already exists in ${destFolder}/: ${filename}`);
+            // Destination already holds this basename (#2622). Treat as already-terminal
+            // and continue the sweep. Do not unlink the source — a same-basename collision
+            // can be a non-identical artifact; leave removal to the operator / git.
+            process.stderr.write(`reconcile: skipped ${relPath} — already present in ${destFolder}/ (#2622); ` +
+                "left source in place for manual cleanup\n");
+            skipped += 1;
             continue;
         }
         catch {
@@ -663,6 +727,54 @@ export function applyLifecycleFixes(vbriefDir, report, projectRoot = null) {
     }
     return [moved, skipped, failures];
 }
+/** Repair completed/ files whose plan.status is not terminal (#2578). */
+export function repairCompletedStatusDrift(vbriefDir, drift) {
+    let repaired = 0;
+    let skipped = 0;
+    const failures = [];
+    const completedDir = join(vbriefDir, "completed");
+    for (const entry of drift) {
+        const slash = entry.rel_path.indexOf("/");
+        if (slash < 0) {
+            failures.push(`unexpected vBRIEF path shape (no folder): ${JSON.stringify(entry.rel_path)}`);
+            continue;
+        }
+        const filename = entry.rel_path.slice(slash + 1);
+        const src = join(completedDir, filename);
+        let data;
+        try {
+            data = JSON.parse(readFileSync(src, "utf8"));
+        }
+        catch (exc) {
+            failures.push(`failed to parse ${entry.rel_path}: ${String(exc)}`);
+            continue;
+        }
+        const plan = (data.plan ?? {});
+        data.plan = plan;
+        const currentStatus = String(plan.status ?? "");
+        if (COMPLETED_TERMINAL_STATUSES.has(currentStatus)) {
+            skipped += 1;
+            continue;
+        }
+        const stamp = utcNowIso();
+        plan.status = "completed";
+        plan.updated = stamp;
+        const infoKey = MIGRATED_INFO_ROOT_KEY in data ? MIGRATED_INFO_ROOT_KEY : LEGACY_INFO_ROOT_KEY;
+        const info = (data[infoKey] ?? {});
+        data[infoKey] = info;
+        info.updated = stamp;
+        propagateItemStatus(plan.items, "completed", stamp);
+        try {
+            writeFileSync(src, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+        }
+        catch (exc) {
+            failures.push(`failed to write ${entry.rel_path}: ${String(exc)}`);
+            continue;
+        }
+        repaired += 1;
+    }
+    return [repaired, skipped, failures];
+}
 export function detectRepo() {
     try {
         const stdout = execFileSync("git", ["remote", "get-url", "origin"], {
@@ -744,6 +856,8 @@ export function reconcileMain(args) {
         report = reconcile(issueToVbriefsObj, issueStateMap);
     }
     const fmt = args.format ?? "markdown";
+    const completedDrift = scanCompletedStatusDrift(vbriefDir);
+    report = attachCompletedStatusDrift(report, completedDrift);
     if (fmt === "json") {
         process.stdout.write(formatJson(report));
     }
@@ -761,11 +875,15 @@ export function reconcileMain(args) {
             return acc;
         }, 0);
         const [moved, skipped, failures] = applyLifecycleFixes(vbriefDir, applyReport, projectRoot);
+        const driftAfterMove = scanCompletedStatusDrift(vbriefDir);
+        const [driftRepaired, driftSkipped, driftFailures] = repairCompletedStatusDrift(vbriefDir, driftAfterMove);
+        const allFailures = [...failures, ...driftFailures];
         process.stderr.write(`[${moved}/${candidates}] vBRIEFs reconciled (moved=${moved}, already-terminal=${skipped}, failures=${failures.length})\n`);
-        for (const f of failures) {
+        process.stderr.write(`[${driftRepaired}/${completedDrift.length}] completed/ status drift repaired (repaired=${driftRepaired}, already-terminal=${driftSkipped}, failures=${driftFailures.length})\n`);
+        for (const f of allFailures) {
             process.stderr.write(`  -- FAIL: ${f}\n`);
         }
-        if (failures.length > 0) {
+        if (allFailures.length > 0) {
             return 1;
         }
     }

package/dist/issue-sync/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./sync-from-xbrief.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/issue-sync/index.js

@@ -0,0 +1,2 @@
+export * from "./sync-from-xbrief.js";
+//# sourceMappingURL=index.js.map

package/dist/issue-sync/sync-from-xbrief-cli.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+export interface ParsedSyncFromXbriefCliArgs {
+    path?: string;
+    dryRun?: boolean;
+    projectRoot?: string;
+    repo?: string;
+    error?: string;
+}
+export declare function parseArgs(argv: readonly string[]): ParsedSyncFromXbriefCliArgs;
+export declare function mainEntry(argv?: string[]): number;
+//# sourceMappingURL=sync-from-xbrief-cli.d.ts.map

package/dist/issue-sync/sync-from-xbrief-cli.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import { fileURLToPath } from "node:url";
+import { syncFromXbriefMain } from "./sync-from-xbrief.js";
+export function parseArgs(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--dry-run") {
+            out.dryRun = true;
+        }
+        else if (arg === "--project-root") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...out, error: "argument --project-root: expected one argument" };
+            }
+            out.projectRoot = value;
+            i += 1;
+        }
+        else if (arg === "--repo") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...out, error: "argument --repo: expected one argument" };
+            }
+            out.repo = value;
+            i += 1;
+        }
+        else if (!arg.startsWith("-")) {
+            out.path = arg;
+        }
+    }
+    return out;
+}
+export function mainEntry(argv = process.argv.slice(2)) {
+    const args = parseArgs(argv);
+    if (args.error !== undefined) {
+        process.stderr.write(`issue:sync-from-xbrief: ${args.error}\n`);
+        return 2;
+    }
+    return syncFromXbriefMain(args);
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(mainEntry());
+}
+//# sourceMappingURL=sync-from-xbrief-cli.js.map