@deftai/directive-core 0.80.0 → 0.82.0

package/dist/product-signal/github-private-sink-adapter.js

@@ -0,0 +1,274 @@
+import { GhRestError, restCreateIssue, restIssueListPaginated, restPostComment, restUpdateIssue, } from "../scm/gh-rest.js";
+import { normalizeActorKey } from "./actor-name.js";
+import { classifySinkError } from "./gates.js";
+export const PRODUCT_SIGNAL_MARKER_PREFIX = "<!-- deft:product-signal v1";
+export const SURFACE_LABELS = {
+    pulse: "surface:pulse",
+    portrait: "surface:portrait",
+};
+/** Build HTML comment marker for standing-thread lookup (#2693 D8). */
+export function buildThreadMarker(installId, actorName, surface) {
+    return (`${PRODUCT_SIGNAL_MARKER_PREFIX} ` +
+        `installId=${installId} actorKey=${normalizeActorKey(actorName)} surface=${surface} -->`);
+}
+function npsLabels(nps) {
+    if (nps === null) {
+        return ["nps:none"];
+    }
+    if (nps >= 9) {
+        return ["nps:promoter"];
+    }
+    if (nps >= 7) {
+        return ["nps:passive"];
+    }
+    return ["nps:detractor"];
+}
+function directiveVersionLabel(version) {
+    const match = version.match(/^(\d+\.\d+)/);
+    const minor = match?.[1] ?? "0.0";
+    return `directive:${minor}`;
+}
+function labelNamesFromIssue(issue) {
+    const labels = issue.labels;
+    if (!Array.isArray(labels)) {
+        return [];
+    }
+    const names = [];
+    for (const label of labels) {
+        if (typeof label === "string" && label.trim().length > 0) {
+            names.push(label.trim());
+            continue;
+        }
+        if (label !== null && typeof label === "object" && !Array.isArray(label)) {
+            const name = label.name;
+            if (typeof name === "string" && name.trim().length > 0) {
+                names.push(name.trim());
+            }
+        }
+    }
+    return names;
+}
+/** Merge labels for PATCH updates (GitHub replaces the full label set). */
+export function mergeIssueLabels(existing, next) {
+    const merged = new Set(labelNamesFromIssue(existing));
+    for (const label of next) {
+        if (label.trim().length > 0) {
+            merged.add(label.trim());
+        }
+    }
+    return [...merged];
+}
+function formatPayloadBody(payload) {
+    const marker = buildThreadMarker(payload.installId, payload.actorName, payload.surface);
+    const humanLines = [];
+    if (payload.human.nps !== null) {
+        humanLines.push(`- NPS: ${payload.human.nps}`);
+    }
+    for (const answer of payload.human.answers) {
+        humanLines.push(`- **${answer.q}**: ${answer.a}`);
+    }
+    if (payload.human.freeText !== null && payload.human.freeText.trim().length > 0) {
+        humanLines.push(`- Free text: ${payload.human.freeText.trim()}`);
+    }
+    const summaryJson = payload.localSignalSummary !== null
+        ? `\n<details><summary>localSignalSummary</summary>\n\n\`\`\`json\n${JSON.stringify(payload.localSignalSummary, null, 2)}\n\`\`\`\n</details>\n`
+        : "";
+    const skillsJson = payload.skillsSummary !== null
+        ? `\n<details><summary>skillsSummary</summary>\n\n\`\`\`json\n${JSON.stringify(payload.skillsSummary, null, 2)}\n\`\`\`\n</details>\n`
+        : "";
+    return [
+        marker,
+        "",
+        `## ${payload.surface === "portrait" ? "Portrait" : "Pulse"} — ${payload.actorName}`,
+        "",
+        `- installId: \`${payload.installId}\``,
+        `- actorNameSource: ${payload.actorNameSource}`,
+        `- directive: ${payload.directiveVersion}`,
+        `- harness: ${payload.harness}${payload.harnessVersion ? ` (${payload.harnessVersion})` : ""}`,
+        `- os: ${payload.os} / shell: ${payload.shell}`,
+        `- collectedAt: ${payload.collectedAt}`,
+        "",
+        "### Human",
+        "",
+        humanLines.length > 0 ? humanLines.join("\n") : "_(no human answers)_",
+        payload.agentNotes ? `\n### Agent notes\n\n${payload.agentNotes}` : "",
+        summaryJson,
+        skillsJson,
+        "",
+        "_Submitted via product-signal (Refs #2693)._",
+        "",
+    ].join("\n");
+}
+function formatPulseComment(payload) {
+    const date = payload.collectedAt.slice(0, 10);
+    const humanLines = [];
+    if (payload.human.nps !== null) {
+        humanLines.push(`NPS ${payload.human.nps}`);
+    }
+    for (const answer of payload.human.answers) {
+        humanLines.push(`${answer.q}: ${answer.a}`);
+    }
+    if (payload.human.freeText) {
+        humanLines.push(payload.human.freeText);
+    }
+    return [`**Pulse ${date}**`, "", ...humanLines, ""].join("\n");
+}
+function findStandingIssue(repo, installId, actorName, surface, seams) {
+    const needleKey = normalizeActorKey(actorName);
+    const markerNeedle = `installId=${installId} actorKey=${needleKey} surface=${surface}`;
+    const issues = restIssueListPaginated(repo, { state: "open", labels: [SURFACE_LABELS[surface]], limit: 200 }, seams);
+    for (const issue of issues) {
+        const body = typeof issue.body === "string" ? issue.body : "";
+        if (body.includes(markerNeedle)) {
+            return issue;
+        }
+    }
+    return null;
+}
+function issueUrlFromRecord(issue) {
+    const url = issue.html_url;
+    return typeof url === "string" ? url : null;
+}
+function issueNumberFromRecord(issue) {
+    const num = issue.number;
+    return typeof num === "number" ? num : null;
+}
+/** Phase-1 GitHub private sink adapter (#2693 D5/D8). */
+export class GitHubPrivateSinkAdapter {
+    id = "github-private-sink";
+    repo;
+    seams;
+    constructor(options) {
+        this.repo = options.sinkRepo;
+        this.seams = options.seams ?? {};
+    }
+    async submit(payload, extras) {
+        try {
+            const labels = [
+                SURFACE_LABELS[payload.surface],
+                ...npsLabels(payload.human.nps),
+                directiveVersionLabel(payload.directiveVersion),
+            ];
+            let result;
+            if (payload.surface === "portrait") {
+                result = this.submitPortrait(payload, labels);
+            }
+            else {
+                result = this.submitPulse(payload, labels);
+            }
+            if (result.outcome === "submitted" &&
+                extras?.gapText !== undefined &&
+                extras.gapText !== null &&
+                extras.gapText.trim().length > 0) {
+                this.appendGapCommentOnPulse(payload, extras.gapText.trim());
+            }
+            return result;
+        }
+        catch (err) {
+            if (err instanceof GhRestError) {
+                const outcome = classifySinkError(err.stderr, err.exitCode);
+                return {
+                    outcome,
+                    message: `product-signal soft-skip (${outcome}): ${err.stderr || err.message}`,
+                };
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                outcome: "sink-unreachable",
+                message: `product-signal soft-skip (sink-unreachable): ${message}`,
+            };
+        }
+    }
+    submitPortrait(payload, labels) {
+        const body = formatPayloadBody(payload);
+        const title = `[portrait] ${payload.actorName} @ ${payload.installId.slice(0, 8)}`;
+        const existing = findStandingIssue(this.repo, payload.installId, payload.actorName, "portrait", this.seams);
+        if (existing !== null) {
+            const num = issueNumberFromRecord(existing);
+            if (num === null) {
+                return { outcome: "sink-unreachable", message: "standing portrait issue missing number" };
+            }
+            const updated = restUpdateIssue(this.repo, num, { body, labels: [...labels] }, this.seams);
+            return {
+                outcome: "submitted",
+                issueUrl: issueUrlFromRecord(updated),
+                issueNumber: issueNumberFromRecord(updated),
+                message: `portrait upserted on #${num}`,
+            };
+        }
+        const created = restCreateIssue(this.repo, title, body, labels, this.seams);
+        return {
+            outcome: "submitted",
+            issueUrl: issueUrlFromRecord(created),
+            issueNumber: issueNumberFromRecord(created),
+            message: "portrait standing issue created",
+        };
+    }
+    submitPulse(payload, labels) {
+        const existing = findStandingIssue(this.repo, payload.installId, payload.actorName, "pulse", this.seams);
+        let issueNumber;
+        let issueUrl;
+        if (existing === null) {
+            const title = `[pulse] ${payload.actorName} @ ${payload.installId.slice(0, 8)}`;
+            const body = formatPayloadBody(payload);
+            const created = restCreateIssue(this.repo, title, body, labels, this.seams);
+            issueNumber = issueNumberFromRecord(created);
+            issueUrl = issueUrlFromRecord(created);
+        }
+        else {
+            issueNumber = issueNumberFromRecord(existing);
+            issueUrl = issueUrlFromRecord(existing);
+            if (issueNumber !== null) {
+                restUpdateIssue(this.repo, issueNumber, { labels: mergeIssueLabels(existing, labels) }, this.seams);
+            }
+        }
+        if (issueNumber === null) {
+            return { outcome: "sink-unreachable", message: "pulse standing issue missing number" };
+        }
+        restPostComment(this.repo, issueNumber, formatPulseComment(payload), this.seams);
+        return {
+            outcome: "submitted",
+            issueUrl,
+            issueNumber,
+            message: `pulse comment appended on #${issueNumber}`,
+        };
+    }
+    /** Append a Gap: comment on the standing pulse thread (#2693 D19). */
+    appendGapCommentOnPulse(payload, gapText) {
+        try {
+            const existing = findStandingIssue(this.repo, payload.installId, payload.actorName, "pulse", this.seams);
+            if (existing === null) {
+                return {
+                    outcome: "sink-unreachable",
+                    message: "no standing pulse issue for gap comment",
+                };
+            }
+            const num = issueNumberFromRecord(existing);
+            if (num === null) {
+                return { outcome: "sink-unreachable", message: "pulse issue missing number" };
+            }
+            const date = payload.collectedAt.slice(0, 10);
+            const body = `**Gap ${date}**\n\nGap: ${gapText}\n`;
+            restPostComment(this.repo, num, body, this.seams);
+            restUpdateIssue(this.repo, num, { labels: mergeIssueLabels(existing, [SURFACE_LABELS.pulse, "signal:gap"]) }, this.seams);
+            return {
+                outcome: "submitted",
+                issueUrl: issueUrlFromRecord(existing),
+                issueNumber: num,
+                message: `gap comment appended on pulse #${num}`,
+            };
+        }
+        catch (err) {
+            if (err instanceof GhRestError) {
+                const outcome = classifySinkError(err.stderr, err.exitCode);
+                return {
+                    outcome,
+                    message: `gap comment soft-skip (${outcome}): ${err.stderr || err.message}`,
+                };
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            return { outcome: "sink-unreachable", message };
+        }
+    }
+}
+//# sourceMappingURL=github-private-sink-adapter.js.map

package/dist/product-signal/headless.d.ts

@@ -0,0 +1,8 @@
+/** Headless / non-interactive detection (#2693 D16). */
+export interface HeadlessDetectionOptions {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly stdinIsTTY?: boolean;
+}
+/** True when the session should fail-open without interactive prompts (#2693 D16). */
+export declare function isHeadlessSession(options?: HeadlessDetectionOptions): boolean;
+//# sourceMappingURL=headless.d.ts.map

package/dist/product-signal/headless.js

@@ -0,0 +1,32 @@
+/** Headless / non-interactive detection (#2693 D16). */
+const CI_MARKERS = [
+    "CI",
+    "CONTINUOUS_INTEGRATION",
+    "GITHUB_ACTIONS",
+    "GITLAB_CI",
+    "BUILDKITE",
+    "CIRCLECI",
+    "JENKINS_URL",
+    "TF_BUILD",
+    "CURSOR_CLOUD_AGENT",
+    "DEFT_CLOUD_AGENT",
+];
+/** True when the session should fail-open without interactive prompts (#2693 D16). */
+export function isHeadlessSession(options = {}) {
+    const env = options.env ?? process.env;
+    if (env.DEFT_HEADLESS === "1" || env.DEFT_HEADLESS === "true") {
+        return true;
+    }
+    for (const key of CI_MARKERS) {
+        const val = env[key];
+        if (val !== undefined && val !== "" && val !== "0" && val !== "false") {
+            return true;
+        }
+    }
+    const stdinIsTTY = options.stdinIsTTY ?? process.stdin.isTTY;
+    if (stdinIsTTY === false) {
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=headless.js.map

package/dist/product-signal/install-context.d.ts

@@ -0,0 +1,13 @@
+export type ProductSignalHarness = "cursor" | "cli" | "codex" | "opencode" | "other";
+export interface InstallContext {
+    readonly installId: string;
+    readonly directiveVersion: string;
+    readonly os: string;
+    readonly osVersion: string;
+    readonly shell: string;
+    readonly harness: ProductSignalHarness;
+    readonly harnessVersion: string | null;
+}
+/** Collect shared install context for product-signal payloads (#2693 D7). */
+export declare function collectInstallContext(projectRoot: string): InstallContext;
+//# sourceMappingURL=install-context.d.ts.map

package/dist/product-signal/install-context.js

@@ -0,0 +1,41 @@
+import { release } from "node:os";
+import { readCorePackageVersion } from "../engine-version.js";
+import { resolveInstallId } from "../events/attribution-enrichment.js";
+import { detectEnvironmentContext } from "../platform/shell-context.js";
+function detectHarness(env = process.env) {
+    const explicit = env.DEFT_HARNESS?.trim().toLowerCase();
+    if (explicit === "cursor" ||
+        explicit === "cli" ||
+        explicit === "codex" ||
+        explicit === "opencode" ||
+        explicit === "other") {
+        return explicit;
+    }
+    if (env.CURSOR_SESSION_ID || env.CURSOR_TRACE_ID) {
+        return "cursor";
+    }
+    if (env.CODEX_HOME || env.CODEX_SESSION) {
+        return "codex";
+    }
+    if (env.OPENCODE) {
+        return "opencode";
+    }
+    return "cli";
+}
+/** Collect shared install context for product-signal payloads (#2693 D7). */
+export function collectInstallContext(projectRoot) {
+    const envCtx = detectEnvironmentContext();
+    const installId = resolveInstallId(projectRoot) ?? "unknown";
+    const harness = detectHarness();
+    const harnessVersion = process.env.DEFT_HARNESS_VERSION?.trim() || process.env.CURSOR_VERSION?.trim() || null;
+    return {
+        installId,
+        directiveVersion: readCorePackageVersion(),
+        os: envCtx.hostPlatform,
+        osVersion: release(),
+        shell: envCtx.shell.name,
+        harness,
+        harnessVersion,
+    };
+}
+//# sourceMappingURL=install-context.js.map

package/dist/product-signal/local-signal-summary.d.ts

@@ -0,0 +1,7 @@
+import { type LocalSignalSummary } from "./payload.js";
+export declare const DEFAULT_LOCAL_SIGNAL_WINDOW = "30d";
+/** Assemble minimized local ledger summaries (#2693 D15). */
+export declare function assembleLocalSignalSummary(projectRoot: string, options?: {
+    window?: string;
+}): LocalSignalSummary;
+//# sourceMappingURL=local-signal-summary.d.ts.map

package/dist/product-signal/local-signal-summary.js

@@ -0,0 +1,173 @@
+import { existsSync, readFileSync } from "node:fs";
+import { evaluateHealth } from "../eval/health.js";
+import { healthMetricsHistoryPath, helpedMetricsHistoryPath, } from "../metrics/resolve-metrics-home.js";
+import { resolveValueFeedback } from "../policy/value-feedback.js";
+import { computeValueShowTrend } from "../value/readback.js";
+import { LOCAL_SIGNAL_SUMMARY_SCHEMA_VERSION, } from "./payload.js";
+export const DEFAULT_LOCAL_SIGNAL_WINDOW = "30d";
+function parseWindowMs(window) {
+    const match = window.trim().match(/^(\d+)\s*(d|h|m)$/i);
+    if (match === null) {
+        return 30 * 86_400_000;
+    }
+    const amount = Number(match[1]);
+    const unit = match[2]?.toLowerCase();
+    if (unit === "d") {
+        return amount * 86_400_000;
+    }
+    if (unit === "h") {
+        return amount * 3_600_000;
+    }
+    return amount * 60_000;
+}
+function readLastJsonlRecord(path) {
+    if (!existsSync(path)) {
+        return null;
+    }
+    try {
+        const lines = readFileSync(path, "utf8")
+            .split("\n")
+            .filter((line) => line.trim().length > 0);
+        const last = lines[lines.length - 1];
+        if (last === undefined) {
+            return null;
+        }
+        const parsed = JSON.parse(last);
+        if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // ignore
+    }
+    return null;
+}
+function buildValueFeedbackSummary(projectRoot, windowMs) {
+    const policy = resolveValueFeedback(projectRoot);
+    if (!policy.enabled) {
+        return {
+            enabled: false,
+            total: 0,
+            byClass: { value: 0, bypass: 0, adoption: 0, friction: 0 },
+            topEvents: [],
+        };
+    }
+    const trend = computeValueShowTrend(projectRoot, { windowMs });
+    const topEvents = Object.entries(trend.byEvent)
+        .sort(([, a], [, b]) => b - a)
+        .slice(0, 5)
+        .map(([name, count]) => ({ name, count }));
+    const byClass = {};
+    for (const key of ["value", "bypass", "adoption", "friction"]) {
+        byClass[key] = trend.byClass[key];
+    }
+    return {
+        enabled: true,
+        total: trend.total,
+        byClass,
+        topEvents,
+    };
+}
+function buildEvalHealthSummary(projectRoot) {
+    const ledgerPath = healthMetricsHistoryPath(projectRoot);
+    if (ledgerPath !== null) {
+        const last = readLastJsonlRecord(ledgerPath);
+        if (last !== null && typeof last.score === "number") {
+            const contradictions = last.contradictions;
+            return {
+                score: last.score,
+                contradictionCount: Array.isArray(contradictions) ? contradictions.length : 0,
+                collectedAt: typeof last.recordedAt === "string" ? last.recordedAt : null,
+            };
+        }
+    }
+    const result = evaluateHealth({ projectRoot, persist: false });
+    if (result.report === null) {
+        return null;
+    }
+    return {
+        score: result.report.score,
+        contradictionCount: result.report.contradictions.length,
+        collectedAt: result.report.recordedAt,
+    };
+}
+function buildHelpedHealthSummary(projectRoot, window) {
+    const windowMs = parseWindowMs(window);
+    const since = Date.now() - windowMs;
+    const helpedPath = helpedMetricsHistoryPath(projectRoot);
+    let helpedCount = 0;
+    if (helpedPath !== null && existsSync(helpedPath)) {
+        try {
+            const lines = readFileSync(helpedPath, "utf8")
+                .split("\n")
+                .filter((l) => l.trim());
+            for (const line of lines) {
+                try {
+                    const rec = JSON.parse(line);
+                    if (rec !== null && typeof rec === "object" && !Array.isArray(rec)) {
+                        const at = rec.recordedAt;
+                        if (typeof at === "string") {
+                            const ts = Date.parse(at);
+                            if (!Number.isNaN(ts) && ts >= since) {
+                                helpedCount += 1;
+                            }
+                        }
+                    }
+                }
+                catch {
+                    // skip bad line
+                }
+            }
+        }
+        catch {
+            helpedCount = 0;
+        }
+    }
+    const healthPath = healthMetricsHistoryPath(projectRoot);
+    let healthEntryCount = 0;
+    if (healthPath !== null && existsSync(healthPath)) {
+        try {
+            const lines = readFileSync(healthPath, "utf8")
+                .split("\n")
+                .filter((l) => l.trim());
+            for (const line of lines) {
+                try {
+                    const rec = JSON.parse(line);
+                    if (rec !== null && typeof rec === "object" && !Array.isArray(rec)) {
+                        const at = rec.recordedAt;
+                        if (typeof at === "string") {
+                            const ts = Date.parse(at);
+                            if (!Number.isNaN(ts) && ts >= since) {
+                                healthEntryCount += 1;
+                            }
+                        }
+                    }
+                }
+                catch {
+                    // skip
+                }
+            }
+        }
+        catch {
+            healthEntryCount = 0;
+        }
+    }
+    return {
+        helpedCount: helpedPath === null ? null : helpedCount,
+        healthEntryCount: healthPath === null ? null : healthEntryCount,
+        window,
+    };
+}
+/** Assemble minimized local ledger summaries (#2693 D15). */
+export function assembleLocalSignalSummary(projectRoot, options = {}) {
+    const window = options.window ?? DEFAULT_LOCAL_SIGNAL_WINDOW;
+    const windowMs = parseWindowMs(window);
+    return {
+        schemaVersion: LOCAL_SIGNAL_SUMMARY_SCHEMA_VERSION,
+        window,
+        valueFeedback: buildValueFeedbackSummary(projectRoot, windowMs),
+        evalHealth: buildEvalHealthSummary(projectRoot),
+        helpedHealth: buildHelpedHealthSummary(projectRoot, window),
+    };
+}
+//# sourceMappingURL=local-signal-summary.js.map

package/dist/product-signal/payload.d.ts

@@ -0,0 +1,90 @@
+import type { ActorNameSource } from "./actor-name.js";
+import type { ProductSignalHarness } from "./install-context.js";
+export declare const PRODUCT_SIGNAL_PAYLOAD_SCHEMA_VERSION: 1;
+export declare const LOCAL_SIGNAL_SUMMARY_SCHEMA_VERSION: 1;
+export declare const SKILLS_SUMMARY_SCHEMA_VERSION: 1;
+export declare const MAX_PAYLOAD_JSON_BYTES = 64000;
+export declare const MAX_HUMAN_ANSWERS = 3;
+export declare const MAX_ANSWER_LENGTH = 2000;
+export declare const MAX_FREE_TEXT_LENGTH = 4000;
+export declare const MAX_AGENT_NOTES_LENGTH = 2000;
+export type ProductSignalSurface = "pulse" | "portrait";
+export interface HumanAnswer {
+    readonly q: string;
+    readonly a: string;
+}
+export interface ProductSignalHuman {
+    readonly nps: number | null;
+    readonly answers: readonly HumanAnswer[];
+    readonly freeText: string | null;
+}
+export interface ValueFeedbackSummary {
+    readonly enabled: boolean;
+    readonly total: number;
+    readonly byClass: {
+        readonly value: number;
+        readonly bypass: number;
+        readonly adoption: number;
+        readonly friction: number;
+    };
+    readonly topEvents: readonly {
+        readonly name: string;
+        readonly count: number;
+    }[];
+}
+export interface EvalHealthSummary {
+    readonly score: number | null;
+    readonly contradictionCount: number | null;
+    readonly collectedAt: string | null;
+}
+export interface HelpedHealthSummary {
+    readonly helpedCount: number | null;
+    readonly healthEntryCount: number | null;
+    readonly window: string;
+}
+export interface LocalSignalSummary {
+    readonly schemaVersion: typeof LOCAL_SIGNAL_SUMMARY_SCHEMA_VERSION;
+    readonly window: string;
+    readonly valueFeedback: ValueFeedbackSummary | null;
+    readonly evalHealth: EvalHealthSummary | null;
+    readonly helpedHealth: HelpedHealthSummary | null;
+}
+export interface SkillsSummaryEntry {
+    readonly skill: string;
+    readonly useCount: number;
+    readonly viewCount: number;
+    readonly lastUsed: string | null;
+}
+export interface SkillsSummary {
+    readonly schemaVersion: typeof SKILLS_SUMMARY_SCHEMA_VERSION;
+    readonly top: readonly SkillsSummaryEntry[];
+    readonly skillCount: number;
+}
+export interface ProductSignalPayload {
+    readonly schemaVersion: typeof PRODUCT_SIGNAL_PAYLOAD_SCHEMA_VERSION;
+    readonly surface: ProductSignalSurface;
+    readonly installId: string;
+    readonly actorName: string;
+    readonly actorNameSource: ActorNameSource;
+    readonly directiveVersion: string;
+    readonly os: string;
+    readonly osVersion: string;
+    readonly shell: string;
+    readonly harness: ProductSignalHarness;
+    readonly harnessVersion: string | null;
+    readonly consentTier: string;
+    readonly consentSource: "user" | "org-policy" | "typed-override";
+    readonly consentVersion: string;
+    readonly human: ProductSignalHuman;
+    readonly agentNotes: string | null;
+    readonly localSignalSummary: LocalSignalSummary | null;
+    readonly skillsSummary: SkillsSummary | null;
+    readonly collectedAt: string;
+}
+/** Client-side payload validation before submit (#2693 D7). */
+export declare function validateProductSignalPayload(payload: ProductSignalPayload): string[];
+/** Optional #829 sidecar path (read-only attach; emit not implemented here). */
+export declare const SKILLS_TELEMETRY_SIDECAR_REL: string;
+/** Read minimized skillsSummary when local sidecar exists (#2693 D14). */
+export declare function readSkillsSummarySidecar(projectRoot: string): SkillsSummary | null;
+//# sourceMappingURL=payload.d.ts.map