fluffy-context 0.3.1 → 0.6.0

package/README.md

@@ -1,8 +1,23 @@
 # Context Runtime
 
-`fluffy-context` 是面向 AI 编程会话的本地 Context Runtime CLI。0.3.1 提供可重复、安全调用的任务定位入口、MCP 工具，以及 Claude Code 的阶段性工作流引导，让 Agent 不必自行拼接恢复、共识发现与短期记录。
+`fluffy-context` 正在从面向 AI 编程会话的本地 Context Runtime CLI，演进为 **Agent 无关的本地 Knowledge Runtime**。它负责自动捕获开发过程中产生的事件、候选共识、问题、不可达路径和分支工作状态，并向任意 Agent 注入有界、可验证的业务认知。
 
-它更接近“Context 的 Git”，而不是代码备份工具：Git 仍然负责代码和真实文件变更；Context Runtime 负责 AI 工作状态、已验证共识与交接信息的本地保存和恢复。
+Git 仍然负责代码和真实文件变更，Issue 系统仍然负责任务，项目文档仍然负责设计；`fluffy-context` 补齐的是持续演进的项目认知层。最终架构是 `project → knowledge runtime → LLM`：CLI、MCP、Claude Hook 和未来 IDE/Agent 集成只是事件入口与信息注入适配器，而不是认知本体。
+
+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 行为。
 
 ## 适用场景
 
@@ -91,11 +106,48 @@ 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
+ctx runtime enable
+ctx runtime start
+ctx runtime status
+ctx runtime stop
 ctx status
 ctx doctor
 ```
 
+### v2 迁移与本地 Runtime
+
+v2 与既有 `.context/` 数据并存，迁移绝不会重写或修复 v1 文件。先执行只读检查，再显式导入并验证投影一致性：
+
+```bash
+ctx migrate v1 --dry-run
+ctx migrate v1 --apply
+ctx migrate verify
+```
+
+只有完成迁移后才可启用 Runtime：
+
+```bash
+ctx runtime enable
+ctx runtime start
+ctx runtime status
+ctx runtime stop
+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。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。
+
 ### `ctx checkpoint` 和 `ctx resume`
 
 第一次 checkpoint 创建 baseline，后续变化创建 patch。相同内容返回 `no_change`；短时间内的变化可能返回 `rate_limited`，应在完成更多阶段工作后再保存。`ctx resume` 返回轻量摘要和按需使用的完整 details，并会保留其既有的 `lastUsedAt` 更新语义。
@@ -106,7 +158,11 @@ ctx doctor
 
 ### 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
@@ -187,6 +243,6 @@ npm pack --dry-run --json
 
 ## 当前范围
 
-0.3.1 聚焦单项目、本地优先的可靠闭环和 Agent 采用路径：有界 Orient、显式 checkpoint、确定性 Knowledge/Deadend discovery、MCP `context_orient` 与可选的 Claude Code Hook 集成。
+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 工具不属于当前版本范围。
+远程同步、多人协作、复杂语义检索、自动模型总结、自动 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

@@ -2,7 +2,10 @@ import { readdir } from 'node:fs/promises';
 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 } from '../runtime/runtime.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) {
@@ -157,7 +160,10 @@ export async function contextOrient(startPath, options = {}) {
         throw new Error('context orient query must not be empty');
     let loaded;
     try {
-        loaded = await resume(projectRoot, options.contextId, options.maxChars ?? 4000, { touchLastUsedAt: false });
+        const v2 = await selectV2Orientation(projectRoot, options.contextId);
+        loaded = v2
+            ? await resumeSnapshot(projectRoot, v2.contextId, v2.snapshotId, options.maxChars ?? 4000)
+            : await resume(projectRoot, options.contextId, options.maxChars ?? 4000, { touchLastUsedAt: false });
     }
     catch (error) {
         if (error instanceof Error && error.message === 'no active context found') {
@@ -172,26 +178,43 @@ 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;
     }
-    const notes = await listNotes(projectRoot, {
+    const v2 = await selectV2Orientation(projectRoot, options.contextId);
+    const notes = (await listNotes(projectRoot, {
         contextId: loaded.context.id,
         openOnly: true,
-        limit: options.noteLimit ?? 20,
+        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 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 knowledge = query === null
+    const applicableKnowledge = query === null
         ? emptyKnowledge('')
-        : await discoverKnowledge(projectRoot, query, {
+        : v2Knowledge?.result ?? await discoverKnowledge(projectRoot, query, {
             scope: options.scope,
             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: options.deadendLimit ?? 10,
             maxChars: options.maxChars ?? 4000,
@@ -214,8 +237,8 @@ export async function contextOrient(startPath, options = {}) {
         || textLength(resumeSummary.decisions) < textLength(loaded.resumeSummary.decisions)
         || textLength(resumeSummary.risks) < textLength(loaded.resumeSummary.risks)
         || textLength(resumeSummary.relatedFiles) < textLength(loaded.resumeSummary.relatedFiles);
-    const limitedKnowledgeResult = limitKnowledge(knowledge, budget);
-    const limitedDeadendResult = limitDeadends(deadends, budget);
+    const limitedKnowledgeResult = limitKnowledge(applicableKnowledge, budget);
+    const limitedDeadendResult = limitDeadends(applicableDeadends, budget);
     const limitedNotesResult = limitNotes(notes, budget);
     return {
         status: 'ready',
@@ -241,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

@@ -1,11 +1,18 @@
 #!/usr/bin/env node
 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) {
@@ -155,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.
@@ -178,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
@@ -192,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.`,
@@ -235,9 +268,51 @@ Options:
   --open                 Only open notes
   --limit <number>       Maximum items (default: 50)
   --max-chars <number>   Maximum message characters`,
+    migrate: `usage: ctx migrate v1 --dry-run|--apply [--path <path>]
+       ctx migrate verify [--path <path>]
+
+Inspect, explicitly import, or verify v1 Context data for the event-journal runtime.`,
+    'migrate v1': `usage: ctx migrate v1 --dry-run|--apply [--path <path>]
+
+Validate v1 Context, Snapshot, Note, Knowledge, and Deadend data for v2 migration.
+
+Options:
+  --dry-run              Inspect only; no v2 data is created
+  --apply                Explicitly append immutable v1 provenance events
+  --path <path>          Project path`,
+    'migrate verify': `usage: ctx migrate verify [--path <path>]
+
+Rebuild v2 projections and verify imported v1 parity.
+
+Options:
+  --path <path>          Project path`,
+    runtime: `usage: ctx runtime enable|disable|start|stop|status [--path <path>]
+
+Control the local event-driven Knowledge Runtime after v1 migration verification.`,
+    'runtime status': `usage: ctx runtime status [--path <path>]
+
+Show the read-only runtime policy, migration and authenticated lease status.
+
+Options:
+  --path <path>          Project path`,
+    'runtime enable': `usage: ctx runtime enable [--path <path>]
+
+Explicitly enable the migrated local Knowledge Runtime.`,
+    'runtime disable': `usage: ctx runtime disable [--path <path>]
+
+Stop the local runtime and disable future startup without deleting v2 history.`,
+    'runtime start': `usage: ctx runtime start [--path <path>]
+
+Start the enabled runtime as a loopback-only background process.`,
+    'runtime stop': `usage: ctx runtime stop [--path <path>]
+
+Stop the local runtime through authenticated loopback IPC.`,
+    'runtime serve': `usage: ctx runtime serve [--path <path>]
+
+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 [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.`;
 }
@@ -256,7 +331,17 @@ function printHelp(args) {
         process.stdout.write(`${usage()}\n`);
         return true;
     }
-    const key = args[1] === 'verify' || args[1] === 'add' || args[1] === 'list' || args[1] === 'discover' || args[1] === 'serve' || args[1] === 'claude' ? `${command} ${args[1]}` : command;
+    const nested = (command === 'agent' && args[1] === 'serve')
+        || (command === 'hook' && args[1] === 'claude-code')
+        || (command === 'integrate' && args[1] === 'claude')
+        || (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]));
+    const key = nested ? `${command} ${args[1]}` : command;
     const nestedKey = key === 'integrate claude' && (args[2] === 'inspect' || args[2] === 'install') ? `${key} ${args[2]}` : key;
     const help = HELP[nestedKey];
     if (!help)
@@ -370,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;
@@ -413,6 +501,69 @@ 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']);
+                validatePositionals(positionals(args.slice(2), ['--path']), 0, HELP['migrate v1']);
+                if (args.includes('--dry-run') === args.includes('--apply'))
+                    throw new Error(HELP['migrate v1']);
+                print(args.includes('--apply') ? await importV1(target) : await migrationReadiness(target));
+            }
+            else if (args[1] === 'verify') {
+                validateOptions(args.slice(2), ['--path'], ['--path']);
+                validatePositionals(positionals(args.slice(2), ['--path']), 0, HELP['migrate verify']);
+                print(await verifyV1Import(target));
+            }
+            else {
+                throw new Error(HELP.migrate);
+            }
+            return;
+        }
+        case 'runtime': {
+            if (!['enable', 'disable', 'start', 'stop', 'status', 'serve'].includes(args[1]))
+                throw new Error(HELP.runtime);
+            validateOptions(args.slice(2), ['--path'], ['--path']);
+            validatePositionals(positionals(args.slice(2), ['--path']), 0, HELP[`runtime ${args[1]}`]);
+            if (args[1] === 'enable')
+                print(await enableRuntime(target));
+            else if (args[1] === 'disable')
+                print(await disableRuntime(target));
+            else if (args[1] === 'start')
+                print(await startRuntime(target));
+            else if (args[1] === 'stop')
+                print(await stopRuntime(target));
+            else if (args[1] === 'status')
+                print(await runtimeStatus(target));
+            else {
+                const runtime = await serveRuntime(target);
+                process.once('SIGINT', () => { void runtime.close('signal'); });
+                process.once('SIGTERM', () => { void runtime.close('signal'); });
+                await new Promise(() => undefined);
+            }
+            return;
+        }
         case 'activity': {
             const valueOptions = ['--path', '--context', '--since', '--limit', '--max-chars'];
             validateOptions(args.slice(1), [...valueOptions, '--open'], valueOptions);
@@ -451,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);
@@ -466,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/git-observer.d.ts

@@ -0,0 +1,13 @@
+import { type GitWorktreeState } from '../git/git-adapter.js';
+export declare class GitObserver {
+    private readonly projectRoot;
+    private previous;
+    private pending;
+    constructor(projectRoot: string);
+    observeNow(): Promise<{
+        state: GitWorktreeState;
+        changed: boolean;
+    }>;
+    drain(): Promise<void>;
+    private observe;
+}