@deftai/directive-core 0.99.0 → 0.101.0

package/dist/check/gate-lists.d.ts

@@ -9,6 +9,11 @@ export type CheckGateSpec = string | {
     readonly task: string;
     readonly args?: readonly string[];
 };
+/**
+ * Product-first AC gate (#3284): always first; soft-missing when no active
+ * xBRIEF so framework self-check is not deadlocked without a story.
+ */
+export declare const PRODUCT_FIRST_AC_GATE: CheckGateSpec;
 export declare function checkGateId(spec: CheckGateSpec): string;
 /** Args for `task … --taskfile <path>` (optional `--` + public CLI flags). */
 export declare function checkGateSpawnArgs(spec: CheckGateSpec, taskfilePath: string): string[];
@@ -26,11 +31,12 @@ export declare function isSuiteCheckGate(spec: CheckGateSpec | string): boolean;
  */
 export declare function isFastBeforeSlowOrder(gates: readonly CheckGateSpec[]): boolean;
 /**
- * Framework-source check composition (#1713 / #3188).
+ * Framework-source check composition (#1713 / #3188 / #3284).
  *
- * Order contract: cheap preflight gates first; `ts:check-lane` (lint+build+
- * vitest coverage suite) last so a stale cache / orphan-active / branch miss
- * fails in seconds without starting the suite.
+ * Order contract:
+ *  1. Product AC first (fail-fast; never skippable when commands exist) — #3284
+ *  2. Cheap hygiene preflight — #3188
+ *  3. `ts:check-lane` suite last
  */
 export declare const FRAMEWORK_CHECK_GATES: readonly CheckGateSpec[];
 export declare const CONSUMER_CHECK_GATES: readonly CheckGateSpec[];

package/dist/check/gate-lists.js

@@ -1,4 +1,13 @@
 /** Gate execution order mirrors Taskfile.yml check targets (#1713 dogfood). */
+import { PRODUCT_AC_GATE_ID } from "../product-first-done-gate/types.js";
+/**
+ * Product-first AC gate (#3284): always first; soft-missing when no active
+ * xBRIEF so framework self-check is not deadlocked without a story.
+ */
+export const PRODUCT_FIRST_AC_GATE = {
+    task: PRODUCT_AC_GATE_ID,
+    args: ["--soft-missing-xbrief"],
+};
 export function checkGateId(spec) {
     return typeof spec === "string" ? spec : spec.task;
 }
@@ -39,13 +48,16 @@ export function isFastBeforeSlowOrder(gates) {
     return true;
 }
 /**
- * Framework-source check composition (#1713 / #3188).
+ * Framework-source check composition (#1713 / #3188 / #3284).
  *
- * Order contract: cheap preflight gates first; `ts:check-lane` (lint+build+
- * vitest coverage suite) last so a stale cache / orphan-active / branch miss
- * fails in seconds without starting the suite.
+ * Order contract:
+ *  1. Product AC first (fail-fast; never skippable when commands exist) — #3284
+ *  2. Cheap hygiene preflight — #3188
+ *  3. `ts:check-lane` suite last
  */
 export const FRAMEWORK_CHECK_GATES = [
+    // --- Product-first done-gate (#3284) — AC before any hygiene ---
+    PRODUCT_FIRST_AC_GATE,
     // --- Fast preflight (seconds–few min) — #3188 ---
     "verify:branch",
     "verify:encoding",
@@ -89,7 +101,9 @@ export const FRAMEWORK_CHECK_GATES = [
     "ts:check-lane",
 ];
 export const CONSUMER_CHECK_GATES = [
-    // Cheap lifecycle / policy first (no suite co-list today; keep fail-fast order)
+    // Product-first: stated AC before hygiene (#3284)
+    PRODUCT_FIRST_AC_GATE,
+    // Cheap lifecycle / policy second (no suite co-list today; keep fail-fast order)
     "verify:branch",
     "verify:cache-fresh",
     "verify:wip-cap",

package/dist/check/index.d.ts

@@ -1,6 +1,7 @@
-export { dispatchCachedTaskCheck } from "./cached-orchestrator.js";
+export { type CachedCheckOptions, dispatchCachedTaskCheck } from "./cached-orchestrator.js";
 export { CHECK_GRAPH_REQUIRED_NAMESPACES, CONSUMER_GATE_INTEGRITY_RECOVERY, type ConsumerGateIntegrityFinding, type ConsumerGateIntegrityResult, type ConsumerGateIntegritySeams, checkGraphOptionalIncludeViolations, evaluateConsumerGateIntegrity, formatConsumerGateIntegrityFailure, gateLocalName, gateNamespace, includeTaskfileRel, parseTaskfileIncludes, requiredNamespacesForGates, taskDefinedInTaskfileYaml, } from "./consumer-gate-integrity.js";
-export { type CheckGateSpec, CONSUMER_CHECK_GATES, checkGateId, checkGateSpawnArgs, FRAMEWORK_CHECK_GATES, gatesForCheckTarget, isFastBeforeSlowOrder, isSuiteCheckGate, SUITE_CHECK_GATE_IDS, } from "./gate-lists.js";
+export { type CheckGateSpec, CONSUMER_CHECK_GATES, checkGateId, checkGateSpawnArgs, FRAMEWORK_CHECK_GATES, gatesForCheckTarget, isFastBeforeSlowOrder, isSuiteCheckGate, PRODUCT_FIRST_AC_GATE, SUITE_CHECK_GATE_IDS, } from "./gate-lists.js";
+export { extractGateCause, formatDegradedSkipReport, formatNamedCauseFailure, type NamedCauseMessage, remedyForGate, } from "./named-cause.js";
 export type { CheckOrchestratorOptions, CheckOrchestratorSeams } from "./orchestrator.js";
 export { dispatchTaskCheck, isFrameworkRepoRoot, isFrameworkSourceContext, resolveCheckTarget, } from "./orchestrator.js";
 export { detectTestRunner, type RunnerDetectResult, runnerDetectionTable, type TestRunnerKind, } from "./runner-detect.js";

package/dist/check/index.js

@@ -1,6 +1,7 @@
 export { dispatchCachedTaskCheck } from "./cached-orchestrator.js";
 export { CHECK_GRAPH_REQUIRED_NAMESPACES, CONSUMER_GATE_INTEGRITY_RECOVERY, checkGraphOptionalIncludeViolations, evaluateConsumerGateIntegrity, formatConsumerGateIntegrityFailure, gateLocalName, gateNamespace, includeTaskfileRel, parseTaskfileIncludes, requiredNamespacesForGates, taskDefinedInTaskfileYaml, } from "./consumer-gate-integrity.js";
-export { CONSUMER_CHECK_GATES, checkGateId, checkGateSpawnArgs, FRAMEWORK_CHECK_GATES, gatesForCheckTarget, isFastBeforeSlowOrder, isSuiteCheckGate, SUITE_CHECK_GATE_IDS, } from "./gate-lists.js";
+export { CONSUMER_CHECK_GATES, checkGateId, checkGateSpawnArgs, FRAMEWORK_CHECK_GATES, gatesForCheckTarget, isFastBeforeSlowOrder, isSuiteCheckGate, PRODUCT_FIRST_AC_GATE, SUITE_CHECK_GATE_IDS, } from "./gate-lists.js";
+export { extractGateCause, formatDegradedSkipReport, formatNamedCauseFailure, remedyForGate, } from "./named-cause.js";
 export { dispatchTaskCheck, isFrameworkRepoRoot, isFrameworkSourceContext, resolveCheckTarget, } from "./orchestrator.js";
 export { detectTestRunner, runnerDetectionTable, } from "./runner-detect.js";
 //# sourceMappingURL=index.js.map

package/dist/check/named-cause.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Named-cause + remedy formatting for check gate failures (#3282).
+ *
+ * Gate failures must never be bare exit 1: report gate name, cause, and remedy
+ * without embedding env values.
+ */
+export interface NamedCauseMessage {
+    readonly gateId: string;
+    readonly exitCode: number;
+    readonly cause: string;
+    readonly remedy: string;
+    readonly lines: readonly string[];
+}
+/**
+ * Extract a short cause from gate stdout/stderr without leaking env values.
+ * Strips lines that look like KEY=value assignments.
+ */
+export declare function extractGateCause(stdout: string, stderr: string, exitCode: number, spawnError?: string): string;
+export declare function remedyForGate(gateId: string, cause: string): string;
+/**
+ * Format named-cause failure lines for a single gate.
+ */
+export declare function formatNamedCauseFailure(input: {
+    readonly gateId: string;
+    readonly exitCode: number;
+    readonly stdout?: string;
+    readonly stderr?: string;
+    readonly spawnError?: string;
+}): NamedCauseMessage;
+/**
+ * Format degraded-mode skip report (which gates skipped and why).
+ */
+export declare function formatDegradedSkipReport(input: {
+    readonly reason: string;
+    readonly skipped: readonly {
+        id: string;
+        cause: string;
+        remedy: string;
+    }[];
+    readonly ran?: readonly string[];
+    readonly failed?: readonly string[];
+    /** Default 2 = config/environment (never green-pass skipped required gates). */
+    readonly exitCode?: number;
+}): readonly string[];
+//# sourceMappingURL=named-cause.d.ts.map

package/dist/check/named-cause.js

@@ -0,0 +1,121 @@
+/**
+ * Named-cause + remedy formatting for check gate failures (#3282).
+ *
+ * Gate failures must never be bare exit 1: report gate name, cause, and remedy
+ * without embedding env values.
+ */
+/** Per-gate remedy hints (static; no env interpolation). */
+const GATE_REMEDIES = {
+    "verify:branch": "Create a feature branch (`git switch -c feat/<name>`) or set plan.policy.allowDirectCommitsToMaster with confirmation",
+    "verify:encoding": "Fix non-ASCII / encoding issues flagged by the gate; re-run task verify:encoding",
+    "verify:cache-fresh": "Run task cache:fetch-all or task triage:bootstrap to refresh the cache",
+    "verify:orphan-active": "Complete or cancel active xBRIEFs whose issues are closed / PRs merged (task scope:complete / scope:cancel)",
+    "verify:wip-cap": "Demote stale pending scopes (task scope:demote) or raise plan.policy.wipCap deliberately",
+    doctor: "Run task doctor and follow the named recovery steps",
+    "toolchain:check": "Install missing maintainer tools reported by the gate (go, uv, git, gh, node, pnpm)",
+    "toolchain:check-consumer": "Install missing consumer tools: go-task, git, gh, node, pnpm (corepack enable && corepack prepare pnpm@latest --activate)",
+    "ts:check-lane": "Fix lint/type/test failures; re-run task ts:check-lane",
+    "vbrief:validate": "Fix xBRIEF/vBRIEF schema errors reported by the gate",
+    "verify-strategy-output": "Re-run strategy output or fix non-conformant scope filenames / PROJECT-DEFINITION",
+    "verify:test-boundary": "Move tests to the allowed placement or update plan.policy test-boundary allowlist",
+    "verify:scope-provenance": "Record approved scope provenance for the failing paths",
+    "verify:consumer-check-contract": "Align consumer Taskfile includes with the required gate graph",
+    "verify:forward-coverage": "Add tests covering new source files (task verify:forward-coverage)",
+    "verify:scm-boundary": "Move SCM mutations off GraphQL-heavy paths or wait for rate-limit reset",
+    "verify:license-sync": "Sync LICENSE / package license fields",
+    "verify:agents-md-budget": "Trim AGENTS.md managed section or raise plan.policy.agentsMdBudget deliberately",
+};
+const SPAWN_ERROR_REMEDY = "Install go-task (https://taskfile.dev/installation/) and ensure `task` is on PATH; then re-run task check";
+/**
+ * Extract a short cause from gate stdout/stderr without leaking env values.
+ * Strips lines that look like KEY=value assignments.
+ */
+export function extractGateCause(stdout, stderr, exitCode, spawnError) {
+    if (spawnError !== undefined && spawnError.length > 0) {
+        // Normalize common missing-binary messages without path dumps.
+        if (/ENOENT|not found|not recognized/i.test(spawnError)) {
+            return "task binary not found on PATH (cannot spawn go-task)";
+        }
+        return sanitizeCauseLine(spawnError);
+    }
+    const combined = `${stderr}\n${stdout}`
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+    for (const line of combined) {
+        if (looksLikeEnvLeak(line))
+            continue;
+        if (line.startsWith("check:"))
+            continue;
+        return sanitizeCauseLine(line);
+    }
+    return `gate exited ${exitCode} without a diagnostic message`;
+}
+function looksLikeEnvLeak(line) {
+    // Avoid echoing DEFT_*= or generic env dumps.
+    if (/^[A-Z][A-Z0-9_]*=/.test(line))
+        return true;
+    if (/\bDEFT_[A-Z0-9_]+\b/.test(line) && line.includes("="))
+        return true;
+    return false;
+}
+function sanitizeCauseLine(line) {
+    // Cap length; collapse absolute home paths lightly.
+    let out = line.replace(/\r/g, "").trim();
+    if (out.length > 240) {
+        out = `${out.slice(0, 237)}...`;
+    }
+    return out;
+}
+export function remedyForGate(gateId, cause) {
+    if (/task binary not found|cannot spawn go-task/i.test(cause)) {
+        return SPAWN_ERROR_REMEDY;
+    }
+    if (/pnpm binary not found|pnpm: NOT FOUND/i.test(cause)) {
+        return "Enable pnpm: corepack enable && corepack prepare pnpm@latest --activate";
+    }
+    return (GATE_REMEDIES[gateId] ??
+        `Re-run the gate for details: task ${gateId}  (or task check); fix the reported product/process defect`);
+}
+/**
+ * Format named-cause failure lines for a single gate.
+ */
+export function formatNamedCauseFailure(input) {
+    const cause = extractGateCause(input.stdout ?? "", input.stderr ?? "", input.exitCode, input.spawnError);
+    const remedy = remedyForGate(input.gateId, cause);
+    const lines = [
+        `check: gate ${input.gateId} failed (exit ${input.exitCode})`,
+        `  cause: ${cause}`,
+        `  remedy: ${remedy}`,
+    ];
+    return {
+        gateId: input.gateId,
+        exitCode: input.exitCode,
+        cause,
+        remedy,
+        lines,
+    };
+}
+/**
+ * Format degraded-mode skip report (which gates skipped and why).
+ */
+export function formatDegradedSkipReport(input) {
+    const exitCode = input.exitCode ?? 2;
+    const lines = [
+        `check: degraded mode — ${input.reason}`,
+        `check: skipped ${input.skipped.length} gate(s) due to missing framework toolchain (#3282):`,
+    ];
+    for (const gate of input.skipped) {
+        lines.push(`  - ${gate.id}: cause: ${gate.cause}; remedy: ${gate.remedy}`);
+    }
+    if (input.ran !== undefined && input.ran.length > 0) {
+        lines.push(`check: ran: ${input.ran.join(", ")}`);
+    }
+    if (input.failed !== undefined && input.failed.length > 0) {
+        lines.push(`check: failed: ${input.failed.join(", ")}`);
+    }
+    lines.push(`check: exit ${exitCode} (degraded/config) — skipped required gates are not a green pass; ` +
+        "install missing tooling (see remedies above) and re-run task check");
+    return lines;
+}
+//# sourceMappingURL=named-cause.js.map

package/dist/check/orchestrator.js

@@ -57,7 +57,12 @@ export function dispatchTaskCheck(frameworkRoot, projectRoot, seams = {}) {
         timeoutMs: seams.timeoutMs,
     });
     if (result.error !== undefined) {
-        process.stderr.write(`check: failed to invoke task: ${result.error.message}\n`);
+        // #3282: named cause + remedy instead of bare spawn failure.
+        const detail = result.error.message;
+        const missingTask = /ENOENT|not found|not recognized/i.test(detail);
+        process.stderr.write(`check: gate ${target} failed (exit 2)\n` +
+            `  cause: ${missingTask ? "task binary not found on PATH (cannot spawn go-task)" : detail}\n` +
+            "  remedy: Install go-task (https://taskfile.dev/installation/) and ensure `task` is on PATH; then re-run task check\n");
         return 2;
     }
     if (result.signal === "SIGTERM" && result.status === null && seams.timeoutMs !== undefined) {

package/dist/doctor/checks.d.ts

@@ -1,9 +1,42 @@
+import type { XbriefSchemaDistance } from "../staleness-tickler/types.js";
 import type { CheckResult } from "./types.js";
+/** Remediation verb for project envelope behind-major (#2971 / #3243 / #3236). */
+export declare const XBRIEF_ENVELOPE_MIGRATE_COMMAND: "deft migrate:xbrief";
+/** Doctor check name for envelope major mismatch (Q5 Option 2, #3243). */
+export declare const XBRIEF_ENVELOPE_MAJOR_CHECK: "xbrief-envelope-version";
 export interface CheckSeams {
     readonly readText?: (path: string) => string | null;
     readonly isFile?: (path: string) => boolean;
     readonly isDir?: (path: string) => boolean;
+    /** List directory entries; throws on enum failure (fail-closed for live lifecycle dirs). */
+    readonly readdir?: (path: string) => string[];
 }
+/** One scanned project envelope and its schema distance vs the framework target. */
+export interface XbriefEnvelopeScanEntry {
+    readonly relativePath: string;
+    readonly declaredVersion: string | null;
+    readonly distance: XbriefSchemaDistance;
+}
+/**
+ * Scan live project xbrief envelopes (PROJECT-DEFINITION + pending/active) for
+ * schema distance vs the installed framework envelope major (#3243). Complements
+ * #2971 PROJECT-DEFINITION-only probe; remediation aligns with migrate hybrid
+ * rewrite (#3236).
+ */
+export declare function scanXbriefEnvelopeVersions(projectRoot: string, seams?: CheckSeams, targetVersion?: string): {
+    readonly targetVersion: string;
+    readonly entries: readonly XbriefEnvelopeScanEntry[];
+    readonly worstDistance: XbriefSchemaDistance | null;
+    readonly behindMajor: readonly XbriefEnvelopeScanEntry[];
+};
+/**
+ * Fail closed when any scanned project xBRIEF envelope declares a major behind
+ * the framework target (#3243 / epic #3237 Q5 Option 2). Behind-minor does not
+ * fail this check. Remediation: `deft migrate:xbrief` (rewrites hybrid 0.6 on
+ * already-xbrief trees — #3236). Distinct from `stale-xbrief-schema-deposit`
+ * which routes schema-only drift to `directive update`.
+ */
+export declare function checkXbriefEnvelopeMajorVersion(projectRoot: string, seams?: CheckSeams): CheckResult;
 export declare function checkQuickStartResolves(projectRoot: string, installRoot: string | null, seams?: CheckSeams): CheckResult;
 export declare function checkSkillPathsResolve(projectRoot: string, agentsMdText: string, seams?: CheckSeams): CheckResult;
 export declare function checkManifestAgreement(projectRoot: string, installRoot: string | null, seams?: CheckSeams): CheckResult;
@@ -60,6 +93,17 @@ export declare function checkGitignoreCoverage(projectRoot: string, seams?: Chec
  * Decided-off is quiet; dismiss-with-reason is pass with reason in detail.
  * Invalid typed blocks resolve fail-closed and surface via source=default-on-error.
  */
+/**
+ * Fail closed when completed/ plan.status disagrees with the folder (#3242 AC1 / epic #3237 Q4).
+ * Open plan.items under completed/ are reported by `checkCompletedOpenItems` (exit-exempt
+ * until historical corpora are backfilled; scope:complete enforces items hard).
+ */
+export declare function checkCompletedLifecycleConsistency(projectRoot: string): CheckResult;
+/**
+ * Surface non-terminal plan.items under completed/ (#3242). Exit-exempt so
+ * historical pre-#2862 corpora do not red-light doctor; scope:complete fails closed.
+ */
+export declare function checkCompletedOpenItems(projectRoot: string): CheckResult;
 export declare function checkCoverageCheckResumePolicy(projectRoot: string): CheckResult;
 export declare function deriveExitCode(checks: readonly CheckResult[], errors: readonly string[]): number;
 export declare function runChecksImpl(projectRoot: string, seams?: CheckSeams & {