fluffy-context 0.7.6 → 0.8.0

package/dist/src/cli/main.js

@@ -1,8 +1,7 @@
 #!/usr/bin/env node
-import { checkpoint, resume } from '../runtime/runtime.js';
-import { contextOrient } from '../agent/api.js';
-import { compileContext } from '../compiler/compile.js';
-import { contextExpand } from '../agent/api.js';
+import { checkpoint } from '../runtime/runtime.js';
+import { contextCompile, contextExpand, contextOrient, contextUsageReport, inspectRecipe, inspectSkill, listRecipes, listSkills, loadContext, materializeContextRecipe, materializeContextSkill, recordContextSkillInvocation, recordContextSkillOutcome, transitionContextRecipe, transitionContextSkill, acceptContextEvolutionCandidate, inspectContextEvolutionProposal, listContextEvolutionProposals, proposeContextEvolution, transitionContextEvolutionProposal } from '../agent/api.js';
+import { formatUsageReport } from '../cognition/usage-report.js';
 import { importV1, verifyV1Import } from '../cognition/migration-v1.js';
 import { recordUse } from '../cognition/feedback.js';
 import { verifyJournal } from '../cognition/journal.js';
@@ -75,6 +74,16 @@ function enumOption(args, name, values) {
         throw new Error(`${name} must be one of: ${values.join(', ')}`);
     return value;
 }
+function graphHopsOption(args) {
+    const value = option(args, '--graph-hops');
+    if (value === undefined)
+        return undefined;
+    if (value !== '0' && value !== '1' && value !== '2')
+        throw new Error('--graph-hops must be one of: 0, 1, 2');
+    return Number(value);
+}
+const recipeBudgets = (value) => value === undefined ? undefined : Object.fromEntries(value.split(',').map((item) => { const [section, budget] = item.split('=', 2); const parsed = Number(budget); if (!section || !Number.isSafeInteger(parsed) || parsed < 0 || parsed > 100_000)
+    throw new Error('--budgets must be section=non-negative-integer up to 100000'); return [section, parsed]; }));
 const HELP = {
     init: `usage: ctx init [path] [--path <path>]
 
@@ -82,6 +91,34 @@ Initialize the local .context runtime layout. Re-running init is safe.
 
 Options:
   --path <path>  Project path`,
+    usage: `usage: ctx usage report [options]
+
+Show read-only context asset, reuse, token investment, and operation metrics.
+
+Options:
+  --path <path>                  Project path
+  --since <ISO>                  Window start
+  --until <ISO>                  Window end
+  --days <number>                Rolling window length (default: 30)
+  --month <YYYY-MM>              Calendar month window
+  --granularity <value>          day|week|month
+  --format <value>               json|ascii (default: json)
+  --baseline-tokens <number>    Explicit comparison token count
+  --baseline-source <value>      manual|recorded-control`,
+    'usage report': `usage: ctx usage report [options]
+
+Show read-only context asset, reuse, token investment, and operation metrics.
+
+Options:
+  --path <path>                  Project path
+  --since <ISO>                  Window start
+  --until <ISO>                  Window end
+  --days <number>                Rolling window length (default: 30)
+  --month <YYYY-MM>              Calendar month window
+  --granularity <value>          day|week|month
+  --format <value>               json|ascii (default: json)
+  --baseline-tokens <number>    Explicit comparison token count
+  --baseline-source <value>      manual|recorded-control`,
     checkpoint: `usage: ctx checkpoint [options]
 
 Save structured work state as a baseline or incremental snapshot.
@@ -125,6 +162,8 @@ Compile bounded, provider-neutral context with source provenance and selection e
 Options:
   --path <path>              Project path
   --context <id>             Context ID
+  --recipe-id <id>           Explicit verified or published Recipe
+  --graph-hops <0|1|2>       Optional bounded evidence-graph traversal
   --scenario <scenario>      resume|implementation|debugging|verification|handoff|exploration|unknown
   --scope <scope>            Exact consensus scope
   --paths <paths>            Comma-separated project-relative paths
@@ -146,6 +185,8 @@ Options:
   --max-chars <number>       Maximum expanded characters
   --compile-max-chars <number> Original compile budget (default: 4000)
   --context <id>             Context ID
+  --recipe-id <id>           Explicit verified or published Recipe
+  --graph-hops <0|1|2>       Optional bounded evidence-graph traversal
   --query <text>             Original compile query
   --scenario <scenario>      resume|implementation|debugging|verification|handoff|exploration|unknown
   --scope <scope>            Exact consensus scope
@@ -161,7 +202,7 @@ Start an MCP stdio server for Agent integrations.
 Run "ctx agent serve --help" for details.`,
     'agent serve': `usage: ctx agent serve
 
-Start an MCP stdio server exposing context_orient, context_expand, context_compile, context_resume, context_note_list, context_note_add, and context_checkpoint tools.
+Start an MCP stdio server exposing context_orient, context_expand, context_compile, context_resume, context_note_list, context_note_add, context_usage_report, and context_checkpoint tools.
 
 The server owns standard input/output; do not use it interactively.`,
     hook: `usage: ctx hook claude-code session-start|user-prompt
@@ -259,6 +300,13 @@ 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.`,
+    skill: `usage: ctx skill list [--path <path>]
+       ctx skill inspect <skill-id> [--path <path>]
+       ctx skill materialize <proposal-id> --title <title> --procedure <steps> [--path <path>]
+       ctx skill verify|publish|deprecate <skill-id> --rationale <text> [--path <path>]
+       ctx skill supersede <skill-id> --rationale <text> --supersedes <entity:id> [--path <path>]
+       ctx skill invoke <skill-id> --invocation-id <id> --caller-event <id> --input-hash <hash> [--path <path>]
+       ctx skill outcome <skill-id> --invocation-id <id> --outcome-id <id> --caller-event <id> --outcome <value> --summary <text> [--path <path>]`,
     journal: `usage: ctx journal verify [--path <path>]
 
 Validate the v2 journal hash chain and replay projections in memory.`,
@@ -325,9 +373,49 @@ Rebuild v2 projections and verify imported v1 parity.
 
 Options:
   --path <path>          Project path`,
-    runtime: `usage: ctx runtime enable|disable|start|stop|status [--path <path>]
+    recipe: `usage: ctx recipe list|inspect|materialize|verify|publish|deprecate|supersede [options]
+
+List, inspect, materialize, or govern immutable compiler Recipes.
+
+Options:
+  --path <path>          Project path
+  --title <text>         Recipe title for materialize
+  --sources <items>      Comma-separated source preferences
+  --sections <items>     Comma-separated section preferences
+  --budgets <items>      Comma-separated section=characters budgets
+  --rationale <text>     Governance rationale
+  --supersedes <ref>     Superseding entity:id`,
+    'recipe verify': `usage: ctx recipe verify <recipe-id> --rationale <text> [--path <path>]
+
+Mark a candidate compiler Recipe as verified.`,
+    'recipe publish': `usage: ctx recipe publish <recipe-id> --rationale <text> [--path <path>]
+
+Publish a verified compiler Recipe.`,
+    'recipe deprecate': `usage: ctx recipe deprecate <recipe-id> --rationale <text> [--path <path>]
+
+Retire a compiler Recipe with an explicit governance reason.`,
+    'recipe supersede': `usage: ctx recipe supersede <recipe-id> --rationale <text> --supersedes <entity:id> [--path <path>]
+
+Supersede a compiler Recipe while retaining its history.`,
+    evolution: `usage: ctx evolution propose|list|inspect|accept|verify|reject|deprecate|supersede [options]
+
+Create and govern bounded, metadata-only Evolution proposals.
 
-Control the local event-driven Knowledge Runtime after v1 migration verification.`,
+Options:
+  --path <path>          Project path
+  --events <items>       Comma-separated source event IDs
+  --recent-limit <n>     Number of recent source events
+  --target-kind <kind>   skill|compiler-recipe
+  --rationale <text>     Governance rationale
+  --supersedes <ref>     Superseding entity:id`,
+    'evolution propose': `usage: ctx evolution propose [--events <event-id,...>|--recent-limit <n>] [--target-kind skill|compiler-recipe] [--path <path>]`,
+    'evolution list': `usage: ctx evolution list [--path <path>]`,
+    'evolution inspect': `usage: ctx evolution inspect <proposal-id> [--path <path>]`,
+    'evolution accept': `usage: ctx evolution accept <proposal-id> --rationale <text> [--path <path>]`,
+    'evolution verify': `usage: ctx evolution verify <proposal-id> --rationale <text> [--path <path>]`,
+    'evolution reject': `usage: ctx evolution reject <proposal-id> --rationale <text> [--path <path>]`,
+    'evolution deprecate': `usage: ctx evolution deprecate <proposal-id> --rationale <text> [--path <path>]`,
+    'evolution supersede': `usage: ctx evolution supersede <proposal-id> --rationale <text> --supersedes <entity:id> [--path <path>]`,
     filesystem: `usage: ctx filesystem enable|disable|status [--path <path>]
 
 Control whether the Runtime records filtered file metadata changes.`,
@@ -340,6 +428,9 @@ Disable filesystem change observation and restart a running Runtime.`,
     'filesystem status': `usage: ctx filesystem status [--path <path>]
 
 Show the filesystem observation policy and Runtime status.`,
+    runtime: `usage: ctx runtime enable|disable|start|stop|status [--path <path>]
+
+Control the local Knowledge Runtime lifecycle.`,
     'runtime status': `usage: ctx runtime status [--path <path>]
 
 Show the read-only runtime policy, migration and authenticated lease status.
@@ -363,7 +454,7 @@ Stop the local runtime through authenticated loopback IPC.`,
 Internal runtime daemon entry point.`,
 };
 function usage() {
-    return `usage: ctx init|checkpoint|resume|orient|compile|expand|agent|hook|integrate|status|doctor|learn|knowledge|deadend|deadends|note|activity|migrate|runtime|filesystem|feedback|journal [options]
+    return `usage: ctx init|checkpoint|resume|orient|compile|expand|usage|agent|hook|integrate|status|doctor|learn|knowledge|deadend|deadends|note|activity|migrate|runtime|filesystem|feedback|skill|recipe|evolution|journal [options]
 
 Run \"ctx <command> --help\" for command details.`;
 }
@@ -391,8 +482,10 @@ function printHelp(args) {
         || (command === 'journal' && args[1] === 'verify')
         || (command === 'note' && ['add', 'list'].includes(args[1]))
         || (command === 'migrate' && ['v1', 'verify'].includes(args[1]))
+        || (command === 'recipe' && ['list', 'inspect', 'materialize', 'verify', 'publish', 'deprecate', 'supersede'].includes(args[1]))
+        || (command === 'evolution' && ['propose', 'list', 'inspect', 'accept', 'verify', 'reject', 'deprecate', 'supersede'].includes(args[1]))
         || (command === 'runtime' && ['enable', 'disable', 'start', 'stop', 'status', 'serve'].includes(args[1]))
-        || (command === 'filesystem' && ['enable', 'disable', 'status'].includes(args[1]));
+        || (command === 'usage' && args[1] === 'report');
     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];
@@ -450,7 +543,7 @@ async function run(args) {
         case 'resume':
             validateOptions(args.slice(1), ['--path', '--context', '--max-chars'], ['--path', '--context', '--max-chars']);
             validatePositionals(positionals(args.slice(1), ['--path', '--context', '--max-chars']), 0, HELP.resume);
-            print(await resume(target, option(args, '--context'), numericOption(args, '--max-chars', 4000)));
+            print(await loadContext(target, { contextId: option(args, '--context'), maxChars: numericOption(args, '--max-chars', 4000) }, 'cli'));
             return;
         case 'orient': {
             const valueOptions = ['--path', '--context', '--scope', '--max-chars', '--knowledge-limit', '--deadend-limit', '--note-limit'];
@@ -466,16 +559,18 @@ async function run(args) {
                 knowledgeLimit: numericOption(args, '--knowledge-limit', 10),
                 deadendLimit: numericOption(args, '--deadend-limit', 10),
                 noteLimit: numericOption(args, '--note-limit', 20),
-            }));
+            }, 'cli'));
             return;
         }
         case 'compile': {
-            const valueOptions = ['--path', '--context', '--scenario', '--scope', '--paths', '--max-chars', '--knowledge-limit', '--deadend-limit', '--note-limit', '--activity-limit'];
+            const valueOptions = ['--path', '--context', '--recipe-id', '--graph-hops', '--scenario', '--scope', '--paths', '--max-chars', '--knowledge-limit', '--deadend-limit', '--note-limit', '--activity-limit'];
             validateOptions(args.slice(1), valueOptions, valueOptions);
             const query = positionals(args.slice(1), valueOptions);
             validatePositionals(query, 1, HELP.compile);
-            print(await compileContext(target, {
+            print(await contextCompile(target, {
                 contextId: option(args, '--context'),
+                recipeId: option(args, '--recipe-id'),
+                graphHops: graphHopsOption(args),
                 query: query[0],
                 scenario: enumOption(args, '--scenario', ['resume', 'implementation', 'debugging', 'verification', 'handoff', 'exploration', 'unknown']),
                 scope: option(args, '--scope'),
@@ -485,11 +580,11 @@ async function run(args) {
                 deadendLimit: numericOption(args, '--deadend-limit', 10),
                 noteLimit: numericOption(args, '--note-limit', 20),
                 activityLimit: numericOption(args, '--activity-limit', 20),
-            }));
+            }, 'cli'));
             return;
         }
         case 'expand': {
-            const valueOptions = ['--path', '--manifest-hash', '--candidate-id', '--item-hash', '--level', '--max-chars', '--compile-max-chars', '--context', '--query', '--scenario', '--scope', '--paths', '--knowledge-limit', '--deadend-limit', '--note-limit', '--activity-limit'];
+            const valueOptions = ['--path', '--manifest-hash', '--candidate-id', '--item-hash', '--level', '--max-chars', '--compile-max-chars', '--context', '--recipe-id', '--graph-hops', '--query', '--scenario', '--scope', '--paths', '--knowledge-limit', '--deadend-limit', '--note-limit', '--activity-limit'];
             validateOptions(args.slice(1), valueOptions, valueOptions);
             validatePositionals(positionals(args.slice(1), valueOptions), 0, HELP.expand);
             const level = enumOption(args, '--level', ['structured', 'evidence']);
@@ -508,6 +603,8 @@ async function run(args) {
                 maxChars: option(args, '--max-chars') === undefined ? undefined : numericOption(args, '--max-chars', 0),
                 compile: {
                     contextId: option(args, '--context'),
+                    recipeId: option(args, '--recipe-id'),
+                    graphHops: graphHopsOption(args),
                     query: option(args, '--query'),
                     scenario: enumOption(args, '--scenario', ['resume', 'implementation', 'debugging', 'verification', 'handoff', 'exploration', 'unknown']),
                     scope: option(args, '--scope'),
@@ -521,6 +618,27 @@ async function run(args) {
             }));
             return;
         }
+        case 'usage': {
+            if (args[1] !== 'report')
+                throw new Error(HELP.usage);
+            const valueOptions = ['--path', '--since', '--until', '--days', '--month', '--granularity', '--format', '--baseline-tokens', '--baseline-source'];
+            validateOptions(args.slice(2), valueOptions, valueOptions);
+            validatePositionals(positionals(args.slice(2), valueOptions), 0, HELP['usage report']);
+            const report = await contextUsageReport(target, {
+                since: option(args, '--since'),
+                until: option(args, '--until'),
+                days: option(args, '--days') === undefined ? undefined : numericOption(args, '--days', 30),
+                month: option(args, '--month'),
+                granularity: enumOption(args, '--granularity', ['day', 'week', 'month']),
+                baselineTokens: option(args, '--baseline-tokens') === undefined ? undefined : numericOption(args, '--baseline-tokens', 0),
+                baselineSource: enumOption(args, '--baseline-source', ['manual', 'recorded-control']),
+            });
+            if (enumOption(args, '--format', ['json', 'ascii']) === 'ascii')
+                process.stdout.write(formatUsageReport(report));
+            else
+                print(report);
+            return;
+        }
         case 'agent':
             if (args[1] !== 'serve')
                 throw new Error(HELP.agent);
@@ -630,6 +748,174 @@ async function run(args) {
             }
             return;
         }
+        case 'skill': {
+            const action = args[1];
+            if (action === 'list') {
+                validateOptions(args.slice(2), ['--path'], ['--path']);
+                validatePositionals(positionals(args.slice(2), ['--path']), 0, HELP.skill);
+                print(await listSkills(target));
+                return;
+            }
+            if (!action)
+                throw new Error(HELP.skill);
+            const skillId = positionals(args.slice(2), ['--path', '--title', '--procedure', '--rationale', '--supersedes', '--invocation-id', '--caller-event', '--input-hash', '--outcome-id', '--outcome', '--summary'])[0];
+            if (action === 'inspect') {
+                validateOptions(args.slice(2), ['--path'], ['--path']);
+                const values = positionals(args.slice(2), ['--path']);
+                if (values.length !== 1)
+                    throw new Error(HELP.skill);
+                print(await inspectSkill(target, values[0]));
+                return;
+            }
+            if (action === 'materialize') {
+                const options = ['--path', '--title', '--procedure'];
+                validateOptions(args.slice(2), options, options);
+                const values = positionals(args.slice(2), options);
+                if (values.length !== 1)
+                    throw new Error(HELP.skill);
+                print(await materializeContextSkill(target, { proposalId: values[0], title: option(args, '--title') ?? '', procedure: listOption(args, '--procedure') ?? [] }));
+                return;
+            }
+            if (['verify', 'publish', 'deprecate', 'supersede'].includes(action)) {
+                const options = ['--path', '--rationale', '--supersedes'];
+                validateOptions(args.slice(2), options, options);
+                const values = positionals(args.slice(2), options);
+                if (values.length !== 1)
+                    throw new Error(HELP.skill);
+                const supersedes = option(args, '--supersedes');
+                const [entity, entityId] = supersedes?.split(':', 2) ?? [];
+                if (action === 'supersede' && (!entity || !entityId || !['knowledge', 'deadend', 'skill', 'compiler-recipe', 'experience', 'proposal'].includes(entity)))
+                    throw new Error('--supersedes must be <entity:id>');
+                print(await transitionContextSkill(target, {
+                    skillId: values[0],
+                    to: action === 'supersede' ? 'superseded' : action,
+                    rationale: option(args, '--rationale') ?? '',
+                    ...(supersedes ? { supersedes: { entity: entity, entityId: entityId, relation: 'supersedes' } } : {}),
+                }));
+                return;
+            }
+            if (action === 'invoke') {
+                const options = ['--path', '--invocation-id', '--caller-event', '--input-hash'];
+                validateOptions(args.slice(2), options, options);
+                const values = positionals(args.slice(2), options);
+                if (values.length !== 1)
+                    throw new Error(HELP.skill);
+                print(await recordContextSkillInvocation(target, { skillId: values[0], invocationId: option(args, '--invocation-id') ?? '', callerEventId: option(args, '--caller-event') ?? '', inputHash: option(args, '--input-hash') ?? '' }));
+                return;
+            }
+            if (action === 'outcome') {
+                const options = ['--path', '--invocation-id', '--outcome-id', '--caller-event', '--outcome', '--summary'];
+                validateOptions(args.slice(2), options, options);
+                const values = positionals(args.slice(2), options);
+                if (values.length !== 1)
+                    throw new Error(HELP.skill);
+                print(await recordContextSkillOutcome(target, { skillId: values[0], invocationId: option(args, '--invocation-id') ?? '', outcomeId: option(args, '--outcome-id') ?? '', callerEventId: option(args, '--caller-event') ?? '', outcome: enumOption(args, '--outcome', ['success', 'failure', 'partial', 'irrelevant', 'unknown']) ?? 'unknown', summary: option(args, '--summary') ?? '' }));
+                return;
+            }
+            void skillId;
+            throw new Error(HELP.skill);
+        }
+        case 'evolution': {
+            const action = args[1];
+            const valueOptions = ['--path', '--events', '--recent-limit', '--target-kind', '--rationale', '--supersedes'];
+            if (action === 'propose') {
+                validateOptions(args.slice(2), valueOptions.slice(0, 4), valueOptions.slice(0, 4));
+                validatePositionals(positionals(args.slice(2), valueOptions.slice(0, 4)), 0, HELP['evolution propose']);
+                if (option(args, '--events') !== undefined && option(args, '--recent-limit') !== undefined)
+                    throw new Error('use either --events or --recent-limit');
+                const eventIds = listOption(args, '--events');
+                if (eventIds && (eventIds.length === 0 || eventIds.length > 32))
+                    throw new Error('--events must contain 1 to 32 event IDs');
+                print(await proposeContextEvolution(target, { eventIds, recentLimit: option(args, '--recent-limit') === undefined ? undefined : numericOption(args, '--recent-limit', 32), targetKind: enumOption(args, '--target-kind', ['skill', 'compiler-recipe']) }));
+                return;
+            }
+            if (action === 'list') {
+                validateOptions(args.slice(2), ['--path'], ['--path']);
+                validatePositionals(positionals(args.slice(2), ['--path']), 0, HELP['evolution list']);
+                print(await listContextEvolutionProposals(target));
+                return;
+            }
+            const values = positionals(args.slice(2), valueOptions);
+            if (action === 'inspect') {
+                validateOptions(args.slice(2), ['--path'], ['--path']);
+                if (values.length !== 1)
+                    throw new Error(HELP['evolution inspect']);
+                print(await inspectContextEvolutionProposal(target, values[0]));
+                return;
+            }
+            if (['accept', 'verify', 'reject', 'deprecate', 'supersede'].includes(action ?? '')) {
+                validateOptions(args.slice(2), valueOptions, valueOptions);
+                if (values.length !== 1)
+                    throw new Error(HELP[`evolution ${action}`]);
+                const rationale = option(args, '--rationale') ?? '';
+                if (!rationale.trim())
+                    throw new Error('--rationale is required');
+                const supersedes = option(args, '--supersedes');
+                const [entity, entityId] = supersedes?.split(':', 2) ?? [];
+                if (action === 'supersede' && (!entity || !entityId || !['knowledge', 'deadend', 'skill', 'compiler-recipe', 'experience', 'proposal'].includes(entity)))
+                    throw new Error('--supersedes must be <entity:id>');
+                if (action === 'accept')
+                    print(await acceptContextEvolutionCandidate(target, { proposalId: values[0], rationale }));
+                else {
+                    const to = action === 'verify' ? 'verified'
+                        : action === 'supersede' ? 'superseded'
+                            : action;
+                    print(await transitionContextEvolutionProposal(target, { proposalId: values[0], to, rationale, ...(supersedes ? { supersedes: { entity: entity, entityId: entityId, relation: 'supersedes' } } : {}) }));
+                }
+                return;
+            }
+            throw new Error(HELP.evolution);
+        }
+        case 'recipe': {
+            const action = args[1];
+            const valueOptions = ['--path', '--title', '--sources', '--sections', '--budgets', '--rationale', '--supersedes'];
+            if (action === 'list') {
+                validateOptions(args.slice(2), ['--path'], ['--path']);
+                validatePositionals(positionals(args.slice(2), ['--path']), 0, HELP.recipe);
+                print(await listRecipes(target));
+                return;
+            }
+            if (action === 'inspect') {
+                validateOptions(args.slice(2), ['--path'], ['--path']);
+                const values = positionals(args.slice(2), ['--path']);
+                if (values.length !== 1)
+                    throw new Error(HELP.recipe);
+                print(await inspectRecipe(target, values[0]));
+                return;
+            }
+            if (action === 'materialize') {
+                validateOptions(args.slice(2), valueOptions, valueOptions);
+                const values = positionals(args.slice(2), valueOptions);
+                if (values.length !== 1)
+                    throw new Error(HELP.recipe);
+                print(await materializeContextRecipe(target, {
+                    proposalId: values[0],
+                    title: option(args, '--title') ?? '',
+                    preferredSources: listOption(args, '--sources'),
+                    preferredSections: listOption(args, '--sections'),
+                    sectionBudgets: recipeBudgets(option(args, '--budgets')),
+                }));
+                return;
+            }
+            if (['verify', 'publish', 'deprecate', 'supersede'].includes(action ?? '')) {
+                validateOptions(args.slice(2), ['--path', '--rationale', '--supersedes'], ['--path', '--rationale', '--supersedes']);
+                const values = positionals(args.slice(2), ['--path', '--rationale', '--supersedes']);
+                if (values.length !== 1)
+                    throw new Error(HELP.recipe);
+                const supersedes = option(args, '--supersedes');
+                const [entity, entityId] = supersedes?.split(':', 2) ?? [];
+                if (action === 'supersede' && (!entity || !entityId || !['knowledge', 'deadend', 'skill', 'compiler-recipe', 'experience', 'proposal'].includes(entity)))
+                    throw new Error('--supersedes must be <entity:id>');
+                print(await transitionContextRecipe(target, {
+                    recipeId: values[0],
+                    to: action === 'supersede' ? 'superseded' : action,
+                    rationale: option(args, '--rationale') ?? '',
+                    ...(supersedes ? { supersedes: { entity: entity, entityId: entityId, relation: 'supersedes' } } : {}),
+                }));
+                return;
+            }
+            throw new Error(HELP.recipe);
+        }
         case 'journal': {
             if (args[1] !== 'verify')
                 throw new Error(HELP.journal);

package/dist/src/cognition/evidence-graph.d.ts

@@ -0,0 +1,4 @@
+import type { CognitionEvent, CognitionGitAnchor, EvidenceGraphProjection } from './types.js';
+export declare const EVIDENCE_GRAPH_DERIVATION_VERSION: "evidence-graph-v1";
+export declare function workspaceNodeId(anchor: Pick<CognitionGitAnchor, 'worktreeId' | 'branch' | 'ref'>): string;
+export declare function buildEvidenceGraph(events: CognitionEvent[]): EvidenceGraphProjection;

package/dist/src/cognition/evidence-graph.js

@@ -0,0 +1,187 @@
+import crypto from 'node:crypto';
+export const EVIDENCE_GRAPH_DERIVATION_VERSION = 'evidence-graph-v1';
+function hash(value) {
+    return crypto.createHash('sha256').update(JSON.stringify(value)).digest('hex');
+}
+function record(event) {
+    const value = event.payload.record;
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+function normalizePath(value) {
+    const normalized = value.replaceAll('\\', '/');
+    return normalized.length > 0 && !normalized.startsWith('/') && !normalized.includes('\0') && !normalized.split('/').includes('..') ? normalized : null;
+}
+function entityKind(entity) {
+    if (entity === 'compiler-recipe')
+        return 'recipe';
+    if (entity === 'knowledge' || entity === 'deadend' || entity === 'skill' || entity === 'experience' || entity === 'proposal')
+        return entity;
+    return null;
+}
+function entityNodeId(entity, entityId) {
+    const kind = entityKind(entity);
+    return kind && entityId.trim().length > 0 ? `${kind}:${entityId}` : null;
+}
+export function workspaceNodeId(anchor) {
+    return `branch-worktree:${hash({ worktreeId: anchor.worktreeId, branch: anchor.branch, ref: anchor.ref }).slice(0, 16)}`;
+}
+function addNode(nodes, nodeId, kind) {
+    nodes.set(nodeId, { nodeId, kind });
+}
+function addEntityNode(nodes, entity, entityId) {
+    const nodeId = entityNodeId(entity, entityId);
+    const kind = entityKind(entity);
+    if (nodeId && kind)
+        addNode(nodes, nodeId, kind);
+    return nodeId;
+}
+function addEdge(edges, input) {
+    const sourceEventIds = [...new Set(input.sourceEventIds)].sort();
+    const basis = { from: input.from, to: input.to, type: input.type, sourceEventIds, occurredAt: input.occurredAt, confidence: input.confidence };
+    const edgeId = `edge:${hash(basis).slice(0, 24)}`;
+    edges.set(edgeId, { ...input, edgeId, sourceEventIds, derivationVersion: EVIDENCE_GRAPH_DERIVATION_VERSION });
+}
+function anchorNodes(event, nodes) {
+    const workspace = workspaceNodeId(event.git);
+    addNode(nodes, workspace, 'branch-worktree');
+    if (event.git.head)
+        addNode(nodes, `commit:${event.git.head}`, 'commit');
+    return workspace;
+}
+function lineageEdge(edges, nodes, from, lineage, event) {
+    const target = addEntityNode(nodes, lineage.entity, lineage.entityId);
+    if (!target)
+        return;
+    addEdge(edges, { from, to: target, type: lineage.relation, sourceEventIds: [event.eventId], occurredAt: event.occurredAt });
+}
+function sourceLinks(edges, nodes, from, contextIds, snapshotIds, event) {
+    if (Array.isArray(contextIds))
+        for (const contextId of contextIds)
+            if (typeof contextId === 'string' && contextId.trim()) {
+                const target = `context:${contextId}`;
+                addNode(nodes, target, 'context');
+                addEdge(edges, { from, to: target, type: 'derived_from', sourceEventIds: [event.eventId], occurredAt: event.occurredAt });
+            }
+    if (Array.isArray(snapshotIds))
+        for (const snapshotId of snapshotIds)
+            if (typeof snapshotId === 'string' && snapshotId.trim()) {
+                const target = `snapshot:${snapshotId}`;
+                addNode(nodes, target, 'snapshot');
+                addEdge(edges, { from, to: target, type: 'derived_from', sourceEventIds: [event.eventId], occurredAt: event.occurredAt });
+            }
+}
+export function buildEvidenceGraph(events) {
+    const nodes = new Map();
+    const edges = new Map();
+    for (const event of events) {
+        const workspace = anchorNodes(event, nodes);
+        if (event.git.head)
+            addEdge(edges, { from: workspace, to: `commit:${event.git.head}`, type: 'changed_in', sourceEventIds: [event.eventId], occurredAt: event.occurredAt });
+        const value = record(event);
+        if (event.type === 'context.checkpoint.imported' || event.type === 'context.state.recorded') {
+            const snapshot = value?.snapshot;
+            if (snapshot && typeof snapshot.contextId === 'string' && typeof snapshot.snapshotId === 'string') {
+                const context = `context:${snapshot.contextId}`;
+                const snap = `snapshot:${snapshot.snapshotId}`;
+                addNode(nodes, context, 'context');
+                addNode(nodes, snap, 'snapshot');
+                addEdge(edges, { from: context, to: snap, type: 'derived_from', sourceEventIds: [event.eventId], occurredAt: event.occurredAt });
+            }
+        }
+        if (event.type === 'experience.recorded' && typeof value?.experienceId === 'string') {
+            const id = addEntityNode(nodes, 'experience', value.experienceId);
+            sourceLinks(edges, nodes, id, value.sourceContextIds, value.sourceSnapshotIds, event);
+            if (Array.isArray(value.paths))
+                for (const item of value.paths)
+                    if (typeof item === 'string') {
+                        const path = normalizePath(item);
+                        if (!path)
+                            continue;
+                        const target = `path:${path}`;
+                        addNode(nodes, target, 'path');
+                        addEdge(edges, { from: id, to: target, type: 'observed_in', sourceEventIds: [event.eventId], occurredAt: event.occurredAt });
+                    }
+        }
+        if (event.type === 'evolution.proposed' && typeof value?.proposalId === 'string') {
+            const id = addEntityNode(nodes, 'proposal', value.proposalId);
+            if (Array.isArray(value.sourceExperienceIds))
+                for (const source of value.sourceExperienceIds)
+                    if (typeof source === 'string') {
+                        const target = addEntityNode(nodes, 'experience', source);
+                        if (target)
+                            addEdge(edges, { from: id, to: target, type: 'derived_from', sourceEventIds: [event.eventId], occurredAt: event.occurredAt });
+                    }
+            if (Array.isArray(value.lineage))
+                for (const item of value.lineage)
+                    if (item && typeof item === 'object')
+                        lineageEdge(edges, nodes, id, item, event);
+        }
+        if (['knowledge.proposed', 'knowledge.verified', 'knowledge.deprecated', 'knowledge.rejected'].includes(event.type) && typeof value?.knowledgeId === 'string') {
+            const id = addEntityNode(nodes, 'knowledge', value.knowledgeId);
+            sourceLinks(edges, nodes, id, value.sourceContextIds, value.sourceSnapshotIds, event);
+        }
+        if (['deadend.proposed', 'deadend.verified', 'deadend.obsoleted', 'deadend.rejected'].includes(event.type) && typeof value?.deadendId === 'string') {
+            const id = addEntityNode(nodes, 'deadend', value.deadendId);
+            sourceLinks(edges, nodes, id, value.sourceContextId === null ? [] : [value.sourceContextId], value.sourceSnapshotId === null ? [] : [value.sourceSnapshotId], event);
+        }
+        if (event.type === 'skill.materialized' && typeof value?.skillId === 'string') {
+            const id = addEntityNode(nodes, 'skill', value.skillId);
+            const proposal = typeof value.proposalId === 'string' ? addEntityNode(nodes, 'proposal', value.proposalId) : null;
+            if (proposal)
+                addEdge(edges, { from: id, to: proposal, type: 'derived_from', sourceEventIds: [event.eventId], occurredAt: event.occurredAt });
+            if (Array.isArray(value.lineage))
+                for (const item of value.lineage)
+                    if (item && typeof item === 'object')
+                        lineageEdge(edges, nodes, id, item, event);
+        }
+        if (event.type === 'recipe.materialized' && typeof value?.recipeId === 'string') {
+            const id = addEntityNode(nodes, 'compiler-recipe', value.recipeId);
+            const proposal = typeof value.proposalId === 'string' ? addEntityNode(nodes, 'proposal', value.proposalId) : null;
+            if (proposal)
+                addEdge(edges, { from: id, to: proposal, type: 'derived_from', sourceEventIds: [event.eventId], occurredAt: event.occurredAt });
+            if (Array.isArray(value.lineage))
+                for (const item of value.lineage)
+                    if (item && typeof item === 'object')
+                        lineageEdge(edges, nodes, id, item, event);
+        }
+        if (event.type === 'evolution.superseded') {
+            const transition = event.payload.transition;
+            if (transition && typeof transition === 'object' && !Array.isArray(transition)) {
+                const value = transition;
+                const from = typeof value.entity === 'string' && typeof value.entityId === 'string' ? addEntityNode(nodes, value.entity, value.entityId) : null;
+                const supersedes = value.supersedes;
+                if (from && supersedes && typeof supersedes === 'object' && !Array.isArray(supersedes)) {
+                    const reference = supersedes;
+                    lineageEdge(edges, nodes, from, reference, event);
+                }
+            }
+        }
+        if (event.type === 'workspace.paths.changed') {
+            const payload = event.payload;
+            if (Array.isArray(payload.paths))
+                for (const item of payload.paths)
+                    if (typeof item === 'string') {
+                        const path = normalizePath(item);
+                        if (!path)
+                            continue;
+                        const target = `path:${path}`;
+                        addNode(nodes, target, 'path');
+                        addEdge(edges, { from: workspace, to: target, type: 'observed_in', sourceEventIds: [event.eventId], occurredAt: event.occurredAt });
+                    }
+        }
+        if (event.type === 'record.used') {
+            const used = event.payload;
+            if (typeof used.entity === 'string' && typeof used.entityId === 'string') {
+                const from = addEntityNode(nodes, used.entity, used.entityId);
+                if (from)
+                    addEdge(edges, { from, to: workspace, type: 'used_for', sourceEventIds: [event.eventId], occurredAt: event.occurredAt });
+            }
+        }
+    }
+    return {
+        schemaVersion: 1,
+        derivationVersion: EVIDENCE_GRAPH_DERIVATION_VERSION,
+        nodes: [...nodes.values()].sort((a, b) => a.nodeId.localeCompare(b.nodeId)),
+        edges: [...edges.values()].sort((a, b) => a.edgeId.localeCompare(b.edgeId)),
+    };
+}