@deftai/directive-core 0.77.0 → 0.79.0

package/dist/cache/empty-populate.d.ts

@@ -0,0 +1,44 @@
+/**
+ * empty-populate.ts -- auto-fetch GitHub when the triage cache is empty (#2575).
+ *
+ * Empty/missing cache is the one case where a live list beats a false-empty
+ * "what's next?" answer. Non-empty caches keep the 24h freshness gate unchanged.
+ */
+import type { FetchAllReportImpl } from "./fetch.js";
+export interface EmptyPopulateResult {
+    readonly skipped: boolean;
+    readonly skipReason: string | null;
+    readonly repo: string | null;
+    readonly populated: boolean;
+    readonly succeeded: number | null;
+    readonly message: string;
+}
+export interface EmptyPopulateOptions {
+    readonly repo?: string | null;
+    readonly cacheRoot?: string;
+    readonly source?: string;
+    readonly inferRepoFn?: (cwd: string) => string | null;
+    readonly fetchFn?: (options: {
+        source: string;
+        repo: string;
+        cacheRoot: string;
+        force: boolean;
+    }) => FetchAllReportImpl;
+    readonly seedFn?: (projectRoot: string) => {
+        ok: boolean;
+    };
+    readonly backfillFn?: (projectRoot: string, repo: string | null) => {
+        ok: boolean;
+    };
+}
+/** True when `.deft-cache/github-issue/` has zero cached issue entries. */
+export declare function isTriageCacheEmpty(projectRoot: string, cacheRoot?: string): boolean;
+/**
+ * When the triage cache is empty, mirror `triage:bootstrap` populate steps:
+ * fetch-all from GitHub, seed the candidates log, backfill lifecycle accepts.
+ * Never auto-accepts new issues beyond existing xBRIEF backfill.
+ */
+export declare function maybeAutoPopulateEmptyCache(projectRoot: string, options?: EmptyPopulateOptions): EmptyPopulateResult;
+/** Idempotent hydrate hook for triage read paths (#2575). */
+export declare function ensureTriageCacheHydrated(projectRoot: string, options?: EmptyPopulateOptions): EmptyPopulateResult;
+//# sourceMappingURL=empty-populate.d.ts.map

package/dist/cache/empty-populate.js

@@ -0,0 +1,117 @@
+/**
+ * empty-populate.ts -- auto-fetch GitHub when the triage cache is empty (#2575).
+ *
+ * Empty/missing cache is the one case where a live list beats a false-empty
+ * "what's next?" answer. Non-empty caches keep the 24h freshness gate unchanged.
+ */
+import { join, resolve } from "node:path";
+import { stepSeedCandidatesLog } from "../triage/bootstrap/gitignore.js";
+import { inferRepoFromGit, stepBackfillAuditLog } from "../triage/bootstrap/index.js";
+import { ENV_TRIAGE_REPO } from "../triage/queue/constants.js";
+import { CACHE_DIR_NAME, CACHE_SOURCE, iterCachedIssues } from "../triage/summary/index.js";
+import { cacheFetchAll } from "./fetch.js";
+/** True when `.deft-cache/github-issue/` has zero cached issue entries. */
+export function isTriageCacheEmpty(projectRoot, cacheRoot) {
+    const root = resolve(projectRoot);
+    const resolvedCacheRoot = cacheRoot ?? join(root, CACHE_DIR_NAME);
+    return iterCachedIssues(resolvedCacheRoot).length === 0;
+}
+/**
+ * When the triage cache is empty, mirror `triage:bootstrap` populate steps:
+ * fetch-all from GitHub, seed the candidates log, backfill lifecycle accepts.
+ * Never auto-accepts new issues beyond existing xBRIEF backfill.
+ */
+export function maybeAutoPopulateEmptyCache(projectRoot, options = {}) {
+    const root = resolve(projectRoot);
+    const source = options.source ?? CACHE_SOURCE;
+    const cacheRoot = options.cacheRoot ?? join(root, CACHE_DIR_NAME);
+    if (!isTriageCacheEmpty(root, cacheRoot)) {
+        return {
+            skipped: true,
+            skipReason: "cache-non-empty",
+            repo: null,
+            populated: false,
+            succeeded: null,
+            message: "cache already populated",
+        };
+    }
+    const infer = options.inferRepoFn ?? inferRepoFromGit;
+    const envRepo = (process.env[ENV_TRIAGE_REPO] ?? "").trim();
+    const repo = options.repo ?? (envRepo.length > 0 ? envRepo : null) ?? infer(root);
+    if (repo === null) {
+        return {
+            skipped: true,
+            skipReason: "repo-not-resolved",
+            repo: null,
+            populated: false,
+            succeeded: null,
+            message: "could not infer repo for empty-cache auto-populate",
+        };
+    }
+    const fetch = options.fetchFn ?? cacheFetchAll;
+    let report;
+    try {
+        report = fetch({ source, repo, cacheRoot, force: true });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            skipped: true,
+            skipReason: "fetch-failed",
+            repo,
+            populated: false,
+            succeeded: null,
+            message,
+        };
+    }
+    const seed = options.seedFn ?? stepSeedCandidatesLog;
+    const seedOutcome = seed(root);
+    if (!seedOutcome.ok) {
+        return {
+            skipped: true,
+            skipReason: "seed-failed",
+            repo,
+            populated: false,
+            succeeded: report.issuesWritten,
+            message: "candidates log seed failed after fetch-all",
+        };
+    }
+    const backfill = options.backfillFn ?? stepBackfillAuditLog;
+    try {
+        const backfillOutcome = backfill(root, repo);
+        if (!backfillOutcome.ok) {
+            return {
+                skipped: true,
+                skipReason: "backfill-failed",
+                repo,
+                populated: false,
+                succeeded: report.issuesWritten,
+                message: "audit log backfill failed after fetch-all",
+            };
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            skipped: true,
+            skipReason: "backfill-failed",
+            repo,
+            populated: false,
+            succeeded: report.issuesWritten,
+            message,
+        };
+    }
+    return {
+        skipped: false,
+        skipReason: null,
+        repo,
+        populated: true,
+        succeeded: report.issuesWritten,
+        message: `auto-populated empty triage cache from GitHub (${repo})`,
+    };
+}
+/** Idempotent hydrate hook for triage read paths (#2575). */
+export function ensureTriageCacheHydrated(projectRoot, options = {}) {
+    return maybeAutoPopulateEmptyCache(projectRoot, options);
+}
+//# sourceMappingURL=empty-populate.js.map

package/dist/cache/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./constants.js";
+export * from "./empty-populate.js";
 export * from "./errors.js";
 export * from "./fetch.js";
 export * from "./io.js";

package/dist/cache/index.js

@@ -1,4 +1,5 @@
 export * from "./constants.js";
+export * from "./empty-populate.js";
 export * from "./errors.js";
 export * from "./fetch.js";
 export * from "./io.js";

package/dist/check-updates/index.d.ts

@@ -2,10 +2,20 @@
 export declare const REMOTE_PROBE_DEFAULT_TIMEOUT = 5;
 /** Baked-in canonical upstream (#1320). Never probe consumer origin. */
 export declare const DEFT_UPSTREAM_URL = "https://github.com/deftai/directive.git";
+/** SSH form of the canonical upstream — allowlisted alongside HTTPS (#2601). */
+export declare const DEFT_UPSTREAM_SSH_URL = "git@github.com:deftai/directive.git";
 /** Reject git ls-remote targets that could be parsed as options (#CodeQL). */
 export declare function isSafeGitLsRemoteTarget(url: string): boolean;
 /** Return a trimmed upstream URL safe for `git ls-remote`, or null when rejected. */
 export declare function sanitizeGitLsRemoteTarget(url: string): string | null;
+/** Extract hostname from an https or git@ upstream URL. */
+export declare function extractUpstreamHostname(url: string): string | null;
+/** Reject localhost, link-local, and RFC1918 targets for blind SSRF hardening (#2601). */
+export declare function isPrivateOrLinkLocalUpstreamHost(hostname: string): boolean;
+/** True when a sanitized upstream URL is on the canonical allowlist (#2601). */
+export declare function isAllowlistedSafeUpstreamUrl(safeUrl: string): boolean;
+/** True when a manifest-controlled upstream URL is safe to probe (#2601). */
+export declare function isAllowlistedUpstreamUrl(url: string): boolean;
 export type RemoteProbeStatus = "ok" | "behind" | "skipped" | "no-upstream" | "no-tags" | "error";
 export interface RemoteProbeResult {
     readonly status: RemoteProbeStatus;

package/dist/check-updates/index.js

@@ -7,6 +7,9 @@ import { resolveVersion } from "../doctor/paths.js";
 export const REMOTE_PROBE_DEFAULT_TIMEOUT = 5.0;
 /** Baked-in canonical upstream (#1320). Never probe consumer origin. */
 export const DEFT_UPSTREAM_URL = "https://github.com/deftai/directive.git";
+/** SSH form of the canonical upstream — allowlisted alongside HTTPS (#2601). */
+export const DEFT_UPSTREAM_SSH_URL = "git@github.com:deftai/directive.git";
+const ALLOWED_UPSTREAM_URLS = new Set([DEFT_UPSTREAM_URL, DEFT_UPSTREAM_SSH_URL]);
 const MANIFEST_UPSTREAM_URL_KEYS = [
     "source_url",
     "url",
@@ -32,6 +35,83 @@ export function sanitizeGitLsRemoteTarget(url) {
     }
     return null;
 }
+/** Extract hostname from an https or git@ upstream URL. */
+export function extractUpstreamHostname(url) {
+    const trimmed = url.trim();
+    const httpsMatch = /^https?:\/\/([^/:?#]+)/i.exec(trimmed);
+    if (httpsMatch?.[1]) {
+        return httpsMatch[1].toLowerCase();
+    }
+    const sshMatch = /^git@([^:/]+):/i.exec(trimmed);
+    if (sshMatch?.[1]) {
+        return sshMatch[1].toLowerCase();
+    }
+    return null;
+}
+function parseIpv4Octets(hostname) {
+    const parts = hostname.split(".");
+    if (parts.length !== 4) {
+        return null;
+    }
+    const octets = [];
+    for (const part of parts) {
+        if (!/^\d+$/.test(part)) {
+            return null;
+        }
+        const value = Number(part);
+        if (value > 255) {
+            return null;
+        }
+        octets.push(value);
+    }
+    return octets;
+}
+/** Reject localhost, link-local, and RFC1918 targets for blind SSRF hardening (#2601). */
+export function isPrivateOrLinkLocalUpstreamHost(hostname) {
+    const host = hostname.trim().toLowerCase();
+    if (host.length === 0) {
+        return true;
+    }
+    if (host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local")) {
+        return true;
+    }
+    if (host === "::1" || host === "[::1]") {
+        return true;
+    }
+    const octets = parseIpv4Octets(host);
+    if (octets !== null) {
+        const [a, b] = octets;
+        if (a === 127)
+            return true;
+        if (a === 10)
+            return true;
+        if (a === 172 && b !== undefined && b >= 16 && b <= 31)
+            return true;
+        if (a === 192 && b === 168)
+            return true;
+        if (a === 169 && b === 254)
+            return true;
+        if (a === 0)
+            return true;
+    }
+    return false;
+}
+/** True when a sanitized upstream URL is on the canonical allowlist (#2601). */
+export function isAllowlistedSafeUpstreamUrl(safeUrl) {
+    if (!ALLOWED_UPSTREAM_URLS.has(safeUrl)) {
+        return false;
+    }
+    const hostname = extractUpstreamHostname(safeUrl);
+    if (hostname === null || isPrivateOrLinkLocalUpstreamHost(hostname)) {
+        return false;
+    }
+    return true;
+}
+/** True when a manifest-controlled upstream URL is safe to probe (#2601). */
+export function isAllowlistedUpstreamUrl(url) {
+    const safe = sanitizeGitLsRemoteTarget(url);
+    return safe !== null && isAllowlistedSafeUpstreamUrl(safe);
+}
 function normalizePrereleaseForSort(pre) {
     const dot = pre.indexOf(".");
     if (dot <= 0) {
@@ -134,7 +214,7 @@ export function resolveUpstreamUrl(projectRoot) {
             const value = manifest[key];
             if (typeof value === "string" && value.trim()) {
                 const safe = sanitizeGitLsRemoteTarget(value);
-                if (safe) {
+                if (safe && isAllowlistedSafeUpstreamUrl(safe)) {
                     return safe;
                 }
             }

package/dist/doctor/main.d.ts

@@ -2,6 +2,7 @@ import { type ResolutionFacts } from "../resolution/index.js";
 import { createPlainSink } from "./output.js";
 import type { DoctorSeams, Finding, ResolutionSummary } from "./types.js";
 export declare function cmdDoctor(args: readonly string[], seams?: DoctorSeams): number;
+export declare function runAgentHooksHealthCheck(projectRoot: string, consumerContext: boolean, sink: ReturnType<typeof createPlainSink>, addFinding: (finding: Finding) => void, seams: DoctorSeams): void;
 /**
  * Never emit a bare `task ...` remediation in a project without Taskfile wiring
  * (#2267). The `directive` surface always works; `task deft:X` is optional and

package/dist/doctor/main.js

@@ -6,6 +6,7 @@ import { describeShadowedPlanExtension, detectShadowedPlanExtensions, } from "..
 import { loadProjectDefinition } from "../policy/resolve.js";
 import { checkLocalEngineIntegrity, classify, detectPackageManager, evaluateSkew, reconcileVersions, plan as resolvePlan, } from "../resolution/index.js";
 import { resolveUserMdPath } from "../user-config/resolve-user-md.js";
+import { evaluateAgentHooks } from "../verify-env/agent-hooks.js";
 import { agentsRefreshPlan, hasV3ManagedMarker } from "./agents-md.js";
 import { runChecks } from "./checks.js";
 import { CONSUMER_FRAMEWORK_DIRS, EXPECTED_CONTENT_DIRS, EXPECTED_FRAMEWORK_DIRS, NETWORK_DISCLOSURE_LINE, PAYLOAD_STALENESS_OFFLINE_SKIP_MESSAGE, TASKFILE_INCLUDE_SNIPPET, UV_INSTALL_URL, } from "./constants.js";
@@ -162,6 +163,11 @@ export function cmdDoctor(args, seams = {}) {
     if (!jsonMode) {
         sink.blank();
     }
+    sink.info("Checking agent-host hook registration...");
+    runAgentHooksHealthCheck(projectRoot, consumerContext, sink, addFinding, seams);
+    if (!jsonMode) {
+        sink.blank();
+    }
     // #2182: payload-staleness is the only doctor check that can reach a
     // registry (git verifies the pin; npm compares stable release availability).
     // It stays in the OFFLINE
@@ -332,6 +338,48 @@ export function cmdDoctor(args, seams = {}) {
     sink.finalWarn(`System check completed with ${warningCount} warning(s).`);
     return 0;
 }
+export function runAgentHooksHealthCheck(projectRoot, consumerContext, sink, addFinding, seams) {
+    const checkName = "agent-hooks-registration";
+    if (!consumerContext) {
+        const reason = "maintainer source checkout; project hook deposit is consumer-only";
+        sink.info(`${checkName}: skip -- ${reason}`);
+        addFinding({ severity: "skip", message: reason, check: checkName, status: "skip" });
+        return;
+    }
+    try {
+        const result = (seams.evaluateAgentHooks ?? evaluateAgentHooks)(projectRoot);
+        if (result.code === 0) {
+            const message = `${checkName}: registered and structurally valid; ` +
+                "Codex runtime trust is user-controlled and must be reviewed with `/hooks`";
+            sink.success(message);
+            addFinding({
+                severity: "skip",
+                message,
+                check: checkName,
+                status: "registered",
+                registrations: result.registrations,
+                trust_status: "not-verifiable",
+                trust_review: "Open `/hooks` in Codex and review the project hook commands.",
+            });
+            return;
+        }
+        const message = `${checkName}: ${result.message.replace(/\s+/g, " ").trim()}`;
+        sink.warn(message);
+        addFinding({
+            severity: "warning",
+            message,
+            check: checkName,
+            status: result.code === 2 ? "unavailable" : "incomplete",
+            registrations: result.registrations,
+            suggestion: "deft update",
+        });
+    }
+    catch (cause) {
+        const message = `${checkName}: probe failed -- ${String(cause)}`;
+        sink.warn(message);
+        addFinding({ severity: "warning", message, check: checkName, suggestion: "deft update" });
+    }
+}
 function runInstallIntegrityChecks(projectRoot, sink, addFinding, seams) {
     if (runningInsideDeftRepo(projectRoot, seams)) {
         sink.info("Skipping install-integrity checks -- running inside the deft framework repo (no install manifest in the source checkout).");

package/dist/doctor/payload-staleness.js

@@ -1,6 +1,7 @@
 import { spawnSync } from "node:child_process";
 import { dirname, join } from "node:path";
 import { detectCanonicalVendoredManifest, isNpmManaged } from "../init-deposit/migrate.js";
+import { isPublishable } from "../release/version.js";
 import { CANONICAL_UPGRADE_COMMAND, NPM_PACKAGE_NAME, upgradeCommandFor, VENDORED_NPM_DEPOSIT_UPGRADE_COMMAND, } from "./constants.js";
 import { locateManifest, parseInstallManifest } from "./manifest.js";
 import { readTextSafe, resolveDefaultFrameworkRoot } from "./paths.js";
@@ -203,7 +204,12 @@ export function runPayloadStalenessCheck(projectRoot, sink, addFinding, seams =
         });
         return;
     }
-    const installedCandidate = (tag || ref).trim().replace(/^refs\/tags\//, "");
+    const normalizedRef = ref.trim().replace(/^refs\/tags\//, "");
+    const normalizedTag = tag.trim().replace(/^refs\/tags\//, "");
+    // Branch pins (ref not a publishable tag) must not fall through to npm via a stale tag (#2538).
+    const installedCandidate = isPublishable(normalizedRef)
+        ? normalizedTag || normalizedRef
+        : normalizedRef;
     const applicability = evaluateReleaseAvailability(installedCandidate, null);
     if (applicability.status === "not-applicable") {
         if (remoteSha && installedSha === remoteSha) {

package/dist/doctor/types.d.ts

@@ -3,6 +3,7 @@ import type { ShadowedPlanExtension } from "../policy/plan-extensions.js";
 import type { EngineProbeResult } from "../resolution/classify.js";
 import type { ResolutionMode } from "../resolution/index.js";
 import type { ResolveUserMdResult } from "../user-config/resolve-user-md.js";
+import type { AgentHookHealthResult } from "../verify-env/agent-hooks.js";
 export declare const EXIT_CLEAN = 0;
 export declare const EXIT_DRIFT = 1;
 export declare const EXIT_CONFIG_ERROR = 2;
@@ -135,5 +136,7 @@ export interface DoctorSeams {
      * its `plan` object; returns [] when no project definition is present.
      */
     readonly detectPlanExtensionShadows?: (projectRoot: string) => readonly ShadowedPlanExtension[];
+    /** Read-only agent-host hook registration probe (#2438). */
+    readonly evaluateAgentHooks?: (projectRoot: string) => AgentHookHealthResult;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/eval/triggers.d.ts

@@ -0,0 +1,76 @@
+/** Relative path to skill-pi-trigger-eval compatible case rows (#1586). */
+export declare const TRIGGER_CASES_REL = "evals/trigger-cases.jsonl";
+/** Default Skills Index source for AGENTS.md skill routing (#1586). */
+export declare const SKILLS_INDEX_REL = "REFERENCES.md";
+/** Parsed Skills Index row. */
+export interface SkillsIndexEntry {
+    readonly skillId: string;
+    readonly triggers: readonly string[];
+}
+/** One row in evals/trigger-cases.jsonl (skill-pi-trigger-eval eval-set + skill id). */
+export interface TriggerCaseRow {
+    readonly id: string;
+    readonly query: string;
+    readonly skill: string;
+    readonly should_trigger: boolean;
+}
+/** Outcome for a single trigger case. */
+export interface TriggerCaseResult {
+    readonly id: string;
+    readonly query: string;
+    readonly skill: string;
+    readonly should_trigger: boolean;
+    readonly actual: boolean;
+    readonly pass: boolean;
+    readonly matchedTrigger?: string;
+    readonly winnerSkill?: string;
+}
+/** Aggregate eval:triggers report. */
+export interface TriggerEvalReport {
+    readonly total: number;
+    readonly passed: number;
+    readonly failed: number;
+    readonly pass_rate: number | null;
+    readonly results: readonly TriggerCaseResult[];
+    readonly coverageErrors: readonly string[];
+}
+export interface RunTriggerEvalOptions {
+    readonly projectRoot?: string;
+    readonly casesPath?: string;
+    readonly indexPath?: string;
+    readonly cases?: readonly TriggerCaseRow[];
+    readonly indexText?: string;
+}
+export interface RunTriggerEvalResult {
+    readonly code: 0 | 1 | 2;
+    readonly report: TriggerEvalReport | null;
+    readonly message: string;
+}
+/** Normalize user text for deterministic substring trigger matching. */
+export declare function normalizeTriggerText(text: string): string;
+/** Collapse embedded newlines before interpolating user/data into log lines. */
+export declare function sanitizeTriggerLogLine(text: string): string;
+/** Extract backtick trigger phrases from a Skills Index triggers cell. */
+export declare function parseTriggerCell(cell: string): string[];
+/** Parse the Skills Index markdown table in REFERENCES.md. */
+export declare function parseSkillsIndex(markdown: string): SkillsIndexEntry[];
+interface TriggerMatch {
+    readonly skillId: string;
+    readonly trigger: string;
+}
+/** Find the winning skill for a query using longest-trigger-wins disambiguation. */
+export declare function resolveTriggerWinner(query: string, index: readonly SkillsIndexEntry[]): TriggerMatch | null;
+/** True when the Skills Index routing would send *query* to *skillId*. */
+export declare function wouldRouteToSkill(query: string, skillId: string, index: readonly SkillsIndexEntry[]): boolean;
+/** Validate one JSONL row against the skill-pi-trigger-eval row contract. */
+export declare function parseTriggerCaseRow(raw: unknown, lineNumber: number): TriggerCaseRow | string;
+/** Load evals/trigger-cases.jsonl. */
+export declare function loadTriggerCases(path: string): TriggerCaseRow[] | {
+    error: string;
+};
+/** Verify at least two positive and one negative case per indexed skill. */
+export declare function validateTriggerCoverage(cases: readonly TriggerCaseRow[], index: readonly SkillsIndexEntry[]): string[];
+/** Run deterministic trigger routing eval (offline skill-pi-trigger-eval counterpart). */
+export declare function runTriggerEval(options?: RunTriggerEvalOptions): RunTriggerEvalResult;
+export {};
+//# sourceMappingURL=triggers.d.ts.map