@deftai/directive-core 0.99.0 → 0.101.0

package/dist/triage/reconcile/reconcile.js

@@ -1,7 +1,8 @@
 import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { appendFileSync, mkdirSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { mkdirSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { containedWrite } from "../../fs/contained-write.js";
 import { resolveLifecycleFolder } from "../../layout/resolve.js";
 import { resolveCandidatesLogPath } from "../cache-path.js";
 import { auditKey, existingAuditRefs, scanLifecycleRefs } from "./audit.js";
@@ -127,9 +128,30 @@ function buildReconcileEntry(repo, issueNumber, sourceFolder) {
             "with a github-issue reference but no prior decision in the audit log",
     };
 }
-function appendAuditEntry(auditPath, entry) {
-    mkdirSync(dirname(auditPath), { recursive: true });
-    appendFileSync(auditPath, `${JSON.stringify(entry)}\n`, "utf8");
+/**
+ * Containment root for reconcile audit appends (#3288 / #3245).
+ * Prefer project root when the log is nested under it; otherwise parent dir.
+ */
+function containmentRootForAudit(projectRoot, auditPath) {
+    const rootAbs = resolve(projectRoot);
+    const logAbs = resolve(auditPath);
+    const parent = dirname(logAbs);
+    mkdirSync(parent, { recursive: true });
+    const rel = relative(rootAbs, logAbs);
+    if (rel.length > 0 && !rel.startsWith("..") && !isAbsolute(rel)) {
+        return rootAbs;
+    }
+    return resolve(parent);
+}
+/** #3288 / #3245 / #2980: product append refuses leaf symlink follow. */
+function appendAuditEntry(projectRoot, auditPath, entry) {
+    const root = containmentRootForAudit(projectRoot, auditPath);
+    containedWrite({
+        root,
+        target: auditPath,
+        data: `${JSON.stringify(entry)}\n`,
+        mode: "append",
+    });
 }
 export function reconcile(projectRoot, options = {}) {
     const root = resolve(projectRoot);
@@ -158,7 +180,7 @@ export function reconcile(projectRoot, options = {}) {
     for (const item of items) {
         const entry = buildReconcileEntry(item.repo, item.issueNumber, item.folder);
         try {
-            appendAuditEntry(auditPath, entry);
+            appendAuditEntry(root, auditPath, entry);
         }
         catch (err) {
             return {

package/dist/triage/summary/index.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
-import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
-import { join, resolve as pathResolve } from "node:path";
+import { existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve as pathResolve } from "node:path";
+import { containedWrite } from "../../fs/contained-write.js";
 import { hasArtifactSuffix, resolveLifecycleFolder, resolveProjectDefinitionPath, } from "../../layout/resolve.js";
 import { readPlanPolicy } from "../../policy/plan-extensions.js";
 import { loadProjectDefinition, PROJECT_DEFINITION_REL_PATH } from "../../policy/resolve.js";
@@ -542,8 +543,15 @@ export function appendHistory(historyPath, result, line, options = {}) {
     });
     const payload = pythonStyleStringify(record);
     try {
-        mkdirSync(join(historyPath, ".."), { recursive: true });
-        appendFileSync(historyPath, `${payload}\n`, { encoding: "utf8" });
+        // #3288 / #3245 / #2980: refuse leaf symlink follow (in-tree diversion).
+        const parent = dirname(historyPath);
+        mkdirSync(parent, { recursive: true });
+        containedWrite({
+            root: pathResolve(parent),
+            target: historyPath,
+            data: `${payload}\n`,
+            mode: "append",
+        });
     }
     catch {
         // observability only — never crash the ritual

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

@@ -1,6 +1,7 @@
 import { resolve } from "node:path";
 import { ensureTriageCacheHydrated } from "../../cache/empty-populate.js";
 import { maybeSelfHealCache } from "../../cache/fetch.js";
+import { maybeFormatMirrorDiscoveryTip } from "../classify/mirror-discovery-tip.js";
 import { FIRST_TIME_NUDGE, INCOMPLETE_NUDGE_TEMPLATE } from "./constants.js";
 import { classifyOnboarding, detectPriorState } from "./prior-state.js";
 import { emitOneliner } from "./summary.js";
@@ -52,6 +53,21 @@ export function runDefaultMode(projectRoot, options = {}) {
     else if (label === "incomplete") {
         out(INCOMPLETE_NUDGE_TEMPLATE.replace("{missing}", missing.join(" + ")).replace(canonicalOnboard, onboardCommand));
     }
+    // #3124: throttled SCM label-mirror discovery tip (existence + get-the-most).
+    // Cold session:start runs this welcome path; re-arm skips welcome so tip is not spammed.
+    try {
+        const tip = maybeFormatMirrorDiscoveryTip(projectRoot, {
+            ...(options.now !== undefined ? { now: options.now } : {}),
+        });
+        if (tip.length > 0) {
+            for (const line of tip.trimEnd().split(/\r?\n/)) {
+                out(line);
+            }
+        }
+    }
+    catch {
+        // Discovery tip is advisory — never fail welcome.
+    }
     return outcome;
 }
 //# sourceMappingURL=default-mode.js.map

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

@@ -51,12 +51,12 @@ export function shouldUseShellForCommand(command, platform = process.platform) {
     return platform === "win32" && /\.(?:cmd|bat)$/i.test(command);
 }
 /** Default runner: an inherited-stdio pnpm invocation. */
-function defaultRunner(argv, cwd) {
+function defaultRunner(argv, cwd, envOverride) {
     const [command, ...rest] = argv;
     const commandPath = command ?? "";
     const result = spawnSync(commandPath, rest, {
         cwd,
-        env: sanitizeTsLaneEnv(process.env),
+        env: envOverride ?? sanitizeTsLaneEnv(process.env),
         stdio: "inherit",
         shell: shouldUseShellForCommand(commandPath),
     });
@@ -108,10 +108,27 @@ export function runTsLane(projectRoot, options) {
     }
     for (const command of LANE_COMMANDS) {
         const argv = [pnpm, ...command];
+        // Soft-pass via lane-private env (vitest 3 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;
         if (debtIssue !== null && command[1] === "test") {
-            argv.push("--", `--allow-coverage-debt=${debtIssue}`);
+            process.env.DEFT_TS_LANE_COVERAGE_DEBT = String(debtIssue);
+        }
+        let result;
+        try {
+            result = runner(argv, projectRoot);
+        }
+        finally {
+            if (debtIssue !== null && command[1] === "test") {
+                if (prevDebt === undefined) {
+                    delete process.env.DEFT_TS_LANE_COVERAGE_DEBT;
+                }
+                else {
+                    process.env.DEFT_TS_LANE_COVERAGE_DEBT = prevDebt;
+                }
+            }
         }
-        const result = runner(argv, projectRoot);
         const code = result.status;
         // A null status means the child was terminated by a signal (SIGKILL / OOM /
         // SIGTERM) before it could exit. Mapping that to 0 would silently pass a

package/dist/vbrief-validate/conformance.js

@@ -28,6 +28,8 @@ export const PLAN_CORE = new Set([
     "changeLog",
     "sequence",
     "fork",
+    // Product-first done-gate (#3284): plan.acceptance.commands / none_stated / source_rung.
+    "acceptance",
 ]);
 export const ITEM_CORE = new Set([
     "id",
@@ -62,6 +64,11 @@ export const ITEM_CORE = new Set([
     "lastModifiedBy",
     "lockedBy",
     "items",
+    // Optional PlanItem.effort enum S/M/L/XL (#1581) — schema-validated, core not extension.
+    "effort",
+    // #3305 Option B: acceptance evidence/disposition are NOT ITEM_CORE.
+    // Canonical keys: plan.items[].x-directive/evidence and x-directive/disposition
+    // (accepted via EXTENSION_PREFIXES). Bare evidence/disposition fail #1620.
 ]);
 export const EXTENSION_PREFIXES = ["x-directive/", "x-vbrief/", "x-xbrief/"];
 export function renderFinding(finding) {

package/dist/vitest-runner/coverage-debt-teardown.js

@@ -1,14 +1,26 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { COVERAGE_GOAL, countRecentCoverageDebtMentions, formatCoverageAttribution, formatOveruseWarning, metricsBelowGoal, readCoverageTotalsFromReport, resolveCoverageDebtIssue, } from "./coverage-debt.js";
-/** Vitest globalTeardown: enforce coverage goal or debt soft-pass (#2573). */
-export default async function coverageDebtTeardown() {
+function resolveDebtIssueForTeardown() {
     const resolution = resolveCoverageDebtIssue(process.argv, process.env);
-    if (resolution.kind === "none")
-        return;
+    if (resolution.kind === "valid")
+        return resolution;
     if (resolution.kind === "invalid") {
         throw new Error(`coverage-debt: ${resolution.reason}`);
     }
+    const laneRaw = process.env.DEFT_TS_LANE_COVERAGE_DEBT;
+    if (laneRaw !== undefined && /^\d+$/.test(laneRaw.trim())) {
+        const issue = Number.parseInt(laneRaw.trim(), 10);
+        if (issue > 0)
+            return { kind: "valid", issue };
+    }
+    return { kind: "none" };
+}
+/** Vitest globalTeardown: enforce coverage goal or debt soft-pass (#2573). */
+export default async function coverageDebtTeardown() {
+    const resolution = resolveDebtIssueForTeardown();
+    if (resolution.kind === "none")
+        return;
     const repoRoot = join(import.meta.dirname, "..", "..", "..", "..");
     const totals = readCoverageTotalsFromReport(join(repoRoot, "coverage"));
     if (totals === null) {

package/dist/xbrief-migrate/migrate-project.d.ts

@@ -24,6 +24,10 @@ export type XbriefMigrationOutcome = {
     readonly kind: "migrated";
     readonly backupDir: string;
     readonly files: number;
+} | {
+    readonly kind: "rewritten";
+    readonly files: number;
+    readonly message: string;
 } | {
     readonly kind: "converged";
     readonly action: VbriefConvergeAction;

package/dist/xbrief-migrate/migrate-project.js

@@ -5,12 +5,12 @@ import { assertWriteTargetSafe, ProjectionContainmentError } from "../fs/project
 import { checkGitClean } from "../migrate-preflight/index.js";
 import { applyAgentsRefresh } from "../platform/agents-md.js";
 import { patchAgentsMdHeader, renderHeaderPatchSummary } from "./agents-header.js";
-import { LEGACY_ARTIFACT_DIR, LEGACY_ARTIFACT_SUFFIX, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, OBSOLETE_FRAMEWORK_NARRATIVE_FILENAME, VBRIEF_DEPRECATION_MARKER_BODY, VBRIEF_DEPRECATION_MARKER_FILENAME, } from "./constants.js";
+import { LEGACY_ARTIFACT_DIR, LEGACY_ARTIFACT_SUFFIX, LEGACY_VBRIEF_VERSION, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, OBSOLETE_FRAMEWORK_NARRATIVE_FILENAME, VBRIEF_DEPRECATION_MARKER_BODY, VBRIEF_DEPRECATION_MARKER_FILENAME, } from "./constants.js";
 import { detectLegacyVbriefLayout, detectXbriefConvergence } from "./detect.js";
 import { hasVbriefDeprecationMarker, isDirectory, isEffectivelyEmptyDir } from "./fs-helpers.js";
 import { assertMigrationSourceSafe } from "./migration-containment.js";
 import { renderXbriefMigrationLine, xbriefMigrationGuidance } from "./signpost.js";
-import { rewriteEmbeddedTokens, transformArtifactV06ToV08Transactional } from "./transforms.js";
+import { readDeclaredArtifactVersion, rewriteEmbeddedTokens, transformArtifactV06ToV08Transactional, } from "./transforms.js";
 function collectFiles(root, acc = []) {
     if (!isDirectory(root)) {
         return acc;
@@ -74,6 +74,65 @@ function writeMigratedFile(projectRoot, srcPath, destPath) {
         mode: "replace",
     });
 }
+/**
+ * Plan in-place hybrid envelope rewrites for xbrief lifecycle `.xbrief.json`
+ * artifacts that still declare `xBRIEFInfo@0.6` after the layout rename
+ * (#3236 / #2974). Pure probe — no writes. Already-0.8 artifacts, schema
+ * deposits, and non-0.6 JSON are skipped so residual #2368 schema-only markers
+ * still route to `directive update`.
+ */
+function planHybridEnvelopeRewrites(projectRoot) {
+    const migratedDir = join(projectRoot, MIGRATED_ARTIFACT_DIR);
+    const artifactPaths = collectFiles(migratedDir).filter((path) => path.endsWith(MIGRATED_ARTIFACT_SUFFIX));
+    const pending = [];
+    for (const filePath of artifactPaths) {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(filePath, "utf8"));
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            return {
+                ok: false,
+                error: `failed to parse hybrid envelope candidate ${relative(projectRoot, filePath)}: ${detail}`,
+            };
+        }
+        // Only residual v0.6 envelopes are rewrite candidates; skip 0.8 and unknown.
+        if (readDeclaredArtifactVersion(parsed) !== LEGACY_VBRIEF_VERSION) {
+            continue;
+        }
+        const result = transformArtifactV06ToV08Transactional(parsed);
+        if (!result.ok) {
+            return {
+                ok: false,
+                error: `failed to transform hybrid envelope ${relative(projectRoot, filePath)}: ${result.error}`,
+            };
+        }
+        if (!result.changed) {
+            continue;
+        }
+        pending.push({
+            path: filePath,
+            body: `${JSON.stringify(result.artifact, null, 2)}\n`,
+        });
+    }
+    return { ok: true, pending };
+}
+/**
+ * Apply a previously planned hybrid-envelope rewrite set via containedWrite (#3236).
+ */
+function applyHybridEnvelopeRewrites(projectRoot, pending) {
+    const root = resolve(projectRoot);
+    for (const entry of pending) {
+        containedWrite({
+            root,
+            target: entry.path,
+            data: entry.body,
+            mode: "replace",
+        });
+    }
+    return pending.length;
+}
 function backupMigrationInputs(projectRoot, legacyDir, migratedDir) {
     const stamp = new Date().toISOString().replace(/[:.]/g, "-");
     const backupRoot = join(projectRoot, ".deft", `xbrief-migrate-backup-${stamp}`);
@@ -256,6 +315,33 @@ export function runXbriefMigration(args, _io) {
         default:
             break;
     }
+    // #3236: on already-xbrief trees with no vbrief/, rewrite residual hybrid
+    // xBRIEFInfo@0.6 envelopes in place (transform accepts hybrid — #2974).
+    // Run before the layout-detection short-circuit so compact `"version":"0.6"`
+    // JSON that the string-scan may miss still gets rewritten.
+    if (convergence.xbriefHasContent && !convergence.vbriefPresent) {
+        const plan = planHybridEnvelopeRewrites(projectRoot);
+        if (!plan.ok) {
+            return { kind: "config", message: plan.error };
+        }
+        if (plan.pending.length > 0) {
+            if (!args.force) {
+                const git = checkGitClean(projectRoot);
+                if (git.status === "WARN") {
+                    return {
+                        kind: "refused",
+                        message: `${git.message} ${xbriefMigrationGuidance()} Pass --force to override.`,
+                    };
+                }
+            }
+            const files = applyHybridEnvelopeRewrites(projectRoot, plan.pending);
+            return {
+                kind: "rewritten",
+                files,
+                message: `Rewrote ${files} hybrid xBRIEFInfo@0.6 envelope(s) in place to xBRIEFInfo@0.8 under '${MIGRATED_ARTIFACT_DIR}/'.`,
+            };
+        }
+    }
     const detection = detectLegacyVbriefLayout(projectRoot);
     if (!detection.legacyLayout) {
         return {
@@ -266,7 +352,7 @@ export function runXbriefMigration(args, _io) {
     if (!isDirectory(legacyDir)) {
         // Already on canonical xbrief/ with no vbrief/ tree — residual markers (e.g. a
         // stale deposited v0.6 schema under xbrief/schemas/) are refreshed by update,
-        // not migrate:xbrief (#2368).
+        // not migrate:xbrief (#2368). Hybrid 0.6 envelopes were handled above (#3236).
         if (convergence.xbriefHasContent && !convergence.vbriefPresent) {
             return {
                 kind: "noop",
@@ -319,6 +405,9 @@ export function emitXbriefMigration(outcome, io, options = {}) {
             io.writeOut(`Migrated ${outcome.files} file(s) from ${LEGACY_ARTIFACT_DIR}/ to ${MIGRATED_ARTIFACT_DIR}/.\n` +
                 `Backup written to ${outcome.backupDir}.\n`);
             return 0;
+        case "rewritten":
+            io.writeOut(`${outcome.message}\n`);
+            return 0;
         case "converged":
             io.writeOut(`${outcome.message}\n`);
             return 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-core",
-  "version": "0.99.0",
+  "version": "0.101.0",
   "description": "TypeScript engine core for the Directive framework.",
   "license": "MIT",
   "type": "module",
@@ -283,6 +283,14 @@
       "types": "./dist/lifecycle/index.d.ts",
       "default": "./dist/lifecycle/index.js"
     },
+    "./literal-acceptance": {
+      "types": "./dist/literal-acceptance/index.d.ts",
+      "default": "./dist/literal-acceptance/index.js"
+    },
+    "./product-first-done-gate": {
+      "types": "./dist/product-first-done-gate/index.d.ts",
+      "default": "./dist/product-first-done-gate/index.js"
+    },
     "./packs": {
       "types": "./dist/packs/index.d.ts",
       "default": "./dist/packs/index.js"
@@ -311,6 +319,10 @@
       "types": "./dist/check/index.d.ts",
       "default": "./dist/check/index.js"
     },
+    "./run-summary": {
+      "types": "./dist/run-summary/index.d.ts",
+      "default": "./dist/run-summary/index.js"
+    },
     "./preflight-gh": {
       "types": "./dist/preflight-gh/index.d.ts",
       "default": "./dist/preflight-gh/index.js"
@@ -366,8 +378,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-content": "^0.99.0",
-    "@deftai/directive-types": "^0.99.0",
+    "@deftai/directive-content": "^0.101.0",
+    "@deftai/directive-types": "^0.101.0",
     "archiver": "^8.0.0"
   },
   "scripts": {