docs(architecture): canonical runtime↔platform↔plugin responsibilities + ADR-003 (guardrail/SSOT) #3255
Reference in New Issue
Block a user
Delete Branch "docs/runtime-platform-plugin-responsibilities"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Why
The 2026-06-25 guardrail audit found the runtime↔platform half of the design — the register/heartbeat status contract (
mcp_server_present+loaded_mcp_tools) that gates online/degraded and broke this session — was tribal knowledge: source-docstring-only, no canonical page, no ADR, and the named contract doc (api-protocol/registry-and-heartbeat.md) was stale ("Five fields", omitted the MCP status fields). A principle that isn't written down + enforced drifts back; this is the documentation half of the guardrail/SSOT goal.What
docs/architecture/runtime-platform-plugin-responsibilities.md— the single canonical statement of the two-layer split (runtime adapts the agent → platform; plugin adapts its abilities → each runtime), with the status-contract field tables, the corollaries (no wrong-layer logic; tool-id SSOTmcp__molecule-platform__create_workspace; platform-ness is a composition, not a baked image), and a guardrail matrix mapping each rule → its red-on-regression test.docs/adr/ADR-003-runtime-platform-plugin-responsibilities.md— the durable committed-architecture anchor (records the principle + the incident that motivated it + the enforcement decision).docs/index.md.docs/api-protocol/registry-and-heartbeat.md— document the platform-agentmcp_server_present+loaded_mcp_toolsfields (tri-state) and the RCA#2970 / core#3082 online↔degraded transitions; the old "five fields" model was incomplete.Docs-only; no code. Lifts cited prose from
plugins/agentskills-compat.md, themcp_render.py/platform_agent_identity.pydocstrings, andrfc-platform-mcp-as-plugin §3.4.Follow-ups (separate PRs, tracked)
The guardrail-matrix rows that aren't green yet — SSOT contract-pin of
loaded_mcp_tools, producer-liveness boot test, renderer/reader lockstep, deterministic online+create_workspacee2e, de-bake absence guard, G3/G4 — land as their own PRs under the guardrail/SSOT workstream.🤖 Generated with Claude Code
Audit (2026-06-25) found the runtime↔platform half of the design — the status contract (mcp_server_present + loaded_mcp_tools) that gates online/degraded and broke this session — was tribal knowledge: source-docstring-only, no canonical page, no ADR, and the named contract doc (registry-and-heartbeat.md) was stale ('Five fields', omitted the MCP status fields). - NEW docs/architecture/runtime-platform-plugin-responsibilities.md: the single canonical statement of the two-layer split (runtime adapts agent→platform; plugin adapts abilities→each runtime), the status-contract field tables, the corollaries (no wrong-layer logic, tool-id SSOT, platform-ness=composition not baked image), and the guardrail matrix. - NEW ADR-003 (durable, CTO-signed anchor). - Link from docs/index.md. - Correct registry-and-heartbeat.md: document the platform-agent mcp_server_present + loaded_mcp_tools fields + the RCA#2970/#3082 transitions. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>Independent 2nd-genuine docs review on current head
38a476499e.Verdict: REQUEST_CHANGES.
The high-level runtime/platform/plugin responsibility split and the mcp_server_present + loaded_mcp_tools status contract are directionally accurate post-runtime#181. The RCA#2970 and core#3082 narratives also match the mechanisms we diagnosed. However, there are accuracy blockers in the new canonical guardrail wording:
docs/architecture/runtime-platform-plugin-responsibilities.md:56-63 and 96-99 overclaim that the required create_workspace tool id is derived everywhere and neither side hardcodes the literal. In current core, workspace-server/internal/handlers/platform_agent.go still defines conciergePlatformMCPCreateWorkspaceTool as the literal "mcp__molecule-platform__create_workspace"; the contract test derives the expected value and catches drift, but the production gate does not literally derive the value from the contract at runtime. Please reword to "pinned by the contract/drift tests" unless/until the production constant is removed.
docs/architecture/runtime-platform-plugin-responsibilities.md:119 names
test_mcp_render_lockstep(set(_RUNTIME_SPECS)==set(_RUNTIME_READERS)) as a guardrail, but I cannot find that test in molecule-core or in the fixed runtime#181 head._RUNTIME_READERSexists, but the named lockstep test does not. This is exactly the kind of enforced-vs-aspirational distinction the review request called out; mark it as a gap/planned test or add the actual guardrail.docs/architecture/runtime-platform-plugin-responsibilities.md:124 says the concierge e2e is deterministic and asserts heartbeat loaded_mcp_tools contains create_workspace, "not LLM self-enumeration". The current staging concierge e2e still prompts the concierge to list MCP tools and parses the reply; the script comments call that LLM-mediated/self-enumeration. It is not a heartbeat-level deterministic assertion yet. Please reword as current behavior, or land the deterministic heartbeat assertion first.
CI note: combined status is not green at review time either: security-review / approved is failing and two E2E Staging SaaS jobs are pending.
Recommended fix shape: keep the canonical docs, but split the matrix into Enforced vs Planned/Gap and correct the create_workspace derivation + e2e wording to match current code/tests.
Requesting changes: the new canonical runtime/platform/plugin responsibilities docs overstate the contract source for the management MCP create_workspace gate.
The PR says the contract field plus required tool id (
mcp__molecule-platform__create_workspace) are pinned incontracts/mcp-plugin-delivery.contract.jsonand that both sides derive from it. Currentmaindoes not support that: the contract pinsruntime_present_fieldandmcp_server_name, but it does not containcreate_workspaceor the full required tool id. Core currently uses the literalconciergePlatformMCPCreateWorkspaceTool = "mcp__molecule-platform__create_workspace"inworkspace-server/internal/handlers/platform_agent.go, and runtime/tests also validate that literal/normalization path rather than deriving the full id from the contract.Please either update the contract/code so the claim is true, or adjust the docs to say the server/status contract is pinned there while the required
create_workspacetool id is a code/test-pinned management-MCP invariant. The rest of the docs I checked align with current behavior:mcp_server_present,loaded_mcp_toolstri-state/omit-when-None, degraded gating, and the RCA#2970/#3082 transitions.REQUEST_CHANGES on fixed head
ba7cb34b: the architecture page and ADR now correctly distinguish current state vs target for themcp__molecule-platform__create_workspacetool id, butdocs/api-protocol/registry-and-heartbeat.mdstill repeats the old overclaim.That file says the required tool id is pinned in
contracts/mcp-plugin-delivery.contract.jsonand derived on both sides. Current code/contract state still does not support that: the contract pins the management server/status fields, while core uses the literalconciergePlatformMCPCreateWorkspaceTooland runtime enumerates the live MCP. Please apply the same current-vs-target wording there as indocs/architecture/runtime-platform-plugin-responsibilities.md.The guardrail matrix status split otherwise looks honest: lockstep, full-tool-id contract derivation, blocking drift, boot producer-liveness, deterministic e2e, and baked-image absence guard are marked target/in-progress; current LLM self-enum e2e is not mislabeled deterministic. CI is also not green at review time: gate-check-v3 is failing and staging E2E contexts are pending.
REQUEST_CHANGES on current head
ba7cb34b3f.Most of the prior overclaims are corrected: the architecture page now honestly marks full tool-id derivation, renderer lockstep, blocking drift, producer-liveness boot coverage, deterministic e2e, and baked-image absence guard as target/in-progress rather than enforced-today; the current e2e is described as LLM self-enumeration with deterministic heartbeat assertion pending; and ADR-003 frames baked-image removal as in progress.
Remaining blocking doc accuracy issue:
mcp__molecule-platform__create_workspaceis "pinned incontracts/mcp-plugin-delivery.contract.jsonand derived on both sides." That is still an overclaim. Current code reality is: core holds the literalconciergePlatformMCPCreateWorkspaceTool = "mcp__molecule-platform__create_workspace"; the contract pins server/status shape, not the full tool id; and full derivation is only the target state. This line should match the corrected language already used indocs/architecture/runtime-platform-plugin-responsibilities.md.5-axis review: correctness is blocked by that stale false claim in the registry contract doc; robustness/security/performance unaffected because this is docs-only; readability is otherwise improved and the guardrail status table now separates enforced from target appropriately.
Verdict: RC until the registry-and-heartbeat.md sentence is corrected to current reality.
APPROVED current head
6fb348821e.Re-reviewed the corrected docs/ADR against the prior RCs and current code/CI reality:
conciergePlatformMCPCreateWorkspaceToolwith a drift test, the contract pins server/status shape only, and full-id contract pinning/derivation is target state.mcp_server_presentplus tri-stateloaded_mcp_tools, with background init enumeration and omit-until-observed semantics.5-axis review: correctness/readability are clean for docs; robustness/security/performance are unaffected by this docs-only change. Required CI is green aside from known review-gate state before this approval / gate-check-v3-only flake.
Verdict: clean for merge after 2-genuine approval and required CI.
APPROVED on current head
6fb34882. The residual overclaim is fixed:docs/api-protocol/registry-and-heartbeat.mdnow says the currentcreate_workspacetool id is a core literal guarded by drift tests, while the contract pins the management server/status-field shape only and full-id derivation is a target. The architecture page and ADR make the same current-vs-target distinction. The guardrail matrix honestly marks enforced-today items versus target/in-progress items; deterministic e2e, lockstep, contract derivation, blocking drift, boot producer-liveness, and baked-image absence guard are not mislabeled as enforced. No stale or contradictory docs claim found in this review pass.