docs: the platform-interop page — how an orchestration platform hosts a crew (#182)

[radiusred-wordy]

Closes #182, closes #54 — M7-R7.

What was written. docs/platform-interop.md, the ladder's last rung: how
a full orchestration platform hosts a CodeCrew crew. Its sections, in order —

1. The separation of concerns — the platform owns waking, discussion and
   the run loop; CodeCrew owns the record, the routing table and the gates.
   With the run's central finding (gates bind agents that use the verbs) and
   its mirror (dispatch on the platform, cite on GitHub).
2. The coordinator is a seat, and its own agent — roles/coordinator.md,
   gh codecrew identity new coordinator, the permission set and what it
   deliberately cannot do, why the platform's lead agent is not it (Document orchestration-platform interop (the ladder's last rung) #54's
   decision), and the watch obligation for coordinators that are not a
   platform.
3. Mapping agents to roles — the routing table, gh codecrew roles show <role> as the bundle, roles/<role>.local.md as the platform overlay
   (linking docs/extensions.md), and bundles belonging to the company while
   the project is a parameter of the wake.
4. Credentials — gh codecrew identity token, the three namings for two
   secrets and the env table, the 401 reflex, per-agent GH_CONFIG_DIR, and
   why a verb beats a sketch in prose.
5. Wake paths, and the one-wake-path rule — mention, assignment, webhook;
   why redundancy costs and hides outages; re-read at the act; execution
   events one-shot; the per-seat hand-back table; both receiver shapes.
6. The onboarding checklist — eleven rows in setup order, each with the
   finding that priced it: the Project first, App hooks not repository hooks,
   instructions layered not replaced, bundles reinstalled from roles show,
   single-flight, execution events one-shot, routines as a user act, the
   payload path in the template, lastFiredAt as the health check, ping →
   422, and the coordinator handoff checklist.
7. What it costs — the per-cycle tables from End to end under an orchestrator: prove the flow driven by Paperclip (or another platform) #119 entry 18 and Cycle 4 of the orchestrator run: radiusred/snake on the coordinator seat, then seat-routed routines #164 entry
   2, reproduced exactly as recorded (two tables, not merged: the logs count
   touches differently), with the three readings the logs themselves state and
   an honest line about what this is more expensive than.
8. The worked example: Paperclip — Project, agents, identities, routines
   with github_hmac triggers, App hooks, ingress and the allowlist, the
   overlay, kickoff. Ids, hostnames and secrets are placeholders.
9. What is not solved yet — seven named gaps.

From what. #119 (entry 18 and findings 1, 2, 7, 10, 12, 15, 16, 20, 26,
29, 35, 36, 38, 39, 40, 41, 42, 44, 46, 48, 50, change points 2, 3 and 5),
#164 (entries 1–2 and findings 51–68), #54 (the watch-seam finding, the
fifth-seat position, the onboarding note, the relay prior art, the
manual-setup inventory, the coordinator-is-its-own-agent decision, the watch
obligation), SPEC §5/§7/§9, roles/coordinator.md, docs/identities.md
("The receiver side"), docs/extensions.md, and the merged M7 PRs #169,
#171, #174, #181. Every claim is linked to one of them — full GitHub URLs for
issues, PRs and comments; relative links for files here.

Links added (the page is not restated anywhere, only pointed at):

• docs/introduction.md — a new item 5 in "Read in this order", and a
  closing sentence in "What it has done".
• docs/first-milestone.md — rung 3 of the ladder, which named Document orchestration-platform interop (the ladder's last rung) #54 as the
  doc yet to be written; now names the page, and Cycle 4 of the orchestrator run: radiusred/snake on the coordinator seat, then seat-routed routines #164 beside End to end under an orchestrator: prove the flow driven by Paperclip (or another platform) #119.
• README.md — the orchestrator receipt (updated to include cycle 4 and the
  sixty-eight findings) links the page; the interop doc leaves "things we
  have not done yet", replaced by the onboarding script that genuinely does
  not exist; a "Read next" row.
• SPEC.md §9 — the orchestrated-company bullet ended "are Document orchestration-platform interop (the ladder's last rung) #54's"; it now
  points at the page, which names the open seams itself.
• CHANGELOG.md — one [Unreleased] entry, ending (M7-R7, #54, #182).

What was not invented. No cost figure is recomputed, averaged or
extrapolated — the two tables are reproduced verbatim and are not merged,
because #119 counts "non-gate touches" while #164 splits onboarding from
workflow. No secret, agent id, company id or receiver URL appears; the
Paperclip recipe carries placeholders, as docs/extensions.md does. The page
does not claim roles/coordinator.md has been exercised on a platform:
cycle 4 ran on a hand-written brief and the contract shipped afterwards
(#169) — that is stated as a gap. The other gaps named rather than smoothed
over: no onboarding script or plugin ships (and init --platform was
deliberately dropped, #174); the scaffold still costs the operator one merge
where a ruleset makes it a PR; wake coalescing is the platform's missing
half; one platform quirk was never diagnosed; the platform's tickets are not
committed as transcripts; and cycle 1's coordinator share was never measured.

Rebased on main after PR #184 (#183) merged. init now commits the
scaffold it wrote, which closed #172, so the gap entry that named it was
rewritten in 780d716: what narrowed (the scaffold is a commit, not a PR
with no task behind it; delete-on-merge sweeps the branch finding 68 found
stranded) and what did not (behind a ruleset the scaffold PR is still the
one merge the operator does by hand, recorded as the pre-milestone gate on
the scaffold PR itself — #164 finding 52; and on a fresh repository whose org
requires a check that cannot report yet, that hand merge is an administrator
merge). One rebase conflict, in CHANGELOG.md: main's "### The scaffold is a
commit" entry kept first, mine beneath it, both intact. Nothing else in the
page or in the README / introduction / quickstart edits said the scaffold
lands outside the protocol. Recorded as a Deviation on #182.

go test ./... green. Commit subjects measured under 100 characters.

[radiusred-wordy]

Operator tone pass requested (outward-facing copy — the page is read by the Paperclip community): @davison as reviewer; his approval is the tone pass, then the reviewer seat arrives by dispatch. One refresh is queued before that dispatch: PR #184 (init commits the scaffold, #183) is in review and closes the scaffold-PR gap this page names under "What is not solved yet" — the line and the README's "not done yet" sentence will be updated once #184 merges.

[radiusred-checky]

PR #185 review verdict

Verdict: changes requested. Reviewer identity was confirmed as App 4719924 (radiusred-checky), distinct from author radiusred-wordy.

Blocking findings

1. docs/platform-interop.md presents unreleased v1.1.0 behavior as current without saying “next release.” The installed/latest release is v1.0.3, while identity token, identity webhook, the coordinator seat/identity, local-extension scaffolding, dry runs, NOT_OWNER, and init’s scaffold commit are all under [Unreleased] and arrived in merged PRs #169, #171, #174, #176, #179, #181, and #184. Examples include “The verb now does all of that” and “gh codecrew init now commits.” Add an explicit page-level release boundary (or qualify each affected passage) so a v1.0.3 reader is not told these commands and behaviors are installed.

2. Checklist row 2 says identity webhook ... works “for an App already minted.” SPEC §6 and PR #181 say an App minted without an active webhook has no hook configuration and GitHub’s API cannot create one; the verb refuses NO_WEBHOOK and points to Settings. Narrow this to “an App whose hook is already active” and state the settings activation requirement for an App minted without one. The worked example later uses the correct wording.

Evidence audited

Claims checked against the cited record included: findings 7 and 36 (gates bind only when verbs run); findings 1, 15, 16, 20, 26, 29 and 36 (coordinator-seat premise); finding 16’s permission set; findings 2, 12 and 35 (credential names, 401 recovery, stale installation hint); findings 38–41 (wake types, mentions, deadlocks, layered instructions); findings 44, 46 and 48 (one-shot events, duplicate wakes, stale single-flight); finding 50 (handoff); findings 53–55 and 59–65 (duplicate paths, user-level routine provisioning, health check, ping 422, payload path, Project first, seat-specific handbacks, dispatch plane); and findings 67–68 (named tooling and bootstrap branch). The cycles 1–3 and cycle-4 cost tables, totals, shares, touch counts, runs/PR, and wall times match #119 entry 18 and #164 entry 2 exactly.

The “not solved yet” list was compared with #54’s inventory and #164’s fold-back map. It does not mislabel merged fixes #169, #171, #174, #176, #179, #181, or #184 as open; its remaining gaps are supported by the record.

All 169 Markdown links in the six changed files were extracted. Relative targets exist, and all changed GitHub issue, comment-anchor, PR, and repository targets resolved through the API. go test ./... passed, including the docs scan. The local build reports dev; the installed extension and latest GitHub release both report v1.0.3.

[radiusred-wordy]

Both blocking findings addressed in b36685a — thank you, both were fair.

1. Release boundary. The page now carries one "A note on releases" paragraph directly under the opening: the installed release is v1.0.3, and it names the six things below it that ship in v1.1.0, each with its PR — the coordinator seat (roles/coordinator.md, the coordinator routing row, identity new coordinator, #169), identity token (#171), the blank roles/<role>.local.md init scaffolds (#174), task finish refusing NOT_OWNER (#176), identity webhook with --webhook-secret and the narrowed default event set (#181), and init committing the scaffold it wrote (#184). It then says what the v1.0.3 path is for each — the coordination layer briefed by hand, a token minted by a script or in-line, the App's hook worked on its settings page, the scaffold committed by whoever ran init — noting that this is precisely what the run did, at the cost its findings record; and it states plainly that everything else on the page (the routing table, roles show, the workflow verbs, the wake rules and the rest of the checklist) is true of v1.0.3 today.

Rather than sprinkle "next release" through the body, I qualified only the four sentences that asserted current binary behaviour:

• Credentials: "The verb now does all of that" → "From v1.1.0 the verb does all of that … before it, every seat wrote its own JWT helper — which is what the run watched them do, three times, in three dialects."
• Credentials: "Every contract now opens with the mint" → "Every seat contract in this hub now opens with the mint" — that one is about files on main, not the binary, so it is scoped rather than deferred.
• The coordinator seat: "shipped in feat: the coordinator seat — roles/coordinator.md, roles.coordinator, identity new coordinator (#168) #169" → "added in feat: the coordinator seat — roles/coordinator.md, roles.coordinator, identity new coordinator (#168) #169".
• The recipe, step 5: the default event set is now "From v1.1.0 … On v1.0.3 it subscribes five, three of which wake a platform for nothing" — a silent behavioural difference a reader would otherwise get wrong.
• "What is not solved yet": "gh codecrew init now commits" → "From v1.1.0 gh codecrew init commits".

--dry-run and NOT_OWNER are not prescribed anywhere in the body, so nothing else needed deferring; NOT_OWNER is in the note only because step 8 tells the reader the task's own seat runs task finish.

2. Checklist row 2. Narrowed as asked: identity webhook is now for "an App whose hook is already active — an App minted without a webhook has no hook configuration at all, GitHub's API cannot create one, and the verb refuses NO_WEBHOOK naming the settings page where Webhook → Active is ticked by hand first." The worked example's step 5 already said it correctly and is unchanged.

go test ./... green (-count=1); the docs scan finds no bare codecrew <verb> on the page. New head b36685a.

One thing outside this PR's scope, flagged rather than fixed: docs/introduction.md's "What exists" lists identity new/token/webhook and the three --dry-run verbs under "Shipped: v1.0.3", which has the same boundary problem this review caught here. That is M7-R9's "the docs true of the installed binary at the boundary" and belongs to the release task, not to M7-R7 — noting it so it does not fall between the two.

[radiusred-checky]

PR #185 second-round review

Verdict: approve at head b36685a.

Reviewer identity was confirmed as radiusred-checky App 4719924, distinct
from author radiusred-wordy[bot]. The second-round commit resolves both
prior blockers: the page now gives an explicit v1.0.3/v1.1.0 release boundary
and qualifies the behavior-bearing passages, and checklist row 2 now limits
identity webhook to an already-active App hook while accurately describing
the NO_WEBHOOK settings-page path.

The whole PR was rechecked against task #182, capture #54, M7-R7 on #163,
SPEC, the merged M7 PRs, #119, and #164. Sampled claims included findings 7
and 36 (gates bind at verb invocation); finding 16 and the coordinator
permission set; findings 2, 12, and 35 (credential names, 401 recovery, stale
installation hint); findings 38–41 (wake semantics and layered instructions);
findings 44, 46, 48, and 50 (one-shot events, duplicate/stale wakes, handoff);
findings 53–55 and 59–65 (duplicate paths, user-level routine provisioning,
health check, ping 422, payload path, Project-first, handback and dispatch
plane); findings 67–68; both cost tables and their totals/shares/touch counts;
all eleven onboarding rows; and the Paperclip Project, routine, hook, ingress,
overlay, and kickoff steps. The claims matched their linked sources.

The open-gap section matches #54's inventory and #164's fold-back map without
reopening fixes merged in #169, #171, #174, #176, #179, #181, or #184. The
introduction reading order, quickstart ladder, README's 68-finding/four-cycle
receipt, SPEC §9 pointer, and CHANGELOG entry are consistent with the record.

Link audit: 177 Markdown link occurrences (87 unique), no missing relative
targets; 58 GitHub URL targets, including comment anchors, resolved through
the API. go test ./... -count=1 passed locally, and both PR checks passed.