fluffy-context 0.5.0 → 0.6.0

package/README.md

@@ -4,7 +4,20 @@
 
 Git 仍然负责代码和真实文件变更，Issue 系统仍然负责任务，项目文档仍然负责设计；`fluffy-context` 补齐的是持续演进的项目认知层。最终架构是 `project → knowledge runtime → LLM`：CLI、MCP、Claude Hook 和未来 IDE/Agent 集成只是事件入口与信息注入适配器，而不是认知本体。
 
-0.5.0 在 v2 迁移、可验证事件日志、确定性投影和按项目 Runtime 基础上，完成首个 branch-aware 注入闭环：迁移并启用 Runtime 后，Orient、MCP 与 Claude Hook 会按当前 worktree/ref 选择 Context，避免跨分支任务状态泄漏。v1 的 checkpoint、Note、Knowledge 与 Deadend 写入会最佳努力镜像为 v2 事件；Runtime 也会协调检测到的外部 v1 变更。自动产物默认仍仅进入 Candidate，Verified Knowledge 仍需治理确认。
+0.6.0 在 branch-aware 注入闭环上补齐了可治理的确定性检索：迁移并启用 Runtime 后，Orient 从 v2 journal 的可重建索引检索已验证、适用的 Knowledge 与 Deadend，并返回有界的选择、排除与截断说明。v1 的 checkpoint、Note、Knowledge 与 Deadend 写入仍会最佳努力镜像为 v2 事件；Runtime 也会协调检测到的外部 v1 变更。自动产物默认仍仅进入 Candidate，Verified Knowledge 仍需治理确认。
+
+## 版本演进
+
+| 版本 | 主要能力 | 关键特点 |
+| --- | --- | --- |
+| 0.1.0 | 本地 Context CLI、baseline/patch Snapshot、resume、Note、Candidate Knowledge/Deadend | Git 继续作为代码权威；Context 只保存有界任务状态，不复制项目文件；checkpoint 显式触发且支持 no-op、限流与敏感路径过滤。 |
+| 0.2.0 | 确定性 Knowledge Discovery、Agent TypeScript API、可安装 Skill | Candidate 与 Verified 分离；默认只注入已验证共识；不依赖向量库、模型或远端服务。 |
+| 0.3.x | MCP `context_orient`、Claude Code Hook 与集成配置生成 | 通过 stdio MCP 和 fail-open Hook 降低 Agent 主动调用成本；集成安装仅在 `--apply` 时写入项目配置。 |
+| 0.4.0 | v2 事件 journal、v1 显式迁移、可重建投影、本地 Runtime、Git 观察 | v2 与 v1 并存；NDJSON hash chain 是 v2 权威；Runtime 仅监听 loopback 并记录分支、ref 与 HEAD 元数据。 |
+| 0.5.0 | branch-aware Orient、v1 写入镜像、Runtime 协调、宿主事件捕获 | Context 按当前 worktree/ref 选择，避免跨分支任务状态泄漏；稳定宿主 ID 才会写入限长、脱敏后的 session/prompt intent。 |
+| 0.6.0 | journal 派生的确定性检索、治理终态、可解释 Orient、显式使用反馈 | 启用 v2 后直接从可重建索引检索已验证且适用的共识；使用反馈只影响稳定排序，绝不自动验证或提升 Candidate。 |
+
+所有版本均保持本地优先、显式治理与 fail-open 集成原则。v1 数据不会在迁移过程中被重写；当 v2 未启用、不可用、损坏或尚未同步时，读取接口会回退到兼容的 v1 行为。
 
 ## 适用场景
 
@@ -93,7 +106,11 @@ ctx note add "测试环境缺少回调凭据" --kind problem --context <context-
 ctx activity --context <context-id> --open
 ctx knowledge discover "支付回调"
 ctx knowledge verify <knowledge-id>
+ctx knowledge deprecate <knowledge-id> --reason "已被新的结论取代"
 ctx deadend verify <deadend-id>
+ctx deadend obsolete <deadend-id> --reason "当前架构已不再适用"
+ctx feedback use knowledge <knowledge-id> --event-id <stable-id>
+ctx journal verify
 ctx migrate v1 --dry-run
 ctx migrate v1 --apply
 ctx migrate verify
@@ -127,7 +144,7 @@ ctx runtime disable
 
 Runtime 是单项目、按需启动的本地守护进程。它只绑定 `127.0.0.1` 的动态端口，并要求存储在项目本地 `.context/v2/runtime/secret` 中的能力令牌；令牌不会显示在 CLI 状态输出或写入事件日志。启动后，Runtime 持续观察当前 worktree 的 Git 状态：初始状态会记录 `git.state.observed`，分支/ref 切换记录 `git.branch.changed`，HEAD 更新记录 `git.head.changed`。这些事件会重建 branch workspace 投影，但不会自动创建 checkpoint 或将候选信息提升为已验证共识。
 
-完成迁移并显式 `ctx runtime enable` 后，`ctx orient`、MCP `context_orient` 与 Claude Hook 会优先选择当前 worktree/ref 的 v2 workspace；它不会借用其他分支的 Context。没有匹配 workspace、v2 状态不可用或 Runtime 已禁用时，接口会安全回退到既有 v1 选择逻辑。Runtime 停止时仍可读取已验证的 v2 状态，但运行中的 Runtime 负责持续 Git 观察和 v1 写入镜像。
+完成迁移并显式 `ctx runtime enable` 后，`ctx orient`、MCP `context_orient` 与 Claude Hook 会优先选择当前 worktree/ref 的 v2 workspace；它不会借用其他分支的 Context。v2 可用时，Knowledge 与 Deadend 由 journal 重放出的确定性倒排索引直接检索，默认仅返回已验证且适用的记录；无匹配 workspace、v2 状态不可用、journal 损坏、v1 尚未同步或 Runtime 已禁用时，接口会安全回退到既有 v1 选择逻辑。Runtime 停止时仍可读取已验证的 v2 状态，但运行中的 Runtime 负责持续 Git 观察和 v1 写入镜像。
 
 Claude Hook 仅在宿主提供稳定的 session 与 event 标识时记录 `host.session.started` 或 `host.prompt.submitted`。提示只保存按 `promptIntentMaxChars` 截断并经过敏感值脱敏后的 intent，绝不保存原始提示；缺少稳定标识时不写入事件。默认 Hook 不启动守护进程；将 v2 policy 的 `allowHookStartup` 设为 `true` 后，SessionStart 才会在严格超时内尽力启动 Runtime，失败仍会 fail open。UserPromptSubmit 不会启动 Runtime。
 
@@ -141,7 +158,11 @@ Claude Hook 仅在宿主提供稳定的 session 与 event 标识时记录 `host.
 
 ### Knowledge 与 Deadend
 
-`ctx learn` 和 `ctx deadend` 默认创建 `candidate` 项。普通发现与 `ctx orient` 只使用已验证项目共识；候选项需要通过 `ctx knowledge verify` 或 `ctx deadend verify` 显式确认，或以 `--all` 审查。
+`ctx learn` 和 `ctx deadend` 默认创建 `candidate` 项。普通发现与 `ctx orient` 只使用已验证项目共识；候选项需要通过 `ctx knowledge verify` 或 `ctx deadend verify` 显式确认，或以 `--all` 审查。验证后的 Knowledge 可用 `ctx knowledge deprecate` 退役，候选项可用 `ctx knowledge reject` 拒绝；验证后的 Deadend 可用 `ctx deadend obsolete` 退役，候选项可用 `ctx deadend reject` 拒绝。终态记录保留证据与治理原因，但不会被默认注入。
+
+新记录默认具有 `global` 适用性。需要限制到当前 worktree/ref 时，可使用 `--branch-mode exact`；`--paths` 只保存精确项目相对路径约束，当前版本不会推断目录前缀、Git 祖先关系、依赖关系或语义相似路径。`ctx orient` 的 `explanation` 字段会有界地给出 v2/v1 选择方式、排除计数和各类别截断原因。
+
+`ctx feedback use knowledge|deadend ... --event-id <stable-id>` 只记录一个幂等的 v2 使用信号。它只作为同等词法相关性结果的确定性排序因素，永不改变验证状态、confidence、evidence 或适用性；Orient、MCP 与 Hook 不会隐式写入该信号。
 
 ```bash
 ctx learn "订单取消后不能再次进入支付中状态" --scope project
@@ -222,6 +243,6 @@ npm pack --dry-run --json
 
 ## 当前范围
 
-0.5.0 聚焦单项目、本地优先的 branch-aware Knowledge Runtime MVP：有界 Orient、显式 checkpoint、确定性 Knowledge/Deadend discovery、MCP `context_orient`、可选 Claude Code Hook，以及 v1 到 v2 的显式事件日志迁移和 Git-aware 本地 Runtime。完成迁移并启用 Runtime 后，Orient、MCP 与 Hook 使用当前 worktree/ref 的 workspace 选择分支正确的 Context，并在 v2 不可用时保持 v1 回退；Runtime 负责可靠捕获生命周期、Git 元数据与后续 v1 写入镜像。带稳定宿主标识的 Hook 事件仅以脱敏、限长 intent 进入 journal。
+0.6.0 聚焦单项目、本地优先、可治理的 branch-aware Knowledge Runtime MVP：有界且可解释的 Orient、显式 checkpoint、journal 派生的确定性 Knowledge/Deadend 检索、终态治理、显式使用反馈、MCP `context_orient`、可选 Claude Code Hook，以及 v1 到 v2 的显式事件日志迁移和 Git-aware 本地 Runtime。完成迁移并启用 Runtime 后，Orient、MCP 与 Hook 使用当前 worktree/ref 的 workspace 选择分支正确的 Context，并在 v2 不可用时保持 v1 回退；Runtime 负责可靠捕获生命周期、Git 元数据与后续 v1 写入镜像。带稳定宿主标识的 Hook 事件仅以脱敏、限长 intent 进入 journal。
 
 远程同步、多人协作、复杂语义检索、自动模型总结、自动 checkpoint、Context merge、自动验证候选共识，以及更多状态变更型 MCP 工具不属于当前版本范围。

package/dist/src/agent/api.d.ts

@@ -1,8 +1,12 @@
 import type { AgentLoadOptions, AgentLoadResult, AgentSaveResult, CheckpointInput, ContextSearchOptions, ContextSearchResult } from '../runtime/types.js';
-import type { ContextOrientOptions, ContextOrientResult } from './types.js';
+import type { ContextOrientOptions, ContextOrientResult, ContextUseInput } from './types.js';
 export declare function saveContext(startPath: string | undefined, input: CheckpointInput, options?: {
     minSaveIntervalMs?: number;
 }): Promise<AgentSaveResult>;
 export declare function loadContext(startPath: string | undefined, options?: AgentLoadOptions): Promise<AgentLoadResult>;
 export declare function contextOrient(startPath: string | undefined, options?: ContextOrientOptions): Promise<ContextOrientResult>;
+export declare function recordContextUse(startPath: string | undefined, input: ContextUseInput): Promise<{
+    recorded: boolean;
+    eventId: string;
+}>;
 export declare function searchContext(startPath: string | undefined, query: string, options?: ContextSearchOptions): Promise<ContextSearchResult>;

package/dist/src/agent/api.js

@@ -3,7 +3,9 @@ import { resolveProjectRoot } from '../project/project-resolver.js';
 import { contextsRoot, contextMetadataPath } from '../storage/layout.js';
 import { isRecord, readJson } from '../storage/json-store.js';
 import { checkpoint, rebuildSnapshot, resume, resumeSnapshot } from '../runtime/runtime.js';
+import { recordUse } from '../cognition/feedback.js';
 import { selectV2Orientation } from '../cognition/orient.js';
+import { discoverV2Deadends, discoverV2Knowledge } from '../cognition/retrieval.js';
 import { discoverDeadends, discoverKnowledge, listDeadends } from '../runtime/knowledge.js';
 import { listNotes } from '../runtime/notes.js';
 function normalized(value) {
@@ -176,6 +178,12 @@ export async function contextOrient(startPath, options = {}) {
                 deadends: emptyDeadends(query ?? ''),
                 notes: [],
                 truncated: false,
+                explanation: {
+                    mode: 'v1-fallback',
+                    selection: 'v1',
+                    retrieval: { knowledge: {}, deadends: {} },
+                    truncation: { summary: false, knowledge: false, deadends: false, notes: false },
+                },
             };
         }
         throw error;
@@ -187,26 +195,30 @@ export async function contextOrient(startPath, options = {}) {
         limit: v2 ? Number.MAX_SAFE_INTEGER : options.noteLimit ?? 20,
         maxChars: options.maxChars ?? 4000,
     })).filter((note) => !v2 || v2.noteIds.has(note.noteId)).slice(0, options.noteLimit ?? 20);
-    const knowledge = query === null
+    const v2Knowledge = query === null || !v2 ? null : discoverV2Knowledge(v2.retrieval, query, v2.currentGit, {
+        scope: options.scope,
+        limit: options.knowledgeLimit ?? 10,
+        maxChars: options.maxChars ?? 4000,
+    });
+    const v2Deadends = query === null || !v2 ? null : discoverV2Deadends(v2.retrieval, query, v2.currentGit, {
+        scope: options.scope,
+        limit: options.deadendLimit ?? 10,
+        maxChars: options.maxChars ?? 4000,
+    });
+    const applicableKnowledge = query === null
         ? emptyKnowledge('')
-        : await discoverKnowledge(projectRoot, query, {
+        : v2Knowledge?.result ?? await discoverKnowledge(projectRoot, query, {
             scope: options.scope,
-            limit: v2 ? Number.MAX_SAFE_INTEGER : options.knowledgeLimit ?? 10,
+            limit: options.knowledgeLimit ?? 10,
             maxChars: options.maxChars ?? 4000,
         });
-    const deadends = query === null
+    const applicableDeadends = query === null
         ? emptyDeadends('')
-        : await discoverDeadends(projectRoot, query, {
+        : v2Deadends?.result ?? await discoverDeadends(projectRoot, query, {
             scope: options.scope,
-            limit: v2 ? Number.MAX_SAFE_INTEGER : options.deadendLimit ?? 10,
+            limit: options.deadendLimit ?? 10,
             maxChars: options.maxChars ?? 4000,
         });
-    const applicableKnowledge = v2
-        ? { ...knowledge, total: knowledge.hits.filter((hit) => v2.knowledgeIds.has(hit.knowledge.knowledgeId)).length, hits: knowledge.hits.filter((hit) => v2.knowledgeIds.has(hit.knowledge.knowledgeId)).slice(0, options.knowledgeLimit ?? 10) }
-        : knowledge;
-    const applicableDeadends = v2
-        ? { ...deadends, total: deadends.hits.filter((hit) => v2.deadendIds.has(hit.deadend.deadendId)).length, hits: deadends.hits.filter((hit) => v2.deadendIds.has(hit.deadend.deadendId)).slice(0, options.deadendLimit ?? 10) }
-        : deadends;
     const budget = { remaining: Math.max(0, options.maxChars ?? 4000) };
     const resumeSummary = {
         progressSummary: limited(loaded.resumeSummary.progressSummary, budget),
@@ -252,8 +264,25 @@ export async function contextOrient(startPath, options = {}) {
         deadends: limitedDeadendResult.result,
         notes: limitedNotesResult.notes,
         truncated: resumeTruncated || limitedKnowledgeResult.truncated || limitedDeadendResult.truncated || limitedNotesResult.truncated,
+        explanation: {
+            mode: v2 ? 'v2' : 'v1-fallback',
+            selection: v2?.selection ?? 'v1',
+            retrieval: {
+                knowledge: v2Knowledge?.exclusions ?? {},
+                deadends: v2Deadends?.exclusions ?? {},
+            },
+            truncation: {
+                summary: resumeTruncated,
+                knowledge: limitedKnowledgeResult.truncated,
+                deadends: limitedDeadendResult.truncated,
+                notes: limitedNotesResult.truncated,
+            },
+        },
     };
 }
+export async function recordContextUse(startPath, input) {
+    return recordUse(startPath, input);
+}
 export async function searchContext(startPath, query, options = {}) {
     const projectRoot = await resolveProjectRoot(startPath);
     const cleanQuery = query.trim();

package/dist/src/agent/index.d.ts

@@ -1,3 +1,3 @@
 export * from './api.js';
-export type { ContextOrientContext, ContextOrientNoContextResult, ContextOrientOptions, ContextOrientReadyResult, ContextOrientResult, ContextOrientSnapshot, } from './types.js';
+export type { ContextOrientContext, ContextUseInput, ContextOrientExplanation, ContextOrientNoContextResult, ContextOrientOptions, ContextOrientReadyResult, ContextOrientResult, ContextOrientSnapshot, } from './types.js';
 export type { AgentLoadOptions, AgentLoadResult, AgentSaveResult, ContextSearchHit, ContextSearchOptions, ContextSearchResult, } from '../runtime/types.js';

package/dist/src/agent/types.d.ts

@@ -23,6 +23,25 @@ export interface ContextOrientSnapshot {
     branch: string | null;
     commit: string | null;
 }
+export interface ContextUseInput {
+    entity: 'knowledge' | 'deadend';
+    entityId: string;
+    eventId: string;
+}
+export interface ContextOrientExplanation {
+    mode: 'v2' | 'v1-fallback';
+    selection: 'requested-context' | 'exact-worktree-ref' | 'legacy-ref-branch' | 'v1';
+    retrieval: {
+        knowledge: Record<'status_not_verified' | 'applicability_mismatch' | 'scope_mismatch' | 'query_no_match' | 'result_limit', number> | {};
+        deadends: Record<'status_not_verified' | 'applicability_mismatch' | 'scope_mismatch' | 'query_no_match' | 'result_limit', number> | {};
+    };
+    truncation: {
+        summary: boolean;
+        knowledge: boolean;
+        deadends: boolean;
+        notes: boolean;
+    };
+}
 export interface ContextOrientReadyResult {
     status: 'ready';
     projectRoot: string;
@@ -34,6 +53,7 @@ export interface ContextOrientReadyResult {
     deadends: DeadendDiscoveryResult;
     notes: Note[];
     truncated: boolean;
+    explanation: ContextOrientExplanation;
 }
 export interface ContextOrientNoContextResult {
     status: 'no_context';
@@ -46,5 +66,6 @@ export interface ContextOrientNoContextResult {
     deadends: DeadendDiscoveryResult;
     notes: Note[];
     truncated: false;
+    explanation: ContextOrientExplanation;
 }
 export type ContextOrientResult = ContextOrientReadyResult | ContextOrientNoContextResult;

package/dist/src/cli/main.js

@@ -2,13 +2,17 @@
 import { checkpoint, resume } from '../runtime/runtime.js';
 import { contextOrient } from '../agent/api.js';
 import { importV1, verifyV1Import } from '../cognition/migration-v1.js';
+import { recordUse } from '../cognition/feedback.js';
+import { readJournal } from '../cognition/journal.js';
+import { projectEvents } from '../cognition/projections.js';
 import { disableRuntime, enableRuntime, runtimeStatus, serveRuntime, startRuntime, stopRuntime } from '../cognition/runtime.js';
 import { migrationReadiness } from '../cognition/readiness.js';
 import { runClaudeCodeHook } from '../hooks/claude-code.js';
+import { readGitWorktreeState } from '../git/git-adapter.js';
 import { inspectClaudeIntegration, installClaudeIntegration } from '../integrations/claude-code.js';
 import { doctor, status } from '../runtime/diagnostics.js';
 import { initProject } from '../runtime/init.js';
-import { discoverKnowledge, learnKnowledge, listKnowledge, verifyKnowledge, recordDeadend, listDeadends, verifyDeadend } from '../runtime/knowledge.js';
+import { discoverKnowledge, learnKnowledge, listKnowledge, verifyKnowledge, recordDeadend, listDeadends, verifyDeadend, transitionKnowledge, transitionDeadend } from '../runtime/knowledge.js';
 import { addNote, listActivity, listNotes } from '../runtime/notes.js';
 import { VERSION } from '../version.js';
 function option(args, name) {
@@ -158,16 +162,23 @@ Options:
   --evidence <items>     Comma-separated evidence references`,
     knowledge: `usage: ctx knowledge [--all] [--path <path>]
        ctx knowledge verify <knowledge-id> [--path <path>]
+       ctx knowledge deprecate|reject <knowledge-id> --reason <text> [--path <path>]
        ctx knowledge discover <query> [options]
 
-List candidate/verified knowledge, verify one item, or discover matching knowledge.
+List, govern, or discover project knowledge.
 
 Options:
   --all                  Include unverified items
   --path <path>          Project path`,
     'knowledge verify': `usage: ctx knowledge verify <knowledge-id> [--path <path>]
 
-Mark a knowledge item as verified.`,
+Mark a candidate knowledge item as verified.`,
+    'knowledge deprecate': `usage: ctx knowledge deprecate <knowledge-id> --reason <text> [--path <path>]
+
+Retire a verified knowledge item with an explicit governance reason.`,
+    'knowledge reject': `usage: ctx knowledge reject <knowledge-id> --reason <text> [--path <path>]
+
+Reject a candidate knowledge item with an explicit governance reason.`,
     'knowledge discover': `usage: ctx knowledge discover <query> [options]
 
 Find matching project knowledge using deterministic lexical and alias rules.
@@ -181,8 +192,9 @@ Options:
   --max-chars <number>   Maximum text characters per match`,
     deadend: `usage: ctx deadend [attempt] [options]
        ctx deadend verify <deadend-id> [--path <path>]
+       ctx deadend obsolete|reject <deadend-id> --reason <text> [--path <path>]
 
-Record or verify a candidate deadend.
+Record or govern a candidate deadend.
 
 Options:
   --path <path>          Project path
@@ -195,7 +207,25 @@ Options:
   --evidence <items>     Comma-separated evidence references`,
     'deadend verify': `usage: ctx deadend verify <deadend-id> [--path <path>]
 
-Mark a deadend as verified.`,
+Mark a candidate deadend as verified.`,
+    'deadend obsolete': `usage: ctx deadend obsolete <deadend-id> --reason <text> [--path <path>]
+
+Retire a verified deadend with an explicit governance reason.`,
+    'deadend reject': `usage: ctx deadend reject <deadend-id> --reason <text> [--path <path>]
+
+Reject a candidate deadend with an explicit governance reason.`,
+    feedback: `usage: ctx feedback use knowledge|deadend <id> --event-id <stable-id> [--path <path>]
+
+Record explicit use of verified v2 retrieval material.`,
+    'feedback use': `usage: ctx feedback use knowledge|deadend <id> --event-id <stable-id> [--path <path>]
+
+Record an idempotent use signal that affects deterministic rank only.`,
+    journal: `usage: ctx journal verify [--path <path>]
+
+Validate the v2 journal hash chain and replay projections in memory.`,
+    'journal verify': `usage: ctx journal verify [--path <path>]
+
+Validate journal integrity without writing derived state.`,
     deadends: `usage: ctx deadends [--all] [--path <path>]
 
 List recorded deadends.`,
@@ -282,7 +312,7 @@ Stop the local runtime through authenticated loopback IPC.`,
 Internal runtime daemon entry point.`,
 };
 function usage() {
-    return `usage: ctx init|checkpoint|resume|orient|agent|hook|integrate|status|doctor|learn|knowledge|deadend|deadends|note|activity|migrate|runtime [options]
+    return `usage: ctx init|checkpoint|resume|orient|agent|hook|integrate|status|doctor|learn|knowledge|deadend|deadends|note|activity|migrate|runtime|feedback|journal [options]
 
 Run \"ctx <command> --help\" for command details.`;
 }
@@ -304,8 +334,10 @@ function printHelp(args) {
     const nested = (command === 'agent' && args[1] === 'serve')
         || (command === 'hook' && args[1] === 'claude-code')
         || (command === 'integrate' && args[1] === 'claude')
-        || (command === 'knowledge' && ['verify', 'discover'].includes(args[1]))
-        || (command === 'deadend' && args[1] === 'verify')
+        || (command === 'knowledge' && ['verify', 'discover', 'deprecate', 'reject'].includes(args[1]))
+        || (command === 'deadend' && ['verify', 'obsolete', 'reject'].includes(args[1]))
+        || (command === 'feedback' && args[1] === 'use')
+        || (command === 'journal' && args[1] === 'verify')
         || (command === 'note' && ['add', 'list'].includes(args[1]))
         || (command === 'migrate' && ['v1', 'verify'].includes(args[1]))
         || (command === 'runtime' && ['enable', 'disable', 'start', 'stop', 'status', 'serve'].includes(args[1]));
@@ -423,17 +455,20 @@ async function run(args) {
             print(await doctor(target));
             return;
         case 'learn': {
-            const valueOptions = ['--path', '--kind', '--scope', '--context', '--snapshot', '--evidence'];
+            const valueOptions = ['--path', '--kind', '--scope', '--context', '--snapshot', '--evidence', '--branch-mode', '--paths'];
             validateOptions(args.slice(1), valueOptions, valueOptions);
             const statement = positionals(args.slice(1), valueOptions);
             if (statement.length === 0)
                 throw new Error(HELP.learn);
+            const branchMode = enumOption(args, '--branch-mode', ['global', 'exact']) ?? 'global';
+            const git = branchMode === 'exact' ? await readGitWorktreeState(target ?? process.cwd()) : null;
             const input = {
                 kind: option(args, '--kind'),
                 scope: option(args, '--scope'),
                 sourceContextId: option(args, '--context'),
                 sourceSnapshotId: option(args, '--snapshot'),
                 evidence: listOption(args, '--evidence'),
+                applicability: { project: true, branchMode, ...(branchMode === 'exact' ? { branches: [git?.ref ?? git?.branch ?? 'detached'], sourceCommit: git?.commit ?? null } : {}), ...(listOption(args, '--paths') ? { paths: listOption(args, '--paths') } : {}) },
             };
             print(await learnKnowledge(target, statement.join(' '), input));
             return;
@@ -466,6 +501,28 @@ async function run(args) {
             }
             return;
         }
+        case 'feedback': {
+            if (args[1] !== 'use' || !['knowledge', 'deadend'].includes(args[2]))
+                throw new Error(HELP.feedback);
+            validateOptions(args.slice(3), ['--path', '--event-id'], ['--path', '--event-id']);
+            const values = positionals(args.slice(3), ['--path', '--event-id']);
+            if (values.length !== 1)
+                throw new Error(HELP['feedback use']);
+            print(await recordUse(target, { entity: args[2], entityId: values[0], eventId: option(args, '--event-id') ?? '' }));
+            return;
+        }
+        case 'journal': {
+            if (args[1] !== 'verify')
+                throw new Error(HELP.journal);
+            validateOptions(args.slice(2), ['--path'], ['--path']);
+            validatePositionals(positionals(args.slice(2), ['--path']), 0, HELP['journal verify']);
+            const root = target ?? process.cwd();
+            const events = await readJournal(root);
+            const projection = projectEvents(events);
+            const last = events.at(-1);
+            print({ verified: true, eventCount: events.length, cursor: { eventId: last?.eventId ?? null, hash: last?.hash ?? null }, counts: { contexts: Object.keys(projection.contexts).length, notes: Object.keys(projection.notes).length, knowledge: Object.keys(projection.knowledge).length, deadends: Object.keys(projection.deadends).length } });
+            return;
+        }
         case 'migrate': {
             if (args[1] === 'v1') {
                 validateOptions(args.slice(2), ['--dry-run', '--apply', '--path'], ['--path']);
@@ -545,6 +602,13 @@ async function run(args) {
                     throw new Error(HELP['knowledge verify']);
                 print(await verifyKnowledge(target, values[0]));
             }
+            else if (args[1] === 'deprecate' || args[1] === 'reject') {
+                validateOptions(args.slice(2), ['--path', '--reason'], ['--path', '--reason']);
+                const values = positionals(args.slice(2), ['--path', '--reason']);
+                if (values.length !== 1)
+                    throw new Error(HELP[`knowledge ${args[1]}`]);
+                print(await transitionKnowledge(target, values[0], args[1] === 'deprecate' ? 'deprecated' : 'rejected', option(args, '--reason') ?? ''));
+            }
             else {
                 validateOptions(args.slice(1), ['--all', '--path'], ['--path']);
                 validatePositionals(positionals(args.slice(1), ['--path']), 0, HELP.knowledge);
@@ -560,16 +624,26 @@ async function run(args) {
                     throw new Error(HELP['deadend verify']);
                 print(await verifyDeadend(target, values[0]));
             }
+            else if (args[1] === 'obsolete' || args[1] === 'reject') {
+                validateOptions(args.slice(2), ['--path', '--reason'], ['--path', '--reason']);
+                const values = positionals(args.slice(2), ['--path', '--reason']);
+                if (values.length !== 1)
+                    throw new Error(HELP[`deadend ${args[1]}`]);
+                print(await transitionDeadend(target, values[0], args[1] === 'obsolete' ? 'obsolete' : 'rejected', option(args, '--reason') ?? ''));
+            }
             else {
-                const valueOptions = ['--path', '--attempt', '--reason', '-m', '--scope', '--context', '--snapshot', '--evidence'];
+                const valueOptions = ['--path', '--attempt', '--reason', '-m', '--scope', '--context', '--snapshot', '--evidence', '--branch-mode', '--paths'];
                 validateOptions(args.slice(1), valueOptions, valueOptions);
                 const values = positionals(args.slice(1), valueOptions);
                 validatePositionals(values, 1, HELP.deadend);
+                const branchMode = enumOption(args, '--branch-mode', ['global', 'exact']) ?? 'global';
+                const git = branchMode === 'exact' ? await readGitWorktreeState(target ?? process.cwd()) : null;
                 const input = {
                     scope: option(args, '--scope'),
                     sourceContextId: option(args, '--context'),
                     sourceSnapshotId: option(args, '--snapshot'),
                     evidence: listOption(args, '--evidence'),
+                    applicability: { project: true, branchMode, ...(branchMode === 'exact' ? { branches: [git?.ref ?? git?.branch ?? 'detached'], sourceCommit: git?.commit ?? null } : {}), ...(listOption(args, '--paths') ? { paths: listOption(args, '--paths') } : {}) },
                 };
                 print(await recordDeadend(target, option(args, '--attempt') ?? values[0], option(args, '--reason') ?? option(args, '-m') ?? '', input));
             }

package/dist/src/cognition/feedback.d.ts

@@ -0,0 +1,9 @@
+export interface RecordUseInput {
+    entity: 'knowledge' | 'deadend';
+    entityId: string;
+    eventId: string;
+}
+export declare function recordUse(startPath: string | undefined, input: RecordUseInput): Promise<{
+    recorded: boolean;
+    eventId: string;
+}>;

package/dist/src/cognition/feedback.js

@@ -0,0 +1,30 @@
+import { resolveProjectRoot } from '../project/project-resolver.js';
+import { readGitWorktreeState } from '../git/git-adapter.js';
+import { appendEvent, readJournal } from './journal.js';
+import { v2Enabled } from './orient.js';
+import { rebuildProjections } from './projections.js';
+import { buildRetrievalProjection } from './retrieval.js';
+export async function recordUse(startPath, input) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    if (!input.eventId.trim())
+        throw new Error('feedback event ID must not be empty');
+    if (!await v2Enabled(projectRoot))
+        throw new Error('record use requires an enabled v2 runtime');
+    const events = await readJournal(projectRoot);
+    const entry = buildRetrievalProjection(events).entries[`${input.entity}:${input.entityId}`];
+    if (!entry)
+        throw new Error(`${input.entity} not found in v2 retrieval: ${input.entityId}`);
+    if (entry.status !== 'verified')
+        throw new Error(`record use requires verified ${input.entity}: ${input.entityId}`);
+    const git = await readGitWorktreeState(projectRoot);
+    const result = await appendEvent(projectRoot, {
+        type: 'record.used',
+        source: { kind: 'cli' },
+        idempotencyKey: `record-use:${input.entity}:${input.entityId}:${input.eventId.trim()}`,
+        git: { worktreeId: git.worktreeId, branch: git.branch, ref: git.ref, head: git.commit },
+        payload: { feedbackId: input.eventId.trim(), entity: input.entity, entityId: input.entityId, outcome: 'used' },
+    });
+    if (result.appended)
+        await rebuildProjections(projectRoot);
+    return { recorded: result.appended, eventId: result.event.eventId };
+}

package/dist/src/cognition/migration-v1.js

@@ -21,6 +21,16 @@ function sha256(value) {
 function isNotFound(error) {
     return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
 }
+function eventType(record, live = false) {
+    const status = record.record.status;
+    if (record.kind === 'context')
+        return live ? 'context.state.recorded' : 'context.checkpoint.imported';
+    if (record.kind === 'note')
+        return record.record.absorbedBySnapshotId ? 'note.absorbed' : record.record.status === 'resolved' ? 'note.resolved' : 'note.recorded';
+    if (record.kind === 'knowledge')
+        return status === 'verified' ? 'knowledge.verified' : status === 'deprecated' ? 'knowledge.deprecated' : status === 'rejected' ? 'knowledge.rejected' : 'knowledge.proposed';
+    return status === 'verified' ? 'deadend.verified' : status === 'obsolete' ? 'deadend.obsoleted' : status === 'rejected' ? 'deadend.rejected' : 'deadend.proposed';
+}
 async function readOptional(filePath) {
     try {
         return await readFile(filePath, 'utf8');
@@ -129,12 +139,8 @@ export async function importV1(startPath) {
         await writeV2Metadata(projectRoot);
         const importedEventIds = [];
         for (const record of records) {
-            const status = record.record.status;
             const event = await appendEvent(projectRoot, {
-                type: record.kind === 'context' ? 'context.checkpoint.imported'
-                    : record.kind === 'note' ? 'note.recorded'
-                        : record.kind === 'knowledge' ? status === 'verified' ? 'knowledge.verified' : 'knowledge.proposed'
-                            : status === 'verified' ? 'deadend.verified' : 'deadend.proposed',
+                type: eventType(record),
                 occurredAt: record.occurredAt,
                 source: { kind: 'migration' },
                 idempotencyKey: `v1:${record.sourceHash}:${record.kind}:${record.id}`,
@@ -158,12 +164,8 @@ export async function reconcileV1State(startPath) {
             return;
         const { records, sourceHash } = await sourceRecords(projectRoot);
         for (const record of records) {
-            const status = record.record.status;
             await appendEvent(projectRoot, {
-                type: record.kind === 'context' ? 'context.state.recorded'
-                    : record.kind === 'note' ? record.record.absorbedBySnapshotId ? 'note.absorbed' : record.record.status === 'resolved' ? 'note.resolved' : 'note.recorded'
-                        : record.kind === 'knowledge' ? status === 'verified' ? 'knowledge.verified' : 'knowledge.proposed'
-                            : status === 'verified' ? 'deadend.verified' : 'deadend.proposed',
+                type: eventType(record, true),
                 occurredAt: record.occurredAt,
                 source: { kind: 'migration' },
                 idempotencyKey: `v1-live-sync:${sourceHash}:${record.kind}:${record.id}`,

package/dist/src/cognition/orient.d.ts

@@ -1,9 +1,13 @@
+import type { CognitionEvent, CognitionRetrievalProjection } from './types.js';
 export interface V2OrientationPlan {
     contextId: string;
     snapshotId: string;
     knowledgeIds: ReadonlySet<string>;
     deadendIds: ReadonlySet<string>;
     noteIds: ReadonlySet<string>;
+    retrieval: CognitionRetrievalProjection;
+    currentGit: CognitionEvent['git'];
+    selection: 'requested-context' | 'exact-worktree-ref' | 'legacy-ref-branch';
 }
 export declare function selectV2Orientation(projectRoot: string, contextId?: string): Promise<V2OrientationPlan | null>;
 export declare function v2Enabled(projectRoot: string): Promise<boolean>;

package/dist/src/cognition/orient.js

@@ -5,6 +5,7 @@ import { readJson } from '../storage/json-store.js';
 import { loadManifest } from '../runtime/init.js';
 import { readJournal } from './journal.js';
 import { projectEvents, workspaceKey } from './projections.js';
+import { buildRetrievalProjection } from './retrieval.js';
 import { v1Synced } from './v1-bridge.js';
 function contextReference(value) {
     const boundary = value.lastIndexOf(':');
@@ -56,6 +57,7 @@ export async function selectV2Orientation(projectRoot, contextId) {
             return null;
         const projection = projectEvents(events);
         let selected = null;
+        let selection = 'requested-context';
         if (contextId) {
             const matching = [...Object.keys(projection.contexts)].reverse().find((reference) => contextReference(reference)?.contextId === contextId);
             selected = matching ? contextReference(matching) : null;
@@ -65,10 +67,17 @@ export async function selectV2Orientation(projectRoot, contextId) {
             const legacy = Object.values(projection.workspaces).find((workspace) => workspace.worktreeId === null && (workspace.ref === current.ref || workspace.branch === current.branch));
             const reference = (exact?.activeContextRef ? exact : legacy)?.activeContextRef;
             selected = reference ? contextReference(reference) : null;
+            selection = exact?.activeContextRef ? 'exact-worktree-ref' : 'legacy-ref-branch';
         }
         if (!selected || !projection.contexts[`${selected.contextId}:${selected.snapshotId}`])
             return null;
-        return { ...selected, ...latestRecords(events, current, selected.contextId) };
+        return {
+            ...selected,
+            ...latestRecords(events, current, selected.contextId),
+            retrieval: buildRetrievalProjection(events),
+            currentGit: { worktreeId: current.worktreeId, branch: current.branch, ref: current.ref, head: current.commit },
+            selection,
+        };
     }
     catch {
         return null;

package/dist/src/cognition/projections.js

@@ -2,8 +2,9 @@ import crypto from 'node:crypto';
 import { readdir, rm } from 'node:fs/promises';
 import path from 'node:path';
 import { atomicWriteJson } from '../storage/atomic-write.js';
-import { cognitionBranchesDirectory, cognitionContextsProjectionPath, cognitionDeadendsProjectionPath, cognitionKnowledgeProjectionPath, cognitionNotesProjectionPath, cognitionProjectionCursorPath, } from '../storage/layout.js';
+import { cognitionBranchesDirectory, cognitionContextsProjectionPath, cognitionDeadendsProjectionPath, cognitionKnowledgeProjectionPath, cognitionNotesProjectionPath, cognitionProjectionCursorPath, cognitionRetrievalProjectionPath, } from '../storage/layout.js';
 import { readJournal } from './journal.js';
+import { buildRetrievalProjection } from './retrieval.js';
 export function workspaceKey(anchor) {
     return crypto.createHash('sha256')
         .update(`${anchor.worktreeId ?? 'default'}\0${anchor.ref ?? anchor.branch ?? 'detached'}`)
@@ -74,12 +75,12 @@ export function projectEvents(events) {
             if (noteId)
                 projection.notes[noteId] = payload;
         }
-        if ((event.type === 'knowledge.proposed' || event.type === 'knowledge.verified') && record) {
+        if (['knowledge.proposed', 'knowledge.verified', 'knowledge.deprecated', 'knowledge.rejected'].includes(event.type) && record) {
             const knowledgeId = recordId(record, 'knowledge');
             if (knowledgeId)
                 projection.knowledge[knowledgeId] = payload;
         }
-        if ((event.type === 'deadend.proposed' || event.type === 'deadend.verified') && record) {
+        if (['deadend.proposed', 'deadend.verified', 'deadend.obsoleted', 'deadend.rejected'].includes(event.type) && record) {
             const deadendId = recordId(record, 'deadend');
             if (deadendId)
                 projection.deadends[deadendId] = payload;
@@ -107,6 +108,7 @@ async function removeObsoleteWorkspaceFiles(projectRoot, workspaceKeys) {
 export async function rebuildProjections(projectRoot) {
     const events = await readJournal(projectRoot);
     const projection = projectEvents(events);
+    const retrieval = buildRetrievalProjection(events);
     const last = events.at(-1);
     const cursor = {
         schemaVersion: 2,
@@ -120,6 +122,7 @@ export async function rebuildProjections(projectRoot) {
         atomicWriteJson(cognitionNotesProjectionPath(projectRoot), projection.notes),
         atomicWriteJson(cognitionKnowledgeProjectionPath(projectRoot), projection.knowledge),
         atomicWriteJson(cognitionDeadendsProjectionPath(projectRoot), projection.deadends),
+        atomicWriteJson(cognitionRetrievalProjectionPath(projectRoot), retrieval),
         ...Object.values(projection.workspaces).map((workspace) => atomicWriteJson(`${cognitionBranchesDirectory(projectRoot)}/${workspace.workspaceKey}.json`, workspace)),
     ]);
     await atomicWriteJson(cognitionProjectionCursorPath(projectRoot), cursor);

package/dist/src/cognition/retrieval.d.ts

@@ -0,0 +1,26 @@
+import type { DeadendDiscoveryResult, KnowledgeDiscoveryResult } from '../runtime/types.js';
+import type { CognitionEvent, CognitionRetrievalProjection } from './types.js';
+export declare function normalized(value: string): string;
+export declare function queryTerms(query: string): string[];
+export declare function buildRetrievalProjection(events: CognitionEvent[]): CognitionRetrievalProjection;
+export interface RetrievalExclusions {
+    status_not_verified: number;
+    applicability_mismatch: number;
+    scope_mismatch: number;
+    query_no_match: number;
+    result_limit: number;
+}
+export interface V2Discovery<T> {
+    result: T;
+    exclusions: RetrievalExclusions;
+}
+export declare function discoverV2Knowledge(index: CognitionRetrievalProjection, query: string, current: CognitionEvent['git'], options: {
+    scope?: string;
+    limit: number;
+    maxChars: number;
+}): V2Discovery<KnowledgeDiscoveryResult>;
+export declare function discoverV2Deadends(index: CognitionRetrievalProjection, query: string, current: CognitionEvent['git'], options: {
+    scope?: string;
+    limit: number;
+    maxChars: number;
+}): V2Discovery<DeadendDiscoveryResult>;

package/dist/src/cognition/retrieval.js

@@ -0,0 +1,273 @@
+const aliasGroups = [
+    ['投保人认证', '投保人身份认证', '身份核验', '实名认证', 'applicant authentication', 'identity verification'],
+    ['短信验证码', '验证码', 'sms verification', 'otp'],
+    ['证件ocr', '证件识别', 'identity ocr', 'document ocr'],
+    ['人脸识别', '人脸认证', 'face recognition', 'facial verification'],
+];
+export function normalized(value) {
+    return value.trim().toLocaleLowerCase();
+}
+export function queryTerms(query) {
+    const clean = normalized(query);
+    const terms = new Set(clean.split(/\s+/).filter(Boolean));
+    for (const group of aliasGroups) {
+        if (group.some((alias) => clean.includes(normalized(alias)))) {
+            for (const alias of group)
+                terms.add(normalized(alias));
+        }
+    }
+    return [...terms].sort();
+}
+function strings(record, entity) {
+    return entity === 'knowledge'
+        ? {
+            statement: typeof record.statement === 'string' ? record.statement : '',
+            kind: typeof record.kind === 'string' ? record.kind : '',
+            scope: typeof record.scope === 'string' ? record.scope : '',
+        }
+        : {
+            attempt: typeof record.attempt === 'string' ? record.attempt : '',
+            reason: typeof record.reason === 'string' ? record.reason : '',
+            scope: typeof record.scope === 'string' ? record.scope : '',
+        };
+}
+function defaultApplicability(event) {
+    if (event.git.ref === null && event.git.branch === null)
+        return { project: true, branchMode: 'global' };
+    return {
+        project: true,
+        branchMode: 'exact',
+        branches: [event.git.ref ?? event.git.branch ?? 'detached'],
+        sourceCommit: event.git.head,
+    };
+}
+function applicability(record, event) {
+    const value = record.applicability;
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        const candidate = value;
+        if (candidate.project === true && (candidate.branchMode === 'global' || candidate.branchMode === 'exact')) {
+            return {
+                project: true,
+                branchMode: candidate.branchMode,
+                ...(Array.isArray(candidate.branches) ? { branches: candidate.branches.filter((item) => typeof item === 'string').sort() } : {}),
+                ...(Array.isArray(candidate.paths) ? { paths: candidate.paths.filter((item) => typeof item === 'string').sort() } : {}),
+                ...(typeof candidate.sourceCommit === 'string' || candidate.sourceCommit === null ? { sourceCommit: candidate.sourceCommit } : {}),
+            };
+        }
+    }
+    return defaultApplicability(event);
+}
+function recordPayload(event) {
+    const payload = event.payload;
+    return payload.record && typeof payload.record === 'object' && !Array.isArray(payload.record)
+        ? payload.record
+        : null;
+}
+function lifecycleEntity(event, record) {
+    if (event.type.startsWith('knowledge.') && typeof record.knowledgeId === 'string')
+        return { entity: 'knowledge', entityId: record.knowledgeId };
+    if (event.type.startsWith('deadend.') && typeof record.deadendId === 'string')
+        return { entity: 'deadend', entityId: record.deadendId };
+    return null;
+}
+function lifecycleEvent(event) {
+    return [
+        'knowledge.proposed', 'knowledge.verified', 'knowledge.deprecated', 'knowledge.rejected',
+        'deadend.proposed', 'deadend.verified', 'deadend.obsoleted', 'deadend.rejected',
+    ].includes(event.type);
+}
+export function buildRetrievalProjection(events) {
+    const entries = new Map();
+    const feedback = new Map();
+    for (const event of events) {
+        if (event.type === 'record.used') {
+            const payload = event.payload;
+            const entity = payload.entity === 'knowledge' || payload.entity === 'deadend' ? payload.entity : null;
+            const entityId = typeof payload.entityId === 'string' ? payload.entityId : null;
+            if (!entity || !entityId)
+                continue;
+            const key = `${entity}:${entityId}`;
+            const prior = feedback.get(key) ?? { usedCount: 0, latestUsedAt: event.occurredAt };
+            feedback.set(key, { usedCount: prior.usedCount + 1, latestUsedAt: event.occurredAt });
+            continue;
+        }
+        if (!lifecycleEvent(event))
+            continue;
+        const record = recordPayload(event);
+        if (!record)
+            continue;
+        const identity = lifecycleEntity(event, record);
+        if (!identity)
+            continue;
+        const fields = strings(record, identity.entity);
+        const normalizedTerms = [...new Set(Object.values(fields).flatMap((value) => {
+                const normalizedValue = normalized(value);
+                return normalizedValue ? [normalizedValue, ...normalizedValue.split(/\s+/).filter(Boolean)] : [];
+            }))].sort();
+        const key = `${identity.entity}:${identity.entityId}`;
+        entries.set(key, {
+            entity: identity.entity,
+            entityId: identity.entityId,
+            status: typeof record.status === 'string' ? record.status : 'candidate',
+            record,
+            applicability: applicability(record, event),
+            searchable: Object.fromEntries(Object.entries(fields).map(([field, value]) => [field, normalized(value)])),
+            normalizedTerms,
+            provenance: {
+                eventId: event.eventId,
+                eventType: event.type,
+                occurredAt: event.occurredAt,
+                git: event.git,
+                ...(typeof event.payload.anchorProvenance === 'string' ? { anchorProvenance: event.payload.anchorProvenance } : {}),
+            },
+            feedback: { usedCount: 0, latestUsedAt: null },
+        });
+    }
+    for (const [key, entry] of entries) {
+        const value = feedback.get(key);
+        if (value)
+            entry.feedback = value;
+    }
+    const ordered = Object.fromEntries([...entries.entries()].sort(([left], [right]) => left.localeCompare(right)));
+    const terms = new Map();
+    for (const [key, entry] of Object.entries(ordered)) {
+        for (const term of entry.normalizedTerms)
+            terms.set(term, [...(terms.get(term) ?? []), key]);
+    }
+    return {
+        schemaVersion: 2,
+        entries: ordered,
+        terms: Object.fromEntries([...terms.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([term, ids]) => [term, ids.sort()])),
+    };
+}
+function emptyExclusions() {
+    return { status_not_verified: 0, applicability_mismatch: 0, scope_mismatch: 0, query_no_match: 0, result_limit: 0 };
+}
+function applicable(entry, current) {
+    if (entry.applicability.branchMode === 'global')
+        return true;
+    const anchor = entry.provenance.git;
+    return anchor.ref === current.ref
+        && anchor.branch === current.branch
+        && (anchor.worktreeId === null || anchor.worktreeId === current.worktreeId);
+}
+function match(entry, terms, entity) {
+    const fields = new Set();
+    const matched = new Set();
+    let score = 0;
+    const phrase = terms.join(' ');
+    const statementField = entity === 'knowledge' ? 'statement' : 'attempt';
+    if (entry.searchable[statementField]?.includes(phrase))
+        score += entity === 'knowledge' ? 20 : 0;
+    for (const term of terms) {
+        for (const [field, value] of Object.entries(entry.searchable)) {
+            if (!value.includes(term))
+                continue;
+            fields.add(field);
+            matched.add(term);
+            score += field === statementField ? 5 : field === 'scope' ? 4 : 3;
+        }
+    }
+    if (entry.searchable.scope === phrase)
+        score += 10;
+    return { score, matchedTerms: [...matched].sort(), matchedFields: [...fields].sort() };
+}
+function limitText(value, maxChars) {
+    return value.length <= maxChars ? value : `${value.slice(0, Math.max(0, maxChars - 1))}…`;
+}
+export function discoverV2Knowledge(index, query, current, options) {
+    const exclusions = emptyExclusions();
+    const terms = queryTerms(query);
+    const hits = Object.values(index.entries).flatMap((entry) => {
+        if (entry.entity !== 'knowledge')
+            return [];
+        if (entry.status !== 'verified') {
+            exclusions.status_not_verified += 1;
+            return [];
+        }
+        if (!applicable(entry, current)) {
+            exclusions.applicability_mismatch += 1;
+            return [];
+        }
+        const knowledge = entry.record;
+        if (options.scope && normalized(knowledge.scope) !== normalized(options.scope)) {
+            exclusions.scope_mismatch += 1;
+            return [];
+        }
+        const matched = match(entry, terms, 'knowledge');
+        if (matched.matchedTerms.length === 0) {
+            exclusions.query_no_match += 1;
+            return [];
+        }
+        return [{ entry, knowledge, ...matched }];
+    }).sort((left, right) => right.score - left.score
+        || Math.min(right.entry.feedback.usedCount, 5) - Math.min(left.entry.feedback.usedCount, 5)
+        || right.knowledge.confidence - left.knowledge.confidence
+        || right.entry.provenance.occurredAt.localeCompare(left.entry.provenance.occurredAt)
+        || left.knowledge.knowledgeId.localeCompare(right.knowledge.knowledgeId));
+    const selected = hits.slice(0, options.limit);
+    exclusions.result_limit = hits.length - selected.length;
+    return {
+        result: {
+            query,
+            total: hits.length,
+            truncated: hits.length > selected.length,
+            hits: selected.map(({ knowledge, score, matchedTerms, matchedFields, entry }) => ({
+                knowledge: { ...knowledge, statement: limitText(knowledge.statement, options.maxChars), supportingEvidence: knowledge.supportingEvidence.map((value) => limitText(value, options.maxChars)) },
+                score,
+                matchedTerms,
+                matchedFields,
+                why: [...matchedFields.map((field) => `matched ${field}`), ...(entry.feedback.usedCount > 0 ? ['prior recorded use'] : [])],
+            })),
+            duplicateIds: [],
+            possibleConflicts: [],
+        },
+        exclusions,
+    };
+}
+export function discoverV2Deadends(index, query, current, options) {
+    const exclusions = emptyExclusions();
+    const terms = queryTerms(query);
+    const hits = Object.values(index.entries).flatMap((entry) => {
+        if (entry.entity !== 'deadend')
+            return [];
+        if (entry.status !== 'verified') {
+            exclusions.status_not_verified += 1;
+            return [];
+        }
+        if (!applicable(entry, current)) {
+            exclusions.applicability_mismatch += 1;
+            return [];
+        }
+        const deadend = entry.record;
+        if (options.scope && normalized(deadend.scope) !== normalized(options.scope)) {
+            exclusions.scope_mismatch += 1;
+            return [];
+        }
+        const matched = match(entry, terms, 'deadend');
+        if (matched.matchedTerms.length === 0) {
+            exclusions.query_no_match += 1;
+            return [];
+        }
+        return [{ entry, deadend, ...matched }];
+    }).sort((left, right) => right.score - left.score
+        || Math.min(right.entry.feedback.usedCount, 5) - Math.min(left.entry.feedback.usedCount, 5)
+        || right.entry.provenance.occurredAt.localeCompare(left.entry.provenance.occurredAt)
+        || left.deadend.deadendId.localeCompare(right.deadend.deadendId));
+    const selected = hits.slice(0, options.limit);
+    exclusions.result_limit = hits.length - selected.length;
+    return {
+        result: {
+            query,
+            total: hits.length,
+            truncated: hits.length > selected.length,
+            hits: selected.map(({ deadend, score, matchedTerms, matchedFields }) => ({
+                deadend: { ...deadend, attempt: limitText(deadend.attempt, options.maxChars), reason: limitText(deadend.reason, options.maxChars), observedEvidence: deadend.observedEvidence.map((value) => limitText(value, options.maxChars)) },
+                score,
+                matchedTerms,
+                matchedFields,
+            })),
+        },
+        exclusions,
+    };
+}

package/dist/src/cognition/types.d.ts

@@ -1,6 +1,6 @@
 export declare const COGNITION_LAYOUT_VERSION: "event-journal-v2";
 export type CognitionEventSource = 'cli' | 'claude-hook' | 'mcp' | 'git-observer' | 'fs-observer' | 'migration';
-export type CognitionEventType = 'runtime.enabled' | 'runtime.started' | 'runtime.stopped' | 'host.session.started' | 'host.prompt.submitted' | 'git.state.observed' | 'git.branch.changed' | 'git.head.changed' | 'workspace.paths.changed' | 'context.checkpoint.imported' | 'context.state.recorded' | 'note.recorded' | 'note.resolved' | 'note.absorbed' | 'knowledge.proposed' | 'knowledge.verified' | 'knowledge.deprecated' | 'deadend.proposed' | 'deadend.verified' | 'deadend.obsoleted' | 'projection.advanced' | 'projection.failed';
+export type CognitionEventType = 'runtime.enabled' | 'runtime.started' | 'runtime.stopped' | 'host.session.started' | 'host.prompt.submitted' | 'git.state.observed' | 'git.branch.changed' | 'git.head.changed' | 'workspace.paths.changed' | 'context.checkpoint.imported' | 'context.state.recorded' | 'note.recorded' | 'note.resolved' | 'note.absorbed' | 'knowledge.proposed' | 'knowledge.verified' | 'knowledge.deprecated' | 'knowledge.rejected' | 'deadend.proposed' | 'deadend.verified' | 'deadend.obsoleted' | 'deadend.rejected' | 'record.used' | 'projection.advanced' | 'projection.failed';
 export interface CognitionGitAnchor {
     worktreeId: string | null;
     branch: string | null;
@@ -53,6 +53,44 @@ export interface Applicability {
     sourceCommit?: string | null;
     dependencyConstraints?: string[];
 }
+export interface CognitionLifecycleTransition {
+    entity: 'knowledge' | 'deadend';
+    entityId: string;
+    from: 'candidate' | 'verified';
+    to: 'verified' | 'deprecated' | 'rejected' | 'obsolete';
+    reason?: string;
+}
+export interface CognitionUseFeedback {
+    feedbackId: string;
+    entity: 'knowledge' | 'deadend';
+    entityId: string;
+    outcome: 'used';
+}
+export interface CognitionRetrievalEntry {
+    entity: 'knowledge' | 'deadend';
+    entityId: string;
+    status: string;
+    record: Record<string, unknown>;
+    applicability: Applicability;
+    searchable: Record<string, string>;
+    normalizedTerms: string[];
+    provenance: {
+        eventId: string;
+        eventType: CognitionEventType;
+        occurredAt: string;
+        git: CognitionGitAnchor;
+        anchorProvenance?: CognitionRecordPayload['anchorProvenance'];
+    };
+    feedback: {
+        usedCount: number;
+        latestUsedAt: string | null;
+    };
+}
+export interface CognitionRetrievalProjection {
+    schemaVersion: 2;
+    entries: Record<string, CognitionRetrievalEntry>;
+    terms: Record<string, string[]>;
+}
 export interface BranchWorkspace {
     schemaVersion: 2;
     workspaceKey: string;

package/dist/src/cognition/v1-bridge.js

@@ -67,8 +67,16 @@ export async function mirrorNote(projectRoot, note, absorbed = false) {
     await mirror(projectRoot, absorbed ? 'note.absorbed' : 'note.recorded', note, note.noteId);
 }
 export async function mirrorKnowledge(projectRoot, knowledge) {
-    await mirror(projectRoot, knowledge.status === 'verified' ? 'knowledge.verified' : 'knowledge.proposed', knowledge, knowledge.knowledgeId);
+    const type = knowledge.status === 'verified' ? 'knowledge.verified'
+        : knowledge.status === 'deprecated' ? 'knowledge.deprecated'
+            : knowledge.status === 'rejected' ? 'knowledge.rejected'
+                : 'knowledge.proposed';
+    await mirror(projectRoot, type, knowledge, knowledge.knowledgeId);
 }
 export async function mirrorDeadend(projectRoot, deadend) {
-    await mirror(projectRoot, deadend.status === 'verified' ? 'deadend.verified' : 'deadend.proposed', deadend, deadend.deadendId);
+    const type = deadend.status === 'verified' ? 'deadend.verified'
+        : deadend.status === 'obsolete' ? 'deadend.obsoleted'
+            : deadend.status === 'rejected' ? 'deadend.rejected'
+                : 'deadend.proposed';
+    await mirror(projectRoot, type, deadend, deadend.deadendId);
 }

package/dist/src/runtime/knowledge.d.ts

@@ -3,7 +3,9 @@ export declare function learnKnowledge(startPath: string | undefined, statement:
 export declare function listKnowledge(startPath?: string, includeUnverified?: boolean): Promise<Knowledge[]>;
 export declare function discoverKnowledge(startPath: string | undefined, query: string, options?: KnowledgeDiscoverOptions): Promise<KnowledgeDiscoveryResult>;
 export declare function verifyKnowledge(startPath: string | undefined, knowledgeId: string): Promise<Knowledge>;
+export declare function transitionKnowledge(startPath: string | undefined, knowledgeId: string, status: 'deprecated' | 'rejected', reason: string): Promise<Knowledge>;
 export declare function recordDeadend(startPath: string | undefined, attempt: string, reason: string, scopeOrInput?: string | DeadendInput): Promise<Deadend>;
 export declare function listDeadends(startPath?: string, includeUnverified?: boolean): Promise<Deadend[]>;
 export declare function discoverDeadends(startPath: string | undefined, query: string, options?: DeadendDiscoverOptions): Promise<DeadendDiscoveryResult>;
+export declare function transitionDeadend(startPath: string | undefined, deadendId: string, status: 'obsolete' | 'rejected', reason: string): Promise<Deadend>;
 export declare function verifyDeadend(startPath: string | undefined, deadendId: string): Promise<Deadend>;

package/dist/src/runtime/knowledge.js

@@ -35,6 +35,23 @@ function isKnowledgeFile(value) {
 function cleanList(values) {
     return [...new Set((values ?? []).map((value) => value.trim()).filter(Boolean))];
 }
+function cleanApplicability(input) {
+    if (!input)
+        return { project: true, branchMode: 'global' };
+    if (input.project !== true || !['global', 'exact'].includes(input.branchMode))
+        throw new Error('invalid record applicability');
+    const branches = cleanList(input.branches);
+    const paths = cleanList(input.paths);
+    if (input.branchMode === 'exact' && branches.length === 0)
+        throw new Error('exact applicability requires a branch');
+    return {
+        project: true,
+        branchMode: input.branchMode,
+        ...(branches.length > 0 ? { branches } : {}),
+        ...(paths.length > 0 ? { paths } : {}),
+        ...(input.sourceCommit === undefined ? {} : { sourceCommit: input.sourceCommit }),
+    };
+}
 function normalized(value) {
     return value.trim().toLocaleLowerCase();
 }
@@ -116,6 +133,7 @@ export async function learnKnowledge(startPath, statement, scopeOrInput = 'proje
             sourceContextIds: cleanList(input.sourceContextId ? [input.sourceContextId] : []),
             sourceSnapshotIds: cleanList(input.sourceSnapshotId ? [input.sourceSnapshotId] : []),
             supportingEvidence: cleanList(input.evidence),
+            applicability: cleanApplicability(input.applicability),
             createdAt: now,
             updatedAt: now,
         };
@@ -208,6 +226,8 @@ export async function verifyKnowledge(startPath, knowledgeId) {
         const item = file.items.find((candidate) => candidate.knowledgeId === knowledgeId);
         if (!item)
             throw new Error(`knowledge not found: ${knowledgeId}`);
+        if (item.status !== 'candidate')
+            throw new Error(`knowledge must be a candidate to verify: ${knowledgeId}`);
         item.status = 'verified';
         item.confidence = Math.max(item.confidence, 0.8);
         item.updatedAt = new Date().toISOString();
@@ -216,6 +236,26 @@ export async function verifyKnowledge(startPath, knowledgeId) {
         return item;
     });
 }
+export async function transitionKnowledge(startPath, knowledgeId, status, reason) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    if (!reason.trim())
+        throw new Error('knowledge transition reason must not be empty');
+    return withLock(`${locksDirectory(projectRoot)}/knowledge.lock`, async () => {
+        const file = await loadKnowledge(projectRoot);
+        const item = file.items.find((candidate) => candidate.knowledgeId === knowledgeId);
+        if (!item)
+            throw new Error(`knowledge not found: ${knowledgeId}`);
+        if ((status === 'deprecated' && item.status !== 'verified') || (status === 'rejected' && item.status !== 'candidate')) {
+            throw new Error(`invalid knowledge transition: ${item.status} to ${status}`);
+        }
+        item.status = status;
+        item.updatedAt = new Date().toISOString();
+        item.governance = { reason: reason.trim(), transitionedAt: item.updatedAt };
+        await atomicWriteJson(knowledgePath(projectRoot), file);
+        await mirrorKnowledge(projectRoot, item);
+        return item;
+    });
+}
 export async function recordDeadend(startPath, attempt, reason, scopeOrInput = 'project') {
     const projectRoot = await resolveProjectRoot(startPath);
     const input = typeof scopeOrInput === 'string' ? { scope: scopeOrInput } : scopeOrInput;
@@ -232,6 +272,7 @@ export async function recordDeadend(startPath, attempt, reason, scopeOrInput = '
             status: 'candidate',
             sourceContextId: input.sourceContextId ?? null,
             sourceSnapshotId: input.sourceSnapshotId ?? null,
+            applicability: cleanApplicability(input.applicability),
             createdAt: now,
             updatedAt: now,
         };
@@ -288,6 +329,26 @@ export async function discoverDeadends(startPath, query, options = {}) {
         hits: selected.map((item) => ({ ...item, deadend: limitedDeadend(item.deadend, maxChars) })),
     };
 }
+export async function transitionDeadend(startPath, deadendId, status, reason) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    if (!reason.trim())
+        throw new Error('deadend transition reason must not be empty');
+    return withLock(`${locksDirectory(projectRoot)}/deadends.lock`, async () => {
+        const file = await loadDeadends(projectRoot);
+        const item = file.items.find((candidate) => candidate.deadendId === deadendId);
+        if (!item)
+            throw new Error(`deadend not found: ${deadendId}`);
+        if ((status === 'obsolete' && item.status !== 'verified') || (status === 'rejected' && item.status !== 'candidate')) {
+            throw new Error(`invalid deadend transition: ${item.status} to ${status}`);
+        }
+        item.status = status;
+        item.updatedAt = new Date().toISOString();
+        item.governance = { reason: reason.trim(), transitionedAt: item.updatedAt };
+        await atomicWriteJson(deadendsPath(projectRoot), file);
+        await mirrorDeadend(projectRoot, item);
+        return item;
+    });
+}
 export async function verifyDeadend(startPath, deadendId) {
     const projectRoot = await resolveProjectRoot(startPath);
     return withLock(`${locksDirectory(projectRoot)}/deadends.lock`, async () => {
@@ -295,6 +356,8 @@ export async function verifyDeadend(startPath, deadendId) {
         const item = file.items.find((candidate) => candidate.deadendId === deadendId);
         if (!item)
             throw new Error(`deadend not found: ${deadendId}`);
+        if (item.status !== 'candidate')
+            throw new Error(`deadend must be a candidate to verify: ${deadendId}`);
         item.status = 'verified';
         item.updatedAt = new Date().toISOString();
         await atomicWriteJson(deadendsPath(projectRoot), file);

package/dist/src/runtime/types.d.ts

@@ -136,6 +136,13 @@ export interface ActivityResult {
 }
 export type KnowledgeStatus = 'candidate' | 'verified' | 'deprecated' | 'rejected';
 export type DeadendStatus = 'candidate' | 'verified' | 'obsolete' | 'rejected';
+export interface RecordApplicability {
+    project: true;
+    branches?: string[];
+    branchMode: 'global' | 'exact';
+    paths?: string[];
+    sourceCommit?: string | null;
+}
 export interface Knowledge {
     knowledgeId: string;
     kind: string;
@@ -146,6 +153,11 @@ export interface Knowledge {
     sourceContextIds: string[];
     sourceSnapshotIds: string[];
     supportingEvidence: string[];
+    applicability?: RecordApplicability;
+    governance?: {
+        reason: string;
+        transitionedAt: string;
+    };
     createdAt: string;
     updatedAt: string;
 }
@@ -155,6 +167,7 @@ export interface KnowledgeInput {
     sourceContextId?: string;
     sourceSnapshotId?: string;
     evidence?: string[];
+    applicability?: RecordApplicability;
 }
 export interface KnowledgeDiscoverOptions {
     scope?: string;
@@ -205,6 +218,7 @@ export interface DeadendInput {
     sourceContextId?: string;
     sourceSnapshotId?: string;
     evidence?: string[];
+    applicability?: RecordApplicability;
 }
 export interface Deadend {
     deadendId: string;
@@ -215,6 +229,11 @@ export interface Deadend {
     status: DeadendStatus;
     sourceContextId: string | null;
     sourceSnapshotId: string | null;
+    applicability?: RecordApplicability;
+    governance?: {
+        reason: string;
+        transitionedAt: string;
+    };
     createdAt: string;
     updatedAt: string;
 }

package/dist/src/storage/layout.d.ts

@@ -22,6 +22,7 @@ export declare function cognitionContextsProjectionPath(projectRoot: string): st
 export declare function cognitionKnowledgeProjectionPath(projectRoot: string): string;
 export declare function cognitionDeadendsProjectionPath(projectRoot: string): string;
 export declare function cognitionNotesProjectionPath(projectRoot: string): string;
+export declare function cognitionRetrievalProjectionPath(projectRoot: string): string;
 export declare function cognitionMigrationsDirectory(projectRoot: string): string;
 export declare function cognitionV1ImportPath(projectRoot: string): string;
 export declare function cognitionRuntimeDirectory(projectRoot: string): string;

package/dist/src/storage/layout.js

@@ -71,6 +71,9 @@ export function cognitionDeadendsProjectionPath(projectRoot) {
 export function cognitionNotesProjectionPath(projectRoot) {
     return path.join(cognitionProjectionsDirectory(projectRoot), 'notes.json');
 }
+export function cognitionRetrievalProjectionPath(projectRoot) {
+    return path.join(cognitionProjectionsDirectory(projectRoot), 'retrieval.json');
+}
 export function cognitionMigrationsDirectory(projectRoot) {
     return path.join(cognitionRoot(projectRoot), 'migrations');
 }

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.5.0";
+export declare const VERSION = "0.6.0";

package/dist/src/version.js

@@ -1 +1 @@
-export const VERSION = '0.5.0';
+export const VERSION = '0.6.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fluffy-context",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Local context management CLI and MCP tools for AI coding agents",
   "license": "MIT",
   "author": "FluffyChi-Xing",
@@ -55,7 +55,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.test.json --noEmit",
-    "test": "tsc -p tsconfig.test.json && node --test dist/test/*.test.js",
+    "test": "tsc -p tsconfig.test.json && node --test --test-concurrency=1 dist/test/*.test.js",
     "pack:check": "tsc -p tsconfig.test.json && node --test dist/test/package-smoke.test.js",
     "prepack": "npm run build",
     "prepublishOnly": "npm test && npm run pack:check",