@productbrain/cli 0.1.0-beta.29 → 0.1.0-beta.2914

package/dist/lib/workspaceNotice.js

@@ -0,0 +1,77 @@
+/**
+ * WP-1 — Loud workspace identity on every Chain write.
+ *
+ * Running `pb` from a directory with no repo pin (e.g. `~/`) silently resolves the
+ * GLOBAL profile and writes to whichever Chain that points at — proven live: captures
+ * meant for one workspace landed on another. This module makes every Chain write NAME
+ * its target workspace on stderr, and qualifies the line LOUDLY when the binding is an
+ * unpinned fallback (`global`/`default` — no repo pin) so a wrong-Chain write is never
+ * silent. An explicit binding (`local`/`env`) gets a plain, non-alarming line.
+ *
+ * Label source — the PROFILE SLUG only, via `resolveEffectiveProfile()`.
+ * Deliberately NOT a workspace-name probe: `resolveEffectiveProfile()` reports the
+ * *configured* pin even when it dangles (TEN-2163), while a probe resolves what
+ * `resolveConfig()` actually binds. On a dangling local pin the two DISAGREE — the
+ * profile says `source='local'` (a plain, reassuring line) while the probe returns the
+ * GLOBAL workspace the write really drifts to. That would print a non-alarming line over
+ * the exact silent-drift this notice exists to expose. One resolution path means the
+ * label and its qualifier can never contradict — and there is no per-write network
+ * round-trip in front of the write.
+ *
+ * Output contract — identical to capture.ts's grounding banner (the JSON-safety pattern):
+ *  - The notice is HUMAN-ONLY: written to STDERR, gated by the combined `json` flag.
+ *  - In `--json` mode it is suppressed entirely, so strict-JSON stdout stays
+ *    byte-for-byte unchanged (machine consumers never see it). The gate is the `json`
+ *    flag alone — not `--quiet`: a quiet human run still names its target Chain.
+ *
+ * SSOT: one pure formatter + one thin emitter, called from all four write commands —
+ * no per-command copy-paste.
+ */
+import { resolveEffectiveProfile } from './config.js';
+/**
+ * Build the one-line target-workspace notice — or null when there is nothing to say.
+ *
+ *  - `none`               → null (not configured: nothing to name, stay silent).
+ *  - `global` / `default` → qualified + hint (no repo pin → an unpinned fallback binding).
+ *  - `local` / `env`      → plain (an explicit, intentional binding).
+ *
+ * Pure: no IO. The display label is the profile slug — a single resolution path, so the
+ * label and the qualifier can never contradict each other.
+ */
+export function formatWriteTargetNotice({ profile, source }) {
+    if (source === 'none')
+        return null;
+    const name = profile?.trim() || 'unknown';
+    if (source === 'global' || source === 'default') {
+        return `→ ${name} (global default — run from your project dir to use its workspace)`;
+    }
+    // 'local' | 'env' — an explicit, intentional binding.
+    return `→ ${name}`;
+}
+/**
+ * Resolve identity and write the target notice to STDERR — gated by the combined `json`
+ * flag. Pass the SAME value the command computed (e.g. `isJsonMode() || options.json ===
+ * true`) so `--json` stdout stays byte-for-byte unchanged.
+ *
+ * Never throws and does no network IO: a wrong/unreadable config degrades to silence, and
+ * the label comes from `resolveEffectiveProfile()` alone — only fast local config reads
+ * (no probe) in front of the write. It is safe to call immediately before any Chain write.
+ */
+export async function emitWriteTargetNotice(json) {
+    if (json)
+        return; // strict-JSON stdout stays byte-for-byte unchanged.
+    let profile = null;
+    let source = 'none';
+    try {
+        ({ profile, source } = resolveEffectiveProfile());
+    }
+    catch {
+        return; // unreadable/racing config — say nothing rather than crash a write.
+    }
+    if (source === 'none')
+        return; // not configured — nothing to name.
+    const notice = formatWriteTargetNotice({ profile, source });
+    if (notice)
+        process.stderr.write(notice + '\n');
+}
+//# sourceMappingURL=workspaceNotice.js.map

package/dist/lib/workspaceNotice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspaceNotice.js","sourceRoot":"","sources":["../../src/lib/workspaceNotice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,uBAAuB,EAA+B,MAAM,aAAa,CAAC;AAUnF;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB,CAAC,EAAE,OAAO,EAAE,MAAM,EAA0B;IACjF,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACnC,MAAM,IAAI,GAAG,OAAO,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;IAC1C,IAAI,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QAChD,OAAO,KAAK,IAAI,oEAAoE,CAAC;IACvF,CAAC;IACD,sDAAsD;IACtD,OAAO,KAAK,IAAI,EAAE,CAAC;AACrB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,IAAa;IACvD,IAAI,IAAI;QAAE,OAAO,CAAC,oDAAoD;IAEtE,IAAI,OAAO,GAAkB,IAAI,CAAC;IAClC,IAAI,MAAM,GAA2B,MAAM,CAAC;IAC5C,IAAI,CAAC;QACH,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,uBAAuB,EAAE,CAAC,CAAC;IACpD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,oEAAoE;IAC9E,CAAC;IACD,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,CAAC,oCAAoC;IAEnE,MAAM,MAAM,GAAG,uBAAuB,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IAC5D,IAAI,MAAM;QAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AAClD,CAAC"}

package/dist/lib/workspaceVocabCache.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 5-minute TTL cache for workspace vocabulary context (WP-436 S2).
+ *
+ * Purpose (R2 mitigation): the CLI resolves vocabulary labels on every invocation.
+ * Without a cache, each `pb orient` / `pb get` / `pb capture` would call
+ * `chain.getVocabulary` — adding a Convex round-trip overhead and risking
+ * handshake-time staleness. A 5-min TTL short-circuits repeat calls within
+ * a typical session while staying fresh enough that label changes land quickly.
+ *
+ * PAT-230: the cache holds WorkspaceVocabCtx (pure data, no Convex imports here).
+ * DEC-1021: only Axis 2 (collectionLabels) lives here; Axis 1 (displayNames) is untouched.
+ *
+ * S4 note: when Cortex UI builds its `vocabularyStore`, it should mirror this
+ * contract — a keyed map by workspaceId with an expiresAt field (Cortex has
+ * direct access to workspaceId; the CLI uses apiKey as a 1:1 surrogate, since
+ * the HTTP gateway server-side injects workspaceId from authResult per
+ * convex/http.ts:675).
+ */
+import type { WorkspaceVocabCtx } from './canonicalRefs.js';
+/**
+ * Get a cached WorkspaceVocabCtx by cacheKey, or null if expired/missing.
+ * Prints a staleness warning when the entry is older than STALE_WARN_MS.
+ */
+export declare function getCachedVocabCtx(cacheKey: string): WorkspaceVocabCtx | null;
+/**
+ * Store a WorkspaceVocabCtx under cacheKey with a 5-min TTL.
+ */
+export declare function setCachedVocabCtx(cacheKey: string, ctx: WorkspaceVocabCtx): void;
+/**
+ * Explicitly invalidate a cached vocab context by cacheKey.
+ * Call this when `updateCollectionLabels` mutation succeeds (e.g. after `pb handshake`).
+ */
+export declare function invalidateVocabCtx(cacheKey: string): void;
+/**
+ * Clear all cached entries (useful for testing or `pb handshake --refresh`).
+ */
+export declare function clearVocabCache(): void;
+/**
+ * Get the cached vocab context, or fetch it via the provided async fetcher on cache miss.
+ *
+ * Usage pattern at CLI command sites:
+ * ```ts
+ * const vocabCtx = await getOrFetchVocabCtx(config.apiKey, async () => {
+ *   type VocabResult = { collectionLabels?: Record<string, unknown> };
+ *   const vocab = await kernelCall<VocabResult>('chain.getVocabulary', {});
+ *   return vocab?.collectionLabels
+ *     ? { collectionLabels: vocab.collectionLabels as WorkspaceVocabCtx['collectionLabels'] }
+ *     : null;
+ * });
+ * ```
+ *
+ * - `cacheKey`: use the API key as a surrogate for cacheKey (1:1 mapping at CLI layer).
+ * - `fetcher`: async function that resolves the vocab ctx; returns null on failure to signal
+ *   "don't cache, fall back to resolver literal". Fetcher errors are swallowed — vocabulary
+ *   labels are advisory (PAT-230 / fail-open principle).
+ *
+ * Returns WorkspaceVocabCtx on cache hit or successful fetch; undefined on error/null fetcher result.
+ */
+export declare function getOrFetchVocabCtx(cacheKey: string, fetcher: () => Promise<WorkspaceVocabCtx | null>): Promise<WorkspaceVocabCtx | undefined>;
+//# sourceMappingURL=workspaceVocabCache.d.ts.map

package/dist/lib/workspaceVocabCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspaceVocabCache.d.ts","sourceRoot":"","sources":["../../src/lib/workspaceVocabCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAc5D;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAe5E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,iBAAiB,GAAG,IAAI,CAEhF;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAEzD;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,GAC/C,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAcxC"}

package/dist/lib/workspaceVocabCache.js

@@ -0,0 +1,98 @@
+/**
+ * 5-minute TTL cache for workspace vocabulary context (WP-436 S2).
+ *
+ * Purpose (R2 mitigation): the CLI resolves vocabulary labels on every invocation.
+ * Without a cache, each `pb orient` / `pb get` / `pb capture` would call
+ * `chain.getVocabulary` — adding a Convex round-trip overhead and risking
+ * handshake-time staleness. A 5-min TTL short-circuits repeat calls within
+ * a typical session while staying fresh enough that label changes land quickly.
+ *
+ * PAT-230: the cache holds WorkspaceVocabCtx (pure data, no Convex imports here).
+ * DEC-1021: only Axis 2 (collectionLabels) lives here; Axis 1 (displayNames) is untouched.
+ *
+ * S4 note: when Cortex UI builds its `vocabularyStore`, it should mirror this
+ * contract — a keyed map by workspaceId with an expiresAt field (Cortex has
+ * direct access to workspaceId; the CLI uses apiKey as a 1:1 surrogate, since
+ * the HTTP gateway server-side injects workspaceId from authResult per
+ * convex/http.ts:675).
+ */
+const TTL_MS = 5 * 60 * 1000; // 5 minutes
+const STALE_WARN_MS = 4 * 60 * 1000; // warn after 4 minutes (1 minute before expiry)
+/** In-memory cache: cacheKey (CLI: apiKey; Cortex would use workspaceId) → CacheEntry. */
+const cache = new Map();
+/**
+ * Get a cached WorkspaceVocabCtx by cacheKey, or null if expired/missing.
+ * Prints a staleness warning when the entry is older than STALE_WARN_MS.
+ */
+export function getCachedVocabCtx(cacheKey) {
+    const entry = cache.get(cacheKey);
+    if (!entry)
+        return null;
+    const now = Date.now();
+    if (now >= entry.expiresAt) {
+        cache.delete(cacheKey);
+        return null;
+    }
+    if (now - (entry.expiresAt - TTL_MS) >= STALE_WARN_MS) {
+        // Staleness hint: labels were fetched > 4 min ago, will refresh within 1 min.
+        process.stderr.write(`[pb] Workspace vocabulary context is almost stale — will refresh on next invocation.\n`);
+    }
+    return entry.ctx;
+}
+/**
+ * Store a WorkspaceVocabCtx under cacheKey with a 5-min TTL.
+ */
+export function setCachedVocabCtx(cacheKey, ctx) {
+    cache.set(cacheKey, { ctx, expiresAt: Date.now() + TTL_MS });
+}
+/**
+ * Explicitly invalidate a cached vocab context by cacheKey.
+ * Call this when `updateCollectionLabels` mutation succeeds (e.g. after `pb handshake`).
+ */
+export function invalidateVocabCtx(cacheKey) {
+    cache.delete(cacheKey);
+}
+/**
+ * Clear all cached entries (useful for testing or `pb handshake --refresh`).
+ */
+export function clearVocabCache() {
+    cache.clear();
+}
+/**
+ * Get the cached vocab context, or fetch it via the provided async fetcher on cache miss.
+ *
+ * Usage pattern at CLI command sites:
+ * ```ts
+ * const vocabCtx = await getOrFetchVocabCtx(config.apiKey, async () => {
+ *   type VocabResult = { collectionLabels?: Record<string, unknown> };
+ *   const vocab = await kernelCall<VocabResult>('chain.getVocabulary', {});
+ *   return vocab?.collectionLabels
+ *     ? { collectionLabels: vocab.collectionLabels as WorkspaceVocabCtx['collectionLabels'] }
+ *     : null;
+ * });
+ * ```
+ *
+ * - `cacheKey`: use the API key as a surrogate for cacheKey (1:1 mapping at CLI layer).
+ * - `fetcher`: async function that resolves the vocab ctx; returns null on failure to signal
+ *   "don't cache, fall back to resolver literal". Fetcher errors are swallowed — vocabulary
+ *   labels are advisory (PAT-230 / fail-open principle).
+ *
+ * Returns WorkspaceVocabCtx on cache hit or successful fetch; undefined on error/null fetcher result.
+ */
+export async function getOrFetchVocabCtx(cacheKey, fetcher) {
+    const cached = getCachedVocabCtx(cacheKey);
+    if (cached)
+        return cached;
+    try {
+        const ctx = await fetcher();
+        if (ctx) {
+            setCachedVocabCtx(cacheKey, ctx);
+            return ctx;
+        }
+    }
+    catch {
+        // fail-open — vocabulary labels are advisory, never block the command
+    }
+    return undefined;
+}
+//# sourceMappingURL=workspaceVocabCache.js.map

package/dist/lib/workspaceVocabCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspaceVocabCache.js","sourceRoot":"","sources":["../../src/lib/workspaceVocabCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAUH,MAAM,MAAM,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,YAAY;AAC1C,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,gDAAgD;AAErF,0FAA0F;AAC1F,MAAM,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;AAE5C;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAClC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,IAAI,GAAG,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QAC3B,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,SAAS,GAAG,MAAM,CAAC,IAAI,aAAa,EAAE,CAAC;QACtD,8EAA8E;QAC9E,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,wFAAwF,CACzF,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC;AACnB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,GAAsB;IACxE,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;AAC/D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAgB;IACjD,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AACzB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe;IAC7B,KAAK,CAAC,KAAK,EAAE,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,QAAgB,EAChB,OAAgD;IAEhD,MAAM,MAAM,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC3C,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,OAAO,EAAE,CAAC;QAC5B,IAAI,GAAG,EAAE,CAAC;YACR,iBAAiB,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;YACjC,OAAO,GAAG,CAAC;QACb,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,sEAAsE;IACxE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/scoreboard/diagnose.d.ts

@@ -0,0 +1,266 @@
+/**
+ * SYNCED from packages/scoreboard-core/src/index.ts — DO NOT EDIT HERE.
+ * Canonical SSOT for the flywheel scoreboard diagnosis (consumed by BOTH the published
+ * `pb` CLI and the Cortex page). The CLI cannot import the workspace package at publish time
+ * (tsc, no bundler), so it carries this committed copy. Edit the source, then run:
+ *   node scripts/sync-scoreboard-core.mjs
+ * A content-hash drift gate (scripts/check-mcp-lib-drift.mjs) fails CI if this drifts.
+ */
+/**
+ * Flywheel scoreboard — the DIAGNOSIS LAYER (spec §2d), SHARED SSOT.
+ *
+ * This is the layer that turns a raw number into the agent closing the loop. It is a PURE
+ * mapping (no I/O — no fs, no node, no Convex runtime) from the data-layer payload
+ * (M1/M2/M3/materialization, from the internal `scoreboard` action) PLUS the CLI-computed M5
+ * local-drift, to per-metric diagnoses: `{ status, reading, cause, nextAction }`.
+ *
+ * WHY THIS LIVES IN ITS OWN WORKSPACE PACKAGE (`@product-brain/scoreboard-core`): the diagnosis
+ * is consumed by BOTH the `pb` CLI (`packages/cli`, pretty + --json) AND the Cortex page
+ * (`src/routes/(app)/w/[slug]/scoreboard`). A shared workspace package is the repo's convention
+ * for framework-agnostic logic two non-Convex surfaces share (mirrors `@product-brain/doc-ast`).
+ * The CLI cannot import across the monorepo boundary at publish time, so it consumes this body
+ * through a committed copy guarded by a content-hash drift check (the same pattern mcp-server uses
+ * for `convex/lib/flags_core.ts` → `src/flags.ts`). The SvelteKit app imports it directly.
+ *
+ * NOTHING HERE TOUCHES fs/node/Convex — the CLI-only `computeLocalDrift` (which stats
+ * `.productbrain/`) stays in `packages/cli/src/scoreboard/localDrift.ts`. `diagnoseM5` itself is
+ * pure (it maps a LocalDriftM5 → diagnosis) and lives here; only the fs *collection* of that
+ * LocalDriftM5 is CLI-only.
+ *
+ * HONESTY OVER FLATTERY (spec §0, §2c). The hard rules this layer encodes:
+ *   - NO flip threshold is pinned yet (DEC-1282). Where a flip would decide ok/degraded, we
+ *     render `awaiting` ("threshold unpinned — pin against live distribution"), NEVER an
+ *     invented number. The RAW reading is always shown.
+ *   - M4 (WP-487 Slice 2, FEAT-1374: the organic rework meter) is now IN the data payload —
+ *     raw distribution only, `unmeasured` with nothing served yet, `awaiting` otherwise (no
+ *     first-time-good floor is pinned), NEVER a fake green, NEVER a causality claim.
+ *   - A STANDING `unmeasured` line for coaching/moat quality (TEN-2377): four green tiles ≠ a
+ *     healthy moat. The board must not imply moat health.
+ *   - Every `degraded`/`awaiting` carries a concrete `nextAction`.
+ *
+ * Pure + exported so the diagnosis unit tests assert the awaiting/unmeasured/degraded mapping
+ * without any network or filesystem.
+ */
+/** A metric's diagnosis status. */
+export type DiagnosisStatus = 'ok' | 'degraded' | 'awaiting' | 'unmeasured';
+export interface MetricDiagnosis {
+    /** The metric id (M1..M5) + a short human label. */
+    metric: string;
+    label: string;
+    status: DiagnosisStatus;
+    /** The raw reading, ALWAYS shown — never replaced by a verdict. */
+    reading: string;
+    /** Named cause of a degraded/awaiting/unmeasured reading (or the steady-state note). */
+    cause: string;
+    /** The concrete next action that closes the loop (empty string when status === 'ok'). */
+    nextAction: string;
+}
+export interface M1Payload {
+    mix: {
+        audited: number;
+        draft: number;
+        noDomain: number;
+        total: number;
+    };
+    noDomainShare: number | null;
+    auditedShare: number | null;
+    draftShare: number | null;
+    windowMs: number;
+    servedRowCount: number;
+    /**
+     * TEN-2449: rows that WERE rendered but fell outside M1's covered serve (`orient/cli/brief`).
+     * Optional so an older payload fails SOFT. When this is > 0 and the mix is empty, the operator
+     * has been serving — just not on the one path M1 measures — and the diagnosis must say so
+     * rather than repeat "drive a serve".
+     */
+    excludedOutOfCoverage?: number;
+}
+export interface M2Payload {
+    divergentBuckets: number;
+    fullParity: boolean;
+    task: string | null;
+}
+export interface M3Payload {
+    capturedCount: number;
+    everRatifiedCount: number;
+    inSessionRatifiedCount: number;
+    everRatifiedRate: number | null;
+    inSessionRatifiedRate: number | null;
+    sessionWindow: number;
+    sessionsConsidered: number;
+}
+export interface MaterializationPayload {
+    latestMaterializedAt: number | null;
+    materializationAgeMs: number | null;
+    now: number;
+}
+/**
+ * WP-487 Slice 2 (FEAT-1374): the organic rework meter, filling the reserved M4 slot. Mirrors
+ * `convex/scoreboard/aggregates.ts`'s `M4Result` structurally (not imported — packages/* has no
+ * import path into convex/, same convention as the other *Payload shapes above).
+ */
+export interface M4Payload {
+    reworkJoinWindowMs: number;
+    lookbackWindowMs: number;
+    now: number;
+    servedCount: number;
+    unattributableServedCount: number;
+    pendingObservationCount: number;
+    decidedCount: number;
+    firstTimeGoodCount: number;
+    reworkedCount: number;
+    firstTimeGoodShare: number | null;
+    signalCount: number;
+    joinedSignalCount: number;
+    unjoinedSignalCount: number;
+    falseAttributionRate: number | null;
+    byClassification: {
+        revision: number;
+        ci_review_correction: number;
+        user_override: number;
+    };
+    ciReviewCorrectionAttribution: {
+        attributable: number;
+        notAttributable: number;
+        unspecified: number;
+    };
+    cohort: {
+        workspaceId: string;
+        taskProvidedCount: number;
+        taskAbsentCount: number;
+    };
+}
+/**
+ * WP-499 Slice B (TEN-2743, §2.5): advisories/verdicts/detection-coverage/override-rate.
+ * Mirrors `convex/scoreboard/aggregates.ts`'s `CoherenceResult` structurally (not imported,
+ * same convention as the other *Payload shapes above). NO thresholds baked in (DEC-1282) —
+ * `humanBar.meets` is the one legitimate bar-comparison field, read as-is from the server,
+ * never a second verdict computed here.
+ */
+export interface CoherencePayload {
+    openConflictCount: number;
+    openConflictsTruncated: boolean;
+    reviewed: number;
+    real: number;
+    falseAlarm: number;
+    /** PR #422 review (Codex, P2): reviewed/real/falseAlarm/humanBar above are a SAMPLE, not
+     *  a complete count, whenever this is true — render a qualifier, never present as complete. */
+    reviewedTruncated: boolean;
+    humanBar: {
+        meets: boolean;
+        lowerBound: number | null;
+        reviewed: number;
+    };
+    detectionCoverage: {
+        bySurface: Record<string, Record<string, number>>;
+        scanned: number;
+        truncated: boolean;
+    };
+    contradictionOverrideRate: {
+        overrides: number;
+        heldBlocks: number;
+        rate: number | null;
+        truncated: boolean;
+    };
+}
+export interface ScoreboardPayload {
+    workspaceId: string;
+    generatedAt: number;
+    m1: M1Payload;
+    m2: M2Payload;
+    m3: M3Payload;
+    m4: M4Payload;
+    materialization: MaterializationPayload;
+    coherence: CoherencePayload;
+}
+/**
+ * The CLI-computed M5 local-pull drift (A5). Produced by computeLocalDrift() (NOT the data
+ * layer — DEC-1284). `null` fields mean the local `.productbrain/` projection (or the server
+ * materialization) was unavailable; the diagnosis fails soft to `awaiting`.
+ */
+export interface LocalDriftM5 {
+    /** Newest mtime across the local `.productbrain/` projection files, ms epoch. Null = absent. */
+    localProjectionMtime: number | null;
+    /** Server-side projection generation time (materialization.latestMaterializedAt). */
+    serverMaterializedAt: number | null;
+    /** How far the local pull lags the server projection, ms (server − local). Null when undeterminable. */
+    localLagMs: number | null;
+    /** Absolute age of the local projection vs now, ms. Null when the projection is absent. */
+    localAgeMs: number | null;
+    /** Set when `.productbrain/` could not be located/stat'd — diagnosis = awaiting, not a fake ok. */
+    unavailableReason?: string;
+}
+/**
+ * M1 — retrieval truth-state mix. The no-domain-share flip (INS-1775 floor) is UNPINNED, so the
+ * status is `awaiting` whenever there is data to judge (we never invent the 50% floor). With zero
+ * serves it is `unmeasured` (nothing served yet). The named cause for a high no-domain share is
+ * "domains unratified".
+ */
+export declare function diagnoseM1(m1: M1Payload): MetricDiagnosis;
+/**
+ * M2 — ranking agreement (tests the unify integrity). This one HAS a clean structural signal:
+ * post-unify, full parity (divergentBuckets === 0) is the EXPECTED steady state — that's `ok`.
+ * A non-zero divergence IS the regression signal — `degraded` — and the M2-magnitude flip stays
+ * unpinned, but the structural ok/degraded does not need a number (0 vs non-0 is exact).
+ */
+export declare function diagnoseM2(m2: M2Payload): MetricDiagnosis;
+/**
+ * M3 — draft-to-SSOT rate. The in-session-ratify floor (ASM-45 rolling-20 window) is UNPINNED,
+ * so a judged reading is `awaiting`. Zero captures in the window → `unmeasured`.
+ */
+export declare function diagnoseM3(m3: M3Payload): MetricDiagnosis;
+/**
+ * M4 — organic rework meter (WP-487 Slice 2, FEAT-1374). Joins served governance against
+ * later-reported rework signals within a frozen 72h window (TEN-2728) and reports RAW
+ * distribution + a false-attribution counter-metric — never a verdict (DEC-1282 unchanged for
+ * M4) and never a causality claim (spec §6: this is association, not "context served CAUSED
+ * first-time-good"). `unmeasured` when nothing has been served in the window yet (no coverage
+ * population to judge, mirrors diagnoseM1's zero-mix gate); `awaiting` whenever there IS data,
+ * since no first-time-good floor is pinned yet — the raw share is always shown, never replaced
+ * by an invented threshold.
+ */
+export declare function diagnoseM4(m4: M4Payload): MetricDiagnosis;
+/**
+ * M5 — projection staleness, computed as LOCAL-PULL drift at the CLI (DEC-1284). The staleness-age
+ * flip is UNPINNED, so a determinable reading is `awaiting`. When the local `.productbrain/`
+ * projection (or the server materialization) is unavailable, the status is `unmeasured` with the
+ * reason — fail-soft, never a fake ok.
+ */
+export declare function diagnoseM5(m5: LocalDriftM5): MetricDiagnosis;
+/**
+ * M5 (server view) — the Cortex page has NO local filesystem, so it cannot compute the spec's
+ * local-pull drift (DEC-1284). It reads only the server-side projection-generation building block
+ * (`materialization.latestMaterializedAt` / age) the public action already returns — adding NO new
+ * truth (spec §2d). This is deliberately a DIFFERENT, HONEST framing from `diagnoseM5`: it is
+ * SERVER-generation age, never claimed to be the local-pull staleness the CLI measures. The
+ * staleness-age flip is UNPINNED → `awaiting` when there is a materialization; `unmeasured` when
+ * the workspace has never materialized.
+ */
+export declare function diagnoseM5FromServer(materialization: MaterializationPayload): MetricDiagnosis;
+/**
+ * The STANDING coaching/moat-quality `unmeasured` line (TEN-2377). It is NOT a tile with a number —
+ * it is a permanent honesty marker so four green tiles are never read as "the moat is healthy".
+ */
+export declare function diagnoseCoachingMoat(): MetricDiagnosis;
+/** The full diagnosis bundle the CLI renders + emits in --json. */
+export interface ScoreboardDiagnosis {
+    m1: MetricDiagnosis;
+    m2: MetricDiagnosis;
+    m3: MetricDiagnosis;
+    m4: MetricDiagnosis;
+    m5: MetricDiagnosis;
+    /** Standing honesty marker — coaching/moat quality is unmeasured. */
+    moat: MetricDiagnosis;
+}
+/**
+ * diagnose — the whole mapping: data-layer payload + CLI-computed M5 local-drift → per-metric
+ * diagnoses + the standing M4-awaiting + coaching-unmeasured lines. Pure.
+ */
+export declare function diagnose(payload: ScoreboardPayload, m5: LocalDriftM5): ScoreboardDiagnosis;
+/**
+ * diagnoseFromServer — the Cortex-page mapping: it has the public action payload but NO local fs,
+ * so M5 is the server-generation-age view (`diagnoseM5FromServer`) rather than the CLI local-pull
+ * drift. Everything else is identical to `diagnose`. Pure, browser-safe.
+ */
+export declare function diagnoseFromServer(payload: ScoreboardPayload): ScoreboardDiagnosis;
+//# sourceMappingURL=diagnose.d.ts.map

package/dist/scoreboard/diagnose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnose.d.ts","sourceRoot":"","sources":["../../src/scoreboard/diagnose.ts"],"names":[],"mappings":"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"}