Repository navigation
docs: refresh pi worked example in harness-onboarding to match main - #22836
Conversation
Pi's compaction, local /clear, member dispatch and MCP handoff (gate-extension handoff file, broker-only projection) are described as main implements them, the version floor is named, and the still-open gaps are listed as current state.
First Principles Review (Opus 5.5) — ⏭️ skippedRevision |
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the change only updates spec prose so the pi example matches main, and it removes no code, key or path. Notes
[DESIGN-REVIEWED] fbe5c65 Description read[DESCRIPTION-READ] 83d20134b3a407cd6a1b7b1cb947997820cfa792580f29b4aea1a85e538a58be That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Problem / Motivation
Goal: Make the pi worked example in
docs/system-specs/modules/harness-onboarding.mddescribe what main's pi harness actually does today.The pi section said pi was out of both compaction sets and out of the session MCP array, and that its MCP projection was
no-channel. On main, pi is inACP_BACKENDS_COMPACT,ACP_BACKENDS_INLINE_COMPACTION,ACP_BACKENDS_LOCAL_CLEAR,ACP_BACKENDS_SESSION_MCP_ARRAYandACP_BACKENDS_MEMBER_DISPATCH. Crew's MCP servers reach pi through the gate extension's sealed handoff file, and the projection isbroker-only. The next harness author reads this example as the template, so it should be right.Why it matters
This doc is the onboarding playbook for new harnesses. A stale pi example gives authors a wrong picture of what a gate-extension harness can carry, MCP included, and it hides the gaps that are still open.
Not a goal
What changed (motivation → approach → change)
I read each pi statement in the doc and checked it against a fresh
origin/main(54c45a3acb). I rewrote every statement that no longer held, citing the code rather than PR numbers:ACP_BACKENDS_COMPACTandACP_BACKENDS_INLINE_COMPACTION, on the livecompact-live.jsonldrive. It is OUT of harness-managed compaction and context recycle. It is INACP_BACKENDS_LOCAL_CLEAR, because pi-acp's built-in list has noclear. It is OUT ofACP_BACKENDS_KIRO_SLASH_COMMANDSand all three steer sets. It is IN the session MCP array, but the array is not what mounts the servers. It is INACP_BACKENDS_MEMBER_DISPATCH.PI_MIN_VERSION(0.99.2) floor and the reason for each threshold. A pi whose manifest can't be read is let through unchecked, and the doc says so.BASELINE_SELECTABLE_BACKENDSwith abroker-onlyprojection.0700check is POSIX-only. The MCP handoff file is a third0400artifact inpi-gate._tripwire_pi_gate, both permission-bearing captures and their versions, andPI_ACP_VERIFIED_VERSION(0.0.33). A 0.0.34 adapter also logs the drift warning. The first capture's pi 0.85.1 is below today's floor.ACP_BACKENDS_HONOR_ZERO_TOOL_BAN, no mirrorACP_BACKENDS_MEMBER_CAPABILITIESandACP_BACKENDS_MEMBER_TOOL_LIMITSbroker-onlytest/real_adapters/package.jsonpins only codex-acp and opencodeACP_BACKENDS_MEMBER_PANELPiLaunch.resolve_spawn→pi_mcp_handoff_payload, AES-256-GCM under a per-spawn key,pi.registerMcpServer,exposure: "direct", sse dropped, republish on new/load, themcp.jsonshadow refusal, andbroker-only. Says exactly whatmcp-stdio-mount-live.jsonlholds as frames and what comes from the server's log note.broker-onlyto the list of declared projection kinds.Claims verified against main
Set memberships come from importing every
ACP_BACKENDS_*set on main and testing"pi" in set. Each is listed as in or out:KNOWN,ADVERTISED_MODEL_SELECTION,MODEL_VIA_CONFIG_OPTION,EFFORT_VIA_CONFIG_OPTION,EFFORT_FROM_ADVERTISED_OPTION,HARNESS_OWNED_SESSIONS,COMPACT,INLINE_COMPACTION,LOCAL_CLEAR,SESSION_MCP_ARRAY,MEMBER_DISPATCHLOAD_WITHOUT_MODES,HARNESS_MANAGED_COMPACTION,CONTEXT_RECYCLE,KIRO_SLASH_COMMANDS,STEER,STEERING_REQUEST,STEER_CONCURRENT_PROMPT,HONOR_ZERO_TOOL_BAN,MEMBER_CAPABILITIES,MEMBER_TOOL_LIMITS,MEMBER_PANELCode paths and constants:
BASELINE_SELECTABLE_BACKENDScontains pi (agent_sdk/backends.py).ProjectionKind.BROKER_ONLY(providers/mirrors/registry.py).EFFORT_CONFIG_OPTION_IDS[pi] == "thought_level"andEFFORT_CONFIG_OPTION_VALUES[pi] == {"max": "xhigh"}(agent_sdk/backends_models.py).PROTOCOL_VERSION_PI = 1(acp/client_start.py)..pi/agent/auth.json,PI_CODING_AGENT_DIR,adapter_own_leaves(agent_sdk/host_auth.py)._probe_piandpi_cached_negative(agent_sdk/backend_install.py).PI_MIN_VERSION = (0, 99, 2), the version read from the npm manifest (Nonelets the session through),PI_GATE_EXTENSION_SHA256over the LF form, thepi-gate0700dir (POSIX), handoff0400, AES-256-GCM,KIROCREW_PI_MCP_HANDOFF/KIROCREW_PI_MCP_KEY,exposure: "direct", sse dropped, republish before new/load (acp/harness/pi.py).MAX_ENVELOPE_CHARS = 200000,pi.registerMcpServer(agent_sdk/gate_extensions/pi/kiro_crew_tool_gate.ts)._tripwire_pi_gate(unasked or denied-but-completed calls),_note_pi_adapter_version,PI_ACP_VERIFIED_VERSION = "0.0.33"(acp/client_permissions.py).test/fixtures/acp_frames/pi/, each replayed viatest_acp_frame_replay.py. Versions match the fixture README.test_acp_pi_backend_spawn.py's real-pi test carriesskipif(not _pi_installed()).test/real_adapters/package.jsonpins only codex-acp and opencode-ai.A separate fresh-context subagent also fact-checked the section (about 80 claims). Its four findings were fixed before pushing: the version-floor wording, the unchecked-manifest case, the verified adapter version against the captures, and what the MCP fixture holds as frames.
Two stale statements outside my file were left alone (out of file ownership) and are noted here:
test/fixtures/acp_frames/pi/README.mdsays "Four files" but lists five..gitattributescomment namesacp/client.pyforPI_GATE_EXTENSION_SHA256. It lives inacp/harness/pi.py.Backwards compatibility
Compatible: docs-only change.
Removes nothing: only prose in one spec file changes. No code, key or path is touched.
Tests
N/A — docs only. Gates run locally on this head:
python3 scripts/docs_lint.py→All documentation checks passedHARNESS_BASE_REF=origin/main python3 scripts/check_harness_parity.py→ exit 0pytest test/test_provider_mirrors.py test/test_backend_id_uniqueness.py→ 76 passed. Both tests read this doc.Manual verification
Checked each pi statement against the code on
origin/main@54c45a3acb(list above).Related Issues
no linked issue: docs-only refresh of a spec section to match merged code.
Does not overlap the open PRs #22400, #21744, #12344, #22807, #22808 or #22813. None of them touches this file.
Checklist
Contribution License Agreement
Contributions are accepted under the project's Apache-2.0 license.