@stardustlc/dsh-dream 0.5.0 → 0.6.0

package/lib/web.d.ts

@@ -5,6 +5,8 @@ import type { Evidence, Lesson } from './knowledge.js';
 export declare const DREAM_ROUTE = "/_dsh/dsh-dream/journal";
 /** M1 经验面板的只读路由。 */
 export declare const DREAM_KNOWLEDGE_ROUTE = "/_dsh/dsh-dream/knowledge";
+/** M2 写入记录面板的只读路由。 */
+export declare const DREAM_BRIDGE_ROUTE = "/_dsh/dsh-dream/bridge";
 /** ?limit 的默认值与上下界。 */
 export declare const DREAM_LIMIT_DEFAULT = 50;
 export declare const DREAM_LIMIT_MIN = 1;
@@ -24,13 +26,16 @@ export interface DreamWebPayload {
     /** 本次生效的条数上限。 */
     limit: number;
 }
-/** 知识路由的统计形状（与 FREEZE §2 的 stats() 对齐）。 */
+/** 知识路由的统计形状（与 FREEZE §2 的 stats() 对齐；v1.1 R8 透传 badLines）。 */
 export interface KnowledgeWebStats {
     lessons: number;
     evidence: number;
     events: number;
     byState: Record<string, number>;
+    /** 有界回放被截断时为 true（面板据此显示提示行）。 */
     truncated?: boolean;
+    /** 事件 / 证据流中被跳过的坏行数（面板据此显示提示行）。 */
+    badLines: number;
 }
 /** 知识路由的 JSON 形状：脱敏后的经验 / 证据 / 统计。 */
 export interface KnowledgeWebPayload {
@@ -50,30 +55,75 @@ export interface KnowledgeReader {
     listEvidence(): Evidence[];
     stats(): KnowledgeWebStats;
 }
+/** 写入记录的单条视图（展示用；字段缺失时按空字符串 / false 归一化）。 */
+export interface BridgeWebLessonRef {
+    lessonId: string;
+    revision: number;
+}
+export interface BridgeWebRecord {
+    backupId: string;
+    at: string;
+    target: string;
+    action: string;
+    lessons: BridgeWebLessonRef[];
+    beforeSha256: string;
+    afterSha256: string;
+    rollbackable: boolean;
+    rollbackReason?: string;
+}
+/** 写入记录路由的 JSON 形状：脱敏后的应用记录 + 汇总。 */
+export interface BridgeWebPayload {
+    records: BridgeWebRecord[];
+    stats: {
+        total: number;
+        rollbackable: number;
+    };
+}
+/** 桥接存储层返回的原始记录形状（字段由 src/bridge.ts 负责）。 */
+export type BridgeApplicationView = Record<string, unknown>;
+/** 只读桥接记录源的最小接口：方便测试注入假数据。 */
+export interface BridgeReader {
+    listApplications(): BridgeApplicationView[];
+}
 /** 安装参数；journalDir 缺省时从 config 解析。 */
 export interface DreamWebOptions {
     /** 梦境日记目录（优先）。 */
     journalDir?: string;
     /** 知识目录（优先；缺省 = <journalDir>/knowledge）。 */
     knowledgeDir?: string;
+    /** 桥接记录目录（优先；缺省 = <journalDir>/bridge）。 */
+    bridgeDir?: string;
     /** 插件配置，用来兜底 journalDir（resolveConfig 的入参）。 */
     config?: Record<string, unknown> | ResolvedDreamConfig | null;
     /** 测试注入：返回只读知识源；提供时不做目录存在性检查。 */
     knowledgeStoreFactory?: (knowledgeDir: string) => KnowledgeReader;
+    /** 测试注入：返回只读桥接记录源；提供时不做目录存在性检查。 */
+    bridgeStoreFactory?: (bridgeDir: string) => BridgeReader;
 }
 /** ?limit 解析：缺省/非数字 → fallback；越界钳制到 [1, 500]。 */
 export declare function limitFromQuery(raw: unknown, fallback?: number): number;
 /** 解析后的 knowledgeDir：显式路径优先，否则 = <journalDir>/knowledge。 */
 export declare function knowledgeDirOf(options: DreamWebOptions, journalDir?: string): string;
+/** 解析后的 bridgeDir：显式路径优先，否则 = <journalDir>/bridge。 */
+export declare function bridgeDirOf(options: DreamWebOptions, journalDir?: string): string;
 /** 知识目录不存在（或尚未建立）时的空载荷：不写盘、不报 404。 */
 export declare function emptyKnowledgePayload(): KnowledgeWebPayload;
+/**
+ * 归一化桥接应用记录：只保留展示需要的字段，坏形状跳过。
+ * 数据源由 src/bridge.ts 负责（本层不做 IO、不重算可否回滚）。
+ */
+export declare function normalizeBridgeApplications(value: unknown): BridgeWebRecord[];
+/** 写入记录目录不存在时的空载荷。 */
+export declare function emptyBridgePayload(): BridgeWebPayload;
 /** 组装梦境日记路由处理器；journalDir 在这一刻定下来（与插件的配置生命周期一致）。 */
 export declare function createDreamWebHandler(options?: DreamWebOptions): (req: any, res: any) => Promise<void>;
+/** 组装只读写入记录路由处理器；零写盘：目录不存在就直接返回空结果。 */
+export declare function createBridgeWebHandler(options?: DreamWebOptions): (req: any, res: any) => Promise<void>;
 /** 组装只读经验路由处理器；零写盘：目录不存在就直接返回空结果。 */
 export declare function createKnowledgeWebHandler(options?: DreamWebOptions): (req: any, res: any) => Promise<void>;
 /**
  * 把只读路由挂到宿主 webserver 上。
  * 与 dsh-calendar 相同：ctx.inject(['webServer']) + effect 注册，插件卸载即摘掉路由；
- * 同一个 effect 里注册日记与知识两条 exact 路由，卸载时一起释放。
+ * 同一个 effect 里注册日记 / 知识 / 写入记录三条 exact 路由，卸载时一起释放。
  */
 export declare function installDreamWeb(ctx: any, options?: DreamWebOptions): void;

package/lib/web.js

@@ -6,25 +6,28 @@
  * 三道门缺一不可 ——
  *   1. remoteAddress 若是明确的非回环地址则拒绝（局域网不可达）；
  *   2. Host 头必须是 localhost 名（挡 DNS rebinding：恶意域名解析到 127.0.0.1）；
- *   3. 只接受 GET：两条路由都没有任何写路径，所以不需要 CSRF 那一套。
+ *   3. 只接受 GET：三条路由都没有任何写路径，所以不需要 CSRF 那一套。
  *
- * 零写盘纪律（M1）：知识路由只读 <journalDir>/knowledge/。目录不存在时直接返回
- * 空 lessons/evidence + 全零 stats，绝不为了读去 mkdir 或 rebuildIndex；重建索引
- * 只发生在写路径或显式维护操作里。
+ * 零写盘纪律（M1/M2）：知识路由只读 <journalDir>/knowledge/，写入记录路由只读
+ * <journalDir>/bridge/。目录不存在时直接返回空结果，绝不为了读去 mkdir 或 rebuildIndex；
+ * 重建索引只发生在写路径或显式维护操作里。
  *
  * @module dsh-dream/web
  */
 import { existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { isAbsolute, join, win32 } from 'node:path';
+import * as bridgeModule from './bridge.js';
 import { resolveConfig } from './config.js';
 import { dreamStats, readDreams, searchDreams } from './journal.js';
 import { KnowledgeStore } from './knowledge-store.js';
-import { maskSecrets } from './mask.js';
+import { isDreamReference, maskSecrets } from './mask.js';
 import { buildEvidenceSummary, lessonScopeLabel } from './retrieval.js';
 /** 面板与浏览器说话的同源路由。 */
 export const DREAM_ROUTE = '/_dsh/dsh-dream/journal';
 /** M1 经验面板的只读路由。 */
 export const DREAM_KNOWLEDGE_ROUTE = '/_dsh/dsh-dream/knowledge';
+/** M2 写入记录面板的只读路由。 */
+export const DREAM_BRIDGE_ROUTE = '/_dsh/dsh-dream/bridge';
 /** ?limit 的默认值与上下界。 */
 export const DREAM_LIMIT_DEFAULT = 50;
 export const DREAM_LIMIT_MIN = 1;
@@ -71,6 +74,12 @@ export function knowledgeDirOf(options, journalDir = journalDirOf(options)) {
         return options.knowledgeDir;
     return join(journalDir, 'knowledge');
 }
+/** 解析后的 bridgeDir：显式路径优先，否则 = <journalDir>/bridge。 */
+export function bridgeDirOf(options, journalDir = journalDirOf(options)) {
+    if (typeof options.bridgeDir === 'string' && options.bridgeDir.trim() !== '')
+        return options.bridgeDir;
+    return join(journalDir, 'bridge');
+}
 /** 解析请求 URL；非法或缺失时退回路由本身（等价于没有查询参数）。 */
 function requestUrl(raw, fallback = DREAM_ROUTE) {
     const text = typeof raw === 'string' && raw !== '' ? raw : fallback;
@@ -125,21 +134,33 @@ function requestGate(req, res, readOnlyMessage) {
     }
     return false;
 }
-/** 递归脱敏所有字符串叶子；数字 / 布尔 / null 原样保留。 */
-function maskDeep(value) {
-    if (typeof value === 'string')
+/** 哈希字段不做二次脱敏：它们是校验值，不是密钥（面板要展示前 12 位）。 */
+const HASH_KEY_RE = /^(?:sourceHash|beforeSha256|afterSha256|afterBlockSha256|afterFileSha256|sha256)$/;
+const REFERENCE_KEYS = new Set(['id', 'lessonId', 'lessonIds', 'evidenceIds', 'conflictIds', 'supersedes', 'targetId', 'affectedIds', 'backupId', 'previewId']);
+const PATH_KEYS = new Set(['target', 'path', 'resolvedPath', 'workspaceRoot']);
+/** 递归脱敏；结构化绝对路径按目录分段，避免 Unix 分隔符把正常路径连成长令牌。 */
+function maskDeep(value, key) {
+    if (typeof value === 'string') {
+        if (key !== undefined && HASH_KEY_RE.test(key) && /^[0-9a-f]{64}$/i.test(value))
+            return value;
+        if (key !== undefined && REFERENCE_KEYS.has(key) && isDreamReference(value))
+            return value;
+        if (key !== undefined && PATH_KEYS.has(key) && (isAbsolute(value) || win32.isAbsolute(value)) && !/[\x00-\x1f]/.test(value)) {
+            return value.split(/([\\/]+)/).map((part) => maskSecrets(part)).join('');
+        }
         return maskSecrets(value);
+    }
     if (Array.isArray(value))
-        return value.map((item) => maskDeep(item));
+        return value.map((item) => maskDeep(item, key));
     if (value !== null && typeof value === 'object') {
         const out = {};
-        for (const [key, item] of Object.entries(value))
-            out[key] = maskDeep(item);
+        for (const [entryKey, item] of Object.entries(value))
+            out[entryKey] = maskDeep(item, entryKey);
         return out;
     }
     return value;
 }
-/** 统计归一化：数字字段兜底为 0，byState 五个键齐全，truncated 只在为 true 时保留。 */
+/** 统计归一化：数字字段兜底为 0，byState 五个键齐全，truncated 只在为 true 时保留，badLines 始终透传。 */
 function normalizeKnowledgeStats(value) {
     const source = value !== null && typeof value === 'object' ? value : {};
     const rawByState = source.byState !== null && typeof source.byState === 'object'
@@ -159,6 +180,7 @@ function normalizeKnowledgeStats(value) {
         evidence: numberAt('evidence'),
         events: numberAt('events'),
         byState,
+        badLines: Math.floor(numberAt('badLines')),
     };
     if (source.truncated === true)
         stats.truncated = true;
@@ -172,6 +194,86 @@ export function emptyKnowledgePayload() {
         stats: normalizeKnowledgeStats(null),
     };
 }
+function asDisplayString(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+function asDisplayRevision(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? Math.floor(value) : 0;
+}
+/**
+ * 归一化桥接应用记录：只保留展示需要的字段，坏形状跳过。
+ * 数据源由 src/bridge.ts 负责（本层不做 IO、不重算可否回滚）。
+ */
+export function normalizeBridgeApplications(value) {
+    if (!Array.isArray(value))
+        return [];
+    const records = [];
+    for (const raw of value) {
+        if (raw === null || typeof raw !== 'object')
+            continue;
+        const item = raw;
+        const backupId = asDisplayString(item.backupId);
+        const target = asDisplayString(item.target);
+        if (backupId === '' && target === '')
+            continue;
+        const lessons = [];
+        if (Array.isArray(item.lessons)) {
+            for (const entry of item.lessons) {
+                if (entry !== null && typeof entry === 'object') {
+                    const ref = entry;
+                    const lessonId = asDisplayString(ref.lessonId);
+                    if (lessonId === '')
+                        continue;
+                    lessons.push({ lessonId, revision: asDisplayRevision(ref.revision) });
+                }
+                else {
+                    const text = asDisplayString(entry);
+                    if (text === '')
+                        continue;
+                    const match = /^(.*)@(\d+)$/.exec(text);
+                    if (match !== null)
+                        lessons.push({ lessonId: match[1], revision: Number(match[2]) });
+                    else
+                        lessons.push({ lessonId: text, revision: 0 });
+                }
+            }
+        }
+        const record = {
+            backupId,
+            at: asDisplayString(item.at),
+            target,
+            action: asDisplayString(item.action),
+            lessons,
+            beforeSha256: asDisplayString(item.beforeSha256),
+            afterSha256: asDisplayString(item.afterSha256),
+            rollbackable: item.rollbackable === true,
+        };
+        const reason = asDisplayString(item.rollbackReason);
+        if (reason !== '')
+            record.rollbackReason = reason;
+        records.push(record);
+    }
+    return records;
+}
+/** 写入记录目录不存在时的空载荷。 */
+export function emptyBridgePayload() {
+    return {
+        records: [],
+        stats: { total: 0, rollbackable: 0 },
+    };
+}
+/**
+ * 从桥接存储层取原始记录（按 at 降序，只读零写盘）。
+ * 契约来源：M2-A，`listBridgeApplications(journalDir): BridgeApplicationView[]`；
+ * 未落地 / 未导出时安全返回空，路由不受影响。
+ */
+function readBridgeApplicationsFromStore(journalDir) {
+    const candidate = bridgeModule.listBridgeApplications;
+    if (typeof candidate !== 'function')
+        return [];
+    const result = candidate(journalDir);
+    return Array.isArray(result) ? result : [];
+}
 /** 组装梦境日记路由处理器；journalDir 在这一刻定下来（与插件的配置生命周期一致）。 */
 export function createDreamWebHandler(options = {}) {
     const journalDir = journalDirOf(options);
@@ -191,6 +293,39 @@ export function createDreamWebHandler(options = {}) {
         }
     };
 }
+/** 组装只读写入记录路由处理器；零写盘：目录不存在就直接返回空结果。 */
+export function createBridgeWebHandler(options = {}) {
+    const journalDir = journalDirOf(options);
+    const bridgeDir = bridgeDirOf(options, journalDir);
+    return async (req, res) => {
+        if (requestGate(req, res, 'dsh-dream bridge route is read-only; use GET'))
+            return;
+        try {
+            let raw;
+            if (options.bridgeStoreFactory !== undefined) {
+                raw = options.bridgeStoreFactory(bridgeDir).listApplications();
+            }
+            else if (existsSync(bridgeDir)) {
+                raw = readBridgeApplicationsFromStore(journalDir);
+            }
+            else {
+                raw = [];
+            }
+            const records = normalizeBridgeApplications(raw).map((record) => maskDeep(record));
+            const payload = {
+                records,
+                stats: {
+                    total: records.length,
+                    rollbackable: records.filter((record) => record.rollbackable).length,
+                },
+            };
+            responseJson(res, 200, payload);
+        }
+        catch (error) {
+            internalError(res, error);
+        }
+    };
+}
 /** 组装只读经验路由处理器；零写盘：目录不存在就直接返回空结果。 */
 export function createKnowledgeWebHandler(options = {}) {
     const knowledgeDir = knowledgeDirOf(options);
@@ -227,7 +362,7 @@ export function createKnowledgeWebHandler(options = {}) {
 /**
  * 把只读路由挂到宿主 webserver 上。
  * 与 dsh-calendar 相同：ctx.inject(['webServer']) + effect 注册，插件卸载即摘掉路由；
- * 同一个 effect 里注册日记与知识两条 exact 路由，卸载时一起释放。
+ * 同一个 effect 里注册日记 / 知识 / 写入记录三条 exact 路由，卸载时一起释放。
  */
 export function installDreamWeb(ctx, options = {}) {
     if (ctx === null || ctx === undefined || typeof ctx.inject !== 'function') {
@@ -235,6 +370,7 @@ export function installDreamWeb(ctx, options = {}) {
     }
     const journalHandler = createDreamWebHandler(options);
     const knowledgeHandler = createKnowledgeWebHandler(options);
+    const bridgeHandler = createBridgeWebHandler(options);
     ctx.inject(['webServer'], (webCtx) => {
         webCtx.effect(() => {
             const disposers = [
@@ -248,6 +384,11 @@ export function installDreamWeb(ctx, options = {}) {
                     path: DREAM_KNOWLEDGE_ROUTE,
                     handler: (req, res) => knowledgeHandler(req, res),
                 }, 'dsh-dream: knowledge route'),
+                webCtx.webServer.register({
+                    kind: 'exact',
+                    path: DREAM_BRIDGE_ROUTE,
+                    handler: (req, res) => bridgeHandler(req, res),
+                }, 'dsh-dream: bridge log route'),
             ];
             return () => {
                 for (const dispose of disposers) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stardustlc/dsh-dream",
-  "version": "0.5.0",
-  "description": "DSH 做梦插件：会话间隙回放近期对话、反思写入梦境日记，并把高频教训幂等桥接进 AGENTS.md；默认隐私脱敏，零运行时依赖。",
+  "version": "0.6.0",
+  "description": "DSH 做梦与经验记忆：核验来源、审阅经验，预览写入 AGENTS.md 并支持回滚；附梦境日记面板，默认隐私脱敏，零运行时依赖。",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/skills/dream-protocol/SKILL.md

@@ -20,10 +20,10 @@ description: 做梦协议：任务开始取回适用经验，长任务收尾沉
 
 ## 一、任务前：取回上下文（dream_context）
 
-- 任务涉及过往代码、用户偏好或踩过的坑时，先调 `dream_context`：给 `query`，能给就给 `projectId` / `workspaceRoot` / `packageVersion`。
+- 任务涉及过往代码、用户偏好或踩过的坑时，先调 `dream_context`：给 `query`，能给就给 `projectId` / `workspaceRoot`，以及 `packageName` + `packageVersion`（`applicability.versions` 只在该包名被识别时参与判定）。审阅候选时显式传 `includeCandidates: true`。
 - **预算：默认 5 条 / 3000 字符**（工具硬上限 20 条 / 20000 字符）。取回少量真正适用的即可；没有相关经验就接受空结果，不要为了「显得有记忆」硬塞。
 - `dream_context` 是只读的：不写盘，只返回标题、适用条件、行动建议、证据摘要与「为什么与当前任务相关」。
-- 未知当前项目时只会返回全局经验；不会跨项目扫描。候选（candidate）默认不作为任务建议注入。
+- 未知当前项目时只会返回全局经验；不会跨项目扫描。候选（candidate）**可被检索到**（显式 `includeCandidates: true`，用于审阅候选），但**默认不注入任务建议**（`includeCandidates: false` 时记 `skipped: candidate-hold`；`independentSupportCount === 0` 且非 `usable` 的记 `no-evidence`），且排在可用经验之后——未经审阅不得当作已证实结论。
 
 ## 二、任务中：先把真实任务做完
 
@@ -38,7 +38,9 @@ description: 做梦协议：任务开始取回适用经验，长任务收尾沉
   - 能定位就填 `sessionId` / `recordSeq`；
   - `summary` 只写脱敏后的一句话，不搬原文；
   - `verification`：`read` = 你或插件读到了原记录；`claimed` = 仅模型声称。**claimed 只计入证据列表，不计入独立支持数。**
+- **只有真的读到来源（会话记录 / 本地验证产物 / 用户明确纠正）才能标 read，自我判断一律 claimed**（"我记得""应该是"都算 claimed）；标错 read 等于自我提权，禁止。
 - 没有证据的观察只能是 candidate，不能写成确定事实，也不能说成「已验证」。
+- 所有新经验都先进入 candidate，包括已读到的用户纠正。read 只表示插件成功核对来源，不表示用户采纳；工具审阅记录 actor:model，不能冒充真人。会话证据须给 sessionId、recordSeq、可匹配 quote（缺省使用 summary）；本地产物须给工作目录内的 artifactPath。插件独立核对项目、角色和原文，计算 sourceHash；失败降为 claimed 并给 verificationReason。
 - 用户明确采纳/驳回、发现经验互相冲突、依赖升级后旧经验需要复核 → 用 `dream_review`（必须带 `expectedRevision`）。
 - 用户采纳必须来自真实用户指令；模型自己不能冒充 `actor: user`。
 - 同一证据重复提交是幂等的，不会增加独立支持数。**禁止靠反复调用 `dream_save` 或 `dream_learn` 刷次数**——次数不等于正确，也不等于重要。
@@ -47,7 +49,8 @@ description: 做梦协议：任务开始取回适用经验，长任务收尾沉
 
 - 只沉淀规律与偏好，不复述流水账；`reflection` 用第一人称写你的观察与感受；
 - `lessons` 是 1–5 条可执行教训，每条以动词开头；拿不准就标注「存疑」；
-- **不得把主观反思升级成 AGENTS.md 指令**：不要用 `dream_bridge` 把未经审阅的感悟写成项目规则。桥接只能用于已采纳、当前项目范围、附证据的经验。
+- **不得把主观反思升级成 AGENTS.md 指令**：不要用 `dream_bridge` 把未经审阅的感悟写成项目规则。桥接只能用于 `usable`、当前项目范围（或显式 global 且 review.decision 为 accepted）、附证据的经验；频次不再作为准入条件。
+- **桥接三步（M2）**：`mode:"preview"` 只读返回 diff / 参与经验 / skipped 原因（零写入）→ 人工复核 → `mode:"apply"` 必须带预览的 `expectedSha256`（新文件为 null），建议同时带 `previewId`（文件被并发修改则 `conflict` 且零写入）；`mode:"rollback"` 只在当前管理块仍等于该次 apply 结果时回滚。缺省不传 `mode` 仍是 0.5.x 直写并返回弃用提示；新流程一律显式 preview → apply。写入内容统一过 `mask.ts`。
 
 ## 何时做梦
 
@@ -60,6 +63,8 @@ description: 做梦协议：任务开始取回适用经验，长任务收尾沉
 - 想在日记里找原话 → `dream_recall`；
 - 想取少量可复用经验 → `dream_context`（带范围与预算，只读）；
 - 想查看/审阅候选、处理冲突 → `dream_review`；
+- attach-evidence 只补充核验后的证据，不自动采纳；resolve-conflict 必须给 resolution、affectedIds、note，整组原子更新；reopen 将驳回经验重新送审。
+
 - 面板查看：「设置 → 梦境日记」里有只读的梦境时间线与「经验」区块（状态、适用条件、证据摘要、最近核验时间），面板不提供任何写操作。
 
 ---
@@ -81,10 +86,10 @@ Dreams and **lessons** are two separate pipelines: a **first-person reflection**
 
 ## 1. Before the task: retrieve context (dream_context)
 
-- When a task touches past code, user preferences or known pitfalls, call `dream_context` first with `query`, plus `projectId` / `workspaceRoot` / `packageVersion` when available.
+- When a task touches past code, user preferences or known pitfalls, call `dream_context` first with `query`, plus `projectId` / `workspaceRoot` and `packageName` + `packageVersion` when available (`applicability.versions` only counts when that package is identified). Pass `includeCandidates: true` explicitly when reviewing candidates.
 - **Budget: 5 items / 3000 characters by default** (hard caps 20 items / 20000 characters). Take only what is relevant; an empty result is acceptable — never stuff memories in to look useful.
 - `dream_context` is read-only: it writes nothing and returns title, applicability, action, evidence summary and why it is relevant.
-- With an unknown project it returns global lessons only; it never scans across projects. Candidates are not injected as task advice by default.
+- With an unknown project it returns global lessons only and never scans across projects. Candidates **can be retrieved** (`includeCandidates: true`, for candidate review) but are **held out of default task advice** (`includeCandidates: false` reports `skipped: candidate-hold`; evidence-free non-usable items report `no-evidence`), and they rank after usable lessons — never treat one as a verified conclusion before review.
 
 ## 2. During the task: do the real work first
 
@@ -99,7 +104,9 @@ Dreams and **lessons** are two separate pipelines: a **first-person reflection**
   - fill `sessionId` / `recordSeq` when the source can be located;
   - keep `summary` to one masked sentence — never copy the raw record;
   - `verification`: `read` = the record was actually read; `claimed` = the model merely asserts it. **Claimed evidence does not count toward independent support.**
+- **Only mark read when the source was actually read (session record / local artifact / explicit user correction); anything self-asserted is claimed.** Marking read without a source is self-promotion and is forbidden.
 - An observation without evidence stays a candidate: do not present it as a fact, and never call it "verified".
+- Every new lesson starts as a candidate, including verified user corrections. Read means the plugin checked the source, not that a user accepted the lesson; tool review records actor:model. Session evidence needs sessionId, recordSeq and a matching quote (summary if omitted). Artifacts need artifactPath inside the working directory. The plugin checks project, role and text and computes sourceHash; failures become claimed with verificationReason.
 - For explicit acceptance/rejection, conflicts between lessons, or re-validation after dependency upgrades → call `dream_review` with an `expectedRevision`.
 - User acceptance must come from a real user instruction; the model must not impersonate `actor: user`.
 - Submitting the same evidence twice is idempotent and does not increase independent support. **Never grind counts by calling `dream_save` or `dream_learn` repeatedly** — frequency is neither correctness nor importance.
@@ -108,7 +115,8 @@ Dreams and **lessons** are two separate pipelines: a **first-person reflection**
 
 - Consolidate patterns and preferences only — never a running transcript. Write `reflection` in the first person.
 - `lessons` are 1–5 actionable items; mark uncertain ones as "tentative".
-- **Never promote a subjective reflection into an AGENTS.md instruction**: do not use `dream_bridge` to write unreviewed reflections into project rules. Bridging is for accepted, project-scoped, evidence-backed lessons only.
+- **Never promote a subjective reflection into an AGENTS.md instruction**: do not use `dream_bridge` to write unreviewed reflections into project rules. Bridging is for `usable`, project-scoped (or explicit global with review.decision accepted), evidence-backed lessons only; frequency is no longer an admission criterion.
+- **Bridge in three steps (M2)**: `mode:"preview"` returns the diff / selected lessons / skipped reasons read-only (zero writes) → human review → `mode:"apply"` with the preview’s required `expectedSha256` (null for a new file); include `previewId` to bind the preview (a concurrent edit yields `conflict` and zero writes); `mode:"rollback"` only rolls back while the current managed block still equals that apply result. Omitting `mode` keeps the 0.5.x direct write and returns a deprecation notice; new flows should always use preview → apply. Everything written is masked via `mask.ts`.
 
 ## When to dream
 
@@ -121,4 +129,5 @@ Dreams and **lessons** are two separate pipelines: a **first-person reflection**
 - Looking for exact words in the journal → `dream_recall`;
 - Retrieving a few reusable lessons → `dream_context` (scoped, budgeted, read-only);
 - Browsing or reviewing candidates and conflicts → `dream_review`;
+- attach-evidence adds verified sources without promoting state. resolve-conflict requires resolution, affectedIds and note and updates the group atomically. reopen sends a rejected lesson back for review.
 - To browse: **Settings → Dream journal** shows the read-only dream timeline and a **Lessons** block (state, applicability, evidence summary, last validated time). The panel has no write actions.