@deftai/directive-core 0.75.0 → 0.77.0

package/dist/eval/crud-telemetry.js

@@ -1,10 +1,11 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
 import { dirname } from "node:path";
 import { readCorePackageVersion } from "../engine-version.js";
-import { resolveEvalPath } from "../layout/resolve.js";
+import { helpedMetricsHistoryPath } from "../metrics/resolve-metrics-home.js";
 import { scanVbrief } from "../vbrief-validate/conformance.js";
 import { validateVbriefSchema } from "../vbrief-validate/schema.js";
-export const CRUD_METRICS_HISTORY_REL = "results/crud-metrics.jsonl";
+/** Relative path under the resolved metrics home for helped / value telemetry (#2545). */
+export const CRUD_METRICS_HISTORY_REL = "helped/crud-metrics.jsonl";
 /** Whole-file rewrites change at least half of the bytes or re-serialize with high drift. */
 export const BYTE_DIFF_WHOLE_FILE_THRESHOLD = 0.5;
 function isRecord(value) {
@@ -85,16 +86,19 @@ function sanitizeInlineMessage(message) {
 function ensureParentDir(path) {
     mkdirSync(dirname(path), { recursive: true });
 }
-/** Absolute path to the versioned CRUD metrics ledger (#1703 Tier 1). */
+/** Absolute path to the versioned CRUD metrics ledger (#1703 Tier 1 / #2545). */
 export function crudMetricsHistoryPath(projectRoot) {
-    return resolveEvalPath(projectRoot, CRUD_METRICS_HISTORY_REL);
+    return helpedMetricsHistoryPath(projectRoot);
 }
-/** Append CRUD operation metrics to the versioned ledger (#1703 Tier 1). */
+/** Append CRUD operation metrics to the versioned ledger (#1703 Tier 1 / #2545). */
 export function persistCrudMetrics(projectRoot, metrics) {
     if (metrics.length === 0) {
         return;
     }
     const path = crudMetricsHistoryPath(projectRoot);
+    if (path === null) {
+        return;
+    }
     mkdirSync(dirname(path), { recursive: true });
     for (const metric of metrics) {
         appendFileSync(path, `${JSON.stringify(metric)}\n`, "utf8");

package/dist/eval/health.d.ts

@@ -1,5 +1,6 @@
 export declare const HEALTH_SCHEMA_VERSION: 1;
-export declare const HEALTH_HISTORY_REL = "results/health-history.jsonl";
+/** Relative path under the resolved metrics home for eval:health history (#2545). */
+export declare const HEALTH_HISTORY_REL = "health/health-history.jsonl";
 /** One static Tier-0 gate probe aggregated into the health score. */
 export interface GateProbeResult {
     readonly id: string;
@@ -37,15 +38,15 @@ export interface EvaluateHealthResult {
     readonly report: HealthReport | null;
     readonly message: string;
 }
-/** Absolute path to the versioned health history ledger. */
-export declare function healthHistoryPath(projectRoot: string): string;
+/** Absolute path to the versioned health history ledger (#2545). */
+export declare function healthHistoryPath(projectRoot: string): string | null;
 /** Detect the canonical wipCap unsatisfiable-nudge contradiction (#1694). */
 export declare function detectWipCapUnsatisfiableNudge(projectRoot: string): ContradictionEvidence | null;
 /** Run all registered contradictory-gate detectors. */
 export declare function detectContradictoryGates(projectRoot: string): ContradictionEvidence[];
 /** Compute a 0-100 score from gate pass rate minus contradiction penalty. */
 export declare function computeHealthScore(gates: readonly GateProbeResult[], contradictions: readonly ContradictionEvidence[]): number;
-/** Append one health run to the versioned ledger (#1703 Tier 0). */
+/** Append one health run to the versioned ledger (#1703 Tier 0 / #2545). */
 export declare function persistHealthRun(projectRoot: string, report: HealthReport): void;
 /** Aggregate Tier-0 static gates into a versioned framework health score (#1703). */
 export declare function evaluateHealth(options?: EvaluateHealthOptions): EvaluateHealthResult;

package/dist/eval/health.js

@@ -3,7 +3,8 @@ import { dirname, resolve } from "node:path";
 import { agentsRefreshPlan } from "../doctor/agents-md.js";
 import { evaluate as evaluateEncoding } from "../encoding/evaluate.js";
 import { readCorePackageVersion } from "../engine-version.js";
-import { resolveEvalPath, resolveProjectDefinitionPath } from "../layout/resolve.js";
+import { resolveProjectDefinitionPath } from "../layout/resolve.js";
+import { healthMetricsHistoryPath } from "../metrics/resolve-metrics-home.js";
 import { readPlanPolicy } from "../policy/plan-extensions.js";
 import { classifyOnboarding, detectPriorState } from "../triage/welcome/prior-state.js";
 import { validateLinks } from "../validate-content/index.js";
@@ -11,7 +12,8 @@ import { evaluateConformance } from "../vbrief-validate/conformance.js";
 import { validateWipCapOnPlan } from "../vbrief-validate/plan-hooks.js";
 import { evaluateContentManifest } from "../verify-source/content-manifest.js";
 export const HEALTH_SCHEMA_VERSION = 1;
-export const HEALTH_HISTORY_REL = "results/health-history.jsonl";
+/** Relative path under the resolved metrics home for eval:health history (#2545). */
+export const HEALTH_HISTORY_REL = "health/health-history.jsonl";
 function sanitizeOneLine(value) {
     return value.replace(/\r?\n/g, " ");
 }
@@ -99,9 +101,9 @@ function probeContentManifest(projectRoot) {
         detail: result.code === 0 ? undefined : result.message.split("\n")[0],
     };
 }
-/** Absolute path to the versioned health history ledger. */
+/** Absolute path to the versioned health history ledger (#2545). */
 export function healthHistoryPath(projectRoot) {
-    return resolveEvalPath(projectRoot, HEALTH_HISTORY_REL);
+    return healthMetricsHistoryPath(projectRoot);
 }
 /** Detect the canonical wipCap unsatisfiable-nudge contradiction (#1694). */
 export function detectWipCapUnsatisfiableNudge(projectRoot) {
@@ -154,9 +156,12 @@ export function computeHealthScore(gates, contradictions) {
     const penalty = contradictions.length * 15;
     return Math.max(0, base - penalty);
 }
-/** Append one health run to the versioned ledger (#1703 Tier 0). */
+/** Append one health run to the versioned ledger (#1703 Tier 0 / #2545). */
 export function persistHealthRun(projectRoot, report) {
     const path = healthHistoryPath(projectRoot);
+    if (path === null) {
+        return;
+    }
     mkdirSync(dirname(path), { recursive: true });
     appendFileSync(path, `${JSON.stringify(report)}\n`, "utf8");
 }
@@ -223,17 +228,20 @@ export function evaluateHealth(options = {}) {
         contradictions,
     };
     if (persist) {
-        try {
-            persistHealthRun(projectRoot, report);
-        }
-        catch (err) {
-            const persistError = `eval:health: failed to persist health history: ${String(err)}`;
-            const healthy = score === 100 && contradictions.length === 0;
-            return {
-                code: healthy ? 0 : 1,
-                report,
-                message: `${formatHumanReport(report)}\n${persistError}`,
-            };
+        const ledgerPath = healthHistoryPath(projectRoot);
+        if (ledgerPath !== null) {
+            try {
+                persistHealthRun(projectRoot, report);
+            }
+            catch (err) {
+                const persistError = `eval:health: failed to persist health history: ${String(err)}`;
+                const healthy = score === 100 && contradictions.length === 0;
+                return {
+                    code: healthy ? 0 : 1,
+                    report,
+                    message: `${formatHumanReport(report)}\n${persistError}`,
+                };
+            }
         }
     }
     const healthy = score === 100 && contradictions.length === 0;

package/dist/eval/readback.js

@@ -28,14 +28,8 @@ function parseJsonObjectOrNull(text) {
     return null;
 }
 function readHealthHistoryRows(projectRoot) {
-    let path;
-    try {
-        path = healthHistoryPath(projectRoot);
-    }
-    catch {
-        return []; // No xbrief/ layout; no health history.
-    }
-    if (!existsSync(path)) {
+    const path = healthHistoryPath(projectRoot);
+    if (path === null || !existsSync(path)) {
         return [];
     }
     let text;

package/dist/index.d.ts

@@ -25,6 +25,7 @@ export * as intake from "./intake/index.js";
 export * as layout from "./layout/index.js";
 export * as legacyBridge from "./legacy-bridge/index.js";
 export * as lifecycle from "./lifecycle/index.js";
+export * as metrics from "./metrics/index.js";
 export * as orchestration from "./orchestration/index.js";
 export * as packs from "./packs/index.js";
 export * as platform from "./platform/index.js";

package/dist/index.js

@@ -25,6 +25,7 @@ export * as intake from "./intake/index.js";
 export * as layout from "./layout/index.js";
 export * as legacyBridge from "./legacy-bridge/index.js";
 export * as lifecycle from "./lifecycle/index.js";
+export * as metrics from "./metrics/index.js";
 export * as orchestration from "./orchestration/index.js";
 export * as packs from "./packs/index.js";
 export * as platform from "./platform/index.js";

package/dist/init-deposit/scaffold.js

@@ -10,12 +10,19 @@ import { mkdir, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { platform } from "node:os";
 import { dirname, join, relative } from "node:path";
 import { copyTree } from "../deposit/copy-tree.js";
+import { assertProjectionContained, ProjectionContainmentError, } from "../fs/projection-containment.js";
 import { agentsRefreshPlan } from "../platform/agents-md.js";
 import { MIGRATED_ARTIFACT_DIR } from "../xbrief-migrate/constants.js";
 import { CANONICAL_INSTALL_ROOT } from "./constants.js";
 import { installerManagedGuardEre } from "./hygiene.js";
 export { CANONICAL_INSTALL_ROOT };
 export const CORE_GLOB = ".deft/core/**";
+/** Refuse init/update projection writes that escape via repo-controlled symlinks (#2446). */
+function projectionTarget(projectDir, ...relSegments) {
+    const target = join(projectDir, ...relSegments);
+    assertProjectionContained(projectDir, target);
+    return target;
+}
 const CODEQL_CONFIG_REL = ".github/codeql/codeql-config.yml";
 const CORE_GUARD_WORKFLOW_REL = ".github/workflows/deft-core-guard.yml";
 const FRAMEWORK_SELF_TEST_REL = ".deft/core/tests";
@@ -232,7 +239,7 @@ export const PIN_DEPENDENCY_NAME = "@deftai/directive";
  */
 export function ensurePackageJsonPin(projectDir, version, io) {
     const pinVersion = version.trim().replace(/^v/i, "");
-    const path = join(projectDir, "package.json");
+    const path = projectionTarget(projectDir, "package.json");
     const existed = existsSync(path);
     let pkg = {};
     if (existed) {
@@ -284,7 +291,7 @@ export function writeAgentsMd(projectDir, deftDir, io) {
     if (typeof newContent !== "string") {
         throw new Error("AGENTS.md render produced no content");
     }
-    const path = join(projectDir, "AGENTS.md");
+    const path = projectionTarget(projectDir, "AGENTS.md");
     writeFileSync(path, newContent, "utf8");
     if (state === "absent") {
         io.printf("AGENTS.md created.\n");
@@ -294,9 +301,9 @@ export function writeAgentsMd(projectDir, deftDir, io) {
     }
     return true;
 }
-async function ensureVbriefLifecycleDirs(consumerVbrief) {
+async function ensureVbriefLifecycleDirs(projectDir) {
     for (const sub of VBRIEF_LIFECYCLE_DIRS) {
-        const dir = join(consumerVbrief, sub);
+        const dir = projectionTarget(projectDir, MIGRATED_ARTIFACT_DIR, sub);
         await mkdir(dir, { recursive: true, mode: 0o755 });
         const gitkeep = join(dir, ".gitkeep");
         try {
@@ -323,9 +330,9 @@ function vbriefLifecycleDirsPresent(consumerVbrief) {
     });
 }
 export async function writeConsumerVbrief(projectDir, deftDir, io) {
-    const consumerVbrief = join(projectDir, MIGRATED_ARTIFACT_DIR);
-    const schemasDst = join(consumerVbrief, "schemas");
-    const vbriefMdDst = join(consumerVbrief, "vbrief.md");
+    const consumerVbrief = projectionTarget(projectDir, MIGRATED_ARTIFACT_DIR);
+    const schemasDst = projectionTarget(projectDir, MIGRATED_ARTIFACT_DIR, "schemas");
+    const vbriefMdDst = projectionTarget(projectDir, MIGRATED_ARTIFACT_DIR, "vbrief.md");
     const schemasPresent = existsSync(schemasDst) && statSync(schemasDst).isDirectory();
     const vbriefMdPresent = existsSync(vbriefMdDst) && statSync(vbriefMdDst).isFile();
     const lifecyclePresent = vbriefLifecycleDirsPresent(consumerVbrief);
@@ -352,20 +359,21 @@ export async function writeConsumerVbrief(projectDir, deftDir, io) {
             writeFileSync(vbriefMdDst, VBRIEF_README_BODY, "utf8");
         }
     }
-    await ensureVbriefLifecycleDirs(consumerVbrief);
+    await ensureVbriefLifecycleDirs(projectDir);
     io.printf("vbrief/ deposited at project root (schemas + vbrief.md + lifecycle dirs).\n");
     return true;
 }
 export function writeAgentsSkills(projectDir, io) {
+    projectionTarget(projectDir, ".agents");
     const allExist = AGENTS_SKILLS.every((skill) => existsSync(join(projectDir, ".agents", "skills", skill.dir, "SKILL.md")));
     if (allExist) {
         io.printf(".agents/skills/ already present — skipping.\n");
         return false;
     }
     for (const skill of AGENTS_SKILLS) {
-        const dir = join(projectDir, ".agents", "skills", skill.dir);
+        const dir = projectionTarget(projectDir, ".agents", "skills", skill.dir);
         mkdirSync(dir, { recursive: true });
-        const path = join(dir, "SKILL.md");
+        const path = projectionTarget(projectDir, ".agents", "skills", skill.dir, "SKILL.md");
         if (existsSync(path))
             continue;
         writeFileSync(path, skill.content, "utf8");
@@ -412,7 +420,7 @@ function insertDeftIncludeAfterIncludesLine(content) {
     return { content, ok: false };
 }
 export function ensureTaskfile(projectDir, io) {
-    const path = join(projectDir, "Taskfile.yml");
+    const path = projectionTarget(projectDir, "Taskfile.yml");
     let existing = "";
     if (existsSync(path)) {
         existing = readFileSync(path, "utf8");
@@ -466,7 +474,7 @@ export function writeConsumerGitHooks(projectDir, deftDir, io, seams = {}) {
         io.printf(`git hooks source ${srcDir} absent — skipping hook wiring.\n`);
         return false;
     }
-    const dstDir = join(projectDir, ".githooks");
+    const dstDir = projectionTarget(projectDir, ".githooks");
     mkdirSync(dstDir, { recursive: true });
     let filesDeposited = false;
     for (const name of [...HOOK_FILENAMES, ...HOOK_SUPPORT_FILENAMES]) {
@@ -474,7 +482,7 @@ export function writeConsumerGitHooks(projectDir, deftDir, io, seams = {}) {
         if (!existsSync(src))
             continue;
         const data = readFileSync(src);
-        const dst = join(dstDir, name);
+        const dst = projectionTarget(projectDir, ".githooks", name);
         const existing = existsSync(dst) ? readFileSync(dst) : null;
         const isHookScript = HOOK_FILENAMES.includes(name);
         if (!existing?.equals(data)) {
@@ -656,7 +664,7 @@ function coreGuardWorkflowContent() {
         '          echo "OK: no mixed framework + app changes."\n');
 }
 export function ensureGitattributes(projectDir, io) {
-    const path = join(projectDir, ".gitattributes");
+    const path = projectionTarget(projectDir, ".gitattributes");
     const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
     const present = new Set(existing.split("\n").map((line) => line.trim()));
     const additions = CORE_GITATTRIBUTES_LINES.filter((line) => !present.has(line));
@@ -691,7 +699,7 @@ function appendGreptilePattern(patterns, glob) {
     return `${patterns}\n${glob}`;
 }
 export function ensureGreptileIgnore(projectDir, io) {
-    const path = join(projectDir, "greptile.json");
+    const path = projectionTarget(projectDir, "greptile.json");
     const fileExisted = existsSync(path);
     let raw = fileExisted ? readFileSync(path, "utf8") : "";
     if (!raw.trim())
@@ -766,7 +774,7 @@ function insertCodeqlPathsIgnore(content, glob) {
     return { content, ok: false };
 }
 export function ensureCodeqlPathsIgnore(projectDir, io) {
-    const path = join(projectDir, CODEQL_CONFIG_REL);
+    const path = projectionTarget(projectDir, CODEQL_CONFIG_REL);
     if (!existsSync(path)) {
         mkdirSync(dirname(path), { recursive: true });
         writeFileSync(path, codeqlConfigDefault(), "utf8");
@@ -787,7 +795,7 @@ export function ensureCodeqlPathsIgnore(projectDir, io) {
     return true;
 }
 export function ensureCoreGuardWorkflow(projectDir, io) {
-    const path = join(projectDir, CORE_GUARD_WORKFLOW_REL);
+    const path = projectionTarget(projectDir, CORE_GUARD_WORKFLOW_REL);
     const desired = coreGuardWorkflowContent();
     if (existsSync(path)) {
         const existing = readFileSync(path, "utf8");
@@ -866,6 +874,9 @@ export async function depositNeutralization(projectDir, io, options = {}) {
             await step();
         }
         catch (cause) {
+            if (cause instanceof ProjectionContainmentError) {
+                throw cause;
+            }
             io.printf(`Warning: neutralization step failed: ${String(cause)}\n`);
         }
     }

package/dist/intake/issue-ingest.js

@@ -8,7 +8,7 @@ import { resolveProjectRoot } from "../scope/project-context.js";
 import { resolveProjectRepo } from "../slice/project-context.js";
 import { slugify, TODAY } from "../vbrief-build/build.js";
 import { EMITTED_VBRIEF_VERSION } from "../vbrief-build/constants.js";
-import { LEGACY_ARTIFACT_SUFFIX, LEGACY_INFO_ROOT_KEY, LEGACY_VBRIEF_VERSION, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY, VBRIEF_VERSION, } from "../xbrief-migrate/constants.js";
+import { LEGACY_ARTIFACT_SUFFIX, LEGACY_INFO_ROOT_KEY, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY, VBRIEF_VERSION, } from "../xbrief-migrate/constants.js";
 import { findAcHeading, parseCheckboxItems, parseListItems, sliceAcSection, stripCodeBlocks, stripFencedCodeBlocks, } from "./markdown-scanners.js";
 import { detectRepo, extractReferencesFromVbrief, fetchOpenIssues, GITHUB_ISSUE_REF_TYPES, LIFECYCLE_FOLDERS, parseIssueNumber, } from "./reconcile-issues.js";
 export const INGEST_STATUSES = ["proposed", "pending", "active"];
@@ -78,7 +78,7 @@ function resolveIngestEmissionLayout(vbriefDir) {
         return {
             artifactSuffix: LEGACY_ARTIFACT_SUFFIX,
             infoRootKey: LEGACY_INFO_ROOT_KEY,
-            infoVersion: LEGACY_VBRIEF_VERSION,
+            infoVersion: EMITTED_VBRIEF_VERSION,
         };
     }
     return {
@@ -300,11 +300,25 @@ export function issueCommentThread(issue) {
 export function issueCommentsAlreadyFetched(issue) {
     return Object.hasOwn(issue, ISSUE_COMMENT_THREAD_KEY);
 }
+/**
+ * Run quarantine `scan()` on untrusted ingest text (#2447). Fail closed on a
+ * credential hard-fail; return the fenced/quarantined transform for soft signals.
+ */
+function scanUntrustedIngestText(issueNumber, text) {
+    const scanResult = scan(text);
+    const hardFails = scanResult.flags.filter((f) => f.severity === "hard-fail");
+    if (hardFails.length > 0) {
+        throw new ScannerHardFailError(issueNumber, scanResult.flags);
+    }
+    return scanResult.transformed_content;
+}
 export function buildIssueVbrief(issue, status, repoUrl, options = {}) {
     const number = Number(issue.number);
-    const title = (typeof issue.title === "string" && issue.title.length > 0
+    const titleRaw = (typeof issue.title === "string" && issue.title.length > 0
         ? issue.title
         : `Issue #${number}`) || `Issue #${number}`;
+    // #2447: quarantine-scan issue title before it lands in agent-authoritative fields.
+    const title = scanUntrustedIngestText(number, titleRaw);
     const url = (typeof issue.url === "string" && issue.url.length > 0 ? issue.url : "") ||
         (repoUrl.length > 0 ? `${repoUrl}/issues/${number}` : "");
     const bodyRaw = issue.body;
@@ -345,7 +359,12 @@ export function buildIssueVbrief(issue, status, repoUrl, options = {}) {
     if (labelNames.length > 0) {
         narratives.Labels = labelNames.join(", ");
     }
-    const planItems = bodyStr.length > 0 ? extractPlanItems(bodyStr) : [];
+    const planItemsRaw = bodyStr.length > 0 ? extractPlanItems(bodyStr) : [];
+    // #2447: scan each derived plan-item title (empty-body issues still scan title above).
+    const planItems = planItemsRaw.map((item) => ({
+        ...item,
+        title: scanUntrustedIngestText(number, String(item.title ?? "")),
+    }));
     const plan = {
         title,
         status: planStatus,

package/dist/metrics/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./resolve-metrics-home.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/metrics/index.js

@@ -0,0 +1,2 @@
+export * from "./resolve-metrics-home.js";
+//# sourceMappingURL=index.js.map

package/dist/metrics/resolve-metrics-home.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Shared metrics home resolver (#2545).
+ *
+ * Helped (value / CRUD) and health (eval:health) append logs are machine-local
+ * telemetry — not project source. They resolve outside the git worktree via an
+ * explicit ladder shared with USER.md platform discovery (#2271 / #2544):
+ *
+ *   1. `DEFT_METRICS_HOME` or `DEFT_EVAL_HOME` — explicit override (CI / headless)
+ *   2. `<projectRoot>/.deft/metrics/` — workspace-local opt-in when
+ *      `DEFT_METRICS_PROJECT_LOCAL=1`
+ *   3. Platform user-data (`%APPDATA%\deft\metrics` / `~/.config/deft/metrics`)
+ *   4. Soft-disable when the resolved root is not writable — never fall back to
+ *      `xbrief/.eval/results/`.
+ */
+export declare const METRICS_DISABLED_DIAGNOSTIC = "metrics persistence disabled";
+export declare const DEFT_METRICS_HOME_ENV = "DEFT_METRICS_HOME";
+export declare const DEFT_EVAL_HOME_ENV = "DEFT_EVAL_HOME";
+export declare const DEFT_METRICS_PROJECT_LOCAL_ENV = "DEFT_METRICS_PROJECT_LOCAL";
+export declare const PROJECT_LOCAL_METRICS_DIR = ".deft/metrics";
+export declare const HELPED_METRICS_FILENAME = "crud-metrics.jsonl";
+export declare const HEALTH_METRICS_FILENAME = "health-history.jsonl";
+export type MetricsHomeRung = "env-override" | "project-local" | "platform-user-data" | "disabled";
+export interface ResolveMetricsHomeResult {
+    /** Absolute metrics root, or null when persistence is disabled. */
+    readonly root: string | null;
+    readonly rung: MetricsHomeRung;
+    /** False when no writable metrics root could be resolved. */
+    readonly enabled: boolean;
+    readonly diagnostic: string;
+}
+export interface ResolveMetricsHomeOptions {
+    readonly projectRoot?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly platform?: NodeJS.Platform;
+    readonly homeDir?: string;
+    /** Writable probe. Defaults to mkdir + W_OK access check. */
+    readonly probeWritable?: (path: string) => boolean;
+}
+/**
+ * Resolve the platform user-data metrics directory (`%APPDATA%\deft\metrics` /
+ * `~/.config/deft/metrics`).
+ */
+export declare function platformMetricsDir(platform: NodeJS.Platform, env: NodeJS.ProcessEnv, homeDir: string): string;
+/** Resolve the metrics home root across the first-hit-wins ladder (#2545). */
+export declare function resolveMetricsHome(options?: ResolveMetricsHomeOptions): ResolveMetricsHomeResult;
+/** Absolute path to the helped / value metrics ledger (`helped/crud-metrics.jsonl`). */
+export declare function helpedMetricsHistoryPath(projectRoot: string, options?: ResolveMetricsHomeOptions): string | null;
+/** Absolute path to the health metrics ledger (`health/health-history.jsonl`). */
+export declare function healthMetricsHistoryPath(projectRoot: string, options?: ResolveMetricsHomeOptions): string | null;
+//# sourceMappingURL=resolve-metrics-home.d.ts.map

package/dist/metrics/resolve-metrics-home.js

@@ -0,0 +1,125 @@
+/**
+ * Shared metrics home resolver (#2545).
+ *
+ * Helped (value / CRUD) and health (eval:health) append logs are machine-local
+ * telemetry — not project source. They resolve outside the git worktree via an
+ * explicit ladder shared with USER.md platform discovery (#2271 / #2544):
+ *
+ *   1. `DEFT_METRICS_HOME` or `DEFT_EVAL_HOME` — explicit override (CI / headless)
+ *   2. `<projectRoot>/.deft/metrics/` — workspace-local opt-in when
+ *      `DEFT_METRICS_PROJECT_LOCAL=1`
+ *   3. Platform user-data (`%APPDATA%\deft\metrics` / `~/.config/deft/metrics`)
+ *   4. Soft-disable when the resolved root is not writable — never fall back to
+ *      `xbrief/.eval/results/`.
+ */
+import { accessSync, constants, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { platformUserConfigDir } from "../user-config/resolve-user-md.js";
+export const METRICS_DISABLED_DIAGNOSTIC = "metrics persistence disabled";
+export const DEFT_METRICS_HOME_ENV = "DEFT_METRICS_HOME";
+export const DEFT_EVAL_HOME_ENV = "DEFT_EVAL_HOME";
+export const DEFT_METRICS_PROJECT_LOCAL_ENV = "DEFT_METRICS_PROJECT_LOCAL";
+export const PROJECT_LOCAL_METRICS_DIR = ".deft/metrics";
+export const HELPED_METRICS_FILENAME = "crud-metrics.jsonl";
+export const HEALTH_METRICS_FILENAME = "health-history.jsonl";
+function defaultProbeWritable(path) {
+    try {
+        mkdirSync(path, { recursive: true });
+        accessSync(path, constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function metricsEnvOverride(env) {
+    const primary = env[DEFT_METRICS_HOME_ENV]?.trim();
+    if (primary) {
+        return primary;
+    }
+    const legacy = env[DEFT_EVAL_HOME_ENV]?.trim();
+    return legacy || null;
+}
+/**
+ * Resolve the platform user-data metrics directory (`%APPDATA%\deft\metrics` /
+ * `~/.config/deft/metrics`).
+ */
+export function platformMetricsDir(platform, env, homeDir) {
+    return join(platformUserConfigDir(platform, env, homeDir), "metrics");
+}
+/** Resolve the metrics home root across the first-hit-wins ladder (#2545). */
+export function resolveMetricsHome(options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const homeDir = options.homeDir ?? homedir();
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const probeWritable = options.probeWritable ?? defaultProbeWritable;
+    const override = metricsEnvOverride(env);
+    if (override) {
+        const root = resolve(override);
+        if (probeWritable(root)) {
+            return {
+                root,
+                rung: "env-override",
+                enabled: true,
+                diagnostic: `metrics home resolved from ${DEFT_METRICS_HOME_ENV}/${DEFT_EVAL_HOME_ENV}: ${root}`,
+            };
+        }
+        return {
+            root: null,
+            rung: "disabled",
+            enabled: false,
+            diagnostic: `${METRICS_DISABLED_DIAGNOSTIC} (${DEFT_METRICS_HOME_ENV} not writable: ${root})`,
+        };
+    }
+    if (env[DEFT_METRICS_PROJECT_LOCAL_ENV] === "1") {
+        const root = resolve(join(projectRoot, PROJECT_LOCAL_METRICS_DIR));
+        if (probeWritable(root)) {
+            return {
+                root,
+                rung: "project-local",
+                enabled: true,
+                diagnostic: `metrics home resolved from workspace-local opt-in: ${root}`,
+            };
+        }
+        return {
+            root: null,
+            rung: "disabled",
+            enabled: false,
+            diagnostic: `${METRICS_DISABLED_DIAGNOSTIC} (workspace-local metrics dir not writable: ${root})`,
+        };
+    }
+    const root = platformMetricsDir(platform, env, homeDir);
+    if (probeWritable(root)) {
+        return {
+            root,
+            rung: "platform-user-data",
+            enabled: true,
+            diagnostic: `metrics home resolved from platform user-data: ${root}`,
+        };
+    }
+    return {
+        root: null,
+        rung: "disabled",
+        enabled: false,
+        diagnostic: `${METRICS_DISABLED_DIAGNOSTIC} (platform user-data not writable: ${root})`,
+    };
+}
+/** Absolute path to the helped / value metrics ledger (`helped/crud-metrics.jsonl`). */
+export function helpedMetricsHistoryPath(projectRoot, options = {}) {
+    const home = resolveMetricsHome({ ...options, projectRoot });
+    if (!home.enabled || home.root === null) {
+        return null;
+    }
+    return join(home.root, "helped", HELPED_METRICS_FILENAME);
+}
+/** Absolute path to the health metrics ledger (`health/health-history.jsonl`). */
+export function healthMetricsHistoryPath(projectRoot, options = {}) {
+    const home = resolveMetricsHome({ ...options, projectRoot });
+    if (!home.enabled || home.root === null) {
+        return null;
+    }
+    return join(home.root, "health", HEALTH_METRICS_FILENAME);
+}
+//# sourceMappingURL=resolve-metrics-home.js.map

package/dist/packaging/openpackage-tiers.d.ts

@@ -0,0 +1,12 @@
+export type OpenPackageTierName = "daily-core" | "standard" | "advanced";
+export interface OpenPackageTierManifest {
+    readonly defaultInstallTier: OpenPackageTierName;
+    readonly tiers: Record<OpenPackageTierName, {
+        skills: string[];
+    }>;
+}
+/** Default OpenPackage install tier from deft-tiers.json (#2494). */
+export declare function getOpenPackageDefaultInstallTier(repoRoot: string): OpenPackageTierName;
+/** Skill names for an OpenPackage tier selection (`all` = every mapped skill). */
+export declare function resolveOpenPackageTierSkills(repoRoot: string, tier: OpenPackageTierName | "all"): string[];
+//# sourceMappingURL=openpackage-tiers.d.ts.map

package/dist/packaging/openpackage-tiers.js

@@ -0,0 +1,42 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+const TIER_NAMES = ["daily-core", "standard", "advanced"];
+function isOpenPackageTierName(value) {
+    return TIER_NAMES.includes(value);
+}
+function loadOpenPackageTierManifest(repoRoot) {
+    const path = join(repoRoot, "packaging", "openpackage", "deft-tiers.json");
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (parsed === null || typeof parsed !== "object" || !parsed.tiers) {
+        throw new Error("deft-tiers.json must be an object with a tiers field");
+    }
+    for (const tier of TIER_NAMES) {
+        const block = parsed.tiers[tier];
+        if (!block || !Array.isArray(block.skills)) {
+            throw new Error(`deft-tiers.json missing tiers.${tier}.skills`);
+        }
+    }
+    const defaultInstallTier = parsed.defaultInstallTier ?? "daily-core";
+    if (!isOpenPackageTierName(defaultInstallTier)) {
+        throw new Error(`deft-tiers.json defaultInstallTier must be one of ${TIER_NAMES.join(", ")}; got ${defaultInstallTier}`);
+    }
+    return {
+        defaultInstallTier,
+        tiers: parsed.tiers,
+    };
+}
+function resolveTierSkills(manifest, tier) {
+    if (tier === "all") {
+        return [...new Set(TIER_NAMES.flatMap((name) => manifest.tiers[name].skills))];
+    }
+    return [...manifest.tiers[tier].skills];
+}
+/** Default OpenPackage install tier from deft-tiers.json (#2494). */
+export function getOpenPackageDefaultInstallTier(repoRoot) {
+    return loadOpenPackageTierManifest(repoRoot).defaultInstallTier;
+}
+/** Skill names for an OpenPackage tier selection (`all` = every mapped skill). */
+export function resolveOpenPackageTierSkills(repoRoot, tier) {
+    return resolveTierSkills(loadOpenPackageTierManifest(repoRoot), tier);
+}
+//# sourceMappingURL=openpackage-tiers.js.map

package/dist/plan-sequence/index.d.ts

@@ -0,0 +1,3 @@
+export { clearPlanSequence, planSequencePath, readPlanSequence, writePlanSequence, } from "./store.js";
+export { advancePlanSequence, type ContinuationResolution, createPlanSequence, EXHAUSTED_FAIL_CLOSED_MESSAGE, EXPLICIT_QUEUE_PHRASES, isExplicitQueueAsk, isPlanFirstPhrase, PLAN_FIRST_PHRASES, PLAN_SEQUENCE_CONTRACT, PLAN_SEQUENCE_FILENAME, type PlanSequence, type PlanSequenceEntry, type PlanSequenceKind, type PlanSequenceVerifyInput, type PlanSequenceVerifyResult, type PlanTargetKind, parsePlanSequence, resolveContinuation, verifyPlanTarget, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/plan-sequence/index.js

@@ -0,0 +1,3 @@
+export { clearPlanSequence, planSequencePath, readPlanSequence, writePlanSequence, } from "./store.js";
+export { advancePlanSequence, createPlanSequence, EXHAUSTED_FAIL_CLOSED_MESSAGE, EXPLICIT_QUEUE_PHRASES, isExplicitQueueAsk, isPlanFirstPhrase, PLAN_FIRST_PHRASES, PLAN_SEQUENCE_CONTRACT, PLAN_SEQUENCE_FILENAME, parsePlanSequence, resolveContinuation, verifyPlanTarget, } from "./types.js";
+//# sourceMappingURL=index.js.map