fluffy-context 0.5.0 → 0.7.2

package/dist/src/hooks/claude-code.js

@@ -1,11 +1,10 @@
 import { contextOrient } from '../agent/api.js';
 import { appendEvent } from '../cognition/journal.js';
 import { v2Enabled } from '../cognition/orient.js';
-import { startRuntime } from '../cognition/runtime.js';
+import { ensureRuntimeForSession, touchRuntime } from '../cognition/runtime.js';
+import { loadRuntimePolicy } from '../cognition/policy.js';
 import { readGitWorktreeState } from '../git/git-adapter.js';
 import { resolveProjectRoot } from '../project/project-resolver.js';
-import { cognitionPolicyPath } from '../storage/layout.js';
-import { readJson } from '../storage/json-store.js';
 const HOOK_RESPONSE = '{}\n';
 function text(value) {
     return typeof value === 'string' ? value : undefined;
@@ -68,15 +67,12 @@ function redactIntent(value) {
         .replace(/\b(?:sk|ghp|gho|github_pat)_[A-Za-z0-9_-]+\b/g, () => { redactionCount += 1; return '[REDACTED]'; });
     return { intent, redactionCount };
 }
-async function within(task, milliseconds) {
-    return Promise.race([task, new Promise((_, reject) => setTimeout(() => reject(new Error('hook deadline exceeded')), milliseconds))]);
-}
 async function capture(event, input) {
     const cwd = text(input.cwd);
     const projectRoot = await resolveProjectRoot(cwd);
     if (!await v2Enabled(projectRoot))
         return;
-    const policy = await readJson(cognitionPolicyPath(projectRoot));
+    const policy = await loadRuntimePolicy(projectRoot);
     const sessionId = stableId(input, 'session');
     const eventId = stableId(input, 'event');
     if (!sessionId || !eventId)
@@ -94,12 +90,7 @@ async function capture(event, input) {
     });
 }
 async function maybeStartRuntime(input) {
-    const projectRoot = await resolveProjectRoot(text(input.cwd));
-    if (!await v2Enabled(projectRoot))
-        return;
-    const policy = await readJson(cognitionPolicyPath(projectRoot));
-    if (policy.allowHookStartup)
-        await within(startRuntime(projectRoot), 1_000);
+    await ensureRuntimeForSession(text(input.cwd), { source: 'claude-hook', timeoutMs: 1_000 });
 }
 async function parseInput(raw) {
     try {
@@ -115,9 +106,10 @@ export async function runClaudeCodeHook(event, raw) {
     if (!input)
         return HOOK_RESPONSE;
     try {
-        if (event === 'session-start')
-            await maybeStartRuntime(input).catch(() => undefined);
+        await maybeStartRuntime(input).catch(() => undefined);
+        await touchRuntime(text(input.cwd)).catch(() => false);
         await capture(event, input).catch(() => undefined);
+        await touchRuntime(text(input.cwd)).catch(() => false);
         const cwd = text(input.cwd);
         const result = event === 'session-start'
             ? await contextOrient(cwd, { maxChars: 1200, noteLimit: 8 })

package/dist/src/mcp/main.js

@@ -1,5 +1,7 @@
 import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import { ensureRuntimeForSession } from '../cognition/runtime.js';
 import { createMcpServer } from './server.js';
+await ensureRuntimeForSession(process.cwd(), { source: 'mcp', timeoutMs: 1_000 }).catch(() => undefined);
 serveStdio(createMcpServer, {
     onerror: (error) => process.stderr.write(`MCP server error: ${error.message}\n`),
 });

package/dist/src/mcp/server.js

@@ -1,6 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 import { contextOrient } from '../agent/api.js';
+import { ensureRuntimeForSession } from '../cognition/runtime.js';
 import { VERSION } from '../version.js';
 const orientInput = z.object({
     path: z.string().optional(),
@@ -23,6 +24,7 @@ export function createMcpServer() {
         inputSchema: orientInput,
     }, async ({ path, ...options }) => {
         try {
+            await ensureRuntimeForSession(path, { source: 'mcp', timeoutMs: 1_000 }).catch(() => undefined);
             const result = await contextOrient(path, options);
             return {
                 content: [{ type: 'text', text: JSON.stringify(result) }],

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,10 +22,12 @@ 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;
 export declare function cognitionRuntimeLeasePath(projectRoot: string): string;
 export declare function cognitionRuntimeSecretPath(projectRoot: string): string;
+export declare function cognitionRuntimeStartupPath(projectRoot: string): string;
 export declare function cognitionV1SyncPath(projectRoot: string): string;
 export declare function cognitionQuarantineDirectory(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');
 }
@@ -86,6 +89,9 @@ export function cognitionRuntimeLeasePath(projectRoot) {
 export function cognitionRuntimeSecretPath(projectRoot) {
     return path.join(cognitionRuntimeDirectory(projectRoot), 'secret');
 }
+export function cognitionRuntimeStartupPath(projectRoot) {
+    return path.join(cognitionRuntimeDirectory(projectRoot), 'startup.json');
+}
 export function cognitionV1SyncPath(projectRoot) {
     return path.join(cognitionRuntimeDirectory(projectRoot), 'v1-sync.json');
 }

package/dist/src/version.d.ts

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

package/dist/src/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fluffy-context",
-  "version": "0.5.0",
+  "version": "0.7.2",
   "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",

package/skills/fluffy-context/SKILL.md

@@ -17,7 +17,8 @@ compatibility: 需要 Node.js >=20.19.0；Git 可选。CLI 通过 npm 全局安
 - 人类需要了解 Agent 发生了什么时使用 `ctx activity`；它是只读时间线，不要求人类参与 Agent 的高频记录操作。
 - 新会话与新任务优先运行 `ctx orient [query] --max-chars <预算>`；它只读地返回有界摘要、匹配的已验证共识和当前 Context 的 open Note，不会创建 Snapshot 或更新 `lastUsedAt`。
 - 仅需要完整详情时再运行 `ctx resume --max-chars <预算>`；它会保留既有的 `lastUsedAt` 更新语义。
-- Agent 集成从 `fluffy-context` 或 `fluffy-context/agent` 导入 `contextOrient`、`saveContext`、`loadContext` 和 `searchContext`，不应直接读写 `.context` 或导入内部 `dist/...` 路径。
+- Agent 集成从 `fluffy-context` 或 `fluffy-context/agent` 导入 `contextOrient`、`compileContext`、`saveContext`、`loadContext` 和 `searchContext`，不应直接读写 `.context` 或导入内部 `dist/...` 路径。
+- `ctx compile` 的 `activity` section 只表示 Runtime 观察到的近期文件 metadata 变化；它不代表文件被读取或理解，也不替代 checkpoint、Note 或已验证 Knowledge。
 - 新任务先发现已验证共识，再开始实现；候选项只在显式审查时使用。
 - 普通查询只使用已验证 Knowledge 和 Deadend；需要审查候选项时显式使用 `--all`。
 - CLI 业务命令的标准输出是 JSON；错误写入标准错误并返回非零退出码。解析输出时不要把 `--help` 的纯文本当作 JSON。