oh-my-knowledge 0.35.0 → 0.36.0

package/dist/inputs/skill-loader.js

@@ -52,7 +52,10 @@ const GIT_PROBE_STDIO = ['ignore', 'pipe', 'ignore'];
 // 由 resolveGitRepoContext 解出 repoRoot 后逐处显式传入。
 export function gitShowFile(ref, filePath, cwd = process.cwd()) {
     try {
-        return execFileSync('git', ['cat-file', 'blob', `${ref}:${filePath}`], { cwd, encoding: 'utf-8', stdio: GIT_PROBE_STDIO }).trim();
+        // `--` 隔断 tree-ish:ref 可能来自盘上受管记录的 locator(用户可手改 / 随仓库分发,被 omk list 等只读
+        // 命令喂进来),前缀 `-` 的 ref 不得被当成 git 选项解析(与 #219 fetch 路径同口径,见
+        // feedback_git_subprocess_dashdash)。加 `--` 后 dash-ref 退化为「非法 object name」fail-closed,普通 ref 输出不变。
+        return execFileSync('git', ['cat-file', 'blob', '--', `${ref}:${filePath}`], { cwd, encoding: 'utf-8', stdio: GIT_PROBE_STDIO }).trim();
     }
     catch {
         return null;
@@ -64,7 +67,7 @@ export function gitShowFile(ref, filePath, cwd = process.cwd()) {
  */
 export function gitShowBytes(ref, filePath, cwd = process.cwd()) {
     try {
-        return execFileSync('git', ['cat-file', 'blob', `${ref}:${filePath}`], { cwd, stdio: GIT_PROBE_STDIO }); // 无 encoding → Buffer
+        return execFileSync('git', ['cat-file', 'blob', '--', `${ref}:${filePath}`], { cwd, stdio: GIT_PROBE_STDIO }); // 无 encoding → Buffer;`--` 隔断同 gitShowFile
     }
     catch {
         return null;
@@ -80,7 +83,7 @@ export function gitShowBytes(ref, filePath, cwd = process.cwd()) {
 export function gitLsTreeBlobs(ref, treePath, cwd = process.cwd()) {
     let out;
     try {
-        out = execFileSync('git', ['ls-tree', '-r', '-z', '--full-tree', `${ref}:${treePath}`], { cwd, encoding: 'utf-8', stdio: GIT_PROBE_STDIO });
+        out = execFileSync('git', ['ls-tree', '-r', '-z', '--full-tree', '--', `${ref}:${treePath}`], { cwd, encoding: 'utf-8', stdio: GIT_PROBE_STDIO });
     }
     catch {
         return [];

package/dist/managed/index.d.ts

@@ -4,3 +4,4 @@
  */
 export * from './store.js';
 export * from './evidence.js';
+export * from './list-view.js';

package/dist/managed/index.js

@@ -4,3 +4,4 @@
  */
 export * from './store.js';
 export * from './evidence.js';
+export * from './list-view.js';

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

@@ -0,0 +1,55 @@
+/**
+ * `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;
+}
+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,66 @@
+import { deriveManagedState } from './store.js';
+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 —— 只按证据给 installed/measurable,drift 标未核。
+        state = 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/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,19 +49,49 @@ 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 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) => d && typeof d === 'object'
         && isStringField(d.decisionKind));
     return okDist && okEv && okDec;

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');

package/dist/observability/soft-standards/llm-extractor.js

@@ -2,7 +2,7 @@ import { mkdirSync, writeFileSync } from 'node:fs';
 import { createExecutor } from '../../executors/index.js';
 import { readPromptDocument } from '../../shared/llm-prompts/index.js';
 import { DEFAULT_LLM_ENHANCED_REVIEW_MODEL, PROMPTS_DIR, SOFT_STANDARD_PROMPT_ID, SOFT_STANDARD_PROMPT_VERSION, } from './constants.js';
-import { hashText, loadExisting, markStale, skillDerivedStandardsDir, skillDerivedStandardsPath, } from './skill-standards-store.js';
+import { hashText, loadExisting, markStale, SKILL_DERIVED_STANDARDS_SCHEMA_VERSION, skillDerivedStandardsDir, skillDerivedStandardsPath, } from './skill-standards-store.js';
 import { evaluateRuntimeStandardNodes } from './runtime-evaluator.js';
 export async function extractSkillSoftStandards(options) {
     const { observationsDir, skillChain } = options;
@@ -47,8 +47,8 @@ export async function extractSkillSoftStandards(options) {
         source: 'llm_soft_standard',
     }));
     const record = {
-        reportKind: 'observe-skill-derived-standards',
-        schemaVersion: 1,
+        kind: 'observe-skill-derived-standards',
+        schemaVersion: SKILL_DERIVED_STANDARDS_SCHEMA_VERSION,
         skillName: skillChain.skillName,
         sourceSkillPath: skillChain.definition.path,
         sourceHash,

package/dist/observability/soft-standards/skill-standards-store.d.ts

@@ -1,4 +1,5 @@
 import type { ResolveSkillStandardsOptions, ResolvedSkillStandards, SkillDerivedStandardStatus, SkillDerivedStandards } from './types.js';
+export declare const SKILL_DERIVED_STANDARDS_SCHEMA_VERSION = 2;
 export declare function skillDerivedStandardsDir(observationsDir: string): string;
 export declare function skillDerivedStandardsPath(observationsDir: string, skillName: string): string;
 export declare function loadSkillDerivedStandards(observationsDir: string): Record<string, SkillDerivedStandards>;

package/dist/observability/soft-standards/skill-standards-store.js

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { buildObservationSkillChain } from '../skill-chain.js';
+export const SKILL_DERIVED_STANDARDS_SCHEMA_VERSION = 2;
 export function skillDerivedStandardsDir(observationsDir) {
     return join(observationsDir, 'skill-derived');
 }
@@ -17,8 +18,8 @@ export function loadSkillDerivedStandards(observationsDir) {
         if (!file.endsWith('.json'))
             continue;
         try {
-            const parsed = JSON.parse(readFileSync(join(dir, file), 'utf-8'));
-            if (isSkillDerivedStandards(parsed))
+            const parsed = normalizeSkillDerivedStandards(JSON.parse(readFileSync(join(dir, file), 'utf-8')));
+            if (parsed)
                 out[parsed.skillName] = parsed;
         }
         catch {
@@ -51,11 +52,13 @@ export function updateSkillDerivedStandardStatus(observationsDir, skillName, sta
 }
 export function resolveSkillStandards(skillName, options) {
     const skillChain = options.skillChain ?? buildObservationSkillChain(skillName, options.cwd ?? process.cwd());
-    const derived = options.derivedStandards
-        ? isSkillDerivedStandards(options.derivedStandards)
-            ? options.derivedStandards
-            : options.derivedStandards[skillName]
-        : loadSkillDerivedStandards(options.observationsDir)[skillName];
+    const directDerived = normalizeSkillDerivedStandards(options.derivedStandards);
+    const mappedDerived = options.derivedStandards && !isSkillDerivedStandards(options.derivedStandards)
+        ? normalizeSkillDerivedStandards(options.derivedStandards[skillName])
+        : undefined;
+    const derived = directDerived
+        ?? mappedDerived
+        ?? loadSkillDerivedStandards(options.observationsDir)[skillName];
     const active = [];
     const candidates = [];
     const hasFrontmatterHardRules = skillChain.healthCheck.hardRules.declared && skillChain.healthCheck.hardRules.rules.length > 0;
@@ -112,8 +115,7 @@ export function loadExisting(path) {
     if (!existsSync(path))
         return undefined;
     try {
-        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
-        return isSkillDerivedStandards(parsed) ? parsed : undefined;
+        return normalizeSkillDerivedStandards(JSON.parse(readFileSync(path, 'utf-8')));
     }
     catch {
         return undefined;
@@ -129,13 +131,74 @@ export function markStale(record, generatedAt) {
     };
 }
 export function isSkillDerivedStandards(value) {
+    return normalizeSkillDerivedStandards(value) !== undefined;
+}
+function normalizeSkillDerivedStandards(value) {
     if (!value || typeof value !== 'object')
-        return false;
+        return undefined;
     const item = value;
-    return item.reportKind === 'observe-skill-derived-standards'
-        && item.schemaVersion === 1
-        && typeof item.skillName === 'string'
-        && Array.isArray(item.standards);
+    const kind = item.kind === 'observe-skill-derived-standards' ? item.kind : null;
+    if (!kind)
+        return undefined;
+    if (item.schemaVersion !== SKILL_DERIVED_STANDARDS_SCHEMA_VERSION)
+        return undefined;
+    if (typeof item.skillName !== 'string' || typeof item.generatedAt !== 'string' || typeof item.model !== 'string' || typeof item.executor !== 'string') {
+        return undefined;
+    }
+    if (typeof item.promptId !== 'string' || typeof item.promptVersion !== 'string' || !Array.isArray(item.standards))
+        return undefined;
+    const standards = item.standards
+        .map(normalizeSkillDerivedStandard)
+        .filter((record) => record !== null);
+    return {
+        kind: 'observe-skill-derived-standards',
+        schemaVersion: SKILL_DERIVED_STANDARDS_SCHEMA_VERSION,
+        skillName: item.skillName,
+        ...(typeof item.sourceSkillPath === 'string' ? { sourceSkillPath: item.sourceSkillPath } : {}),
+        ...(typeof item.sourceHash === 'string' ? { sourceHash: item.sourceHash } : {}),
+        generatedAt: item.generatedAt,
+        model: item.model,
+        executor: item.executor,
+        promptId: item.promptId,
+        promptVersion: item.promptVersion,
+        ...(typeof item.promptHash === 'string' ? { promptHash: item.promptHash } : {}),
+        ...(typeof item.runtimeEvidenceHash === 'string' ? { runtimeEvidenceHash: item.runtimeEvidenceHash } : {}),
+        ...(item.enhancedReview && typeof item.enhancedReview === 'object' ? { enhancedReview: item.enhancedReview } : {}),
+        standards,
+    };
+}
+function normalizeSkillDerivedStandard(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const item = value;
+    const standardKind = item.standardKind === 'hard_rule_candidate' || item.standardKind === 'workflow_candidate'
+        ? item.standardKind
+        : item.kind === 'hard_rule_candidate' || item.kind === 'workflow_candidate'
+            ? item.kind
+            : null;
+    if (!standardKind)
+        return null;
+    if (typeof item.id !== 'string' || typeof item.title !== 'string' || typeof item.body !== 'string')
+        return null;
+    if (item.status !== 'pending_review' && item.status !== 'author_confirmed' && item.status !== 'rejected' && item.status !== 'stale') {
+        return null;
+    }
+    if (item.source !== 'llm_soft_standard')
+        return null;
+    if (item.confidence !== 'low' && item.confidence !== 'medium' && item.confidence !== 'high')
+        return null;
+    if (!Array.isArray(item.evidence) || item.evidence.some((entry) => typeof entry !== 'string'))
+        return null;
+    return {
+        id: item.id,
+        standardKind,
+        status: item.status,
+        title: item.title,
+        body: item.body,
+        source: item.source,
+        confidence: item.confidence,
+        evidence: item.evidence,
+    };
 }
 function candidateRank(status) {
     if (status === 'pending_review')

package/dist/observability/soft-standards/types.d.ts

@@ -14,8 +14,8 @@ export interface SkillDerivedStandard {
     evidence: string[];
 }
 export interface SkillDerivedStandards {
-    reportKind: 'observe-skill-derived-standards';
-    schemaVersion: 1;
+    kind: 'observe-skill-derived-standards';
+    schemaVersion: 2;
     skillName: string;
     sourceSkillPath?: string;
     sourceHash?: string;

package/dist/renderer/html-renderer.js

@@ -21,7 +21,7 @@ function levelDot(level) {
     }
 }
 function isEvaluationReport(document) {
-    return document.reportKind === 'evaluation';
+    return document.kind === 'evaluation';
 }
 function scoreOf(summary) {
     return summary?.avgCompositeScore ?? summary?.avgLlmScore ?? null;
@@ -163,7 +163,7 @@ export function renderRunList(runs, lang = DEFAULT_LANG) {
             `<span class="rc-score-num rc-score-num--${cls}">${score.toFixed(2)}</span></div>`;
     };
     const cards = runs.map((run) => {
-        if (run.reportKind === 'batch-evaluation') {
+        if (run.kind === 'batch-evaluation') {
             const m = run.meta;
             const scores = run.items.length > 0
                 ? run.items.map((item) => {
@@ -652,7 +652,7 @@ export function renderBatchEvaluationDetail(report, lang = DEFAULT_LANG) {
 export function renderReportDocumentDetail(report, lang = DEFAULT_LANG) {
     if (!report)
         return renderRunDetail(null, lang);
-    return report.reportKind === 'batch-evaluation'
+    return report.kind === 'batch-evaluation'
         ? renderBatchEvaluationDetail(report, lang)
         : renderRunDetail(report, lang);
 }

package/dist/server/report-server.js

@@ -762,7 +762,7 @@ export function createReportServer({ port, host: hostOption, reportsDir = DEFAUL
                 let evalReport = null;
                 if (entry.eval) {
                     const r = await reportStore.get(entry.eval.reportId);
-                    if (r && r.reportKind === 'evaluation')
+                    if (r && r.kind === 'evaluation')
                         evalReport = r;
                 }
                 res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });