@deftai/directive-core 0.105.0 → 0.107.0

package/dist/lifecycle/completed-write-guard.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Refuse newly added completed/ blobs that bypass runTransition (#3679).
+ *
+ * Historical corpus is advisory (doctor). New work in the change set is hard
+ * (verify:completed-write-guard). Does not read completionProvenance and does
+ * not change verify:completed-tracked.
+ *
+ * Disk reads are capped at COMPLETED_WRITE_GUARD_MAX_BYTES so a huge
+ * contributor-controlled completed/ add fails through the guard instead of
+ * exhausting memory on the required gate path.
+ */
+export type CompletedWriteGuardCode = 0 | 1 | 2;
+export interface CompletedWriteGuardFinding {
+    readonly relPath: string;
+    readonly detail: string;
+}
+export interface CompletedWriteGuardResult {
+    readonly code: CompletedWriteGuardCode;
+    readonly message: string;
+    readonly findings: readonly CompletedWriteGuardFinding[];
+}
+export interface CompletedWriteGuardOptions {
+    readonly baseRef?: string;
+    /** Inject added repo-relative POSIX paths (skips git). */
+    readonly addedFiles?: readonly string[];
+    /** Inject payloads: relPath -> raw JSON. */
+    readonly payloads?: ReadonlyMap<string, string>;
+}
+/**
+ * In-repo completed xBRIEFs average ~5.5 KiB and peak near 44 KiB.
+ * 1 MiB is ~23× that peak and still refuses a multi-hundred-MB add
+ * before the bytes are loaded.
+ */
+export declare const COMPLETED_WRITE_GUARD_MAX_BYTES = 1048576;
+/**
+ * Hard check: newly added completed/ artifacts must show runTransition evidence.
+ */
+export declare function evaluateCompletedWriteGuard(projectRoot: string, options?: CompletedWriteGuardOptions): CompletedWriteGuardResult;
+export interface CompletedWriteCorpusResult {
+    readonly findings: readonly CompletedWriteGuardFinding[];
+    readonly scanned: number;
+}
+/**
+ * Corpus scan for doctor: artifacts without transition evidence.
+ * Caller marks these advisory so historical pre-stamp files do not red doctor.
+ */
+export declare function scanCompletedWriteCorpus(projectRoot: string): CompletedWriteCorpusResult;
+//# sourceMappingURL=completed-write-guard.d.ts.map

package/dist/lifecycle/completed-write-guard.js

@@ -0,0 +1,373 @@
+/**
+ * Refuse newly added completed/ blobs that bypass runTransition (#3679).
+ *
+ * Historical corpus is advisory (doctor). New work in the change set is hard
+ * (verify:completed-write-guard). Does not read completionProvenance and does
+ * not change verify:completed-tracked.
+ *
+ * Disk reads are capped at COMPLETED_WRITE_GUARD_MAX_BYTES so a huge
+ * contributor-controlled completed/ add fails through the guard instead of
+ * exhausting memory on the required gate path.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, lstatSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { GitCommandError, GitNotFoundError } from "../encoding/git.js";
+import { hasArtifactSuffix, LEGACY_ARTIFACT_DIR, MIGRATED_ARTIFACT_DIR, } from "../layout/resolve.js";
+import { hasTransitionWrite, LEFTOVER_LAND_PR_REMEDIATION } from "../scope/lifecycle-write.js";
+import { resolveDefaultBaseRef, unquoteGitPath } from "../scope-provenance/evaluate.js";
+/**
+ * In-repo completed xBRIEFs average ~5.5 KiB and peak near 44 KiB.
+ * 1 MiB is ~23× that peak and still refuses a multi-hundred-MB add
+ * before the bytes are loaded.
+ */
+export const COMPLETED_WRITE_GUARD_MAX_BYTES = 1_048_576;
+const COMPLETED_REL_RE = /^(?:xbrief|vbrief)\/completed\/[^/]+$/;
+function normalizeRepoRelPath(raw) {
+    return raw.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function isCompletedArtifactRel(relPath) {
+    const n = normalizeRepoRelPath(relPath);
+    if (!COMPLETED_REL_RE.test(n)) {
+        return false;
+    }
+    const base = n.split("/").pop() ?? "";
+    return hasArtifactSuffix(base);
+}
+function parsePlan(raw) {
+    try {
+        const data = JSON.parse(raw);
+        if (typeof data !== "object" || data === null || Array.isArray(data)) {
+            return null;
+        }
+        const plan = data.plan;
+        if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+            return null;
+        }
+        return plan;
+    }
+    catch {
+        return null;
+    }
+}
+function gitEnv(projectRoot) {
+    const env = { ...process.env };
+    delete env.GIT_DIR;
+    delete env.GIT_WORK_TREE;
+    env.GIT_CEILING_DIRECTORIES = dirname(resolve(projectRoot));
+    return env;
+}
+function git(args, projectRoot) {
+    const result = spawnSync("git", args, {
+        cwd: projectRoot,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        env: gitEnv(projectRoot),
+    });
+    if (result.error !== undefined) {
+        const e = result.error;
+        if (e.code === "ENOENT") {
+            throw new GitNotFoundError("'git' executable not found on PATH");
+        }
+        throw new GitCommandError(`git ${args.join(" ")} failed: ${String(e.message)}`);
+    }
+    if (result.signal !== null && result.signal !== undefined) {
+        throw new GitCommandError(`git ${args.join(" ")} killed by signal ${String(result.signal)}`);
+    }
+    const status = result.status ?? 1;
+    const stderr = String(result.stderr ?? "").trim();
+    if (status !== 0 && stderr.length > 0) {
+        return { status, stdout: `${result.stdout ?? ""}\n${stderr}` };
+    }
+    return { status, stdout: result.stdout ?? "" };
+}
+function addedPathsFromNameStatus(stdout) {
+    const out = [];
+    for (const line of stdout.split("\n")) {
+        const t = line.replace(/\r$/, "").trim();
+        if (t.length === 0) {
+            continue;
+        }
+        const parts = t.split("\t");
+        const status = parts[0] ?? "";
+        if (status.startsWith("A")) {
+            const path = parts[1];
+            if (path !== undefined) {
+                out.push(unquoteGitPath(path));
+            }
+        }
+        else if (status.startsWith("R")) {
+            const dest = parts[2] ?? parts[1];
+            if (dest !== undefined) {
+                out.push(unquoteGitPath(dest));
+            }
+        }
+    }
+    return out;
+}
+function discoverAddedFiles(projectRoot, baseRef) {
+    const inside = git(["rev-parse", "--is-inside-work-tree"], projectRoot);
+    if (inside.status !== 0) {
+        throw new GitCommandError("not a git working tree");
+    }
+    let resolved = baseRef;
+    if (baseRef === "HEAD" || baseRef === "") {
+        const upgraded = resolveDefaultBaseRef(projectRoot);
+        if (upgraded === null) {
+            throw new GitCommandError("no merge-base ref (origin/master|main or DEFT_BASE_REF/GITHUB_BASE_REF)");
+        }
+        resolved = upgraded;
+    }
+    const hasBase = git(["rev-parse", "--verify", "-q", resolved], projectRoot).status === 0;
+    if (!hasBase) {
+        throw new GitCommandError(`base ref '${resolved}' not found; pass --base-ref`);
+    }
+    const out = new Set();
+    const range = resolved.includes("...") ? resolved : `${resolved}...HEAD`;
+    const committed = git(["diff", "--name-status", "--diff-filter=AR", range], projectRoot);
+    if (committed.status !== 0) {
+        const detail = committed.stdout.trim() || `git diff ${range} exited ${String(committed.status)}`;
+        throw new GitCommandError(`committed change-set unavailable for '${range}': ${detail}. ` +
+            "Pass --base-ref to a merge-base ancestor of HEAD.");
+    }
+    for (const p of addedPathsFromNameStatus(committed.stdout)) {
+        out.add(normalizeRepoRelPath(p));
+    }
+    const vsHead = git(["diff", "--name-status", "--diff-filter=AR", "HEAD"], projectRoot);
+    if (vsHead.status !== 0) {
+        const detail = vsHead.stdout.trim() || `git diff HEAD exited ${String(vsHead.status)}`;
+        throw new GitCommandError(`working-tree change-set unavailable: ${detail}`);
+    }
+    for (const p of addedPathsFromNameStatus(vsHead.stdout)) {
+        out.add(normalizeRepoRelPath(p));
+    }
+    const untracked = git(["ls-files", "--others", "--exclude-standard"], projectRoot);
+    if (untracked.status !== 0) {
+        const detail = untracked.stdout.trim() || `git ls-files exited ${String(untracked.status)}`;
+        throw new GitCommandError(`untracked change-set unavailable: ${detail}`);
+    }
+    for (const line of untracked.stdout.split("\n")) {
+        const p = normalizeRepoRelPath(unquoteGitPath(line));
+        if (p.length > 0) {
+            out.add(p);
+        }
+    }
+    return [...out];
+}
+function readPayload(projectRoot, relPath, payloads) {
+    const n = normalizeRepoRelPath(relPath);
+    const injected = payloads?.get(n);
+    if (injected !== undefined) {
+        if (injected.length > COMPLETED_WRITE_GUARD_MAX_BYTES) {
+            return {
+                kind: "unsafe",
+                detail: `${n}: completed/ artifact is ${String(injected.length)} bytes; ` +
+                    `exceeds the ${String(COMPLETED_WRITE_GUARD_MAX_BYTES)}-byte read limit`,
+            };
+        }
+        return { kind: "ok", raw: injected };
+    }
+    const parts = n.split("/").filter((part) => part.length > 0 && part !== ".");
+    let abs = resolve(projectRoot);
+    let st;
+    for (const part of parts) {
+        if (part === "..") {
+            return {
+                kind: "unsafe",
+                detail: `${n}: completed/ path escapes project root; refuse without following`,
+            };
+        }
+        abs = join(abs, part);
+        try {
+            st = lstatSync(abs);
+        }
+        catch {
+            return { kind: "missing" };
+        }
+        if (st.isSymbolicLink()) {
+            return {
+                kind: "unsafe",
+                detail: `${n}: completed/ path contains a symlink; refuse without following`,
+            };
+        }
+    }
+    if (st === undefined || !st.isFile()) {
+        return {
+            kind: "unsafe",
+            detail: `${n}: completed/ add is not a regular file; refuse without reading`,
+        };
+    }
+    if (st.size > COMPLETED_WRITE_GUARD_MAX_BYTES) {
+        return {
+            kind: "unsafe",
+            detail: `${n}: completed/ artifact is ${String(st.size)} bytes; ` +
+                `exceeds the ${String(COMPLETED_WRITE_GUARD_MAX_BYTES)}-byte read limit`,
+        };
+    }
+    try {
+        return { kind: "ok", raw: readFileSync(abs, "utf8") };
+    }
+    catch {
+        return { kind: "missing" };
+    }
+}
+/**
+ * Hard check: newly added completed/ artifacts must show runTransition evidence.
+ */
+export function evaluateCompletedWriteGuard(projectRoot, options = {}) {
+    const root = resolve(projectRoot);
+    let added;
+    try {
+        if (options.addedFiles !== undefined) {
+            added = options.addedFiles.map(normalizeRepoRelPath);
+        }
+        else {
+            const inside = git(["rev-parse", "--is-inside-work-tree"], root);
+            if (inside.status !== 0 || inside.stdout.trim() !== "true") {
+                return {
+                    code: 0,
+                    findings: [],
+                    message: "verify_completed_write_guard: skipped -- not a git working tree.",
+                };
+            }
+            let baseRef = options.baseRef ?? "";
+            if (baseRef.length === 0 || baseRef === "HEAD") {
+                const resolved = resolveDefaultBaseRef(root);
+                if (resolved === null) {
+                    return {
+                        code: 2,
+                        findings: [],
+                        message: "verify_completed_write_guard: no merge-base ref found " +
+                            "(origin/master|main, DEFT_BASE_REF, or GITHUB_BASE_REF). " +
+                            "Pass --base-ref. Unguarded completed/ adds cannot be skipped.",
+                    };
+                }
+                baseRef = resolved;
+            }
+            added = discoverAddedFiles(root, baseRef);
+        }
+    }
+    catch (err) {
+        if (err instanceof GitNotFoundError) {
+            return {
+                code: 2,
+                findings: [],
+                message: "verify_completed_write_guard: 'git' executable not found on PATH.\n" +
+                    "  Recovery: install git or run inside a git working tree.",
+            };
+        }
+        if (err instanceof GitCommandError) {
+            const msg = err.message.toLowerCase();
+            if (msg.includes("not a git repository") ||
+                msg.includes("outside repository") ||
+                msg.includes("not a git working tree")) {
+                return {
+                    code: 0,
+                    findings: [],
+                    message: `verify_completed_write_guard: skipped -- not a git working tree (${err.message}).`,
+                };
+            }
+            return {
+                code: 2,
+                findings: [],
+                message: `verify_completed_write_guard: git failed -- ${err.message}`,
+            };
+        }
+        throw err;
+    }
+    const findings = [];
+    for (const rel of added) {
+        if (!isCompletedArtifactRel(rel)) {
+            continue;
+        }
+        const payload = readPayload(root, rel, options.payloads);
+        if (payload.kind === "missing") {
+            findings.push({
+                relPath: rel,
+                detail: `${rel}: added under completed/ but unreadable`,
+            });
+            continue;
+        }
+        if (payload.kind === "unsafe") {
+            findings.push({
+                relPath: rel,
+                detail: payload.detail,
+            });
+            continue;
+        }
+        const plan = parsePlan(payload.raw);
+        if (plan === null) {
+            findings.push({
+                relPath: rel,
+                detail: `${rel}: added under completed/ with unreadable plan`,
+            });
+            continue;
+        }
+        if (!hasTransitionWrite(plan)) {
+            findings.push({
+                relPath: rel,
+                detail: `${rel}: added under completed/ without a runTransition write`,
+            });
+        }
+    }
+    if (findings.length === 0) {
+        return {
+            code: 0,
+            findings: [],
+            message: "verify_completed_write_guard: clean -- no unguarded completed/ adds",
+        };
+    }
+    return {
+        code: 1,
+        findings,
+        message: `verify_completed_write_guard: ${findings.length} unguarded completed/ add(s) (#3679).\n` +
+            findings.map((f) => `  - ${f.detail}`).join("\n") +
+            `\n${LEFTOVER_LAND_PR_REMEDIATION}`,
+    };
+}
+function listCompletedArtifactRels(projectRoot) {
+    const out = [];
+    for (const dirName of [MIGRATED_ARTIFACT_DIR, LEGACY_ARTIFACT_DIR]) {
+        const completedDir = join(projectRoot, dirName, "completed");
+        if (!existsSync(completedDir)) {
+            continue;
+        }
+        let names = [];
+        try {
+            names = readdirSync(completedDir).filter((n) => hasArtifactSuffix(n));
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            out.push(`${dirName}/completed/${name}`);
+        }
+    }
+    return out.sort();
+}
+/**
+ * Corpus scan for doctor: artifacts without transition evidence.
+ * Caller marks these advisory so historical pre-stamp files do not red doctor.
+ */
+export function scanCompletedWriteCorpus(projectRoot) {
+    const findings = [];
+    const rels = listCompletedArtifactRels(projectRoot);
+    for (const rel of rels) {
+        const payload = readPayload(resolve(projectRoot), rel, undefined);
+        if (payload.kind !== "ok") {
+            continue;
+        }
+        const plan = parsePlan(payload.raw);
+        if (plan === null) {
+            continue;
+        }
+        if (!hasTransitionWrite(plan)) {
+            findings.push({
+                relPath: rel,
+                detail: `${rel}: completed/ artifact has no runTransition write (historical advisory)`,
+            });
+        }
+    }
+    return { findings, scanned: rels.length };
+}
+//# sourceMappingURL=completed-write-guard.js.map

package/dist/lifecycle/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./completed-consistency.js";
 export * from "./completed-tracked-on-delivery.js";
+export * from "./completed-write-guard.js";
 export * from "./event.js";
 export * as eventDetect from "./event-detect.js";
 export * as events from "./events.js";

package/dist/lifecycle/index.js

@@ -1,5 +1,6 @@
 export * from "./completed-consistency.js";
 export * from "./completed-tracked-on-delivery.js";
+export * from "./completed-write-guard.js";
 export * from "./event.js";
 export * as eventDetect from "./event-detect.js";
 export * as events from "./events.js";

package/dist/lifecycle-visible/evaluate.d.ts

@@ -0,0 +1,98 @@
+/**
+ * verify:lifecycle-visible — detect ignore/index flags that hide lifecycle roots (#3505).
+ *
+ * Warn-only by default (exit 0). Pass --enforce to fail closed.
+ * Not a task-check gate: this is a per-clone environment property.
+ */
+import { type GitRunner } from "../session/git.js";
+export declare const LIFECYCLE_ROOT_PREFIXES: readonly ["xbrief", "vbrief"];
+export declare const LIFECYCLE_STAGE_DIRS: readonly ["proposed", "pending", "active", "completed", "cancelled"];
+export type LifecycleHideKind = "ignored" | "skip-worktree" | "assume-unchanged";
+export interface LifecycleHideFinding {
+    readonly path: string;
+    readonly kind: LifecycleHideKind;
+    readonly source: string;
+    readonly line: number | null;
+    readonly rule: string;
+    readonly raw: string;
+}
+export interface LifecycleVisibleOptions {
+    readonly projectRoot: string;
+    readonly enforce?: boolean;
+    readonly runGit?: GitRunner;
+}
+export interface LifecycleVisibleResult {
+    readonly code: 0 | 1 | 2;
+    readonly message: string;
+    readonly stream: "stdout" | "stderr";
+    readonly findings: readonly LifecycleHideFinding[];
+    readonly enforce: boolean;
+    readonly failOpen: boolean;
+}
+export interface CheckIgnoreMatch {
+    readonly source: string;
+    readonly line: number;
+    readonly pattern: string;
+    readonly path: string;
+}
+export interface LsFilesVerboseRecord {
+    readonly tag: string;
+    readonly path: string;
+}
+/** Ignore globs from one file, with the directory Git applies them against. */
+export interface IgnorePatternSource {
+    readonly baseDir: string;
+    readonly patterns: readonly string[];
+}
+/** Canonical lifecycle root pathspecs (`xbrief/active/`, `vbrief/pending/`, …). */
+export declare function lifecycleRootRelPaths(): string[];
+/** Fills `*` in ignore globs so a derived probe still matches the rule. */
+export declare const LIFECYCLE_PROBE_STEM = "lifecycle-visible";
+/**
+ * Date-prefixed brief-shaped fallback when no ignore-rule date glob exists.
+ * Date globs emit their own matching names (`2026-07-*` → a July file, `2025-*` → 2025).
+ */
+export declare const LIFECYCLE_PROBE_SENTINEL = "2026-01-01-lifecycle-visible.xbrief.json";
+/** Legacy vbrief filename so `*.vbrief.json` / `2026-*.vbrief.json` cannot report clean. */
+export declare const LIFECYCLE_PROBE_SENTINEL_VBRIEF = "2026-01-01-lifecycle-visible.vbrief.json";
+/** Stage dirs plus one matching-extension sentinel under each. */
+export declare function lifecycleIgnoreProbeRelPaths(): string[];
+/** True when an ignore glob could hide a convention-valid brief. */
+export declare function ignorePatternLooksLifecycleRelevant(pattern: string): boolean;
+/** Linear `[abc]` expansion — avoid nested regex quantifiers (CodeQL js/polynomial-redos). */
+export declare function expandGitignoreCharClasses(body: string): string;
+/**
+ * Expand one gitignore glob into a single concrete pathname that still matches it.
+ * `*` becomes {@link LIFECYCLE_PROBE_STEM}; `**` collapses; `?` becomes `0`.
+ */
+export declare function expandGitignoreGlobToConcrete(pattern: string): string | null;
+/** Join a glob-expanded probe to the ignore file's directory (Git's match root). */
+export declare function joinIgnoreFileBase(baseDir: string, concrete: string): string;
+/**
+ * One derived probe per relevant ignore-rule line (bounded by ignore-file size, not a numeric cap).
+ * Date globs keep their year/month so `2026-07-*` probes a July name, not the January fallback.
+ * Slash patterns keep the ignore-file directory; stage wildcards expand onto real stages.
+ */
+export declare function derivedLifecycleIgnoreProbesFromSources(sources: readonly IgnorePatternSource[]): string[];
+/** Ignore-file globs → check-ignore pathspecs (one per relevant rule line). */
+export declare function derivedLifecycleIgnoreProbes(projectRoot: string, runGit: GitRunner): string[];
+/** Map a check-ignore pathname back to its canonical stage root, or null if outside. */
+export declare function lifecycleRootForRelPath(relPosix: string): string | null;
+/** Deliberate hybrid ignores under a visible root must not trip the check (#1144). */
+export declare function isSelectiveLifecyclePath(relPosix: string): boolean;
+/** Map git check-ignore source paths to the actionable display form. */
+export declare function displayIgnoreSource(source: string, projectRoot: string): string;
+/**
+ * Parse one `git check-ignore -v` line: `<source>:<linenum>:<pattern>\\t<pathname>`.
+ * Source may be a Windows absolute path with a drive colon.
+ */
+export declare function parseCheckIgnoreVerboseLine(line: string): CheckIgnoreMatch | null;
+/** Parse one `git ls-files -v` record (`S path` / `h path`). */
+export declare function parseLsFilesVerboseRecord(record: string): LsFilesVerboseRecord | null;
+/** Index flag encoded by the `ls-files -v` status tag. */
+export declare function indexFlagKind(tag: string): "skip-worktree" | "assume-unchanged" | null;
+/** Session:start advisory lines — silent when clean. */
+export declare function formatLifecycleVisibleSessionLines(result: LifecycleVisibleResult): string[];
+/** Evaluate whether lifecycle roots are hidden by ignore rules or index flags (#3505). */
+export declare function evaluateLifecycleVisible(options: LifecycleVisibleOptions): LifecycleVisibleResult;
+//# sourceMappingURL=evaluate.d.ts.map