Skip to content

docs: refresh pi worked example in harness-onboarding to match main - #22836

Merged
iamwhatever merged 1 commit into
mainfrom
docs/pi-harness-onboarding-refresh
Oct 21, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
docs/pi-harness-onboarding-refresh

Conversation

@kyleseaman

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Make the pi worked example in docs/system-specs/modules/harness-onboarding.md describe 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 in ACP_BACKENDS_COMPACT, ACP_BACKENDS_INLINE_COMPACTION, ACP_BACKENDS_LOCAL_CLEAR, ACP_BACKENDS_SESSION_MCP_ARRAY and ACP_BACKENDS_MEMBER_DISPATCH. Crew's MCP servers reach pi through the gate extension's sealed handoff file, and the projection is broker-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:

  • Stage 2 (capability sets): pi is IN ACP_BACKENDS_COMPACT and ACP_BACKENDS_INLINE_COMPACTION, on the live compact-live.jsonl drive. It is OUT of harness-managed compaction and context recycle. It is IN ACP_BACKENDS_LOCAL_CLEAR, because pi-acp's built-in list has no clear. It is OUT of ACP_BACKENDS_KIRO_SLASH_COMMANDS and all three steer sets. It is IN the session MCP array, but the array is not what mounts the servers. It is IN ACP_BACKENDS_MEMBER_DISPATCH.
  • Stage 3 (spawn): adds the 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.
  • Stage 7: pi is in BASELINE_SELECTABLE_BACKENDS with a broker-only projection.
  • Routing: the extension refuses three cases outright instead of raising a dialog: a shadowed Crew server name, no UI channel, and an oversize envelope. The 0700 check is POSIX-only. The MCP handoff file is a third 0400 artifact in pi-gate.
  • Residual: names _tripwire_pi_gate, both permission-bearing captures and their versions, and PI_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.
  • Stage 8: lists the five replayed live captures. Notes that the real-pi spawn test skips on hosts without pi.
  • New "open gaps" row, as current state:
    • zero-tool ban: out of ACP_BACKENDS_HONOR_ZERO_TOOL_BAN, no mirror
    • saved-spec verification: out of ACP_BACKENDS_MEMBER_CAPABILITIES and ACP_BACKENDS_MEMBER_TOOL_LIMITS
    • the spec's own servers and per-tool deny set: not carried under broker-only
    • mid-turn steer
    • real-adapter lane: test/real_adapters/package.json pins only codex-acp and opencode
    • member panel: out of ACP_BACKENDS_MEMBER_PANEL
  • MCP paragraph: rewritten for the handoff-file channel. Covers PiLaunch.resolve_spawn → pi_mcp_handoff_payload, AES-256-GCM under a per-spawn key, pi.registerMcpServer, exposure: "direct", sse dropped, republish on new/load, the mcp.json shadow refusal, and broker-only. Says exactly what mcp-stdio-mount-live.jsonl holds as frames and what comes from the server's log note.
  • Stage 7 general text: adds broker-only to 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:

  • In: 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_DISPATCH
  • Out: LOAD_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_PANEL

Code paths and constants:

  • BASELINE_SELECTABLE_BACKENDS contains pi (agent_sdk/backends.py).
  • The pi projection is ProjectionKind.BROKER_ONLY (providers/mirrors/registry.py).
  • EFFORT_CONFIG_OPTION_IDS[pi] == "thought_level" and EFFORT_CONFIG_OPTION_VALUES[pi] == {"max": "xhigh"} (agent_sdk/backends_models.py).
  • PROTOCOL_VERSION_PI = 1 (acp/client_start.py).
  • Auth declaration: leaf .pi/agent/auth.json, PI_CODING_AGENT_DIR, adapter_own_leaves (agent_sdk/host_auth.py).
  • _probe_pi and pi_cached_negative (agent_sdk/backend_install.py).
  • PI_MIN_VERSION = (0, 99, 2), the version read from the npm manifest (None lets the session through), PI_GATE_EXTENSION_SHA256 over the LF form, the pi-gate 0700 dir (POSIX), handoff 0400, 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).
  • Five fixtures under test/fixtures/acp_frames/pi/, each replayed via test_acp_frame_replay.py. Versions match the fixture README.
  • test_acp_pi_backend_spawn.py's real-pi test carries skipif(not _pi_installed()).
  • test/real_adapters/package.json pins 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.md says "Four files" but lists five.
  • The .gitattributes comment names acp/client.py for PI_GATE_EXTENSION_SHA256. It lives in acp/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 passed
  • HARNESS_BASE_REF=origin/main python3 scripts/check_harness_parity.py → exit 0
  • pytest 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

  • At most two commits (one is the norm), with a Conventional Commits title
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license.

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.
@kyleseaman
kyleseaman requested review from a team and KiroCrewCaptain as code owners October 21, 2026 17:46
@kyleseaman
kyleseaman requested a review from buluoray October 21, 2026 17:46
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 21, 2026
@github-actions

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision fbe5c6593c6ca6b9f2f116dcd238633fafc8f211 ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Does not block merge.

@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision fbe5c6593c6ca6b9f2f116dcd238633fafc8f211 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of fbe5c6593c6ca6b9f2f116dcd238633fafc8f211 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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

  • The description names two stale statements it left alone: the fixture README says "Four files" but lists five, and the .gitattributes comment points to the wrong path for PI_GATE_EXTENSION_SHA256. Fix them in a follow-up so the onboarding template and its fixtures agree.

[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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed fbe5c6593c6ca6b9f2f116dcd238633fafc8f211 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] fbe5c65

Verdict parsed from the review's SHA-scoped output markers for commit fbe5c6593c6ca6b9f2f116dcd238633fafc8f211.

False positive or not applicable? A repository writer can comment:
/ai-review override fable fbe5c6593c6ca6b9f2f116dcd238633fafc8f211: <one-sentence reason>

@github-actions

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of fbe5c6593c6ca6b9f2f116dcd238633fafc8f211 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] fbe5c65

False positive or not applicable? A repository writer can comment:
/ai-review override gpt fbe5c6593c6ca6b9f2f116dcd238633fafc8f211: <one-sentence reason>

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 21, 2026
@iamwhatever
iamwhatever enabled auto-merge (squash) October 21, 2026 21:14
@iamwhatever
iamwhatever merged commit f03ac4e into main Oct 21, 2026
104 checks passed
@iamwhatever
iamwhatever deleted the docs/pi-harness-onboarding-refresh branch October 21, 2026 22:30
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants