oh-my-knowledge 0.35.0 → 0.37.0

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

@@ -0,0 +1,58 @@
+/**
+ * `omk list` 的纯视图构造(#203 管理支柱)—— 把受管记录摊成可渲染的行,不做任何 IO。
+ *
+ * 「当前源探测」由调用方注入(`probeOf`):CLI 侧重物化真源算哈,单测侧给 mock —— 保持本模块纯函数、
+ * 可测。探测是**三态**:`reachable:true + hash`(算出了当前哈,可判 drift)/ `reachable:false`(源不可达 /
+ * 解析失败 / 拒绝读取)。**不可达 ≠ 已 drift** —— 把「这里查不了」当「内容变了」会对从别处看的本地 git 记录
+ * 误报 stale(locator 随 cwd 漂),所以不可达时只按证据给 installed/measurable、不打 drift、单独标「未核」。
+ * reachable 时才走 `deriveManagedState`(哈不等 → stale)。verdict / 可比性取**当前有效证据**
+ * (contentHash == record.contentHash)里 recordedAt 最新那条 —— 旧内容的证据不冒充当前。
+ */
+import type { ArtifactKind, ManagedArtifactRecord, ManagedLifecycleLabel } from '../types/index.js';
+/** 当前源探测结果(三态)。`reachable:false` = 不可达 / 解析失败 / 拒读,**不等于**已 drift。 */
+export interface SourceProbe {
+    reachable: boolean;
+    /** 当前源整树 / 单文件哈;仅 reachable 时有。 */
+    hash?: string;
+}
+export interface ManagedListRow {
+    id: string;
+    name: string;
+    /** artifact 类型,直取自记录(裸 kind 留给 ArtifactKind,见 terminology-spec §5.4)。 */
+    kind: ArtifactKind;
+    sourceKind: 'file' | 'git';
+    /** 展示用源标识:仅远端 git(sourceKind==='git' 且带 url)显 url,其余一律显 locator —— 保证「显示的」
+     *  就是「被 probe / 读取的」路径,file 源即便混入 url(validator 已拒)也不显示它。 */
+    sourceLabel: string;
+    state: ManagedLifecycleLabel;
+    drifted: boolean;
+    /** 当前源是否被成功核对过 hash。false = 不可达/拒读 → drift 未核(不据此判 stale)。 */
+    reachable: boolean;
+    /** 当前有效证据(若有)里 recordedAt 最新那条的 verdict。 */
+    latestVerdict?: string;
+    /** 该证据的可比性 marker —— 跨报告比 verdict 前需一致。 */
+    comparability?: {
+        cliVersion: string;
+        judgePromptHash?: string;
+        debiasMode?: Array<'length' | 'position'>;
+    };
+    /** 最新当前证据的记录时间。 */
+    recordedAt?: string;
+    /** 当前有效证据数 / 全部证据数(含旧内容的历史证据)。 */
+    currentEvidenceCount: number;
+    totalEvidenceCount: number;
+    distributionCount: number;
+}
+/** 当前有效证据(contentHash == record.contentHash)里 recordedAt 最新那条;无则 undefined。
+ *  list(展示最新 verdict)与 promote(门禁取证)共用同一口径——旧内容的证据不冒充当前。 */
+export declare function latestCurrentEvidence(record: ManagedArtifactRecord): import("../types/managed.js").ManagedEvidenceRef | undefined;
+export declare function buildManagedListRow(record: ManagedArtifactRecord, probe: SourceProbe): ManagedListRow;
+/**
+ * 组装全部行。`probeOf` 给每条记录探测当前源(三态,见文件头)。
+ * 按 name 排序(稳定、可读);name collation 相等再按 kind。排序对机读出口(--json)也生效,故:
+ *   - **钉死 locale**(`'en'`):缺省 locale 随宿主 LANG / LC_COLLATE 漂,会让两台机器对同一批记录排出不同
+ *     JSON 顺序,破坏 omk「确定、可比」的底色。
+ *   - 平级判定用**同一 collation 度量**(localeCompare 结果是否为 0)而非 `===`:NFC / NFD 等价的同显示名
+ *     在 `===` 下不等、却 collation 相等,用 `===` 会漏掉 kind 平级 tiebreak、令顺序退回 readdir 序(不定)。
+ */
+export declare function buildManagedListRows(records: ManagedArtifactRecord[], probeOf: (record: ManagedArtifactRecord) => SourceProbe): ManagedListRow[];

package/dist/managed/list-view.js

@@ -0,0 +1,70 @@
+import { deriveManagedState, isCurrentlyPromoted } from './store.js';
+/** 当前有效证据(contentHash == record.contentHash)里 recordedAt 最新那条;无则 undefined。
+ *  list(展示最新 verdict)与 promote(门禁取证)共用同一口径——旧内容的证据不冒充当前。 */
+export function latestCurrentEvidence(record) {
+    const current = record.evidence.filter((e) => e.contentHash === record.contentHash);
+    if (current.length === 0)
+        return undefined;
+    // 取 recordedAt 最新的一条。omk 自写恒 UTC `Z`、字典序即时间序;但记录可手改 / 随仓库分发,异偏移
+    // 或异精度的 ISO 串字典序会乱 → 优先按解析后的真实时刻比,两端都可解析才用;否则退回字典序(不劣化
+    // omk 自写场景)。并列取后出现的。
+    const ms = (s) => { const n = Date.parse(s); return Number.isNaN(n) ? null : n; };
+    return current.reduce((a, b) => {
+        const ta = ms(a.recordedAt);
+        const tb = ms(b.recordedAt);
+        if (ta !== null && tb !== null)
+            return tb >= ta ? b : a;
+        return b.recordedAt >= a.recordedAt ? b : a;
+    });
+}
+export function buildManagedListRow(record, probe) {
+    const currentEvidenceCount = record.evidence.filter((e) => e.contentHash === record.contentHash).length;
+    let state;
+    let drifted;
+    if (probe.reachable) {
+        // 算出了当前哈:正常推导(哈不等 → stale/drift)。
+        const d = deriveManagedState({ record, currentContentHash: probe.hash });
+        state = d.label;
+        drifted = d.drifted;
+    }
+    else {
+        // 不可达:不据此判 stale。promote 决定是**内容锚定**的(只看 record.decisions + record.contentHash,
+        // 不依赖源能否被 probe),故当前内容仍处于 promoted 态时保留 promoted —— 它比 evidence 更不该因源不可达
+        // 丢失(deriveManagedState 的 promoted 分支同理)。否则按证据给 measurable/installed,drift 标未核。
+        state = isCurrentlyPromoted(record) ? 'promoted' : currentEvidenceCount > 0 ? 'measurable' : 'installed';
+        drifted = false;
+    }
+    const latest = latestCurrentEvidence(record);
+    return {
+        id: record.id,
+        name: record.name,
+        kind: record.kind,
+        sourceKind: record.source.sourceKind,
+        sourceLabel: record.source.sourceKind === 'git' && record.source.url ? record.source.url : record.source.locator,
+        state,
+        drifted,
+        reachable: probe.reachable,
+        ...(latest?.verdict ? { latestVerdict: latest.verdict } : {}),
+        ...(latest?.comparability ? { comparability: latest.comparability } : {}),
+        ...(latest?.recordedAt ? { recordedAt: latest.recordedAt } : {}),
+        currentEvidenceCount,
+        totalEvidenceCount: record.evidence.length,
+        distributionCount: record.distribution.length,
+    };
+}
+/**
+ * 组装全部行。`probeOf` 给每条记录探测当前源(三态,见文件头)。
+ * 按 name 排序(稳定、可读);name collation 相等再按 kind。排序对机读出口(--json)也生效,故:
+ *   - **钉死 locale**(`'en'`):缺省 locale 随宿主 LANG / LC_COLLATE 漂,会让两台机器对同一批记录排出不同
+ *     JSON 顺序,破坏 omk「确定、可比」的底色。
+ *   - 平级判定用**同一 collation 度量**(localeCompare 结果是否为 0)而非 `===`:NFC / NFD 等价的同显示名
+ *     在 `===` 下不等、却 collation 相等,用 `===` 会漏掉 kind 平级 tiebreak、令顺序退回 readdir 序(不定)。
+ */
+export function buildManagedListRows(records, probeOf) {
+    return records
+        .map((r) => buildManagedListRow(r, probeOf(r)))
+        .sort((a, b) => {
+        const byName = a.name.localeCompare(b.name, 'en');
+        return byName !== 0 ? byName : a.kind.localeCompare(b.kind, 'en');
+    });
+}

package/dist/managed/promote-gate.d.ts

@@ -0,0 +1,40 @@
+/**
+ * promote 证据门禁(纯函数,无 IO)——`omk list` 读侧判据的写侧对应。
+ *
+ * 把「这份当前版本是否值得 ship」收成一组可拦截原因(spec evidence-gated-management.md §5 mandatory four
+ * + §7 default gate)。默认只放行 verdict=PROGRESS(omk default-strict:影响「值得 ship」判定的默认必须严格);
+ * CAUTIOUS 需显式 `acceptCautious`;其余 verdict 一律拦。可比性核对(judge prompt 是否还是当前评委)用
+ * **注入**的当前 judge hash 集合,故本模块不依赖 grading 层、保持叶子可测。
+ *
+ * force(越门)不在此处:门禁只产「客观判定」。CLI 拿到结果后决定是否 `--force` 越过——但**无当前证据时
+ * 无 evidence 可锚定,force 也越不过**(返回的 evidence 为 undefined,CLI 据此拒绝空证据 promote)。
+ */
+import type { ManagedArtifactRecord, ManagedEvidenceRef } from '../types/index.js';
+export type PromoteBlockKind = 'drifted' | 'no_current_evidence' | 'incomparable' | 'verdict_blocked';
+export interface PromoteBlock {
+    /** 限定判别字(裸 kind 留给 ArtifactKind,见 terminology-spec §5.4);这是「拦截原因」分类、非持久。 */
+    blockKind: PromoteBlockKind;
+    /** 供 CLI 拼 i18n 参数的可读细节(被拦的 verdict / judge hash 等)。 */
+    detail?: Record<string, string>;
+}
+export interface PromoteGateInput {
+    record: ManagedArtifactRecord;
+    /** 当前源内容 hash;undefined = 源不可达 / 解析失败(probeSourceState reachable:false)。 */
+    currentContentHash?: string;
+    /** 接受 CAUTIOUS(默认只接受 PROGRESS)。 */
+    acceptCautious?: boolean;
+    /** 当前 omk 的 judge prompt hash 集合(debias on/off 两变体)。CLI 用 getJudgePromptHash 算好注入,
+     *  使本模块不依赖 grading 层。空集 / 省略 = 跳过可比性核对(只在无法取 judge hash 时)。 */
+    currentJudgeHashes?: ReadonlySet<string>;
+}
+export interface PromoteGateResult {
+    /** 无任何拦截原因 → 门禁通过。 */
+    ok: boolean;
+    blocked: PromoteBlock[];
+    /** 非拦截级提醒(如 judgePromptHash 缺失、无从核对可比性)。 */
+    warnings: PromoteBlock[];
+    /** 命中判定的当前有效证据;无当前证据时 undefined —— CLI 据此判定「force 也不能空证据 promote」。 */
+    evidence?: ManagedEvidenceRef;
+    drifted: boolean;
+}
+export declare function evaluatePromoteGate(input: PromoteGateInput): PromoteGateResult;

package/dist/managed/promote-gate.js

@@ -0,0 +1,37 @@
+import { latestCurrentEvidence } from './list-view.js';
+// 默认接受集:只 PROGRESS。
+const DEFAULT_ACCEPTED = new Set(['PROGRESS']);
+export function evaluatePromoteGate(input) {
+    const { record, currentContentHash, acceptCautious, currentJudgeHashes } = input;
+    const blocked = [];
+    const warnings = [];
+    const drifted = currentContentHash === undefined || currentContentHash !== record.contentHash;
+    // 1. drift:源不可达 / 内容已变 → 当前盘上的源不是被测内容,门禁不过(force 可越,见 CLI)。
+    if (drifted)
+        blocked.push({ blockKind: 'drifted' });
+    // 2. 当前有效证据(contentHash == record.contentHash;源 drift 不影响——证据绑的是记录基线内容)。
+    const evidence = latestCurrentEvidence(record);
+    if (!evidence) {
+        // 无证据无从谈 verdict / 可比性,且 force 也无 evidence 可锚定 → 提前收,终态拦截。
+        blocked.push({ blockKind: 'no_current_evidence' });
+        return { ok: false, blocked, warnings, drifted };
+    }
+    // 3. 可比性:judgePromptHash 在场且不属当前任一评委模板 → 评委已变、旧 verdict 不可比 → 拦。
+    //    缺失 → 无从核对(旧报告 / 无 judge 评测)→ warn 不拦。cliVersion 仅展示、不硬卡(否则每次发版即全失效)。
+    const judgeHash = evidence.comparability?.judgePromptHash;
+    if (judgeHash !== undefined && currentJudgeHashes && currentJudgeHashes.size > 0) {
+        if (!currentJudgeHashes.has(judgeHash)) {
+            blocked.push({ blockKind: 'incomparable', detail: { judgePromptHash: judgeHash } });
+        }
+    }
+    else if (judgeHash === undefined) {
+        warnings.push({ blockKind: 'incomparable' });
+    }
+    // 4. verdict ∈ 接受集。
+    const accepted = acceptCautious ? new Set([...DEFAULT_ACCEPTED, 'CAUTIOUS']) : DEFAULT_ACCEPTED;
+    const verdict = evidence.verdict;
+    if (!verdict || !accepted.has(verdict)) {
+        blocked.push({ blockKind: 'verdict_blocked', detail: { verdict: verdict ?? 'UNKNOWN' } });
+    }
+    return { ok: blocked.length === 0, blocked, warnings, evidence, drifted };
+}

package/dist/managed/store.d.ts

@@ -1,4 +1,4 @@
-import type { ArtifactKind, DeriveManagedStateInput, DerivedManagedState, ManagedArtifactRecord, ManagedArtifactSource, ManagedDistributionTarget, ManagedEvidenceRef } from '../types/index.js';
+import type { ArtifactKind, DeriveManagedStateInput, DerivedManagedState, ManagedArtifactRecord, ManagedArtifactSource, ManagedDecision, ManagedDistributionTarget, ManagedEvidenceRef } from '../types/index.js';
 /**
  * 受管记录的 per-record 文件存储。一条记录一个 `.omk/managed/<id>.json`,镜像 report-store 的
  * 成熟模式(原子 tmp+rename):每次 install 只碰自己那个文件,independent write、不丢别人、
@@ -44,6 +44,28 @@ 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;
+/**
+ * 当前内容(contentHash === record.contentHash)是否处于 promoted 态。决定是 append-only 事件流,
+ * promote 与 rollback 互为反操作,故不能看「是否存在过 promote」,而要看**当前内容最近一条** promote/rollback
+ * 决定是不是 promote —— rollback 之后再 promote 仍能恢复 promoted,反之亦然。换了内容(contentHash 变)后
+ * 旧内容的决定一概不算数。
+ *
+ * 「最近」按 decidedAt 真实时刻取,与 `latestCurrentEvidence` 同口径:omk 自写恒 UTC `Z`、字典序即时间序;
+ * 但记录可手改 / 随仓库分发,异偏移 ISO 串字典序会乱 → 两端可解析才用解析时刻,否则退字典序;并列取后出现的
+ * (数组追加序 = 事件序)。
+ */
+export declare function isCurrentlyPromoted(record: ManagedArtifactRecord): boolean;
+/**
+ * 追加一条人工管理决定(append-only,promote/reject/rollback 走此路)。与 evidence 同样**不能走 upsert**
+ * (`mergeManagedRecord` 刻意保留旧 decisions、丢弃 next.decisions),必须独立 load→push→原子重写。
+ *
+ * 幂等:对**当前内容**的 promote/rollback,看是否会改变当前 promoted 态——已 promoted 再 promote、未 promoted
+ * 再 rollback 都不追加、原样返回(由 CLI 提示「已 promoted」/「未 promoted」)。这让重复 `omk promote` /
+ * `omk rollback` 不堆冗余事件,但 promote↔rollback 的真实切换、以及换了内容(contentHash 变)后的新决定仍会
+ * 追加——正是要的版本史。其它 decisionKind(如 reject)仍按「同 kind + 同 contentHash 即 dedup」。记录不存在
+ * (未 install)返回 null,与 evidence 同口径(管理是 install 显式 opt-in,绝不为未纳管 skill 凭空建记录)。
+ */
+export declare function appendManagedDecision(dir: string, recordId: string, decision: ManagedDecision): ManagedArtifactRecord | null;
 /**
  * 统一的记录构造点——所有消费方(CLI / 未来 server / SDK)经此组装,保证 schema 一致。
  * 只接收事实(身份、源、hash、分发落点);evidence/decisions 恒为空(eval/promote 的地盘)。
@@ -64,9 +86,10 @@ export declare function recordManagedArtifact(record: ManagedArtifactRecord, opt
 /**
  * 读时推导生命周期标签。
  *   - 源缺失或 hash 漂(当前内容 ≠ 记录 contentHash)→ stale;
+ *   - 否则当前内容已有 promote 决定 → promoted;
  *   - 否则有**当前**证据 / samples → measurable;
  *   - 否则 installed。
- * 「当前证据」= contentHash 与记录当前 contentHash 匹配的 evidence —— 旧内容的 evidence 不算数,
+ * 「当前证据 / 当前决定」= contentHash 与记录当前 contentHash 匹配的 evidence / decision —— 旧内容的不算数,
  * 这正是 #203「证据必须跟 artifact 一起走」的读时保证。`'discovered'` 留给无分发的记录,此函数不产生。
  */
 export declare function deriveManagedState(input: DeriveManagedStateInput): DerivedManagedState;

package/dist/managed/store.js

@@ -31,9 +31,16 @@ export { hashArtifactSource, isDistributablePath, distributableCopyFilter } from
 function isStringField(v) {
     return typeof v === 'string';
 }
-// 校验到元素级:记录文件是用户可手改的(透明性是设计价值),`evidence:[null]` / 缺字段的 distribution
-// 都是现实的坏手改;若只查 Array.isArray,坏元素会在 deriveManagedState / mergeManagedRecord 里
-// 解引用崩溃(且在 load 的 try/catch 之外)。这里直接判脏 → load 丢弃该文件,消费方永远拿不到半成品。
+/** 仅当字段缺省或是 string 才放行(可选 string 字段的脏值守卫,如 source.url / evidence.verdict)。 */
+function isOptionalString(v) {
+    return v === undefined || typeof v === 'string';
+}
+// 受管记录可安装的 kind(managed 记录绝不是 baseline)。
+const MANAGED_KINDS = new Set(['skill', 'prompt', 'agent', 'workflow']);
+// 校验到**运行时实际收窄**的边界,不止「字段是 string」:记录文件是用户可手改、且可能随仓库分发(被
+// loadAllManagedRecords 无 opt-in 读到)的不可信输入。若只查 string,畸形记录(如 source.url 是对象、
+// sourceKind 是任意串)会绕过 validator,在下游(omk list 的 sourceLabel ?? → dispWidth(对象) 等)
+// 抛 TypeError 让命令崩溃。这里把 source / evidence 收窄到 list 等消费方实际解引用的类型,判脏即丢弃该文件。
 function isManagedArtifactRecord(value) {
     if (!value || typeof value !== 'object')
         return false;
@@ -42,21 +49,72 @@ function isManagedArtifactRecord(value) {
         && r.schemaVersion === 2
         && isStringField(r.id)
         && isStringField(r.name)
-        && isStringField(r.kind)
+        && isStringField(r.kind) && MANAGED_KINDS.has(r.kind)
         && isStringField(r.contentHash)
         && r.source && typeof r.source === 'object'
-        && isStringField(r.source.locator)
-        && isStringField(r.source.sourceKind)
         && Array.isArray(r.distribution)
         && Array.isArray(r.evidence)
         && Array.isArray(r.decisions)))
         return false;
+    const src = r.source;
+    if (!(isStringField(src.locator)
+        && (src.sourceKind === 'file' || src.sourceKind === 'git')
+        && typeof src.isDirectorySkill === 'boolean'
+        && isOptionalString(src.url)
+        && isOptionalString(src.ref)))
+        return false;
+    // url / ref 是 git-only 字段。file 源带 url 时,list 的 sourceLabel 会显示假 url、掩盖真实被 probe /
+    // 读取的 locator(畸形但可通过上面 string 校验)→ 「读了什么」与「显示什么」不一致。判脏丢弃。
+    if (src.sourceKind === 'file' && (src.url !== undefined || src.ref !== undefined))
+        return false;
     const okDist = r.distribution.every((d) => d && typeof d === 'object'
         && isStringField(d.path) && isStringField(d.contentHash));
-    const okEv = r.evidence.every((e) => e && typeof e === 'object'
-        && isStringField(e.reportId) && isStringField(e.contentHash));
-    const okDec = r.decisions.every((d) => d && typeof d === 'object'
-        && isStringField(d.decisionKind));
+    const okEv = r.evidence.every((e) => {
+        if (!e || typeof e !== 'object')
+            return false;
+        const ev = e;
+        if (!(isStringField(ev.reportId) && isStringField(ev.contentHash) && isStringField(ev.recordedAt)))
+            return false;
+        if (!isOptionalString(ev.verdict))
+            return false;
+        // comparability 若存在:必须是带 string cliVersion 的对象(list / promote 会读它)。可选 marker
+        // judgePromptHash / debiasMode 同样收窄到声明类型 —— 否则任意类型脏值会穿过 validator 原样进 `omk list
+        // --json`(及未来 promote gate)消费方。
+        if (ev.comparability !== undefined) {
+            const c = ev.comparability;
+            if (!c || typeof c !== 'object' || !isStringField(c.cliVersion))
+                return false;
+            if (!isOptionalString(c.judgePromptHash))
+                return false;
+            if (c.debiasMode !== undefined
+                && !(Array.isArray(c.debiasMode) && c.debiasMode.every((m) => m === 'length' || m === 'position')))
+                return false;
+        }
+        return true;
+    });
+    const okDec = r.decisions.every((d) => {
+        if (!d || typeof d !== 'object')
+            return false;
+        const dec = d;
+        if (!isStringField(dec.decisionKind))
+            return false;
+        // promote/reject/rollback 的证据指针(promote 写)同样收窄:任意类型脏值不得穿过 validator 进
+        // deriveManagedState / promote 消费方。actor / decidedAt / reason 是 install 后才追加的可选展示字段,
+        // 旧记录(install 时 decisions 恒空)无,按 optional 读。
+        if (!isOptionalString(dec.actor) || !isOptionalString(dec.decidedAt) || !isOptionalString(dec.reason))
+            return false;
+        if (!isOptionalString(dec.contentHash) || !isOptionalString(dec.reportId))
+            return false;
+        if (dec.override !== undefined) {
+            const o = dec.override;
+            if (!o || typeof o !== 'object' || !isStringField(o.verdict))
+                return false;
+            if (o.overriddenBlocks !== undefined
+                && !(Array.isArray(o.overriddenBlocks) && o.overriddenBlocks.every((b) => typeof b === 'string')))
+                return false;
+        }
+        return true;
+    });
     return okDist && okEv && okDec;
 }
 export function loadManagedRecord(dir, id) {
@@ -181,6 +239,69 @@ export function appendManagedEvidence(dir, recordId, evidence) {
     }
     return merged;
 }
+/**
+ * 当前内容(contentHash === record.contentHash)是否处于 promoted 态。决定是 append-only 事件流,
+ * promote 与 rollback 互为反操作,故不能看「是否存在过 promote」,而要看**当前内容最近一条** promote/rollback
+ * 决定是不是 promote —— rollback 之后再 promote 仍能恢复 promoted,反之亦然。换了内容(contentHash 变)后
+ * 旧内容的决定一概不算数。
+ *
+ * 「最近」按 decidedAt 真实时刻取,与 `latestCurrentEvidence` 同口径:omk 自写恒 UTC `Z`、字典序即时间序;
+ * 但记录可手改 / 随仓库分发,异偏移 ISO 串字典序会乱 → 两端可解析才用解析时刻,否则退字典序;并列取后出现的
+ * (数组追加序 = 事件序)。
+ */
+export function isCurrentlyPromoted(record) {
+    const ms = (s) => { const n = Date.parse(s); return Number.isNaN(n) ? null : n; };
+    let latest;
+    for (const d of record.decisions) {
+        if (d.contentHash !== record.contentHash)
+            continue;
+        if (d.decisionKind !== 'promote' && d.decisionKind !== 'rollback')
+            continue;
+        if (latest === undefined) {
+            latest = d;
+            continue;
+        }
+        const tcur = ms(d.decidedAt);
+        const tlat = ms(latest.decidedAt);
+        const newer = tcur !== null && tlat !== null ? tcur >= tlat : d.decidedAt >= latest.decidedAt;
+        if (newer)
+            latest = d;
+    }
+    return latest?.decisionKind === 'promote';
+}
+/**
+ * 追加一条人工管理决定(append-only,promote/reject/rollback 走此路)。与 evidence 同样**不能走 upsert**
+ * (`mergeManagedRecord` 刻意保留旧 decisions、丢弃 next.decisions),必须独立 load→push→原子重写。
+ *
+ * 幂等:对**当前内容**的 promote/rollback,看是否会改变当前 promoted 态——已 promoted 再 promote、未 promoted
+ * 再 rollback 都不追加、原样返回(由 CLI 提示「已 promoted」/「未 promoted」)。这让重复 `omk promote` /
+ * `omk rollback` 不堆冗余事件,但 promote↔rollback 的真实切换、以及换了内容(contentHash 变)后的新决定仍会
+ * 追加——正是要的版本史。其它 decisionKind(如 reject)仍按「同 kind + 同 contentHash 即 dedup」。记录不存在
+ * (未 install)返回 null,与 evidence 同口径(管理是 install 显式 opt-in,绝不为未纳管 skill 凭空建记录)。
+ */
+export function appendManagedDecision(dir, recordId, decision) {
+    const prev = loadManagedRecord(dir, recordId);
+    if (!prev)
+        return null;
+    const isPromotion = decision.decisionKind === 'promote' || decision.decisionKind === 'rollback';
+    const onCurrent = decision.contentHash !== undefined && decision.contentHash === prev.contentHash;
+    const dup = isPromotion && onCurrent
+        // promote/rollback 当前内容:不改变 promoted 态 → no-op(promote 当已 promoted、rollback 当未 promoted)。
+        ? (decision.decisionKind === 'promote') === isCurrentlyPromoted(prev)
+        : decision.contentHash !== undefined
+            && prev.decisions.some((d) => d.decisionKind === decision.decisionKind && d.contentHash === decision.contentHash);
+    const merged = dup
+        ? prev
+        : { ...prev, decisions: [...prev.decisions, decision] };
+    if (!dup) {
+        mkdirSync(dir, { recursive: true });
+        const path = recordPath(dir, recordId);
+        const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
+        writeFileSync(tmp, JSON.stringify(merged, null, 2));
+        renameSync(tmp, path);
+    }
+    return merged;
+}
 /**
  * 统一的记录构造点——所有消费方(CLI / 未来 server / SDK)经此组装,保证 schema 一致。
  * 只接收事实(身份、源、hash、分发落点);evidence/decisions 恒为空(eval/promote 的地盘)。
@@ -207,9 +328,10 @@ export function recordManagedArtifact(record, opts = {}) {
 /**
  * 读时推导生命周期标签。
  *   - 源缺失或 hash 漂(当前内容 ≠ 记录 contentHash)→ stale;
+ *   - 否则当前内容已有 promote 决定 → promoted;
  *   - 否则有**当前**证据 / samples → measurable;
  *   - 否则 installed。
- * 「当前证据」= contentHash 与记录当前 contentHash 匹配的 evidence —— 旧内容的 evidence 不算数,
+ * 「当前证据 / 当前决定」= contentHash 与记录当前 contentHash 匹配的 evidence / decision —— 旧内容的不算数,
  * 这正是 #203「证据必须跟 artifact 一起走」的读时保证。`'discovered'` 留给无分发的记录,此函数不产生。
  */
 export function deriveManagedState(input) {
@@ -218,6 +340,10 @@ export function deriveManagedState(input) {
     const drifted = currentContentHash === undefined || currentContentHash !== record.contentHash;
     if (drifted)
         return { label: 'stale', drifted: true, hasEvidence };
+    // 当前内容(contentHash 匹配)最近一条 promote/rollback 决定是 promote → 已人工接受当前版本,排在 measurable
+    // 之上。rollback 之后落回 measurable/installed;换了内容(contentHash 变)后旧决定不冒充当前。
+    if (isCurrentlyPromoted(record))
+        return { label: 'promoted', drifted: false, hasEvidence };
     if (hasEvidence || hasSamplesOrDoctorPass)
         return { label: 'measurable', drifted: false, hasEvidence };
     return { label: 'installed', drifted: false, hasEvidence };

package/dist/observability/experience.d.ts

@@ -4,6 +4,7 @@ import type { SkillSegment } from './trace-segmenter.js';
 export { findNegativeFeedbackMatches, findPositiveFeedbackMatches, findUserCorrectionMatches, findUserGoalShiftMatches, hasNegativeFeedbackSignal, hasPositiveFeedbackSignal, hasUserCorrectionSignal, hasUserGoalShiftSignal, } from './feedback-matchers.js';
 export type { TextMatchRange } from './feedback-matchers.js';
 export type { ExperienceAssistiveInference, ExperienceAssistiveInferenceCautionCode, ExperienceAssistiveInferenceCode, ExperienceAssistiveInferenceConfidence, ExperienceChecklistContribution, ExperienceChecklistItem, ExperienceChecklistItemStatus, ExperienceEpisode, ExperienceEpisodeArtifact, ExperienceEpisodeArtifactKind, ExperienceEpisodeBoundaryReason, ExperienceEpisodeOutcome, ExperienceEpisodeRole, ExperienceEvidenceChain, ExperienceEvidenceKind, ExperienceEvidenceRef, ExperienceFeedbackAttribution, ExperienceFeedbackAttributionReason, ExperienceFeedbackAttributionRole, ExperienceFeedbackSignal, ExperienceFeedbackSignalType, ExperienceGoalEvidenceRef, ExperienceGoalSlice, ExperienceGoalSliceReasonCode, ExperienceInvocation, ExperienceMessageRange, ExperienceOrchestrationEdge, ExperienceOrchestrationEdgeKind, ExperienceOrchestrationEdgeStatus, ExperienceOutcomeClosure, ExperienceParentReason, ExperienceReviewBasisCode, ExperienceReviewIndicators, ExperienceReviewPriority, ExperienceReviewerReport, ExperienceReviewerReportFinding, ExperienceReviewerReportFindingLevel, ExperienceReviewerReportFindingSource, ExperienceReviewerReportScope, ExperienceReviewerReportStep, ExperienceReviewerReportStepStatus, ExperienceRuleFinding, ExperienceRuleFindingCode, ExperienceRuleFindingLevel, ExperienceRuntimeSkillType, ExperienceRuntimeSkillTypeSource, ExperienceSessionStory, ExperienceSessionStoryAnswer, ExperienceSessionStoryAnswerKey, ExperienceSessionStoryGoalSlice, ExperienceSessionStoryGraphEdge, ExperienceSessionStoryGraphNode, ExperienceSessionStoryNode, ExperienceSessionStoryNodeKind, ExperienceSessionStorySkillLink, ExperienceSessionStorySkillRole, ExperienceSessionStorySubagentDispatch, ExperienceSessionSummary, ExperienceSkillSegment, ExperienceSkillSummary, ExperienceTimelineBranch, ExperienceTimelineEvent, ExperienceTimelineTree, ObservationExperienceReport, ObservationReviewState, };
+export declare const OBSERVATION_EXPERIENCE_SCHEMA_VERSION = 2;
 export declare function aggregateExperienceChecklistItemStatus(statuses: ExperienceChecklistItemStatus[]): ExperienceChecklistItemStatus;
 interface BuildExperienceInput {
     sessions: CcSession[];
@@ -13,6 +14,7 @@ interface BuildExperienceInput {
     reviewState?: ObservationReviewState;
 }
 export declare function buildObservationExperienceReport(input: BuildExperienceInput): ObservationExperienceReport;
+export declare function normalizeObservationExperienceReport(value: unknown): ObservationExperienceReport | null;
 export declare function isExperienceTraceInProgress(session: ExperienceSessionSummary): boolean;
 export declare function hasRecognizableUserGoalText(value: string | undefined): boolean;
 export declare function foldExperienceChecklistItems(items: ExperienceChecklistItem[]): {

package/dist/observability/experience.js

@@ -7,6 +7,7 @@ import { durationMsBetween } from '../shared/time.js';
 import { loadExpectedToolsForSkill, loadFrontmatterSkillType, loadSkillDeclarationCheck, } from './experience-frontmatter.js';
 import { findNegativeFeedbackMatches, findPositiveFeedbackMatches, findUserCorrectionMatches, findUserGoalShiftMatches, hasNegativeFeedbackSignal, hasPositiveFeedbackSignal, hasUserCorrectionSignal, hasUserGoalShiftSignal, } from './feedback-matchers.js';
 export { findNegativeFeedbackMatches, findPositiveFeedbackMatches, findUserCorrectionMatches, findUserGoalShiftMatches, hasNegativeFeedbackSignal, hasPositiveFeedbackSignal, hasUserCorrectionSignal, hasUserGoalShiftSignal, } from './feedback-matchers.js';
+export const OBSERVATION_EXPERIENCE_SCHEMA_VERSION = 2;
 export function aggregateExperienceChecklistItemStatus(statuses) {
     if (statuses.includes('degraded'))
         return 'degraded';
@@ -131,8 +132,8 @@ export function buildObservationExperienceReport(input) {
     const sessions = summarizeExperienceSessions(invocations, sessionGroupsByKey, input.generatedAt, input.reviewState);
     const skills = summarizeExperienceSkills(sessions, invocations);
     return {
-        reportKind: 'observe-experience',
-        schemaVersion: 1,
+        kind: 'observe-experience',
+        schemaVersion: OBSERVATION_EXPERIENCE_SCHEMA_VERSION,
         scope: 'evidence-only',
         generatedAt: input.generatedAt,
         meta: {
@@ -148,6 +149,34 @@ export function buildObservationExperienceReport(input) {
         skills,
     };
 }
+export function normalizeObservationExperienceReport(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const report = value;
+    const kind = report.kind === 'observe-experience' ? report.kind : null;
+    if (!kind)
+        return null;
+    if (report.schemaVersion !== OBSERVATION_EXPERIENCE_SCHEMA_VERSION)
+        return null;
+    if (report.scope !== 'evidence-only')
+        return null;
+    if (typeof report.generatedAt !== 'string' || !report.meta || typeof report.meta !== 'object')
+        return null;
+    if (!Array.isArray(report.goalSlices) || !Array.isArray(report.invocations) || !Array.isArray(report.sessions) || !Array.isArray(report.skills)) {
+        return null;
+    }
+    return {
+        kind: 'observe-experience',
+        schemaVersion: OBSERVATION_EXPERIENCE_SCHEMA_VERSION,
+        scope: 'evidence-only',
+        generatedAt: report.generatedAt,
+        meta: report.meta,
+        goalSlices: report.goalSlices,
+        invocations: report.invocations,
+        sessions: report.sessions,
+        skills: report.skills,
+    };
+}
 function relatedObservationItems(segment, items) {
     return items.filter((item) => item.skillName === segment.skillName
         && (item.sessionId === segment.sessionId || item.recentSessionIds.includes(segment.sessionId))

package/dist/observability/inbox.js

@@ -6,10 +6,11 @@ import { extractGapSignalsFromTrace } from '../analysis/gap-analyzer.js';
 import { ccTracesToResultEntries } from './trace-adapter.js';
 import { isSearchToolCall, toolCallQuery } from '../shared/tool-search.js';
 import { durationMsBetween } from '../shared/time.js';
-import { buildObservationExperienceReport } from './experience.js';
+import { buildObservationExperienceReport, normalizeObservationExperienceReport, } from './experience.js';
 export const DEFAULT_PROJECT_OBSERVATIONS_DIR = join(process.cwd(), '.omk', 'observations');
 export const DEFAULT_GLOBAL_OBSERVATIONS_DIR = join(homedir(), '.oh-my-knowledge', 'observations');
 export const DEFAULT_OBSERVATIONS_DIR = DEFAULT_PROJECT_OBSERVATIONS_DIR;
+const OBSERVATION_INBOX_SCHEMA_VERSION = 2;
 function hashString(input) {
     return createHash('sha256').update(input).digest('hex').slice(0, 16);
 }
@@ -432,8 +433,8 @@ export function buildObservationInboxReport(tracePath, options = {}) {
     const items = finishInboxAggregation(aggregationState);
     const experience = buildObservationExperienceReport({ sessions, segments, items, generatedAt, reviewState: options.reviewState });
     const report = {
-        reportKind: 'observe-inbox',
-        schemaVersion: 1,
+        kind: 'observe-inbox',
+        schemaVersion: OBSERVATION_INBOX_SCHEMA_VERSION,
         meta: {
             tracePath,
             generatedAt,
@@ -543,7 +544,9 @@ export function loadObservationInboxReports(dir = DEFAULT_OBSERVATIONS_DIR) {
         .filter((file) => file.endsWith('-observe-inbox.json'))
         .map((file) => {
         try {
-            const report = JSON.parse(readFileSync(join(dir, file), 'utf-8'));
+            const report = normalizeObservationInboxReport(JSON.parse(readFileSync(join(dir, file), 'utf-8')));
+            if (!report)
+                return null;
             report.items = report.items.map((item) => {
                 const sourceKind = item.sourceKind;
                 return {
@@ -567,7 +570,30 @@ export function loadObservationInboxReports(dir = DEFAULT_OBSERVATIONS_DIR) {
             return null;
         }
     })
-        .filter((r) => r?.reportKind === 'observe-inbox');
+        .filter((r) => r?.kind === 'observe-inbox');
+}
+function normalizeObservationInboxReport(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const report = value;
+    const kind = report.kind === 'observe-inbox' ? report.kind : null;
+    if (!kind)
+        return null;
+    if (report.schemaVersion !== OBSERVATION_INBOX_SCHEMA_VERSION)
+        return null;
+    if (!report.meta || typeof report.meta !== 'object' || !Array.isArray(report.items))
+        return null;
+    const experience = report.experience === undefined
+        ? undefined
+        : normalizeObservationExperienceReport(report.experience) ?? undefined;
+    return {
+        kind: 'observe-inbox',
+        schemaVersion: OBSERVATION_INBOX_SCHEMA_VERSION,
+        meta: report.meta,
+        items: report.items,
+        ...(experience ? { experience } : {}),
+        ...(report.diagnostics !== undefined ? { diagnostics: report.diagnostics } : {}),
+    };
 }
 export function loadLatestObservationInboxReport(dir = DEFAULT_OBSERVATIONS_DIR) {
     const reports = loadObservationInboxReports(dir);

package/dist/observability/review-state.js

@@ -38,10 +38,11 @@ export function observationMetricAnnotationVerdict(state, ref, metricKey) {
 export function observationReviewStatePath(observationsDir) {
     return join(observationsDir, 'review-state.json');
 }
+const OBSERVATION_REVIEW_STATE_SCHEMA_VERSION = 2;
 export function emptyObservationReviewState(now = new Date().toISOString()) {
     return {
-        reportKind: 'observe-review-state',
-        schemaVersion: 1,
+        kind: 'observe-review-state',
+        schemaVersion: OBSERVATION_REVIEW_STATE_SCHEMA_VERSION,
         updatedAt: now,
         entries: {},
     };
@@ -52,15 +53,7 @@ export function loadObservationReviewState(observationsDir) {
         return emptyObservationReviewState();
     try {
         const parsed = JSON.parse(readFileSync(path, 'utf-8'));
-        if (parsed.reportKind !== 'observe-review-state' || parsed.schemaVersion !== 1 || !parsed.entries || typeof parsed.entries !== 'object') {
-            return emptyObservationReviewState();
-        }
-        return {
-            reportKind: 'observe-review-state',
-            schemaVersion: 1,
-            updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : new Date().toISOString(),
-            entries: Object.fromEntries(Object.entries(parsed.entries).filter(([, entry]) => isReviewStateEntry(entry))),
-        };
+        return normalizeObservationReviewState(parsed) ?? emptyObservationReviewState();
     }
     catch {
         return emptyObservationReviewState();
@@ -92,6 +85,24 @@ export function updateObservationReviewState(observationsDir, update, now = new
     writeFileSync(observationReviewStatePath(observationsDir), JSON.stringify(state, null, 2));
     return state;
 }
+function normalizeObservationReviewState(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const parsed = value;
+    const kind = parsed.kind === 'observe-review-state' ? parsed.kind : null;
+    if (!kind)
+        return null;
+    if (parsed.schemaVersion !== OBSERVATION_REVIEW_STATE_SCHEMA_VERSION)
+        return null;
+    if (!parsed.entries || typeof parsed.entries !== 'object')
+        return null;
+    return {
+        kind: 'observe-review-state',
+        schemaVersion: OBSERVATION_REVIEW_STATE_SCHEMA_VERSION,
+        updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : new Date().toISOString(),
+        entries: Object.fromEntries(Object.entries(parsed.entries).filter(([, entry]) => isReviewStateEntry(entry))),
+    };
+}
 export function deleteObservationReviewState(observationsDir, targetType, targetId, now = new Date().toISOString()) {
     if (!isReviewTargetType(targetType))
         throw new Error('invalid review targetType');