@deftai/directive-core 0.69.0 → 0.71.0

package/dist/value/feedback-file.js

@@ -0,0 +1,353 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { isFrameworkRepoRoot } from "../check/orchestrator.js";
+import { isValueFeedbackPathAllowed, resolveValueFeedback } from "../policy/value-feedback.js";
+import { GhRestError, restCreateIssue, restIssueListPaginated, } from "../scm/gh-rest.js";
+import { resolveProjectRoot } from "../scope/project-context.js";
+export const DEFAULT_UPSTREAM_REPO = "deftai/directive";
+export const FRAMEWORK_GAP_TITLE_PREFIX = "[framework-gap]";
+function sanitizeOneLine(value) {
+    return value.replace(/\r?\n/g, " ").trim();
+}
+function sectionOrPlaceholder(value, placeholder) {
+    const trimmed = value?.trim() ?? "";
+    return trimmed.length > 0 ? trimmed : placeholder;
+}
+/** True when the resolved project root is the directive maintainer source checkout. */
+export function isMaintainerFrameworkRepo(projectRoot) {
+    return isFrameworkRepoRoot(resolve(projectRoot));
+}
+/** Normalize a title for duplicate comparison (#1709). */
+export function normalizeForDedup(title) {
+    return title
+        .trim()
+        .replace(/^\[framework-gap\]\s*/i, "")
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}]+/gu, " ")
+        .trim();
+}
+/** Build the upstream issue title for a framework-gap report. */
+export function buildFrameworkGapTitle(summary) {
+    const clean = sanitizeOneLine(summary);
+    if (clean.toLowerCase().startsWith(FRAMEWORK_GAP_TITLE_PREFIX.toLowerCase())) {
+        return clean;
+    }
+    return `${FRAMEWORK_GAP_TITLE_PREFIX} ${clean}`;
+}
+/** Build the structured framework-gap issue body. */
+export function buildFrameworkGapBody(input) {
+    const summary = sanitizeOneLine(input.summary);
+    const lines = [
+        "## Summary",
+        "",
+        summary,
+        "",
+        "## Context",
+        "",
+        sectionOrPlaceholder(input.context, "_(not provided)_"),
+        "",
+        "## Expected behavior",
+        "",
+        sectionOrPlaceholder(input.expected, "_(not provided)_"),
+        "",
+        "## Actual behavior / gap",
+        "",
+        sectionOrPlaceholder(input.actual, summary),
+        "",
+        "## Session notes",
+        "",
+        sectionOrPlaceholder(input.sessionNotes, "_(not provided)_"),
+        "",
+        "---",
+        "_Filed via `task feedback:file` from a directive consumer project (Refs #1709 value-feedback gap escalation)._",
+        "",
+    ];
+    return lines.join("\n");
+}
+/** Search open upstream issues for a normalized title match. */
+export function findDuplicateIssue(repo, title, seams = {}) {
+    const needle = normalizeForDedup(title);
+    if (needle.length === 0) {
+        return null;
+    }
+    const issues = restIssueListPaginated(repo, { state: "open", limit: 100, excludePulls: true }, seams);
+    for (const issue of issues) {
+        const issueTitle = typeof issue.title === "string" ? issue.title : "";
+        if (normalizeForDedup(issueTitle) === needle) {
+            const url = typeof issue.html_url === "string" ? issue.html_url : "";
+            if (url.length > 0) {
+                return { url, title: issueTitle };
+            }
+        }
+    }
+    return null;
+}
+function resolveRepo(options) {
+    const explicit = options.repo?.trim();
+    return explicit && explicit.length > 0 ? explicit : DEFAULT_UPSTREAM_REPO;
+}
+function isOffline() {
+    return process.env.DEFT_NO_NETWORK === "1";
+}
+function networkErrorMessage(prefix, err) {
+    const detail = err instanceof GhRestError ? err.message : String(err);
+    return `[deft feedback] ${prefix}: ${detail}\n`;
+}
+function buildConfirmationPrompt(title, body) {
+    return ("Draft framework-gap issue (not filed yet):\n\n" +
+        `Title: ${title}\n\n` +
+        `${body}\n` +
+        "Re-run with --confirm to file this issue upstream after reviewing the draft.\n");
+}
+/** Core feedback:file workflow (#1709 gap escalation). */
+export function runFeedbackFile(options) {
+    const summary = sanitizeOneLine(options.summary);
+    if (summary.length === 0) {
+        return {
+            outcome: "error-bad-args",
+            exitCode: 2,
+            title: "",
+            body: "",
+            repo: resolveRepo(options),
+            message: "Error: summary is required (pass --summary or a positional argument).\n",
+        };
+    }
+    const projectRootRaw = resolveProjectRoot(options.projectRoot ?? undefined);
+    if (projectRootRaw === null) {
+        return {
+            outcome: "error-config",
+            exitCode: 2,
+            title: buildFrameworkGapTitle(summary),
+            body: buildFrameworkGapBody(options),
+            repo: resolveRepo(options),
+            message: "Error: could not resolve project root. Pass --project-root or run from a directive consumer repo.\n",
+        };
+    }
+    const projectRoot = resolve(projectRootRaw);
+    const repo = resolveRepo(options);
+    const title = buildFrameworkGapTitle(summary);
+    const body = buildFrameworkGapBody(options);
+    if (isMaintainerFrameworkRepo(projectRoot)) {
+        return {
+            outcome: "skipped-maintainer",
+            exitCode: 0,
+            title,
+            body,
+            repo,
+            message: "[deft feedback] Skipped: maintainer framework repo detected; gap escalation targets consumer projects only.\n",
+        };
+    }
+    const policy = resolveValueFeedback(projectRoot);
+    if (!isValueFeedbackPathAllowed("upstreamPrompt", policy)) {
+        return {
+            outcome: "blocked-policy",
+            exitCode: 1,
+            title,
+            body,
+            repo,
+            message: "[deft feedback] Blocked: plan.policy.valueFeedback upstreamPrompt is OFF. " +
+                "Enable with `task policy:enable-value-feedback -- --confirm` and set upstreamPrompt, " +
+                "or inspect via `task policy:show --field=valueFeedback`.\n",
+        };
+    }
+    const offline = isOffline();
+    const dryRun = options.dryRun ?? false;
+    const seams = options.seams ?? {};
+    let dedupSkippedNote = "";
+    if (!offline) {
+        try {
+            const duplicate = findDuplicateIssue(repo, title, seams);
+            if (duplicate !== null) {
+                return {
+                    outcome: "blocked-duplicate",
+                    exitCode: 1,
+                    title,
+                    body,
+                    repo,
+                    duplicateUrl: duplicate.url,
+                    message: `[deft feedback] Duplicate detected: open issue ${duplicate.url} ` +
+                        `("${duplicate.title}") matches this report.\n`,
+                };
+            }
+        }
+        catch (err) {
+            return {
+                outcome: "error-network",
+                exitCode: 2,
+                title,
+                body,
+                repo,
+                message: networkErrorMessage("Duplicate search failed", err),
+            };
+        }
+    }
+    else {
+        dedupSkippedNote = "[deft feedback] Note: duplicate detection skipped (DEFT_NO_NETWORK=1).\n\n";
+    }
+    if (!options.confirm) {
+        return {
+            outcome: "draft",
+            exitCode: 1,
+            title,
+            body,
+            repo,
+            message: `${dedupSkippedNote}${buildConfirmationPrompt(title, body)}`,
+        };
+    }
+    if (dryRun || offline) {
+        return {
+            outcome: "draft",
+            exitCode: 0,
+            title,
+            body,
+            repo,
+            message: `${dedupSkippedNote}[deft feedback] Dry run: would file upstream issue in ${repo}.\n` +
+                `${buildConfirmationPrompt(title, body)}`,
+        };
+    }
+    try {
+        const created = restCreateIssue(repo, title, body, [], seams);
+        const issueUrl = typeof created.html_url === "string" && created.html_url.length > 0 ? created.html_url : null;
+        const number = created.number;
+        const urlLine = issueUrl ??
+            (typeof number === "number" ? `https://github.com/${repo}/issues/${number}` : null);
+        return {
+            outcome: "filed",
+            exitCode: 0,
+            title,
+            body,
+            repo,
+            issueUrl: urlLine,
+            message: urlLine !== null
+                ? `[deft feedback] Filed upstream issue: ${urlLine}\n`
+                : "[deft feedback] Issue filed upstream (URL unavailable in API response).\n",
+        };
+    }
+    catch (err) {
+        return {
+            outcome: "error-network",
+            exitCode: 2,
+            title,
+            body,
+            repo,
+            message: networkErrorMessage("Upstream filing failed", err),
+        };
+    }
+}
+/** Parse argv for feedback:file. */
+export function parseFeedbackFileArgs(argv) {
+    const out = {};
+    const positionals = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--confirm")
+            out.confirm = true;
+        else if (arg === "--dry-run")
+            out.dryRun = true;
+        else if (arg === "--json")
+            out.json = true;
+        else if (arg === "--summary") {
+            out.summary = argv[++i];
+        }
+        else if (arg?.startsWith("--summary=")) {
+            out.summary = arg.slice("--summary=".length);
+        }
+        else if (arg === "--context") {
+            out.context = argv[++i];
+        }
+        else if (arg?.startsWith("--context=")) {
+            out.context = arg.slice("--context=".length);
+        }
+        else if (arg === "--expected") {
+            out.expected = argv[++i];
+        }
+        else if (arg?.startsWith("--expected=")) {
+            out.expected = arg.slice("--expected=".length);
+        }
+        else if (arg === "--actual") {
+            out.actual = argv[++i];
+        }
+        else if (arg?.startsWith("--actual=")) {
+            out.actual = arg.slice("--actual=".length);
+        }
+        else if (arg === "--notes" || arg === "--session-notes") {
+            out.sessionNotes = argv[++i];
+        }
+        else if (arg?.startsWith("--notes=")) {
+            out.sessionNotes = arg.slice("--notes=".length);
+        }
+        else if (arg?.startsWith("--session-notes=")) {
+            out.sessionNotes = arg.slice("--session-notes=".length);
+        }
+        else if (arg === "--repo") {
+            out.repo = argv[++i];
+        }
+        else if (arg?.startsWith("--repo=")) {
+            out.repo = arg.slice("--repo=".length);
+        }
+        else if (arg === "--project-root") {
+            out.projectRoot = argv[++i];
+        }
+        else if (arg?.startsWith("--project-root=")) {
+            out.projectRoot = arg.slice("--project-root=".length);
+        }
+        else if (arg.startsWith("-")) {
+            return { ...out, error: `unrecognized argument: ${arg}` };
+        }
+        else {
+            positionals.push(arg);
+        }
+    }
+    if ((out.summary === undefined || out.summary.trim().length === 0) && positionals.length > 0) {
+        out.summary = positionals.join(" ");
+    }
+    return out;
+}
+/** CLI entry for feedback:file. */
+export function feedbackFileMain(argv) {
+    const args = parseFeedbackFileArgs(argv);
+    if (args.error !== undefined) {
+        process.stderr.write(`feedback:file: ${args.error}\n`);
+        return 2;
+    }
+    const result = runFeedbackFile({
+        summary: args.summary ?? "",
+        context: args.context,
+        expected: args.expected,
+        actual: args.actual,
+        sessionNotes: args.sessionNotes,
+        confirm: args.confirm,
+        dryRun: args.dryRun,
+        json: args.json,
+        repo: args.repo,
+        projectRoot: args.projectRoot,
+    });
+    if (args.json) {
+        process.stdout.write(`${JSON.stringify({
+            outcome: result.outcome,
+            exit_code: result.exitCode,
+            title: result.title,
+            body: result.body,
+            repo: result.repo,
+            issue_url: result.issueUrl ?? null,
+            duplicate_url: result.duplicateUrl ?? null,
+            message: result.message.trim(),
+        }, null, 2)}\n`);
+    }
+    else {
+        process.stdout.write(result.message);
+    }
+    return result.exitCode;
+}
+/** CLI module entrypoint for dispatch (#1709). */
+export function mainEntry(argv = process.argv.slice(2)) {
+    return feedbackFileMain(argv);
+}
+/** Convenience probe used in tests for project-root sentinel presence. */
+export function projectRootLooksLikeConsumer(projectRoot) {
+    const root = resolve(projectRoot);
+    return (existsSync(resolve(root, "xbrief")) ||
+        existsSync(resolve(root, "vbrief")) ||
+        existsSync(resolve(root, ".deft")));
+}
+//# sourceMappingURL=feedback-file.js.map

package/dist/value/friction-emit.d.ts

@@ -0,0 +1,10 @@
+import { type ValueFeedbackResolved } from "../policy/value-feedback.js";
+export interface FrictionEmitOptions {
+    readonly logPath?: string | null;
+    readonly policyOverride?: ValueFeedbackResolved;
+}
+/** Record friction signals for each contradictory gate detected by eval:health (#2339). */
+export declare function recordFrictionFromContradictoryGates(projectRoot: string, options?: FrictionEmitOptions): number;
+/** Session/work-boundary friction probe alias (#2339). */
+export declare function probeFrictionAtWorkBoundary(projectRoot: string, options?: FrictionEmitOptions): number;
+//# sourceMappingURL=friction-emit.d.ts.map

package/dist/value/friction-emit.js

@@ -0,0 +1,24 @@
+import { detectContradictoryGates } from "../eval/health.js";
+import { recordFrictionSignal } from "../events/attribution-ledger.js";
+import { isValueFeedbackPathAllowed, resolveValueFeedback, } from "../policy/value-feedback.js";
+/** Record friction signals for each contradictory gate detected by eval:health (#2339). */
+export function recordFrictionFromContradictoryGates(projectRoot, options = {}) {
+    const policy = options.policyOverride ?? resolveValueFeedback(projectRoot);
+    if (!isValueFeedbackPathAllowed("emitEvents", policy)) {
+        return 0;
+    }
+    const contradictions = detectContradictoryGates(projectRoot);
+    let recorded = 0;
+    for (const contradiction of contradictions) {
+        const record = recordFrictionSignal(projectRoot, "eval:health", `${contradiction.id}: ${contradiction.summary}`, { logPath: options.logPath, policyOverride: policy });
+        if (record !== null) {
+            recorded += 1;
+        }
+    }
+    return recorded;
+}
+/** Session/work-boundary friction probe alias (#2339). */
+export function probeFrictionAtWorkBoundary(projectRoot, options = {}) {
+    return recordFrictionFromContradictoryGates(projectRoot, options);
+}
+//# sourceMappingURL=friction-emit.js.map

package/dist/value/readback.d.ts

@@ -0,0 +1,86 @@
+import { type BehavioralEventRecord } from "../lifecycle/events.js";
+import { type ValueFeedbackResolved } from "../policy/value-feedback.js";
+/** Repeat-suppression window for the budgeted session readback (#1709 / #1279 parity). */
+export declare const VALUE_READBACK_SUPPRESSION_HOURS = 4;
+export declare const VALUE_READBACK_HISTORY_REL: string;
+export declare const VALUE_READBACK_HISTORY_SCHEMA = "deft.value.readback.v1";
+export type SignalClass = "value" | "bypass" | "adoption" | "friction";
+export interface ReadAttributionOptions {
+    readonly projectRoot: string;
+    readonly logPath?: string | null;
+    readonly since?: Date | null;
+}
+export interface ValueShowTrend {
+    readonly windowLabel: string;
+    readonly windowMs: number;
+    readonly total: number;
+    readonly byClass: Readonly<Record<SignalClass, number>>;
+    readonly byEvent: Readonly<Record<string, number>>;
+    readonly recent: readonly BehavioralEventRecord[];
+}
+export interface ValueShowResult {
+    readonly exitCode: 0 | 1 | 2;
+    readonly gated: boolean;
+    readonly empty: boolean;
+    readonly text: string;
+    readonly trend: ValueShowTrend | null;
+}
+export interface SessionReadbackResult {
+    readonly line: string | null;
+    readonly suppressed: boolean;
+    readonly gated: boolean;
+}
+/** Read attribution ledger entries in emission order (#1709). */
+export declare function readAttributionEvents(options: ReadAttributionOptions): BehavioralEventRecord[];
+/** Format one attributed session line from a concrete ledger event (#1709 attributed-only). */
+export declare function formatAttributedSessionLine(record: BehavioralEventRecord): string;
+/** Pick the single highest-priority recent attribution for the session one-liner. */
+export declare function selectSessionAttribution(events: readonly BehavioralEventRecord[]): BehavioralEventRecord | null;
+/** True when the same attribution event id was read back within the suppression window. */
+export declare function shouldSuppressSessionReadback(eventId: string, historyFile: string, options?: {
+    now?: Date;
+}): boolean;
+/** Budgeted session one-liner — silent when gated, empty, or debounced (#1709). */
+export declare function renderSessionReadback(projectRoot: string, options?: {
+    policyOverride?: ValueFeedbackResolved;
+    logPath?: string | null;
+    now?: Date;
+    maxChars?: number;
+    writeHistory?: boolean;
+}): SessionReadbackResult;
+/** Emit the session readback line to stdout when present. Returns the line or null. */
+export declare function emitSessionValueReadback(projectRoot: string, options?: {
+    output?: (line: string) => void;
+    policyOverride?: ValueFeedbackResolved;
+    logPath?: string | null;
+    now?: Date;
+    writeHistory?: boolean;
+}): string | null;
+export declare function parseWindowMs(raw: string | undefined, defaultDays?: number): number;
+/** Build attributed-value trend counts for pull-based value:show (#1709). */
+export declare function computeValueShowTrend(projectRoot: string, options?: {
+    windowMs?: number;
+    logPath?: string | null;
+    now?: Date;
+}): ValueShowTrend;
+export declare function formatValueShowReport(trend: ValueShowTrend): string;
+/** Pull-based value:show CLI core (#1709). */
+export declare function runValueShow(options: {
+    projectRoot?: string | null;
+    window?: string;
+    format?: "text" | "json";
+    logPath?: string | null;
+    policyOverride?: ValueFeedbackResolved;
+}): ValueShowResult;
+export interface ValueShowCliArgs {
+    window?: string;
+    format?: "text" | "json";
+    projectRoot?: string;
+    error?: string;
+}
+export declare function parseValueShowArgs(argv: readonly string[]): ValueShowCliArgs;
+/** CLI entry for value:show (#1709). */
+export declare function valueShowMain(argv?: readonly string[]): number;
+/** CLI module entrypoint for dispatch (#1709). */
+export declare function mainEntry(argv?: string[]): number;
+//# sourceMappingURL=readback.d.ts.map