@deftai/directive-core 0.94.0 → 0.95.0

package/dist/triage/help/registry-data.d.ts

@@ -168,13 +168,13 @@ export declare const registryData: {
         };
         readonly "task triage:classify": {
             readonly name: "task triage:classify";
-            readonly summary: "Inspect / validate auto-classification surface";
-            readonly refs: "(D10 / #1129)";
-            readonly description: "Inspect or validate the auto-classification rule set. --list renders effective rules (framework universal first, consumer overrides next). --validate exits non-zero on a malformed plan.policy.triageAutoClassify.";
-            readonly usage: "task triage:classify -- [--list | --validate]";
-            readonly flags: readonly [readonly ["--list", "(default)", "Print effective rules + hold markers."], readonly ["--validate", "(off)", "Validate plan.policy.triageAutoClassify."]];
-            readonly examples: readonly ["task triage:classify -- --list", "task triage:classify -- --validate"];
-            readonly see_also: readonly ["task triage:bootstrap", "task triage:queue", "#1119 / D10"];
+            readonly summary: "Inspect / validate auto-classification surface; Tier-1 SCM label mirror";
+            readonly refs: "(D10 / #1129, #1423 Wave 1)";
+            readonly description: "Inspect or validate the auto-classification rule set. --list renders effective rules (framework universal first, consumer overrides next). --validate exits non-zero on a malformed plan.policy.triageAutoClassify or triageLabelMirror. --mirror runs the Tier-1 deterministic SCM label mirror over the github-issue cache (dry-run default; --apply writes via SCM boundary). Never calls triage:accept / never writes proposed/ xBRIEFs.";
+            readonly usage: "task triage:classify -- [--list | --validate | --mirror [--apply] [--repo owner/name] [--json] [--allow-cross-repo]]";
+            readonly flags: readonly [readonly ["--list", "(default)", "Print effective rules + hold markers."], readonly ["--validate", "(off)", "Validate plan.policy.triageAutoClassify + triageLabelMirror."], readonly ["--mirror", "(off)", "Tier-1 label mirror: classify cache → planned/applied labels (dry-run default)."], readonly ["--apply", "(off)", "With --mirror: write labels via SCM (requires github SCM boundary)."], readonly ["--repo owner/name", "(all cached)", "Limit mirror to one repo."], readonly ["--json", "(off)", "With --mirror: structured JSON outcome."], readonly ["--allow-cross-repo", "(off)", "With --mirror --apply: allow non-project repos (#2601)."]];
+            readonly examples: readonly ["task triage:classify -- --list", "task triage:classify -- --validate", "task triage:classify -- --mirror", "task triage:classify -- --mirror --apply --repo owner/name"];
+            readonly see_also: readonly ["task triage:bootstrap", "task triage:queue", "task vbrief:reconcile:labels", "#1119 / D10", "#1423"];
             readonly placeholder: false;
         };
         readonly "task triage:bootstrap": {

package/dist/triage/help/registry-data.js

@@ -264,16 +264,36 @@ export const registryData = {
         },
         "task triage:classify": {
             name: "task triage:classify",
-            summary: "Inspect / validate auto-classification surface",
-            refs: "(D10 / #1129)",
-            description: "Inspect or validate the auto-classification rule set. --list renders effective rules (framework universal first, consumer overrides next). --validate exits non-zero on a malformed plan.policy.triageAutoClassify.",
-            usage: "task triage:classify -- [--list | --validate]",
+            summary: "Inspect / validate auto-classification surface; Tier-1 SCM label mirror",
+            refs: "(D10 / #1129, #1423 Wave 1)",
+            description: "Inspect or validate the auto-classification rule set. --list renders effective rules (framework universal first, consumer overrides next). --validate exits non-zero on a malformed plan.policy.triageAutoClassify or triageLabelMirror. --mirror runs the Tier-1 deterministic SCM label mirror over the github-issue cache (dry-run default; --apply writes via SCM boundary). Never calls triage:accept / never writes proposed/ xBRIEFs.",
+            usage: "task triage:classify -- [--list | --validate | --mirror [--apply] [--repo owner/name] [--json] [--allow-cross-repo]]",
             flags: [
                 ["--list", "(default)", "Print effective rules + hold markers."],
-                ["--validate", "(off)", "Validate plan.policy.triageAutoClassify."],
+                ["--validate", "(off)", "Validate plan.policy.triageAutoClassify + triageLabelMirror."],
+                [
+                    "--mirror",
+                    "(off)",
+                    "Tier-1 label mirror: classify cache → planned/applied labels (dry-run default).",
+                ],
+                ["--apply", "(off)", "With --mirror: write labels via SCM (requires github SCM boundary)."],
+                ["--repo owner/name", "(all cached)", "Limit mirror to one repo."],
+                ["--json", "(off)", "With --mirror: structured JSON outcome."],
+                ["--allow-cross-repo", "(off)", "With --mirror --apply: allow non-project repos (#2601)."],
+            ],
+            examples: [
+                "task triage:classify -- --list",
+                "task triage:classify -- --validate",
+                "task triage:classify -- --mirror",
+                "task triage:classify -- --mirror --apply --repo owner/name",
+            ],
+            see_also: [
+                "task triage:bootstrap",
+                "task triage:queue",
+                "task vbrief:reconcile:labels",
+                "#1119 / D10",
+                "#1423",
             ],
-            examples: ["task triage:classify -- --list", "task triage:classify -- --validate"],
-            see_also: ["task triage:bootstrap", "task triage:queue", "#1119 / D10"],
             placeholder: false,
         },
         "task triage:bootstrap": {

package/dist/triage/queue/show.d.ts

@@ -58,7 +58,7 @@ export declare function extractBodySummary(body: string, maxLines?: number): str
  * Looks for AC / Acceptance headings and checkbox / bullet lists under them.
  */
 export declare function extractAcceptanceCriteria(body: string): readonly string[];
-/** Operator-facing pasteable brief backbone for Phase 3 decisions (#2890). */
+/** Operator-facing pasteable brief backbone for Phase 3 decisions (#2890 / #3116). */
 export declare function renderOperatorBrief(options: {
     readonly issue: CachedIssueDetail | null;
     readonly repo: string;

package/dist/triage/queue/show.js

@@ -245,7 +245,7 @@ export function extractAcceptanceCriteria(body) {
     }
     return bullets.slice(0, 12);
 }
-/** Operator-facing pasteable brief backbone for Phase 3 decisions (#2890). */
+/** Operator-facing pasteable brief backbone for Phase 3 decisions (#2890 / #3116). */
 export function renderOperatorBrief(options) {
     const lines = [];
     lines.push(`triage:show --format=operator -- ${options.repo}#${options.number}`);
@@ -258,9 +258,11 @@ export function renderOperatorBrief(options) {
     const issue = options.issue;
     const link = issue.htmlUrl ?? resolveIssueHtmlUrl(options.repo, options.number);
     const labels = issue.labels.length > 0 ? issue.labels.map(oneLine).join(", ") : "<none>";
+    // URL-first lead line (#3116): canonical issue URL before title/body fields.
+    lines.push(oneLine(link));
     lines.push(`#${options.number}  ${oneLine(issue.title)}`);
-    lines.push(`link:    ${oneLine(link)}`);
     lines.push(`labels:  ${labels}`);
+    lines.push("validity: (agent-owned — still-open | partial | likely-shipped | needs-re-scope + evidence)");
     lines.push("");
     lines.push("summary:");
     for (const line of extractBodySummary(issue.body).split("\n")) {

package/dist/vbrief-validate/project-definition.js

@@ -78,7 +78,7 @@ export function validateProjectDefinition(filepath, data, vbriefDir) {
                 }
                 const uriRaw = ref.uri;
                 const uri = typeof uriRaw === "string" ? uriRaw : "";
-                if (uri && uri.startsWith("file://")) {
+                if (uri.startsWith("file://")) {
                     const refPath = uri.replace("file://", "");
                     const fullPath = resolve(vbriefDir, refPath);
                     if (!isRelativeTo(fullPath, resolvedRoot)) {

package/dist/verify-env/agent-hook-readiness.d.ts

@@ -0,0 +1,42 @@
+import type { HookHost } from "../hooks/dispatcher.js";
+import type { AgentHookInspection } from "../init-deposit/agent-hooks.js";
+import type { HostHooksPolicy } from "../policy/host-hooks.js";
+import { type AgentHookHealthResult } from "./agent-hooks.js";
+import { type AgentHookLiveProbeResult, type AgentHookLiveProbeSeams } from "./agent-hooks-live-probe.js";
+import type { OutputStream } from "./verify-hooks-installed.js";
+export type AgentHookReadinessRegistration = "registered" | "disabled" | "missing" | "drifted" | "not-applicable";
+export type AgentHookReadinessFunctionality = "functional" | "non-functional" | "unavailable" | "not-run" | "disabled" | "not-applicable";
+export type AgentHookReadinessTrust = "manual-review-required" | "not-applicable" | "disabled";
+export type AgentHookReadinessInterception = "not-directly-verified" | "not-applicable" | "disabled";
+export type AgentHookReadinessLiveStatus = "functional" | "non-functional" | "unavailable" | "not-run" | "disabled" | "skipped";
+export interface AgentHookReadinessHostResult {
+    readonly host: HookHost;
+    readonly registration: AgentHookReadinessRegistration;
+    readonly functionality: AgentHookReadinessFunctionality;
+    readonly trust: AgentHookReadinessTrust;
+    readonly interception: AgentHookReadinessInterception;
+}
+export interface AgentHookReadinessResult {
+    readonly code: 0 | 1 | 2;
+    readonly message: string;
+    readonly stream: OutputStream;
+    readonly skipped: boolean;
+    readonly liveStatus: AgentHookReadinessLiveStatus;
+    readonly hosts: readonly AgentHookReadinessHostResult[];
+    readonly registrations: readonly AgentHookInspection[];
+    readonly liveProbe: AgentHookLiveProbeResult | null;
+}
+export interface AgentHookReadinessOptions {
+    readonly hostHooksPolicy?: HostHooksPolicy;
+    readonly consumerContext?: (projectRoot: string) => boolean;
+    readonly evaluateStructural?: (projectRoot: string, policy: HostHooksPolicy) => AgentHookHealthResult;
+    readonly probeLive?: (projectRoot: string, seams?: AgentHookLiveProbeSeams) => AgentHookLiveProbeResult;
+    readonly liveProbeSeams?: Omit<AgentHookLiveProbeSeams, "hosts">;
+}
+/** Stable CLI JSON projection; keep the four readiness dimensions orthogonal. */
+export declare function agentHookReadinessJson(result: AgentHookReadinessResult): Record<string, unknown>;
+/** Preserve fail-closed readiness semantics when an unexpected evaluator dependency throws. */
+export declare function evaluateAgentHookReadinessSafely(projectRoot: string, evaluate?: (projectRoot: string) => AgentHookReadinessResult): AgentHookReadinessResult;
+/** Fail-closed consumer readiness: structural registration first, installed-shim live probe second. */
+export declare function evaluateAgentHookReadiness(projectRoot: string, options?: AgentHookReadinessOptions): AgentHookReadinessResult;
+//# sourceMappingURL=agent-hook-readiness.d.ts.map

package/dist/verify-env/agent-hook-readiness.js

@@ -0,0 +1,150 @@
+import { resolve } from "node:path";
+import { resolveFrameworkRootForProject } from "../doctor/paths.js";
+import { loadHostHooksPolicyFromProject } from "../policy/host-hooks.js";
+import { evaluateAgentHooks } from "./agent-hooks.js";
+import { probeAgentHooksLive, } from "./agent-hooks-live-probe.js";
+/** Stable CLI JSON projection; keep the four readiness dimensions orthogonal. */
+export function agentHookReadinessJson(result) {
+    return {
+        ready: result.code === 0,
+        exit_code: result.code,
+        skipped: result.skipped,
+        live_status: result.liveStatus,
+        hosts: result.hosts.map((entry) => ({ ...entry })),
+        message: result.message,
+    };
+}
+/** Preserve fail-closed readiness semantics when an unexpected evaluator dependency throws. */
+export function evaluateAgentHookReadinessSafely(projectRoot, evaluate = evaluateAgentHookReadiness) {
+    try {
+        return evaluate(projectRoot);
+    }
+    catch (cause) {
+        const detail = cause instanceof Error ? cause.message : String(cause);
+        return {
+            code: 2,
+            message: `❌ deft agent hook readiness unavailable: ${detail}`,
+            stream: "stderr",
+            skipped: false,
+            liveStatus: "unavailable",
+            hosts: [],
+            registrations: [],
+            liveProbe: null,
+        };
+    }
+}
+function isConsumerContext(projectRoot) {
+    return resolve(projectRoot) !== resolve(resolveFrameworkRootForProject(projectRoot));
+}
+function registrationState(entry) {
+    if (entry.status === "healthy")
+        return "registered";
+    return entry.status;
+}
+function renderHosts(hosts) {
+    return hosts
+        .map((entry) => `  - ${entry.host}: registration=${entry.registration}; functionality=${entry.functionality}; ` +
+        `trust=${entry.trust}; interception=${entry.interception}`)
+        .join("\n");
+}
+function baseHostResult(entry, policy) {
+    if (!policy[entry.host]) {
+        return {
+            host: entry.host,
+            registration: "disabled",
+            functionality: "disabled",
+            trust: "disabled",
+            interception: "disabled",
+        };
+    }
+    return {
+        host: entry.host,
+        registration: registrationState(entry),
+        functionality: "not-run",
+        trust: entry.host === "codex" ? "manual-review-required" : "not-applicable",
+        interception: "not-directly-verified",
+    };
+}
+/** Fail-closed consumer readiness: structural registration first, installed-shim live probe second. */
+export function evaluateAgentHookReadiness(projectRoot, options = {}) {
+    const root = resolve(projectRoot);
+    const consumerContext = options.consumerContext ?? isConsumerContext;
+    if (!consumerContext(root)) {
+        return {
+            code: 0,
+            message: "✓ deft agent hook readiness skipped: maintainer source checkout; consumer hook deposit is not applicable.",
+            stream: "stdout",
+            skipped: true,
+            liveStatus: "skipped",
+            hosts: [],
+            registrations: [],
+            liveProbe: null,
+        };
+    }
+    const policy = options.hostHooksPolicy ?? loadHostHooksPolicyFromProject(root);
+    const structural = (options.evaluateStructural ?? evaluateAgentHooks)(root, policy);
+    const hosts = structural.registrations.map((entry) => baseHostResult(entry, policy));
+    if (structural.code !== 0) {
+        return {
+            code: structural.code,
+            message: `${structural.message}\n${renderHosts(hosts)}`,
+            stream: "stderr",
+            skipped: false,
+            liveStatus: "not-run",
+            hosts,
+            registrations: structural.registrations,
+            liveProbe: null,
+        };
+    }
+    const enabledHosts = structural.registrations
+        .filter((entry) => policy[entry.host])
+        .map((entry) => entry.host);
+    const liveProbe = (options.probeLive ?? probeAgentHooksLive)(root, {
+        ...options.liveProbeSeams,
+        hosts: enabledHosts,
+    });
+    const liveByHost = new Map(liveProbe.hosts.map((entry) => [entry.host, entry.status]));
+    const evaluatedHosts = hosts.map((entry) => {
+        if (entry.functionality === "disabled")
+            return entry;
+        const liveStatus = liveByHost.get(entry.host);
+        return {
+            ...entry,
+            functionality: liveStatus === "functional"
+                ? "functional"
+                : liveStatus === "unavailable"
+                    ? "unavailable"
+                    : liveStatus === "non-functional"
+                        ? "non-functional"
+                        : "not-run",
+        };
+    });
+    const allDisabled = enabledHosts.length === 0;
+    const liveStatus = allDisabled
+        ? "disabled"
+        : liveProbe.code === 0
+            ? "functional"
+            : liveProbe.code === 2
+                ? "unavailable"
+                : "non-functional";
+    const trustReview = policy.codex
+        ? "\n  Codex trust: manual-review-required. Open `/hooks` and approve the exact project hook commands. " +
+            "The live probe validates the shim and codec, not host interception."
+        : "";
+    return {
+        code: liveProbe.code,
+        message: `${liveProbe.code === 0 ? "✓" : "❌"} deft agent hook readiness: ${liveProbe.message}\n` +
+            renderHosts(evaluatedHosts) +
+            trustReview +
+            (liveProbe.code === 0
+                ? ""
+                : "\n  If an affected host is unused, inspect `deft policy:show --field=hostHooks`, set `plan.policy.hostHooks.<host> = false`, and run `deft update`."),
+        stream: liveProbe.code === 0 ? "stdout" : "stderr",
+        skipped: false,
+        liveStatus,
+        hosts: evaluatedHosts,
+        registrations: structural.registrations,
+        liveProbe,
+    };
+}
+//# sourceMappingURL=agent-hook-readiness.js.map

package/dist/verify-env/agent-hooks-live-probe.d.ts

@@ -1,5 +1,6 @@
-import type { HookEvent, HookHost } from "../hooks/dispatcher.js";
-export type AgentHookLiveProbeIssue = "hook-command-missing" | "spawn-failed" | "empty-stdout" | "unparseable-json" | "missing-allow" | "missing-deny";
+import { type HookEvent, type HookHost } from "../hooks/dispatcher.js";
+export declare const LIVE_PROBE_CASE_TIMEOUT_MS = 1500;
+export type AgentHookLiveProbeIssue = "hook-command-missing" | "spawn-failed" | "timed-out" | "empty-stdout" | "unparseable-json" | "missing-allow" | "missing-deny";
 export interface AgentHookLiveProbeCase {
     readonly host: HookHost;
     readonly event: HookEvent;
@@ -7,26 +8,37 @@ export interface AgentHookLiveProbeCase {
     readonly issue: AgentHookLiveProbeIssue;
     readonly detail: string;
 }
+export type AgentHookLiveProbeHostStatus = "functional" | "non-functional" | "unavailable";
+export interface AgentHookLiveProbeHostResult {
+    readonly host: HookHost;
+    readonly status: AgentHookLiveProbeHostStatus;
+}
 export interface AgentHookLiveProbeResult {
     readonly code: 0 | 1 | 2;
     readonly message: string;
     readonly cases: readonly AgentHookLiveProbeCase[];
+    readonly hosts: readonly AgentHookLiveProbeHostResult[];
+    readonly durationMs: number;
 }
 export interface AgentHookLiveProbeSeams {
+    /** Enabled hosts to probe. Defaults to every deposited host. */
+    readonly hosts?: readonly HookHost[];
     readonly resolveCommand?: (name: string) => string | null;
     readonly spawnHook?: (input: {
         readonly command: string;
         readonly args: readonly string[];
         readonly stdin: string;
         readonly cwd: string;
-        readonly env?: NodeJS.ProcessEnv;
+        readonly env: NodeJS.ProcessEnv;
     }) => {
         readonly status: number;
         readonly stdout: string;
         readonly stderr: string;
+        readonly timedOut?: boolean;
     };
 }
+/** Quote one Windows cmd.exe argument used by the installed hook shim. */
 export declare function quoteWindowsCmdArg(value: string): string;
-/** Spawn the configured hook command and assert Cursor tool.before allow/deny behavior. */
+/** Invoke the installed deft-hook shim and validate enabled host allow/deny codecs. */
 export declare function probeAgentHooksLive(projectRoot: string, seams?: AgentHookLiveProbeSeams): AgentHookLiveProbeResult;
 //# sourceMappingURL=agent-hooks-live-probe.d.ts.map