oh-my-knowledge 0.38.0 → 0.40.0

package/dist/grading/layered-scores.js

@@ -1,35 +1,57 @@
-const FACTUAL_ASSERTION_TYPES = new Set([
-    'contains',
-    'not_contains',
-    'regex',
-    'json_valid',
-    'json_schema',
-    'equals',
-    'not_equals',
-    'contains_all',
-    'contains_any',
-    'semantic_similarity',
-    'tool_output_contains',
-    'tool_input_contains',
-    'tool_input_not_contains',
-]);
-const BEHAVIORAL_ASSERTION_TYPES = new Set([
-    'starts_with',
-    'ends_with',
-    'min_length',
-    'max_length',
-    'word_count_min',
-    'word_count_max',
-    'cost_max',
-    'latency_max',
-    'turns_min',
-    'turns_max',
-    'tools_called',
-    'tools_not_called',
-    'tools_count_min',
-    'tools_count_max',
-    'custom',
-]);
+/**
+ * 每个 assertion 类型归到事实层 / 行为层。**单一来源**:`computeLayeredScores` 据此把 assertion 明细拆进
+ * fact / behavior 两层算分。
+ *   - **事实层(fact)**:测输出内容对不对 —— 命中 / 匹配 / 结构合法 / 与参考的文本相似度。
+ *   - **行为层(behavior)**:测做事的方式 —— 长度 / 成本 / 轮次 / 工具调用 / 必经里程碑,不看内容本身。
+ *
+ * 不变量:**runner 支持的每个 assertion 类型都必须能被归层**,否则该类型的 pass/fail 会被 computeLayeredScores
+ * 从 fact 与 behavior 同时漏掉 —— 既不报错也不进 composite,静默丢分(曾漏掉七类:mock_hit / rouge_n_min /
+ * bleu_min / levenshtein_max + RAG 三件套 faithfulness / answer_relevancy / context_recall)。叶子断言在此静态
+ * 分类;组合器 `assert-set` 没有静态层,由 `assertions.ts` 的 resolveAssertSetLayer 在 grading 期按其叶子 children
+ * 解析(同层→归层、混层→不计),结果落 detail.layer。`test/grading/layered-scores-exhaustiveness.test.ts` 扫
+ * runner 源(evalAssertion 的 case ∪ `assertion.type ===` 组合器 ∪ ASYNC_ASSERTION_TYPES)守住:新增类型既不在本
+ * 映射、又不是已知组合器,即 CI 失败。
+ */
+export const ASSERTION_LAYER = {
+    contains: 'fact',
+    not_contains: 'fact',
+    regex: 'fact',
+    json_valid: 'fact',
+    json_schema: 'fact',
+    equals: 'fact',
+    not_equals: 'fact',
+    contains_all: 'fact',
+    contains_any: 'fact',
+    semantic_similarity: 'fact',
+    tool_output_contains: 'fact',
+    tool_input_contains: 'fact',
+    tool_input_not_contains: 'fact',
+    // 文本相似度指标:衡量输出与参考答案的内容贴合度 = 内容保真 → 事实层。
+    rouge_n_min: 'fact',
+    bleu_min: 'fact',
+    levenshtein_max: 'fact',
+    // RAG 评委指标:都评输出内容质量(忠实度 / 答非所问 / 关键事实召回),= 内容正确性 → 事实层。
+    faithfulness: 'fact',
+    answer_relevancy: 'fact',
+    context_recall: 'fact',
+    starts_with: 'behavior',
+    ends_with: 'behavior',
+    min_length: 'behavior',
+    max_length: 'behavior',
+    word_count_min: 'behavior',
+    word_count_max: 'behavior',
+    cost_max: 'behavior',
+    latency_max: 'behavior',
+    turns_min: 'behavior',
+    turns_max: 'behavior',
+    tools_called: 'behavior',
+    tools_not_called: 'behavior',
+    tools_count_min: 'behavior',
+    tools_count_max: 'behavior',
+    custom: 'behavior',
+    // 必经工具 / 步骤里程碑(value 形如 "Tool:N"):测"有没有走到那一步" = 做事方式 → 行为层(类同 tools_called)。
+    mock_hit: 'behavior',
+};
 function ratioToScore(ratio) {
     return Number((1 + ratio * 4).toFixed(2));
 }
@@ -45,15 +67,19 @@ function scoreFromDetails(details) {
 export function computeLayeredScores(results) {
     const layered = {};
     if (results.assertions?.details) {
-        const factDetails = results.assertions.details.filter((d) => FACTUAL_ASSERTION_TYPES.has(d.type));
-        const behaviorDetails = results.assertions.details.filter((d) => BEHAVIORAL_ASSERTION_TYPES.has(d.type));
+        // 优先用 detail.layer(组合器如 assert-set 在 grading 期按 children 解析出的层;混层组合器无 layer → 两层都不计,
+        // 见 assertions.ts resolveAssertSetLayer);叶子断言无 layer,退回静态 ASSERTION_LAYER[type]。
+        const layerOf = (d) => d.layer ?? ASSERTION_LAYER[d.type];
+        const factDetails = results.assertions.details.filter((d) => layerOf(d) === 'fact');
+        const behaviorDetails = results.assertions.details.filter((d) => layerOf(d) === 'behavior');
         layered.factScore = scoreFromDetails(factDetails) ?? undefined;
         layered.behaviorScore = scoreFromDetails(behaviorDetails) ?? undefined;
     }
-    // 评委打 0 分是"完全不合格"的合法低分,不是缺失——保留进 composite 计算,不做 > 0 gate。
-    // 只排除 undefined(真正缺数据:没配 judge 或打分失败)。fact/behavior 通过 ratioToScore
-    // 产出的分数理论上 ≥ 1,null 判断即可。
-    if (typeof results.llmScore === 'number') {
+    // 评委分量表是 1-5(见 judge.ts prompt),`score <= 0` 是失败哨兵(非 JSON / parse / executor 错),
+    // 是**缺测**不是「0 分内容」—— 当缺层排除,绝不让基础设施失败当内容分污染 composite。上游(grading/index.ts
+    // 单评委路径 + 多维度 filter(s>0) + 多轮 validSamples)已保证失败不进 llmScore;这里再 `> 0` 防御一层,
+    // 与全管线"0=失败=排除"口径一致(fact/behavior 经 ratioToScore 恒 ≥ 1,有效评委分亦 ≥ 1)。
+    if (typeof results.llmScore === 'number' && results.llmScore > 0) {
         layered.judgeScore = results.llmScore;
     }
     const scores = [layered.factScore, layered.behaviorScore, layered.judgeScore].filter((s) => s != null);

package/dist/inputs/load-samples.d.ts

@@ -32,4 +32,9 @@ export interface LoadSamplesResult {
  * - `requires` from each file unioned together
  */
 export declare function loadSamples(samplesPath: string): LoadSamplesResult;
+/** Pull `.json/.yaml/.yml` siblings out of a directory, skipping omk's own report/health
+ *  artifacts and any underscore-prefixed file (the convention for "not a sample").
+ *  Exported so `omk sample --append` picks its target with the same sorted/filtered order
+ *  that directory-mode loading merges by (deterministic, predictable). */
+export declare function listSampleFilesInDir(dir: string): string[];
 export declare function validateSamples(samples: Sample[]): void;

package/dist/inputs/load-samples.js

@@ -38,8 +38,10 @@ export function loadSamples(samplesPath) {
     };
 }
 /** Pull `.json/.yaml/.yml` siblings out of a directory, skipping omk's own report/health
- *  artifacts and any underscore-prefixed file (the convention for "not a sample"). */
-function listSampleFilesInDir(dir) {
+ *  artifacts and any underscore-prefixed file (the convention for "not a sample").
+ *  Exported so `omk sample --append` picks its target with the same sorted/filtered order
+ *  that directory-mode loading merges by (deterministic, predictable). */
+export function listSampleFilesInDir(dir) {
     const RESERVED = /^(report|health|_)/i;
     return readdirSync(dir)
         .filter((f) => /\.(json|ya?ml)$/i.test(f))

package/dist/inputs/skill-loader.d.ts

@@ -5,6 +5,14 @@ export declare function gitShowFile(ref: string, filePath: string, cwd?: string)
  * 同 gitShowFile 用 `cat-file blob`:对目录会非零退出,不会把树清单字节当文件内容物化。
  */
 export declare function gitShowBytes(ref: string, filePath: string, cwd?: string): Buffer | null;
+/**
+ * 把一个 ref(branch / tag / HEAD / 缩写或完整 SHA)解析到它指向的 commit SHA(#234/#236 还原坐标)。
+ * `^{commit}` 会把 annotated tag 也 peel 到 commit;`--verify --quiet` 解析不出时静默非零退出 → 落 null。
+ * 不存在 / 出错 → null(best-effort,绝不抛、不阻断 eval)。`<ref>` 物化内容时用的就是它,故这是被测字节的定点
+ * (与工作树是否 dirty 无关 —— 内容从 object DB 按 ref 取)。dash-ref(前缀 `-`)直接挡,不得被当 git 选项
+ * (rev-parse 的 rev 不能放 `--` 之后,故显式前置守卫,与 gitShowBytes 的 `--` 同口径 fail-closed)。
+ */
+export declare function gitResolveCommit(ref: string, cwd?: string): string | null;
 export interface GitTreeEntry {
     /** git 文件模式:100644/100755=普通文件,120000=软链,160000=submodule。 */
     mode: string;

package/dist/inputs/skill-loader.js

@@ -73,6 +73,24 @@ export function gitShowBytes(ref, filePath, cwd = process.cwd()) {
         return null;
     }
 }
+/**
+ * 把一个 ref(branch / tag / HEAD / 缩写或完整 SHA)解析到它指向的 commit SHA(#234/#236 还原坐标)。
+ * `^{commit}` 会把 annotated tag 也 peel 到 commit;`--verify --quiet` 解析不出时静默非零退出 → 落 null。
+ * 不存在 / 出错 → null(best-effort,绝不抛、不阻断 eval)。`<ref>` 物化内容时用的就是它,故这是被测字节的定点
+ * (与工作树是否 dirty 无关 —— 内容从 object DB 按 ref 取)。dash-ref(前缀 `-`)直接挡,不得被当 git 选项
+ * (rev-parse 的 rev 不能放 `--` 之后,故显式前置守卫,与 gitShowBytes 的 `--` 同口径 fail-closed)。
+ */
+export function gitResolveCommit(ref, cwd = process.cwd()) {
+    if (!ref || ref.startsWith('-'))
+        return null;
+    try {
+        const out = execFileSync('git', ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], { cwd, encoding: 'utf-8', stdio: GIT_PROBE_STDIO }).trim();
+        return out || null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * 递归列出 `<ref>:<treePath>` 子树下的叶子条目(blob / 软链 / submodule)。tree 不存在返回 []。
  * 用 `-z`(NUL 分隔):git 不会对含换行 / 非 ASCII 的路径做 C-quote,路径原样可回喂 git show。
@@ -632,6 +650,9 @@ export function resolveArtifacts(skillDir, variants, opts = {}) {
             if (!resolved) {
                 throw new Error(`skill not found in git ${ref}: ${name}.md or ${name}/SKILL.md`);
             }
+            // #234/#236:把 variant 的 ref 解析到实际 commit 当还原坐标。是 ref(可能 branch/tag/HEAD)而非进程
+            // cwd 的 HEAD —— 内容从 object DB 按这个 ref 物化,坐标必须对齐它(否则在别的分支跑会记错版本)。
+            const resolvedCommit = gitResolveCommit(ref, gitCtx.repoRoot) ?? undefined;
             if (resolved.isDir) {
                 // git 目录-skill 忠实执行:物化整树到临时目录 → 落地内容寻址隔离副本 → executor cwd 锚副本,
                 // agent 读得到 references/ 资产、资产成为真实运行时输入。整树指纹与 install 受管记录的
@@ -652,6 +673,7 @@ export function resolveArtifacts(skillDir, variants, opts = {}) {
                     contentHash: isolated.contentHash,
                     locator: name,
                     ref,
+                    ...(resolvedCommit ? { resolvedCommit } : {}),
                     cwd: variantCwd,
                     ...(isolated.execRoot ? { execRoot: isolated.execRoot } : {}),
                 });
@@ -672,6 +694,7 @@ export function resolveArtifacts(skillDir, variants, opts = {}) {
                 contentHash: hashBytes(skillMdBytes),
                 locator: name,
                 ref,
+                ...(resolvedCommit ? { resolvedCommit } : {}),
                 cwd: variantCwd,
             });
             continue;

package/dist/managed/evidence.d.ts

@@ -1,7 +1,8 @@
 import type { EvaluationReport, ManagedEvidenceRef } from '../types/index.js';
 /**
  * 为某个变体组装一条 evidence ref;变体无真实内容(baseline / no-skill / 缺 hash)→ null。
- * `verdict` 由调用方传入(CLI 已 computeVerdict,避免在此重算)。
+ * `verdict` 由调用方传入(CLI 已 computeVerdict,避免在此重算)。git 还原坐标从该 variant 的
+ * `resolvedCommit` 取(见 variantResolvedCommit),无则不记。
  */
 export declare function buildEvidenceRef(report: EvaluationReport, variant: string, verdict: string, recordedAt: string): ManagedEvidenceRef | null;
 export interface RecordedEvidence {

package/dist/managed/evidence.js

@@ -27,7 +27,7 @@
  */
 import { basename, dirname } from 'node:path';
 import { hashString } from '../eval-core/evaluation-reporting.js';
-import { loadAllManagedRecords, appendManagedEvidence, managedDir, resolveManagedDir } from './store.js';
+import { loadAllManagedRecords, appendManagedEvidence, managedDir, resolveManagedDir, isShaLike } from './store.js';
 /** baseline / 无 skill 变体的 artifactHash 哨兵(见 report.ts artifactHashes 注释)——不产证据。 */
 const NO_SKILL = 'no-skill';
 /** 样本集覆盖摘要:report 的 sampleHashes 排序后取一个稳定 digest(同一样本集 ⇒ 同 hash)。
@@ -39,9 +39,20 @@ function sampleCoverage(report) {
     const entries = Object.entries(sh).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
     return { count: entries.length, hash: hashString(JSON.stringify(entries)) };
 }
+/**
+ * 该版的 git 还原坐标(#234/#236):被测 variant 物化时 `<ref>` 解析出的实际 commit(resolveArtifacts 在
+ * 物化本地 git variant 时算好,经 `variantConfigs[].resolvedCommit` 透传)。**不是**进程 cwd 的 HEAD ——
+ * variant 内容从 object DB 按它自己的 ref 取,在别的分支 / 用显式旧 SHA 跑时 cwd HEAD 会是错版本。
+ * 远端 / file variant 无 resolvedCommit → 不记(诚实留空)。读到的值再过一道 SHA 形态守卫,脏报告不污染证据。
+ */
+function variantResolvedCommit(report, variant) {
+    const cfg = report.meta?.variantConfigs?.find((c) => c.variant === variant);
+    return isShaLike(cfg?.resolvedCommit) ? cfg.resolvedCommit : undefined;
+}
 /**
  * 为某个变体组装一条 evidence ref;变体无真实内容(baseline / no-skill / 缺 hash)→ null。
- * `verdict` 由调用方传入(CLI 已 computeVerdict,避免在此重算)。
+ * `verdict` 由调用方传入(CLI 已 computeVerdict,避免在此重算)。git 还原坐标从该 variant 的
+ * `resolvedCommit` 取(见 variantResolvedCommit),无则不记。
  */
 export function buildEvidenceRef(report, variant, verdict, recordedAt) {
     const contentHash = report.meta?.artifactHashes?.[variant];
@@ -49,6 +60,7 @@ export function buildEvidenceRef(report, variant, verdict, recordedAt) {
         return null;
     const meta = report.meta;
     const cov = sampleCoverage(report);
+    const gitCommit = variantResolvedCommit(report, variant);
     return {
         reportId: report.id,
         contentHash,
@@ -60,6 +72,7 @@ export function buildEvidenceRef(report, variant, verdict, recordedAt) {
             ...(meta.judgePromptHash ? { judgePromptHash: meta.judgePromptHash } : {}),
             ...(meta.debiasMode ? { debiasMode: meta.debiasMode } : {}),
         },
+        ...(gitCommit ? { gitCommit } : {}),
     };
 }
 /**

package/dist/managed/index.d.ts

@@ -4,7 +4,9 @@
  */
 export * from './store.js';
 export * from './evidence.js';
+export * from './observe-feedback.js';
 export * from './list-view.js';
+export * from './version-scores.js';
 export * from './list-query.js';
 export * from './source-probe.js';
 export * from './promote-gate.js';

package/dist/managed/index.js

@@ -4,7 +4,9 @@
  */
 export * from './store.js';
 export * from './evidence.js';
+export * from './observe-feedback.js';
 export * from './list-view.js';
+export * from './version-scores.js';
 export * from './list-query.js';
 export * from './source-probe.js';
 export * from './promote-gate.js';

package/dist/managed/list-view.d.ts

@@ -8,7 +8,7 @@
  * reachable 时才走 `deriveManagedState`(哈不等 → stale)。verdict / 可比性取**当前有效证据**
  * (contentHash == record.contentHash)里 recordedAt 最新那条 —— 旧内容的证据不冒充当前。
  */
-import type { ArtifactKind, ManagedArtifactRecord, ManagedLifecycleLabel } from '../types/index.js';
+import type { ArtifactKind, ManagedArtifactRecord, ManagedLifecycleLabel, ManagedObservation } from '../types/index.js';
 /** 当前源探测结果(三态)。`reachable:false` = 不可达 / 解析失败 / 拒读,**不等于**已 drift。 */
 export interface SourceProbe {
     reachable: boolean;
@@ -36,6 +36,20 @@ export interface ManagedListRow {
         judgePromptHash?: string;
         debiasMode?: Array<'length' | 'position'>;
     };
+    /** 当前 promoted 版本是否经 `--force` override 采用(只读审计标);非越门 / 已 rollback / 未采用 → undefined。
+     *  override 的写仍只在 CLI(`promote --force`),Studio 只读展示 —— 见 spec §9(#238)。 */
+    override?: {
+        verdict: string;
+        overriddenBlocks?: string[];
+    };
+    /** observe 生产盲区 marker(#235):仅当 `deriveProductionGap` 取最新观测为**确诊盲区**(红 + 统计够力)时填。
+     *  与 `state` / `drifted` **正交** —— 它是版本无关的生产信号(observe 量线上部署版),绝不参与生命周期、不翻
+     *  stale(见 store.deriveProductionGap)。underpowered / 非红观测不在此 surface(留 unknown / 信息态,避免噪声)。 */
+    productionGap?: {
+        healthBand: ManagedObservation['healthBand'];
+        confidence: ManagedObservation['confidence'];
+        gapByType: ManagedObservation['gapByType'];
+    };
     /** 最新当前证据的记录时间。 */
     recordedAt?: string;
     /** 当前有效证据数 / 全部证据数(含旧内容的历史证据)。 */

package/dist/managed/list-view.js

@@ -1,4 +1,4 @@
-import { deriveManagedState, isCurrentlyPromoted } from './store.js';
+import { deriveManagedState, isCurrentlyPromoted, currentPromoteOverride, deriveProductionGap } from './store.js';
 /** 当前有效证据(contentHash == record.contentHash)里 recordedAt 最新那条;无则 undefined。
  *  list(展示最新 verdict)与 promote(门禁取证)共用同一口径——旧内容的证据不冒充当前。 */
 export function latestCurrentEvidence(record) {
@@ -35,6 +35,10 @@ export function buildManagedListRow(record, probe) {
         drifted = false;
     }
     const latest = latestCurrentEvidence(record);
+    const override = currentPromoteOverride(record);
+    // 生产盲区是读时 marker、与生命周期正交:在 reachable / unreachable / 任意 state 下都照常计算并 surface
+    // (observe 量的是线上部署版,与本机能否 probe 源、源是否漂移无关)。只 surface 确诊盲区(marker==='gap')。
+    const gap = deriveProductionGap(record);
     return {
         id: record.id,
         name: record.name,
@@ -47,6 +51,10 @@ export function buildManagedListRow(record, probe) {
         ...(latest?.verdict ? { latestVerdict: latest.verdict } : {}),
         ...(latest?.comparability ? { comparability: latest.comparability } : {}),
         ...(latest?.recordedAt ? { recordedAt: latest.recordedAt } : {}),
+        ...(override ? { override } : {}),
+        ...(gap.marker === 'gap' && gap.latest
+            ? { productionGap: { healthBand: gap.latest.healthBand, confidence: gap.latest.confidence, gapByType: gap.latest.gapByType } }
+            : {}),
         currentEvidenceCount,
         totalEvidenceCount: record.evidence.length,
         distributionCount: record.distribution.length,

package/dist/managed/observe-feedback.d.ts

@@ -0,0 +1,60 @@
+/**
+ * observe → managed 反哺(#235)。一次 `omk observe` 跑完,把每个 skill 的生产健康(盲区率 / 严重度加权 /
+ * 统计功效 / 盲区类型计数)落成一条 `ManagedObservation` 追加进**已纳管**的同名 skill 记录,供读时派生
+ * production-gap marker(`deriveProductionGap`)与「建议补样本」提示。写入仿 `evidence.ts` 的 `recordEvalEvidence`。
+ *
+ * 三条与 eval 写证据对齐的取舍:
+ *   - **触发**:observe 完成自动写,但只写**已存在**的受管记录(install 是显式 opt-in,未纳管 skill 永不被
+ *     凭空建记录,零副作用惊吓);CLI 另给 `--no-feedback` 关。
+ *   - **去重**:append-only + 按 `reportId` 去重(observe 无 contentHash,一份报告对一条观测;新窗口是新报告
+ *     → 新条目 = 时间序)。
+ *   - **匹配**:按 skill **名** + `kind==='skill'` 绑 —— observe 报告只带名、无 contentHash。observe 的 skillName
+ *     是 trace 调用名(已 `normalizeSkillName` 去插件前缀),`record.name` 是 install 名,约定相等;skill 的
+ *     frontmatter `name:` ≠ 目录名时静默不匹配(fail-safe,见 spec §7 已知局限)。
+ *
+ * 版本无关:观测的是线上**正在跑那一版**(无 skill contentHash),故产读时 marker、**绝不翻 stale**
+ * (§6.1 只有内容漂移翻 stale;observe 是信号源不是受控 eval)。
+ */
+import type { ManagedObservation } from '../types/index.js';
+/** 结构化最小入参(仿 `version-scores.ts` 的 `ReportScoreView`):observe CLI 侧从 `SkillHealthReport` 抽出
+ *  这几样传入,`managed/` 不 import `observability/`(避免跨支柱反向依赖)。`healthBand` 由 CLI 用 observability
+ *  自己的 `healthBandOf` 算好传入 —— 阈值单一来源,managed 不复制阈值、不伪造 observe 不出的 per-skill band。 */
+export interface ObservedSkillHealthView {
+    skillName: string;
+    segmentCount: number;
+    gapRate: number;
+    weightedGapRate: number;
+    confidence: 'high' | 'low' | 'underpowered';
+    healthBand: 'green' | 'yellow' | 'red';
+    gapByType: {
+        failed_search: number;
+        explicit_marker: number;
+        hedging: number;
+        repeated_failure: number;
+    };
+}
+export interface ObserveReportView {
+    /** observe-health 报告 id —— 观测去重主键。 */
+    reportId: string;
+    /** 被观测**流量窗口的结束时刻**(report.meta.timeRange.to,CLI 侧 buildObserveReportView 取,空则退
+     *  generatedAt)——供 deriveProductionGap 的 latest-wins,不是报告生成的「此刻」(generatedAt 恒约等于
+     *  now,拿它比会让所有观测一样新)。无版本闸门:观测是版本无关的生产信号(见 ManagedObservation.observedAt)。 */
+    observedAt: string;
+    skills: ObservedSkillHealthView[];
+}
+export interface RecordedObservation {
+    recordId: string;
+    name: string;
+    healthBand: 'green' | 'yellow' | 'red';
+    confidence: 'high' | 'low' | 'underpowered';
+    /** 该观测是否构成确诊生产盲区(red 且够力)—— CLI 据此选「盲区警示」还是「已记录」文案。 */
+    isProductionGap: boolean;
+    gapByType: ManagedObservation['gapByType'];
+}
+/**
+ * 驱动:对每个能按 name(限 kind==='skill')匹配到的**已纳管**记录追加一条生产健康观测。返回实际写入清单
+ * (供 CLI 提示)。无任何记录匹配 → 返回空(常见的非管理用户场景,静默无副作用)。
+ */
+export declare function recordObserveHealth(report: ObserveReportView, opts?: {
+    dir?: string;
+}): RecordedObservation[];

package/dist/managed/observe-feedback.js

@@ -0,0 +1,49 @@
+import { loadAllManagedRecords, appendManagedObservation, managedDir, resolveManagedDir, isProductionGapObservation, } from './store.js';
+/**
+ * 驱动:对每个能按 name(限 kind==='skill')匹配到的**已纳管**记录追加一条生产健康观测。返回实际写入清单
+ * (供 CLI 提示)。无任何记录匹配 → 返回空(常见的非管理用户场景,静默无副作用)。
+ */
+export function recordObserveHealth(report, opts = {}) {
+    const out = [];
+    if (report.skills.length === 0)
+        return out;
+    // 写回读方实际取记录的同一目录(project→global 同口径)。
+    const dir = resolveManagedDir(opts.dir ?? managedDir());
+    const records = loadAllManagedRecords(dir);
+    if (records.length === 0)
+        return out;
+    // 按 name 索引,仅 kind==='skill':同名跨 kind 的 prompt/agent 记录不接 observe 信号(observe 测的是 skill)。
+    // id = hash(kind,name) 保证每个 (skill,name) 至多一条记录,故 name→record 唯一,无需唯一性闸门。
+    const byName = new Map();
+    for (const r of records)
+        if (r.kind === 'skill')
+            byName.set(r.name, { id: r.id, name: r.name });
+    for (const s of report.skills) {
+        const rec = byName.get(s.skillName);
+        if (!rec)
+            continue;
+        const observation = {
+            observationKind: 'production-health',
+            reportId: report.reportId,
+            observedAt: report.observedAt,
+            gapRate: s.gapRate,
+            weightedGapRate: s.weightedGapRate,
+            confidence: s.confidence,
+            healthBand: s.healthBand,
+            segmentCount: s.segmentCount,
+            gapByType: s.gapByType,
+        };
+        const merged = appendManagedObservation(dir, rec.id, observation);
+        if (!merged)
+            continue;
+        out.push({
+            recordId: rec.id,
+            name: rec.name,
+            healthBand: s.healthBand,
+            confidence: s.confidence,
+            isProductionGap: isProductionGapObservation(observation),
+            gapByType: s.gapByType,
+        });
+    }
+    return out;
+}

package/dist/managed/store.d.ts

@@ -1,4 +1,4 @@
-import type { ArtifactKind, DeriveManagedStateInput, DerivedManagedState, ManagedArtifactRecord, ManagedArtifactSource, ManagedDecision, ManagedDistributionTarget, ManagedEvidenceRef } from '../types/index.js';
+import type { ArtifactKind, DeriveManagedStateInput, DerivedManagedState, ManagedArtifactRecord, ManagedArtifactSource, ManagedDecision, ManagedDistributionTarget, ManagedEvidenceRef, ManagedObservation } from '../types/index.js';
 /**
  * 受管记录的 per-record 文件存储。一条记录一个 `.omk/managed/<id>.json`,镜像 report-store 的
  * 成熟模式(原子 tmp+rename):每次 install 只碰自己那个文件,independent write、不丢别人、
@@ -15,6 +15,9 @@ export declare function recordPath(dir: string, id: string): string;
 /** 稳定身份 = hash(kind, name)。源路径是可变属性、不进 id。kind 取自固定枚举(无 `|`),分隔可注入。 */
 export declare function managedRecordId(kind: ArtifactKind, name: string): string;
 export { hashArtifactSource, isDistributablePath, distributableCopyFilter } from '../inputs/content-hash.js';
+/** git commit SHA 形态:7–64 位 hex。写入(evidence.ts)与读取校验共用同一判定,避免写读不对称
+ *  (写时不校验、读时却要求 SHA → 自己写进去的值重载时被自己判脏)。 */
+export declare function isShaLike(v: unknown): v is string;
 export declare function loadManagedRecord(dir: string, id: string): ManagedArtifactRecord | null;
 /** 读全部记录。项目目录空 → 兜底全局(镜像 observe inbox 的 project→global)。 */
 export declare function loadAllManagedRecords(dir?: string): ManagedArtifactRecord[];
@@ -44,6 +47,13 @@ export declare function upsertManagedRecord(dir: string, record: ManagedArtifact
  * null —— 这是"管理是 install 显式 opt-in"的体现:eval 绝不为未纳管的 skill 凭空建记录。
  */
 export declare function appendManagedEvidence(dir: string, recordId: string, evidence: ManagedEvidenceRef): ManagedArtifactRecord | null;
+/**
+ * 追加一条 observe 生产健康观测(append-only,#235)。同 evidence 不走 upsert:`mergeManagedRecord` 保留旧
+ * observations、丢弃 next 的(install 只写事实)。按 `reportId` 去重——observe 无 contentHash,一份 observe 报告
+ * 对一条观测;同报告重跑不堆重复,不同报告(新窗口)是新 reportId → 新条目。记录不存在(未 install / 名字不
+ * 匹配)返回 null —— 与 evidence 同口径:observe 绝不为未纳管 skill 凭空建记录(管理是 install 显式 opt-in)。
+ */
+export declare function appendManagedObservation(dir: string, recordId: string, observation: ManagedObservation): ManagedArtifactRecord | null;
 /**
  * 把受管记录的 drift 基线(contentHash)重锚到新源内容哈,保留 evidence / decisions / source /
  * distribution 全不动。用于 `omk evolve` 把胜出版本写回 source 后,让记录跟上实际内容——否则记录的
@@ -65,6 +75,13 @@ export declare function rebaselineManagedContentHash(dir: string, recordId: stri
  * (数组追加序 = 事件序)。
  */
 export declare function isCurrentlyPromoted(record: ManagedArtifactRecord): boolean;
+/**
+ * 当前 promoted 版本是否经 override(--force)采用 —— 返回该 override(verdict + 被绕过的门),否则 undefined。
+ * 仅当前内容最近一条决定是 promote 且带 override 才有值;rollback 之后(已撤销接受)返回 undefined。供 list /
+ * Studio **读时审计**:从总览一眼看出哪些当前采用是越门来的。override 的**写**仍只在 CLI(`promote --force`),
+ * Studio 不执行——见 evidence-gated-management.md §9(#238)。
+ */
+export declare function currentPromoteOverride(record: ManagedArtifactRecord): ManagedDecision['override'];
 /**
  * 追加一条人工管理决定(append-only,promote/reject/rollback 走此路)。与 evidence 同样**不能走 upsert**
  * (`mergeManagedRecord` 刻意保留旧 decisions、丢弃 next.decisions),必须独立 load→push→原子重写。
@@ -103,3 +120,23 @@ export declare function recordManagedArtifact(record: ManagedArtifactRecord, opt
  * 这正是 #203「证据必须跟 artifact 一起走」的读时保证。`'discovered'` 留给无分发的记录,此函数不产生。
  */
 export declare function deriveManagedState(input: DeriveManagedStateInput): DerivedManagedState;
+/** 一条观测是否构成「确诊生产盲区」:healthBand 红 **且** 统计够力。underpowered(数据不足)是 §6.1 的
+ *  unknown —— 既不放行也不拦截,不当确诊盲区;yellow / green 也不算(留信息展示,避免低样本噪声里过度报警)。 */
+export declare function isProductionGapObservation(obs: ManagedObservation): boolean;
+export interface ProductionGapState {
+    /** `gap` = 确诊生产盲区(red + 够力);`underpowered` = 线上数据不足、不可知;`none` = 无观测 / 最新观测非红。 */
+    marker: 'none' | 'gap' | 'underpowered';
+    latest?: ManagedObservation;
+}
+/**
+ * observe 生产健康观测的**读时 marker**(#235)。取**最新一条**观测(latest-wins,按 observedAt = 被观测
+ * 流量窗口结束时刻)分类:red + 够力 → `gap`;underpowered → `underpowered`(数据不足);其余 → `none`。
+ *
+ * **版本无关的生产信号**:observe 量的是线上**部署版**的行为,而记录里没有可靠的「源码版 ↔ 部署版」时间锚
+ * (`evolve` 改写源、`rebaselineManagedContentHash` 只换 `contentHash`,不碰 distribution/installedAt;部署副本
+ * 仍是旧的)——所以这里**不按源码版归因、也不臆造版本闸门**(那只会给假精度、还会在源码 bump 后压掉仍然有效的
+ * 真盲区)。marker 反映的是部署版的近况,可能滞后于当前源码版,UI / spec 据此老实标注。
+ *
+ * **绝不翻 stale / 不动生命周期枚举**(§6.1:只有内容漂移翻 stale,observe 是信号源不是受控 eval)。
+ */
+export declare function deriveProductionGap(record: ManagedArtifactRecord): ProductionGapState;