@veewo/claw 0.2.21 → 0.2.23

package/README.md

@@ -1,141 +1,141 @@
-# @veewo/claw
-
-`@veewo/claw` is the CLI entrypoint for running the `.claw` workflow in a project.
-
-It gives agents and developers a concrete way to plan work, recall project knowledge, deposit truth and ADR notes, and close rounds out cleanly instead of leaving project state scattered across transient chats.
-
-## What the CLI is for
-
-- initialize and normalize the `.claw` project surface
-- run project-scoped planning and task lifecycle commands
-- index and query project documentation recall
-- support truth ingestion and closeout flows
-
-## Install
-
-```bash
-npm install -g @veewo/claw
-```
-
-After installing the CLI, project search still needs one-time setup inside each `.claw` project:
-
-1. Run `claw context` so `.claw/project.json` is normalized and the default local embedding config is present.
-2. Run `claw search index --refresh` once so the local embedding model can be downloaded or reused and the first vector index can be built.
-
-## Host startup context
-
-`claw context --host <host>` is the single structured startup-state entrypoint
-for host adapters. A host Hook owns its native event payload, validates its
-trusted cwd and session identity, invokes `context`, and maps the JSON result
-to its own prompt, card, or host-action surface. The CLI does not own platform
-Hook event names or Hook-output envelopes.
-
-The result may contain `activeWorkflow`, `error`, `startupRecovery.versionSync`,
-and `searchGuidance`, in addition to project and session state. Adapters must
-not accept cwd or session identity from model input. A missing `activeWorkflow`
-means the session has no bound plan; it does not authorize plan discovery by
-scanning unrelated project tasks.
-
-Then run:
-
-```bash
-claw init
-claw search index --refresh
-claw search "existing truth or ADR topic"
-claw plan create --title "My task" --goal "Define the first task"
-claw plan create "My templated task" --template default --goal "Route through the default template"
-claw plan create "Ephemeral harness" --scope session --goal "Use plan and Goal workflows without project deposition"
-```
-
-`claw plan create` uses explicit `--template` first, otherwise the project's configured `defaultPlanTemplate`, and finally falls back to the built-in `default` template. You can select a template explicitly with `claw plan create "<title>" --template <name>` or `claw plan create --template <name> --title "<title>"`.
-
-New project tasks are grouped under `.claw/tasks/YYYY-MM-DD/`. On the first `claw context` call of each local calendar day, claw performs a lock-protected maintenance pass: it removes expired entries from `.claw/runtime/tmp/`, removes workflow task directories that exceed the task TTL even when incomplete, moves eligible date-scoped task folders into the archive, applies `maxTasksToKeep` and archive TTL, removes expired or invalid bindings, and sweeps expired session workflows. This is lazy maintenance, not a background scheduler.
-
-`--scope session` stores the workflow in a user-level directory keyed by the platform session id, so it works without a project `.claw` directory and recovers across cwd changes. It preserves plan/task/subplan/Goal behavior while disabling project knowledge capture, memory/GitNexus refresh, and project retention. Use `claw session clean` for the current session or `claw session clean --expired` for the seven-day TTL sweep.
-
-Projects can add reusable templates directly under `.claw/templates` with `.json`, `.js`, `.mjs`, or `.cjs` files. Put `defaultPlanTemplate` in `.claw/project.json` for a shared team default, or in `.claw/project-override.json` for a local personal override.
-
-When `.claw/project.json` has `planning: true`, the default `default` template seeds one planning task in `process.discussing`. It loads the effective `externalPlanningSkill`, falling back to `claw-kit:planning`, and stays open while the requirements and proposed solution are discussed and confirmed with the user. Use `plan start` when execution tasks remain; when planning itself resolves the request, complete task 1 and close the plan.
-
-When `planning: false`, `claw plan create` seeds the smallest executable plan directly in `process.active`.
-
-## Workflow shape
-
-In a typical round, the CLI helps land this loop in a project:
-
-`plan` -> `search and recall` -> `execute` -> `deposit truth / ADR` -> `close out`
-
-That project-level plan structure helps agents carry longer-running work more cleanly than leaving the task in loose chat state alone.
-
-## Persistent sessions
-
-Open a persistent terminal with:
-
-```bash
-claw session open <dir> <agent-session-id>
-```
-
-The workdir is immutable for the lifetime of that session. Opening another
-directory closes the prior live connection and opens the composite identity
-`(canonical workdir, agent session id)`; two directories with the same agent id
-remain isolated.
-
-Inside the terminal, these commands implicitly target `currentPlan`:
-
-```text
-plan show [--simple]
-plan edit ...
-plan wait
-plan done --retrospective "..."
-task add ...
-task edit --id ...
-task done --id ...
-```
-
-Use `plan resume` to resume the retained current plan, `plan resume <planId>` to
-make a specified resumable plan current, and `plan leave` to enter
-`end.leave` and clear focus. Every `end.*` triggers end-state finalization;
-`end.leave` remains resumable and does not set `completedAt`.
-
-`search --dir <dir> <query>` changes only that search operation. It never
-changes the session workdir or current plan.
-
-On an interrupted connection, mutations are never replayed automatically.
-Reopen with the exact command returned by the error, then inspect
-`plan show --simple`. Retained v2 state expires seven days after its last
-update. Legacy session caches are not migrated and canonical plans are never
-deleted by v2 cleanup.
-
-Host adapters remain compatible with the stateless CLI. They can adopt
-`@veewo/claw-client` incrementally once they consume the same structured
-post-commit effects; opening a persistent session does not change existing
-adapter behavior.
-
-Codex startup workflow should rely on the session hook or startup recovery path instead of treating any extra manual recovery step as required after plan creation.
-
-## Search and recall
-
-`claw search` is the project recall command for `.claw` memory, truth, ADR, and declared markdown docs. Use it for retained project context rather than code search.
-
-When a task needs deeper code investigation or relationship tracing, GitNexus can complement this workflow, but it is optional rather than required for using `claw` itself.
-
-Typical setup:
-
-```bash
-claw context
-claw search index --refresh
-```
-
-If you need deeper backup detail on config or recall behavior, use the adapter reference notes in [packages/codex-adapter/references/project-config-reference.md](../codex-adapter/references/project-config-reference.md) or [packages/opencode-adapter/references/project-config-reference.md](../opencode-adapter/references/project-config-reference.md).
-
-## Configuration
-
-If you need backup `.claw/project.json` detail, start with the adapter reference notes above and use [docs/project-json-reference.md](../../docs/project-json-reference.md) only for deeper canonical detail.
-
-`claw-kit` also stays usable alongside other harnesses or external skills, so the CLI does not assume a single host or investigation surface.
-
-The config model is team-friendly as well: `.claw/project.json` carries the shared canonical workflow, while `.claw/project-override.json` leaves room for personal runtime preferences.
-
-## Repository
-
-- [claw-kit](https://github.com/chanyuenpang/claw-kit)
+# @veewo/claw
+
+`@veewo/claw` is the CLI entrypoint for running the `.claw` workflow in a project.
+
+It gives agents and developers a concrete way to plan work, recall project knowledge, deposit truth and ADR notes, and close rounds out cleanly instead of leaving project state scattered across transient chats.
+
+## What the CLI is for
+
+- initialize and normalize the `.claw` project surface
+- run project-scoped planning and task lifecycle commands
+- index and query project documentation recall
+- support truth ingestion and closeout flows
+
+## Install
+
+```bash
+npm install -g @veewo/claw
+```
+
+After installing the CLI, project search still needs one-time setup inside each `.claw` project:
+
+1. Run `claw context` so `.claw/project.json` is normalized and the default local embedding config is present.
+2. Run `claw search index --refresh` once so the local embedding model can be downloaded or reused and the first vector index can be built.
+
+## Host startup context
+
+`claw context --host <host>` is the single structured startup-state entrypoint
+for host adapters. A host Hook owns its native event payload, validates its
+trusted cwd and session identity, invokes `context`, and maps the JSON result
+to its own prompt, card, or host-action surface. The CLI does not own platform
+Hook event names or Hook-output envelopes.
+
+The result may contain `activeWorkflow`, `error`, `startupRecovery.versionSync`,
+and `searchGuidance`, in addition to project and session state. Adapters must
+not accept cwd or session identity from model input. A missing `activeWorkflow`
+means the session has no bound plan; it does not authorize plan discovery by
+scanning unrelated project tasks.
+
+Then run:
+
+```bash
+claw init
+claw search index --refresh
+claw search "existing truth or ADR topic"
+claw plan create --title "My task" --goal "Define the first task"
+claw plan create "My templated task" --template default --goal "Route through the default template"
+claw plan create "Ephemeral harness" --scope session --goal "Use plan and Goal workflows without project deposition"
+```
+
+`claw plan create` uses explicit `--template` first, otherwise the project's configured `defaultPlanTemplate`, and finally falls back to the built-in `default` template. You can select a template explicitly with `claw plan create "<title>" --template <name>` or `claw plan create --template <name> --title "<title>"`.
+
+New project tasks are grouped under `.claw/tasks/YYYY-MM-DD/`. On the first `claw context` call of each local calendar day, claw performs a lock-protected maintenance pass: it removes expired entries from `.claw/runtime/tmp/`, removes workflow task directories that exceed the task TTL even when incomplete, moves eligible date-scoped task folders into the archive, applies `maxTasksToKeep` and archive TTL, removes expired or invalid bindings, and sweeps expired session workflows. This is lazy maintenance, not a background scheduler.
+
+`--scope session` stores the workflow in a user-level directory keyed by the platform session id, so it works without a project `.claw` directory and recovers across cwd changes. It preserves plan/task/subplan/Goal behavior while disabling project knowledge capture and project retention. When the session's frozen origin belongs to a valid claw project, its terminal transition refreshes that project's memory and enabled GitNexus index; otherwise it creates no refresh state. Use `claw session clean` for the current session or `claw session clean --expired` for the seven-day TTL sweep.
+
+Projects can add reusable templates directly under `.claw/templates` with `.json`, `.js`, `.mjs`, or `.cjs` files. Put `defaultPlanTemplate` in `.claw/project.json` for a shared team default, or in `.claw/project-override.json` for a local personal override.
+
+When `.claw/project.json` has `planning: true`, the default `default` template seeds one planning task in `process.discussing`. It loads the effective `externalPlanningSkill`, falling back to `claw-kit:planning`, and stays open while the requirements and proposed solution are discussed and confirmed with the user. Use `plan start` when execution tasks remain; when planning itself resolves the request, complete task 1 and close the plan.
+
+When `planning: false`, `claw plan create` seeds the smallest executable plan directly in `process.active`.
+
+## Workflow shape
+
+In a typical round, the CLI helps land this loop in a project:
+
+`plan` -> `search and recall` -> `execute` -> `deposit truth / ADR` -> `close out`
+
+That project-level plan structure helps agents carry longer-running work more cleanly than leaving the task in loose chat state alone.
+
+## Persistent sessions
+
+Open a persistent terminal with:
+
+```bash
+claw session open <dir> <agent-session-id>
+```
+
+The workdir is immutable for the lifetime of that session. Opening another
+directory closes the prior live connection and opens the composite identity
+`(canonical workdir, agent session id)`; two directories with the same agent id
+remain isolated.
+
+Inside the terminal, these commands implicitly target `currentPlan`:
+
+```text
+plan show [--simple]
+plan edit ...
+plan wait
+plan done --retrospective "..."
+task add ...
+task edit --id ...
+task done --id ...
+```
+
+Use `plan resume` to resume the retained current plan, `plan resume <planId>` to
+make a specified resumable plan current, and `plan leave` to enter
+`end.leave` and clear focus. Every `end.*` triggers end-state finalization;
+`end.leave` remains resumable and does not set `completedAt`.
+
+`search --dir <dir> <query>` changes only that search operation. It never
+changes the session workdir or current plan.
+
+On an interrupted connection, mutations are never replayed automatically.
+Reopen with the exact command returned by the error, then inspect
+`plan show --simple`. Retained v2 state expires seven days after its last
+update. Legacy session caches are not migrated and canonical plans are never
+deleted by v2 cleanup.
+
+Host adapters remain compatible with the stateless CLI. They can adopt
+`@veewo/claw-client` incrementally once they consume the same structured
+post-commit effects; opening a persistent session does not change existing
+adapter behavior.
+
+Codex startup workflow should rely on the session hook or startup recovery path instead of treating any extra manual recovery step as required after plan creation.
+
+## Search and recall
+
+`claw search` is the project recall command for `.claw` memory, truth, ADR, and declared markdown docs. Use it for retained project context rather than code search.
+
+When a task needs deeper code investigation or relationship tracing, GitNexus can complement this workflow, but it is optional rather than required for using `claw` itself.
+
+Typical setup:
+
+```bash
+claw context
+claw search index --refresh
+```
+
+If you need deeper backup detail on config or recall behavior, use the adapter reference notes in [packages/codex-adapter/references/project-config-reference.md](../codex-adapter/references/project-config-reference.md) or [packages/opencode-adapter/references/project-config-reference.md](../opencode-adapter/references/project-config-reference.md).
+
+## Configuration
+
+If you need backup `.claw/project.json` detail, start with the adapter reference notes above and use [docs/project-json-reference.md](../../docs/project-json-reference.md) only for deeper canonical detail.
+
+`claw-kit` also stays usable alongside other harnesses or external skills, so the CLI does not assume a single host or investigation surface.
+
+The config model is team-friendly as well: `.claw/project.json` carries the shared canonical workflow, while `.claw/project-override.json` leaves room for personal runtime preferences.
+
+## Repository
+
+- [claw-kit](https://github.com/chanyuenpang/claw-kit)

package/dist/cli.js

@@ -6,7 +6,7 @@ import { createInterface } from "node:readline";
 import { pathToFileURL } from "node:url";
 import { createHash } from "node:crypto";
 import { spawn, spawnSync } from "node:child_process";
-import { buildDirectWorkflowGuidance, appendKnowledgeTaskConclusions, buildKnowledgeAtomicDispatch, buildKnowledgeDelegateDispatch, buildKnowledgeAssignmentTemplate, buildKnowledgeWriterAssignments, DEFAULT_MAX_TASKS_TO_KEEP, checkProjectProtocol, ClawError, buildPlanWorkflowGuidance, buildMemoryIndex, buildSessionStartDefaultPrompt, buildSessionStartRecoveredPrompt, editPlan, ensureProjectProtocol, enforceTaskRetention, findKnowledgeFinalizationJobPath, findTaskDirectory, runDailyMaintenance, ingestTruth, initProject, getTemplateTaskDoneChoices, resolvePlanTemplateFile, resolvePlanEffectiveConfig, resolveKnowledgeWriterForHost, resolveProjectContext, resolveWorkflowProjectContext, resolveSessionWorkflowContext, deleteSessionWorkflow, sweepExpiredSessionWorkflows, resolveSessionBoundPlan, resolveContext, resolveSeedPlanTemplate, searchMemoryAsync, warmProjectMemoryEmbedding, showPlan, createSubplan, switchTask, tryCaptureKnowledgeStop, claimKnowledgeFinalizationJob, doneKnowledgeFinalizationJob, readKnowledgeFinalizationJob, waitForKnowledgeFinalizationJobReady, listKnowledgeFinalizationJobs, listRetryableKnowledgeFinalizationJobs, normalizeTruthMarkdownEncoding, recordKnowledgeFinalizationResult, unbindSession, writePlan, } from "@veewo/claw-core";
+import { buildDirectWorkflowGuidance, appendKnowledgeTaskConclusions, buildKnowledgeAtomicDispatch, buildKnowledgeDelegateDispatch, buildKnowledgeAssignmentTemplate, buildDirectKnowledgeAssignments, buildKnowledgeWriterAssignments, DEFAULT_MAX_TASKS_TO_KEEP, checkProjectProtocol, ClawError, assertRootPlanCreateAllowedForPlan, buildPlanWorkflowGuidance, buildMemoryIndex, buildSessionStartDefaultPrompt, buildSessionStartRecoveredPrompt, editPlan, ensureProjectProtocol, enforceTaskRetention, findKnowledgeFinalizationJobPath, findTaskDirectory, runDailyMaintenance, ingestTruth, initProject, getTemplateTaskDoneChoices, resolvePlanTemplateFile, resolvePlanEffectiveConfig, resolveKnowledgeWriterForHost, resolveProjectContext, resolveWorkflowProjectContext, resolveSessionWorkflowContext, deleteSessionWorkflow, sweepExpiredSessionWorkflows, resolveSessionBoundPlan, resolveContext, resolveSeedPlanTemplate, searchMemoryAsync, warmProjectMemoryEmbedding, showPlan, createSubplan, createPlanRef, switchTask, tryCaptureKnowledgeStop, claimKnowledgeFinalizationJob, doneKnowledgeFinalizationJob, readKnowledgeFinalizationJob, waitForKnowledgeFinalizationJobReady, listKnowledgeFinalizationJobs, listRetryableKnowledgeFinalizationJobs, normalizeTruthMarkdownEncoding, governKnowledgeMarkdownPaths, resolveKnowledgeDocUpdateSnapshot, recordKnowledgeFinalizationResult, unbindSession, writePlan, } from "@veewo/claw-core";
 import { buildCodexDriverEnvelope } from "./codex-driver.js";
 import { buildCodexHostActions } from "./codex-host-actions.js";
 import { checkCodexRuntime, resolveCodexSdkEntryPath } from "./codex-runtime.js";
@@ -21,7 +21,7 @@ const TOP_LEVEL_COMMANDS = [
     { name: "context [--task <name>]", summary: "Resolve project context, auto-initializing or correcting .claw state." },
     { name: "session clean [--expired]", summary: "Remove current or expired session workflow state." },
     { name: "check", summary: "Check and auto-correct .claw project protocol fields." },
-    { name: "plan <subcommand> [options]", summary: "Plan lifecycle: create, start, edit, remove, wait, resume, sync, show, done." },
+    { name: "plan <subcommand> [options]", summary: "Plan lifecycle: create, start, edit, remove, wait, resume, leave, sync, show, done." },
     { name: "codex driver", summary: "Return the versioned code-mode driver used by the Codex adapter." },
     { name: "template <subcommand> [options]", summary: "Plan template helpers such as validation." },
     { name: "task <subcommand> [options]", summary: "Task lifecycle helpers inside an existing plan." },
@@ -142,6 +142,11 @@ const COMMAND_HELP = {
                     { flag: "--plan-file <relative-path>", detail: "Advanced: override the session-bound plan file." },
                 ],
             },
+            leave: {
+                usage: ["{script} plan leave"],
+                description: "Explicitly leave the current plan and clear its session binding so a new root plan may be created.",
+                summary: "Leave the current plan without completing it.",
+            },
             sync: {
                 usage: ["{script} plan sync"],
                 description: "Resynchronize a recovered active Codex plan with host progress and Goal Mode without mutating the plan.",
@@ -328,8 +333,28 @@ const COMMAND_HELP = {
     },
     knowledge: {
         usage: ["{script} knowledge <subcommand> [options]"],
-        description: "Session-bound lifecycle commands for a queued knowledge finalization job.",
+        description: "Commands for queued knowledge finalization jobs and explicit same-agent knowledge capture.",
         subcommands: {
+            prepare: {
+                usage: ["{script} knowledge prepare --source agent-memory --project-root <path>"],
+                description: "Read the current project configuration and return the immutable assignment projection for one explicit manual knowledge capture. It never initializes, repairs, or mutates the project.",
+                summary: "Prepare explicit same-agent knowledge capture.",
+                options: [
+                    { flag: "--source agent-memory", detail: "(required) Only source supported by the manual same-agent route." },
+                    { flag: "--project-root <path>", detail: "(required) Project root used to resolve current team and personal configuration." },
+                ],
+            },
+            complete: {
+                usage: ["{script} knowledge complete --source agent-memory --project-root <path> --config-fingerprint <hash> [--changed-truth <absolute-path> ...]"],
+                description: "Validate the prepared configuration, govern declared canonical paths, normalize knowledge encoding, and queue the existing completion refresh without creating a report or job.",
+                summary: "Complete explicit same-agent knowledge capture.",
+                options: [
+                    { flag: "--source agent-memory", detail: "(required) Only source supported by the manual same-agent route." },
+                    { flag: "--project-root <path>", detail: "(required) Project root used to resolve current configuration." },
+                    { flag: "--config-fingerprint <hash>", detail: "(required) Fingerprint returned by knowledge prepare." },
+                    { flag: "--changed-truth <absolute-path>", detail: "Canonical Truth or ADR Markdown path changed by this capture (repeatable)." },
+                ],
+            },
             wait: {
                 usage: ["{script} knowledge wait --project-root <path> --finalize-id <id> [--session-key <key>] [--timeout-ms <n>]"],
                 description: "Wait for Stop capture to create a knowledge finalization job. This command does not create or inspect session bindings.",
@@ -1019,6 +1044,24 @@ function readCindyKnowledgeClaimCaptureInput() {
 async function runKnowledge(args) {
     const subcommand = args.shift();
     switch (subcommand) {
+        case "prepare": {
+            const source = readRequiredFlag(args, "--source");
+            const projectRoot = path.resolve(readRequiredFlag(args, "--project-root"));
+            assertNoRemainingArgs(args, "knowledge prepare");
+            assertDirectKnowledgeSource(source);
+            printJson(prepareDirectKnowledgeCapture(projectRoot));
+            return;
+        }
+        case "complete": {
+            const source = readRequiredFlag(args, "--source");
+            const projectRoot = path.resolve(readRequiredFlag(args, "--project-root"));
+            const configFingerprint = readRequiredFlag(args, "--config-fingerprint");
+            const changedTruth = readRepeatedFlag(args, "--changed-truth");
+            assertNoRemainingArgs(args, "knowledge complete");
+            assertDirectKnowledgeSource(source);
+            printJson(completeDirectKnowledgeCapture({ projectRoot, configFingerprint, changedTruth }));
+            return;
+        }
         case "list": {
             const projectRoot = path.resolve(readRequiredFlag(args, "--project-root"));
             const sessionKey = readOptionalFlag(args, "--session-key");
@@ -1200,6 +1243,98 @@ async function runKnowledge(args) {
             throw new ClawError("PROJECT_CONFIG_INVALID", `Unknown knowledge subcommand "${subcommand ?? ""}".`);
     }
 }
+function prepareDirectKnowledgeCapture(projectRoot) {
+    const project = resolveProjectContext(projectRoot);
+    const ownerSessionKey = resolveOwnerSessionKey() ?? undefined;
+    if (ownerSessionKey && resolveSessionBoundPlan(project, ownerSessionKey)) {
+        throw new ClawError("KNOWLEDGE_DIRECT_WORKFLOW_ACTIVE", "Manual knowledge capture cannot run while this session has an active claw workflow.");
+    }
+    const writer = project.projectConfig?.knowledgeWriter;
+    const docUpdate = resolveKnowledgeDocUpdateSnapshot(project);
+    const assignments = buildDirectKnowledgeAssignments({ writer, ...(docUpdate ? { docUpdate } : {}) });
+    for (const assignment of assignments) {
+        for (const resourcePath of [assignment.contractPath, assignment.formatPath]) {
+            if (resourcePath && (!fs.existsSync(resourcePath) || !fs.statSync(resourcePath).isFile())) {
+                throw new ClawError("KNOWLEDGE_DIRECT_RESOURCE_MISSING", "A required knowledge-capture contract resource is unavailable.", { resourcePath });
+            }
+        }
+    }
+    const configFingerprint = directKnowledgeConfigFingerprint({ project, assignments, docUpdate });
+    return {
+        ok: true,
+        command: "knowledge.prepare",
+        schemaVersion: 1,
+        source: "agent-memory",
+        project: { projectRoot: project.projectRoot, truthDir: project.truthDir },
+        configFingerprint,
+        assignments,
+        refresh: {
+            operations: ["memory.reindex.project", ...(project.projectConfig?.gitnexus === true ? ["gitnexus.refresh"] : [])],
+        },
+    };
+}
+function completeDirectKnowledgeCapture(input) {
+    const prepared = prepareDirectKnowledgeCapture(input.projectRoot);
+    if (prepared.configFingerprint !== input.configFingerprint) {
+        throw new ClawError("KNOWLEDGE_DIRECT_CONFIG_CHANGED", "Knowledge-capture configuration changed after prepare; run knowledge prepare again before completion.", { expected: input.configFingerprint, actual: prepared.configFingerprint });
+    }
+    const project = resolveProjectContext(input.projectRoot);
+    const relativePaths = input.changedTruth.map((candidate) => relativeTruthPath(project.truthDir, candidate));
+    const builtin = prepared.assignments.find((assignment) => assignment.kind === "builtin");
+    const governance = builtin
+        ? governKnowledgeMarkdownPaths({
+            truthDir: project.truthDir,
+            relativePaths,
+            datedSectionsToKeep: builtin.datedSectionsToKeep ?? 6,
+        })
+        : { changedFiles: 0, compactedFiles: 0, removedSections: 0, files: [] };
+    const truthEncoding = normalizeTruthMarkdownEncoding(project);
+    const refresh = queueCompletionRefresh({
+        cwd: project.projectRoot,
+        taskName: "knowledge-capture",
+        includeTaskRetention: false,
+        statusLabel: "knowledge-capture",
+    });
+    return {
+        ok: true,
+        command: "knowledge.complete",
+        source: "agent-memory",
+        configFingerprint: prepared.configFingerprint,
+        changedTruth: relativePaths,
+        governance,
+        truthEncoding,
+        asyncRefresh: refresh.asyncRefresh,
+    };
+}
+function assertDirectKnowledgeSource(source) {
+    if (source !== "agent-memory") {
+        throw new ClawError("PROJECT_CONFIG_INVALID", 'Manual knowledge capture supports only --source agent-memory.');
+    }
+}
+function relativeTruthPath(truthDir, candidate) {
+    const root = path.resolve(truthDir);
+    const target = path.resolve(candidate);
+    const relative = path.relative(root, target);
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative) || !/\.md$/iu.test(relative)) {
+        throw new ClawError("KNOWLEDGE_DIRECT_PATH_INVALID", "Changed knowledge paths must be Markdown files inside the resolved truth directory.", { candidate, truthDir: root });
+    }
+    return relative.replaceAll("\\", "/");
+}
+function directKnowledgeConfigFingerprint(input) {
+    const payload = {
+        schemaVersion: 1,
+        truthDir: path.resolve(input.project.truthDir),
+        assignments: input.assignments.map((assignment) => ({
+            kind: assignment.kind,
+            skill: assignment.skill ?? null,
+            datedSectionsToKeep: assignment.datedSectionsToKeep ?? null,
+        })),
+        externalDocPaths: input.docUpdate?.externalDocPaths ?? [],
+        gitnexus: input.project.projectConfig?.gitnexus === true,
+        memoryRefresh: input.project.projectConfig?.memory?.enabled !== false,
+    };
+    return `sha256:${createHash("sha256").update(JSON.stringify(payload)).digest("hex")}`;
+}
 async function runPlan(args, effectiveHost) {
     const subcommand = args.shift();
     switch (subcommand) {
@@ -1217,7 +1352,9 @@ async function runPlan(args, effectiveHost) {
             if (!title) {
                 throw new ClawError("PROJECT_CONFIG_INVALID", "plan create requires a title. Use `claw plan create \"<title>\"` or `claw plan create --title \"<title>\"`.");
             }
-            await preparePlanCreateWorkflow(process.cwd(), resolveOwnerSessionKey(), effectiveHost, scope);
+            const ownerSessionKey = resolveOwnerSessionKey();
+            assertDirectRootPlanCreateAllowed(process.cwd(), ownerSessionKey, scope);
+            await preparePlanCreateWorkflow(process.cwd(), ownerSessionKey, effectiveHost, scope);
             const result = await writePlan({
                 cwd: process.cwd(),
                 scope,
@@ -1225,9 +1362,18 @@ async function runPlan(args, effectiveHost) {
                 templateFile: explicitTemplateFile ? path.resolve(process.cwd(), explicitTemplateFile) : undefined,
                 title,
                 goalText: readOptionalFlag(args, "--goal"),
-                ownerSessionKey: resolveOwnerSessionKey() ?? undefined,
+                ownerSessionKey: ownerSessionKey ?? undefined,
                 host: effectiveHost,
             });
+            if (ownerSessionKey && scope !== "session") {
+                const sessionProject = resolveSessionWorkflowContext(ownerSessionKey);
+                if (sessionProject) {
+                    const relativePlanPath = path.relative(sessionProject.clawDir, result.planPath);
+                    if (relativePlanPath.startsWith("..") || path.isAbsolute(relativePlanPath)) {
+                        unbindSession(sessionProject, ownerSessionKey);
+                    }
+                }
+            }
             assertNoRemainingArgs(args, "plan create");
             printJson(compactPlanCommandResult("plan.create", result, effectiveHost));
             return;
@@ -1253,8 +1399,8 @@ async function runPlan(args, effectiveHost) {
                 && effectiveHost !== "cindy") {
                 throw new ClawError("PROJECT_CONFIG_INVALID", 'knowledgeWriter.executionPolicy "subagent" is supported only by the Codex or Cindy host.', { host: effectiveHost ?? null });
             }
-            const queuePlanEndFinalization = entersEndTerminal
-                ? preparePlanEndFinalization(process.cwd(), ownerSessionKey)
+            const terminalRefresh = entersEndTerminal
+                ? preparePlanTerminalRefresh(process.cwd(), ownerSessionKey)
                 : undefined;
             const result = await editPlan({
                 cwd: process.cwd(),
@@ -1276,7 +1422,7 @@ async function runPlan(args, effectiveHost) {
                     writer: effectiveWriter,
                 })
                 : undefined;
-            const completionRefresh = queuePlanEndFinalization?.(result.taskName);
+            const completionRefresh = queueTerminalRefreshIfEntered(result, terminalRefresh);
             printJson(compactPlanCommandResult("plan.edit", result, effectiveHost, completionRefresh, false, knowledgeDispatch));
             if (result.operationChain?.status === "partial")
                 process.exitCode = 1;
@@ -1306,6 +1452,9 @@ async function runPlan(args, effectiveHost) {
         case "resume":
             await runPlanStatusAlias(args, "process.active", "plan.resume", effectiveHost);
             return;
+        case "leave":
+            await runPlanLeave(args, effectiveHost);
+            return;
         case "sync":
             await runPlanSync(args, effectiveHost);
             return;
@@ -1361,7 +1510,7 @@ async function runPlan(args, effectiveHost) {
                 && effectiveHost !== "cindy") {
                 throw new ClawError("PROJECT_CONFIG_INVALID", 'knowledgeWriter.executionPolicy "subagent" is supported only by the Codex or Cindy host.', { host: effectiveHost ?? null });
             }
-            const queuePlanEndFinalization = preparePlanEndFinalization(process.cwd(), ownerSessionKey);
+            const terminalRefresh = preparePlanTerminalRefresh(process.cwd(), ownerSessionKey);
             const result = await editPlan({
                 cwd: process.cwd(),
                 ...target,
@@ -1380,7 +1529,7 @@ async function runPlan(args, effectiveHost) {
                     writer: effectiveWriter,
                 })
                 : undefined;
-            const completionRefresh = queuePlanEndFinalization?.(result.taskName);
+            const completionRefresh = queueTerminalRefreshIfEntered(result, terminalRefresh);
             printJson(compactPlanCommandResult("plan.done", result, effectiveHost, completionRefresh, false, knowledgeDispatch));
             return;
         }
@@ -1425,6 +1574,22 @@ async function runPlanStatusAlias(args, planStatus, command, effectiveHost) {
     assertNoRemainingArgs(args, command);
     printJson(compactPlanCommandResult(command, result, effectiveHost, undefined, true));
 }
+async function runPlanLeave(args, effectiveHost) {
+    const ownerSessionKey = resolveOwnerSessionKey() ?? undefined;
+    const target = readPlanMutationTarget(args);
+    assertNoRemainingArgs(args, "plan leave");
+    const terminalRefresh = preparePlanTerminalRefresh(process.cwd(), ownerSessionKey);
+    const result = await editPlan({
+        cwd: process.cwd(),
+        ...target,
+        planStatus: "end.leave",
+        commandSource: "plan.edit",
+        host: effectiveHost,
+        ownerSessionKey,
+    });
+    const completionRefresh = queueTerminalRefreshIfEntered(result, terminalRefresh);
+    printJson(compactPlanCommandResult("plan.leave", result, effectiveHost, completionRefresh, true));
+}
 async function runPlanSync(args, effectiveHost) {
     const ownerSessionKey = resolveOwnerSessionKey() ?? undefined;
     const result = showPlan({ cwd: process.cwd(), ...readPlanMutationTarget(args), ownerSessionKey });
@@ -1618,7 +1783,10 @@ async function runContextCommand(args, cwd = process.cwd(), ownerSessionKey = re
     let corrected = false;
     let fixedPaths = [];
     const sessionProject = resolveSessionWorkflowContext(ownerSessionKey ?? undefined);
-    if (sessionProject) {
+    const sessionPlanPath = sessionProject && ownerSessionKey
+        ? resolveSessionBoundPlan(sessionProject, ownerSessionKey)
+        : null;
+    if (sessionProject && sessionPlanPath) {
         const maintenance = effectiveHost
             ? null
             : runDailyMaintenance(sessionProject, {
@@ -2175,6 +2343,33 @@ async function preparePlanCreateWorkflow(cwd, ownerSessionKey, effectiveHost, re
     }
     await prepareProjectWorkflow(cwd, ownerSessionKey, effectiveHost, project);
 }
+function assertDirectRootPlanCreateAllowed(cwd, ownerSessionKey, requestedScope) {
+    if (!ownerSessionKey)
+        return;
+    const project = requestedScope === "session"
+        ? resolveSessionWorkflowContext(ownerSessionKey)
+        : tryResolveHookProject(cwd);
+    if (!project)
+        return;
+    const planPath = resolveSessionBoundPlan(project, ownerSessionKey);
+    if (!planPath)
+        return;
+    const target = parseTaskPlanPath(project, planPath);
+    if (!target) {
+        throw new ClawError("PLAN_TRANSITION_CONFLICT", `Invalid session-bound plan path: ${planPath}`);
+    }
+    const current = showPlan({
+        cwd,
+        taskName: target.taskName,
+        planFile: target.planFile,
+        ownerSessionKey,
+    });
+    if (current.plan.status.startsWith("end.")) {
+        unbindSession(project, ownerSessionKey);
+        return;
+    }
+    assertRootPlanCreateAllowedForPlan(createPlanRef(project, current.taskName, current.planFile), current.plan);
+}
 async function prepareProjectWorkflow(cwd, ownerSessionKey, effectiveHost, project = tryResolveHookProject(cwd)) {
     const sessionProject = resolveSessionWorkflowContext(ownerSessionKey ?? undefined);
     if (sessionProject) {
@@ -3268,11 +3463,24 @@ function readRepeatedIntegerFlag(args, flag) {
 function failMissingNumericFlag(flag) {
     throw new ClawError("PROJECT_CONFIG_INVALID", `Missing required flag ${flag}.`, { flag });
 }
-function preparePlanEndFinalization(cwd, ownerSessionKey) {
+function preparePlanTerminalRefresh(cwd, ownerSessionKey) {
     const workflowProject = resolveWorkflowProjectContext(cwd, ownerSessionKey);
-    if (workflowProject.scope !== "project")
+    const refreshProject = tryResolveHookProject(workflowProject.projectRoot);
+    if (!refreshProject)
         return undefined;
-    return (taskName) => queueCompletionRefresh({ cwd, taskName });
+    return {
+        queue: (taskName) => queueCompletionRefresh({
+            cwd: refreshProject.projectRoot,
+            taskName,
+            includeTaskRetention: workflowProject.scope !== "session",
+        }),
+    };
+}
+function queueTerminalRefreshIfEntered(result, terminalRefresh) {
+    if (!terminalRefresh || result.previousPlanStatus.startsWith("end.") || !result.planStatus.startsWith("end.")) {
+        return undefined;
+    }
+    return terminalRefresh.queue(result.taskName);
 }
 function queueCompletionRefresh(input) {
     const project = resolveProjectContext(input.cwd);