docs: one owner per question, and a contract that lives with its code - #1026
Merged
Conversation
An audit of the planning layers found the code healthy and the coordination layer not: a frozen contract that had drifted from its own types, a decision log that did not contain the shipped architecture, and two documents each claiming top authority. - Promote the AgentGateway v0 contract out of docs/issues/909/ into packages/agent/docs/AGENT_GATEWAY_V0.md, beside the types it describes, and correct it to the shipped shape (input DTOs nest scope rather than inheriting it; listAgents takes ListAgentsInput; JsonSafe and the snapshot state type differ from the frozen text). Code written from the old §6 does not typecheck. - Add Decision 29 (PROPOSED) recording AgentGateway v0, and settle the AgentHost naming collision: createAgentHost is a deployment-static composition helper, not the publication machinery D25-D28 rejected. - Mark Decision 26 SUPERSEDED where it lives, rather than only in DIRECTION. - Banner 909/plan.md as a historical record and 391/plan.md as subordinate to DIRECTION on sequencing; mark the three-tier host topology as future work owned by #905, not shipped architecture. - Document the five planning layers and one-owner-per-question rule in docs/README.md so the next reader routes correctly. Docs only.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation and planning cleanup, from the three-way audit of the vision/decision/sequencing/contract/dispatch layers. Docs only — no code.
The audit's finding: the code is in good shape (§10's acceptance criteria are genuinely met, verified against real tests), but the layer that tells an agent what to do next is not. This fixes that layer.
The rule this establishes
Five kinds of planning document, one owner per kind — why (#391), what-was-ruled (
DECISIONS.md), when (DIRECTION.md), how-it-works (packagedocs/), what-now (beads/issues). A document that answers two of those questions goes stale in one of them without anyone noticing. That is exactly what happened to the gateway contract.Changes
The contract moves to live with its code.
docs/issues/909/plan.md§6 was declared frozen and binding, and had drifted from the shipped types within one release — because it sat in an issue folder nobody updates after the issue closes. It is nowpackages/agent/docs/AGENT_GATEWAY_V0.md, besideshared/gateway/types.ts, corrected to what actually shipped:CreateAgentSessionInput extends AuthorizedAgentScope(+5 more)readonly scopeon all six inputslistAgents(input: AuthorizedAgentScope)listAgents(input: ListAgentsInput)state: PiChatSnapshotstate: JsonSafe<PiChatSnapshot>JsonSafe<T>The 7 methods, 13 error codes and every output DTO match §6 exactly — the drift is contained to inputs. But code written from §6's text does not typecheck, which is a real cost to whoever opens Wave 2.
Decision 29 (PROPOSED, for your ratification). The log ended at 28, so the newest ratified decision described a topology that is still unbuilt while the architecture everything depends on was authorized only by an issue folder. D29 records AgentGateway v0 and settles the
AgentHostnaming collision:createAgentHost()is a deployment-static composition helper returning a gateway and aclose()— not the controller/CAS/registry machinery D25–D28 rejected. Verified:AgentHostProtocolappears in zero source files.Supersession written where the old text lives. Decision 26 still read
Status: Accepted; it now reads SUPERSEDED with a note on what survives (workspaceTypeIdas compatibility metadata).909/plan.mdis bannered as a historical record.391/plan.mdkeeps F-graph authority but is bannered as subordinate to DIRECTION on sequencing — it currently names a public agent selector as a failure condition, which Wave 1 shipped by owner ruling.The host tiers keep their home. The owner-ratified managed/dedicated/pushed topology is marked FUTURE WAVE owned by #905 rather than deleted — it is real intent, it just was not shipped architecture sitting in a "what shipped" document.
Review focus
Decision 29 is the part that needs your judgment, particularly the AgentHost rationale. Everything else is recording what is already true.
Refs #909, #391, #905