test: add opt-in workspace verification and cross-module workflow

[jbeda]

Summary

Add an opt-in way to verify coordinated Go-module changes against the same checkout before publishing dependencies, without paying for another full suite on every PR.

• Add task test:workspace and task test:workspace:race, explicitly selecting the checkout's workspace and reusing the existing 12-module inventory plus the offline tagged proof.
• Keep existing tests, standalone checks, and publication gates. CI runs only cheap infrastructure fixtures and metadata checks, not a new full workspace suite.
• Untrack/ignore root go.work.sum; retain go.work and each module's go.mod/go.sum. Share non-mutating staged/unstaged/untracked metadata checks between local use and existing CI jobs.
• Document the cross-module development, reconciliation, and dependency-first publication workflow in docs/module-development.md, linked from AGENTS.md and docs/READING.md.
• Extract the short embedded-runtime test fixture fix without identity/API changes, and increase the agent's complete-suite outer timeout guidance to 30 minutes.

Issue relationship

Relates to #2117. This is independently useful testing infrastructure, not the identity implementation or release stack.

Type of change

• Bug fix
• Documentation
• Other: contributor testing infrastructure and CI metadata hygiene

Test plan

Baseline checks

• task lint
• task --concurrency 3 test
• task --concurrency 3 test:race (passed with the updated 1800-second outer budget)
• go run ./cmd/mecademo (offline Read/result and Write ask/approval/result)
• task docs (186 documents; zero broken links/anchors)
• task --concurrency 3 test:workspace:race
• task test:workspace-infrastructure (9 metadata fixtures and 3 workspace-dispatch/resolution tests)
• task test:module-metadata
• Startup compatibility tests under race, with and without microvm_dev

Site build and engine API regeneration are not applicable: no public user-docs content, guarded API, production behavior, module pins, or wire contracts changed.

task lint:actions passed actionlint, action templates, and the new infrastructure fixtures, then stopped in the existing release fixture because local cosign is missing. This limitation is not a passing full lint:actions receipt.

API compatibility

No remote-observable behavior, public Go API, stored-data format, or dependency-version changes. No wire major or feature identifiers change; no client upgrade is required. The socket-path adjustment is test-fixture-only.

User-facing change

Contributor-only commands and guidance. Root workspace checksum churn no longer needs to be submitted. Per-module dependency metadata remains versioned and checked.

Special notes for reviewers

• Candidate workspace evidence and standalone/publication evidence remain distinct; local workspace assertions do not introduce a required-check waiver for intermediate coordinated-release PRs.
• The earlier socket failures reproduced on the unchanged baseline. The extracted fixture fix makes the real embedded-listener tests pass without skipping their compatibility or cleanup assertions.
• A previous 600-second full race attempt timed out; the subsequent run with the documented 30-minute budget passed.
• The code panel and targeted incremental fixture review have no open findings.

Implementation plan

Full approved implementation plan, including accepted amendments and the deferred intermediate-release check policy.

[jbeda]

Approved implementation plan

• Slug: workspace-testing
• Source provenance: .scratch/workspace-testing-plan.md (ignored local authoring file)
• Branch: impl/workspace-testing
• Implementation baseline: e17d8394d365a94fb79258fa02a940625bfb99ff
• Implementation head: d179b0578
• Published: 2026-10-17T17:44:52Z

This is the full approved plan, including its planning-time baseline and intended checks. Actual completed verification and limitations are reported in the PR description. Operator amendments retained here: reuse the current checkout, ignore root workspace sums while retaining module sums, extract only the socket test fixture, and allow 30 minutes for complete test suites. Machine-specific absolute checkout paths have been omitted; no functional requirements were removed. No merge, tag, release, or deployment authority is implied.

Workspace testing and cross-module contributor workflow

Slug: workspace-testing
Implementation branch: impl/workspace-testing
Base branch: main (fresh origin/main at implementation start; not the identity branch)
Plan path: .scratch/workspace-testing-plan.md
Status: approved; implementation and local verification complete. Commit/push/PR creation authorized by the operator; publication does not imply merge or release authority.

Goal and approved scope

Provide explicit opt-in commands to test every same-checkout Go module together before publishing coordinated module changes. Explain how to move from an assembled candidate to independently consumable modules without conflating the evidence.

Operator decisions:

• Add workspace non-race/race tasks, checksum hygiene, and explicit agent-discoverable cross-module instructions.
• Do NOT add another full suite/job to every PR or commit. For rare coordinated releases, a human's assertion of local workspace verification is sufficient workspace evidence.
• Preserve existing test/test:race, standalone and publication gates. Local workspace evidence is not published-dependency evidence.
• Implement on a fresh main-based branch separately from impl/2117-tool-call-identity. Operator subsequently requested using this existing checkout: the clean sibling worktree was removed and the current checkout switched to impl/workspace-testing. The committed identity branch remains available for a later separately authorized rebase.
• No module publishing, dependency-pin migration, identity changes, automatic stacked-PR integration, commits, pushes, PR creation, or rebases in this implementation without separate authority.
• Follow-up operator authorization: extract only the short embedded-runtime test fixture from the identity branch into this change. Add the runtime import/helper and its two startup-compatibility test call sites; retain API-major fixtures and production code unchanged.

Do not introduce a CI skip label, workflow waiver, branch-protection bypass, or changed required-check policy. Acceptance of local workspace evidence does not by itself define how an intermediate breaking PR passes existing checks; that separate release-stack question remains open.

Established behavior

These files are unchanged between local main (42b933f) and the current identity checkpoint; revalidate against fresh main before implementation.

• go.work includes root plus 11 nested modules (go.work:3–25).
• Taskfile.yml:334–373 enumerates all 12 modules once in test:_suite and runs them through test:_module with GOWORK=off and -mod=readonly. test/test:race select the race flag (509–524).
• The suite also invokes the offline microvm_dev-tag proof (542–547), which currently does not pin GOWORK.
• Root go.mod:337–353 contains local replacements. GOWORK=off does not remove them. environment/microvm/go.mod:5 and integration/microvm/go.mod:331+ also have local replacements. Do not describe these checks as fully public-dependency resolution.
• Providers depend on pinned engine versions; OpenAI and OpenAI Chat also depend on provider/ssefilter. Adapters depend on engine, adaptersupport and generated driver modules. Workspace mode uses local workspace modules and a combined third-party module graph, not each module's standalone graph.
• Root go test ./... does not run nested modules' own tests.
• go.work.sum is tracked. It records supplemental workspace checksums, is not a version lockfile, and can change during tests/builds/package loading even with -mod=readonly.
• task tidy runs root tidy, go work sync, then nested standalone tidy (Taskfile.yml:1148–1169). go work sync can upgrade member requirements; it is not checksum-only maintenance.
• CI Test runs task --concurrency 3 test for drafts and test:race otherwise (.github/workflows/ci.yml:984–1012). Keep this policy unchanged.
• Build CI runs task tidy and checks all Go metadata, including go.work.sum (863–870). It cannot detect changes in another job's checkout. Named standalone jobs and conditional public publication proof remain unchanged.
• The publication script checks specific persistence-module pins/main ancestry and resolves published adapters through a fresh external consumer and public proxy; it is not a universal proof for every module (.github/scripts/check-module-publication.sh).

Proposed contracts

Opt-in candidate tests

Add public tasks test:workspace and test:workspace:race. Reuse test:_suite's module/tag inventory by passing an execution mode or equivalent small internal parameter; default existing callers to today's behavior. Avoid a duplicate hand-maintained module list.

Workspace tasks must:

• Explicitly select the absolute committed go.work in this checkout, regardless of ambient GOWORK (including off or another workspace).
• Run root and every nested module's tests, plus the existing offline tagged proof, with the correct race flag and bounded caller-selected Task concurrency.
• Keep ordinary module manifests read-only (-mod=readonly), while acknowledging checksum files can change.
• Fail on any constituent test failure. Never report partial execution as a pass.
• Never run go work sync, go mod tidy, or edit requirement pins as a side effect.

Keep existing test/test:race and named standalone command semantics. Scope the explicit workspace selection for the tagged proof to new workspace calls rather than changing the existing task's ambient behavior gratuitously.

Checksum hygiene

Untrack the repository-root go.work.sum and add a root-specific ignore entry; Go may retain/regenerate each checkout's local copy. Keep go.work and every module's go.mod/go.sum tracked. Remove go.work.sum from CI freshness requirements. This replaces the original plan's tracked-workspace-sum policy after discussion of incidental workspace checksum churn.

Provide a cheap explicit metadata verification command (proposed task name: test:module-metadata) usable after workspace tests and existing CI commands. It checks tracked differences and newly untracked Go metadata: root/nested go.mod and go.sum plus root go.work, without sweeping scratch worktrees or dependencies. Explicitly exclude root go.work.sum, including any legacy tracked copy in transition. Reuse the existing CI metadata check where practical rather than maintaining divergent path policies.

This command is a cleanliness check against the committed candidate, not a formatter or dependency resolver. Check both HEAD-to-index and index-to-working-tree differences, plus untracked metadata; a staged edit reversed only in the working tree must not pass. Cover staged edits, additions and deletions, including newly staged metadata that is no longer untracked. It does not edit, reset, stage or delete files. Failures identify changed paths and tell the contributor to review/commit legitimate metadata changes and rerun. Preexisting intentional uncommitted metadata is not silently accepted; document that final cleanliness verification is performed after the intended metadata has been committed. Normal workspace test tasks themselves may leave checksum changes for review and must not call the cleanliness check unconditionally.

Add only cheap checks to existing CI jobs: reuse the helper after Build's current metadata preparation and check the Test job's own metadata after its existing successful suite. No new full suite or job. Preserve current classification/draft behavior and do not run metadata preparation automatically after a test, which would conceal its effects. Changes that need unrelated published versions remain failures, not bypasses.

Document that local go.work.sum creation/updates are expected and not submitted. Regeneration may produce a smaller file but covers only the commands run, not all supported configurations. Public checksum-database verification under normal settings and tracked per-module sums remain; an untracked workspace sum does not share prior supplemental checksum expectations, particularly relevant for private modules outside the checksum database. Do not promise a universal workspace tidy command or all-platform saturation. Do not recommend deleting tracked module sums, disabling the workspace, or running go work sync reflexively. Never delete checksum files as a workaround for checksum mismatches.

Discoverable contributor procedure

Create docs/module-development.md (contributor procedure, not a public product feature). Add a short action-oriented pointer to root AGENTS.md and a link in docs/READING.md. Link applicable module compatibility policies; avoid duplicating their versioning authority. Add scoped pointers only if needed for discovery, not a new rule framework. Use tech-writer when drafting substantive documentation, and run task docs.

The procedure must include executable commands and explicit stages:

1. Map changed modules and direct/transitive consumers; distinguish source compatibility, wire compatibility and stored-data concerns. Existing compatibility policies still govern changes.
2. Develop the coordinated same-checkout candidate. Run focused workspace tests using an absolute checkout go.work. Update generated/API artifacts only through owning tasks when applicable.
3. Run task --concurrency 3 test:workspace, then test:workspace:race as final candidate evidence, retaining the existing offline tagged proof. State the checkout/commit, command, toolchain and result in the PR's test evidence; after changes, rerun affected checks. No new attestation parser/enforcement system.
4. Review incidental Go metadata. If requirements/imports actually changed, tidy the affected modules deliberately with GOWORK=off and inspect replacements. Explain why tidy may be blocked until new dependency versions exist. Explain current task tidy ordering and go work sync's upgrade effects, without changing tidy semantics in this PR.
5. Review and commit intended metadata through the normal authorized workflow; rerun candidate verification and the cheap cleanliness check. Checksum mismatches require investigation, not deleting checksum history. Do not mistake a clean check for standalone/publication proof.
6. Prepare dependency-first PRs/releases. Local workspace results can establish candidate integration before publication but cannot manufacture a green standalone boundary. Identify unavailable pins/failing gates honestly and obtain an explicit merge-policy decision before proceeding. No implicit bypass approved here.
7. After a human merges a dependency PR, select its actual main-reachable release commit and publish its independent module tag through the owning release process. Do not publish PR-head versions that a squash merge strands off main. Do not assume a premerge SHA will survive merge. If a dependency layer needs several independently tagged modules, order by the real dependency DAG.
8. Update consumers to real released versions, tidy each affected module independently, inspect local replacements, and run its genuine standalone checks. Existing replacements are checkout conveniences, not evidence of external resolvability; use the appropriate external-consumer/publication proof where needed. Do not invent a universal proof that the current script does not implement.
9. Repeat for dependent layers, finish host/integration pins, run existing full gates and workspace gates, and verify tracked metadata is stable. Record any remaining unavailable proofs rather than declaring readiness.

Include a compact command table distinguishing task build, test/test:race, workspace tasks, named standalone tasks, task tidy, metadata check and publication proof. Include the module dependency outline and why workspace-selected third-party versions can differ from standalone versions.

Implementation tasks

1. Establish implementation checkout. Per the operator's explicit amended location choice, use the current checkout on impl/workspace-testing. Base/start is e17d839 from freshly fetched origin/main. The clean sibling worktree was removed; preserve the committed identity branch. Record the implementation start OID in ignored run notes.
2. Add workspace suite mode. Parameterize existing module/suite machinery minimally, add two public tasks, pin the checkout workspace, forward the mode/race choice through the tag proof. Preserve the single module inventory and old behavior.
3. Add metadata cleanliness helper/check and focused regression tests. Reuse existing Build job semantics, add cheap post-test verification to its existing checkout, and provide a local command. Tests run real Task wiring against small offline test-owned fixture modules and controlled environment/PATH as appropriate; do not rely only on YAML string assertions. Integrate these cheap regression tests into an existing verification path without running the full new workspace suite in CI.
4. Document the cross-module workflow and discovery pointers. Implement the procedure above, reconcile only directly conflicting owning instructions, and validate commands against the actual tasks. Do not rewrite unrelated release policies/docs.
5. Integrate and review. Run focused fixtures, task listing/dry runs, actual workspace tests on the main-based candidate, current applicable gates and panel review. Resolve findings; no automatic commit/push/PR.

Tasks 2 and 3 share execution contracts and should integrate before task 4 is finalized.

Observable acceptance and tests

• Every go.work member, including integration/microvm, is exercised; member omissions/drift are detected by a completeness test rather than a second production inventory.
• A tiny fixture consumer succeeds only when the local candidate dependency is selected, despite a deliberately incompatible standalone version; an independent standalone positive control remains valid. Use offline fixture modules/local test-owned proxy if versioned resolution is needed, not operator caches or network.
• Ambient GOWORK=off and an unrelated workspace cannot change the new tasks' resolution, including the tagged leg. Existing suite calls still supply GOWORK=off to normal modules.
• Race/non-race flag forwarding, tagged coverage and failure propagation are tested at invocation boundaries; include a failing nested module and tagged proof. Keep test fixtures in t.TempDir()/managed TMPDIR, not .scratch.
• Metadata checks pass on clean fixtures and fail on staged, unstaged or newly untracked root/nested go.mod/go.sum and root go.work. They ignore root go.work.sum even when generated or modified, ignore unrelated/scratch files, handle paths safely, and do not modify files. Verify the root-specific ignore policy while retaining module go.sum tracking. Test a first workspace checksum update followed by stable rerun where practical; neither generation nor updates to the ignored sum may fail the guard.
• CI retains its current Test suite/draft selection and standalone/publication jobs, adds no automatic full workspace run, and detects metadata changes in the job that produced them. Preserve classifier/fail-closed behavior.
• Agent entry points link to the contributor procedure, which distinguishes candidate verification, replacements, release ordering and actual publication proof scope.

Verification and delivery

Focused real command/fixture tests first; task lint and task test once on the integrated main-based change, then task test:race. Per the operator's timeout increase, give complete Go test suites 1800 seconds (30 minutes) each and other full gates 600 seconds. Run test:workspace:race explicitly for the new path, task docs for Markdown, offline go run ./cmd/mecademo showing tool call, permission ask/approval and result. Check no unintended dependency/API/generated changes remain. If full gates time out/fail, investigate and report, never count cancellation as success.

Use panel-review against the implementation branch's recorded start OID, not moving main or the identity checkpoint. Focus on task selection, shell/metadata handling, CI cost and documentation correctness. No product wire/API behavior change intended; no engine public API change.

If later authorized to open a PR, preserve a publishable full copy of the approved plan in one verified PR conversation comment per plan-implement; no posting authority is implied now.

Plan review

Fresh-context review found no blockers and one important correction: the metadata guard must cover staged as well as unstaged changes, including staged edits reversed only in the working tree. Folded into the checksum contract and required regressions. A focused checksum-policy recheck found no blocker; its request to clarify Test-job wiring is already explicit above: add a new cheap invocation after its existing suite, since it has no guard today. Its uncertainty about -mod=readonly and workspace checksum writes must be settled by real Go fixture tests, not by dropping manifest protections on speculation. Reviews did not execute tests or fetch fresh main; implementation must revalidate those facts.

Open boundary for operator confirmation

The plan intentionally leaves the existing CI/merge requirements untouched. Some intermediate coordinated-release PRs may still fail because old consumers or unpublished dependency pins cannot compile. Local workspace attestation is accepted as workspace evidence, but does not automatically waive those checks. A later explicit release-stack policy is required if such a PR must merge before its existing checks can pass. This PR should ship independently without solving that policy.