clinkx 1.1.1 → 1.2.0

package/docs/engineering-recipes.md

@@ -0,0 +1,415 @@
+# Engineering Recipes (ClinkX wiring)
+
+ClinkX ships explicitly invoked `architecture-comparison` and `verified-repair` workflows through MCP.
+Grounded investigation and the manual verified bug fix remain companion recipes;
+the manual architecture recipe remains available. This guide describes invocation, bounds,
+failure behavior and evidence. Comparison and inspected verification records are
+advisory; the owner and independent verifier retain acceptance authority.
+
+## Compatible skill revision
+
+The recipes are defined in `skills/chief-of-staff/references/engineering-recipes.md` in `jim380/agent-skills`.
+
+- Status: **merged.** [jim380/agent-skills#3](https://github.com/jim380/agent-skills/pull/3) merged as `c1dd3b4959c7cfa1156070ae5aa772eb5b855f67` on 2026-10-09. The compatible revision for all three recipes and the current packet-secret rule is [`097a2fa7a636aeecfb34a60617ec9bd9c5cd7369`](https://github.com/jim380/agent-skills/commit/097a2fa7a636aeecfb34a60617ec9bd9c5cd7369), verified through the owning GitHub API on 2026-10-10.
+- Use that revision of the companion checkout and its `scripts/sync-skills.sh`. Check the installed `chief-of-staff/references/engineering-recipes.md` against the pinned source before relying on it; a repository merge alone does not establish local installation. The reference includes grounded investigation, architecture comparison, and verified bug fix.
+
+## Installation and distribution
+
+This invocation guide, the [verification overview](verification/README.md), and the
+[project-check guide](verification/project-checks.md) ship in the npm package.
+Installed MCP clients can call `provider_doctor`, `verification_run`, and
+`verification_inspect` without cloning ClinkX or needing shell access.
+Install the companion `chief-of-staff` skill separately as described above; the
+npm package does not include or install its recipe instructions.
+
+The built-in `architecture-comparison` workflow includes its own templates,
+validators and deterministic handoffs. It needs no companion skill or ClinkX
+checkout. Provider CLIs and their configured authentication must be available on
+the MCP server's host, as for any `clink` call.
+
+## Built-in architecture comparison
+
+Call `list_workflows` for the installed input declarations, then explicitly select
+the workflow:
+
+```json
+{
+  "name": "run_workflow",
+  "arguments": {
+    "workflow": "architecture-comparison",
+    "run_id": "architecture-001",
+    "variables": {
+      "user_request": "Compare two designs for the requested change. State caller usage, signatures, ownership, failures and rejected alternatives.",
+      "source_identity": "my-project at reviewed revision; declared attached files only",
+      "context_files": ["/absolute/path/to/project/design-context.md"],
+      "candidate_a_cli": "codex",
+      "candidate_b_cli": "claude",
+      "judge_cli": "codex"
+    }
+  }
+}
+```
+
+Paths refer to the MCP host and must satisfy workflow source/path admission.
+Both authors receive the same requirements and frozen context bytes. Existing
+context preflight runs according to the server's configuration; its costs and
+coverage signals remain part of the run. Explicit context overrides do not
+change the installed defaults or establish secret protection.
+
+The workflow freezes a versioned shared-input artifact, runs two fresh authors,
+constructs a separate judge view, runs one fresh judge, and deterministically
+publishes an `architecture-comparison-record-v1` owner record. The judge receives
+only shared context and semantic candidate bodies under `candidate_A` and
+`candidate_B`; author routes remain in the owner record. Structured source
+references and aliases are checked against delivered artifacts. Identity metadata
+is excluded and explicit self-attribution is rejected, but arbitrary prose can
+still reveal authorship. This is structural blinding, not a guarantee of semantic
+anonymity.
+
+Both author and judge templates explicitly require read-only review of delivered
+inputs: no command, sketch or test execution, edits, networking tools or
+delegation. Only the CLI's designated response artifact may be written. These
+are provider instructions, not a tool sandbox guarantee. Independently verify
+the proposed design and inspect provider activity when execution scope matters.
+
+Candidate and judge routes accept optional declared `_model` and `_effort`
+variables only when the actual adapter supports them. The judge is an independent
+fresh invocation with no author continuation; it may use the same provider as an
+author. There is no route substitution or fallback. Missing or invalid candidates,
+an unavailable judge, mismatched digests or invalid references leave the
+comparison incomplete. A final record may be available while workflow health is
+degraded; inspect the record's own status rather than treating run success as
+comparison completeness.
+
+Requirements, shared context, candidate outputs and full judge fan-in have byte
+ceilings. Candidates are never silently dropped or truncated to fit. Byte
+admission does not establish a provider's token capacity; inspect the workflow's
+capacity declaration/limitations and use a smaller packet when capacity is
+unknown. Resume retains the original frozen input and validates its recorded
+artifact identities; changed or corrupt retained evidence cannot be reused as a
+fresh candidate.
+
+| Artifact or input | UTF-8 byte ceiling |
+| --- | --- |
+| Requirements | 16 KiB |
+| Frozen shared JSON, including at most 32 source files | 48 KiB |
+| Each candidate JSON | 16 KiB |
+| Complete judge view JSON | 96 KiB |
+| Judge JSON | 12 KiB |
+| Owner comparison record JSON | 128 KiB |
+
+Optional `judge_prompt_token_limit` declares an independently known input
+capacity. Admission uses a conservative byte-token upper bound for the full
+view, prompt and response reserve; an insufficient declaration fails before
+dispatch. When omitted, the owner record explicitly reports capacity as unknown.
+
+For async execution, set `async:true`, poll `workflow_run_status`, and fetch with
+`include_result:true`. The same existing `cancel_workflow` and `resume_workflow`
+controls apply. Complete comparison grants no acceptance: the owner records the
+selected/rejected ideas, synthesizes the design and runs any required prototype
+or implementation verification.
+
+Read the owner record's `judge.recommendation` as advice. Its `status:complete`
+establishes delivery and validated artifact identity/reference structure.
+It does not validate the semantics of the proposed design. Independent source
+review and executable prototype checks remain separate; attached inspected
+verification records cover only their pinned checks at inspection time.
+`owner_acceptance:not_recorded` stays unchanged until the owner records a decision
+outside this comparison contract. A model grade cannot substitute for any of
+these steps: the stricter targeted GLM evaluation found three material defects
+in five designs that its calibrated graders accepted.
+
+ClinkX's own dashboard and workflow-handoff regression procedures still require a
+source checkout. The dashboard procedure uses
+`clinkx-workflows/dashboard-ui/e2e/real-disk-doctor.mjs` with `preflight`, `classify`,
+and `identity` subcommands, documented in `docs/verification/dashboard-real-disk.md`.
+The workflow-handoff procedure uses `scripts/verify-workflow-handoff.mjs run` and
+`inspect`, documented in `docs/verification/workflow-handoff.md`. Those fixtures
+qualify ClinkX; use the installed project-check control for your own project's
+commands through the same MCP connection. `npx clinkx` starts the MCP server;
+readiness and verification are tools on that server.
+
+## Companion recipe invocation
+
+The [GLM-only efficacy pilot in PR68](https://github.com/jim380/clink-mcp/pull/68)
+does not establish a general productivity or quality gain. Across four new
+architecture tasks repeated twice, the frozen semantic gate accepted single-author
+practice 7/8, manual comparison 5/8 and native comparison 6/8; execution medians were
+211.533s/322.310s/308.147s. Native comparison reduced core caller requests from
+three to one versus manual, while using the same three provider invocations.
+One native malformed judge output remained incomplete with no retry. Monetary
+cost and human correction time are unknown. Keep comparison opt-in.
+
+The same pilot found no textual proof-interpretation advantage (plain 8/12 exact
+versus projection 6/12; absent-field canonicalization was underspecified), and no
+recipe investigation advantage (practice 3/4 versus recipe 2/4). All eight seeded
+fixes passed causal functional checks and fresh verifier reruns, but generic
+outside-workspace temporary writes and host temporary fixtures prevent full
+procedure/scope qualification. Reference guidance was tested; the full skill
+orchestration and human dashboard usability were not measured. Prior unfavorable
+studies below remain relevant. Read the report's limits before applying these
+counts as a recommendation.
+
+Recipes apply only when the caller asks. Example requests to chief-of-staff:
+
+- "Apply the grounded-investigation recipe to: <one answerable question>. Source: <repo@commit, dirty state>."
+- "Run the architecture-comparison recipe for <change>: two candidates, independent judge."
+
+ClinkX tools used:
+
+- `clink` runs each candidate author and the independent judge, one seat per call. Parallel calls are fine for independent candidates.
+- `context_builder` builds the shared source packet that is attached to those calls (`recommended_clink.absolute_file_paths` hands the bundle over).
+- `provider_doctor` checks seat readiness; request `probes` explicitly to establish authentication.
+- `verification_run` executes a reviewed project-check manifest; retain its `expectations_sha256` independently and pass it to `verification_inspect` when reassessing the evidence. Neither tool accepts a recipe, workflow, or change on behalf of its owner.
+
+Judge input is a separate alias-only view (e.g. `candidate_A`/`candidate_B`, no author, seat, model, or route names). The parent keeps the alias-to-identity map privately; it is not published or shown to the judge. See the skill reference for the full input and output contracts.
+
+## Unavailable-tool behavior
+
+- A missing or unusable ClinkX `clink` seat for a candidate, or for the independent judge, leaves the comparison **incomplete**. Name the missing part. Do not substitute the parent's own verdict as the judge, and never silently drop or truncate a candidate. Local investigation can still be useful.
+- Configuration is not authentication. An adapter that resolves has not proven its CLI is logged in; a seat is usable only after it actually runs.
+- Workflow context preflight (default on) needs a curator (`CLINKX_WORKFLOWS_CONTEXT_DEFAULT_CURATOR`, default `codex`) and a Codex `json` finalizer configured, or startup fails with `ConfigError`. See [configuration](configuration.md). `CLINKX_WORKFLOWS_CONTEXT_PREFLIGHT_ENABLED=false` bypasses preflight but gives no secret protection.
+- Secrets: sanitize what you author. The user settled report §8.1 on 2026-10-09: keep the engine default `allow_secrets:true` and the chief-of-staff rule to omit rather than pin `allow_secrets` / `cb_allow_secrets` to `false`. The companion `runtime-routing.md` rule at the compatible revision is grounded in the recorded measurement: on that build, `false` shifted selection but performed no redactions, and a planted in-file key reached delivered context in both modes. Neither mode establishes secret protection. Keep secrets out of packets and prompts; secret scrubbing is a separate work item. This integration adds no secret-policy defaults.
+- Judge-input bounds: see the skill reference ("Architecture comparison", "Bounds before dispatch").
+
+## Worked example: output ownership (task 1-4)
+
+A real run of both recipes on this repo (source `d0a55b1`, Playwright 1.61.1).
+
+- **Question:** how should each real-disk dashboard Playwright invocation own its output (artifacts dir, JSON report, bootstrap file) so two concurrent invocations keep separate results?
+- **Grounded brief:** question, exact source identity, code anchors, constraints, and the decision (native CLI/env options vs. a small `playwright.real-disk.config.ts` change), with cited observations, hypotheses, unknowns, and one discriminating experiment.
+- **Candidates:** aliases `X` (native flags and env only; `judge-view/candidate-X.md`) and `Y` (small config change; `judge-view/candidate-Y.md`), authored from identical requirements and packet.
+- **Independent judge:** a separate seat given only the alias view. It cited only delivered aliases, so alias resolution passed. It selected Y conditionally and noted X suffices if the documented procedure is the supported caller.
+- **Owner synthesis:** selected X, diverging from the judge for a stated scope reason. The plan's contract is that a fresh caller can repeat the *documented* procedure, and the rule is to change config only when native options cannot meet it. Y stays as the ready fallback if overlap evidence (task 2-5) shows native options fail. The comparison was recorded as complete.
+
+Local-only evidence (this machine; not remote downloads, not in the repo): `${XDG_STATE_HOME:-~/.local/state}/clinkx-pstack-evidence/1-4/` with `brief.md`, `judge-view/candidate-X.md`, `judge-view/candidate-Y.md`, and `comparison-record.md`. A parent-only alias map exists beside them and is intentionally not described here.
+
+## Built-in native verified repair
+
+Choose `verified-repair` explicitly when the host has the project, reviewed
+commands and a separate authorized verification-copy parent. It edits existing
+UTF-8 files in the selected working tree through host-applied full replacements.
+Providers return proposals; they do not receive workflow authority to edit.
+See [project setup and contract](verification/project-checks.md#native-verified-repair).
+The workflow ships with the installed package and reuses `run_workflow`; no
+ClinkX checkout or additional binary is required. The caller needs access to
+the selected project to prepare the contract and manifests. Confirm the
+connected server lists `verified-repair` through `list_workflows` and that the
+selected provider CLIs are configured and authenticated on the MCP host.
+
+```json
+{
+  "name": "run_workflow",
+  "arguments": {
+    "workflow": "verified-repair",
+    "run_id": "repair-001",
+    "async": true,
+    "variables": {
+      "repair_contract_path": "/absolute/private-evidence/repair-contract.json",
+      "investigator_cli": "codex",
+      "repair_author_cli": "claude",
+      "verifier_cli": "codex"
+    }
+  }
+}
+```
+
+All three routes are explicit. Optional `investigator_model` /
+`investigator_effort`, `repair_author_model` / `repair_author_effort`, and
+`verifier_model` / `verifier_effort` use each configured adapter's supported
+invocation overrides. Unsupported routes or overrides fail admission; no
+provider fallback is selected. The independent verifier receives fresh context.
+
+Use `workflow_run_status` with the run ID and `include_result:true` to read the
+terminal `clinkx-verified-repair-record-v1`. The record preserves applied paths,
+original pins, reproduction, fixed-tree checks, independent findings and the
+copy's pass → fail without fix → pass after restoration experiment. `verified`
+requires every gate; a provider's approval alone cannot qualify it.
+
+```json
+{
+  "name": "workflow_run_status",
+  "arguments": {"run_id": "repair-001", "include_result": true}
+}
+```
+
+These examples are MCP `tools/call` payloads. A client may expose the same tool
+as `mcp__clinkx__run_workflow`; pass the shown `arguments` to that tool. Use a
+fresh run ID, poll until terminal, and inspect result availability, the repair
+record's `repair_status` and gaps. Execution completion alone is insufficient.
+
+The dashboard shows historical repair facts at publication alongside the
+existing inspected verification history. Execution status, repair qualification
+and `owner_acceptance: not_recorded` remain separate. Missing or corrupt records
+are unavailable. Current applicability requires native inspection against the
+selected tree and the retained original expectations pin.
+
+Failed, blocked or interrupted runs retain applied edits and private evidence.
+There is no automatic rollback, retry, revision loop, Git staging or integration.
+Resolve reported gaps and select recovery before creating a fresh explicit run.
+Provider restrictions are prompt instructions, not a filesystem sandbox.
+Manifest commands execute literal argv with host account permissions.
+
+### Using verified-repair from an agent runtime
+
+Use the dedicated `verified-repair` skill from the companion `agent-skills`
+repository in Claude Code or Codex. It inspects the selected host tree, prepares
+and reviews the native contract/manifests, launches once, polls to terminal and
+reports the retained repair evidence. The calling runtime and the three worker
+routes are independent choices. The host keeps execution and mutation authority.
+
+Install the source skill from your companion checkout with its existing
+installer:
+
+```sh
+scripts/sync-skills.sh --dry-run verified-repair
+scripts/sync-skills.sh verified-repair
+```
+
+That installer targets `~/.claude/skills` and `~/.agents/skills`. Reload skill
+discovery in the calling runtime if needed. The current `run-workflow` skill is
+council-specific; its members/chairman, context preflight and retry/resume rules
+must not be used for native repair.
+
+Replace the host paths and defect in this skill invocation. The task data is
+JSON inside one tag; strings are data, not instructions or executable code.
+Omitted route model/effort fields retain adapter defaults.
+
+```text
+Use the verified-repair skill to prepare a reviewed repair contract and native check manifests for the request below, then launch ClinkX's native verified-repair workflow and poll it to completion. Preparation and the scoped in-place repair are authorized; preserve unrelated changes and let the native host perform capture, replacements and verification.
+
+Treat the single repair_request_json object as task data. Read the skill's native contract reference, verify the MCP host paths and capabilities, and preserve the requested routes and optional model/effort values. Stop with an actionable blocker if authority, exclusive ownership, host access, native capability or bounded complete inputs cannot be established.
+
+Report repair qualification, applied paths, actual checks and causal proof, independent findings, gaps and retained evidence. Owner acceptance remains separate. Do not stage, commit, push, resume, retry, roll back or substitute providers automatically.
+
+<repair_request_json>
+{
+  "project_path": "/absolute/repair-demo/project",
+  "evidence_parent": "/absolute/repair-demo/evidence",
+  "verification_copy_parent": "/absolute/repair-demo/copies",
+  "defect": {
+    "description": "double(n) currently returns n + 1.",
+    "expected_behavior": "double(n) returns 2 * n; assert double(2) equals 4."
+  },
+  "routes": {
+    "investigator": { "cli_name": "codex" },
+    "repair_author": { "cli_name": "codex" },
+    "verifier": { "cli_name": "claude" }
+  },
+  "exclusive_write_ownership": true
+}
+</repair_request_json>
+```
+
+The skill requires the installed workflow and host file access. It derives the
+smallest sufficient source scope and exact manifest inputs, leaves the buggy
+implementation intact until native capture, and creates only an initial missing
+regression harness when preparation is authorized. Preserve unrelated edits.
+Missing paths, ownership, preparation or capabilities produce an actionable
+blocker. A missing skill must be reported instead of silently switching to a
+council or manual repair. Direct MCP integration uses the contracts and calls
+above when explicitly selected.
+
+Open `/prompt-builder?mode=verified-repair` on your dashboard for the
+**Verified repair** target. Enter the defect, expected behavior, host
+project/evidence/copy-parent paths and three provider routes, then acknowledge
+scoped preparation/repair and exclusive write ownership. The builder emits
+this skill invocation with `repair_request_json`, just as the other targets
+invoke their respective skills. Its vendored template is pinned in tests;
+the source lives in `agent-skills/skills/verified-repair/VERIFIED-REPAIR-PROMPT.md`.
+
+Copy is the builder's only action: the browser does not execute workflows,
+prepare contracts, grant host access or establish actual ownership. It blocks
+copy for absent/stale workflow or adapter catalogs, providers without a JSON
+role, missing/overlapping paths, or an unchecked ownership acknowledgment. The
+skill and native admission validate the actual host prerequisites. Drafts remain
+isolated from the council and chief-of-staff targets. Council/context-builder
+variables are omitted; model/effort use adapter defaults.
+
+## Verified bug fix
+
+The recipe is the "Verified bug fix" section of the same skill reference, present in the compatible merged revision above. The three-arm evaluation completed on 2026-10-09 (36/36 governing runs); its installation freeze is historical. The recipe remains explicitly invoked, and its independent-verifier contract still applies.
+
+Example request: "Apply the verified-bug-fix recipe to: <defect>. Source: <repo@commit, diff or file-hash identity>. Checks: <commands>. Procedure: <doc path or none>."
+
+ClinkX tools used:
+
+- `clink` runs the implementation worker under the `runtime-routing.md` direct-write conditions (confirmed workspace, exclusive and disjoint paths), otherwise as a patch the parent applies; `clink` has no `cwd`, so the child runs in the server's cwd. A separate `clink` seat with fresh context is the verifier, run against the absolute path of the exact fixed state. It gets that state, the commands, and the recorded outputs, never the implementer's status or verdict. It reruns the regression test read-only and repeats the undo-the-fix check in a disposable copy (`git worktree add --detach` at the same commit plus the same diff and untracked files, or a clone), never in the implementer's tree, after confirming the copy's commit, diff digest, and untracked file hashes equal the fixed state. The copy and any attempt directories are its only writes; it removes the copy afterwards and keeps its attempt directories as evidence.
+- `context_builder` optionally builds the shared source packet, as above.
+- For a dashboard defect the procedure is [verification/dashboard-real-disk.md](verification/dashboard-real-disk.md). On the attempt counted as evidence: `real-disk-doctor.mjs preflight` prints `{"verdict":"ready"}`; `identity.json` `head`, `dirty`, `diff_sha256`, and untracked hashes match the fixed state; the [Checking The Result](verification/dashboard-real-disk.md#checking-the-result) command block exits 0 for that attempt directory (its exit status is `result_check`); and `classify` prints `passed`. A zero `exit.txt` or a `passed` classification alone is not a pass, because Playwright ignores the web server's exit status, a stop failure shows only as a missing `fixture stopped (ok)` line, and `classify` only triages: it does not check the observation, identity, report shape, or cleanup. The procedure does not accept a dirty attempt as acceptance evidence, so for an uncommitted fix run it from [Clean Checkout](verification/dashboard-real-disk.md#clean-checkout) at the fixed commit (`dirty=false`); until then `procedure_evidence` is incomplete. The verifier reruns the result check over the retained attempt directory from the same checkout path (recreate the clean checkout at that path and commit if it was removed), or reruns the procedure. On any other outcome `classify` names the failure.
+
+Unavailable-tool behavior:
+
+- No usable verifier seat: the fix stays `implemented-unverified` and the recipe status is `incomplete`. The parent and the implementer do not stand in.
+- Preflight `blocked`, no `identity.json`, an identity that does not match the fixed state, or a result check that does not exit 0: the procedure evidence is missing and the status is `incomplete`. Repair the prerequisite as the procedure says; do not substitute another run.
+- Report `verified` only after the verifier's ACCEPT is recorded. Report `incomplete` as a `log_append` entry with `kind: "warn"` naming the missing item.
+
+### Worked example: double-SIGTERM false pass (`a01c4c4`, `463e30e`)
+
+- **False pass:** Playwright's `webServer` `gracefulShutdown` signals the whole process group, and the fixture sent the dashboard CLI a second `SIGTERM` about 0.26 ms later. The CLI registered `SIGTERM` with `process.once`, so the second signal killed it mid-close, and the fixture's classifier logged `fixture stopped (ok)` for any death by a signal it had sent. A council review (`code-review-20261005-134849`) found it; every earlier ACCEPT was invalidated.
+- **Regression tests:** repeated-`SIGTERM` tests for each entry point (`tests/shutdown.test.ts`, `tests/dashboard-cli.test.ts`, `tests/dashboard-gateway/gateway.test.ts`, `clinkx-workflows/tests/shutdown.test.ts`), plus a real-CLI fixture test that reproduces the process-group signal and fails against a `once` handler (`tests/dashboard-real-disk-fixture.test.ts`).
+- **Fix:** `a01c4c4` moves `SIGTERM` to `process.on` behind the existing re-entry guards and makes the dashboard CLI exit explicitly once close settles; `463e30e` makes `stopped (ok)` require exit code 0 after a requested stop.
+- **Independent verification:** review-loop round 4 on state `542c59b9c07f6b72` (the committed code) signed off with two native reviewer seats at 9/10 and no blockers; the full gate exited 0 and the concurrent procedure passed on macOS and Linux Docker arm64. Recorded in `.ai/plans/2026-10-04-clinkx-pstack-integration-implementation-plan.md`.
+- **Gap against this recipe:** that run predates it. Whether fail-before output (commit, command, output) and an undo-the-fix check were recorded on the exact states is not established in these records; the evaluation protocol's P2 later saw the five repeated-`SIGTERM` tests from `a01c4c4` (dashboard CLI ×2, gateway, root, workflows) fail on the unfixed `d0a55b1`; the fixture test was not in that gate. Under this recipe the record stays `incomplete` until fail-before on `d0a55b1` and an undo check on the fixed state are attached.
+
+## Reporting outcomes through existing progress-report tools
+
+Use the existing `progress_report_update` append fields for owner decisions and
+caller-reported counts. Inspected project proof has a separate versioned workflow
+attachment described in [the project-check guide](verification/project-checks.md).
+Neither surface grants acceptance; report counts are not inspected proof.
+
+Procedure for dashboard checks: [verification/dashboard-real-disk.md](verification/dashboard-real-disk.md) (follow it there, not here).
+
+Rules:
+
+- Record the authoritative disposition (the verifier's accept/reject) **before** reporting. The report mirrors the decision; it never makes it.
+- A reporting failure or `revision_conflict` never changes acceptance and never releases dependencies. Re-read with `progress_report_get`, then retry with the new `expected_revision`. Blindly re-sending the same `log_append` after a `revision_conflict` can append twice, so re-read first.
+- `tests_set` counts are caller-supplied. They are not collector-verified.
+- Evidence paths in messages are local to the machine that produced them, not remote downloads.
+- `log_append` entries are `{agent, kind, msg}` with `kind` one of `info|success|warn|error`; `decisions_append` entries are `{by, msg}`. Each `msg` is at most 300 code points, so name source, attempt, evidence type, result, and what is unavailable tersely. Use a fresh `request_id` per intended write; replaying it with identical content writes nothing.
+
+Example, direct dashboard-procedure evidence (placeholders in angle brackets; `expected_revision` is an integer, at least 1, taken from the last receipt or `progress_report_get`, so `3` here is illustrative):
+
+```json
+{
+  "report_id": "<SESSION-id from progress_report_start>",
+  "request_id": "<fresh uuid>",
+  "expected_revision": 3,
+  "changes": {
+    "log_append": [
+      {
+        "agent": "verifier",
+        "kind": "success",
+        "msg": "real-disk dashboard check, src <commit>, attempt <n>: exit 0, JSON report present, assertions passed, fixture stopped (ok). Evidence local: <attempt dir>"
+      }
+    ]
+  }
+}
+```
+
+Example, recipe outcome (comparison, owner decision):
+
+```json
+{
+  "report_id": "<SESSION-id>",
+  "request_id": "<fresh uuid>",
+  "expected_revision": 4,
+  "changes": {
+    "decisions_append": [
+      {
+        "by": "chief-of-staff",
+        "msg": "Comparison complete (2 candidates + independent judge). Judge chose Y; owner chose X (documented procedure is the supported caller). Local evidence: <evidence dir>"
+      }
+    ]
+  }
+}
+```
+
+Report an incomplete comparison as a `log_append` entry with `kind: "warn"` naming the missing candidate or judge (optionally also a `decisions_append` entry, which has no `kind`).
+
+If recording verification counts, `tests_set` takes `{passed, failed, skipped, failing: []}`; label them in the accompanying `log_append` as caller-supplied.
+
+### Optional helper proof (B1)
+
+Dashboard helper-produced proof through these append fields remains **conditional and not implemented**. The 2026-10-10 follow-up selects a separate core workflow-handoff procedure with an internal coverage evaluator and retained run/inspect evidence; it does not implement the broader dashboard B1 helper or add a reporting schema. See the [follow-up scope](../.ai/reports/2026-10-10-pr68-implementation-follow-up.md). Direct procedure reporting needs no helper or typed manifest.

package/docs/security.md

@@ -12,6 +12,9 @@ ClinkX validates and constrains the *inputs* it accepts — file paths, argument
 
 - `CLINKX_ALLOWED_ROOTS` (comma-separated, default: `process.cwd()`) defines which filesystem paths the tool will accept as `absolute_file_paths` or `images` inputs.
 - All paths are resolved via `realpath` — symlink escapes are blocked.
+- A directory entry admits that directory and its descendants. An existing regular-file entry is an exact-file grant: it resolves to the canonical file and admits only that path, never siblings, name prefixes such as `file.bak`, or child paths.
+- An entry that is a dangling symlink, inaccessible (`EACCES`, `EPERM`, `ENOTDIR`, `ELOOP`), or neither a directory nor a regular file fails startup (`-32602` on tool paths) with `CLINKX_ALLOWED_ROOTS entry "<entry>" is unusable: <reason>. Fix or remove this entry from CLINKX_ALLOWED_ROOTS.` A nonexistent entry is still accepted.
+- The server also admits its workflow state and artifact roots as artifact-only, directory-only entries. A state or artifacts override equal to the home directory or one of its ancestors is accepted with a startup warning, because any file in that tree can then be passed as a direct file reference that subprocess CLIs read, and ClinkX child processes may write anywhere in it; a filesystem root is rejected, including a TMPDIR-derived artifacts default that resolves to one. See [Durable storage roots](configuration.md#durable-storage-roots).
 - Startup refuses to run from filesystem root (`/` or drive root) unless `CLINKX_ALLOWED_ROOTS` is explicitly set.
 
 ### Context builder validation

package/docs/verification/README.md

@@ -0,0 +1,59 @@
+# Verification Procedures
+
+The npm-installed ClinkX MCP server exposes provider readiness and project
+verification tools. An MCP client can use them without shell access, a ClinkX
+checkout, Git, a browser, or ClinkX development dependencies. Node 24 or newer
+and the tools required by your own project checks must be installed on the MCP
+server's host.
+
+| MCP tool | Purpose | Guide |
+| --- | --- | --- |
+| `provider_doctor` | Separate provider configuration, executable, authentication, and startup readiness; authentication probes are explicit | [Provider readiness](../configuration.md#provider-readiness-doctor) |
+| `verification_run` | Execute a reviewed project manifest and retain private evidence for the identified state | [Project checks](project-checks.md), [example manifest](project-checks.example.json) |
+| `run_workflow` with `verified-repair` | Explicit scoped in-place repair with native and independent causal checks; owner acceptance stays separate | [Native repair setup](project-checks.md#native-verified-repair), [invocation](../engineering-recipes.md#built-in-native-verified-repair) |
+| `verification_inspect` | Inspect retained evidence with the owner's original expectations digest; execute no project commands | [Project checks](project-checks.md) |
+
+These guides and the example manifest ship in the npm package. The engineering
+recipe invocation guide also ships; the built-in native workflows require no companion checkout. Manual recipe instructions use
+the separately installed companion skill described in
+[engineering recipes](../engineering-recipes.md).
+
+## ClinkX source-checkout procedures
+
+The following regression procedures exercise ClinkX's own runtime with controlled
+fixtures. Their scripts and fixtures require a source checkout; their guides are
+also included in the package. They do not replace the canonical check
+(`npm run build:all && npm test`).
+
+Each source procedure names one feature and states its prerequisites, exact commands,
+the assertions it proves, the evidence to keep, cleanup, and known limits.
+
+| Procedure | Feature | Surface exercised |
+| --- | --- | --- |
+| [dashboard-real-disk.md](dashboard-real-disk.md) | Dashboard serves persisted run history and refreshes a same-generation state replacement | Real dashboard CLI, HTTP API, Chromium, files on disk |
+| [workflow-handoff.md](workflow-handoff.md) | Workflow producers deliver the correct persisted bytes to a final consumer; absent producer evidence remains missing | Real YAML loader, MCP STDIO child, workflow engine, validators, artifact store, host coverage evaluator |
+
+General rules:
+
+- Build once, then run invocations that do not build.
+- Give every invocation its own attempt directory under a private evidence
+  root outside the checkout (`chmod 700`).
+- A zero exit status is not proof. Check the retained report for the exact
+  required test and its status.
+- Raw reports, traces, and logs can contain credentials. Keep them private;
+  share only checked, token-free summaries.
+
+## Maintaining the feature map
+
+Each row above maps one feature to one procedure. When a procedure stops
+passing, classify the cause before repairing it:
+
+| Class | Meaning | Example | Repair in |
+| --- | --- | --- | --- |
+| Documentation drift | The product changed on purpose; the procedure or its selectors did not follow. | A UI redesign moved labels the spec asserted. | The procedure and spec. Keep the assertion's intent; record any check that can no longer be observed. |
+| Harness defect | The fixture, config, or runner misreports the result. | A fixture that treats an unsolicited exit as a clean shutdown; a runner that kills the fixture before its cleanup. | The fixture or config, with a subprocess test or a repeated procedure run that fails without the repair. |
+| Product regression | The feature itself no longer behaves as intended. | The inspector stops refreshing after a state replacement. | The product code, not the procedure. |
+
+After any repair, repeat the affected procedure and keep the new attempt's
+evidence. Do not weaken an assertion to make drift pass. Add a row here when a
+new procedure is added, and remove a row only when its feature is removed.