@deftai/directive-core 0.80.0 → 0.82.0

package/dist/orphan-active/evaluate.d.ts

@@ -0,0 +1,25 @@
+import type { RunGhFn } from "../pr-protected-issues/types.js";
+export type OutputStream = "stdout" | "stderr" | "none";
+export interface OrphanActiveBrief {
+    readonly path: string;
+    readonly reason: string;
+}
+export interface EvaluateResult {
+    readonly code: 0 | 1 | 2;
+    readonly message: string;
+    readonly stream: OutputStream;
+    readonly orphans: readonly OrphanActiveBrief[];
+}
+export interface EvaluateOptions {
+    readonly quiet?: boolean;
+    readonly repo?: string | null;
+    readonly runGh?: RunGhFn;
+    readonly skipGh?: boolean;
+}
+/**
+ * Pure evaluator for orphaned active/running xBRIEF detection (#2321).
+ * Fails when active/ briefs with plan.status==running reference only closed
+ * issues and/or a merged PR — the stop-at:pr-open orphan signature.
+ */
+export declare function evaluate(projectRoot: string, options?: EvaluateOptions): EvaluateResult;
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/orphan-active/evaluate.js

@@ -0,0 +1,275 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
+import { defaultRunGh } from "../pr-protected-issues/gh.js";
+import { CACHE_DIR_NAME, CACHE_SOURCE_GITHUB_ISSUE } from "../triage/queue/constants.js";
+import { resolveRepo } from "../triage/queue/repo.js";
+import { collectGithubRefs } from "./refs.js";
+function readJson(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function planOf(data) {
+    const plan = data?.plan;
+    return typeof plan === "object" && plan !== null && !Array.isArray(plan)
+        ? plan
+        : null;
+}
+function relBriefPath(path, projectRoot) {
+    try {
+        return relative(resolve(projectRoot), resolve(path)).replace(/\\/g, "/");
+    }
+    catch {
+        return path.replace(/\\/g, "/");
+    }
+}
+function listActiveRunningBriefs(projectRoot) {
+    let lifecycleRoot;
+    try {
+        lifecycleRoot = resolveLifecycleRoot(projectRoot);
+    }
+    catch {
+        return [];
+    }
+    const activeDir = join(lifecycleRoot, "active");
+    if (!existsSync(activeDir)) {
+        return [];
+    }
+    const out = [];
+    for (const entry of readdirSync(activeDir, { withFileTypes: true })) {
+        if (!entry.isFile() || !hasArtifactSuffix(entry.name)) {
+            continue;
+        }
+        const path = join(activeDir, entry.name);
+        const data = readJson(path);
+        const plan = planOf(data);
+        if (plan === null) {
+            continue;
+        }
+        if (String(plan.status ?? "").toLowerCase() !== "running") {
+            continue;
+        }
+        out.push({ path, plan });
+    }
+    return out.sort((a, b) => a.path.localeCompare(b.path));
+}
+function readCachedIssueState(projectRoot, ref) {
+    const [owner, name] = ref.repo.split("/", 2);
+    if (!owner || !name) {
+        return null;
+    }
+    const rawPath = join(projectRoot, CACHE_DIR_NAME, CACHE_SOURCE_GITHUB_ISSUE, owner, name, String(ref.number), "raw.json");
+    if (!existsSync(rawPath)) {
+        return null;
+    }
+    const raw = readJson(rawPath);
+    if (raw === null) {
+        return null;
+    }
+    const state = typeof raw.state === "string" ? raw.state.toLowerCase() : "";
+    if (state === "closed") {
+        return "closed";
+    }
+    if (state === "open") {
+        return "open";
+    }
+    return null;
+}
+function fetchIssueStateLive(ref, runGh) {
+    const path = `repos/${ref.repo}/issues/${ref.number}`;
+    const result = runGh(["gh", "api", path]);
+    if (result.returncode !== 0) {
+        return null;
+    }
+    try {
+        const payload = JSON.parse(result.stdout);
+        if (payload === null || typeof payload !== "object") {
+            return null;
+        }
+        const state = payload.state;
+        if (state === "closed") {
+            return "closed";
+        }
+        if (state === "open") {
+            return "open";
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function resolveIssueState(ref, projectRoot, runGh, skipGh) {
+    const cached = readCachedIssueState(projectRoot, ref);
+    if (cached !== null) {
+        return cached;
+    }
+    if (skipGh) {
+        return null;
+    }
+    return fetchIssueStateLive(ref, runGh);
+}
+function fetchPrMerged(ref, runGh) {
+    const path = `repos/${ref.repo}/pulls/${ref.number}`;
+    const result = runGh(["gh", "api", path]);
+    if (result.returncode !== 0) {
+        return null;
+    }
+    try {
+        const payload = JSON.parse(result.stdout);
+        if (payload === null || typeof payload !== "object") {
+            return null;
+        }
+        const mergedAt = payload.merged_at;
+        if (mergedAt === null) {
+            return false;
+        }
+        return typeof mergedAt === "string" && mergedAt.length > 0;
+    }
+    catch {
+        return null;
+    }
+}
+function assessOrphanSignature(issueRefs, prRefs, projectRoot, runGh, skipGh) {
+    for (const pr of prRefs) {
+        if (skipGh) {
+            continue;
+        }
+        const merged = fetchPrMerged(pr, runGh);
+        if (merged === true) {
+            return { orphaned: true, reason: `linked PR #${pr.number} is merged` };
+        }
+    }
+    if (issueRefs.length === 0) {
+        return { orphaned: false, reason: null };
+    }
+    let resolved = 0;
+    for (const ref of issueRefs) {
+        const state = resolveIssueState(ref, projectRoot, runGh, skipGh);
+        if (state === null) {
+            return { orphaned: false, reason: null };
+        }
+        resolved += 1;
+        if (state !== "closed") {
+            return { orphaned: false, reason: null };
+        }
+    }
+    if (resolved > 0) {
+        return { orphaned: true, reason: "all referenced issues are closed" };
+    }
+    return { orphaned: false, reason: null };
+}
+function formatRefusal(orphans, projectRoot) {
+    const lines = [
+        `verify:orphan-active: ${orphans.length} active/running xBRIEF${orphans.length === 1 ? "" : "s"} look shipped but still consume WIP (project_root=${projectRoot}).`,
+        "  Remediation: move each brief out of active/ with lifecycle ownership:",
+        "    task scope:complete -- xbrief/active/<file>.xbrief.json",
+        "    task scope:cancel -- xbrief/active/<file>.xbrief.json   # when abandoning",
+        "  For stop-at:pr-open workers the orchestrator owns post-merge complete/cancel;",
+        "  for drive-to:merge-ready workers scope:complete is part of the worker unit (#2321).",
+        "  Or run task swarm:finalize-cohort / task swarm:complete-cohort after cohort merge.",
+        "  Offending briefs:",
+    ];
+    for (const orphan of orphans) {
+        lines.push(`    - ${orphan.path} (${orphan.reason})`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Pure evaluator for orphaned active/running xBRIEF detection (#2321).
+ * Fails when active/ briefs with plan.status==running reference only closed
+ * issues and/or a merged PR — the stop-at:pr-open orphan signature.
+ */
+export function evaluate(projectRoot, options = {}) {
+    const root = resolve(projectRoot);
+    const quiet = options.quiet ?? false;
+    const skipGh = options.skipGh ?? false;
+    const runGh = options.runGh ?? defaultRunGh;
+    const defaultRepo = resolveRepo(options.repo, root);
+    if (!existsSync(root)) {
+        return {
+            code: 2,
+            message: `verify:orphan-active: project root does not exist: ${root}`,
+            stream: "stderr",
+            orphans: [],
+        };
+    }
+    let lifecycleRoot;
+    try {
+        lifecycleRoot = resolveLifecycleRoot(root);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        // Consumer/greenfield fixtures may still use legacy vbrief/ only (#2112).
+        // Orphan detection applies only to xbrief/active/ — skip cleanly, not config fail.
+        if (message.includes("No xbrief/ layout found")) {
+            if (quiet) {
+                return { code: 0, message: "", stream: "none", orphans: [] };
+            }
+            return {
+                code: 0,
+                message: "verify:orphan-active: no xbrief/ lifecycle root; nothing to scan.",
+                stream: "stdout",
+                orphans: [],
+            };
+        }
+        return {
+            code: 2,
+            message: `verify:orphan-active: ${message}`,
+            stream: "stderr",
+            orphans: [],
+        };
+    }
+    if (!existsSync(lifecycleRoot)) {
+        if (quiet) {
+            return { code: 0, message: "", stream: "none", orphans: [] };
+        }
+        return {
+            code: 0,
+            message: "verify:orphan-active: no xbrief/ lifecycle root; nothing to scan.",
+            stream: "stdout",
+            orphans: [],
+        };
+    }
+    const orphans = [];
+    for (const brief of listActiveRunningBriefs(root)) {
+        const { issues, prs } = collectGithubRefs(brief.plan, defaultRepo);
+        if (issues.length === 0 && prs.length === 0) {
+            continue;
+        }
+        const assessment = assessOrphanSignature(issues, prs, root, runGh, skipGh);
+        if (assessment.orphaned && assessment.reason !== null) {
+            orphans.push({
+                path: relBriefPath(brief.path, root),
+                reason: assessment.reason,
+            });
+        }
+    }
+    if (orphans.length > 0) {
+        return {
+            code: 1,
+            message: formatRefusal(orphans, root),
+            stream: "stderr",
+            orphans,
+        };
+    }
+    if (quiet) {
+        return { code: 0, message: "", stream: "none", orphans: [] };
+    }
+    const scanned = listActiveRunningBriefs(root).length;
+    return {
+        code: 0,
+        message: `verify:orphan-active: no orphaned active/running xBRIEFs ` +
+            `(scanned ${scanned} running brief${scanned === 1 ? "" : "s"} in active/).`,
+        stream: "stdout",
+        orphans: [],
+    };
+}
+//# sourceMappingURL=evaluate.js.map

package/dist/orphan-active/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./evaluate.js";
+export * from "./refs.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/orphan-active/index.js

@@ -0,0 +1,3 @@
+export * from "./evaluate.js";
+export * from "./refs.js";
+//# sourceMappingURL=index.js.map

package/dist/orphan-active/refs.d.ts

@@ -0,0 +1,16 @@
+export interface IssueRef {
+    readonly repo: string;
+    readonly number: number;
+}
+export interface PrRef {
+    readonly repo: string;
+    readonly number: number;
+}
+/** Parse (repo, pr_number) from a github-pr reference URI. */
+export declare function parseGithubPrUri(uri: unknown): [string | null, number | null];
+/** Collect GitHub issue and PR refs from a scope plan object. */
+export declare function collectGithubRefs(plan: Record<string, unknown>, defaultRepo: string | null): {
+    issues: IssueRef[];
+    prs: PrRef[];
+};
+//# sourceMappingURL=refs.d.ts.map

package/dist/orphan-active/refs.js

@@ -0,0 +1,105 @@
+import { referenceTypeMatches } from "@deftai/directive-types";
+import { parseGithubIssueUri } from "../triage/reconcile/parse-uri.js";
+/** Parse (repo, pr_number) from a github-pr reference URI. */
+export function parseGithubPrUri(uri) {
+    if (typeof uri !== "string") {
+        return [null, null];
+    }
+    const cleaned = uri.trim().replace(/\/$/, "");
+    if (!cleaned) {
+        return [null, null];
+    }
+    const noScheme = cleaned.includes("://") ? cleaned.split("://").slice(1).join("://") : cleaned;
+    const parts = noScheme.split("/").filter(Boolean);
+    if (parts.length >= 4 && parts[parts.length - 2] === "pull") {
+        const tail = parts[parts.length - 1] ?? "";
+        if (/^\d+$/.test(tail)) {
+            const owner = parts[parts.length - 4];
+            const repo = parts[parts.length - 3];
+            if (owner && repo) {
+                return [`${owner}/${repo}`, Number(tail)];
+            }
+        }
+    }
+    const tail = parts[parts.length - 1] ?? "";
+    if (/^\d+$/.test(tail)) {
+        return [null, Number(tail)];
+    }
+    return [null, null];
+}
+function parseTrackingIssue(value) {
+    if (typeof value === "number" && Number.isInteger(value) && value > 0) {
+        return value;
+    }
+    if (typeof value !== "string") {
+        return null;
+    }
+    const match = value.match(/#(\d+)/);
+    return match ? Number(match[1]) : null;
+}
+function addIssueRef(out, seen, repo, number, defaultRepo) {
+    if (number === null) {
+        return;
+    }
+    const resolvedRepo = repo ?? defaultRepo;
+    if (resolvedRepo === null || resolvedRepo.length === 0) {
+        return;
+    }
+    const key = `${resolvedRepo}:${number}`;
+    if (seen.has(key)) {
+        return;
+    }
+    seen.add(key);
+    out.push({ repo: resolvedRepo, number });
+}
+function addPrRef(out, seen, repo, number, defaultRepo) {
+    if (number === null) {
+        return;
+    }
+    const resolvedRepo = repo ?? defaultRepo;
+    if (resolvedRepo === null || resolvedRepo.length === 0) {
+        return;
+    }
+    const key = `${resolvedRepo}:${number}`;
+    if (seen.has(key)) {
+        return;
+    }
+    seen.add(key);
+    out.push({ repo: resolvedRepo, number });
+}
+/** Collect GitHub issue and PR refs from a scope plan object. */
+export function collectGithubRefs(plan, defaultRepo) {
+    const issues = [];
+    const prs = [];
+    const seenIssues = new Set();
+    const seenPrs = new Set();
+    const refs = plan.references;
+    if (Array.isArray(refs)) {
+        for (const ref of refs) {
+            if (typeof ref !== "object" || ref === null || Array.isArray(ref)) {
+                continue;
+            }
+            const typed = ref;
+            const type = String(typed.type ?? "");
+            if (referenceTypeMatches(type, "github-issue")) {
+                const [repo, number] = parseGithubIssueUri(typed.uri);
+                addIssueRef(issues, seenIssues, repo, number, defaultRepo);
+            }
+            else if (referenceTypeMatches(type, "github-pr")) {
+                const [repo, number] = parseGithubPrUri(typed.uri);
+                addPrRef(prs, seenPrs, repo, number, defaultRepo);
+            }
+        }
+    }
+    const metadata = plan.metadata;
+    if (typeof metadata === "object" && metadata !== null && !Array.isArray(metadata)) {
+        const tracking = metadata["x-tracking"];
+        if (typeof tracking === "object" && tracking !== null && !Array.isArray(tracking)) {
+            const t = tracking;
+            addIssueRef(issues, seenIssues, defaultRepo, parseTrackingIssue(t.parent_issue), defaultRepo);
+            addIssueRef(issues, seenIssues, defaultRepo, parseTrackingIssue(t.decomposition_origin), defaultRepo);
+        }
+    }
+    return { issues, prs };
+}
+//# sourceMappingURL=refs.js.map

package/dist/policy/index.d.ts

@@ -5,6 +5,7 @@ export * from "./decisions.js";
 export * from "./disclosure.js";
 export * from "./plan-extensions.js";
 export * from "./policy-invocation.js";
+export * from "./product-signal.js";
 export * from "./resolve.js";
 export * from "./runtime-authority.js";
 export * from "./staleness-tickler.js";

package/dist/policy/index.js

@@ -1,4 +1,5 @@
 import { readPlanPolicy } from "./plan-extensions.js";
+import { FIELD_PRODUCT_SIGNAL, FIELD_PRODUCT_SIGNAL_CLI_ALIAS, inspectProductSignal, } from "./product-signal.js";
 import { coerceLegacyNarrative, LEGACY_NARRATIVE_KEY, loadProjectDefinition } from "./resolve.js";
 import { FIELD_RUNTIME_AUTHORITY, FIELD_RUNTIME_AUTHORITY_CLI_ALIAS, inspectRuntimeAuthority, } from "./runtime-authority.js";
 import { FIELD_STALENESS_TICKLER, FIELD_STALENESS_TICKLER_CLI_ALIAS, inspectStalenessTickler, } from "./staleness-tickler.js";
@@ -11,6 +12,7 @@ export * from "./decisions.js";
 export * from "./disclosure.js";
 export * from "./plan-extensions.js";
 export * from "./policy-invocation.js";
+export * from "./product-signal.js";
 export * from "./resolve.js";
 export * from "./runtime-authority.js";
 export * from "./staleness-tickler.js";
@@ -220,6 +222,15 @@ function inspectSwarmSubagentBackend(data) {
         source: "default-on-error",
     };
 }
+function inspectProductSignalField(data, projectRoot) {
+    const field = inspectProductSignal(data, projectRoot);
+    return {
+        name: field.name,
+        current: field.current,
+        default: field.default,
+        source: field.source,
+    };
+}
 function inspectValueFeedbackField(data, projectRoot) {
     const field = inspectValueFeedback(data, projectRoot);
     return {
@@ -261,6 +272,7 @@ const REGISTERED_POLICIES = [
     inspectSwarmSubagentBackend,
     inspectStalenessTicklerField,
     inspectRuntimeAuthorityField,
+    inspectProductSignalField,
     inspectValueFeedbackField,
 ];
 /** Walk registered inspectors and return one row per field (#1148). */
@@ -272,11 +284,13 @@ export function inspectAllPolicies(projectRoot) {
 export function inspectOnePolicy(name, projectRoot) {
     const normalized = name === FIELD_VALUE_FEEDBACK_CLI_ALIAS
         ? FIELD_VALUE_FEEDBACK
-        : name === FIELD_STALENESS_TICKLER_CLI_ALIAS
-            ? FIELD_STALENESS_TICKLER
-            : name === FIELD_RUNTIME_AUTHORITY_CLI_ALIAS
-                ? FIELD_RUNTIME_AUTHORITY
-                : name;
+        : name === FIELD_PRODUCT_SIGNAL_CLI_ALIAS
+            ? FIELD_PRODUCT_SIGNAL
+            : name === FIELD_STALENESS_TICKLER_CLI_ALIAS
+                ? FIELD_STALENESS_TICKLER
+                : name === FIELD_RUNTIME_AUTHORITY_CLI_ALIAS
+                    ? FIELD_RUNTIME_AUTHORITY
+                    : name;
     for (const field of inspectAllPolicies(projectRoot)) {
         if (field.name === normalized)
             return field;

package/dist/policy/product-signal.d.ts

@@ -0,0 +1,45 @@
+/** Canonical registered policy field name (#2693). */
+export declare const FIELD_PRODUCT_SIGNAL = "plan.policy.productSignal";
+/** Short alias for `policy:show --field=productSignal`. */
+export declare const FIELD_PRODUCT_SIGNAL_CLI_ALIAS = "productSignal";
+export declare const DEFAULT_PRODUCT_SIGNAL_ENABLED = false;
+/** Baked-in default private sink (#2693 D6). */
+export declare const DEFAULT_PRODUCT_SIGNAL_SINK_REPO = "deftai/product-signal";
+export interface ProductSignalConfig {
+    readonly enabled: boolean;
+    readonly sinkRepo: string;
+}
+export type ProductSignalSource = "typed" | "default" | "default-on-error";
+export interface ProductSignalResolved extends ProductSignalConfig {
+    readonly source: ProductSignalSource;
+    readonly error: string | null;
+}
+export declare const PRODUCT_SIGNAL_CAPABILITY_COST_DISCLOSURE: string;
+/** Validate a `plan.policy.productSignal` payload. */
+export declare function validateProductSignal(value: unknown): string[];
+/** Resolve `plan.policy.productSignal` from PROJECT-DEFINITION (#2693). */
+export declare function resolveProductSignal(projectRoot: string): ProductSignalResolved;
+/** Human-readable status line for CLI surfaces. */
+export declare function formatProductSignalStatusLine(policy: ProductSignalResolved): string;
+export interface ProductSignalPolicyField {
+    readonly name: typeof FIELD_PRODUCT_SIGNAL;
+    readonly current: ProductSignalConfig;
+    readonly default: ProductSignalConfig;
+    readonly source: string;
+}
+/** Inspector row for `policy:show --field=productSignal`. */
+export declare function inspectProductSignal(data: Record<string, unknown> | null, projectRoot?: string): ProductSignalPolicyField;
+export interface EnableProductSignalOptions {
+    readonly confirm: boolean;
+    readonly actor?: string;
+    readonly note?: string;
+    readonly sinkRepo?: string;
+}
+export interface EnableProductSignalResult {
+    readonly exitCode: 0 | 1 | 2;
+    readonly stdout: string;
+    readonly changed: boolean;
+}
+/** Persist `productSignal.enabled=true` after capability-cost disclosure (#2693). */
+export declare function enableProductSignal(projectRoot: string, options: EnableProductSignalOptions): EnableProductSignalResult;
+//# sourceMappingURL=product-signal.d.ts.map