@deftai/directive-core 0.69.0 → 0.71.0

package/dist/intake/issue-ingest.js

@@ -1,6 +1,7 @@
 import { mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import { cacheGet } from "../cache/operations.js";
+import { scan } from "../cache/scanner.js";
 import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
 import { call } from "../scm/call.js";
 import { resolveProjectRoot } from "../scope/project-context.js";
@@ -11,6 +12,27 @@ import { LEGACY_ARTIFACT_SUFFIX, LEGACY_INFO_ROOT_KEY, LEGACY_VBRIEF_VERSION, MI
 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"];
+/**
+ * Thrown when the quarantine scanner hard-fails (credential-shaped content) on
+ * an ingested issue body/comment thread (#2306). Ingest MUST fail closed: emit
+ * nothing and propagate a non-zero exit rather than persisting the xBRIEF.
+ */
+export class ScannerHardFailError extends Error {
+    issueNumber;
+    flags;
+    constructor(issueNumber, flags) {
+        const details = flags
+            .filter((f) => f.severity === "hard-fail")
+            .map((f) => f.detail)
+            .join("; ");
+        super(`issue:ingest refused #${issueNumber}: quarantine scanner hard-fail` +
+            (details.length > 0 ? ` (${details})` : "") +
+            " -- nothing written.");
+        this.name = "ScannerHardFailError";
+        this.issueNumber = issueNumber;
+        this.flags = flags;
+    }
+}
 /** Enriched on issues after `fetchIssue` when the comment thread is non-empty (#2143). */
 export const ISSUE_COMMENT_THREAD_KEY = "issueCommentThread";
 const STATUS_MAP = {
@@ -311,7 +333,14 @@ export function buildIssueVbrief(issue, status, repoUrl, options = {}) {
     };
     if (overviewSource.length > 0) {
         warnBodyControlCharacters(number, overviewSource);
-        narratives.Overview = overviewSource;
+        // #2306: quarantine-scan untrusted body + comment-thread content before it
+        // is persisted as agent-facing scope authority. Fail closed on a credential
+        // hard-fail; otherwise persist the fenced/quarantined transform.
+        const scanResult = scan(overviewSource);
+        if (!scanResult.passed) {
+            throw new ScannerHardFailError(number, scanResult.flags);
+        }
+        narratives.Overview = scanResult.transformed_content;
     }
     if (labelNames.length > 0) {
         narratives.Labels = labelNames.join(", ");
@@ -369,6 +398,19 @@ export function fetchFromCache(repo, number, options = {}) {
         if (typeof issue.html_url === "string" && issue.html_url.length > 0) {
             issue.url = issue.html_url;
         }
+        // #2306: consume the cache entry's SCANNED content.md (fenced/quarantined at
+        // cache-put) rather than the raw body, so the cache read path cannot bypass
+        // the quarantine transform. When content.md is absent (e.g. a credential
+        // hard-fail deleted it), the raw body falls through and is re-scanned in
+        // buildIssueVbrief.
+        if (result.contentPath !== null) {
+            try {
+                issue.body = readFileSync(result.contentPath, "utf8");
+            }
+            catch {
+                // fall back to the raw body (re-scanned downstream)
+            }
+        }
         return issue;
     }
     catch {
@@ -514,9 +556,25 @@ export function ingestBulk(issues, options) {
         created: [],
         duplicate: [],
         dryrun: [],
+        failed: [],
     };
     for (const issue of filtered) {
-        const [result, path, _msg] = ingestOne(issue, { ...options, existingRefs: refs });
+        let ingested;
+        try {
+            ingested = ingestOne(issue, { ...options, existingRefs: refs });
+        }
+        catch (exc) {
+            // #2306: a per-issue quarantine hard-fail must not sink the whole batch;
+            // record it, emit nothing for that issue, and surface a non-zero exit
+            // upstream via the `failed` bucket.
+            if (exc instanceof ScannerHardFailError) {
+                summary.failed.push(`#${exc.issueNumber}`);
+                process.stderr.write(`${exc.message}\n`);
+                continue;
+            }
+            throw exc;
+        }
+        const [result, path, _msg] = ingested;
         const rel = path !== null ? path.replace(`${options.vbriefDir}/`, "").replace(/\\/g, "/") : "";
         summary[result].push(rel);
         if (result === "created" && path !== null) {
@@ -581,7 +639,8 @@ export function issueIngestMain(args) {
         const created = summary.created;
         const duplicate = summary.duplicate;
         const dryrun = summary.dryrun;
-        process.stdout.write(`issue:ingest bulk summary: ${created.length} created, ${duplicate.length} duplicate, ${dryrun.length} dry-run (total considered: ${summary.total})\n`);
+        const failed = summary.failed ?? [];
+        process.stdout.write(`issue:ingest bulk summary: ${created.length} created, ${duplicate.length} duplicate, ${dryrun.length} dry-run, ${failed.length} refused (total considered: ${summary.total})\n`);
         for (const entry of created) {
             process.stdout.write(`  CREATED ${entry}\n`);
         }
@@ -591,19 +650,35 @@ export function issueIngestMain(args) {
         for (const entry of duplicate) {
             process.stdout.write(`  SKIP    ${entry} (already has scope vBRIEF)\n`);
         }
-        return 0;
+        for (const entry of failed) {
+            process.stdout.write(`  REFUSED ${entry} (quarantine scanner hard-fail; nothing written)\n`);
+        }
+        // #2306: fail closed on any quarantine hard-fail in the batch.
+        return failed.length > 0 ? 2 : 0;
     }
     const issue = fetchIssue(repo, args.number, { cwd: projectRoot });
     if (issue === null) {
         return 2;
     }
-    const [result, _path, msg] = ingestOne(issue, {
-        vbriefDir,
-        status,
-        repoUrl,
-        dryRun: args.dryRun,
-        cwd: projectRoot,
-    });
+    let result;
+    let msg;
+    try {
+        [result, , msg] = ingestOne(issue, {
+            vbriefDir,
+            status,
+            repoUrl,
+            dryRun: args.dryRun,
+            cwd: projectRoot,
+        });
+    }
+    catch (exc) {
+        // #2306: fail closed -- emit nothing, non-zero exit on a quarantine hard-fail.
+        if (exc instanceof ScannerHardFailError) {
+            process.stderr.write(`${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
     process.stdout.write(`${msg}\n`);
     return result === "duplicate" ? 1 : 0;
 }

package/dist/layout/resolve.d.ts

@@ -51,9 +51,9 @@ export declare function resolveLifecycleRoot(projectRoot: string): string;
  * (e.g. `<root>/<xbrief|vbrief>/active`). Layout-aware (#2109 part 2a).
  */
 export declare function resolveLifecycleFolder(projectRoot: string, folder: string): string;
-/** Absolute path to the resolved lifecycle `.eval` cache directory (#2109 part 2a). */
+/** Absolute path to the layout-aware `.eval/` directory for version-eval results (#1703). */
 export declare function resolveEvalDir(projectRoot: string): string;
-/** Absolute path to a file or subpath under the resolved `.eval` cache directory. */
+/** Absolute path under `.eval/` for version-eval artefacts (not triage working-set). */
 export declare function resolveEvalPath(projectRoot: string, ...segments: string[]): string;
 /** Absolute path to the resolved lifecycle `.audit` directory (#2109 part 2a). */
 export declare function resolveAuditDir(projectRoot: string): string;

package/dist/layout/resolve.js

@@ -101,11 +101,11 @@ export function resolveLifecycleRoot(projectRoot) {
 export function resolveLifecycleFolder(projectRoot, folder) {
     return join(resolveLifecycleRoot(projectRoot), folder);
 }
-/** Absolute path to the resolved lifecycle `.eval` cache directory (#2109 part 2a). */
+/** Absolute path to the layout-aware `.eval/` directory for version-eval results (#1703). */
 export function resolveEvalDir(projectRoot) {
     return join(resolveLifecycleRoot(projectRoot), ".eval");
 }
-/** Absolute path to a file or subpath under the resolved `.eval` cache directory. */
+/** Absolute path under `.eval/` for version-eval artefacts (not triage working-set). */
 export function resolveEvalPath(projectRoot, ...segments) {
     return join(resolveEvalDir(projectRoot), ...segments);
 }

package/dist/lifecycle/events.js

@@ -3,10 +3,12 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { contentRoot } from "../content-root.js";
+import { ATTRIBUTION_REQUIRED_PAYLOAD } from "../events/attribution-constants.js";
 /** Default event log location (project-local). */
 export const DEFAULT_EVENT_LOG = join(".deft-cache", "events.jsonl");
 const BEHAVIORAL_CATEGORY = "behavioral";
 const REQUIRED_BEHAVIORAL_PAYLOAD = {
+    ...ATTRIBUTION_REQUIRED_PAYLOAD,
     "session:interrupted": ["session_id", "reason"],
     "session:resumed": ["session_id", "interrupted_id"],
     "plan:approved": ["plan_ref", "approver"],

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 "./resolve.js";
+export * from "./value-feedback.js";
 export * from "./wip.js";
 export declare const FIELD_ALLOW_DIRECT_COMMITS = "plan.policy.allowDirectCommitsToMaster";
 export declare const FIELD_WIP_CAP = "plan.policy.wipCap";
@@ -29,7 +30,7 @@ export interface PolicyField {
 }
 /** Walk registered inspectors and return one row per field (#1148). */
 export declare function inspectAllPolicies(projectRoot: string): PolicyField[];
-/** Look up a single registered field by canonical dotted-path name. */
+/** Look up a single registered field by canonical dotted-path name (or CLI alias). */
 export declare function inspectOnePolicy(name: string, projectRoot: string): PolicyField | null;
 /** Return canonical names of every registered typed-policy field. */
 export declare function registeredPolicyNames(): string[];

package/dist/policy/index.js

@@ -1,5 +1,6 @@
 import { readPlanPolicy } from "./plan-extensions.js";
 import { coerceLegacyNarrative, LEGACY_NARRATIVE_KEY, loadProjectDefinition } from "./resolve.js";
+import { FIELD_VALUE_FEEDBACK, FIELD_VALUE_FEEDBACK_CLI_ALIAS, inspectValueFeedback, } from "./value-feedback.js";
 import { DEFAULT_WIP_CAP } from "./wip.js";
 export * from "./agents-md-advisory.js";
 export * from "./autonomy.js";
@@ -8,6 +9,7 @@ export * from "./decisions.js";
 export * from "./disclosure.js";
 export * from "./plan-extensions.js";
 export * from "./resolve.js";
+export * from "./value-feedback.js";
 export * from "./wip.js";
 export const FIELD_ALLOW_DIRECT_COMMITS = "plan.policy.allowDirectCommitsToMaster";
 export const FIELD_WIP_CAP = "plan.policy.wipCap";
@@ -213,6 +215,15 @@ function inspectSwarmSubagentBackend(data) {
         source: "default-on-error",
     };
 }
+function inspectValueFeedbackField(data) {
+    const field = inspectValueFeedback(data);
+    return {
+        name: field.name,
+        current: field.current,
+        default: field.default,
+        source: field.source,
+    };
+}
 const REGISTERED_POLICIES = [
     inspectAllowDirectCommits,
     inspectWipCap,
@@ -225,16 +236,18 @@ const REGISTERED_POLICIES = [
         emptyIsTyped: true,
     }),
     inspectSwarmSubagentBackend,
+    inspectValueFeedbackField,
 ];
 /** Walk registered inspectors and return one row per field (#1148). */
 export function inspectAllPolicies(projectRoot) {
     const [data] = loadProjectDefinition(projectRoot);
     return REGISTERED_POLICIES.map((inspect) => inspect(data));
 }
-/** Look up a single registered field by canonical dotted-path name. */
+/** Look up a single registered field by canonical dotted-path name (or CLI alias). */
 export function inspectOnePolicy(name, projectRoot) {
+    const normalized = name === FIELD_VALUE_FEEDBACK_CLI_ALIAS ? FIELD_VALUE_FEEDBACK : name;
     for (const field of inspectAllPolicies(projectRoot)) {
-        if (field.name === name)
+        if (field.name === normalized)
             return field;
     }
     return null;

package/dist/policy/plan-extensions.d.ts

@@ -32,4 +32,35 @@ export declare function readPlanCompletedNote(plan: unknown): unknown;
  * bare block alongside the namespaced one.
  */
 export declare function migrateLegacyPolicyKey(plan: Record<string, unknown>): void;
+/** The namespaced/legacy key pairs a bare block can silently shadow (#2301). */
+export declare const SHADOWABLE_PLAN_EXTENSIONS: ReadonlyArray<{
+    readonly namespacedKey: string;
+    readonly legacyKey: string;
+}>;
+/** A plan-extension key whose bare form is silently shadowed by the namespaced form. */
+export interface ShadowedPlanExtension {
+    /** The namespaced key that wins the read (e.g. `x-directive/policy`). */
+    readonly namespacedKey: string;
+    /** The bare legacy key that is silently ignored (e.g. `policy`). */
+    readonly legacyKey: string;
+    /**
+     * Best-effort list of sub-keys present in the shadowed bare object (e.g.
+     * `["triageScope", "wipCap"]`). Empty when the bare value is not an object.
+     */
+    readonly shadowedSubKeys: readonly string[];
+}
+/**
+ * Detect every plan-extension key where a bare (legacy) block coexists with the
+ * namespaced form (#2301). Because `readPlanExtension` is namespace-first, the
+ * bare block is never read once the namespaced key exists -- edits to it take no
+ * effect. Detecting the coexistence lets callers emit a loud diagnostic instead
+ * of the silent no-op that the #2295 onboarding trap exhibited.
+ */
+export declare function detectShadowedPlanExtensions(plan: unknown): ShadowedPlanExtension[];
+/**
+ * Render a human-readable, loud diagnostic for a single shadowed plan-extension
+ * key. The message is surface-agnostic (no leading tag) so each caller can
+ * prefix it (`[policy:show]`, a doctor finding, ...).
+ */
+export declare function describeShadowedPlanExtension(shadow: ShadowedPlanExtension): string;
 //# sourceMappingURL=plan-extensions.d.ts.map

package/dist/policy/plan-extensions.js

@@ -54,4 +54,49 @@ export function migrateLegacyPolicyKey(plan) {
         delete plan[LEGACY_PLAN_POLICY_KEY];
     }
 }
+/** The namespaced/legacy key pairs a bare block can silently shadow (#2301). */
+export const SHADOWABLE_PLAN_EXTENSIONS = [
+    { namespacedKey: PLAN_POLICY_KEY, legacyKey: LEGACY_PLAN_POLICY_KEY },
+    { namespacedKey: PLAN_COMPLETED_NOTE_KEY, legacyKey: LEGACY_PLAN_COMPLETED_NOTE_KEY },
+];
+/**
+ * Detect every plan-extension key where a bare (legacy) block coexists with the
+ * namespaced form (#2301). Because `readPlanExtension` is namespace-first, the
+ * bare block is never read once the namespaced key exists -- edits to it take no
+ * effect. Detecting the coexistence lets callers emit a loud diagnostic instead
+ * of the silent no-op that the #2295 onboarding trap exhibited.
+ */
+export function detectShadowedPlanExtensions(plan) {
+    const planObj = asPlanObject(plan);
+    if (planObj === null) {
+        return [];
+    }
+    const shadows = [];
+    for (const { namespacedKey, legacyKey } of SHADOWABLE_PLAN_EXTENSIONS) {
+        if (planObj[namespacedKey] === undefined || planObj[legacyKey] === undefined) {
+            continue;
+        }
+        const legacyValue = planObj[legacyKey];
+        const shadowedSubKeys = typeof legacyValue === "object" && legacyValue !== null && !Array.isArray(legacyValue)
+            ? Object.keys(legacyValue)
+            : [];
+        shadows.push({ namespacedKey, legacyKey, shadowedSubKeys });
+    }
+    return shadows;
+}
+/**
+ * Render a human-readable, loud diagnostic for a single shadowed plan-extension
+ * key. The message is surface-agnostic (no leading tag) so each caller can
+ * prefix it (`[policy:show]`, a doctor finding, ...).
+ */
+export function describeShadowedPlanExtension(shadow) {
+    const subKeys = shadow.shadowedSubKeys.length > 0
+        ? ` Shadowed field(s): ${shadow.shadowedSubKeys
+            .map((k) => `plan.${shadow.legacyKey}.${k}`)
+            .join(", ")}.`
+        : "";
+    return (`bare \`plan.${shadow.legacyKey}\` coexists with namespaced \`plan.${shadow.namespacedKey}\`; ` +
+        `the bare block is IGNORED (namespaced-first read) so edits to it silently take no effect.${subKeys} ` +
+        `Fold its values into \`plan.${shadow.namespacedKey}\` and delete \`plan.${shadow.legacyKey}\`.`);
+}
 //# sourceMappingURL=plan-extensions.js.map

package/dist/policy/value-feedback.d.ts

@@ -0,0 +1,56 @@
+/** Canonical registered policy field name (matches other FIELD_* dotted paths). */
+export declare const FIELD_VALUE_FEEDBACK = "plan.policy.valueFeedback";
+/** Short alias accepted by `policy:show --field=valueFeedback` (#1709). */
+export declare const FIELD_VALUE_FEEDBACK_CLI_ALIAS = "valueFeedback";
+export declare const DEFAULT_VALUE_FEEDBACK_ENABLED = false;
+/** Sub-flag defaults applied when the master flag is enabled (#1709 tiered-cost decision). */
+export declare const VALUE_FEEDBACK_SUBFLAG_DEFAULTS_WHEN_ENABLED: {
+    readonly emitEvents: true;
+    readonly sessionLine: true;
+    readonly upstreamPrompt: false;
+};
+export type ValueFeedbackSubFlag = keyof typeof VALUE_FEEDBACK_SUBFLAG_DEFAULTS_WHEN_ENABLED;
+export interface ValueFeedbackConfig {
+    readonly enabled: boolean;
+    readonly emitEvents: boolean;
+    readonly sessionLine: boolean;
+    readonly upstreamPrompt: boolean;
+}
+export type ValueFeedbackSource = "typed" | "default" | "default-on-error";
+export interface ValueFeedbackResolved extends ValueFeedbackConfig {
+    readonly source: ValueFeedbackSource;
+    readonly error: string | null;
+}
+export declare const VALUE_FEEDBACK_CAPABILITY_COST_DISCLOSURE: string;
+/** Validate a `plan.policy.valueFeedback` payload. */
+export declare function validateValueFeedback(value: unknown): string[];
+/** Resolve `plan.policy.valueFeedback` from PROJECT-DEFINITION (#1709). */
+export declare function resolveValueFeedback(projectRoot: string): ValueFeedbackResolved;
+/** Master gate: when `enabled` is false, every downstream path is rejected. */
+export declare function isValueFeedbackPathAllowed(path: ValueFeedbackSubFlag, policy: ValueFeedbackResolved): boolean;
+/** Resolved per-path gate booleans for policy:show and enable status output. */
+export declare function valueFeedbackPathGates(policy: ValueFeedbackResolved): Record<ValueFeedbackSubFlag, boolean>;
+/** Human-readable status line for CLI enable/show surfaces. */
+export declare function formatValueFeedbackStatusLine(policy: ValueFeedbackResolved): string;
+export interface ValueFeedbackPolicyField {
+    readonly name: typeof FIELD_VALUE_FEEDBACK;
+    readonly current: ValueFeedbackConfig;
+    readonly default: ValueFeedbackConfig;
+    readonly source: string;
+}
+/** Inspector row for `policy:show --field=valueFeedback`. */
+export declare function inspectValueFeedback(data: Record<string, unknown> | null): ValueFeedbackPolicyField;
+export interface EnableValueFeedbackOptions {
+    readonly confirm: boolean;
+    readonly actor?: string;
+    readonly note?: string;
+    readonly subFlags?: Partial<Record<ValueFeedbackSubFlag, boolean>>;
+}
+export interface EnableValueFeedbackResult {
+    readonly exitCode: 0 | 1 | 2;
+    readonly stdout: string;
+    readonly changed: boolean;
+}
+/** Persist `valueFeedback.enabled=true` after capability-cost disclosure (#1709). */
+export declare function enableValueFeedback(projectRoot: string, options: EnableValueFeedbackOptions): EnableValueFeedbackResult;
+//# sourceMappingURL=value-feedback.d.ts.map