docs: require mcpg v0.4.18 and fix enclave network membership

[lpcox]

Summary

Audited the enclave documentation and cross-component comments against the current implementations in AWF main, gh-aw main, and gh-aw-mcpg v0.4.18. Found two factual errors and fixed both.

No behavior change — comments, docs, and one test description only.

1. The documented mcpg floor was wrong (v0.4.17 → v0.4.18)

docs/enclaves-architecture.md stated dynamic repository admission runs on "mcpg v0.4.17 or newer". That's incorrect now that delegation durations are whole seconds on the wire:

	v0.4.17	v0.4.18
max_identity_ttl	time.Duration → nanoseconds	int64 seconds (wire.go)
requested_ttl	time.Duration → nanoseconds	int64 seconds (wire.go)
internal/delegation/wire.go	absent (404 at that tag)	present

Current AWF sends requested_ttl: 120. Against v0.4.17 that decodes as 120 nanoseconds — an instantly-expired identity. gh-aw already pins the correct floor (DefaultMCPGatewayVersion = v0.4.18 in pkg/constants/version_constants.go), so only AWF's docs and comments were stale.

Corrected in five places: the architecture doc plus the four source/test comments that cited v0.4.17 (delegation-control-client.ts, dynamic-delegation-handoff.ts, and two in dynamic-delegation-contract.test.ts).

I also disambiguated the static base floor (spec 1.15.0 / post-v0.4.8, still accurate) from the dynamic floor in both enclaves-architecture.md and awf-config-spec.md, since a reader could otherwise take the base floor as sufficient for dynamic enclaves.

Verified, not relabeled on trust

The contract fixture exists to pin upstream, so bumping its version label without re-checking would defeat it. I diffed each pinned constant against v0.4.18 before relabeling:

• delegationControlPath = /internal/awf-enclave-mcp-control/ ✓
• All five operation paths: create-or-confirm, status, reconcile, revoke, revoke-by-labels ✓
• CreateOrConfirmRequestWire key set, including RequestedTTLSeconds int64 with json:"requested_ttl" ✓
• Closed tool set {issue_read, list_issues} in internal/delegation/selector.go ✓

2. CLAUDE.md misstated the enclave network membership

It claimed "the MCP gateway are excluded" from awf-enclave-agent. The opposite is true whenever GitHub access is configured — statically or dynamically — and it's how the enclave reaches the GitHub data plane at all:

// containers/enclave/agent-executor/docker-enclave-runner.js:35-39
if (this.config.githubEnabled || this.config.dynamicEnabled) {
  const steadyStateMembers = [proxyMember,
    `${this.config.githubGatewayContainer}@172.31.0.40/24,`];

Rewrote that bullet to state the mandatory peer (dedicated API proxy), the conditional peer (shared mcpg at 172.31.0.40, alias awf-enclave-github-mcp), what genuinely is excluded, and that assertNetworkIsolated enforces the exact membership set. Also added the missing dynamic-enclave bullet: control client in the host process, 0700 file channel to enclave-mcp-server, no new network listener.

Two terminology slips fixed while there: enclave_run_script "launches a … Python executor" → enclave (an executor is broker-side machinery; the launched container is an enclave, per the terminology note in enclaves-architecture.md), and used enclave-mcp-server rather than "broker" to match the naming we agreed to keep.

3. Recorded the capability-only decision

enclaves-architecture.md already described the reachability model correctly (4783af78). Added a short note that relying on capability authentication alone for the delegation control listener is a reviewed decision — github/gh-aw#59268, closed as not planned — rather than an oversight, with the constant-time/pre-routing/separate-handler properties that make it hold. Without this, the next reader may re-litigate it as a bug.

Validation

• npm run build (tsc) — clean
• npm run lint — 0 errors
• npx jest src/enclave src/services/enclave — 28 suites, 549 tests pass
• npx jest — 356 suites, 5806 tests pass
• Upstream facts re-fetched live from gh-aw@main and gh-aw-mcpg@v0.4.17/v0.4.18 rather than from memory

Refs #8195
Refs github/gh-aw#59268

Fixes: #8195

[github-actions]

Documentation Preview

Documentation has been built for this PR.

Download preview artifact

To view locally:

1. Download the docs-preview-pr-8305 artifact from the workflow run
2. Unzip and open index.html in your browser

Built from commit 5b9e19c

[Copilot]

Copilot review overview

🟢 Approval recommended

The only unresolved comment is a minor provenance-attribution nit.

Review tier: Balanced
Findings: None

What changed in this PR

Corrects enclave documentation and comments to match current AWF and mcpg behavior.

Changes:

• Raises dynamic delegation’s mcpg minimum to v0.4.18.
• Corrects enclave network membership documentation.
• Records capability-only authentication as intentional.

File	Description
src/​enclave/​dynamic-delegation-handoff.ts	Updates the documented mcpg version.
src/​enclave/​dynamic-delegation-contract.test.ts	Relabels the v0.4.18 contract; PR attribution has a non-blocking nit.
src/​enclave/​delegation-control-client.ts	Updates wire-contract commentary.
docs/​enclaves-architecture.md	Corrects version, topology, and security details.
docs/​awf-config-spec.md	Clarifies static and dynamic mcpg requirements.
CLAUDE.md	Corrects enclave architecture guidance.

Suppressed comments (1)

src/enclave/dynamic-delegation-contract.test.ts:16

• The provenance is inaccurate: PR #12605 shipped in v0.4.17 and retained the time.Duration wire fields; wire.go and the whole-second encoding were introduced separately by gh-aw-mcpg PR #12686 for v0.4.18. Because this fixture explicitly documents which upstream change its constants were copied from, please attribute the seconds contract to #12686 (or remove the PR attribution).

 * - `github/gh-aw-mcpg` v0.4.18 `internal/proxy/delegation.go`,
 *   `internal/delegation/wire.go`, and
 *   `internal/delegation/{identity,store,selector}.go` (PR #12605): the
 *   operation paths, the `CreateOrConfirmRequest`/`IdentityResult` JSON key
 *   sets, the whole-second duration encoding, the status/reconcile/revoke

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

✅ Coverage Check Passed

Overall Coverage

Metric	Base	PR	Delta
Lines	94.03%	94.05%	📈 +0.02%
Statements	92.70%	92.71%	➡️ +0.01%
Functions	93.33%	93.33%	➡️ +0.00%
Branches	86.62%	86.63%	➡️ +0.01%

📁 Per-file Coverage Changes (1 files)

File	Lines (Before → After)	Statements (Before → After)
src/log-directory-setup.ts	96.2% → 100.0% (+3.78%)	96.3% → 100.0% (+3.71%)

---

Coverage comparison generated by scripts/ci/compare-coverage.ts