clinkx 1.1.1 → 1.1.2

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 1.1.2 — 2026-10-09
+
+### Added
+
+- Built-in `architecture-comparison` through `run_workflow`: two parallel authors receive the same bounded frozen packet, a fresh judge receives a separate semantic view with candidate aliases, and a deterministic reducer writes a strict owner-facing comparison record. References, output bounds, retained artifact digests, route bindings, and resume inputs are checked; incomplete evidence stays incomplete. The record preserves independent owner acceptance and states the limits of caller-declared source identity and free-text anonymity.
+- Native `workflow_verification_attach` re-inspects project proof with the owner's original expectations digest and retains a bounded, separately versioned inspection history on a workflow run. MCP status and dashboard detail expose inspected-at applicability, required coverage, check failures and safe digest references, with retention and owner acceptance kept separate. Progress-report test counts remain caller-reported.
+- Native MCP tools `provider_doctor`, `verification_run`, and `verification_inspect` work from an npm installation without a ClinkX clone or client shell access. Readiness is structured and authentication probes are explicit. Project verification runs reviewed argv commands within allowed roots, binds required checks to declared input and verifier identities, and retains private evidence for inspection with the owner's original expectations digest. The proposed standalone doctor/verifier npm CLI entry points were withdrawn before release. No Git or browser is required for project checks.
+- Packaged engineering-recipe wiring, verification overview, project-check guide, and example manifest. Recipe instructions remain in the separately installed companion `chief-of-staff` skill; ClinkX's dashboard and workflow-handoff regression fixtures remain source-only.
+- A source-checkout workflow-handoff verification procedure using the real YAML loader, MCP child session, workflow engine, validators, and artifact store. A host coverage evaluator checks frozen requirements and retained evidence; offline inspection requires the owner's original expectations digest and ignores cached success claims.
+- `scripts/provider-doctor.mjs` remains a source-checkout JSONL wrapper over the shared provider-doctor core. The MCP tool returns structured adapter readiness and a final verdict; all diagnostics are credential-redacted. Documented in `docs/configuration.md`.
+- A real-disk doctor (`clinkx-workflows/dashboard-ui/e2e/real-disk-doctor.mjs`) gates the dashboard real-disk e2e procedure: `preflight` checks node, dist freshness, chromium, the test-child seam, and an isolated `EVIDENCE_ROOT` before exercising the real fixture, `classify` maps a finished run to passed / blocked / not_run / harness_drift / failed_assertion / failed_fixture, and `identity` binds a run to its checkout and built artifacts. `docs/verification/dashboard-real-disk.md` documents the repeatable procedure.
+- A "Verified bug fix" recipe in `docs/engineering-recipes.md`.
+
+### Fixed
+
+- Dashboard-doctor Chromium preflight now removes only its owned profile and artifact directory, preserving other concurrent Playwright runs.
+- Provider-doctor interruption stops all concurrent version checks and cancels active authentication probes with their owned descendants before exiting.
+- Provider-doctor probes enforce their own 120-second cancellation deadline regardless of an adapter's timeout floor and require an exit-zero stdout or validated result-contract-file result with the exact trimmed `OK` answer before reporting authentication success.
+- Workflow-handoff inspection preserves independently observed execution, consumer, and cleanup failures when source/build identity has drifted.
+- Secret-redaction warnings deduplicate line numbers with a `Set`, preserving their ordering and bounded output without quadratic array scans.
+- `context_builder` opt-out secret redaction (`allow_secrets:false`) can no longer gut ordinary code: a quote inside a regex literal or a mid-value `key: quote` no longer opens a redaction span that runs to the end of the file, an in-place redaction that would move line breaks or span more than three lines omits the body fail-closed instead of shipping it redacted, and remaining redactions surface as one aggregate `content_secret_redacted` warning. `CONTEXT_DISCOVERY_ALGORITHM_VERSION` advances to 6.
+- A repeated SIGTERM no longer kills the dashboard, dashboard gateway, and server mid-shutdown: SIGTERM/SIGHUP handlers stay installed for repeats, teardown exits explicitly, and the dashboard and gateway close under an 8-second deadline that forces exit if closing stalls.
+- Codex app-server diagnostics now redact hyphenated vendor tokens (`sk-ant-`, `sk-proj-`, `sk-or-`) in stderr and recent-failure text.
+
+### Docs
+
+- Recipe wiring pins the merged three-recipe companion revision and records the completed evaluation and settled secret-policy decision.
+- The pstack integration evaluation for ClinkX (reports, three-arm evaluation protocol, and implementation plan under `.ai/plans/`), the dashboard verification runbook (`docs/verification/`), and the opt-out redaction bound in the context-builder notes.
+
 ## 1.1.1 — 2026-10-05
 
 ### Changed

package/README.md

@@ -60,6 +60,10 @@ ClinkX starts the Codex CLI, sends the prompt and the file references, and retur
 | `clink` | Runs one task on one configured CLI and returns the result. |
 | `context_builder` | Selects a bounded set of files from permitted roots and writes a reusable context bundle to disk. |
 | `refine_context_run` | Makes a new bundle from an earlier one. You can add, remove, promote, or demote files, or set their slices. |
+| `provider_doctor` | Checks provider configuration, executables, and startup readiness. Optional explicit probes make real authentication calls. |
+| `verification_run` | Runs a reviewed project-check manifest and retains private evidence with a digest for later inspection. |
+| `verification_inspect` | Reassesses retained evidence using the original owner-held digest, without running project commands. |
+| `workflow_verification_attach` | Re-inspects proof with the original owner-held digest and records its historical coverage on a workflow run. |
 | `list_workflows` | Lists the available workflows, CLIs, and roster presets. |
 | `run_workflow` | Starts a multi-stage workflow. Runs in blocking mode by default, or in the background with `async: true`. |
 | `workflow_run_status` | Reports the progress and result of a workflow run. |
@@ -74,6 +78,13 @@ Two more tool groups are off by default:
 
 Each tool publishes its full input schema through MCP. MCP clients can show the schema with the tool description.
 
+Readiness and project verification are available through the same npm-installed
+MCP connection; no ClinkX checkout or client shell access is needed. See
+[provider readiness](docs/configuration.md#provider-readiness-doctor) and
+[project checks](docs/verification/project-checks.md) for tool calls, authorized
+project/evidence roots, and evidence limits. Project execution v1 supports
+macOS/Linux and runs trusted manifest commands with the server account's permissions.
+
 ## Supported CLIs
 
 An adapter file tells ClinkX how to start one CLI, how to pass the prompt, and how to read the output. These adapters are included:
@@ -153,6 +164,8 @@ A workflow runs many CLI calls in stages and returns one result. A council workf
 
 | Workflow | Purpose |
 |---|---|
+| `architecture-comparison` | Compare two designs using frozen shared input and a fresh judge with candidate aliases. |
+| `verified-repair` | Repair declared existing files in place, reproduce the defect, and prove the fix through native checks and independent causal verification. |
 | `council-answer` | Answer one hard question. |
 | `council-code-review` | Review a change set. |
 | `council-debug` | Find the cause of a defect. |
@@ -161,7 +174,27 @@ A workflow runs many CLI calls in stages and returns one result. A council workf
 | `council-default` | General-purpose council. |
 | `plan-review-receipts` | Typed plan review that returns receipt candidates for an external approval process. |
 
-Before the first stage, the workflow runs `context_builder` with Codex as curator and finalizer. This step selects the repository files that the members receive. The `codex` command must be on your `PATH`. To skip this step, set `CLINKX_WORKFLOWS_CONTEXT_PREFLIGHT_ENABLED=false`.
+Before the first stage, ordinary workflows run `context_builder` with Codex as curator and finalizer. This step selects the repository files that the members receive. The `codex` command must be on your `PATH`. To skip this step, set `CLINKX_WORKFLOWS_CONTEXT_PREFLIGHT_ENABLED=false`. `verified-repair` uses its host-frozen declared inputs instead of this context preflight.
+
+Select `architecture-comparison` explicitly and provide `user_request`,
+`source_identity`, and optional `context_files` in `variables`. Its built-in
+templates and validators ship in the npm package. Two authors receive the same
+frozen packet; the independent judge receives a separate view with candidate
+aliases. The result reports comparison completeness and leaves owner acceptance
+unrecorded. See [engineering recipes](docs/engineering-recipes.md) for an example,
+route settings, bounds, and evidence limits.
+
+For a bug fix, invoke the companion `verified-repair` skill in Claude Code,
+Codex, or another connected MCP agent. It prepares the repair contract and
+native manifests, then calls `run_workflow` with
+`workflow: "verified-repair"`. The workflow needs three explicit provider routes
+and separate authorized project, evidence and verification-copy locations on
+the MCP host. It preserves unrelated changes and retains applied edits on
+failure; qualification never records owner acceptance. See the
+[paste-ready agent prompt and MCP calls](docs/engineering-recipes.md#using-verified-repair-from-an-agent-runtime)
+and [minimal contract and manifests](docs/verification/project-checks.md#native-verified-repair).
+The dashboard's **Verified repair** prompt-builder target prepares this caller
+skill invocation for copying; it does not execute the repair or authorize host paths.
 
 ### Roster presets
 

package/clinkx-workflows/dist/architecture-comparison/admission.d.ts

@@ -0,0 +1,5 @@
+import type { NormalizedWorkflowDefinition } from "../definition-normalizer.js";
+export declare function materializeArchitectureRoutes(definition: NormalizedWorkflowDefinition, variables: Readonly<Record<string, unknown>>, available?: readonly string[], validateOverrides?: (cli: string, knobs: {
+    model?: string;
+    effort?: string;
+}) => void): NormalizedWorkflowDefinition;

package/clinkx-workflows/dist/architecture-comparison/admission.js

@@ -0,0 +1,50 @@
+import { getMaxPromptBytes } from "../config.js";
+import { DEFAULT_RESERVE_BYTES } from "../prompt-budget.js";
+import { ARCHITECTURE_WORKFLOW, MAX_JUDGE_BYTES, MAX_VIEW_BYTES, RouteSchema } from "./contract.js";
+const ROUTE_VARIABLES = { "candidates.author_a": "candidate_a", "candidates.author_b": "candidate_b", "judge.judge": "judge" };
+export function materializeArchitectureRoutes(definition, variables, available, validateOverrides) {
+    if (definition.name !== ARCHITECTURE_WORKFLOW)
+        return definition;
+    for (const name of ["user_request", "source_identity"]) {
+        const value = variables[name];
+        const cap = name === "user_request" ? 16 * 1024 : 2000;
+        if (typeof value !== "string" || value.trim() === "" || Buffer.byteLength(value, "utf8") > cap)
+            throw new Error(`${name} must be nonblank and at most ${cap} UTF-8 bytes`);
+    }
+    const contextFiles = variables["context_files"] ?? [];
+    if (!Array.isArray(contextFiles) || contextFiles.length > 32 || new Set(contextFiles).size !== contextFiles.length)
+        throw new Error("context_files must contain at most 32 distinct source files");
+    const judge = definition.stages.find((stage) => stage.id === "judge")?.calls[0];
+    const worstCase = MAX_VIEW_BYTES + MAX_JUDGE_BYTES + DEFAULT_RESERVE_BYTES + Buffer.byteLength(judge?.prompt ?? "", "utf8");
+    if (worstCase > getMaxPromptBytes())
+        throw new Error(`architecture worst-case judge input and response reserve (${worstCase} bytes) exceeds workflow prompt budget`);
+    const tokenLimit = variables["judge_prompt_token_limit"];
+    if (tokenLimit !== undefined && (!Number.isSafeInteger(tokenLimit) || tokenLimit < worstCase))
+        throw new Error(`judge_prompt_token_limit must cover the conservative byte-token upper bound ${worstCase}; shorten the contract or use a larger route`);
+    const materialized = {
+        ...definition,
+        stages: definition.stages.map((stage) => ({ ...stage, calls: stage.calls.map((call) => {
+                const prefix = ROUTE_VARIABLES[`${stage.id}.${call.id}`];
+                if (prefix === undefined)
+                    return call;
+                const cli = variables[`${prefix}_cli`];
+                const model = variables[`${prefix}_model`];
+                const effort = variables[`${prefix}_effort`];
+                const route = RouteSchema.parse({ cli_name: typeof cli === "string" ? cli.trim() : cli, ...(model !== undefined ? { model } : {}), ...(effort !== undefined ? { effort } : {}) });
+                if (!/^[A-Za-z0-9_-]+$/.test(route.cli_name))
+                    throw new Error(`invalid ${prefix}_cli`);
+                if (route.model !== undefined && !/^[^\s\u0000-][^\s\u0000]*$/.test(route.model))
+                    throw new Error(`invalid ${prefix}_model`);
+                if (route.effort !== undefined && !/^[a-z0-9][a-z0-9_-]*$/.test(route.effort))
+                    throw new Error(`invalid ${prefix}_effort`);
+                if (available !== undefined && !available.includes(route.cli_name))
+                    throw new Error(`${prefix}_cli ${route.cli_name} is not an available JSON-capable route`);
+                validateOverrides?.(route.cli_name, { ...(route.model !== undefined ? { model: route.model } : {}), ...(route.effort !== undefined ? { effort: route.effort } : {}) });
+                const { model: _model, effort: _effort, ...base } = call;
+                return { ...base, ...route, role: "json" };
+            }) })),
+    };
+    const judgeCli = String(variables["judge_cli"]);
+    return { ...materialized, stages: materialized.stages.map((stage) => ({ ...stage, calls: stage.calls.map((call) => call.reducer === undefined ? call : { ...call, cli_name: judgeCli }) })) };
+}
+//# sourceMappingURL=admission.js.map

package/clinkx-workflows/dist/architecture-comparison/admission.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admission.js","sourceRoot":"","sources":["../../src/architecture-comparison/admission.ts"],"names":[],"mappings":"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"}