@veewo/claw 0.2.16 → 0.2.18

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, 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)

package/dist/cli.js

@@ -182,10 +182,10 @@ const COMMAND_HELP = {
             },
             done: {
                 usage: ["{script} plan done --retrospective <text> [options]"],
-                description: "Shortcut for applying closeout fields and --status end.completed in one ordered plan edit; it retains the task for at least one hour, sweeps older completed tasks into the archive, and queues the async completion refresh.",
-                summary: "Shortcut for completing a plan with a retrospective and queueing completion refresh.",
+                description: "Shortcut for applying closeout fields and --status end.completed in one ordered plan edit; project scope requires a retrospective, while session scope completes without document deposition. It retains the task for at least one hour, sweeps older completed tasks into the archive, and queues the async completion refresh.",
+                summary: "Shortcut for completing a plan and queueing completion refresh.",
                 options: [
-                    { flag: "--retrospective <text>", detail: "Retrospective summary (required)." },
+                    { flag: "--retrospective <text>", detail: "Retrospective summary (required for project scope)." },
                     { flag: "--key-decision <text>", detail: "Append a durable key decision when one exists (repeatable)." },
                     { flag: "--what-worked <text>", detail: "Append a retrospective success (repeatable)." },
                     { flag: "--issue <text>", detail: "Append a retrospective issue (repeatable)." },
@@ -307,12 +307,13 @@ const COMMAND_HELP = {
         ],
     },
     search: {
-        usage: ["{script} search [<query>] [--dir <dir>] [--limit <n>]", "{script} search index --refresh"],
+        usage: ["{script} search [<query>] [--dir <dir>] [--limit <n>] [--json]", "{script} search index --refresh [--json]"],
         description: "Project-scoped recall over .claw memory, truth, ADR, and declared markdown docs. Use a positional query or --query. Task-local scope (--task/--scope) is rejected; put task materials in plan.references instead.",
         options: [
             { flag: "--query <text>", detail: "Search query (or pass the query positionally)." },
             { flag: "--dir <dir>", detail: "Override the project directory for this search only." },
             { flag: "--limit <n>", detail: "Max number of results." },
+            { flag: "--json", detail: "Compatibility flag; search output is always JSON." },
         ],
         subcommands: {
             index: {
@@ -788,9 +789,6 @@ function parsePersistentSessionCommand(line) {
     }
     if (group === "plan" && action === "done") {
         const retrospectiveSummary = consumeSessionFlag(tokens, "--retrospective");
-        if (!retrospectiveSummary) {
-            throw new ClawError("RETROSPECTIVE_REQUIRED", "plan done requires --retrospective.");
-        }
         const keyDecisions = consumeAllSessionFlags(tokens, "--key-decision");
         const whatWorked = consumeAllSessionFlags(tokens, "--what-worked");
         const issues = consumeAllSessionFlags(tokens, "--issue");
@@ -801,7 +799,7 @@ function parsePersistentSessionCommand(line) {
             request: {
                 operation: "plan.done",
                 input: {
-                    retrospectiveSummary,
+                    ...(retrospectiveSummary ? { retrospectiveSummary } : {}),
                     ...(keyDecisions.length ? { keyDecisions } : {}),
                     ...(whatWorked.length ? { whatWorked } : {}),
                     ...(issues.length ? { issues } : {}),
@@ -1334,11 +1332,8 @@ async function runPlan(args, effectiveHost) {
         }
         case "done": {
             const retrospective = readOptionalFlag(args, "--retrospective");
-            if (!retrospective?.trim()) {
-                throw new ClawError("PROJECT_CONFIG_INVALID", "plan done requires --retrospective.");
-            }
             const updates = {
-                retrospectiveSummary: retrospective,
+                ...(retrospective?.trim() ? { retrospectiveSummary: retrospective } : {}),
                 keyDecisions: readRepeatedFlag(args, "--key-decision"),
                 whatWorked: readRepeatedFlag(args, "--what-worked"),
                 issues: readRepeatedFlag(args, "--issue"),
@@ -1352,6 +1347,10 @@ async function runPlan(args, effectiveHost) {
                 ...target,
                 ownerSessionKey,
             });
+            const currentProject = resolveWorkflowProjectContext(process.cwd(), ownerSessionKey);
+            if (currentProject.scope !== "session" && !retrospective?.trim()) {
+                throw new ClawError("RETROSPECTIVE_REQUIRED", "plan done requires --retrospective for project-scoped plans.");
+            }
             const project = tryResolveHookProject(process.cwd());
             const effectiveWriter = resolveKnowledgeWriterForHost(project
                 ? resolvePlanEffectiveConfig(project.projectConfig, current.plan)?.knowledgeWriter
@@ -1441,6 +1440,7 @@ async function runPlanSync(args, effectiveHost) {
         plan: result.plan,
         projectRoot: project.projectRoot,
         projectConfig: project.projectConfig,
+        scope: project.scope,
         previousStatus: "process.wait",
         host: effectiveHost,
         recoveryResync: true,
@@ -2785,6 +2785,7 @@ async function tryResolveActiveWorkflowSnapshot(cwd, ownerSessionKey, effectiveH
                 plan: result.plan,
                 projectRoot: project.projectRoot,
                 projectConfig: project.projectConfig,
+                scope: project.scope,
                 host: effectiveHost,
             }),
         };