@deftai/directive-core 0.104.0 → 0.106.0

package/dist/lifecycle/completed-tracked-on-delivery.js

@@ -198,13 +198,16 @@ export function resolveDeliveryTip(projectRoot, tipOverride, runGit) {
             return { tip: candidate, error: null };
         }
     }
-    // Last resort: HEAD of current checkout (still a real tip for fixtures).
-    if (refExists(projectRoot, "HEAD", runGit)) {
-        return { tip: "HEAD", error: null };
-    }
+    // ⊗ HEAD fallback (#3478 review). This gate exists to prove an artifact landed
+    // on the delivery tip rather than on feature-worktree HEAD; falling back to
+    // HEAD when the delivery ref is missing (shallow clone, unfetched worktree,
+    // fetch-depth:1 checkout) checks the very branch whose land is in question and
+    // silently passes. Unresolvable delivery tip must fail closed -- pass an
+    // explicit --tip (e.g. --tip HEAD for an in-flight land PR) to opt in.
     return {
         tip: null,
-        error: `could not resolve delivery tip for branch '${branch}' (no origin/${branch}, ${branch}, or HEAD)`,
+        error: `could not resolve delivery tip for branch '${branch}' (no origin/${branch} or ${branch}); ` +
+            "fetch the delivery branch or pass an explicit --tip",
     };
 }
 function listTreePaths(projectRoot, tip, prefixes, runGit) {
@@ -270,6 +273,28 @@ function issuesFromBlobPaths(projectRoot, tip, paths, defaultRepo, runGit, origi
     }
     return hits;
 }
+/**
+ * Narrow the origin map to the requested issue.
+ *
+ * Matching is repo-scoped when the caller's repo is known (#3478 review): a
+ * corpus entry for another repository's same-numbered issue must NOT survive
+ * this filter. Letting it through leaves `originMap` non-empty, which suppresses
+ * the synthesis below and makes the gate resolve the wrong `repo#number` --
+ * a foreign open issue then green-skips an unlanded local one.
+ */
+function filterOriginsByIssue(originMap, issue, repo) {
+    const out = new Map();
+    for (const [key, entry] of originMap) {
+        if (entry.issue.number !== issue) {
+            continue;
+        }
+        if (repo !== null && entry.issue.repo !== repo) {
+            continue;
+        }
+        out.set(key, entry);
+    }
+    return out;
+}
 function mergeOrigins(hits) {
     const map = new Map();
     for (const hit of hits) {
@@ -353,7 +378,47 @@ export function evaluateCompletedTracked(projectRoot, options = {}) {
     const localHits = scanLocalOrigins(root, defaultRepo);
     const tipNonterminalPaths = listTreePaths(root, tip, nonterminalPrefixes(), runGit);
     const tipNonterminalHits = issuesFromBlobPaths(root, tip, tipNonterminalPaths, defaultRepo, runGit, `tip:${tip}`);
-    const originMap = mergeOrigins([...localHits, ...tipNonterminalHits]);
+    let originMap = mergeOrigins([...localHits, ...tipNonterminalHits]);
+    // Delivery tip only — the land invariant is post-merge tip truth (#3264 AC).
+    // Lifecycle PRs that commit completed/ on a feature branch are not expected
+    // to satisfy this gate until merge; run the verb with --tip HEAD when
+    // validating an in-flight land PR. The gate is a standalone verify verb
+    // (not wired into check:consumer) so product PRs are not deadlocked.
+    const tipTerminalPaths = listTreePaths(root, tip, terminalPrefixes(), runGit);
+    const tipTerminalHits = issuesFromBlobPaths(root, tip, tipTerminalPaths, defaultRepo, runGit, `tip:${tip}`);
+    const landedKeys = new Set(tipTerminalHits.map((h) => issueKey(h.issue)));
+    const issueFilter = options.issue ?? null;
+    if (issueFilter !== null) {
+        if (!Number.isInteger(issueFilter) || issueFilter <= 0) {
+            return {
+                code: 2,
+                message: `verify:completed-tracked: --issue must be a positive integer (got ${issueFilter})`,
+                stream: "stderr",
+                missing: [],
+                tip,
+            };
+        }
+        originMap = filterOriginsByIssue(originMap, issueFilter, defaultRepo);
+        // Drive-to DONE must not green-skip a named origin with no local brief
+        // (#3476). Synthesize the requested issue so closed+unlanded fails.
+        if (originMap.size === 0) {
+            if (defaultRepo === null) {
+                return {
+                    code: 2,
+                    message: `verify:completed-tracked: --issue ${issueFilter} requires --repo or a resolvable ` +
+                        "origin remote when no scoped xBRIEF origin is present.",
+                    stream: "stderr",
+                    missing: [],
+                    tip,
+                };
+            }
+            const synthetic = {
+                issue: { repo: defaultRepo, number: issueFilter },
+                origins: [`--issue ${issueFilter}`],
+            };
+            originMap.set(issueKey(synthetic.issue), synthetic);
+        }
+    }
     if (originMap.size === 0) {
         if (quiet) {
             return { code: 0, message: "", stream: "none", missing: [], tip };
@@ -366,14 +431,6 @@ export function evaluateCompletedTracked(projectRoot, options = {}) {
             tip,
         };
     }
-    // Delivery tip only — the land invariant is post-merge tip truth (#3264 AC).
-    // Lifecycle PRs that commit completed/ on a feature branch are not expected
-    // to satisfy this gate until merge; run the verb with --tip HEAD when
-    // validating an in-flight land PR. The gate is a standalone verify verb
-    // (not wired into check:consumer) so product PRs are not deadlocked.
-    const tipTerminalPaths = listTreePaths(root, tip, terminalPrefixes(), runGit);
-    const tipTerminalHits = issuesFromBlobPaths(root, tip, tipTerminalPaths, defaultRepo, runGit, `tip:${tip}`);
-    const landedKeys = new Set(tipTerminalHits.map((h) => issueKey(h.issue)));
     const missing = [];
     for (const [key, entry] of originMap) {
         if (landedKeys.has(key)) {
@@ -383,10 +440,20 @@ export function evaluateCompletedTracked(projectRoot, options = {}) {
         if (state === "open") {
             continue;
         }
-        // Closed: always fail. Unknown with live expected (!skipGh): also fail —
-        // cannot prove the issue is still open, so do not green-skip land debt
-        // (#3264 Greptile residual on live lookup failure).
-        if (state === "closed" || (state === null && !skipGh)) {
+        // Closed: always fail.
+        //
+        // Unknown: fail when live lookup was expected (!skipGh) -- cannot prove the
+        // issue is still open, so do not green-skip land debt (#3264 Greptile
+        // residual on live lookup failure).
+        //
+        // Unknown also fails for an explicitly named --issue even under --skip-gh
+        // (#3478 review): that is the drive-to DONE form, where the caller asserts
+        // this specific issue is done. An uncached issue must not exit 0 there --
+        // otherwise --skip-gh silently turns the DONE gate into a no-op. The
+        // unscoped corpus scan keeps the offline allowance, since a cold cache
+        // legitimately knows nothing about most scoped issues.
+        const unknownIsTerminal = !skipGh || issueFilter !== null;
+        if (state === "closed" || (state === null && unknownIsTerminal)) {
             missing.push(entry);
         }
     }

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