@deftai/directive-core 0.69.0 → 0.71.0

package/dist/value/adoption-emit.js

@@ -0,0 +1,67 @@
+import { execFileSync } from "node:child_process";
+import { recordAdoptionSignal } from "../events/attribution-ledger.js";
+import { isValueFeedbackPathAllowed, resolveValueFeedback, } from "../policy/value-feedback.js";
+import { detectApplicableButUnusedGated } from "./adoption-registry.js";
+/** Best-effort WorkContext snapshot from git porcelain status (#2339). */
+export function buildWorkContextFromGit(projectRoot) {
+    try {
+        const porcelain = execFileSync("git", ["status", "--porcelain"], {
+            cwd: projectRoot,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        const paths = new Set();
+        for (const line of porcelain.split("\n")) {
+            if (line.length < 4) {
+                continue;
+            }
+            let path = line.slice(3).trim();
+            if (path.startsWith('"') && path.endsWith('"')) {
+                path = path.slice(1, -1);
+            }
+            if (path.length > 0) {
+                paths.add(path);
+            }
+        }
+        const modules = new Set();
+        for (const filePath of paths) {
+            const segment = filePath.split("/")[0];
+            if (segment !== undefined && segment.length > 0) {
+                modules.add(segment);
+            }
+        }
+        return {
+            filesTouched: paths.size,
+            distinctModuleGlobs: modules.size,
+            usedCapabilities: [],
+        };
+    }
+    catch {
+        return { filesTouched: 0, distinctModuleGlobs: 0, usedCapabilities: [] };
+    }
+}
+/** Record adoption signals for applicable-but-unused capabilities (#2339). */
+export function recordAdoptionSignalsFromWorkContext(projectRoot, ctx, options = {}) {
+    const policy = options.policyOverride ?? resolveValueFeedback(projectRoot);
+    if (!isValueFeedbackPathAllowed("emitEvents", policy)) {
+        return 0;
+    }
+    const signals = detectApplicableButUnusedGated(ctx, policy);
+    let recorded = 0;
+    for (const signal of signals) {
+        const record = recordAdoptionSignal(projectRoot, signal.capabilityId, signal.message, {
+            logPath: options.logPath,
+            policyOverride: policy,
+        });
+        if (record !== null) {
+            recorded += 1;
+        }
+    }
+    return recorded;
+}
+/** Session/work-boundary adoption probe — builds WorkContext when omitted (#2339). */
+export function probeAdoptionAtWorkBoundary(projectRoot, options = {}) {
+    const ctx = options.workContext ?? buildWorkContextFromGit(projectRoot);
+    return recordAdoptionSignalsFromWorkContext(projectRoot, ctx, options);
+}
+//# sourceMappingURL=adoption-emit.js.map

package/dist/value/adoption-registry.d.ts

@@ -0,0 +1,62 @@
+import { type ValueFeedbackResolved } from "../policy/value-feedback.js";
+/** Canonical directive capabilities tracked for underutilization nudges (#1709). */
+export type CapabilityId = "planning" | "cost" | "decompose" | "swarm" | "pre-pr" | "debug" | "glossary" | "lessons";
+/** How downstream instrumentation knows a capability was exercised. */
+export type UsageSignalSource = "command:/deft:directive:run:interview" | "command:/deft:directive:run:speckit" | "command:task capacity:show" | "command:split-to-prs" | "command:task swarm:launch" | "skill:deft-directive-pre-pr" | "skill:debug-mode" | "command:/deft:glossary" | "command:deft packs:slice";
+export interface CapabilityRecord {
+    readonly id: CapabilityId;
+    readonly label: string;
+    readonly description: string;
+    readonly usageSignals: readonly UsageSignalSource[];
+    readonly nudgeHint: string;
+}
+/** Work snapshot supplied by callers when evaluating adoption heuristics. */
+export interface WorkContext {
+    readonly filesTouched: number;
+    /** Distinct module globs from the codebase map (parallelizability proxy). */
+    readonly distinctModuleGlobs: number;
+    readonly usedCapabilities: readonly CapabilityId[];
+    readonly isBuildIntent?: boolean;
+    readonly isPrOpening?: boolean;
+}
+export interface ApplicabilityVerdict {
+    readonly applicable: boolean;
+    readonly reason: string;
+}
+export interface AdoptionSignal {
+    readonly signalClass: "adoption";
+    readonly event: string;
+    readonly capabilityId: CapabilityId;
+    readonly message: string;
+    readonly evidence: Readonly<Record<string, unknown>>;
+}
+/** Conservative thresholds — adoption nudges fire only above these bars (#1709). */
+export declare const ADOPTION_THRESHOLDS: {
+    readonly smallWorkMaxFiles: 2;
+    readonly planningMinFiles: 4;
+    readonly costMinFiles: 3;
+    readonly largeMultiFileMinFiles: 5;
+    readonly largeMultiFileMinModules: 2;
+    readonly swarmMinFiles: 8;
+    readonly swarmMinModules: 3;
+    readonly glossaryMinFiles: 6;
+    readonly lessonsMinFiles: 5;
+};
+export declare const ADOPTION_SIGNAL_CLASS: "adoption";
+/** Event name for the attribution ledger (`adoption:<capability>`). */
+export declare function formatAdoptionEventName(id: CapabilityId): string;
+/** True when work is too small for any adoption nudge (#1709-adoption-registry-a3). */
+export declare function isWorkTooSmallForAdoptionNudges(ctx: WorkContext): boolean;
+/** Evaluate whether a capability's conservative heuristic applies to the work snapshot. */
+export declare function evaluateApplicability(id: CapabilityId, ctx: WorkContext): ApplicabilityVerdict;
+/**
+ * Detect applicable-but-unused capabilities (#1709-adoption-registry-a2).
+ * Does not consult the value-feedback policy — use `detectApplicableButUnusedGated`.
+ */
+export declare function detectApplicableButUnused(ctx: WorkContext): AdoptionSignal[];
+/**
+ * Policy-gated adoption detection — returns signals only when value feedback
+ * is enabled and the emitEvents path is allowed (#1709 opt-in gate).
+ */
+export declare function detectApplicableButUnusedGated(ctx: WorkContext, policy: ValueFeedbackResolved): AdoptionSignal[];
+//# sourceMappingURL=adoption-registry.d.ts.map

package/dist/value/adoption-registry.js

@@ -0,0 +1,214 @@
+import { isValueFeedbackPathAllowed, } from "../policy/value-feedback.js";
+/** Conservative thresholds — adoption nudges fire only above these bars (#1709). */
+export const ADOPTION_THRESHOLDS = {
+    smallWorkMaxFiles: 2,
+    planningMinFiles: 4,
+    costMinFiles: 3,
+    largeMultiFileMinFiles: 5,
+    largeMultiFileMinModules: 2,
+    swarmMinFiles: 8,
+    swarmMinModules: 3,
+    glossaryMinFiles: 6,
+    lessonsMinFiles: 5,
+};
+export const ADOPTION_SIGNAL_CLASS = "adoption";
+const CAPABILITY_CATALOG = [
+    {
+        id: "planning",
+        label: "Planning",
+        description: "Structured spec interview or speckit planning before implementation.",
+        usageSignals: ["command:/deft:directive:run:interview", "command:/deft:directive:run:speckit"],
+        nudgeHint: "Consider `/deft:directive:run:interview` or `/deft:directive:run:speckit` before a multi-file build.",
+    },
+    {
+        id: "cost",
+        label: "Cost awareness",
+        description: "Capacity/cost phase before committing to a build.",
+        usageSignals: ["command:task capacity:show"],
+        nudgeHint: "Run `task capacity:show` before a build to surface allocation targets.",
+    },
+    {
+        id: "decompose",
+        label: "Decompose",
+        description: "Split large multi-file work into reviewable PRs.",
+        usageSignals: ["command:split-to-prs"],
+        nudgeHint: "Large multi-file work may benefit from split-to-prs decomposition.",
+    },
+    {
+        id: "swarm",
+        label: "Swarm",
+        description: "Parallel agent dispatch for disjoint multi-story cohorts.",
+        usageSignals: ["command:task swarm:launch"],
+        nudgeHint: "Disjoint multi-story work may benefit from `task swarm:launch`.",
+    },
+    {
+        id: "pre-pr",
+        label: "Pre-PR loop",
+        description: "Iterative pre-PR quality loop before opening a pull request.",
+        usageSignals: ["skill:deft-directive-pre-pr"],
+        nudgeHint: "Run the deft-directive-pre-pr skill before opening a PR.",
+    },
+    {
+        id: "debug",
+        label: "Debug mode",
+        description: "Systematic debug workflow for failures and regressions.",
+        usageSignals: ["skill:debug-mode"],
+        nudgeHint: "Switch to debug mode when chasing a failure systematically.",
+    },
+    {
+        id: "glossary",
+        label: "Glossary",
+        description: "Project glossary for unfamiliar domain terms.",
+        usageSignals: ["command:/deft:glossary"],
+        nudgeHint: "Consult `/deft:glossary` when domain terms are ambiguous.",
+    },
+    {
+        id: "lessons",
+        label: "Lessons packs",
+        description: "Prior-art slices from directive content packs.",
+        usageSignals: ["command:deft packs:slice"],
+        nudgeHint: "Load a lessons pack slice before improvising on a novel problem.",
+    },
+];
+function usedSet(ctx) {
+    return new Set(ctx.usedCapabilities);
+}
+function verdict(applicable, reason) {
+    return { applicable, reason };
+}
+const APPLICABILITY_RULES = {
+    planning(ctx) {
+        if (ctx.isPrOpening) {
+            return verdict(false, "at PR-open boundary — planning phase is past");
+        }
+        if (ctx.filesTouched < ADOPTION_THRESHOLDS.planningMinFiles) {
+            return verdict(false, "scope below planning threshold");
+        }
+        return verdict(true, "multi-file scope without a planning pass");
+    },
+    cost(ctx) {
+        if (!ctx.isBuildIntent) {
+            return verdict(false, "not a build-intent session");
+        }
+        if (ctx.filesTouched < ADOPTION_THRESHOLDS.costMinFiles) {
+            return verdict(false, "build scope below cost threshold");
+        }
+        return verdict(true, "build intent without a cost phase");
+    },
+    decompose(ctx) {
+        if (ctx.filesTouched < ADOPTION_THRESHOLDS.largeMultiFileMinFiles) {
+            return verdict(false, "file count below large multi-file threshold");
+        }
+        if (ctx.distinctModuleGlobs < ADOPTION_THRESHOLDS.largeMultiFileMinModules) {
+            return verdict(false, "work is not parallelizable across modules");
+        }
+        return verdict(true, "large multi-file parallelizable work");
+    },
+    swarm(ctx) {
+        if (ctx.filesTouched < ADOPTION_THRESHOLDS.swarmMinFiles) {
+            return verdict(false, "file count below swarm threshold");
+        }
+        if (ctx.distinctModuleGlobs < ADOPTION_THRESHOLDS.swarmMinModules) {
+            return verdict(false, "insufficient module breadth for swarm cohort");
+        }
+        return verdict(true, "broad parallelizable cohort scope");
+    },
+    "pre-pr"(ctx) {
+        if (!ctx.isPrOpening) {
+            return verdict(false, "not at PR-open boundary");
+        }
+        return verdict(true, "PR opening without pre-PR loop");
+    },
+    debug(_ctx) {
+        return verdict(false, "debug nudges require an explicit failure signal");
+    },
+    glossary(ctx) {
+        if (ctx.filesTouched < ADOPTION_THRESHOLDS.glossaryMinFiles) {
+            return verdict(false, "scope below glossary threshold");
+        }
+        return verdict(true, "broad unfamiliar scope");
+    },
+    lessons(ctx) {
+        if (ctx.filesTouched < ADOPTION_THRESHOLDS.lessonsMinFiles) {
+            return verdict(false, "scope below lessons threshold");
+        }
+        return verdict(true, "novel multi-file scope");
+    },
+};
+/** Return the full capability catalog (#1709-adoption-registry-a1). */
+function listCapabilities() {
+    return CAPABILITY_CATALOG;
+}
+/** Lookup a single catalog entry by id. */
+function getCapability(id) {
+    return CAPABILITY_CATALOG.find((entry) => entry.id === id);
+}
+/** Event name for the attribution ledger (`adoption:<capability>`). */
+export function formatAdoptionEventName(id) {
+    return `${ADOPTION_SIGNAL_CLASS}:${id}`;
+}
+/** True when work is too small for any adoption nudge (#1709-adoption-registry-a3). */
+export function isWorkTooSmallForAdoptionNudges(ctx) {
+    return ctx.filesTouched <= ADOPTION_THRESHOLDS.smallWorkMaxFiles;
+}
+/** Evaluate whether a capability's conservative heuristic applies to the work snapshot. */
+export function evaluateApplicability(id, ctx) {
+    if (isWorkTooSmallForAdoptionNudges(ctx)) {
+        return verdict(false, "small work — adoption nudges suppressed");
+    }
+    return APPLICABILITY_RULES[id](ctx);
+}
+function buildAdoptionSignal(id, ctx, applicability) {
+    const record = getCapability(id);
+    if (record === undefined) {
+        return null;
+    }
+    return {
+        signalClass: ADOPTION_SIGNAL_CLASS,
+        event: formatAdoptionEventName(record.id),
+        capabilityId: record.id,
+        message: record.nudgeHint,
+        evidence: {
+            filesTouched: ctx.filesTouched,
+            distinctModuleGlobs: ctx.distinctModuleGlobs,
+            usageSignals: record.usageSignals,
+            applicabilityReason: applicability.reason,
+        },
+    };
+}
+/**
+ * Detect applicable-but-unused capabilities (#1709-adoption-registry-a2).
+ * Does not consult the value-feedback policy — use `detectApplicableButUnusedGated`.
+ */
+export function detectApplicableButUnused(ctx) {
+    if (isWorkTooSmallForAdoptionNudges(ctx)) {
+        return [];
+    }
+    const used = usedSet(ctx);
+    const signals = [];
+    for (const record of listCapabilities()) {
+        if (used.has(record.id)) {
+            continue;
+        }
+        const applicability = evaluateApplicability(record.id, ctx);
+        if (!applicability.applicable) {
+            continue;
+        }
+        const signal = buildAdoptionSignal(record.id, ctx, applicability);
+        if (signal !== null) {
+            signals.push(signal);
+        }
+    }
+    return signals;
+}
+/**
+ * Policy-gated adoption detection — returns signals only when value feedback
+ * is enabled and the emitEvents path is allowed (#1709 opt-in gate).
+ */
+export function detectApplicableButUnusedGated(ctx, policy) {
+    if (!isValueFeedbackPathAllowed("emitEvents", policy)) {
+        return [];
+    }
+    return detectApplicableButUnused(ctx);
+}
+//# sourceMappingURL=adoption-registry.js.map

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

@@ -0,0 +1,67 @@
+import { type GhRestSeams } from "../scm/gh-rest.js";
+export declare const DEFAULT_UPSTREAM_REPO = "deftai/directive";
+export declare const FRAMEWORK_GAP_TITLE_PREFIX = "[framework-gap]";
+export type FeedbackFileOutcome = "draft" | "filed" | "skipped-maintainer" | "blocked-policy" | "blocked-duplicate" | "blocked-no-confirm" | "error-bad-args" | "error-config" | "error-network";
+export interface FeedbackGapInput {
+    readonly summary: string;
+    readonly context?: string;
+    readonly expected?: string;
+    readonly actual?: string;
+    readonly sessionNotes?: string;
+}
+export interface FeedbackFileOptions extends FeedbackGapInput {
+    readonly projectRoot?: string | null;
+    readonly repo?: string;
+    readonly confirm?: boolean;
+    readonly dryRun?: boolean;
+    readonly json?: boolean;
+    readonly seams?: GhRestSeams;
+}
+export interface FeedbackFileResult {
+    readonly outcome: FeedbackFileOutcome;
+    readonly exitCode: 0 | 1 | 2;
+    readonly title: string;
+    readonly body: string;
+    readonly repo: string;
+    readonly issueUrl?: string | null;
+    readonly duplicateUrl?: string | null;
+    readonly message: string;
+}
+/** True when the resolved project root is the directive maintainer source checkout. */
+export declare function isMaintainerFrameworkRepo(projectRoot: string): boolean;
+/** Normalize a title for duplicate comparison (#1709). */
+export declare function normalizeForDedup(title: string): string;
+/** Build the upstream issue title for a framework-gap report. */
+export declare function buildFrameworkGapTitle(summary: string): string;
+/** Build the structured framework-gap issue body. */
+export declare function buildFrameworkGapBody(input: FeedbackGapInput): string;
+export interface DuplicateMatch {
+    readonly url: string;
+    readonly title: string;
+}
+/** Search open upstream issues for a normalized title match. */
+export declare function findDuplicateIssue(repo: string, title: string, seams?: GhRestSeams): DuplicateMatch | null;
+/** Core feedback:file workflow (#1709 gap escalation). */
+export declare function runFeedbackFile(options: FeedbackFileOptions): FeedbackFileResult;
+export interface FeedbackFileCliArgs {
+    summary?: string;
+    context?: string;
+    expected?: string;
+    actual?: string;
+    sessionNotes?: string;
+    confirm?: boolean;
+    dryRun?: boolean;
+    json?: boolean;
+    repo?: string;
+    projectRoot?: string;
+    error?: string;
+}
+/** Parse argv for feedback:file. */
+export declare function parseFeedbackFileArgs(argv: readonly string[]): FeedbackFileCliArgs;
+/** CLI entry for feedback:file. */
+export declare function feedbackFileMain(argv: readonly string[]): number;
+/** CLI module entrypoint for dispatch (#1709). */
+export declare function mainEntry(argv?: string[]): number;
+/** Convenience probe used in tests for project-root sentinel presence. */
+export declare function projectRootLooksLikeConsumer(projectRoot: string): boolean;
+//# sourceMappingURL=feedback-file.d.ts.map