@deftai/directive-core 0.104.0 → 0.105.0

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/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],

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

@@ -8,5 +8,5 @@ export { pyRepr } from "./py-repr.js";
 export { buildSpecTaskIndex, detectStatusMarker, folderFromStatus, formatReconciliationMarkdown, hasDisagreement, loadOverrides, normalizeTaskId, OVERRIDES_FILENAME, parseOverridesYaml, reconcileScopeItems, writeReconciliationReport, } from "./reconciliation.js";
 export { allScopeIds, asStrList, candidateDepGraph, candidateFromPath, markCycles, } from "./swarm-deps.js";
 export type { Candidate, Child, ConflictEntry, ForgeIssueState, LabelChange, LabelClient, ReconciledItem, ReconcileGraphOutcome, ReconcileLabelsOutcome, ReconcileUmbrellasOutcome, ReconciliationReport, SpecTaskEntry, UmbrellaChange, UmbrellaClient, } from "./types.js";
-export { buildChildIndex, CHILD_REF_TYPE, CLOSED_FOLDERS, childFromData, classifyPassType, computeChildren, computeWaves, indexChildrenByIssueNumber, isChildOpen, LIFECYCLE_FOLDERS, nowIso, OPEN_FOLDERS, parseCurrentShape, reconcileBodyChecklist, reconcileUmbrellas, renderBody, renderUmbrellasReport, ScmUmbrellaClient, UmbrellaScmError, UNKNOWN_FOLDER, umbrellasOutcomeToJson, } from "./umbrellas.js";
+export { buildChildIndex, CHILD_REF_TYPE, CLOSED_FOLDERS, childFromData, childrenFromSliceRecord, classifyPassType, computeChildren, computeWaves, formatCloseComment, indexChildrenByIssueNumber, isChildOpen, LIFECYCLE_FOLDERS, nowIso, OPEN_FOLDERS, parseCurrentShape, reconcileBodyChecklist, reconcileUmbrellas, renderBody, renderUmbrellasReport, ScmUmbrellaClient, shouldCloseOnAllChildrenMerged, UmbrellaScmError, UNKNOWN_FOLDER, umbrellasOutcomeToJson, } from "./umbrellas.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/vbrief-reconcile/index.js

@@ -6,5 +6,5 @@ export { PARITY_SCENARIO_NAMES, renderScenarioOutput, runParityScenario, } from
 export { pyRepr } from "./py-repr.js";
 export { buildSpecTaskIndex, detectStatusMarker, folderFromStatus, formatReconciliationMarkdown, hasDisagreement, loadOverrides, normalizeTaskId, OVERRIDES_FILENAME, parseOverridesYaml, reconcileScopeItems, writeReconciliationReport, } from "./reconciliation.js";
 export { allScopeIds, asStrList, candidateDepGraph, candidateFromPath, markCycles, } from "./swarm-deps.js";
-export { buildChildIndex, CHILD_REF_TYPE, CLOSED_FOLDERS, childFromData, classifyPassType, computeChildren, computeWaves, indexChildrenByIssueNumber, isChildOpen, LIFECYCLE_FOLDERS, nowIso, OPEN_FOLDERS, parseCurrentShape, reconcileBodyChecklist, reconcileUmbrellas, renderBody, renderUmbrellasReport, ScmUmbrellaClient, UmbrellaScmError, UNKNOWN_FOLDER, umbrellasOutcomeToJson, } from "./umbrellas.js";
+export { buildChildIndex, CHILD_REF_TYPE, CLOSED_FOLDERS, childFromData, childrenFromSliceRecord, classifyPassType, computeChildren, computeWaves, formatCloseComment, indexChildrenByIssueNumber, isChildOpen, LIFECYCLE_FOLDERS, nowIso, OPEN_FOLDERS, parseCurrentShape, reconcileBodyChecklist, reconcileUmbrellas, renderBody, renderUmbrellasReport, ScmUmbrellaClient, shouldCloseOnAllChildrenMerged, UmbrellaScmError, UNKNOWN_FOLDER, umbrellasOutcomeToJson, } from "./umbrellas.js";
 //# sourceMappingURL=index.js.map

package/dist/vbrief-reconcile/types.d.ts

@@ -54,6 +54,11 @@ export interface Candidate {
 }
 export interface ReconcileGraphOutcome {
     promoted: string[];
+    /** Successful promote messages, including refused-stamp remediation (#3398). */
+    promotedNotices?: Array<{
+        story_id: string;
+        message: string;
+    }>;
     deferredWip: string[];
     waiting: Array<{
         story_id: string;
@@ -110,6 +115,12 @@ export interface UmbrellaChange {
      * `unchanged` when already correct, `skipped` when body APIs unavailable.
      */
     readonly checklist_action?: "edited" | "unchanged" | "skipped";
+    /**
+     * slices.jsonl expected_close_signal close (#3428): `closed` when the
+     * umbrella was closed this run, `unchanged` when already closed under
+     * all-children-merged, `skipped` when the signal is not a close.
+     */
+    readonly close_action?: "closed" | "unchanged" | "skipped";
 }
 export interface ReconcileUmbrellasOutcome {
     changed: UmbrellaChange[];
@@ -138,5 +149,7 @@ export interface UmbrellaClient {
     fetchIssueBody?(repo: string, issueNumber: number): string;
     /** Optional: write reconciled checklist body (#1649). */
     editIssueBody?(repo: string, issueNumber: number, body: string): void;
+    /** Optional: close an umbrella via REST (#3428). */
+    closeIssue?(repo: string, issueNumber: number): void;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/vbrief-reconcile/umbrellas.d.ts

@@ -63,8 +63,22 @@ export declare class ScmUmbrellaClient implements UmbrellaClient {
     fetchIssueStates(repo: string, issueNumbers: readonly number[]): ReadonlyMap<number, ForgeIssueState>;
     fetchIssueBody(repo: string, issueNumber: number): string;
     editIssueBody(repo: string, issueNumber: number, body: string): void;
+    closeIssue(repo: string, issueNumber: number): void;
 }
 export declare function nowIso(date?: Date): string;
+/** Children listed on a slices.jsonl row (#3428). Last write of a duplicate `n` wins. */
+export declare function childrenFromSliceRecord(record: Record<string, unknown>): Child[];
+/**
+ * Close only when the slice signal is all-children-merged, the umbrella is
+ * still open, and every child has forge state closed (#3428).
+ */
+export declare function shouldCloseOnAllChildrenMerged(options: {
+    readonly signal: unknown;
+    readonly children: readonly Child[];
+    readonly forgeStates: ReadonlyMap<number, ForgeIssueState> | null | undefined;
+    readonly umbrellaState: ForgeIssueState | null | undefined;
+}): boolean;
+export declare function formatCloseComment(signal: string, children: readonly Child[]): string;
 export interface ReconcileUmbrellasOptions {
     readonly repo?: string | null;
     readonly dryRun?: boolean;