@iowarp/clio-coder 0.4.3 → 0.4.5

package/docs/architecture/prompt-envelope-and-tools.md

@@ -16,7 +16,7 @@ window source, prompt-input epoch, resolved session inputs, and the exact
 attached tool-schema bytes. `mainPromptCacheIdentity` in
 `src/interactive/prompt-cache-identity.ts` owns that list.
 
-The compiled prompt is reused byte-for-byte on ordinary submits. It recompiles only when that key changes or when config hot-reload invalidates the prompt cache. Path-scoped project rules can therefore recompile the prompt when a matching file enters working context. When recompilation changes the text, the session ledger records a `promptRecompiled` entry with the previous hash, new hash, and token estimate.
+The compiled prompt is reused byte-for-byte on ordinary submits. Handbook source bytes and prompt inputs are captured per session, so ordinary recompilation does not silently reload edited files. Init, refresh, and reset invalidate the session snapshot and prompt cache, including partial-write failure paths; config hot-reload also invalidates inputs. Path-scoped rules can recompile when a matching file enters working context. When recompilation changes the text, the ledger records `promptRecompiled` with previous hash, new hash, and token estimate. The bounded handbook preload retains exact safe prefixes; captured-source hashes belong to its accounting/manifest metadata. Model-facing omission notices identify source paths and line ranges, and later filesystem retrieval reads current bytes.
 
 ## Section order: stable prefix first
 
@@ -55,7 +55,7 @@ In addition to project root `CLIO-CODER.md` handbooks, Clio supports directory-s
 - Sibling directories outside the subtree continue to inherit from the root handbook or their own local overrides.
 - Deeper subtrees within the directory may add further localized guidance.
 - Prompt blocks preserve explicit source paths for attribution and debugging.
-- Malformed override files fail closed rather than injecting partial guidance, and context resets never delete override files.
+- Empty or unreadable selected overrides fail closed. Ordinary authored Markdown is accepted without a structured project identity, and context resets never delete override files.
 
 `wiki.page` and `wiki.plan` (`src/domains/prompts/fragments/wiki/*.md`) load through this same loader, with the same id/version/content-hash contract as every other fragment, but they are consumed differently: `context/wiki/prompts.ts` reads them by id, substitutes per-dispatch `{{token}}` placeholders (a page's path, title, and relative path; the plan file's path), and sends the result as a wiki-generation dispatch's `task`, never as a compiled system prompt. `{{token}}` substitution has no home in the fragment loader itself, the same division `identity.self-awareness`'s `{TOKEN}` placeholders use in `compiler.ts`: the loader hands back a raw body, and the one caller that needs live values fills them in. Both files' bodies open and close on a standalone `---` line that predates their frontmatter and was kept unchanged as body text so the substituted prompt stays byte-identical to what the old hand-rolled `readFileSync` produced.
 
@@ -73,17 +73,17 @@ Providers that cannot call tools receive no schemas, and the prompt tells the mo
 
 ## Canonical worker harness
 
-Native and mediated dispatch workers use a separate prompts-domain compiler over the same loaded fragment table. Its stable system prompt has five fixed sections plus one optional trailing one: identity-lite, the constitutional operating contract plus the `operating.worker` assigned-task contract, a tool contract sliced to the final canonical toolkit, the same `safety.<level>` fragment the session reads for the single effective autonomy under a worker one-liner that carries the run's permission routing, one final persona, and the operator-editable layer when either of its parts renders non-empty: active project rules scoped to this run's inferred working context, and the operator profile. A request persona override replaces only the recipe body; eligible bound-skill instructions are composed inside that same final persona and never widen tools.
+Native and mediated dispatch workers use a separate prompts-domain compiler over the shared fragment table. The stable system prompt contains identity-lite, the constitutional operating and assigned-task contracts, the final toolkit contract, effective safety and permission routing, one final persona, and any scoped project rules and operator profile. A request persona replaces the recipe body; eligible bound-skill instructions remain inside the final persona without widening tools. Authored handbook context travels separately in a bounded dynamic message, not in this stable system prompt.
 
-The operator-editable layer reaches a worker through `additionalFragments`, the same channel `compile()` uses for the session, so nothing splices into an existing section. The operator profile renders unconditionally, capped, the same as it does for the session: it governs how the worker should do the task (validation preference, commit-message style, local-only paths), not only how the orchestrator talks to the operator. Project rules are scoped to the worker's working context rather than shipped wholesale. That context is `writeRoots`, when the caller sets them, plus path-like tokens recalled from the task and briefing text, since the model-facing dispatch tool has no structured path field. A missed path token means a rule can go unseen; it can never fabricate one, because `selectActiveRules` still requires a real glob match.
+The operator-editable system layer uses `additionalFragments`. The operator profile renders unconditionally within its cap, while project rules are selected from `writeRoots` and path-like tokens in the task and briefing through real glob matches. The separate handbook message follows the effective project-context tier: native defaults depend on capability class and recipe, with Coder and verification workers bounded and Scout none; ACP defaults to none and requires `projectContext: "bounded"` in its configuration. A bounded run uses captured `ProjectPromptContext` authored Markdown through the shared exact-prefix selector, within 1,500 UTF-16 units including source wrappers and omission notices, and the inherited 220-rendered-line limit. The raw authored branch does not inject a second structured projection of conventions, invariants, or verification. Legacy structured-only callers still receive project name, conventions, and invariants; their derived verification supplement is limited to verification-class workers.
 
-The compiler runs after target capability and tool-profile admission. Its canonical tool names are the same names transported in `WorkerSpec.allowedTools` and attached as schemas; routine non-Scout work removes `code_nav`, narrow profiles remove their excluded schemas and guidance, tool-incapable targets get an explicit no-tools contract, and Claude SDK aliases are filtered from the same canonical set. ACP's external inventory is unknown, so ACP bounded-role admission continues to validate the unchanged raw persona rather than fabricating a complete native schema list.
+The worker compiler runs after target capability and tool-profile admission. Canonical names match `WorkerSpec.allowedTools` and attached schemas: routine non-Scout work removes `code_nav`, narrow profiles remove excluded schemas and guidance, and tool-incapable native targets receive a no-tools contract. Claude SDK aliases are filtered from the same set. For omitted handbook text, native workers without admitted read capability are told retrieval is unavailable; unknown native capability makes the read instruction conditional. ACP and subprocess runtimes have unknown external tool inventories, so their notices refer conditionally to their own file-reading tools without promising a native Clio read schema. ACP bounded-role admission continues to validate its raw persona rather than claiming a complete native toolkit. Retrieval reads current filesystem content, which may differ from the captured source identified by accounting/manifest hashes.
 
 Project context, memory, bounded dispatch briefing, pipeline input, the assigned task, and the per-run safety-posture reminder remain dynamic user messages. A briefing is a separately delimited message labeled as untrusted task context/data; it is never concatenated into the task or stable system prompt. Dynamic ordering is project, safety, memory, briefing, then pipeline input, with pipeline input last. These messages do not affect the stable composition hash. Persona, effective autonomy, target tool capability, or final toolkit changes do affect it.
 
-## Seven planes, twenty-one tools
+## Seven planes, twenty-four tools
 
-The canonical builtin catalog contains 21 tools organized in seven planes. A
+The canonical builtin catalog contains 24 tools organized in seven planes. A
 particular session or worker receives the subset whose dependencies and policy
 allow it to register. Each plane is one policy unit: its tools share an action
 class, a size posture, a details schema, and a concurrency rule.
@@ -95,6 +95,7 @@ engine assumes.
 | Plane | Tools | Action class | Concurrency |
 | --- | --- | --- | --- |
 | OBSERVE | `read`, `grep`, `find`, `ls`, `code_nav`, `context`, `credential_present` | read | parallel |
+| OBSERVE | `evidence` | read | sequential |
 | MUTATE | `write`, `edit` | write | sequential |
 | EXECUTE | `bash`, `verify` | execute | sequential |
 | EXECUTE | `git` | read | parallel |
@@ -103,6 +104,8 @@ engine assumes.
 | ORCHESTRATE | `tasks` | read | sequential |
 | ORCHESTRATE | `ledger` | read | sequential |
 | ORCHESTRATE | `panes` | read | sequential |
+| ORCHESTRATE | `limitation` | read | parallel |
+| ORCHESTRATE | `decide` | read | sequential |
 | RETRIEVE | `web_fetch` | read | parallel |
 | INTERACT | `ask_user` | read | sequential |
 | ARTIFACT | `artifact` | write | sequential |
@@ -120,7 +123,14 @@ and a read answers from a local mirror, so it touches no workspace and stays
 read class, and reviewers and judges are pinned to read-only autonomy where a
 write class would block the peer review the board exists for. `panes` controls
 only Clio-owned terminal panes through the live mux; it stays read class but is
-sequential so two operations cannot race the same pane registry.
+sequential so two operations cannot race the same pane registry. `evidence` sits in the OBSERVE plane
+because it only reads canonical evidence, trust status, gate decisions, and
+findings, but it is sequential because `run` mode may materialize a bundle
+under Clio's data directory. `limitation` and `decide` sit in the ORCHESTRATE
+plane as read class: each appends one typed receipt or decision-board entry
+to the session ledger and touches nothing else. `limitation` is parallel
+because the call is pure; `decide` is sequential so two decisions in one batch
+cannot race the supersede lookup.
 
 Registration is conditional on wiring: `context` gains its workspace scope only
 when a session contract is bound, `dispatch`/`monitor`/`steer` register only
@@ -141,7 +151,7 @@ Several tools absorb what used to be separate tools:
 
 - `find(pattern, path?, order?, limit?, include_ignored?)` locates paths by glob pattern (`*`, `**`, `?`, `[abc]`), default limit 500. `order="path"` (default) returns fd's native order; `order="mtime"` returns newest first from a bounded candidate set instead of statting the whole tree, and reports `details.candidates` when the candidate cap made the ordering approximate.
 - `grep(pattern, path?, mode?, glob?, ignore_case?, literal?, context?, limit?, include_ignored?)` searches file contents with ripgrep, degrading to a bounded pure-Node search when rg is absent. `mode=content` (default) returns line-referenced matches, `mode=files` returns matching paths, `mode=count` returns per-file counts. Context lines are consumed from rg's `--json` stream.
-- `context(scope="workspace"|"docs"|"skills")` is the one OBSERVE entry point for material about the working environment: the session workspace snapshot, retrieval over Clio's bundled documentation (`query` required), and skill listing or loading (`name` optional, `include_tree` for the skill's resource files).
+- `context(scope="workspace"|"docs"|"skills"|"recall")` observes the session workspace snapshot, bundled documentation (omit `query` to list the corpus), skills (`name` optional, `include_tree` for resources), or persisted historical tool results. In recall scope, provide `ref` for exact retrieval or omit it for discovery with `query`, `limit`, and `offset`.
 - `verify(check?, path?, args?, browser?, cwd?, timeout_ms?)` runs declared verification. `verify()` lists package.json verification scripts and strict version-1 `.clio-coder/verifiers.yaml` entries through the same `{id, description, command, cwd, timeoutMs, tags, source}` projection. `verify(check="<id>")` runs a package script or the catalog's exact argv/cwd/timeout through safe-exec with no shell. Model `args`, cwd, timeout, output-cap, and environment fields cannot mutate a project entry. `verify(check="frontend", path=...)` validates an HTML/CSS/JS artifact without granting shell access.
 - `artifact(kind="plan"|"review"|"report", content, ...)` writes named artifacts behind one surface: Markdown documents (default `.clio-coder/artifacts/PLAN.md`/`REVIEW.md`/`REPORT.md`; `path` may override inside the workspace) that terminate the turn, because writing the artifact is the answer. Skills are not artifacts; a `SKILL.md` is written with the ordinary write tool and validated by the skills loader.
 - `dispatch(task?, tasks?, mode?, ...)` supports a first-class singular assignment (`task`) and a batch (`tasks`), never both. `task` is worker instructions; `briefing` is optional bounded parent context/data and cannot replace it. Briefing stays a separate dynamic message and receipt provenance, never part of the receipt task. A shared top-level briefing applies to strings and objects without an override; an object-level briefing wins. Blank values are omitted, the cap is 12,000 UTF-8 bytes, and approval pins the exact canonical value. Ordinary handles enter one registered event consumer immediately. Synchronous calls auto-wait for stream-and-receipt completion; `detach:true` returns ids after durable batch registration while the same consumer continues. Review and compete retain gate-sensitive direct drains. Task objects may include `persona`, `tool_profile`, and a typed `budget: {toolCalls, readReserve, retryRevision?}`. The budget must fit the recipe's authored range and the operator lifetime cap. `retryRevision` is the only authority for a later retry, result-contract revision, or review revision to grow its phase. Pipeline output is threaded as bounded data. A successful native or ACP run requires a nonempty receipt-sealed final output; exit zero without one fails as `worker_final_output_missing`, with unfinished text retained only as partial diagnostics. `dispatch(list=true)` renders the catalog.
@@ -154,7 +164,7 @@ Several tools absorb what used to be separate tools:
 
 ## The observation envelope
 
-The six content-returning OBSERVE tools (`read`, `grep`, `find`, `ls`, `code_nav`, `context`) close every result through one shared envelope in `src/tools/observation.ts`. `credential_present` sits in the OBSERVE plane but returns a typed boolean and carries no envelope cap. The envelope owns four guarantees.
+The six content-returning OBSERVE tools (`read`, `grep`, `find`, `ls`, `code_nav`, `context`) close every result through one shared envelope in `src/tools/observation.ts`. `credential_present` sits in the OBSERVE plane but returns a typed boolean and carries no envelope cap, and `evidence` returns bounded JSON under its own 16KB summary policy. The envelope owns four guarantees.
 
 **One notice line, one format.** A truncated text result appends exactly one notice:
 
@@ -190,12 +200,12 @@ Tool descriptions are tiered by how much a wrong call costs. The hot tools the m
 
 Clio uses two context-protection mechanisms.
 
-1. Tool results are capped at the source and again at the registry boundary. OBSERVE tools use the envelope caps above. Exact mutation tools (`write`, `edit`, `artifact`) use 8KB; `steer` and `credential_present` use 4KB; `ledger` uses 16KB; `panes` uses 8KB; and `ask_user` has a 20KB policy. Summary-kind tools (`bash`, `git`, `verify`, `dispatch`, `monitor`) use 16KB at the registry boundary. Bash also exposes the canonical per-call `output_policy`: omitted/`bounded` keeps its diagnostic tail, `summary` selects stable redacted head/error/tail evidence, `metadata-only` keeps facts and retrieval without stdout/stderr context, and `full` succeeds only inside the same hard result budget or records a typed downgrade. This model-context choice does not change the folded tail-biased operator presentation. `web_fetch` is bounded at 16KB after shaping and may read more before it: its `max_bytes` argument defaults to 600KB and is hard-capped at 5MB. Tools without an explicit result-size policy use an approximately 18KB generic backstop. Over-cap generic results are shown briefly and, when possible, saved under `<stateDir>/scratch/<sessionId>/<sha256 of the captured text>.txt` with an `offloadPath` detail and a 10MB scratch-file cap.
+1. Tool results are capped at the source and again at the registry boundary. OBSERVE tools use the envelope caps above. Exact mutation tools (`write`, `edit`, `artifact`) use 8KB; `steer` and `credential_present` use 4KB; `ledger` uses 16KB; `panes` uses 8KB; `limitation` and `decide` use 4KB; and `ask_user` has a 20KB policy. Summary-kind tools (`bash`, `git`, `verify`, `dispatch`, `monitor`, `evidence`) use 16KB at the registry boundary. Bash also exposes the canonical per-call `output_policy`: omitted/`bounded` keeps its diagnostic tail, `summary` selects stable redacted head/error/tail evidence, `metadata-only` keeps facts and retrieval without stdout/stderr context, and `full` succeeds only inside the same hard result budget or records a typed downgrade. This model-context choice does not change the folded tail-biased operator presentation. `web_fetch` is bounded at 16KB after shaping and may read more before it: its `max_bytes` argument defaults to 600KB and is hard-capped at 5MB. Tools without an explicit result-size policy use an approximately 18KB generic backstop. Over-cap generic results are shown briefly and, when possible, saved under `<stateDir>/scratch/<sessionId>/<sha256 of the captured text>.txt` with an `offloadPath` detail and a 10MB scratch-file cap.
 2. Auto-compaction uses one pressure threshold. The default threshold is 0.8. When pressure crosses the threshold, Clio first applies a non-destructive working-set eviction and records the evicted items in the session ledger. If pressure remains above the threshold, it runs the LLM summary compaction path and replays from the compacted session view. The older destructive observation/thinking mask is available only as a compatibility escape hatch when `CLIO_CODER_LEGACY_MASK=1`.
 
 Manual `/context compact`, `CLIO_CODER_FORCE_COMPACT=1`, and overflow recovery force the LLM summary path directly.
 
-Compaction rewrites history, so the next turn on a local single-slot backend is expected to lose prefix-cache alignment. Clio records `expectedColdReasons` and shows one dim notice for that turn.
+Compaction changes projected model replay while retaining the raw ledger, so the next turn on a local single-slot backend is expected to lose prefix-cache alignment. Clio records `expectedColdReasons` and shows one dim notice for that turn.
 
 ## Inspecting a session
 

package/docs/architecture/safety-model.md

@@ -97,7 +97,7 @@ Escalation can never hang a run. Every escalated ask resolves by an operator dec
 ## Operating Posture and Visible Tools
 
 Clio operates under a single operating posture. The canonical catalog contains
-21 built-in tools organized in seven planes; each plane is one policy unit for
+24 built-in tools organized in seven planes; each plane is one policy unit for
 action class, size posture, and concurrency, asserted at bootstrap by
 `src/tools/policy.ts` so the classifier and registered specs cannot drift apart
 silently. Dependency wiring, target capability, worker profile, and recipe
@@ -105,17 +105,17 @@ policy determine which subset is visible in a particular context.
 
 | Plane | Tools | Action class |
 | --- | --- | --- |
-| OBSERVE | `read`, `grep`, `find`, `ls`, `code_nav`, `context`, `credential_present` | `read` |
+| OBSERVE | `evidence`, `read`, `grep`, `find`, `ls`, `code_nav`, `context`, `credential_present` | `read` |
 | MUTATE | `write`, `edit` | `write` |
 | EXECUTE | `bash`, `verify` | `execute` |
 | EXECUTE | `git` | `read` |
 | ORCHESTRATE | `dispatch`, `steer` | `dispatch` |
-| ORCHESTRATE | `monitor`, `tasks`, `ledger`, `panes` | `read` |
+| ORCHESTRATE | `monitor`, `tasks`, `ledger`, `panes`, `limitation`, `decide` | `read` |
 | RETRIEVE | `web_fetch` | `read` |
 | INTERACT | `ask_user` | `read` |
 | ARTIFACT | `artifact` | `write` |
 
-`git` is read-only inspection on the safe-exec spine, so it carries the read class despite living in the EXECUTE plane. `monitor` does not mutate a run or the workspace. The model-facing `tasks` tool is an intentional bookkeeping exception to the everyday meaning of "read": board mutations append full `taskLedger` snapshots to Clio's session ledger, and any action may reconcile the project-local `.clio-coder/user-tasks.json` inbox while `pick` and linked `done` update its durable correlation. Those Clio-owned ledger and inbox mutations intentionally remain audited with `actionClass: "read"`, so task planning and pickup stay available at every autonomy level without an approval card. `ledger` reads a worker-local mirror and posts through the dispatch control lane; it registers only for a worker with an agent-ledger port. `panes` controls Clio-owned terminal panes and registers only when a pane host and live mux are available. Both are read class and sequential because their coordination state must not interleave. This classification grants no source-workspace, command-execution, or run-mutation authority; those operations still require their own tools and action classes. `gateway` is a design-reserved name only (see `src/core/tool-names.ts`), not a registered tool.
+`git` is read-only inspection on the safe-exec spine, so it carries the read class despite living in the EXECUTE plane. `monitor` does not mutate a run or the workspace. The model-facing `tasks` tool is an intentional bookkeeping exception to the everyday meaning of "read": board mutations append full `taskLedger` snapshots to Clio's session ledger, and any action may reconcile the project-local `.clio-coder/user-tasks.json` inbox while `pick` and linked `done` update its durable correlation. Those Clio-owned ledger and inbox mutations intentionally remain audited with `actionClass: "read"`, so task planning and pickup stay available at every autonomy level without an approval card. `ledger` reads a worker-local mirror and posts through the dispatch control lane; it registers only for a worker with an agent-ledger port. `panes` controls Clio-owned terminal panes and registers only when a pane host and live mux are available. Both are read class and sequential because their coordination state must not interleave. `evidence` reads canonical evidence bundles, trust status, gate decisions, and findings; it touches no workspace, and it is sequential because `run` mode may materialize a bundle under Clio's data directory. `limitation` records a typed receipt of what a turn could not verify and why; it touches no filesystem and runs no shell, so it is read class and parallel. `decide` appends the model's own design decision, with its rejected alternatives and rationale, to the session decision board; dispatch seals every active decision's ref onto the run envelope and receipt, and commit seams write them as `Clio-Decision:` trailers. It is read class and sequential. This classification grants no source-workspace, command-execution, or run-mutation authority; those operations still require their own tools and action classes. `gateway` is a design-reserved name only (see `src/core/tool-names.ts`), not a registered tool.
 
 Target capability, dispatch tool profiles, and recipe constraints can further narrow the tools available to a run. That narrowing is convenience and budget control; safety still lives in code gates.
 
@@ -263,7 +263,7 @@ Prefer typed tools over Bash:
 - `verify(check="<id>")` runs either a declared package.json verification script (the `test*/lint*/build*/typecheck*/check*/format*/ci*` family) or an exact version-1 `.clio-coder/verifiers.yaml` argv vector through bounded execution helpers with no shell; `verify()` lists both sources through one canonical check projection.
 - `verify(check="frontend", path=...)` validates frontend artifacts without granting arbitrary shell access.
 
-A package-script check and the frontend validator are in the no-prompt set at `auto-edit`: both are bounded by the verification-script family and a fixed argv shape. A project-catalog check is not. The engine resolves the check id against `.clio-coder/verifiers.yaml` on every call and treats the declared argv exactly like a bash command string: the damage-control rules and the zero-access read guard scan it, and it is tagged unrecognized, so `auto-edit` parks it for one confirmation that shows the argv and `full-auto` runs it. `.clio-coder/verifiers.yaml` and `.clio-coder/safety.yaml` are read-only to the model's `write`, `edit`, and bash redirect paths through the default path policy: both files are operator authority, and a model that could author either one could widen its own permissions in two tool calls.
+A package-script check and the frontend validator are in the no-prompt set at `auto-edit`: both are bounded by the verification-script family and a fixed argv shape. A project-catalog check is not. The engine resolves the check id against `.clio-coder/verifiers.yaml` on every call and treats the declared argv exactly like a bash command string: the damage-control rules and the zero-access read guard scan it, and it is tagged unrecognized, so `auto-edit` parks it for one confirmation that shows the argv and `full-auto` runs it. `.clio-coder/verifiers.yaml`, `.clio-coder/safety.yaml`, `.clio-coder/skills/`, and the user-scoped `<configDir>/skills/` are read-only to the model's `write`, `edit`, and bash redirect paths through the default path policy: these files and skill roots are operator authority, and a model that could author them could change its own permissions or active instructions. Skill installs go through `clio-coder skills install`.
 
 The project verifier catalog is an executable authority supplied by the repository, not by model prose. Its schema rejects unknown fields, shell strings, invalid or duplicate IDs, oversized values, absolute or escaping working directories, unsupported versions, and collisions with package-provider IDs. It also refuses the common shell executables (`sh`, `bash`, `zsh`, and the like) as argv[0], which is a tripwire against the obvious mistake rather than a sandbox: `python3 -c`, `node -e`, and `env bash -c` pass the schema, so the authority boundary is the fact that the catalog file is operator-owned and read-only to the model, and that every catalog check is scanned by the damage-control rules and parked at `auto-edit`. A catalog entry fixes argv, repository-relative cwd, and timeout. Tool-call `args`, `cwd`, timeout, output-cap, or environment-shaped fields cannot widen it. Safe-exec uses `spawn` without a shell, filters the child environment to the Clio allowlist, honors cancellation, and reports exact argv and termination evidence.
 
@@ -373,26 +373,19 @@ It is critical to distinguish these two control axes:
 The effective rigor level for a session or dispatch run is resolved at boot time using the following prioritization:
 
 1. **Explicit Override**: Checked via the `CLIO_CODER_RIGOR` environment variable. It is trimmed and parsed case-insensitively. A value of `"high"` or `"normal"` overrides any other setting.
-2. **Repository-Derived Default**: If no override is present, Clio checks the workspace root for the presence of any of the following validation contract files:
-   - `.clio-coder/validation.yaml`
-   - `.clio-coder/validation.yml`
-   - `validation.yaml`
-   - `validation.yml`
-   - `VALIDATION.md`
-   
-   If any of these files are present, the default rigor level is raised to `high`. Otherwise, the default is `normal`.
+2. **Repository-Derived Default**: If no override is present, Clio loads the first of `.clio-coder/validation.yaml`, `.clio-coder/validation.yml`, `validation.yaml`, or `validation.yml` at the workspace root through the strict version-1 loader in `src/domains/safety/validation-contract.ts`. A contract that parses raises the default to `high`. A contract that does not parse leaves the default at `normal` and carries the fault as a diagnostic that `clio-coder doctor` and the interactive startup notices print. `VALIDATION.md` is advisory prose: it is recognized as present but never parsed and never raises rigor. `rigorResolution()` returns the rigor with its source (`override`, `validation-contract`, `invalid-contract`, `markdown-advisory`, or `none`) and the diagnostic; `resolveRigor()` is the thin wrapper that returns the rigor alone. See [Scientific Validation](../process/scientific-validation.md) for the schema.
 
 ---
 
 ### The Finish Gate and Re-Prompt Behavior
 
-On every settled `turn_end`, the finish-contract assessor scans entries since the last user message, capped at 80 entries. The trigger is action-scoped: the gate engages only when that window contains successful workspace mutation evidence and no validation evidence or explicit limitation. The model does not have to type a phrase such as `done` or `fixed`; the settled turn after mutation is the completion signal.
+On every settled `turn_end`, the finish-contract assessor scans entries since the last user message, capped at 80 entries. The trigger is action-scoped: the gate engages only when that window contains successful workspace mutation evidence and no validation evidence or `limitation` receipt. The model does not have to type a phrase such as `done` or `fixed`; the settled turn after mutation is the completion signal. The assistant's prose never enters the decision.
 
 The assessor decision order is:
 
 1. If the window has no successful mutating receipt or settled mutating `!` bash execution, the contract passes with `no_mutation`.
 2. If the window has validation evidence, the contract passes with `validation_evidence`. Evidence includes successful validation commands, `verify` checks (declared package scripts, admitted project-catalog entries, and the frontend check), passed dispatch receipts, and protected-artifact validation records.
-3. If the assistant explicitly states what could not be verified and why, the contract passes with `explicit_limitation`.
+3. If the window has a successful `limitation` tool receipt (a `limitation` tool_call paired with a non-error tool_result, carrying the scope, a reason from `no-runner`, `blocked`, `out-of-scope`, `environment`, or `other`, and optional unverified paths), the contract passes with `explicit_limitation`. A call the tool rejected leaves no receipt and does not count.
 4. Otherwise, the contract engages with `unvalidated_mutation`.
 
 The finish assessment projects only onto the canonical completion-evidence
@@ -405,11 +398,11 @@ persisted-format compatibility table are documented in
 [`evidence-and-memory.md`](evidence-and-memory.md#canonical-trust-status).
 
 - **Normal Rigor**: Clio issues a soft advisory warning (`FINISH_CONTRACT_ADVISORY_MESSAGE`) injected as a reminder for the next turn, but permits the turn to settle.
-- **High Rigor**: Clio withholds completion. The assessor emits `request_continuation` and a warning `inject_reminder` carrying `HIGH_RIGOR_REVALIDATION_MESSAGE`, instructing the model to run a verification-family command (e.g. `npm test`, `npm run build`) or explicitly declare a limitation before ending.
+- **High Rigor**: Clio withholds completion. The assessor emits `request_continuation` and a warning `inject_reminder` carrying `HIGH_RIGOR_REVALIDATION_MESSAGE`, instructing the model to run a verification-family command (e.g. `npm test`, `npm run build`) or call `limitation` before ending.
 
 #### Exemptions and Safety Precautions
 - **No-Mutation Turns**: Read-only status, alignment, and inspection turns are exempt because there is no successful workspace mutation in the recent window.
-- **Limitation Claims**: If the model explicitly states what could not be verified and why, the assessor accepts the statement as an explicit limitation and allows the turn to settle cleanly.
+- **Limitation Receipts**: A successful `limitation` tool receipt in the window settles the contract with `explicit_limitation`. The assistant's prose never does, so wording alone cannot pass the gate and a real limitation is never missed for its phrasing.
 - **Dynamic Injection**: All gate directives are injected dynamically through middleware effects. This ensures that the static system prompt prefix remains byte-stable, preserving prompt caches.
 - **Prior Hard-Block Preservation**: If a prior middleware hook has already emitted a hard block (e.g. tool-prose violation), the high-rigor continuation is suppressed so that critical error guidance is not overwritten.
 

package/docs/architecture/session-lifecycle.md

@@ -168,7 +168,7 @@ reported to `/cost` under a handoffs row and excluded from the turn count.
 
 ### Streaming Turn Settlement During Session Transitions
 
-When an operator issues `/new`, `/resume`, `/tree`, or `/fork` while an assistant turn is actively streaming, `settleChatBeforeSessionSwitch` (`src/interactive/session-switch-settlement.ts`) cancels the in-flight stream and awaits completion. This guarantees that partial assistant records and completed tool executions seal cleanly into the active session ledger before the session writer is replaced, preventing orphaned records in new sessions or unanswered prompts in original sessions (#114). Synchronous session transitions when chat is idle continue to execute immediately.
+When an operator issues `/new`, `/resume`, `/tree`, or `/fork` during streaming, `settleChatBeforeSessionSwitch` cancels and awaits the in-flight turn so partial assistant records and completed tools settle before replacing the writer. Shutdown separately stops shell admission and drains the active operator command. Hooks default to 500 ms each; the operator-shell hook allows six seconds for its existing five-second cancellation escalation, and worker group escalation uses 500 ms. Owned same-process-group descendants are covered by Linux validation, including descendants that close inherited pipes. Arbitrary daemonized or regrouped processes are outside this scope; macOS, Windows, and real SSH behavior remain unverified.
 
 ---
 
@@ -185,7 +185,7 @@ When resuming a session via `/resume` or a headless `clio-coder run --session <i
 
 ### Model-Facing Custom Entry Replay
 
-When resumed or forked session history is replayed to the model, custom session entries (such as compaction summaries, branch summaries, and operator bash executions) are projected into standardized user-role message text via `src/engine/messages.ts` constants (`COMPACTION_SUMMARY_PREFIX`, `BRANCH_SUMMARY_PREFIX`, `bashExecutionToText`) rather than ad-hoc formats, ensuring deterministic prompt construction across sessions.
+When resumed or forked session history is replayed to the model, compaction summaries, branch summaries, and operator bash executions use standardized user-role text through `src/engine/messages.ts`. Working-set projection runs before compaction counting and summary serialization, while raw ledger entries remain intact. Tool results hidden by summaries are discoverable with `context(scope="recall")` and recoverable by exact ref through the normal observation envelope; older destructive logs cannot recover removed bytes.
 
 ---
 
@@ -199,12 +199,12 @@ An explicit path ending in `.md` keeps the plain Markdown form: a heading, UTC e
 
 ## 7. Directory Handbooks and Project Overrides
 
-During session context loading, `loadProjectContextFiles` (`src/domains/context/clio-md.ts`) discovers root `CLIO-CODER.md` handbooks and directory-scoped `CLIO-CODER.override.md` files:
+During session context loading, `loadProjectContextFiles` (`src/domains/context/clio-md.ts`) captures readable authored Markdown from root `CLIO-CODER.md` handbooks and directory-scoped `CLIO-CODER.override.md` files. Optional structured projections do not determine source acceptance. Init, refresh, and reset invalidate captured session inputs; refresh preserves handbook bytes. Preload is bounded to 8,000 UTF-16 units and 220 rendered lines, with exact safe prefixes and capability-aware omission notices naming source paths and line ranges. Captured-source hashes are retained separately in accounting/manifest metadata. Tools-disabled targets cannot retrieve omitted suffixes through session tools; ordinary reads retrieve current content and retain their independent byte and 20 MB file limits:
 - An override handbook replaces inherited project instructions for its directory and all subdirectories, establishing an explicit subtree boundary.
 - Sibling directories remain unaffected.
 - Subdirectories within the subtree may supply narrower instructions with additional override files.
 - Prompt blocks preserve explicit source paths for provenance.
-- Malformed override files fail closed, and context resets never delete override files.
+- Empty or unreadable selected overrides fail closed; ordinary authored Markdown does not require a structured project heading. Context resets never delete override files.
 
 ---
 

package/docs/architecture/tui-design.md

@@ -314,7 +314,7 @@ The `/settings` overlay is a full-screen transactional control center:
 
 ### 7.2 Fleet Runs Board
 
-The `Alt+W` board renders one card per run. The default list is compact: run id, route, task, status, telemetry, retry, tool names, and proof. `Enter` opens the selected run's worker detail, which adds two rows to that card and nothing to any other:
+The `Alt+W` board renders one card per run from the observability run projection, which owns lifecycle, worker progress, receipt trust, retries, cancellation, fleet positions, and evidence readiness; the board owns only ordering, selection, and rendering. The default list is compact: run id, route, task, status, telemetry, retry, tool names, and proof. `Enter` opens the selected run's worker detail, which adds two rows to that card and nothing to any other:
 
 - **`doing`**: the phase (`◐ thinking` in `reason`, `◑ writing` in `accent`, `⚙ tool` in `action`, `◔ waiting` in `info`) followed by the running call as `<tool> <verb> <object>`, or the last finished call as `last <tool> <verb> <object>`. The verb and object come from a descriptor composed at the worker seam; raw arguments never reach the renderer.
 - **`answer`**: the newest rows of the worker's bounded prose on a `│` rail with a hanging indent under the key, then a dim row naming the lines and bytes the bounds refused and the `/view dispatch:<runId>` deep link.

package/docs/architecture/worker-dispatch-mechanics.md

@@ -247,3 +247,7 @@ The child process exits with specific status codes to signal run outcomes to the
 * **`2`**: Worker runtime initialization failed (e.g., target runtime not registered, or `WorkerSpec` invalid/mismatched).
 * **`3` (`WORKER_EXIT_PERMISSION_REQUIRED`)**: The run aborted because a tool required permission and `onPermission` was set to `fail` (or timed out to a `fail` fallback).
 * **Other (e.g., `1` or uncaught exceptions)**: Represents an unhandled crash or internal error within the runner.
+
+## Antigravity conversation identity
+
+Antigravity resumes a conversation only when a caller explicitly supplies its conversation ID through the worker runtime. The dispatch tool exposes no resume argument. A nonempty ID must be at most 4096 UTF-8 bytes and contain no Unicode control characters; it is passed as a literal `--conversation` argument. Clio requires the first init conversation ID to match the requested ID and fails the run if agy starts a different conversation. An absent or empty ID starts fresh. Antigravity runs are never retried automatically.

package/docs/guide/built-in-agents.md

@@ -49,14 +49,14 @@ User-facing agents visible in `clio-coder agents` and `/agents`.
 
 | Agent ID | Primary tools | Purpose | Capability | Latency |
 | --- | --- | --- | --- | --- |
-| `architect` | read, grep, find, ls, code_nav, git, artifact, context, ledger | Designs a change across boundaries and slices it into a sprint: contracts, migrations, validation gates, and cut-it sprint slicing. | `artifact-write` | `deep` |
-| `coder` | read, write, edit, grep, find, ls, web_fetch, git, bash, verify, code_nav, ledger | Implements bounded code changes, repairs, and refactors, behavior-preserving by default. | `workspace-edit` | `balanced` |
+| `architect` | read, grep, find, ls, code_nav, git, artifact, context, ledger, limitation | Designs a change across boundaries and slices it into a sprint: contracts, migrations, validation gates, and cut-it sprint slicing. | `artifact-write` | `deep` |
+| `coder` | read, write, edit, grep, find, ls, web_fetch, git, bash, verify, code_nav, ledger, limitation | Implements bounded code changes, repairs, and refactors, behavior-preserving by default. | `workspace-edit` | `balanced` |
 | `debugger` | read, grep, find, ls, git, verify, code_nav, ledger | Diagnoses failing code, tests, or runs without editing, reading receipts, logs, and runtime behavior. | `verification` | `balanced` |
-| `documenter` | read, write, edit, grep, find, ls, git, verify, code_nav, context, ledger | Updates developer docs, examples, and operational runbooks. | `workspace-edit` | `balanced` |
-| `git-master` | read, write, edit, context, git, bash, grep, find, ls, code_nav, ledger | Runs bounded git operations end to end: history, commits, worktrees, integration merges, and PR prep. | `workspace-edit` | `balanced` |
-| `tester` | read, write, edit, grep, find, ls, git, verify, code_nav, ledger | Adds focused deterministic regression and coverage tests. | `workspace-edit` | `balanced` |
-| `verifier` | read, grep, find, ls, git, verify, code_nav, ledger | Runs test, lint, build, review, and release gates and reports each independently. | `verification` | `fast` |
-| `wiki-writer` | read, write, edit, grep, find, ls, code_nav, context, ledger | Plans a repository wiki or writes one wiki page against a supplied plan. | `workspace-edit` | `balanced` |
+| `documenter` | read, write, edit, grep, find, ls, git, verify, code_nav, context, ledger, limitation | Updates developer docs, examples, and operational runbooks. | `workspace-edit` | `balanced` |
+| `git-master` | read, write, edit, context, git, bash, grep, find, ls, code_nav, ledger, limitation | Runs bounded git operations end to end: history, commits, worktrees, integration merges, and PR prep. | `workspace-edit` | `balanced` |
+| `tester` | read, write, edit, grep, find, ls, git, verify, code_nav, ledger, limitation | Adds focused deterministic regression and coverage tests. | `workspace-edit` | `balanced` |
+| `verifier` | verify, evidence, read, grep, find, ls, git, code_nav, ledger | Runs test, lint, build, review, and release gates and reports each independently. | `verification` | `fast` |
+| `wiki-writer` | read, write, edit, grep, find, ls, code_nav, context, ledger, limitation | Plans a repository wiki or writes one wiki page against a supplied plan. | `workspace-edit` | `balanced` |
 
 ### Shipped Shadow and Internal Agents
 Internal orchestration helpers and internal process agents. They are hidden from default displays but visible via `clio-coder agents --all`. The full on-demand catalog has a separate shadow section and omits internal recipes; the compact session prompt likewise omits internal recipes and also excludes the operator-only `oracle`.
@@ -66,7 +66,7 @@ Internal orchestration helpers and internal process agents. They are hidden from
 | `scout` | read, grep, find, ls, context, code_nav, git, ledger | Broad repository reconnaissance with cited findings: orientation, structure and entry-point mapping, multi-file symbol hunting. | `read-only` | `fast` |
 | `researcher` | read, web_fetch, context, ledger | Extracts and compares concrete supplied URLs, standards, release notes, and papers through Clio-observed reads and URL retrieval. | `read-only` | `deep` |
 | `world-knowledge` | optional web_fetch, read, context, ledger | Current open-world discovery, ecosystem comparison, broad external context, and an advisory second opinion; reports when discovery is unavailable. | `read-only` | `deep` |
-| `provenance` | read, grep, find, ls, git, ledger | Reads receipts, diffs, and telemetry for evidence-backed handoffs. | `read-only` | `balanced` |
+| `provenance` | evidence, read, grep, find, ls, git, ledger | Reads receipts, diffs, and telemetry for evidence-backed handoffs. | `read-only` | `balanced` |
 | `oracle` | read, grep, find, ls, code_nav, context, ledger | Shadow advisor behind `/oracle` that protects consistency with prior decisions and returns the strongest challenge to a question. | `read-only` | `deep` |
 | `context-bootstrap` | read, grep, find, ls, context, code_nav | Internal agent behind `clio-coder context init` that parses repository and returns CLIO-CODER.md payload. | `read-only` | `balanced` |
 

package/docs/guide/commands-and-modes.md

@@ -33,7 +33,7 @@ For process exit codes, stdout deliverable guarantees, and machine-readable JSON
 | `clio-coder config [inspect] [--json]` | Print the effective customization graph across settings, context files, rules, skills, prompts, agents, extensions, safety, memory, hooks, and operator profile. |
 | `clio-coder targets [--json] [--probe] [--target <id>]` | List configured targets, health, auth, runtime, model, and capabilities. |
 | `clio-coder targets add` | Add a target interactively or through configure flags. |
-| `clio-coder targets use <id> [--model <id>] [--orchestrator-model <id>] [--background-model <id>] [--fleet-target <id>] [--fleet-model <id>]` | Point the orchestrator at one target. Without `--fleet-target` the fleet default follows it; with `--fleet-target` the fleet runs on a different node. |
+| `clio-coder targets use <id> [--model <id>] [--orchestrator-model <id>] [--background-model <id>] [--fleet-target <id>] [--fleet-model <id>]` | Select the named roles only when any role flag is present. `--background-model` selects memory; `--orchestrator-model` selects chat; `--fleet-model` or `--fleet-target` selects fleet. Other roles and thinking levels are preserved. Without role flags, chat and fleet use the target default (or shared `--model`), while memory is preserved. Confirmation names only roles whose settings changed. Model IDs must match a nonempty discovered or cached inventory exactly; unavailable discovery is reported explicitly. |
 | `clio-coder targets fleet [--json]` | List the configured fleet profiles with their target, runtime, model, and thinking level. `targets workers` is an accepted alias. |
 | `clio-coder targets profile list\|set\|remove\|rename\|bind\|unbind\|bindings` | Manage named fleet profiles and agent bindings. `clio-coder targets profile <name> <id>` is the short form of `profile set`, and `targets worker` is an accepted alias for `targets profile`. |
 | `clio-coder targets convert <id> --runtime <runtimeId>` | Convert older local target definitions to a runtime-specific target. |
@@ -86,9 +86,10 @@ For process exit codes, stdout deliverable guarantees, and machine-readable JSON
 | `clio-coder context` | Show project context status, preload class, codewiki freshness, and the codewiki digest when present. |
 | `clio-coder context init [--preview] [--heuristic] [--yes] [--json] [--adopt] [--global] [--propose\|--apply\|--rewrite] [--target <id> [--model <id>] [--thinking <level>]]` | Explore the repo and bootstrap or update project context: `CLIO-CODER.md`, `.clio-coder/codewiki.json`, and `.clio-coder/state.json`. |
 | `clio-coder context refresh [--wiki]` | Rebuild the codewiki and state without touching `CLIO-CODER.md`; with `--wiki`, update an existing Markdown wiki. |
-| `clio-coder context wiki [--update] [--status] [--depth auto\|simple\|medium\|detailed] [--target <id>] [--model <id>] [--thinking off\|low\|medium\|high]` | Generate, update, or inspect the agent-authored Markdown wiki under `.clio-coder/wiki/`. |
+| `clio-coder context wiki [--update\|--retry-pending] [--status] [--depth auto\|simple\|medium\|detailed] [--target <id>] [--model <id>] [--thinking off\|low\|medium\|high]` | Generate, update, or inspect the agent-authored Markdown wiki under `.clio-coder/wiki/`. |
 | `clio-coder context reset [--all] [--yes]` | Clear accumulated project context artifacts; `--all` also removes `CLIO-CODER.md`. `--yes` (or `-y`) answers every confirmation and is required when stdin is not a terminal. |
 | `clio-coder context index [--json]` | Build the structural codewiki index without model calls; writes `.clio-coder/codewiki.json` and `.clio-coder/state.json` and prints coverage plus a structural hash. |
+| `clio-coder context map [--out <path>] [--json]` | Write an archify architecture seed from the structural index without model calls. |
 | `clio-coder context replay (--sessions <path>... \| --synthetic <ids>) [--policies <ids>] [--budgets <tokens>] [--threshold <ratio>] [--target <ratio>] [--protect-last-turns <n>] [--min-evictable-tokens <n>] [--seed <n>] [--no-filter] [--json <out>] [--md <out>]` | Replay working-set policies over Clio session ledgers or the seeded procedural corpora and report retention, precision, token savings, recall cost, cold-prefix cost, saturation, and summary headroom. |
 | `clio-coder context working-set --session <id\|path>` | Inspect one session's durable working-set fold and path-index summary without modifying the ledger. |
 
@@ -103,7 +104,6 @@ For process exit codes, stdout deliverable guarantees, and machine-readable JSON
 | `--temperature <n>` / `--top-p <n>` / `--top-k <n>` / `--min-p <n>` | One-run sampler overrides when the selected runtime supports them. |
 | `--presence-penalty <n>` / `--frequency-penalty <n>` / `--repeat-penalty <n>` | One-run penalty overrides when the selected runtime supports them. |
 | `--max-context-tokens <n>` | One-run context-window override for supported local runtimes. |
-| `--kv-cache-mode <mode>` | One-run KV-cache override for supported local runtimes: `f16`, `f32`, `none`, `false`, `q8_0`, `q4_0`, `q4_1`, `iq4_nl`, `q5_0`, or `q5_1`. |
 | `--json` | Stream JSONL events for main-agent runs; dispatch streams events and receipt JSON. |
 | `--json-events <mode>` | Main-agent JSON stream mode: `full` or `terminal`; implies `--json`. |
 | `--session <id>` | Append this turn to an existing session identified by `<id>`. |
@@ -138,6 +138,7 @@ A headless turn (`clio-coder run`) starts a fresh session unless `--session <id>
 - `--session` and `--continue` are mutually exclusive. Specifying both causes the invocation to fail with exit code 2 before execution.
 - Session continuity options apply strictly to main-agent execution. They are non-applicable to `--agent` fleet dispatches because dispatched agents execute in isolated worker processes with independent transcripts; specifying session flags alongside `--agent` exits with code 2.
 - A named session that cannot be resumed (such as an unknown session ID or unreadable history) fails the run with exit code 2 before any model call is initiated.
+- An explicit `--target <id>` resolves targets from layered project settings (`.clio-coder/settings.yaml`, `.clio-coder/settings.local.yaml`) as well as user settings before applying target-not-found validation.
 - The session ID is discoverable via the `session` event when running under `--json` mode and on stderr via the `clio-coder run: session <id>` line in text mode. Standard output remains reserved for the assistant answer alone.
 
 ### JSON Event Streaming and Wire Projection Promise
@@ -182,7 +183,7 @@ The registry table below lists the available interactive slash commands. On a ba
 | `/context` | `/context compact [instructions] \| /context recall <ref> \| /context init \| /context refresh \| /context reset` | Context hub: window overlay plus compact, recall, init, refresh, and reset |
 | `/fleet` | `/fleet run [--var <key=value>] <name>` | Open Settings → Fleet, or run a fleet contract with an approval preview |
 | `/decisions` | `/decisions` | Show settled interview decisions and operator revisions |
-| `/tasks` | `/tasks add <text> \| /tasks hand <id> \| /tasks done <id> \| /tasks drop <id>` | Show the session board or manage project operator tasks |
+| `/tasks` | `/tasks add [--expect <path>] [--verify <checkId>[:timeoutMs]] <text> \| /tasks hand <id> \| /tasks done <id> \| /tasks drop <id>` | Show the session board or manage project operator tasks |
 | `/memory` | `/memory seed` | Inspect, promote, or seed task memory |
 | `/view` | `/view [filter] \| /view verify <runId>` | Browse session artifacts and verify receipts |
 | `/panes` | `/panes show <run-or-agent> \| /panes open <preset-or-argv> \| /panes zoom [target] \| /panes close [target]` | Inspect the pane layer, watch a live run in a pane, or open a utility pane (`files`, `logs`, `shell`, `files --once`, or a command); a second open focuses the pane already there |
@@ -198,11 +199,23 @@ The registry table below lists the available interactive slash commands. On a ba
 | `/fork` | `/fork` | Fork from an assistant turn |
 | `/export` | `/export [path]` | Export a self-contained HTML transcript by default; a `.md` path writes Markdown |
 
-Retired spellings fail closed and print their exact replacement. In particular,
-`/targets` points to `/settings targets`, `/scoped-models` points to
-`/settings chat model-picker`, and `/library`, `/prompts`, and `/extensions`
-point to the corresponding `/resources` subcommand. They never fall through to
-the model as prompt text.
+Operator tasks are durable project work in `.clio-coder/user-tasks.json`. Use
+`clio-coder tasks add "Fix the solver" --expect src/solver.ts --verify test:solver:60000`
+or `/tasks add Fix the solver --expect src/solver.ts --verify test:solver:60000`.
+Both `--expect <path>` and `--verify <checkId>[:timeoutMs]` are repeatable. Expected
+outputs use repository-relative paths; verification ids must exist in the project
+verifier catalog or package scripts when added. An omitted timeout uses the
+check's declared timeout, and requested timeouts are bounded as in dispatch
+intent. If a complete value matches a declared id containing colons, it names
+that check; otherwise the final numeric suffix is the timeout. Acceptance travels
+with the task when handed and picked, and seeds the board's required validation
+evidence. Under high rigor, a turn that changes files while this task is active
+must record a passing validation receipt for every named check or a successful
+`limitation` receipt whose `paths` array includes the exact check id. A task's
+completion note alone does not satisfy acceptance. `clio-coder tasks list`,
+`hand <uN>`, `done <uN>`, and `drop <uN>` manage the same inbox as `/tasks`.
+
+Retired spellings are unrecognized commands and use the standard unknown-command diagnostic; they do not print automatic replacement hints. Use supported spellings such as `/settings targets`, `/settings chat model-picker`, and the corresponding `/resources` subcommand. Unrecognized commands are not sent to the model as prompt text.
 
 `/context` with no arguments opens the context-window ledger overlay, including
 the working-set section (policy, evicted items and tokens, events, recalls, churn).
@@ -428,14 +441,7 @@ one or `d` to decline; the overlay reads the report this process already produce
 at boot and never probes on a keystroke. Accepting applies to the live session,
 because `delegation` hot-reloads.
 
-Boot adds at most one line about interop, in the current source shape
-`clio-coder: codex detected on PATH and not configured. Run /interop to review.`
-The `/interop` name is retained only as a retired-command tombstone and answers
-`Use /agents connect.`, so operators can open `/agents connect` directly. The
-hint names only agents that are installed, unconfigured, and undecided, appears
-at most once per set of facts, and is never emitted in headless or ACP mode.
-Declining an agent silences it until its binary version or path changes, at which
-point it becomes a fresh proposal.
+Boot adds at most one line about interop. The current hint can still say `Run /interop to review.`, but `/interop` is unrecognized and receives the standard unknown-command diagnostic. Open `/agents connect` directly. The hint names only agents that are installed, unconfigured, and undecided, appears at most once per set of facts, and is never emitted in headless or ACP mode. Declining an agent silences it until its binary version or path changes, at which point it becomes a fresh proposal.
 
 `clio-coder doctor` reports interop and never proposes anything. It emits one
 `ok` row per detected agent naming its version, its path, and whether it is
@@ -591,14 +597,14 @@ to execute through the existing engine worker path, the sanctioned Claude Code w
 
 | Command | Purpose |
 | --- | --- |
-| `npm run ci` | Local and GitHub PR gate: typecheck, lint, skills pin check, build, the deterministic test suite, and the trace-viewer suite. |
-| `npm run ci:release` | Maintainer release gate: `npm run ci`, then the `check-release` dist and packaging audit. |
-| `npm run typecheck` | Strict TypeScript pass. |
-| `npm run lint` | Biome checks plus `scripts/check-hygiene.ts`, which runs the boundary invariants, the skills pin check, and the README and docs drift rules. |
-| `npm test` | Focused contract and smoke files through plain `node --test`. |
-| `npm run build` | Production bundle through `tsup`. |
-| `npm run dev` | `tsup --watch`. |
-| `npm run clean` | Remove `dist/`. |
+| `pnpm run ci` | Local and GitHub PR gate: typecheck, lint, skills pin check, build, the deterministic test suite, and the trace-viewer suite. |
+| `pnpm run ci:release` | Maintainer release gate: `pnpm run ci`, then the `check-release` dist and packaging audit. |
+| `pnpm run typecheck` | Strict TypeScript pass. |
+| `pnpm run lint` | Biome checks plus `scripts/check-hygiene.ts`, which runs the boundary invariants, the skills pin check, and the README and docs drift rules. |
+| `pnpm test` | Focused contract and smoke files through plain `node --test`. |
+| `pnpm run build` | Production bundle through `tsup`. |
+| `pnpm run dev` | `tsup --watch`. |
+| `pnpm run clean` | Remove `dist/`. |
 
 Live provider checks cost tokens or local GPU time and are deliberately not
 part of deterministic CI. Maintainers perform them explicitly against an
@@ -636,6 +642,8 @@ structural hash. The same builder is used by `clio-coder context init`, `clio-co
 refresh`, session freshness checks, tool-demand backfill, and in-session
 incremental updates.
 
+`clio-coder context map` derives an archify architecture specification from the structural index without model calls and writes it to `.clio-coder/artifacts/maps/<repo>.architecture.json` (or `--out <path>`). Map generation reconciles the existing structural index before mapping; missing index refuses, naming `clio-coder context index`. Pinned source citations require that the workspace is clean at repository root and indexed file bytes match current files and Git blobs under a GitHub origin and full `HEAD` revision. Unknown or dirty source states fall back cleanly to usable uncited seeds; `--json` reports path, counts, repository metadata, reconciled index status, and source state (`clean`, `dirty`, or `unknown`). Clio produces the deterministic seed while Archify validates and delivers it. Standard validation checks schema conformance and layout composition, while source review assesses semantic claims and visual review in a browser assesses layout presentation. Custom model-authored maps can remain layout-invalid until refined.
+
 ### Working-set replay
 
 `clio-coder context replay --sessions <path>...` accepts individual session directories,
@@ -687,19 +695,31 @@ matter after the run, so no dispatch writes them. `.clio-coder/wiki/meta.json` r
 the page list, model label, content hash, git head, indexed source-tree hash,
 and the plan.
 
-Each page dispatch is bounded on its own wall clock, and the run is bounded
-between pages. Neither bound loses work: a page that fails or times out is
-recorded as still owed and the run continues to the next one, and every finished
-page is assembled and promoted. When `generation.pagesWritten` is below
-`generation.pagesPlanned`, run `clio-coder context wiki --update` to finish the rest;
-it resumes from the plan rather than starting over.
-
-`clio-coder context wiki --update` requests update mode explicitly. It rewrites the
-pages whose front-matter `sources` git reports as changed since the recorded
-wiki `gitHead`, and leaves the rest alone.
+Ordinary planner, page, and whole-run time and tool estimates are advisory across
+generation, not automatic aborts. An explicit caller deadline (`timeout_ms`) or
+operator cancellation remains authoritative. Failed writers remain pending; admission
+rejection does not consume a writer attempt. When `generation.pagesWritten` is below
+`generation.pagesPlanned`, run `clio-coder context wiki --update` to continue pending pages
+and refresh stale pages based on changed source dependencies, or run `clio-coder context wiki --retry-pending`
+to retry each pending page once, including exhausted pages, without erasing cumulative attempts
+or replanning at the same depth.
+
+Coverage depth is controlled by `--depth auto|simple|medium|detailed` and is harness-owned;
+explicit upgrades and downgrades requeue coverage while retaining existing prose, and
+default retries retain saved depth. Both original writer output and saved pages pass nonmutating
+mechanical validation (missing/escaping paths, invalid line ranges, malformed source/test
+metadata, or empty bodies keep pages pending); mechanical checks do not establish semantic
+accuracy or that the model read the source.
+
+`clio-coder context wiki --update` requests update mode explicitly. It revalidates
+pages against bounded source-byte evidence and recorded source and test dependencies
+rather than assuming unmentioned pages remain fresh. Pages with changed inputs or
+dependencies, as well as pages whose Git evidence is missing, unreadable, or changed,
+are re-queued for generation, while verified up-to-date pages are preserved; it is not a
+promise to overcome exhausted attempts.
 `clio-coder context wiki --status` is read-only: it prints whether wiki metadata is
 present, page count, `updatedAt`, recorded `gitHead`, whether that head differs
-from current `HEAD`, and how many planned pages remain unwritten. It dispatches
+from current `HEAD`, and retained failure diagnostics for unwritten planned pages. It dispatches
 nothing and spends no model tokens.
 
 `clio-coder context refresh` rebuilds only the structural codewiki and state. It does
@@ -810,11 +830,11 @@ All TUI overlays fluidly adapt to narrow terminals down to 40 columns:
 
 | Problem | Try this |
 | --- | --- |
-| `clio-coder: command not found` | Run `npm run install:local`, then `hash -r`; confirm `${CLIO_CODER_BIN_DIR:-$HOME/.local/bin}` is on `PATH`. |
+| `clio-coder: command not found` | Run `pnpm run install:local`, then `hash -r`; confirm `${CLIO_CODER_BIN_DIR:-$HOME/.local/bin}` is on `PATH`. |
 | No model target is available | Run `clio-coder configure`, then `clio-coder targets --probe`. |
 | Local model does not respond | Confirm the runtime is running and the target URL is correct. |
 | Cloud model auth fails | Check `clio-coder auth status <target>` and verify the relevant API key or login flow. |
-| Source changes do not appear | Re-run `npm run build`; linked CLI points at `dist/`. |
+| Source changes do not appear | Re-run `pnpm run build`; linked CLI points at `dist/`. |
 | Session replay looks incomplete | Confirm durable session entries exist for the relevant tool, bash, or display activity. |
 | Doctor reports stale state metadata | Run `clio-coder doctor --fix`; upgrades also refresh install metadata after reinstalling. |
 | You need a clean start | Use `clio-coder reset --state`, `--data`, `--cache`, `--auth`, `--config`, or `--all`. |
@@ -833,3 +853,11 @@ actual behavior. Redact secrets and private repository content.
 > CLI subcommands (`targets use/remove/rename/profile/convert`, `context refresh`,
 > `fleet list/run/status/drain/resume`, `auth login`), passing `--help` prints
 > usage instructions and exits with code 0.
+
+## Operator-task handoff and continuation
+
+`clio-coder tasks hand <uN>` prints the inbox record as JSON on stdout and an actionable pickup prompt on stderr. Submit that prompt to the intended session. Before task work, the model must pick the intended `uN`, confirm its durable session and board linkage, and use the returned `tN`. Handing a task does not itself pick it. Completion should be checked against the linked board and inbox with the actual IDs; manual CLI completion is an operator action, not evidence of model completion.
+
+Acceptance rows labeled Required declare expected checks and timeout limits; they are not pending executions or passing results. Inspect verification receipts for outcomes. Under high rigor, the finish gate requires the applicable passing checks or explicit limitations.
+
+Task-board guidance and ordinary continuation preserve proposal-only scope. Deferred implementation should be blocked or dropped while awaiting an explicit operator go-ahead. A skill-install decision is separate from implementation authorization, and full-auto capability does not expand the task. These are model instructions, not a guarantee of model adherence.

package/docs/guide/configuration-and-targets.md

@@ -52,8 +52,9 @@ From a source checkout:
 ```bash
 git clone https://github.com/iowarp/clio-coder.git
 cd clio-coder
-npm ci
-npm run install:local
+corepack enable pnpm
+pnpm install --frozen-lockfile
+pnpm run install:local
 hash -r
 clio-coder --version
 ```
@@ -312,7 +313,7 @@ The tool-prose-loop detector is keyed on the same tier, for the same reason: nar
 
 ### LM Studio transport and settings
 
-The canonical runtime id is `lmstudio`. The former `lmstudio-native` id remains an accepted alias,
+The canonical runtime id is `lmstudio`. The former `lmstudio-native` id remains an accepted alias scheduled for removal in v0.7.0,
 and `clio-coder upgrade` rewrites persisted targets to the canonical id. It also converts `ws:` URLs
 to `http:` and `wss:` URLs to `https:` because this adapter is entirely HTTP. Chat uses LM Studio's
 OpenAI-compatible `POST /v1/chat/completions` endpoint
@@ -903,6 +904,8 @@ Antigravity remains an external agent loop: Clio cannot intercept each tool call
 | `suggest` | Refused because a headless subprocess cannot pause for Clio approval |
 | `full-auto` | Capped at `accept-edits` unless the external full-access gate is explicitly enabled |
 
+Launch flags are a request to agy rather than a guarantee. Headless agy reports `permission_mode: always-proceed` even under `--mode plan --sandbox`, and Clio grades autonomy enforcement as `approximated` in execution receipts. The only Clio-enforced read-only boundary is the receipt grade.
+
 Only `full-auto` together with `CLIO_CODER_ALLOW_EXTERNAL_FULL_ACCESS=1` passes `--dangerously-skip-permissions`. Treat that as an external safety bypass: agy, not Clio's tool registry, controls the resulting filesystem, shell, network, prompts, and approvals. The gate is never enabled by onboarding. A `world-knowledge` dispatch remains read-only even if the caller requests a stronger posture; use another agent for mutation work.
 
 **Setup and verification:**
@@ -1139,3 +1142,7 @@ clio-coder auth status <target-or-runtime>
 ```
 
 When opening issues, include the Clio version, Node version, target id/runtime, model id, whether the live model listing succeeds (or the target probe result), and a redacted receipt or command transcript.
+
+## Explicit Antigravity continuity
+
+Antigravity resumes a conversation only when a caller explicitly supplies its conversation ID through the worker runtime. The dispatch tool exposes no resume argument. A nonempty ID must be at most 4096 UTF-8 bytes and contain no Unicode control characters; it is passed as a literal `--conversation` argument. Clio requires the first init conversation ID to match the requested ID and fails the run if agy starts a different conversation. An absent or empty ID starts fresh. Antigravity runs are never retried automatically.