fluffy-context 0.7.6 → 0.8.0

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

@@ -1,4 +1,4 @@
-import type { CognitionGitAnchor, WorkspacePathChange } from '../cognition/types.js';
+import type { CognitionGitAnchor, CompilerRecipeSection, CompilerRecipeSource, WorkspacePathChange } from '../cognition/types.js';
 import type { ContextOrientResult } from '../agent/types.js';
 import type { Deadend, Knowledge, Note, ResumeSummary, StructuredContext } from '../runtime/types.js';
 export type ContextScenario = 'resume' | 'implementation' | 'debugging' | 'verification' | 'handoff' | 'exploration' | 'unknown';
@@ -155,8 +155,27 @@ export interface ContextManifestIdentity {
     selectedItemHashes: string[];
     tokenEstimate: ContextTokenEstimate;
 }
+export interface ContextRecipeParticipation {
+    recipeId: string;
+    contentHash: string;
+    interpreterVersion: 'recipe-interpreter-v1';
+    preferredSources: CompilerRecipeSource[];
+    preferredSections: CompilerRecipeSection[];
+    sectionBudgets: Partial<Record<ContextCandidateSection, number>>;
+}
+export interface ContextGraphParticipation {
+    derivationVersion: 'evidence-graph-v1';
+    projectionHash: string | null;
+    hops: 0 | 1 | 2;
+    seedNodeIds: string[];
+    selectedNodeIds: string[];
+    selectedEdgeIds: string[];
+    fallbackReason: string | null;
+}
 export interface ContextCompileOptions {
     contextId?: string;
+    recipeId?: string;
+    graphHops?: 0 | 1 | 2;
     query?: string;
     scenario?: ContextScenario;
     scope?: string;
@@ -201,7 +220,7 @@ export interface ContextExpandResult {
 }
 export interface ContextManifest {
     schemaVersion: 1;
-    compilerVersion: '0.7.6';
+    compilerVersion: '0.7.7';
     rankingVersion: 'compiler-ranking-v2';
     status: 'ready' | 'no_context';
     projectRoot: string;
@@ -227,6 +246,8 @@ export interface ContextManifest {
     budget: ContextBudgetReport;
     truncation: ContextTruncation;
     provenance: ContextManifestProvenance;
+    recipe?: ContextRecipeParticipation;
+    graph?: ContextGraphParticipation;
     text: string;
 }
 export type CompilerRecord = StructuredContext | Note | Knowledge | Deadend;

package/dist/src/mcp/server.js

@@ -1,8 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
-import { compileContext } from '../compiler/compile.js';
 import { addNote, listNotes } from '../runtime/notes.js';
-import { contextExpand, contextOrient, loadContext, saveContext } from '../agent/api.js';
+import { contextCompile, contextExpand, contextOrient, contextUsageReport, inspectRecipe, inspectSkill, listRecipes, listSkills, loadContext, materializeContextRecipe, materializeContextSkill, recordContextSkillInvocation, recordContextSkillOutcome, saveContext, transitionContextRecipe, transitionContextSkill, acceptContextEvolutionCandidate, inspectContextEvolutionProposal, listContextEvolutionProposals, proposeContextEvolution, transitionContextEvolutionProposal } from '../agent/api.js';
 import { ensureRuntimeForSession } from '../cognition/runtime.js';
 import { VERSION } from '../version.js';
 const orientInput = z.object({
@@ -22,6 +21,8 @@ const noteActor = z.enum(['agent', 'human']);
 const noteStatus = z.enum(['open', 'resolved']);
 const compileOptions = z.object({
     contextId: z.string().optional(),
+    recipeId: z.string().optional(),
+    graphHops: z.union([z.literal(0), z.literal(1), z.literal(2)]).optional(),
     query: z.string().optional(),
     scenario: scenario.optional(),
     scope: z.string().optional(),
@@ -84,6 +85,35 @@ const checkpointInput = z.object({
     risks: z.array(z.string()).optional(),
     relatedFiles: z.array(z.string()).optional(),
 });
+const usageReportInput = z.object({
+    path: z.string().optional(),
+    since: z.string().optional(),
+    until: z.string().optional(),
+    days: z.int().nonnegative().optional(),
+    month: z.string().optional(),
+    granularity: z.enum(['day', 'week', 'month']).optional(),
+    baselineTokens: z.number().nonnegative().optional(),
+    baselineSource: z.enum(['manual', 'recorded-control']).optional(),
+});
+const skillOutcome = z.enum(['success', 'failure', 'partial', 'irrelevant', 'unknown']);
+const recipeEntity = z.enum(['knowledge', 'deadend', 'skill', 'compiler-recipe', 'experience', 'proposal']);
+const recipeListInput = z.object({ path: z.string().optional() });
+const recipeInspectInput = z.object({ path: z.string().optional(), recipeId: z.string() });
+const recipeMaterializeInput = z.object({ path: z.string().optional(), proposalId: z.string(), title: z.string(), preferredSources: z.array(z.enum(['context', 'knowledge', 'deadend', 'note'])).optional(), preferredSections: z.array(z.enum(['summary', 'pending', 'decision', 'risk', 'note', 'knowledge', 'deadend', 'activity'])).optional(), sectionBudgets: z.record(z.string(), z.int().nonnegative().max(100_000)).optional() });
+const recipeTransitionInput = z.object({ path: z.string().optional(), recipeId: z.string(), to: z.enum(['verified', 'published', 'deprecated', 'superseded']), rationale: z.string(), supersedes: z.object({ entity: recipeEntity, entityId: z.string(), relation: z.literal('supersedes') }).optional() });
+const skillEntity = z.enum(['knowledge', 'deadend', 'skill', 'compiler-recipe', 'experience', 'proposal']);
+const skillListInput = z.object({ path: z.string().optional() });
+const skillInspectInput = z.object({ path: z.string().optional(), skillId: z.string() });
+const skillMaterializeInput = z.object({ path: z.string().optional(), proposalId: z.string(), title: z.string(), procedure: z.array(z.string()) });
+const skillTransitionInput = z.object({ path: z.string().optional(), skillId: z.string(), to: z.enum(['verified', 'published', 'deprecated', 'superseded']), rationale: z.string(), supersedes: z.object({ entity: skillEntity, entityId: z.string(), relation: z.literal('supersedes') }).optional() });
+const skillInvocationInput = z.object({ path: z.string().optional(), skillId: z.string(), invocationId: z.string(), callerEventId: z.string(), inputHash: z.string() });
+const skillOutcomeInput = z.object({ path: z.string().optional(), skillId: z.string(), invocationId: z.string(), outcomeId: z.string(), callerEventId: z.string(), outcome: skillOutcome, summary: z.string() });
+const evolutionEntity = z.enum(['knowledge', 'deadend', 'skill', 'compiler-recipe', 'experience', 'proposal']);
+const evolutionProposeInput = z.object({ path: z.string().optional(), eventIds: z.array(z.string()).min(1).max(32).optional(), recentLimit: z.int().nonnegative().max(32).optional(), targetKind: z.enum(['skill', 'compiler-recipe']).optional() });
+const evolutionListInput = z.object({ path: z.string().optional() });
+const evolutionInspectInput = z.object({ path: z.string().optional(), proposalId: z.string() });
+const evolutionAcceptInput = z.object({ path: z.string().optional(), proposalId: z.string(), rationale: z.string().min(1) });
+const evolutionTransitionInput = z.object({ path: z.string().optional(), proposalId: z.string(), to: z.enum(['verified', 'rejected', 'deprecated', 'superseded']), rationale: z.string().min(1), supersedes: z.object({ entity: evolutionEntity, entityId: z.string(), relation: z.literal('supersedes') }).optional() });
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -108,7 +138,7 @@ export function createMcpServer() {
     }, async ({ path, ...options }) => {
         try {
             await ensureRuntimeForSession(path, { source: 'mcp', timeoutMs: 1_000 }).catch(() => undefined);
-            return successResponse(await contextOrient(path, options));
+            return successResponse(await contextOrient(path, options, 'mcp'));
         }
         catch (error) {
             return failureResponse('context_orient', error);
@@ -121,7 +151,7 @@ export function createMcpServer() {
     }, async ({ path, ...input }) => {
         try {
             await ensureRuntimeForSession(path, { source: 'mcp', timeoutMs: 1_000 }).catch(() => undefined);
-            return successResponse(await contextExpand(path, input));
+            return successResponse(await contextExpand(path, input, 'mcp'));
         }
         catch (error) {
             return failureResponse('context_expand', error);
@@ -134,7 +164,7 @@ export function createMcpServer() {
     }, async ({ path, ...options }) => {
         try {
             await ensureRuntimeForSession(path, { source: 'mcp', timeoutMs: 1_000 }).catch(() => undefined);
-            return successResponse(await compileContext(path, options));
+            return successResponse(await contextCompile(path, options, 'mcp'));
         }
         catch (error) {
             return failureResponse('context_compile', error);
@@ -147,7 +177,7 @@ export function createMcpServer() {
     }, async ({ path, ...options }) => {
         try {
             await ensureRuntimeForSession(path, { source: 'mcp', timeoutMs: 1_000 }).catch(() => undefined);
-            return successResponse(await loadContext(path, options));
+            return successResponse(await loadContext(path, options, 'mcp'));
         }
         catch (error) {
             return failureResponse('context_resume', error);
@@ -179,6 +209,198 @@ export function createMcpServer() {
             return failureResponse('context_note_add', error);
         }
     });
+    server.registerTool('context_usage_report', {
+        title: 'Context usage report',
+        description: 'Build a read-only report of context assets, explicit reuse, estimated token investment, and operation metrics.',
+        inputSchema: usageReportInput,
+    }, async ({ path, ...options }) => {
+        try {
+            return successResponse(await contextUsageReport(path, options));
+        }
+        catch (error) {
+            return failureResponse('context_usage_report', error);
+        }
+    });
+    server.registerTool('recipe_list', {
+        title: 'List Recipes',
+        description: 'List immutable v2 compiler Recipes without modifying project state.',
+        inputSchema: recipeListInput,
+    }, async ({ path }) => {
+        try {
+            return successResponse(await listRecipes(path));
+        }
+        catch (error) {
+            return failureResponse('recipe_list', error);
+        }
+    });
+    server.registerTool('recipe_inspect', {
+        title: 'Inspect Recipe',
+        description: 'Inspect a compiler Recipe and its lifecycle.',
+        inputSchema: recipeInspectInput,
+    }, async ({ path, recipeId }) => {
+        try {
+            return successResponse(await inspectRecipe(path, recipeId));
+        }
+        catch (error) {
+            return failureResponse('recipe_inspect', error);
+        }
+    });
+    server.registerTool('recipe_materialize', {
+        title: 'Materialize Recipe',
+        description: 'Materialize a Recipe from an accepted compiler-recipe proposal.',
+        inputSchema: recipeMaterializeInput,
+    }, async ({ path, ...input }) => {
+        try {
+            return successResponse(await materializeContextRecipe(path, input));
+        }
+        catch (error) {
+            return failureResponse('recipe_materialize', error);
+        }
+    });
+    server.registerTool('recipe_transition', {
+        title: 'Transition Recipe',
+        description: 'Apply an explicit append-only Recipe lifecycle transition.',
+        inputSchema: recipeTransitionInput,
+    }, async ({ path, ...input }) => {
+        try {
+            return successResponse(await transitionContextRecipe(path, input));
+        }
+        catch (error) {
+            return failureResponse('recipe_transition', error);
+        }
+    });
+    server.registerTool('skill_list', {
+        title: 'List Skills',
+        description: 'List immutable v2 Skills without modifying project state.',
+        inputSchema: skillListInput,
+    }, async ({ path }) => {
+        try {
+            return successResponse(await listSkills(path));
+        }
+        catch (error) {
+            return failureResponse('skill_list', error);
+        }
+    });
+    server.registerTool('skill_inspect', {
+        title: 'Inspect Skill',
+        description: 'Inspect an immutable v2 Skill and its lifecycle without modifying project state.',
+        inputSchema: skillInspectInput,
+    }, async ({ path, skillId }) => {
+        try {
+            return successResponse(await inspectSkill(path, skillId));
+        }
+        catch (error) {
+            return failureResponse('skill_inspect', error);
+        }
+    });
+    server.registerTool('skill_materialize', {
+        title: 'Materialize Skill',
+        description: 'Materialize a Skill from an accepted candidate Skill proposal.',
+        inputSchema: skillMaterializeInput,
+    }, async ({ path, ...input }) => {
+        try {
+            return successResponse(await materializeContextSkill(path, input));
+        }
+        catch (error) {
+            return failureResponse('skill_materialize', error);
+        }
+    });
+    server.registerTool('skill_transition', {
+        title: 'Transition Skill',
+        description: 'Apply an explicit append-only Skill lifecycle transition.',
+        inputSchema: skillTransitionInput,
+    }, async ({ path, ...input }) => {
+        try {
+            return successResponse(await transitionContextSkill(path, input));
+        }
+        catch (error) {
+            return failureResponse('skill_transition', error);
+        }
+    });
+    server.registerTool('skill_record_invocation', {
+        title: 'Record Skill invocation',
+        description: 'Record a published Skill invocation using only an input hash.',
+        inputSchema: skillInvocationInput,
+    }, async ({ path, ...input }) => {
+        try {
+            return successResponse(await recordContextSkillInvocation(path, input));
+        }
+        catch (error) {
+            return failureResponse('skill_record_invocation', error);
+        }
+    });
+    server.registerTool('skill_record_outcome', {
+        title: 'Record Skill outcome',
+        description: 'Record one explicit terminal outcome for a Skill invocation.',
+        inputSchema: skillOutcomeInput,
+    }, async ({ path, ...input }) => {
+        try {
+            return successResponse(await recordContextSkillOutcome(path, input));
+        }
+        catch (error) {
+            return failureResponse('skill_record_outcome', error);
+        }
+    });
+    server.registerTool('evolution_propose', {
+        title: 'Propose Evolution',
+        description: 'Derive a bounded candidate Evolution proposal from authorized metadata.',
+        inputSchema: evolutionProposeInput,
+    }, async ({ path, ...input }) => {
+        try {
+            return successResponse(await proposeContextEvolution(path, input));
+        }
+        catch (error) {
+            return failureResponse('evolution_propose', error);
+        }
+    });
+    server.registerTool('evolution_list', {
+        title: 'List Evolution proposals',
+        description: 'List Evolution proposals without modifying project state.',
+        inputSchema: evolutionListInput,
+    }, async ({ path }) => {
+        try {
+            return successResponse(await listContextEvolutionProposals(path));
+        }
+        catch (error) {
+            return failureResponse('evolution_list', error);
+        }
+    });
+    server.registerTool('evolution_inspect', {
+        title: 'Inspect Evolution proposal',
+        description: 'Inspect one Evolution proposal and its lifecycle.',
+        inputSchema: evolutionInspectInput,
+    }, async ({ path, proposalId }) => {
+        try {
+            return successResponse(await inspectContextEvolutionProposal(path, proposalId));
+        }
+        catch (error) {
+            return failureResponse('evolution_inspect', error);
+        }
+    });
+    server.registerTool('evolution_accept', {
+        title: 'Accept Evolution candidate',
+        description: 'Accept a proposal into an immutable candidate artifact.',
+        inputSchema: evolutionAcceptInput,
+    }, async ({ path, ...input }) => {
+        try {
+            return successResponse(await acceptContextEvolutionCandidate(path, input));
+        }
+        catch (error) {
+            return failureResponse('evolution_accept', error);
+        }
+    });
+    server.registerTool('evolution_transition', {
+        title: 'Transition Evolution proposal',
+        description: 'Apply an explicit append-only Evolution proposal lifecycle transition.',
+        inputSchema: evolutionTransitionInput,
+    }, async ({ path, ...input }) => {
+        try {
+            return successResponse(await transitionContextEvolutionProposal(path, input));
+        }
+        catch (error) {
+            return failureResponse('evolution_transition', error);
+        }
+    });
     server.registerTool('context_checkpoint', {
         title: 'Checkpoint context',
         description: 'Explicitly save context progress and create a Snapshot when changes are present; runtime rate limits remain enforced.',

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

@@ -22,6 +22,11 @@ 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 cognitionExperiencesProjectionPath(projectRoot: string): string;
+export declare function cognitionProposalsProjectionPath(projectRoot: string): string;
+export declare function cognitionSkillsProjectionPath(projectRoot: string): string;
+export declare function cognitionRecipesProjectionPath(projectRoot: string): string;
+export declare function cognitionEvidenceGraphProjectionPath(projectRoot: string): string;
 export declare function cognitionRetrievalProjectionPath(projectRoot: string): string;
 export declare function cognitionMigrationsDirectory(projectRoot: string): string;
 export declare function cognitionV1ImportPath(projectRoot: string): string;

package/dist/src/storage/layout.js

@@ -71,6 +71,21 @@ export function cognitionDeadendsProjectionPath(projectRoot) {
 export function cognitionNotesProjectionPath(projectRoot) {
     return path.join(cognitionProjectionsDirectory(projectRoot), 'notes.json');
 }
+export function cognitionExperiencesProjectionPath(projectRoot) {
+    return path.join(cognitionProjectionsDirectory(projectRoot), 'experiences.json');
+}
+export function cognitionProposalsProjectionPath(projectRoot) {
+    return path.join(cognitionProjectionsDirectory(projectRoot), 'proposals.json');
+}
+export function cognitionSkillsProjectionPath(projectRoot) {
+    return path.join(cognitionProjectionsDirectory(projectRoot), 'skills.json');
+}
+export function cognitionRecipesProjectionPath(projectRoot) {
+    return path.join(cognitionProjectionsDirectory(projectRoot), 'recipes.json');
+}
+export function cognitionEvidenceGraphProjectionPath(projectRoot) {
+    return path.join(cognitionProjectionsDirectory(projectRoot), 'evidence-graph.json');
+}
 export function cognitionRetrievalProjectionPath(projectRoot) {
     return path.join(cognitionProjectionsDirectory(projectRoot), 'retrieval.json');
 }

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.7.6";
+export declare const VERSION = "0.8.0";

package/dist/src/version.js

@@ -1 +1 @@
-export const VERSION = '0.7.6';
+export const VERSION = '0.8.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fluffy-context",
-  "version": "0.7.6",
+  "version": "0.8.0",
   "description": "Local context management CLI and MCP tools for AI coding agents",
   "license": "MIT",
   "author": "FluffyChi-Xing",

package/skills/fluffy-context/SKILL.md

@@ -19,12 +19,19 @@ compatibility: 需要 Node.js >=20.19.0；Git 可选。CLI 通过 npm 全局安
 - 仅需要完整详情时再运行 `ctx resume --max-chars <预算>`；它会保留既有的 `lastUsedAt` 更新语义。
 - Agent 集成从 `fluffy-context` 或 `fluffy-context/agent` 导入 `contextOrient`、`compileContext`、`saveContext`、`loadContext` 和 `searchContext`，不应直接读写 `.context` 或导入内部 `dist/...` 路径。
 - `ctx compile` 的 `activity` section 只表示 Runtime 观察到的近期文件 metadata 变化；它不代表文件被读取或理解，也不替代 checkpoint、Note 或已验证 Knowledge。
-- 0.7.6 的 Compiler Manifest 提供稳定 `identity.manifestHash`、候选 `itemHash`、`tokenEstimate` 和 `level` 契约；默认输出 `summary` 层。
+- 只有显式传入已验证或已发布的 `--recipe-id <recipe-id>` 时，Recipe 才能影响一次编译；未指定时保持默认编译。Recipe 是受限声明式数据，不能执行命令、读取文件或替换核心排序。
+- 仅在需要时使用 `--graph-hops 0|1|2`；图只对已经词法命中的合规候选进行有界排序，图不可用时接受明确 fallback 并保持词法结果。
+- `ctx expand` 必须重传原始 `recipeId`、`graphHops` 和 compile budget；身份过期、Recipe 状态/内容/适用性变化时重新 compile，不要绕过 hash 校验。
+- 0.8.0 的 Compiler Manifest 提供稳定 `identity.manifestHash`、候选 `itemHash`、`tokenEstimate` 和 `level` 契约；默认输出 `summary` 层。
 - 只对 selected candidate 使用 `ctx expand --manifest-hash ... --candidate-id ... --level structured|evidence`。必须带上原始 compile 参数和相同的 compile budget；Manifest 过期时应重新 compile，不要绕过 hash 校验。
 - `expand` 是无状态、只读的渐进式展开：`complete` 才提供完整 `content`，`partial` 提供有界 `text` 且 `content` 为 null。它不写入 Context/journal、不记录 feedback、不读取项目文件正文、diff、命令输出或敏感数据。Agent API 使用 `contextExpand`，MCP 使用 `context_expand`。
 - 新任务先发现已验证共识，再开始实现；候选项只在显式审查时使用。
 - 普通查询只使用已验证 Knowledge 和 Deadend；需要审查候选项时显式使用 `--all`。
 - CLI 业务命令的标准输出是 JSON；错误写入标准错误并返回非零退出码。解析输出时不要把 `--help` 的纯文本当作 JSON。
+- 每周或每月复盘时使用 `ctx usage report`，不要为每条 prompt 运行；它只读 journal 和 v1 数据，不创建事件或修改项目状态。
+- Report 中的 `chars / 4` 是明确标注的 estimated token，不是真实 Provider token；Provider token 和计费金额当前 unavailable。
+- 只有显式 `record.used` 才算 Knowledge/Deadend reuse；compile 命中或 orient 返回不等于复用。
+- 没有显式 baseline 时，report 不生成 savings、ROI 或 payback 数字；report 不能替代 `doctor`、`journal verify` 或人工治理。
 
 ## 快速工作流
 
@@ -46,6 +53,21 @@ ctx learn ... / ctx deadend ... → 显式 verify
 
 `ctx orient` 不带查询时也有效，用于恢复当前任务和 open Note。带查询时只发现已验证的 Knowledge 与 Deadend；不要以候选项驱动普通实现。
 
+### Usage report
+
+在阶段性复盘、周报或月报时运行只读观测报告：
+
+```bash
+ctx usage report --days 30
+ctx usage report --month 2026-08 --granularity week
+ctx usage report --since 2026-08-01T00:00:00.000Z --until 2026-09-01T00:00:00.000Z --baseline-tokens 12000 --baseline-source manual
+ctx usage report --format ascii
+```
+
+JSON 是默认输出；`--format ascii` 仅用于终端展示。报告分别统计 v1 文件资产和 v2 journal 事件，展示 Knowledge、Deadend、Note、Context、Snapshot、显式 reuse、操作趋势与 estimated token 投入。`record.used` 是唯一的 reuse 信号，候选项命中、compile 选择和普通检索都不算复用。
+
+`--baseline-tokens` 必须是显式对照输入。未提供 baseline 时 savings、ROI 和 payback 为 `null` 或 `no_baseline`；字符换算不代表 Provider 真实 token，也不提供默认单价。报告失败时应使用 `ctx doctor` 与 `ctx journal verify` 进一步诊断，而不是把 report 当作数据修复工具。
+
 ### 初始化
 
 ```bash
@@ -101,11 +123,33 @@ ctx resume --path path/to/project --max-chars 2000
 
 遇到 `rate_limited` 时不要循环重试；完成更多阶段性工作后，在 `retryAt` 之后再保存。
 
-## MCP 与 Claude Code 集成
+### Evolution、Skill 与 Recipe
+
+Evolution 必须显式发起，并且只基于已授权的 journal、Git/workspace metadata 与 `record.used` 信号：
+
+```text
+Experience metadata → Evolution Proposal → accept → materialize → governed lifecycle
+```
+
+```bash
+ctx evolution propose --recent-limit 32 --target-kind skill
+ctx evolution list
+ctx evolution inspect <proposal-id>
+ctx evolution accept <proposal-id> --rationale "人工审查"
+ctx evolution verify <proposal-id> --rationale "确认可物化"
+ctx evolution supersede <proposal-id> --rationale "由新提案替换" --supersedes proposal:<predecessor-id>
+```
+
+- 不自动运行 `evolution propose`；它不读取项目源文件、原始 prompt、Note/Snapshot 内容，不创建 checkpoint，也不自动接受、验证、发布、物化或调用。
+- 接受 Proposal 仅创建候选工件。Skill/Recipe 仍需要显式物化和人工治理；候选从不进入默认 orient/compile/retrieval。
+- Skill 和 Recipe 都追加式经历 `candidate → verified → published → deprecated|superseded`；修改时用带 `supersedes` 谱系的新记录，不删除或覆盖旧记录。
+- 仅 `published` Skill 可以记录 invocation。调用只存输入 hash 与 caller event ID；每个 invocation 仅能写入一个 `success|failure|partial|irrelevant|unknown` 终态 outcome。不要执行 procedure 文本，也不要把原始输入写入 Note、journal 或命令参数。
+- 只有已物化、verified/published 且适用的 Recipe 可以作为 `--recipe-id` 参与 compile；不存在、候选、终态或不适用 Recipe 必须修正治理/选择，而非静默降级。
+
 
-`ctx agent serve` 提供 MCP stdio server，注册以下工具：`context_orient`、`context_expand`、`context_compile`、`context_resume`、`context_note_list`、`context_note_add` 和 `context_checkpoint`。标准输入和输出都是 MCP 协议，不能输出提示、日志或交互文本；调用错误是单次工具错误，不应让 server 退出。
+`ctx agent serve` 提供 MCP stdio server，注册 23 个工具：`context_orient`、`context_expand`、`context_compile`、`context_resume`、`context_note_list`、`context_note_add`、`context_usage_report`、`recipe_list`、`recipe_inspect`、`recipe_materialize`、`recipe_transition`、`skill_list`、`skill_inspect`、`skill_materialize`、`skill_transition`、`skill_record_invocation`、`skill_record_outcome`、`evolution_propose`、`evolution_list`、`evolution_inspect`、`evolution_accept`、`evolution_transition` 和 `context_checkpoint`。标准输入和输出都是 MCP 协议，不能输出提示、日志或交互文本；调用错误是单次工具错误，不应让 server 退出。
 
-读取工作流通常是 `context_orient → context_compile → context_expand`。`context_compile` 与 `context_expand` 继续保持有界、确定性和不读取文件正文的边界；`context_resume` 复用 `loadContext`，可能更新 `lastUsedAt`。`context_note_list` 是只读的，`context_note_add` 和 `context_checkpoint` 是显式写入操作，分别新增 Note 或保存 Snapshot；它们不会自动记录 feedback、Knowledge、Deadend 或重复 checkpoint。Knowledge/Deadend 的完整记录和治理仍使用 CLI/Agent API。
+读取工作流通常是 `context_orient → context_compile → context_expand`。`context_compile` 与 `context_expand` 保持有界、确定性且不读取文件正文，且可显式传递 `recipeId` 和 `graphHops: 0|1|2`；`context_resume` 复用 `loadContext`，可能更新 `lastUsedAt`。`context_note_list`、usage、Evolution/Skill/Recipe 的 list/inspect 是逻辑只读操作。`context_note_add`、`context_checkpoint`、Evolution 的 propose/accept/transition，以及 Skill/Recipe 的 materialize/transition/invocation/outcome 都是显式写入；不会自动执行 Skill/Recipe 或自动推进生命周期。
 
 ```bash
 ctx agent serve
@@ -341,7 +385,11 @@ ctx learn "订单取消后不能再次进入支付中状态"
 [ ] .contextignored 排除敏感和越界路径
 [ ] Knowledge candidate → verified
 [ ] Deadend candidate → verified
-[ ] MCP context_orient/context_expand/context_compile/context_resume/context_note_list/context_note_add/context_checkpoint 可调用，且单次错误不会终止 server
+[ ] Skill/Recipe candidate → verified → published 的显式治理，以及 supersedes 谱系
+[ ] 只调用 published Skill，且 invocation 不保存原始输入、每次仅一个 outcome
+[ ] MCP 23 个工具可调用，read-only 工具不逻辑创建认知记录，单次错误不会终止 server
+[ ] 显式 Recipe 与 graphHops 编译/展开保持 Manifest identity 校验和 lexical fallback
+[ ] ctx usage report 的 JSON/ASCII 输出、baseline 边界和只读性符合预期
 [ ] MCP 只读工具不写入 Context；Note add 和 checkpoint 仅在显式调用时写入
 [ ] Claude 集成预览不写文件，--apply 幂等且拒绝冲突
 [ ] Hook 失败时 fail open，且不会自动 checkpoint