fluffy-context 0.7.7 → 1.0.0-beta.1

package/dist/src/cli/main.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import { checkpoint } from '../runtime/runtime.js';
-import { contextCompile, contextExpand, contextOrient, contextUsageReport, loadContext } from '../agent/api.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';
+import { compactJournal, verifyJournal } from '../cognition/journal.js';
 import { projectEvents } from '../cognition/projections.js';
 import { disableRuntime, enableRuntime, ensureRuntimeForSession, runtimeStatus, serveRuntime, setFilesystemEvents, startRuntime, stopRuntime } from '../cognition/runtime.js';
 import { loadRuntimePolicy } from '../cognition/policy.js';
@@ -13,7 +13,9 @@ 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 { setupProject } from '../runtime/setup.js';
+import { importMemory } from '../cognition/import-memory.js';
+import { injectContext } from '../compiler/inject.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';
@@ -74,13 +76,35 @@ 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>]
+    init: `usage: ctx init [path] [--path <path>] [--no-start] [--no-integrations]
 
-Initialize the local .context runtime layout. Re-running init is safe.
+Initialize, migrate, verify, install project guidance and start the runtime. Re-running init preserves policy.
 
 Options:
-  --path <path>  Project path`,
+  --path <path>  Project path
+  --no-start    Configure without starting a background process
+  --no-integrations  Skip project guidance and host configuration`,
+    import: `usage: ctx import [--path <path>] [--apply]
+
+Preview project memory, .claude, .zcode, .cursor, .curcor, .codex and AGENTS.md.
+--apply imports deduplicated, source-linked candidates; verification remains explicit.`,
+    inject: `usage: ctx inject [query] [--path <path>] [--max-chars <number>] [--paths <paths>] [--explain]
+
+Select bounded task context; --explain includes detailed source provenance.`,
+    report: `usage: ctx report [options]
+
+Alias of ctx usage report; supports its window, format and baseline options.`,
     usage: `usage: ctx usage report [options]
 
 Show read-only context asset, reuse, token investment, and operation metrics.
@@ -152,6 +176,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
@@ -173,6 +199,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
@@ -286,12 +314,23 @@ 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>]
+    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|compact [--path <path>] [--apply]
 
 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.`,
+    'journal compact': `usage: ctx journal compact [--path <path>] [--apply]
+
+Preview or apply lossless gzip archival. Replays the full hash chain before and after.
+Archived projects require this development version or newer readers.`,
     deadends: `usage: ctx deadends [--all] [--path <path>]
 
 List recorded deadends.`,
@@ -352,9 +391,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.`,
@@ -367,6 +446,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.
@@ -390,7 +472,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|usage|agent|hook|integrate|status|doctor|learn|knowledge|deadend|deadends|note|activity|migrate|runtime|filesystem|feedback|journal [options]
+    return `usage: ctx init|inject|import|report|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.`;
 }
@@ -415,9 +497,11 @@ function printHelp(args) {
         || (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 === 'journal' && ['verify', 'compact'].includes(args[1]))
         || (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 === 'usage' && args[1] === 'report');
     const key = nested ? `${command} ${args[1]}` : command;
@@ -436,6 +520,8 @@ function validatePositionals(values, max, usageText) {
         throw new Error(usageText);
 }
 async function run(args) {
+    if (args[0] === 'report' && !args.includes('--help'))
+        args = ['usage', 'report', ...args.slice(1)];
     if (args.includes('--version')) {
         print(VERSION);
         return;
@@ -450,10 +536,24 @@ async function run(args) {
     const target = option(args, '--path');
     switch (command) {
         case 'init': {
-            validateOptions(args.slice(1), ['--path'], ['--path']);
+            validateOptions(args.slice(1), ['--path', '--no-start', '--no-integrations'], ['--path']);
             const values = positionals(args.slice(1), ['--path']);
             validatePositionals(values, 1, HELP.init);
-            print(await initProject(target ?? values[0]));
+            print(await setupProject(target ?? values[0], { start: !args.includes('--no-start'), integrations: !args.includes('--no-integrations') }));
+            return;
+        }
+        case 'import': {
+            validateOptions(args.slice(1), ['--path', '--apply'], ['--path']);
+            validatePositionals(positionals(args.slice(1), ['--path']), 0, HELP.import);
+            print(await importMemory(target, args.includes('--apply')));
+            return;
+        }
+        case 'inject': {
+            const valueOptions = ['--path', '--max-chars', '--paths'];
+            validateOptions(args.slice(1), [...valueOptions, '--explain'], valueOptions);
+            const values = positionals(args.slice(1), valueOptions);
+            validatePositionals(values, 1, HELP.inject);
+            print(await injectContext(target, { query: values[0], paths: listOption(args, '--paths'), maxChars: numericOption(args, '--max-chars', 2400), explain: args.includes('--explain') }, 'cli'));
             return;
         }
         case 'checkpoint': {
@@ -497,12 +597,14 @@ async function run(args) {
             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 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'),
@@ -516,7 +618,7 @@ async function run(args) {
             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']);
@@ -535,6 +637,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'),
@@ -678,7 +782,181 @@ 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] === 'compact') {
+                validateOptions(args.slice(2), ['--path', '--apply'], ['--path']);
+                validatePositionals(positionals(args.slice(2), ['--path']), 0, HELP['journal compact']);
+                print(await compactJournal(target, { apply: args.includes('--apply') }));
+                return;
+            }
             if (args[1] !== 'verify')
                 throw new Error(HELP.journal);
             validateOptions(args.slice(2), ['--path'], ['--path']);

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

@@ -0,0 +1,8 @@
+interface AdmissionStats {
+    schemaVersion: 1;
+    dropped: Record<string, number>;
+    updatedAt: string;
+}
+export declare function readAdmissionStats(root: string): Promise<AdmissionStats>;
+export declare function recordAdmissionDrop(root: string, type: string): Promise<void>;
+export {};

package/dist/src/cognition/admission.js

@@ -0,0 +1,24 @@
+import path from 'node:path';
+import { cognitionRuntimeDirectory } from '../storage/layout.js';
+import { readJson, isRecord } from '../storage/json-store.js';
+import { atomicWriteJson } from '../storage/atomic-write.js';
+const statsPath = (root) => path.join(cognitionRuntimeDirectory(root), 'admission.json');
+export async function readAdmissionStats(root) {
+    try {
+        return await readJson(statsPath(root), (value) => isRecord(value)
+            && value.schemaVersion === 1 && typeof value.updatedAt === 'string' && isRecord(value.dropped)
+            && Object.values(value.dropped).every((count) => typeof count === 'number' && Number.isSafeInteger(count) && count >= 0));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { schemaVersion: 1, dropped: {}, updatedAt: '' };
+        throw error;
+    }
+}
+// The journal writer lock serializes these counters too. Never store content.
+export async function recordAdmissionDrop(root, type) {
+    const stats = await readAdmissionStats(root);
+    stats.dropped[type] = Math.min(Number.MAX_SAFE_INTEGER, (stats.dropped[type] ?? 0) + 1);
+    stats.updatedAt = new Date().toISOString();
+    await atomicWriteJson(statsPath(root), stats);
+}

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;