@deftai/directive-core 0.104.0 → 0.106.0

package/dist/triage/welcome/writers.js

@@ -4,6 +4,7 @@ import { containedWrite } from "../../fs/contained-write.js";
 import { assertWriteTargetSafe } from "../../fs/projection-containment.js";
 import { hasArtifactSuffix, resolveLifecycleFolder, resolveProjectDefinitionPath, } from "../../layout/resolve.js";
 import { migrateLegacyPolicyKey, PLAN_ONBOARDING_KEY, PLAN_POLICY_KEY, } from "../../policy/plan-extensions.js";
+import { stampChangedToken } from "../../policy/resolve.js";
 import { projectDefinitionMutationLock } from "../../vbrief-build/project-definition-io.js";
 import { AUDIT_LOG_REL_PATH, DEFAULT_RELIEF_AGE_DAYS, DEFAULT_WIP_CAP, SUBSCRIPTION_PRESETS, WELCOME_AUDIT_TAG, } from "./constants.js";
 function projectDefinitionPath(projectRoot) {
@@ -12,9 +13,13 @@ function projectDefinitionPath(projectRoot) {
 function utcIso() {
     return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 }
-export function appendAuditEntry(projectRoot, entry) {
+export function appendAuditEntry(projectRoot, entry, changed = true) {
     const root = resolve(projectRoot);
     const logPath = join(root, AUDIT_LOG_REL_PATH);
+    const stamped = stampChangedToken(entry, changed);
+    if (!changed) {
+        return logPath;
+    }
     // #2980 wave D: product write sink routes through containedWrite.
     mkdirSync(root, { recursive: true });
     if (!existsSync(logPath)) {
@@ -28,7 +33,7 @@ export function appendAuditEntry(projectRoot, entry) {
     containedWrite({
         root,
         target: AUDIT_LOG_REL_PATH,
-        data: `${utcIso()} ${entry}\n`,
+        data: `${utcIso()} ${stamped}\n`,
         mode: "append",
     });
     return logPath;
@@ -102,7 +107,7 @@ export function writeTriageScope(projectRoot, rules, options = { presetLabel: "c
             `rule_count=${rules.length}`,
             `changed=${changed ? "true" : "false"}`,
         ].join(" ");
-        appendAuditEntry(projectRoot, auditEntry);
+        appendAuditEntry(projectRoot, auditEntry, changed);
         return [changed, auditEntry];
     });
 }
@@ -153,7 +158,7 @@ export function writeWipCapDecision(projectRoot, options = {}) {
             `acceptedDefault=${acceptedDefault ? "true" : "false"}`,
             `changed=${changed ? "true" : "false"}`,
         ].join(" ");
-        appendAuditEntry(projectRoot, auditEntry);
+        appendAuditEntry(projectRoot, auditEntry, changed);
         return [changed, auditEntry];
     });
 }
@@ -220,7 +225,7 @@ export function writeWipCap(projectRoot, wipCap, options = {}) {
         const changed = previous !== wipCap;
         const auditEntry = `actor=${actor} field=plan.policy.wipCap value=${wipCap} previous=${JSON.stringify(previous)} ` +
             `changed=${changed ? "true" : "false"}`;
-        appendAuditEntry(projectRoot, auditEntry);
+        appendAuditEntry(projectRoot, auditEntry, changed);
         return [changed, auditEntry];
     });
 }

package/dist/ts-check-lane/index.d.ts

@@ -1,3 +1,6 @@
+export type { ProgressLineSink, ProgressTick, WriteFlushedLineOptions, } from "./progress.js";
+export { buildTestLaneCommand, formatProgressLine, nextProgressTick, PROGRESS_BAND_PERCENT, PROGRESS_REPORTER_RELATIVE_PATH, PROGRESS_UNIT, resolveTestLaneCommand, writeFlushedLine, } from "./progress.js";
+export { TsCheckLaneProgressReporter } from "./progress-reporter.js";
 export type { LaneRunner, ResolvePnpmOptions, RunnerResult, RunTsLaneOptions } from "./run-lane.js";
 export { LANE_COMMANDS, resolvePnpm, runTsLane, SKIP_NOTICE, sanitizeTsLaneEnv, } from "./run-lane.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/ts-check-lane/index.js

@@ -1,2 +1,4 @@
+export { buildTestLaneCommand, formatProgressLine, nextProgressTick, PROGRESS_BAND_PERCENT, PROGRESS_REPORTER_RELATIVE_PATH, PROGRESS_UNIT, resolveTestLaneCommand, writeFlushedLine, } from "./progress.js";
+export { TsCheckLaneProgressReporter } from "./progress-reporter.js";
 export { LANE_COMMANDS, resolvePnpm, runTsLane, SKIP_NOTICE, sanitizeTsLaneEnv, } from "./run-lane.js";
 //# sourceMappingURL=index.js.map

package/dist/ts-check-lane/progress-reporter.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Vitest reporter that emits coarse flushed progress for ts:check-lane (#3470).
+ *
+ * Wired from the lane via `--reporter` so vitest.config.ts stays unchanged.
+ * Does not print test names and does not change pass/fail.
+ */
+export declare class TsCheckLaneProgressReporter {
+    private total;
+    private completed;
+    private lastEmittedPercent;
+    private readonly sink?;
+    constructor(sink?: unknown);
+    onTestRunStart(specifications?: ReadonlyArray<unknown>): void;
+    onTestModuleEnd(): void;
+}
+export default TsCheckLaneProgressReporter;
+//# sourceMappingURL=progress-reporter.d.ts.map

package/dist/ts-check-lane/progress-reporter.js

@@ -0,0 +1,38 @@
+/**
+ * Vitest reporter that emits coarse flushed progress for ts:check-lane (#3470).
+ *
+ * Wired from the lane via `--reporter` so vitest.config.ts stays unchanged.
+ * Does not print test names and does not change pass/fail.
+ */
+import { formatProgressLine, nextProgressTick, writeFlushedLine, } from "./progress.js";
+function isLineSink(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.write === "function");
+}
+export class TsCheckLaneProgressReporter {
+    total = 0;
+    completed = 0;
+    lastEmittedPercent = 0;
+    sink;
+    constructor(sink) {
+        // Vitest constructs reporters with its options object; only tests pass a sink.
+        this.sink = isLineSink(sink) ? sink : undefined;
+    }
+    onTestRunStart(specifications = []) {
+        this.total = specifications.length;
+        this.completed = 0;
+        this.lastEmittedPercent = 0;
+    }
+    onTestModuleEnd() {
+        this.completed += 1;
+        const tick = nextProgressTick(this.completed, this.total, this.lastEmittedPercent);
+        if (tick === null) {
+            return;
+        }
+        this.lastEmittedPercent = tick.percent;
+        writeFlushedLine(formatProgressLine(tick), this.sink);
+    }
+}
+export default TsCheckLaneProgressReporter;
+//# sourceMappingURL=progress-reporter.js.map

package/dist/ts-check-lane/progress.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Coarse percent/count ticks for ts:check-lane (#3470).
+ *
+ * Band math is independent of vitest so tests can cover cadence and flush
+ * without running the suite.
+ */
+/** Relative to the repo root; wired onto `pnpm run test` from the lane. */
+export declare const PROGRESS_REPORTER_RELATIVE_PATH = "packages/core/src/ts-check-lane/progress-reporter.ts";
+/** One line every 20% of known files -- coarse enough for a log snapshot. */
+export declare const PROGRESS_BAND_PERCENT = 20;
+export declare const PROGRESS_UNIT = "files";
+export interface ProgressTick {
+    readonly percent: number;
+    readonly completed: number;
+    readonly total: number;
+}
+export interface ProgressLineSink {
+    write(chunk: string): void;
+    flush?: () => void;
+}
+export declare function nextProgressTick(completed: number, total: number, lastEmittedPercent: number, bandPercent?: number): ProgressTick | null;
+export declare function formatProgressLine(tick: ProgressTick, unit?: string): string;
+export interface WriteFlushedLineOptions {
+    readonly fd?: number;
+    readonly syncWrite?: (fd: number, payload: string) => void;
+}
+/** writeSync so a non-TTY capture sees each tick immediately (#1353). */
+export declare function writeFlushedLine(line: string, sink?: ProgressLineSink, options?: WriteFlushedLineOptions): void;
+export declare function buildTestLaneCommand(reporterPath?: string): readonly string[];
+/** Attach the reporter only when the source file is present (framework checkout). */
+export declare function resolveTestLaneCommand(projectRoot: string, exists?: (path: string) => boolean): readonly string[];
+//# sourceMappingURL=progress.d.ts.map

package/dist/ts-check-lane/progress.js

@@ -0,0 +1,57 @@
+/**
+ * Coarse percent/count ticks for ts:check-lane (#3470).
+ *
+ * Band math is independent of vitest so tests can cover cadence and flush
+ * without running the suite.
+ */
+import { existsSync, writeSync } from "node:fs";
+import { join } from "node:path";
+/** Relative to the repo root; wired onto `pnpm run test` from the lane. */
+export const PROGRESS_REPORTER_RELATIVE_PATH = "packages/core/src/ts-check-lane/progress-reporter.ts";
+/** One line every 20% of known files -- coarse enough for a log snapshot. */
+export const PROGRESS_BAND_PERCENT = 20;
+export const PROGRESS_UNIT = "files";
+export function nextProgressTick(completed, total, lastEmittedPercent, bandPercent = PROGRESS_BAND_PERCENT) {
+    if (!Number.isFinite(completed) ||
+        !Number.isFinite(total) ||
+        !Number.isFinite(lastEmittedPercent)) {
+        return null;
+    }
+    if (total <= 0 || completed <= 0 || bandPercent <= 0) {
+        return null;
+    }
+    const raw = Math.min(100, Math.floor((completed / total) * 100));
+    const band = Math.floor(raw / bandPercent) * bandPercent;
+    if (band < bandPercent || band <= lastEmittedPercent) {
+        return null;
+    }
+    return { percent: band, completed, total };
+}
+export function formatProgressLine(tick, unit = PROGRESS_UNIT) {
+    return `ts:check-lane ${tick.percent}% (${tick.completed}/${tick.total} ${unit})`;
+}
+/** writeSync so a non-TTY capture sees each tick immediately (#1353). */
+export function writeFlushedLine(line, sink, options = {}) {
+    const payload = line.endsWith("\n") ? line : `${line}\n`;
+    if (sink !== undefined && typeof sink.write === "function") {
+        sink.write(payload);
+        sink.flush?.();
+        return;
+    }
+    const syncWrite = options.syncWrite ?? writeSync;
+    syncWrite(options.fd ?? 1, payload);
+}
+export function buildTestLaneCommand(reporterPath = PROGRESS_REPORTER_RELATIVE_PATH) {
+    // Do not insert a standalone "--": pnpm forwards it to vitest, which then
+    // treats later --reporter flags as file filters (#3470).
+    return ["run", "test", "--reporter", reporterPath, "--reporter", "default"];
+}
+/** Attach the reporter only when the source file is present (framework checkout). */
+export function resolveTestLaneCommand(projectRoot, exists = existsSync) {
+    const reporterAbs = join(projectRoot, ...PROGRESS_REPORTER_RELATIVE_PATH.split("/"));
+    if (!exists(reporterAbs)) {
+        return ["run", "test"];
+    }
+    return buildTestLaneCommand();
+}
+//# sourceMappingURL=progress.js.map

package/dist/ts-check-lane/run-lane.d.ts

@@ -20,7 +20,7 @@
  * Run order is deliberate: lint (cheapest, catches the biome class first),
  * then build, then the test suite.
  */
-export declare const LANE_COMMANDS: ReadonlyArray<readonly [string, string]>;
+export declare const LANE_COMMANDS: ReadonlyArray<readonly string[]>;
 export declare const SKIP_NOTICE: string;
 /** Result of a single lane command invocation. Mirrors a subset of SpawnSyncReturns. */
 export interface RunnerResult {
@@ -46,6 +46,8 @@ export interface RunTsLaneOptions {
      * DEFT_RELEASE_PREFLIGHT (#2618). Defaults to process.env.
      */
     readonly env?: NodeJS.ProcessEnv;
+    /** Injected reporter-file probe (defaults to existsSync). */
+    readonly reporterExists?: (path: string) => boolean;
 }
 /** Windows command shims (.cmd/.bat) need a shell; native executables do not. */
 export declare function shouldUseShellForCommand(command: string, platform?: NodeJS.Platform): boolean;

package/dist/ts-check-lane/run-lane.js

@@ -21,6 +21,7 @@ import { existsSync } from "node:fs";
 import { posix, win32 } from "node:path";
 import { BRANCH_GATE_BYPASS_ENV, RELEASE_PREFLIGHT_ENV } from "../release/constants.js";
 import { resolveCoverageDebtIssue } from "../vitest-runner/coverage-debt.js";
+import { buildTestLaneCommand, resolveTestLaneCommand } from "./progress.js";
 /** Release Step-5 vars that must not leak into vitest via inherited pnpm env (#2434). */
 const TS_LANE_POISON_ENV_KEYS = [BRANCH_GATE_BYPASS_ENV, RELEASE_PREFLIGHT_ENV];
 /**
@@ -30,7 +31,7 @@ const TS_LANE_POISON_ENV_KEYS = [BRANCH_GATE_BYPASS_ENV, RELEASE_PREFLIGHT_ENV];
 export const LANE_COMMANDS = [
     ["run", "lint"],
     ["run", "build"],
-    ["run", "test"],
+    buildTestLaneCommand(),
 ];
 export const SKIP_NOTICE = "[ts:check-lane] pnpm not found on PATH -- skipping the TypeScript lane " +
     "(build/lint/test). The TS engine stays validated by the dedicated CI job. " +
@@ -107,8 +108,9 @@ export function runTsLane(projectRoot, options) {
         return 0;
     }
     for (const command of LANE_COMMANDS) {
-        const argv = [pnpm, ...command];
-        // Soft-pass via lane-private env (vitest 3 CAC rejects unknown CLI debt tokens).
+        const resolved = command[1] === "test" ? resolveTestLaneCommand(projectRoot, options.reporterExists) : command;
+        const argv = [pnpm, ...resolved];
+        // Soft-pass via lane-private env (vitest CAC rejects unknown CLI debt tokens).
         // vitest.config reads DEFT_TS_LANE_COVERAGE_DEBT without DEFT_RELEASE_PREFLIGHT
         // (sanitizeTsLaneEnv strips preflight). Refs #2573 / #2618.
         const prevDebt = process.env.DEFT_TS_LANE_COVERAGE_DEBT;
@@ -137,14 +139,14 @@ export function runTsLane(projectRoot, options) {
         // (non-zero) for a signal-killed process.
         if (code === null) {
             if (result.error) {
-                out(`[ts:check-lane] \`pnpm ${command.join(" ")}\` failed to start: ${result.error.message}`);
+                out(`[ts:check-lane] \`pnpm ${resolved.join(" ")}\` failed to start: ${result.error.message}`);
                 return 1;
             }
-            out(`[ts:check-lane] \`pnpm ${command.join(" ")}\` was killed by ${result.signal ?? "a signal"} before exit -- treating as failure.`);
+            out(`[ts:check-lane] \`pnpm ${resolved.join(" ")}\` was killed by ${result.signal ?? "a signal"} before exit -- treating as failure.`);
             return 1;
         }
         if (code !== 0) {
-            out(`[ts:check-lane] \`pnpm ${command.join(" ")}\` failed (exit ${code}).`);
+            out(`[ts:check-lane] \`pnpm ${resolved.join(" ")}\` failed (exit ${code}).`);
             return code;
         }
     }

package/dist/validate-content/validate-links.d.ts

@@ -1,4 +1,12 @@
 import type { EvaluateResult } from "./types.js";
+/**
+ * Shared "not product source" core (#3487) plus the two directories only the
+ * link walk skips: generated planning projections and `specs/`.
+ *
+ * Walking agent worktrees during release Step 5 / `task check` is pure
+ * wall-clock waste (#2953, #1656, #3481).
+ */
+export declare const EXCLUDE_DIRS: Set<string>;
 export interface BrokenLink {
     readonly file: string;
     readonly line: number;

package/dist/validate-content/validate-links.js

@@ -1,21 +1,15 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join, relative, resolve, sep } from "node:path";
+import { NON_PRODUCT_DIRS } from "../fs/non-product-dirs.js";
 import { extractLinkTargets, shouldSkipLinkTarget } from "./link-parser.js";
-const EXCLUDE_DIRS = new Set([
-    ".git",
-    "backup",
-    "node_modules",
-    ".venv",
-    "__pycache__",
-    "dist",
-    ".planning",
-    "specs",
-    // Swarm / agent worktrees are not framework content; walking them
-    // during release Step 5 / task check is pure wall-clock waste (#2953, #1656).
-    ".deft-scratch",
-    // Legacy swarm worktree root name (pre-.deft-scratch layout).
-    "swarm-worktrees",
-]);
+/**
+ * Shared "not product source" core (#3487) plus the two directories only the
+ * link walk skips: generated planning projections and `specs/`.
+ *
+ * Walking agent worktrees during release Step 5 / `task check` is pure
+ * wall-clock waste (#2953, #1656, #3481).
+ */
+export const EXCLUDE_DIRS = new Set([...NON_PRODUCT_DIRS, ".planning", "specs"]);
 function shouldSkipPath(parts) {
     if (parts.some((p) => EXCLUDE_DIRS.has(p)))
         return true;

package/dist/value/feedback-file.js

@@ -235,10 +235,17 @@ export function runFeedbackFile(options) {
         };
     }
 }
+/** Join repeated --context values; schema stays `context?: string` (#3454). */
+const CONTEXT_JOIN = "\n";
+function appendContextValue(collected, value) {
+    if (typeof value === "string")
+        collected.push(value);
+}
 /** Parse argv for feedback:file. */
 export function parseFeedbackFileArgs(argv) {
     const out = {};
     const positionals = [];
+    const contextValues = [];
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
         if (arg === "--confirm")
@@ -254,10 +261,10 @@ export function parseFeedbackFileArgs(argv) {
             out.summary = arg.slice("--summary=".length);
         }
         else if (arg === "--context") {
-            out.context = argv[++i];
+            appendContextValue(contextValues, argv[++i]);
         }
         else if (arg?.startsWith("--context=")) {
-            out.context = arg.slice("--context=".length);
+            appendContextValue(contextValues, arg.slice("--context=".length));
         }
         else if (arg === "--expected") {
             out.expected = argv[++i];
@@ -302,6 +309,9 @@ export function parseFeedbackFileArgs(argv) {
     if ((out.summary === undefined || out.summary.trim().length === 0) && positionals.length > 0) {
         out.summary = positionals.join(" ");
     }
+    if (contextValues.length > 0) {
+        out.context = contextValues.join(CONTEXT_JOIN);
+    }
     return out;
 }
 /** CLI entry for feedback:file. */

package/dist/value/readback.d.ts

@@ -1,5 +1,6 @@
 import { type BehavioralEventRecord } from "../lifecycle/events.js";
 import { type ValueFeedbackResolved } from "../policy/value-feedback.js";
+import { type CeremonyCostRollup } from "../session/process-cost.js";
 /** Repeat-suppression window for the budgeted session readback (#1709 / #1279 parity). */
 export declare const VALUE_READBACK_SUPPRESSION_HOURS = 4;
 export declare const VALUE_READBACK_HISTORY_REL: string;
@@ -24,6 +25,8 @@ export interface ValueShowResult {
     readonly empty: boolean;
     readonly text: string;
     readonly trend: ValueShowTrend | null;
+    /** Composed #3508 ceremony-cost rollup (CLI process time, not turn clock). */
+    readonly ceremonyCost: CeremonyCostRollup | null;
 }
 export interface SessionReadbackResult {
     readonly line: string | null;
@@ -64,7 +67,7 @@ export declare function computeValueShowTrend(projectRoot: string, options?: {
     now?: Date;
 }): ValueShowTrend;
 export declare function formatValueShowReport(trend: ValueShowTrend): string;
-/** Pull-based value:show CLI core (#1709). */
+/** Pull-based value:show CLI core (#1709) with composed ceremony-cost reader (#3508). */
 export declare function runValueShow(options: {
     projectRoot?: string | null;
     window?: string;

package/dist/value/readback.js

@@ -8,6 +8,7 @@ import { DEFAULT_EVENT_LOG, readEvents } from "../lifecycle/events.js";
 import { policyColonInvocation } from "../policy/policy-invocation.js";
 import { isValueFeedbackPathAllowed, resolveValueFeedback, } from "../policy/value-feedback.js";
 import { resolveProjectRoot } from "../scope/project-context.js";
+import { computeCeremonyCostRollup, formatCeremonyCostReport, PROCESS_COST_EVENT_NAMES, } from "../session/process-cost.js";
 import { MAX_LINE_CHARS } from "../triage/welcome/constants.js";
 import { probeAdoptionAtWorkBoundary } from "./adoption-emit.js";
 import { probeFrictionAtWorkBoundary } from "./friction-emit.js";
@@ -391,7 +392,36 @@ export function formatValueShowReport(trend) {
     ];
     return `${lines.join("\n")}\n`;
 }
-/** Pull-based value:show CLI core (#1709). */
+function attachCeremonyCost(result, ceremonyCost, format) {
+    if (format === "json") {
+        const payload = result.trend !== null
+            ? {
+                ...result.trend,
+                ceremonyCost,
+                process_cost_events: PROCESS_COST_EVENT_NAMES,
+                gated: result.gated,
+                attribution_gated: result.gated,
+            }
+            : {
+                ceremonyCost,
+                process_cost_events: PROCESS_COST_EVENT_NAMES,
+                gated: result.gated,
+                attribution_gated: result.gated,
+                empty: result.empty,
+            };
+        return {
+            ...result,
+            ceremonyCost,
+            text: `${JSON.stringify(payload, null, 2)}\n`,
+        };
+    }
+    return {
+        ...result,
+        ceremonyCost,
+        text: `${result.text}${formatCeremonyCostReport(ceremonyCost)}`,
+    };
+}
+/** Pull-based value:show CLI core (#1709) with composed ceremony-cost reader (#3508). */
 export function runValueShow(options) {
     const rootRaw = resolveProjectRoot(options.projectRoot ?? undefined);
     if (rootRaw === null) {
@@ -401,30 +431,39 @@ export function runValueShow(options) {
             empty: true,
             text: "Error: could not resolve project root.\n",
             trend: null,
+            ceremonyCost: null,
         };
     }
     const root = resolve(rootRaw);
+    const windowMs = parseWindowMs(options.window);
+    const ceremonyCost = computeCeremonyCostRollup({
+        projectRoot: root,
+        logPath: options.logPath,
+        windowMs,
+        now: options.now,
+        windowLabel: formatWindowLabel(windowMs),
+    });
     if (maintainerReadbackDisabled(root)) {
-        return {
+        return attachCeremonyCost({
             exitCode: 0,
-            gated: true,
+            gated: false,
             empty: true,
-            text: "[value] Skipped: maintainer framework repo (set DEFT_VALUE_SELF_DOGFOOD=1 to dogfood).\n",
+            text: "[value] Attribution skipped: maintainer framework repo " +
+                "(set DEFT_VALUE_SELF_DOGFOOD=1 to dogfood).\n",
             trend: null,
-        };
+        }, ceremonyCost, options.format);
     }
     const policy = options.policyOverride ?? resolveValueFeedback(root);
     if (!policy.enabled) {
-        return {
+        return attachCeremonyCost({
             exitCode: 1,
             gated: true,
             empty: true,
             text: "[value] Blocked: plan.policy.valueFeedback is OFF. " +
                 `Enable with \`${policyColonInvocation("enable-value-feedback", " -- --confirm")}\`.\n`,
             trend: null,
-        };
+        }, ceremonyCost, options.format);
     }
-    const windowMs = parseWindowMs(options.window);
     const trend = computeValueShowTrend(root, {
         windowMs,
         logPath: options.logPath,
@@ -432,21 +471,21 @@ export function runValueShow(options) {
     });
     const empty = trend.total === 0;
     if (options.format === "json") {
-        return {
+        return attachCeremonyCost({
             exitCode: 0,
             gated: false,
             empty,
             text: `${JSON.stringify(trend, null, 2)}\n`,
             trend,
-        };
+        }, ceremonyCost, "json");
     }
-    return {
+    return attachCeremonyCost({
         exitCode: 0,
         gated: false,
         empty,
         text: formatValueShowReport(trend),
         trend,
-    };
+    }, ceremonyCost, "text");
 }
 export function parseValueShowArgs(argv) {
     const out = {};

package/dist/vbrief-build/index.d.ts

@@ -4,6 +4,7 @@ export { pythonJsonPretty } from "./json.js";
 export { cmdVbriefBuild, run, usage } from "./main.js";
 export { PARITY_SCENARIO_NAMES, renderScenarioOutput, runParityScenario, SAMPLE_PROJECT_MD, SAMPLE_ROADMAP_MD, SAMPLE_SPEC_MD, SAMPLE_SPEC_VBRIEF, } from "./parity-scenarios.js";
 export { atomicWriteProjectDefinition, loadProjectDefinitionForMutation, projectDefinitionMutationLock, projectDefinitionPath, } from "./project-definition-io.js";
+export { loadProjectInvariants, parseProjectInvariantsField } from "./project-invariants-io.js";
 export { buildScopeVbriefFromReconciled, defaultStatusForFolder, folderForStatus, migrationTimestamp, planStatusMatchesFolder, } from "./routing.js";
 export { deriveOverviewNarrative, extractTechStack, firstProseParagraph, parseRoadmapItems, resolveRepoUrl, } from "./sources.js";
 export { createSpeckitScopeVbrief, dependenciesForItem, edgeNodes, migrateSpeckitPlan, speckitIpIndex, speckitIpSlug, } from "./speckit.js";

package/dist/vbrief-build/index.js

@@ -4,6 +4,7 @@ export { pythonJsonPretty } from "./json.js";
 export { cmdVbriefBuild, run, usage } from "./main.js";
 export { PARITY_SCENARIO_NAMES, renderScenarioOutput, runParityScenario, SAMPLE_PROJECT_MD, SAMPLE_ROADMAP_MD, SAMPLE_SPEC_MD, SAMPLE_SPEC_VBRIEF, } from "./parity-scenarios.js";
 export { atomicWriteProjectDefinition, loadProjectDefinitionForMutation, projectDefinitionMutationLock, projectDefinitionPath, } from "./project-definition-io.js";
+export { loadProjectInvariants, parseProjectInvariantsField } from "./project-invariants-io.js";
 export { buildScopeVbriefFromReconciled, defaultStatusForFolder, folderForStatus, migrationTimestamp, planStatusMatchesFolder, } from "./routing.js";
 export { deriveOverviewNarrative, extractTechStack, firstProseParagraph, parseRoadmapItems, resolveRepoUrl, } from "./sources.js";
 export { createSpeckitScopeVbrief, dependenciesForItem, edgeNodes, migrateSpeckitPlan, speckitIpIndex, speckitIpSlug, } from "./speckit.js";

package/dist/vbrief-build/project-invariants-io.d.ts

@@ -0,0 +1,16 @@
+/**
+ * PROJECT-DEFINITION IO for plan.policy.projectInvariants (#3425 Story A).
+ */
+import { type ProjectInvariant, type ProjectInvariantsResolved } from "../policy/project-invariants.js";
+export interface LoadedProjectInvariants {
+    readonly path: string;
+    readonly resolved: ProjectInvariantsResolved;
+    readonly modulePathGlobs: Readonly<Record<string, readonly string[]>>;
+}
+/** Read and parse projectInvariants via the PROJECT-DEFINITION IO path. */
+export declare function loadProjectInvariants(projectRoot: string): LoadedProjectInvariants;
+export declare function parseProjectInvariantsField(raw: unknown): {
+    readonly invariants: readonly ProjectInvariant[];
+    readonly errors: readonly string[];
+};
+//# sourceMappingURL=project-invariants-io.d.ts.map

package/dist/vbrief-build/project-invariants-io.js

@@ -0,0 +1,41 @@
+/**
+ * PROJECT-DEFINITION IO for plan.policy.projectInvariants (#3425 Story A).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { extractModulePathGlobs, parseProjectInvariants, resolveProjectInvariantsFromData, } from "../policy/project-invariants.js";
+import { projectDefinitionPath } from "./project-definition-io.js";
+/** Read and parse projectInvariants via the PROJECT-DEFINITION IO path. */
+export function loadProjectInvariants(projectRoot) {
+    const path = projectDefinitionPath(projectRoot);
+    if (!existsSync(path)) {
+        return {
+            path,
+            resolved: {
+                invariants: [],
+                source: "default",
+                error: `PROJECT-DEFINITION not found at ${path}`,
+            },
+            modulePathGlobs: {},
+        };
+    }
+    try {
+        const data = JSON.parse(readFileSync(path, "utf8"));
+        return {
+            path,
+            resolved: resolveProjectInvariantsFromData(data),
+            modulePathGlobs: extractModulePathGlobs(data),
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            path,
+            resolved: { invariants: [], source: "default-on-error", error: msg },
+            modulePathGlobs: {},
+        };
+    }
+}
+export function parseProjectInvariantsField(raw) {
+    return parseProjectInvariants(raw);
+}
+//# sourceMappingURL=project-invariants-io.js.map

package/dist/vbrief-reconcile/graph.js

@@ -34,6 +34,7 @@ export function reconcileGraph(projectRoot, options = {}) {
             2,
             {
                 promoted: [],
+                promotedNotices: [],
                 deferredWip: [],
                 waiting: [],
                 cycles: [],
@@ -62,6 +63,7 @@ export function reconcileGraph(projectRoot, options = {}) {
     const [cap, count] = resolveWipState(root);
     const outcome = {
         promoted: [],
+        promotedNotices: [],
         deferredWip: [],
         waiting: [],
         cycles: [],
@@ -105,6 +107,9 @@ export function reconcileGraph(projectRoot, options = {}) {
             continue;
         }
         outcome.promoted.push(cand.storyId);
+        if (result.message.trim().length > 0) {
+            outcome.promotedNotices?.push({ story_id: cand.storyId, message: result.message });
+        }
         runningCount += 1;
     }
     return [outcome.cycles.length > 0 ? 1 : 0, { ...outcome, count: runningCount }];
@@ -114,8 +119,16 @@ export function renderGraphReport(outcome) {
     const suffix = outcome.dryRun ? " (dry-run)" : "";
     lines.push(`Promoted${suffix}:`);
     if (outcome.promoted.length > 0) {
-        for (const id of outcome.promoted)
+        const notices = new Map((outcome.promotedNotices ?? []).map((n) => [n.story_id, n.message]));
+        for (const id of outcome.promoted) {
             lines.push(`- ${id}`);
+            const notice = notices.get(id);
+            if (notice !== undefined && notice.trim().length > 0) {
+                for (const line of notice.split(/\r?\n/)) {
+                    lines.push(`  ${line}`);
+                }
+            }
+        }
     }
     else {
         lines.push("- none");
@@ -159,6 +172,10 @@ export function renderGraphReport(outcome) {
 export function graphOutcomeToJson(outcome) {
     return {
         promoted: [...outcome.promoted],
+        promoted_notices: (outcome.promotedNotices ?? []).map((n) => ({
+            story_id: n.story_id,
+            message: n.message,
+        })),
         deferred_wip: [...outcome.deferredWip],
         waiting: outcome.waiting.map((w) => ({ story_id: w.story_id, unresolved: w.unresolved })),
         cycles: [...outcome.cycles],