@iowarp/clio-coder 0.4.7 → 0.4.9

package/docs/process/tool-audit-v0.4.9.md

@@ -0,0 +1,357 @@
+# Individual Tool Audit for v0.4.9
+
+This is the landed disposition of each builtin tool and each dynamic capability family. It replaces the pre-implementation findings with the current contract, without treating placement as proof of correctness. Source references name the implementation; [Tool usage](../guide/tool-usage.md) supplies detailed arguments and examples. `src/tools/surface.ts` owns placement and `src/tools/policy.ts` owns action class/concurrency. There are 30 builtin names, plus extension and MCP families whose individual schemas are discovered at runtime.
+
+The implementation commits are on the candidate branch; this document does not claim that the version has been published. Scientific integrity below describes evidence and limits, not an empirical certification of each tool. Existing orchestration and interaction behavior was checked for its documentation contract; no new scientific benchmark or full source re-audit is claimed.
+
+## read
+
+- **Purpose:** Retrieve cited text windows or supported images from a known file.
+- **Placement:** Direct OBSERVE, read class, parallel.
+- **Contract:** `path`, `offset`, `limit`, `tail`, `line_numbers`; bounded text and file identity/change details; refuse binary or invalid UTF-8 with byte offsets.
+- **Implementation:** `src/tools/read.ts` uses bounded fd windows and backward tail scans. Exact counts stop above 32 MiB; images keep a 20 MB (20000000 bytes) ceiling. Observation bytes and lines are bounded. Tail numbering is refused when the total is unknown.
+- **Scientific integrity:** `N+` and continuation distinguish a window from a dataset. Observed changes do not create snapshot isolation; unread bytes are not validated.
+- **Disposition:** Redesign the whole-file reader; retain explicit pagination and image behavior.
+
+Status: landed in `30826041`.
+
+## write
+
+- **Purpose:** Create or regenerate a complete UTF-8 file.
+- **Placement:** Direct MUTATE, write class, sequential.
+- **Contract:** `path`, `content`; byte count, eligible diff, paths, before/after identity, and possible durability warning. Existing targets are overwritten.
+- **Implementation:** `src/tools/write.ts` and `src/tools/file-mutation-queue.ts` serialize same-target writes and publish by temporary file, fsync, and real-target rename. Previous-content comparison is bounded; either version above 1 MiB skips diff generation. Symlink targets and mode bits are preserved.
+- **Scientific integrity:** No partial publication before rename, but external writers are unlocked and last rename wins. Ownership, ACLs, xattrs, and original timestamps are not preserved. A write is not data validation.
+- **Disposition:** Repair publication and evidence; retain full-file replacement semantics.
+
+Status: landed in `82ebee28`.
+
+## edit
+
+- **Purpose:** Apply disjoint targeted replacements to one existing text file.
+- **Placement:** Direct MUTATE, write class, sequential.
+- **Contract:** `path`, `edits`; refuse absent/ambiguous matches, overlaps, no-ops, NUL, invalid UTF-8, mixed endings, and bare CR. Preserve BOM and uniform LF/CRLF.
+- **Implementation:** `src/tools/edit.ts`, `edit-diff.ts`, and `file-mutation-queue.ts`. Small files try exact, normalized punctuation/whitespace, then indentation-relaxed matching. Above 1 MiB only exact matching is allowed. Atomic publication and identity reporting match write; large diffs are skipped before construction.
+- **Scientific integrity:** Invalid bytes are never silently repaired. Editing still holds source/replacement in memory; file identity does not enforce an earlier-read precondition or lock external writers.
+- **Disposition:** Repair encoding, publication, and large-file allocation behavior.
+
+Status: landed in `82ebee28`.
+
+## bash
+
+- **Purpose:** Execute shell workflows that require shell semantics.
+- **Placement:** Direct EXECUTE, execute class, sequential; command classification can escalate authority.
+- **Contract:** `command`, `cwd`, `timeout_ms`, `output_policy`; combined result with separate termination and disposition facts. The combined 16 MiB output ceiling stops the child.
+- **Implementation:** `src/tools/bash.ts`, `src/core/bash-exec.ts`, and result shaping retain the existing process lifecycle and login-environment snapshot. Cap handling distinguishes raw observed and retained bytes, decoded retention, actual offload, and discarded bytes.
+- **Scientific integrity:** Summary and metadata-only projections preserve failure/retrieval facts. A cap is unsuccessful partial execution, not a complete dataset; use run_script for streaming.
+- **Disposition:** Retain the cap and repair diagnostic and retention honesty.
+
+Status: landed in `bde78f76`.
+
+## grep
+
+- **Purpose:** Locate content matches with source-line citations.
+- **Placement:** Direct OBSERVE, read class, parallel.
+- **Contract:** Pattern/path, content/files/count modes, glob, context, limits, and ignore options; partial results carry `details.search` completeness, reason, skipped counts/samples, and unknown coverage.
+- **Implementation:** `src/tools/grep.ts` and `spawn-hygiene.ts` preserve collected native results on timeout, cancellation, and recoverable errors. Native diagnostics have bounded decoding; fallback traversal/read work is asynchronous and skips oversized, binary, or unreadable inputs explicitly.
+- **Scientific integrity:** Complete empty and incomplete searches are distinct. Native `.gitignore` and fallback generated-directory-only semantics are disclosed; counts never imply unseen paths were searched.
+- **Disposition:** Repair completeness, diagnostics, and responsiveness.
+
+Status: landed in `17e2de0b`; ignore-policy clarification in `bde78f76`.
+
+## find
+
+- **Purpose:** Locate paths using filename/glob or bounded recent-change selection.
+- **Placement:** Direct OBSERVE, read class, parallel.
+- **Contract:** `pattern`, `path`, `order`, `limit`, `include_ignored`; paths, continuation, candidate bounds, and `details.search`.
+- **Implementation:** `src/tools/find.ts` keeps fd's glob/smart-case filtering and native result cap. The fallback is asynchronous. Mtime selection stats only a bounded candidate set; neither traversal follows symlinked directories.
+- **Scientific integrity:** Mtime order can be approximate. Native skipped symlink-directory counts are explicitly unavailable (`counted=false`); fallback counts them. Native and fallback matching/ignore semantics are not guaranteed identical.
+- **Disposition:** Retain native filtering and repair incomplete-search evidence.
+
+Status: landed in `17e2de0b`.
+
+## ls
+
+- **Purpose:** Inspect one directory, including symlinks and broken entries.
+- **Placement:** Direct OBSERVE, read class, parallel.
+- **Contract:** `path`, `limit`; alphabetical entries, `name@ -> target` or `name@ (broken)`, failure markers, `details.skipped`, and `details.selection`.
+- **Implementation:** `src/tools/ls.ts` asynchronously enumerates, keeps O(limit) selected names in a heap, and stats only selected entries. Case-insensitive ties preserve enumeration order. Listing still scans the directory to select its prefix.
+- **Scientific integrity:** Broken or unreadable entries do not disappear silently. Bounded retained state is not a claim of constant total work.
+- **Disposition:** Repair link truthfulness and selection allocation.
+
+Status: landed in `17e2de0b`.
+
+## code_nav
+
+- **Purpose:** Retrieve indexed repository symbols, paths, outlines, dependencies, entries, and generated wiki context.
+- **Placement:** Direct OBSERVE, read class, parallel; worker profile/recipe policy can omit it.
+- **Contract:** Mode, query, and bounded limit select structured index results with citations, omissions, and continuation; unavailable index/invalid queries return actionable failures.
+- **Implementation:** `src/tools/codewiki/code-nav.ts` and `code-nav-surface.ts` use the codewiki index and a 16KB observation cap. Result selection is bounded, but the loaded index and index searches are not a streaming live filesystem scan.
+- **Scientific integrity:** Index freshness and source citations bound the claim. Navigation is neither executed validation nor evidence that a dataset is complete.
+- **Disposition:** Retain the existing indexed navigation contract; no release-specific numerical processing is added.
+
+Status: unchanged in v0.4.9 because the existing indexed navigation and freshness contract remains appropriate.
+
+## context
+
+- **Purpose:** Retrieve workspace state, activate installed skills, and recall persisted observations.
+- **Placement:** Direct OBSERVE, read class, parallel.
+- **Contract:** `scope=workspace|skills|recall`; skill name/tree and recall query/ref/limit/offset arguments. Workspace needs session wiring; skill activation obeys operator and recipe policy.
+- **Implementation:** `src/tools/context/surface.ts` and `index.ts` retain existing engines with the narrower permanent schema. Workspace/skills use the observation envelope; recall resolves persisted evidence.
+- **Scientific integrity:** Recall identifies historical observations without presenting them as current file reads. Skill availability is separate from permission to activate or install.
+- **Disposition:** Redesign the permanent schema; move secondary docs/library retrieval to named gateway capabilities.
+
+Status: landed in `021ec049`.
+
+## verify
+
+- **Purpose:** Execute declared checks and inspect explicit validation judgements.
+- **Placement:** Direct EXECUTE, execute class, sequential.
+- **Contract:** Package scripts, strict project catalog entries, or frontend verification. Numeric checks use explicit tolerance combination/non-finite policy; performance checks use budgets or baselines. Execution failure prevents judgement.
+- **Implementation:** `src/tools/verify/numeric.ts`, `perf.ts`, and `scripts.ts` cap judged capture and references at 32 MiB; ULP tolerance cannot exceed Number.MAX_SAFE_INTEGER. Version-2 baselines record environment; direct and host paths retain provenance and judgement axes.
+- **Scientific integrity:** Non-finite report values serialize by name. Hashes identify reference/actual bytes; environment mismatches are informational. `scientificValidity` stays `not established by this check` even on pass.
+- **Disposition:** Repair mathematical policy and evidence instead of equating execution with scientific validity.
+
+Status: landed in `2968271a`; host-verification parity and authoring/help closures in `bde78f76`.
+
+## evidence
+
+- **Purpose:** Inspect canonical bundles, per-run trust axes, gate decisions, and findings.
+- **Placement:** Gateway OBSERVE, read class, sequential.
+- **Contract:** `mode=list|inspect|run`, `id` or `runId`; bounded JSON. Run mode may build a missing bundle; absent ledger runs report artifact absence.
+- **Implementation:** `src/tools/evidence.ts` shares evidence-domain projections and caps the result at 16KB with valid JSON preview on truncation. Sequential execution protects materialization ordering; gateway evidence export resolves the underlying identity.
+- **Scientific integrity:** Integrity, validation grounding, provenance, and completion remain separate axes. A trusted bundle does not establish the truth of every worker claim.
+- **Disposition:** Retain the bounded evidence engine and repair routing/consumer identity for gateway invocation.
+
+Status: placement and evidence projection landed in `021ec049`.
+
+## credential_present
+
+- **Purpose:** Check credential availability without returning its value.
+- **Placement:** Gateway OBSERVE, read class, parallel.
+- **Contract:** Credential `name`, optional environment/file source and file path; booleans, checked sources, and missing-file state. Invalid names or unusable reads fail.
+- **Implementation:** `src/tools/credential-present.ts` returns a small presence projection rather than the observation envelope. File access remains subject to the capability's admitted read contract.
+- **Scientific integrity:** Presence does not validate a credential, establish external access, or expose secret contents. No numerical interpretation occurs.
+- **Disposition:** Retain the minimal result and move its schema off the permanent direct surface.
+
+Status: placement landed in `021ec049`.
+
+## git
+
+- **Purpose:** Inspect repository status, diffs, and history without a free-form shell.
+- **Placement:** Gateway EXECUTE plane, read class, parallel.
+- **Contract:** `op=status|diff|log`, optional path/cwd, diff flags, log limit, timeout, and output cap. Nonzero, capped, timed-out, or aborted execution returns failure facts.
+- **Implementation:** `src/tools/safe-exec.ts` builds fixed git argv vectors on safe-exec; default timeout 120000 ms and capture 600000 bytes, followed by bounded result shaping. Log count caps at 200.
+- **Scientific integrity:** Command/argv/cwd/exit/timing identify the observation; truncation is not a complete change inventory. Git inspection does not validate scientific output.
+- **Disposition:** Retain fixed-vector inspection and preserve recipe attestation through gateway placement.
+
+Status: placement/attestation landed in `021ec049`; shared safe-exec cleanup strengthened in `4ef9277e`.
+
+## web_fetch
+
+- **Purpose:** Make full HTTP requests and retrieve bounded textual content.
+- **Placement:** Gateway RETRIEVE, read base class, parallel; non-GET or body requests retain outward-action classification.
+- **Contract:** URL, method, headers, body, format, timeout, and byte limit. Unsupported/binary content and disallowed private-network targets are refused.
+- **Implementation:** `src/tools/web-fetch.ts` and its helpers share the existing fetcher, default 600KB read allowance, 5MB hard read cap, and 16KB shaped result. Abort/timeout and network policy remain in force.
+- **Scientific integrity:** HTML conversion and arXiv/repository summaries are derived views, not raw source identity or independent corroboration. Request success is not evidence that a remote claim is correct.
+- **Disposition:** Retain full requests behind the gateway and split GET-only reading into web_read.
+
+Status: landed in `021ec049`.
+
+## web_read
+
+- **Purpose:** Read public web content without full-request argument authority.
+- **Placement:** Gateway RETRIEVE, read class, parallel.
+- **Contract:** `url`, `timeout_ms`, `max_bytes`, `format`; GET only, without headers, method, or body arguments.
+- **Implementation:** `src/tools/web-fetch.ts` and `web-fetch-surface.ts` delegates to the existing web fetch implementation and inherits its byte caps, cancellation, conversion, and private-network policy.
+- **Scientific integrity:** Bounded/converted content must be distinguished from the complete original. A GET-only tool is not a guarantee that remote content is trustworthy.
+- **Disposition:** Split the read-only request surface from full web_fetch while sharing implementation.
+
+Status: landed in `021ec049`.
+
+## artifact
+
+- **Purpose:** Publish a requested terminal plan, review, or report.
+- **Placement:** Gateway ARTIFACT, write class, sequential.
+- **Contract:** `kind`, `content`, optional title/path; default `.clio-coder/artifacts/{PLAN,REVIEW,REPORT}.md`, workspace-contained overrides, and terminal turn completion.
+- **Implementation:** `src/tools/artifact.ts` uses the atomic publisher. Gateway preserves `terminate`, `details.kind`, and `details.paths`; ledger/artifact consumers unwrap capability identity. Post-publication durability warnings remain visible.
+- **Scientific integrity:** Successful publication establishes document delivery, not correctness of its claims. Pre-rename failure is not presented as an artifact; terminal content must contain the full answer.
+- **Disposition:** Retain the terminal document contract, repair publication, and move behind gateway.
+
+Status: landed in `021ec049` using publisher from `82ebee28`.
+
+## clio_docs
+
+- **Purpose:** Retrieve cited bundled documentation on demand.
+- **Placement:** Gateway OBSERVE, read class, parallel.
+- **Contract:** Optional query and section limit (default 5, max 12); omitted query lists corpus; searches return ranked cited sections and follow-up guidance.
+- **Implementation:** `src/tools/gateway/clio-context-tools.ts` reuses `src/tools/context/docs-engine.ts`, with a 16KB observation cap and valid JSON offload behavior. It reads the shipped corpus without network access.
+- **Scientific integrity:** Rankings are retrieval hints, not proofs. File/section/line citations let callers inspect the source; omitted sections remain explicitly omitted.
+- **Disposition:** Move the existing docs engine out of context's permanent schema.
+
+Status: landed in `021ec049`.
+
+## clio_library
+
+- **Purpose:** Inspect loaded recipes and installable package claims without activation or installation.
+- **Placement:** Gateway OBSERVE, read class, parallel; unavailable inside workers.
+- **Contract:** Query, kind, ref, limit (20 default, 50 max), offset; tagged resource/hint/package rows with continuation and lower-bound totals where needed.
+- **Implementation:** `src/tools/gateway/clio-context-tools.ts` and `src/tools/context/library.ts` reuse bounded inventory and fit pages to a 16KB observation allowance. No recipe body or installation side effect is returned.
+- **Scientific integrity:** Installed resources have real invocation information; catalog hints do not pretend to be loaded tools. Availability does not confer trust or validate a package's scientific claims.
+- **Disposition:** Move read-only catalog browsing out of the permanent context schema.
+
+Status: landed in `021ec049`.
+
+## data
+
+- **Purpose:** Inspect, select, or validate explicitly supported structured formats without rewriting them.
+- **Placement:** Gateway OBSERVE, read class, parallel.
+- **Contract:** CSV/TSV/JSON/JSONL op/path, format-specific selectors, sample/scan limits; view flags, schema/counts, precision issues, and actionable refusals.
+- **Implementation:** `src/tools/data/` streams with bounded CSV field/record, JSON depth/capture, and JSONL line budgets. `src/tools/gateway/data-tool.ts` normalizes the protected read path before admission and applies a 32 KiB observation cap.
+- **Scientific integrity:** Preserve numeric literals and sentinels; disclose sampling, approximate extrema, duplicate-tracking limits, and cut values. `exact=false, sampled=false` denotes a complete scan with a value cut to budget, not a complete selection. Validation is format validation only.
+- **Disposition:** Add bounded structured-data inspection; refuse unsupported binary formats and direct them to a supplied script/library.
+
+Status: readers landed in `7623ce27`; gateway/admission integration in `021ec049`.
+
+## dispatch
+
+- **Purpose:** Run explicitly bounded tasks on fleet workers and collect durable receipts.
+- **Placement:** Direct ORCHESTRATE, dispatch class, sequential; requires a dispatch contract.
+- **Contract:** Singular/batch tasks, recipe/route, typed intent, budgets, timeout, topology, and optional detach. Nonzero terminal attempts fail; detached ids require collection before final synthesis.
+- **Implementation:** `src/tools/dispatch.ts` delegates to the dispatch domain's admission and lifecycle. Summaries are bounded; cancellation and receipts are owned there. Gateway capabilities remain in the admitted worker list while schemas and attestation use the direct projection.
+- **Scientific integrity:** Receipt integrity, worker evidence, host verification, and project/briefing provenance remain distinct. Worker prose is advisory; successful execution alone is not a scientific result.
+- **Disposition:** Retain orchestration and direct placement; adapt worker capability projection and host evidence integration.
+
+Status: gateway worker integration landed in `021ec049`; host verification closures in `bde78f76`. Existing dispatch workflow is retained.
+
+## monitor
+
+- **Purpose:** Observe dispatched runs and collect detached results.
+- **Placement:** Direct ORCHESTRATE, read class, parallel; requires dispatch wiring.
+- **Contract:** List/status/peek/receipt/wait/collect/tools, run/batch identifiers and bounded waiting. Wait never cancels; collect resolves terminal attempts.
+- **Implementation:** `src/tools/monitor.ts` uses the dispatch ledger and live snapshot. Peek uses bounded in-process tails (100 events/run, 64 runs, 8KB output); receipts are bounded projections with retrieval paths.
+- **Scientific integrity:** Process-local event absence is disclosed, not treated as proof of no tool activity. Receipt integrity and validation evidence are separate, and an unfinished run is never a completed result.
+- **Disposition:** Retain observation and collection; it does not process scientific values.
+
+Status: unchanged in v0.4.9 because existing bounded run observation and collection remain the required contract.
+
+## steer
+
+- **Purpose:** Correct or cancel a worker with an already-known run id.
+- **Placement:** Direct ORCHESTRATE, dispatch class, sequential.
+- **Contract:** `run_id`, `action=guide|cancel`, message for guide. Unsupported live-input runtimes and terminal-run cancellation return structured failures.
+- **Implementation:** `src/tools/steer.ts` uses the dispatch contract's stdin steer/cancel path. Guidance acknowledgement follows runtime acceptance; parent-model mid-run control needs detached ids.
+- **Scientific integrity:** Guidance records ordered byte/hash/timestamp and acknowledgement provenance, not validation of the changed work. Cancellation yields a cancelled outcome instead of a successful deliverable.
+- **Disposition:** Retain the explicit control surface and supported-runtime boundary.
+
+Status: unchanged in v0.4.9 because existing steering/cancellation contracts suffice.
+
+## tasks
+
+- **Purpose:** Maintain a session work board and linked operator-task state.
+- **Placement:** Direct ORCHESTRATE, read class, sequential bookkeeping.
+- **Contract:** plan/add/pick/start/done/block/drop/list with title, tasks, id, and note. Done requires evidence text; block requires a reason. Invalid state transitions fail.
+- **Implementation:** `src/tools/tasks.ts` updates the board and durable full-snapshot task ledger; operator inbox reconciliation/pick/done can update Clio-owned state. Sequential execution prevents interleaved board changes.
+- **Scientific integrity:** A completion note is an attributable claim, not an executed check or operator authorization. Linked operator status must be inspected before claiming completion.
+- **Disposition:** Retain the explicit bookkeeping exception to read-class semantics; do not equate it with source mutation authority.
+
+Status: unchanged in v0.4.9 because the existing board and operator correlation contract is retained.
+
+## ledger
+
+- **Purpose:** Exchange typed claims, findings, and reviews among peer workers.
+- **Placement:** Direct ORCHESTRATE, read class, sequential; only workers with a bound agent-ledger port.
+- **Contract:** Read with filters/watermark or post required kind-specific fields. Each run is limited to 20 posts; duplicate posts are not retry-safe.
+- **Implementation:** `src/tools/ledger.ts` reads a local mirror and posts through the dispatch control lane, returning a bounded board and sequence watermark. It does not mutate the source workspace.
+- **Scientific integrity:** Peer state may be stale. Findings and reviews carry provenance but remain untrusted data, not instructions or independent empirical proof.
+- **Disposition:** Retain typed coordination and its explicit availability/post bounds.
+
+Status: unchanged in v0.4.9 because coordination does not require scientific-data processing changes.
+
+## panes
+
+- **Purpose:** Display Clio-owned runs and fixed utility panes.
+- **Placement:** Direct ORCHESTRATE, read class, sequential; requires detected host and live mux.
+- **Contract:** show/open/close/list, target, and fixed files/logs/shell presets. Arbitrary argv stays operator-only; close is limited to owned panes.
+- **Implementation:** `src/tools/panes.ts` and `panes-surface.ts` delegate to the mux. Sequential calls protect pane inventory; an unavailable host omits the tool rather than advertising a working pane layer.
+- **Scientific integrity:** Display visibility is not execution evidence or validation. Pane operations cannot justify claims about worker completion beyond the displayed run facts.
+- **Disposition:** Retain the bounded owned-pane interface and direct placement.
+
+Status: unchanged in v0.4.9 because no data or evidence interpretation change is required.
+
+## limitation
+
+- **Purpose:** Record a typed statement of what could not be verified.
+- **Placement:** Direct ORCHESTRATE, read class, parallel.
+- **Contract:** Scope, enumerated reason, optional paths; successful receipt is its effect. Empty/invalid calls do not count.
+- **Implementation:** `src/tools/limitation.ts` is pure and runs no process or file mutation. The finish contract recognizes its successful ledger receipt within the mutation window.
+- **Scientific integrity:** It explicitly marks absent validation; it never converts missing or failed checks into a pass. Free-form final prose is not an equivalent receipt.
+- **Disposition:** Retain the precise limitation-evidence boundary.
+
+Status: unchanged in v0.4.9 because the existing receipt already preserves uncertainty honestly.
+
+## decide
+
+- **Purpose:** Record an agent-authored design choice beside operator decisions.
+- **Placement:** Direct ORCHESTRATE, read class, sequential; needs a session decision board.
+- **Contract:** Key, value, alternatives, rationale, optional label with byte/count bounds. A repeat agent key supersedes; an operator-owned key cannot be overwritten; worker calls are refused.
+- **Implementation:** `src/tools/decide.ts` appends a decision-ledger entry. Sequential lookup/write prevents supersede races; dispatch and commit seams carry active decision references.
+- **Scientific integrity:** Provenance records who chose what and why. It does not grant authorization, independently review the choice, or establish scientific validity.
+- **Disposition:** Retain bounded decision provenance and direct placement.
+
+Status: unchanged in v0.4.9 because the existing decision-board contract remains suitable.
+
+## ask_user
+
+- **Purpose:** Resolve missing operator choices through host-owned interviews.
+- **Placement:** Direct INTERACT, read class, sequential; interactive handler required.
+- **Contract:** Ask/complete, round/single-question mode, questions/options, decisions, summary, round bound, and local/outward exposure. Cancellation is an explicit host outcome.
+- **Implementation:** `src/tools/ask-user.ts` bounds questions/rounds and records interview decisions. Exposure participates in autonomy admission; caller prose cannot choose authority or consequence tier.
+- **Scientific integrity:** An operator answer establishes an attributed decision, not validation of a scientific claim. Missing answers and cancelled interviews are not fabricated approval.
+- **Disposition:** Retain the direct host interaction surface and its admission boundary.
+
+Status: unchanged in v0.4.9 because the operator explicitly retained INTERACT placement and the existing interview contract.
+
+## gateway
+
+- **Purpose:** Discover secondary capabilities without attaching every schema to every turn.
+- **Placement:** Direct GATEWAY, read outer class, sequential.
+- **Contract:** Find/describe/call with query/capability/args. Bounded listings, full described schemas, and capability results; unavailable/disallowed/invalid calls fail explicitly.
+- **Implementation:** `src/tools/gateway/index.ts`, `registry.ts`, and `surface.ts` reuse inner admission, cancellation, authority decisions, result shaping, terminal propagation, and effective evidence identity. Nested accounting counts one model call; worker allowlists apply to discovery and invocation.
+- **Scientific integrity:** Gateway success retains the underlying operation's facts instead of hiding them. The 31,272-byte measurement covers 19 attached fixture tools excluding ask_user/panes; a derived full-surface total is not comparable measurement evidence for overall shrinkage.
+- **Disposition:** Add a stable router without introducing new authority or sandbox claims.
+
+Status: landed in `021ec049`.
+
+## run_script
+
+- **Purpose:** Execute an inspectable scientific script with large logs streamed to disk and bounded model progress.
+- **Placement:** Direct EXECUTE, execute class, sequential.
+- **Contract:** Allowlisted PATH interpreter, workspace script/cwd, explicit argv/env, positive-integer timeout capped at six hours, and provenance-only input/output declarations. Records logs, manifest, identities, output states, and honest unsuccessful outcomes.
+- **Implementation:** `src/tools/run-script.ts`, `src/core/safe-exec.ts`, and `run-records.ts` reuse the execution substrate with streaming sinks, 250 ms progress, bounded tails/hashes, and retention of 100 completed runs. Retention metadata reads cap at 64 KiB and skip nonregular entries explicitly.
+- **Scientific integrity:** `exitCode` is effective status while `leaderExit` is observed process status. Original-group cleanup and one-second pipe draining can fail independently; escaped processes remain outside containment. ESRCH permanently closes ownership, but the probe-to-signal race remains accepted. Logs/argv can carry literal secrets; env values are omitted from manifest. Execute success is not scientific validation.
+- **Disposition:** Add the streaming provenance contract; no installs, automatic retries, script-to-tool calling, or OS sandboxing.
+
+Status: execution landed in `4ef9277e`; direct registration/policy integration in `021ec049`.
+
+## extension_<id>__<name>
+
+- **Purpose:** Expose operator-installed command capabilities under declared schemas.
+- **Placement:** Gateway dynamic extension family; execute class and sequential command execution.
+- **Contract:** Each installed descriptor supplies its schema; JSON arguments go to the command and bounded JSON/text results return. Invalid trust/digest, arguments, execution, or output fail rather than fabricating capability availability.
+- **Implementation:** `src/tools/harness-extensions.ts` freezes schemas at registry construction, re-verifies the extension digest per call, projects safety through command argv, and uses safe-exec with timeout/output bounds and cancellation.
+- **Scientific integrity:** Installation/trust and provenance identify the extension but cannot certify its scientific implementation. Each capability's described contract must state its own precision and validation semantics.
+- **Disposition:** Retain existing command execution and move discovery/attestation to the gateway. This family record cannot pre-audit arbitrary future installed commands.
+
+Status: placement and worker integration landed in `021ec049`; existing command engine retained.
+
+## mcp_<id>__<tool>
+
+- **Purpose:** Call explicitly trusted local stdio MCP capabilities.
+- **Placement:** Gateway dynamic MCP family, session-owned; action class comes from trust, not server annotations.
+- **Contract:** Discover/describe server schemas and call with validated arguments; bounded normalized results, protocol errors, timeouts, and cancellation. Project declarations cannot spawn without digest-bound operator trust.
+- **Implementation:** `src/domains/gateway/mcp/` bounds framing, outbound queues, result text, stderr, pages/tools, and config/trust reads. `src/tools/gateway/mcp-capabilities.ts` bounds one call result to 16 KiB in model context (offloading larger results to external artifacts) and shares connection/close ownership. Discovery cancellation closes the shared connection without session restart; shutdown awaits teardown, and the client owns exit cleanup. ESRCH and bounded release permanently end signalling ownership.
+- **Scientific integrity:** Trust authorizes launching an unsandboxed local process, not trusting its results. Incomplete cleanup is reported; residual PGID reuse and escaped-process limitations remain. Unknown external numerical semantics must be checked in each discovered capability's contract.
+- **Disposition:** Add local stdio integration with explicit trust and bounded lifecycle; defer remote MCP/OAuth and OS isolation.
+
+Status: client/config/trust landed in `d7b0edee`, CLI/slash in `bde78f76`, gateway cancellation/shutdown/exit ownership in `021ec049`.

package/library/registry.yaml

@@ -185,9 +185,9 @@ entries:
       - run Clio contract tests
       - test ACP over stdio
       - Clio mock provider harness
-    version: 0.3.0
+    version: 0.3.1
     sourceUrl: skills/meta/clio-coder-test
-    sha256: 8832464dfd5e5d827c770f1dddc860a1cb397748435ae61e8e68a0032add249e
+    sha256: fc8b0f3f7748070456bcf5366a0cf0bb41bf1737549592d3064b7b81cc9b0512
     provides:
       - kind: skill
         name: clio-coder-test

package/library/skills/meta/clio-coder-test/SKILL.md

@@ -7,7 +7,7 @@ triggers:
   - run Clio contract tests
   - test ACP over stdio
   - Clio mock provider harness
-version: 0.3.0
+version: 0.3.1
 license: Apache-2.0
 clio-coder:
   registry-id: iowarp/clio-coder
@@ -20,10 +20,11 @@ clio-coder:
 
 # Clio Test
 
-The root Node suite has two test lanes. Contract tests import `src/` directly
-through tsx; smoke tests spawn the built `dist/cli/index.js`. The import-boundary
-checker runs under lint rather than `npm test`. The trace viewer and Workbench
-have separate application gates.
+The root Node suite has a small required contract/process lane, an installed-package
+qualification lane, and explicit extended development regressions. Contract tests
+import source through tsx; CLI tests use the current built binary. Lint owns static
+import boundaries and library pins. Publication performs only an exact-candidate
+preflight after successful qualification.
 
 For the question of whether a change may leave your machine (commit, push, or
 PR), use `clio-coder-dev`. **REQUIRED SUB-SKILL:** `clio-coder-dev` for the
@@ -38,15 +39,24 @@ npm run skills:check                      # catalog pins and marketplace index
 npm run test:file -- tests/contracts/<file>.test.ts
 npm run build                             # tsup plus the codewiki asset
 npm run test:file -- tests/smoke/<file>.test.ts  # requires a current build
-npm run test                              # every contract and smoke file
-npm run test:trace-viewer                 # apps/trace-viewer
+npm run test                              # required contracts and three process smoke files
+npm run test:full                         # explicit extended root investigation
+npm run test:web:full                     # explicit extended web investigation
+pnpm --filter @iowarp/clio-coder-web verify # app types, lint, tests, build, browser
 npm run ci                                # deterministic root gate
-npm run ci:release                        # root gate plus package/release audit
+npm run ci:release                        # qualify clean committed source and exact installed tarball
+npm run release:preflight                 # fast check of the unchanged qualified package
 ```
 
-The Workbench is not part of the root `npm run ci` command. From
-`apps/workbench`, run `deno task verify` for its format, lint, type check, test,
-and build gate.
+The required web tests cover authentication, permissions, cancellation, worker RPC,
+egress and process ownership. The installed-package lane includes one real browser
+boot/reconnect against the installed server. The full web `verify` command is an
+explicit development investigation, including its viewport/accessibility matrix.
+Do not run full development tests repeatedly during release or publication.
+
+The separate trace viewer is retired. `apps/workbench/` is retained reference
+source, excluded from builds, publication and product gates. Use `test:web` for
+the required app tests alone; app `verify` requires headless Chrome.
 
 No deterministic gate contacts a real model. When a task explicitly requires
 live validation, build first and run `node dist/cli/index.js run` against a
@@ -63,8 +73,7 @@ settings with the result.
 | Any import edit under `src/` | `npm run lint` | Hygiene invokes all six boundary rules. |
 | CLI, entry, process lifecycle, or ACP stdio flow | Build, then the closest file under `tests/smoke/` | Smoke executes the built binary. |
 | Published package contents | Build, then `tests/smoke/installed-package.test.ts` | The test packs and installs the actual artifact. |
-| Trace viewer | `npm run test:trace-viewer` | It has a separate Node package and test command. |
-| Workbench | `deno task verify` in `apps/workbench` | Its Deno/Vite gate is independent of the root npm gate. |
+| Unified web application | `npm run test:web` | Required authentication/runtime boundaries; full `verify` is optional development work. |
 
 Read `references/test-map.md` for the current file map and exact subset
 commands.
@@ -93,7 +102,7 @@ The authoritative definitions and exceptions are in
 ## Source and configuration reload
 
 Contract tests and hygiene read current source, so they need no build. Smoke
-tests run `dist/`, so rebuild first or keep `npm run dev` (`tsup --watch`)
+tests run `dist/`, so rebuild first or keep `npm run dev` (`scripts/build.ts --watch`)
 running. A running Clio process does not reload changed ESM modules; restart it
 after a fresh build.
 
@@ -115,7 +124,8 @@ three buckets:
 3. Run the narrowest related contract or application test.
 4. If the built boundary changed, build and run the closest smoke file.
 5. Run `npm run ci` before handing back a broad root change. Use
-   `npm run ci:release` when release packaging is in scope.
+   `npm run ci:release` on the clean committed candidate when packaging is in scope.
+   It records the exact source/artifact; use only `release:preflight` afterward.
 6. Report exactly what ran and what remains unverified.
 
 For one test file or an `it.only` while debugging:

package/library/skills/meta/clio-coder-test/evals.md

@@ -18,14 +18,14 @@ Expected:
 Prompt: "I edited `src/cli/run.ts`. How do I verify end-to-end?"
 Expected:
 - Builds (or relies on `npm run dev` watch), then starts with
-  `npm run test:file -- tests/smoke/cli-core.test.ts`.
+  `npm run test:file -- tests/extended-smoke/cli-core.test.ts`.
 - Explains smoke spawns `dist/cli/index.js`, so it only sees built code.
 
 ## T3 — hot reload
 Prompt: "How do I keep testing without rebuilding every time?"
 Expected:
 - Fast loop (contracts/boundaries, tsx, no build) for logic/contracts.
-- `npm run dev` (`tsup --watch`) keeps `dist/` fresh for smoke.
+- `npm run dev` (`scripts/build.ts --watch`) keeps `dist/` fresh for smoke.
 - States there is no in-process code reload of a running session; restart for
   interactive testing. Distinguishes this from config hot-reload (classify.ts).
 
@@ -46,3 +46,17 @@ Expected:
 
 One representative scenario via `clio-coder eval skill` against Nemo-3.5-Lightning
 (30B local, llamacpp on mini), full-auto sandbox. NOT CLEANLY RUN: scenario id is T1; driver's --scenario S1 exited 2; re-run did not land before the time-box.
+
+## T5 — current application gates
+Prompt: "The web API changed. Which checks belong to this release?"
+Expected:
+- Builds the root CLI for ACP fixtures, then runs
+  `pnpm --filter @iowarp/clio-coder-web verify` with temporary state outside the checkout.
+- Names app type, API/worker boundary, test, client build and headless-browser checks.
+- Explains root `ci:release` includes web tests and the installed package audit.
+- Does not run the retired trace viewer or reference-only Workbench gates.
+
+RED: the prior 0.3.0 instructions prescribe both obsolete application lanes.
+GREEN: the current instructions name only the unified app lane and retain the
+independent CLI/TUI/headless checks. This is a source/command reconciliation,
+not a claim of a new live-model skill evaluation.

package/library/skills/meta/clio-coder-test/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
 	"name": "clio-coder-test",
-	"version": "0.3.0",
+	"version": "0.3.1",
 	"description": "Verifies a Clio Coder source change against the current contract, smoke, boundary, and application test lanes, including temporary-state and local-provider harnesses. Not for deciding what may change; use clio-coder-dev.",
 	"license": "Apache-2.0",
 	"extensions": {

package/library/skills/meta/clio-coder-test/references/test-map.md

@@ -1,27 +1,28 @@
 # Where Clio's tests live
 
-The root repository has contract and smoke tests under `tests/`; import
-boundaries run through the lint hygiene checker. Add a test beside the closest
-current behavior, and create a new file only for a genuinely new cluster.
+Routine contracts and three process smoke files protect core product boundaries.
+The installed-package and real native timing checks belong to qualification.
+Extended regressions are explicit development investigations.
 
 ## Layout
 
-| Lane | Path | Runner | Build needed |
+| Lane | Path | Command | Build needed |
 |---|---|---|---|
-| Contracts | `tests/contracts/*.test.ts` | `npm run test:file -- <file-or-files>` through tsx and the temp-root preload | No; imports `src/` |
-| Smoke | `tests/smoke/*.test.ts` | `npm run test:file -- <file-or-files>` | Yes; spawns `dist/cli/index.js` |
-| Boundaries | `tests/boundaries/check-boundaries.ts` | `npm run lint` through `scripts/check-hygiene.ts` | No |
-| Root full suite | Contract and smoke files | `npm run test` | Yes for current smoke behavior |
-| Trace viewer | `apps/trace-viewer/tests/*.test.mjs` | `npm run test:trace-viewer` | No |
-| Workbench | `apps/workbench/tests/` | `deno task verify` from `apps/workbench` | The command builds the app |
-
-`npm run ci` orders typecheck, lint, skill-pin verification, build, the root
-suite, and trace-viewer tests. `npm run ci:release` adds the release audit. The
-Workbench gate is separate.
+| Required contracts | `tests/contracts/*.test.ts` | `npm run test:file -- <file>` | CLI tests require current dist |
+| Required process smoke | ACP, binary boot, process lifecycle under `tests/smoke/` | `npm run test` includes them | Yes |
+| Package qualification | Installed package and native call timing under `tests/smoke/` | `npm run ci:release` | Built once by qualification |
+| Extended regressions | `tests/extended/`, `tests/extended-smoke/` | `npm run test:full` or a focused `test:file` | Yes for CLI scenarios |
+| Static boundaries and pins | `scripts/check-hygiene.ts` | `npm run lint` | No |
+| Required web boundaries | Selected files in `apps/clio-coder-web/tests/` | `npm run test:web` | Root build |
+| Full web investigation | All web tests and browser matrix | `pnpm --filter @iowarp/clio-coder-web verify` | Yes |
+
+`npm run ci` runs the routine lane. `npm run ci:release` qualifies a clean,
+committed candidate and its exact tarball; `npm run release:preflight` checks
+that qualification without repeating development tests. See CONTRIBUTING.md.
 
 ## Contract files
 
-| Area | Current files under `tests/contracts/` |
+| Area | Required or extended focused files |
 |---|---|
 | Authentication | `auth-login-write-failure`, `auth-storage-durability` |
 | Context, session, and state | `context-lifecycle`, `memory-scope`, `project-bootstrap`, `session-durability`, `state-file-lock`, `task-board-done`, `working-set-core` |
@@ -32,7 +33,7 @@ Workbench gate is separate.
 | Safety and tools | `bash-exec-settlement`, `rejection-feedback`, `safe-resource-write`, `safety-gates`, `tool-boundaries` |
 | Evidence, eval, and release | `eval-boundary`, `evidence-integrity`, `metering-integrity`, `release-boundary` |
 | Extensions, interop, and skills | `extension-compatibility`, `extension-reload-coordinator`, `extension-reload-slash`, `extension-resources`, `extension-snapshot`, `interop-boundary`, `marketplace-offer`, `skill-install` |
-| Documentation server | `docs-server` |
+| Documentation navigation | `docs-server` |
 
 Append `.test.ts` to every stem in the table. Use `rg` over the files before
 choosing a lane; related behavior can span more than one focused contract.
@@ -70,12 +71,12 @@ Child fixtures in `tests/fixtures/` are
 
 ```bash
 # all contracts (the shell expands the file pattern)
-npm run test:file -- tests/contracts/*.test.ts
+npm run test:full
 
 # one contract or smoke file
 npm run test:file -- tests/contracts/skill-install.test.ts
 npm run build
-npm run test:file -- tests/smoke/cli-core.test.ts
+npm run test:file -- tests/extended-smoke/cli-core.test.ts
 
 # only it.only or describe.only within one file
 npm run test:file -- --test-only tests/contracts/skill-install.test.ts

package/library/skills/registry.yaml

@@ -65,8 +65,8 @@ skills:
     sha256: 8980f3bed0f06c24685bc0a02f3ffbbcdac9442616dc3ce54122265b666ae0d7
   - name: clio-coder-test
     path: meta/clio-coder-test
-    version: 0.3.0
-    sha256: 87f6689d083080e4b80294304f2b2fd36f70ce941ab7265cb573e84e4c5e6a12
+    version: 0.3.1
+    sha256: 1e8c839b3668e50cd8ed7c69e7ae3ccc5afa15a1db72eb2b8babb1672134fba1
   - name: credentials
     path: meta/credentials
     version: 0.2.0

package/library/skills/skill-marketplace.json

@@ -220,7 +220,7 @@
 				"Clio mock provider harness"
 			],
 			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/library/skills/meta/clio-coder-test",
-			"version": "0.3.0",
+			"version": "0.3.1",
 			"audit": "pass",
 			"category": "meta"
 		},