Add portable Workflow assistant example

decisions/0064-package-workflow-agent-example.md

@@ -0,0 +1,19 @@
+# 0064. Package a direct Workflow assistant example
+
+**Status:** Accepted
+**Date:** 2026-10-19
+**Related:** `docs/plans/2026-10-19-workflow-agent-plugin-design.md`
+
+## Context
+
+Users need repeatable config authoring, diagnosis and readiness evidence using public Workflow capabilities. Existing wfctl already exposes stdio MCP. Go engine plugins occupy `plugins/`; full standalone samples belong under `example/`.
+
+## Decision
+
+Place a portable Agent Plugins package under `example/workflow-agent-plugin`, containing three skills and a direct `wfctl mcp` connection. Discover live tools and schemas before use. Keep evidence explicit about validation versus runtime acceptance. Do not bundle binaries, create an orchestration wrapper or depend on private services.
+
+Alternatives: prose-only documentation lacks a loadable workflow package; a new wrapper server duplicates wfctl and adds a maintenance surface. A new repository is unnecessary for this bounded example.
+
+## Consequences
+
+The package can be copied from public GitHub independently of engine source. Users supply wfctl and a local-capable host. Full desktop skill activation remains a separately recorded acceptance gate. The upstream MCP tool surface remains visible and host permissions still apply. Reverting the additive package removes it without service changes.

decisions/0065-use-go-for-agent-tests.md

@@ -0,0 +1,38 @@
+# 0065. Use Go for assistant package verification
+
+**Status:** Accepted
+**Date:** 2026-10-19
+**Related:** `0064-package-workflow-agent-example.md`, `docs/plans/2026-10-19-workflow-agent-plugin.md`
+
+## Context
+
+The initial package used a Python stdlib MCP client and Python jsonschema for two
+vendored portable manifests. Neither language nor validator is required by the
+MCP or Agent Plugins standards. The repository already uses Go and
+`github.com/santhosh-tekuri/jsonschema/v6 v6.0.3`.
+Its existing dependency checksums also pin `github.com/dlclark/regexp2 v1.11.0`.
+
+## Decision
+
+At the user's request, replace the new Python tests/helper with Go. Keep a small
+standalone tests module using that existing schema dependency/version; the smoke
+consumer itself uses the Go standard library. Preserve all assertions, real
+release probes, failure privacy and lifecycle regressions. A related root Go
+integration test invokes the nested suite through the existing native CI command.
+The workflow trust policy requires three staged PRs for workflow changes, so
+the workflow and its authority manifests remain unchanged.
+
+Python's short standalone implementation did not outweigh a second test language
+and package manager. Reimplementing JSON Schema validation would weaken the
+official-schema proof, so reuse the existing Go validator instead.
+The unchanged official schema contains ECMA negative lookahead unsupported by
+Go's standard regexp package. Use the validator's documented regexp2 adapter at
+that existing pinned version rather than weakening the schema.
+
+## Consequences
+
+No Python/pip dependency remains in the distributed package. The standalone
+tests need Go and existing public schema dependencies, with no Workflow engine
+or private module import. The three skills/direct MCP runtime are unchanged.
+This replaces implementation within the same three tasks and draft PR; it does
+not expand the shared MCP SDK or platform scope.

docs/mcp.md

@@ -4,6 +4,10 @@ The workflow engine includes a built-in [Model Context Protocol (MCP)](https://m
 
 The MCP server is integrated into the `wfctl` CLI as the `mcp` subcommand. Use `wfctl mcp` to start it. This ensures the MCP server version always matches the CLI and engine version, and benefits from automatic updates via `wfctl update`.
 
+For a portable assistant package with configure, diagnose and readiness skills,
+see the [Workflow Assistant example](../example/workflow-agent-plugin/README.md).
+It connects directly to this MCP server and documents validation and host limits.
+
 ## Features
 
 The MCP server provides:

docs/plans/2026-10-19-workflow-agent-plugin-alignment.md

@@ -0,0 +1,18 @@
+# Design-to-plan alignment
+
+**Status:** PASS (2026-10-19)
+
+| design requirement | plan task | reverse trace |
+|---|---|---|
+| portable manifests, local direct MCP, three focused skills, privacy/tool restrictions | Task 1 | justified |
+| public self-contained fixtures, real released MCP, missing executable/version/tools/types/imports/prerequisites, safe errors | Task 2 | justified |
+| source/snapshot/version evidence, audit/coexistence, independent review, public draft distribution, host/runtime limits | Task 1 and Task 3 | justified |
+| no engine/platform/Compute/session/infra modifications; rollback | all tasks/out-of-scope/rollback notes | justified |
+
+All requirements ship in PR row 1; Task 1–3 each appear once, with one existing isolated branch. No drift or scope creep. `plan-scope-check.sh --plan ... --strict` returned `PASS: scope-manifest checks succeeded.`
+
+Execution checklist: contract tests RED → manifest/shared reference → configure scenario GREEN → diagnose scenario GREEN → readiness scenario GREEN → Task 1 checks/commit → smoke negative tests RED → stdio client/fixtures → real release checks/commit → independent package review → extraction/privacy/coexistence audit → evidence/draft PR.
+
+Skill baseline (`skill_cases`, no new skills): configure incorrectly chose documented `type` and `config/target_version` arguments, promising v0.90.0 compatibility. Diagnose correctly withheld install and recognized unresolved imports; readiness correctly withheld deployment badge. These are scenario evaluations, not host activation evidence.
+
+Task 1 GREEN scenarios (`skill_cases`): configure used live `module_type`/`yaml_content` and retained v0.90.0 compatibility as unknown; diagnose retained incomplete imports and unmet prerequisite without installing; readiness withheld deployment badge, separated reported/observed data, and ignored an untrusted YAML instruction to reveal environment values. Each skill was evaluated before proceeding to the next. No actual host activation, tool selection or secret redaction guarantee is inferred from these scripted evaluations.

docs/plans/2026-10-19-workflow-agent-plugin-code-review.md

@@ -0,0 +1,88 @@
+# Independent package review
+
+Reviewer: `package_skeptic`, read-only, 2026-10-19.
+
+## Round 1 — REQUEST-CHANGES
+
+Full diff `origin/main..1383f64`; structural scope gate PASS.
+
+| ID | severity/class | location | finding | resolution |
+|---|---|---|---|---|
+| C1 | Important / missing edge cases | `tests/mcp_smoke.py`, Client.close | Broken stdin close could throw before child reaping. Real child reproduced the leak. | `a3331d3`: catch pipe failure, continue teardown; real-child regression. |
+| C2 | Minor / concurrency | `tests/mcp_smoke.py`, Client._read | Blocking queue writes could strand daemon reader after shutdown. | `a3331d3`: stop event + interruptible bounded puts; full-queue regression. |
+| C3 | Minor / missing edge cases | `tests/mcp_smoke.py`, Client.request | Notifications renewed a 10s timeout up to 100 times. | `a3331d3`: one monotonic request deadline; notification/elapsed-time regression. |
+
+All paths in finding locations are relative to `example/workflow-agent-plugin/`.
+Each root-cause fix was independently reverted/restored: expected FAIL → PASS.
+
+## Round 2 — SHIP-IT
+
+Full diff `origin/main..a3331d3` re-read, all mandatory classes scanned. No open
+Critical/Important/Minor findings. Reviewer reran 17 tests and real v0.86.2 smoke
+(33 tools, release checksum unchanged); diff check PASS. Final historical test
+counts were reconciled in the evidence document before publication.
+
+| mandatory class | result |
+|---|---|
+| Symmetry | Clean: three skills share contract. |
+| Error swallowing | Clean: safe categorization intentional, broken pipe no longer interrupts cleanup. |
+| Comment/code drift | Clean after final evidence count reconciliation. |
+| Test-name/body mismatch | Clean: regression names match failure paths. |
+| Missing edge cases | Clean: lifecycle/notification cases covered. |
+| Concurrency | Clean: producer observes shutdown; reader termination checked. |
+| Type coercion | Clean: bool IDs rejected, malformed data fails safely. |
+| Dead/unreachable code | No tangible finding. |
+| Scope drift | None. |
+| Shortcut/band-aid fixes | Clean: fixes target actual lifecycle/deadline causes. |
+| One-sided boundary wiring | Clean: real manifest/released-wfctl crossing. |
+| Declared integration unused | Clean: host/coexistence explicitly config-only; activation deferred. |
+| Hermeticity/non-determinism | Clean: isolated children/doubles, explicit release executable. |
+| Portability | Clean: placeholders/direct launch, no certification claim. |
+| Vacuous assertions | Clean: process/reader/deadline and actual release behavior observed. |
+
+Scope gate covers all three user workflows, direct public wfctl reuse, standalone
+fixtures, negative/privacy tests, bounded evidence, preserved Autodev/Compute,
+and no forbidden hooks/installer/platform/hosted service/telemetry. Source
+publication is the remaining Task 3 operation. Full desktop activation is an
+explicit authorized deferral, not inferred integration proof.
+
+## Go conversion — independent REQUEST-CHANGES
+
+The user requested Go verification; ADR 0065 replaces the initial Python test
+implementation. Historical rounds above do not certify this replacement.
+
+| ID | severity/class | finding | resolution |
+|---|---|---|---|
+| G1 | Important / silent coercion | Invalid UTF-8 is replaced by Go JSON encoding while original bytes were hashed; real released smoke reproduced a false tested-snapshot identity. | Strict fixture UTF-8 rejection before child launch; strict protocol decode too. Independent real-binary repro now fails safely without evidence; launch-marker regression and revert/restore proof pass. |
+| G2 | Minor / vacuous assertion | A short notification timeout could expire before a slow child sends notifications. | Child readiness barrier plus at least two consumed notifications; deadline-renewal mutation fails and restored test passes. |
+
+Independent reviewer mapped all four prior package contracts and thirteen smoke
+contracts to Go equivalents, verified unchanged schemas/six fixture digests,
+focused CI wiring and bounded host claims. Race tests, vet and released MCP
+passed before these findings; passing happy paths did not resolve G1/G2.
+Additional focused cancellation coverage and removal of unnecessary Unix PATH
+assumptions are included in the correction. All mandatory bug classes were
+scanned; no feature/platform scope drift found.
+
+Corrected Go verification independently passed: 22 substantive tests plus helper
+under race detection (7.561 seconds), vet, actual v0.86.2 smoke (33 tools, same
+binary/fixture digests), and the actual root integration test file (8.953 seconds
+including nested race suite). Root wiring preserves the existing workflow trust
+policy and introduces no workflow/authority change. Installed-host discovery
+claims remain bounded to the separately reviewed disposable test.
+
+## Corrected Go round — SHIP-IT
+
+Independent final scan: no Critical, Important or Minor findings remain. All
+mandatory classes were rescanned: symmetry, error handling, comment/body drift,
+edge cases, concurrency, coercion, dead code, scope, root causes, boundary wiring,
+integration use, hermeticity, portability and vacuous assertions. This verdict
+approves bounded draft source, not complete customer host/runtime acceptance.
+Exact-head hosted CI is an external acceptance gate tracked on PR 1083.
+
+Hosted lint on `2289194` found SA1019 in the root integration test's use of
+deprecated runtime.GOROOT. The correction uses standard PATH-based `exec` lookup
+for Go, without suppressions. Independent narrow review: SHIP-IT; exact-file vet,
+race test including nested suite (8.975 seconds), diff check all pass. Official
+CI linter v2.14.0 was checksum-verified and run task-locally against that file:
+zero issues. Package source/tree/archive are unchanged by this wrapper fix.

docs/plans/2026-10-19-workflow-agent-plugin-design-review.md

@@ -0,0 +1,38 @@
+# Adversarial design review
+
+Independent reviewer: `design_skeptic` (read-only), 2026-10-19.
+Artifact: `2026-10-19-workflow-agent-plugin-design.md`.
+
+## Cycle 1 — FAIL (`745c73e`)
+
+| ID | severity/class | finding | resolution |
+|---|---|---|---|
+| D1 | Important: assumptions/runtime validity | Released basic validation skips workflow/trigger checks and permits no entry points; real unknown step/workflow/trigger input returned valid. | `f159527`: basic + deep validation + discovered inventory comparison; preserve false-positive probes. |
+| D2 | Important: failure modes/evidence | MCP string loaders do not resolve imports; nonexistent imports can validate and vanish from inspection. | `f159527`: single-document boundary, incomplete imports, separate flattened artifact, exact sanitized snapshot identity/equivalence unknown. |
+| D3 | Minor: privacy boundary | list_plugins data_dir can override isolated default inventory. | `f159527`: no-argument inventory only; allowlisted tools; upstream surface is not sandboxed. |
+
+Reviewer independently exercised released v0.86.2 stdio, invalid-type checks and missing-import acceptance. No file/session/app changes.
+
+## Cycle 2 — PASS (`f159527`)
+
+No open Critical/Important/Minor findings. Later `d2c93a1` adds plan review's prerequisite clarification without changing architecture.
+
+| mandatory class | result/evidence |
+|---|---|
+| Project guidance conflicts | Clean: repo guide/layout respected. |
+| Assumptions under attack | Clean: disproved validator assumptions replaced with bounded coverage. |
+| Repo precedent | Clean: no core or Go plugin ownership changes. |
+| Artifact class precedent | Clean: existing example root. |
+| YAGNI | Clean: no resolver/validator/server added. |
+| Missing failure modes | Clean: types/imports/redaction/protocol/dependency gaps bounded. |
+| Security/privacy | Clean: explicit restrictions, no sandbox claim. |
+| Infrastructure | Clean: no app/DB/browser/Docker/service/session changes. |
+| Multi-component validation | Clean: released stdio required; desktop/runtime deferred. |
+| Declared integration proof | Clean: explicit integration matrix. |
+| Contributed UI proof | Clean: none. |
+| Rollback | Clean: additive revert/removal. |
+| Simpler alternative | Clean: single-document boundary avoids import subsystem. |
+| User intent | Clean: three public workflows, Compute deferred. |
+| Existence/runtime validity | Clean: real consumer checked and claims corrected. |
+
+Options: use consistent per-check evidence across docs/tests; keep upstream false-positive assertions distinct from package coverage statements. Reviewer verdict: resolution addresses verified defects without expanding platform or obscuring deferred acceptance.