peer-notebook-delivery-guard

Guard MCP peer notebook delivery for: $ARGUMENTS

Purpose

This skill is the delivery guardrail for ADR-022. It keeps large implementation units aligned with the brokered peer notebook end state:

• governed peer identities
• approved manifests
• brokered inbound invocation
• broker-proxied outbound access
• durable invocations, traces, and artifacts
• web-app inspection
• real runtime providers behind explicit contracts

Use this skill whenever work touches .specs/mcp-peer-notebooks/, .specs/mcp-peer-notebooks/SPEC-CONTROL-PLANE.md, src/peer-notebook/, peer notebook Supabase migrations, peer notebook web app routes, or runtime providers.

Required Reads

Read these before planning or editing:

1. AGENTS.md
2. .specs/mcp-peer-notebooks/SPEC-CONTROL-PLANE.md
3. .specs/mcp-peer-notebooks/SPEC-CONTROL-PLANE.md
4. .specs/mcp-peer-notebooks/README.md
5. .specs/mcp-peer-notebooks/NEXT-IMPLEMENTATION-HANDOFF.md

If the work touches app UI, also read apps/web/AGENTS.md.

Hard Rule

Mocks are contract fixtures, not final substitutes.

A mock, in-memory store, stubbed provider, fake broker target, or local-only stand-in may prove shape, schema, trace semantics, and client reachability. It does not satisfy the production requirement for the capability it represents.

Before any unit is complete, every mocked or in-memory component touched must be either:

1. replaced by a real implementation behind the same contract,
2. narrowed to test-only/non-production use by code and docs, or
3. explicitly deferred in the user-selected tracker or handoff artifact with the real replacement named.

If a mock fulfills the function of the thing it mocks in a final acceptance claim, the unit is not complete.

Large Unit Boundaries

Pick exactly one primary unit unless the user explicitly asks for a larger combined effort.

Unit	Capability Produced	Explicit Non-Goals
Durable Control Plane	Supabase-backed peers, manifests, invocations, traces, and artifacts while runtime remains mock-capable	Web app pages, real runtime isolation
Manifest Lifecycle And Notebook Graduation	Compile peer.manifest.json from real notebook source, store drafts, approve/activate/retire manifests	Runtime provider expansion, UI beyond minimal admin/read APIs
Web App Inspection Surface	Peer registry/detail, invocation list/detail, trace timeline, artifact preview from durable rows	New runtime providers, migration redesign
Real Runtime Provider Path	local-process integration provider behind runtime contract, marked development-only	Production isolation claims
Production Isolation And Policy Hardening	Isolated execution provider, enforced network/filesystem/secrets/budget policy, adversarial acceptance	Treating local-process or mock as production

If work crosses a unit boundary, stop and record/link follow-up work in the user-selected tracker or handoff artifact before proceeding.

Workflow

1. Classify The Unit

Write a short classification before editing:

Unit:
ADR claims advanced:
Spec sections touched:
Production capability expected:
Mocks/in-memory components involved:
Explicit non-goals:
Tracker/handoff reference:

If there is no tracker reference and tracker writes are in scope, create or request one. If tracker writes are unavailable, record the gap in the handoff and do not create a fallback tracker.

2. Define Acceptance Before Code

Every unit must have observable acceptance criteria before implementation:

• positive path
• negative path
• workspace scoping path where relevant
• trace/artifact/read-model evidence where relevant
• mock accountability outcome

Acceptance must name concrete files, rows, API responses, UI states, or tests. Avoid acceptance phrased only as "implemented support for X."

3. Mock Accountability Gate

Before code review or completion, produce this table:

Component	Real Capability It Stands In For	Current Scope	Replaced/Narrowed/Deferred	Tracker/Handoff Follow-Up
MockPeerRuntimeProvider	Runtime execution provider	test/pilot	deferred	thoughtbox-...

Rules:

• Current Scope must be test-only, pilot-only, development-only, or production.
• production is allowed only for real implementations.
• If Deferred, the follow-up issue is mandatory.
• If the unit claims final acceptance for a capability, the corresponding row cannot be mock, in-memory, or stub.

4. Unit Failure-Mode Gates

Apply only the gate for the active unit.

Durable Control Plane

Reject the unit if:

• schema names drift from SPEC-CONTROL-PLANE.md without a spec update
• workspace scoping is not tested
• in-memory repository remains the only implementation
• trace or artifact writes can partially succeed without visible status/error
• durable seed -> invoke -> trace -> artifact flow is untested

Required evidence:

• migration files
• repository contract tests against Supabase-shaped storage
• verification query or test proving invocation, trace, and artifact rows exist

Manifest Lifecycle And Notebook Graduation

Reject the unit if:

• compiling a manifest executes notebook code
• draft manifests can be invoked
• notebook edits silently change active capabilities
• manifest hash is unstable across equivalent JSON
• approval/activation can be bypassed

Required evidence:

• malformed JSON, duplicate manifest, draft, active, retired, and expansion denial tests
• active manifest hash asserted during invocation

Web App Inspection Surface

Reject the unit if:

• UI reads mock/local state instead of durable rows
• denied calls are hidden
• artifact previews fetch unbounded full payloads
• workspace filtering is not represented in query tests or fixtures
• src/observatory becomes a deployed dependency

Required evidence:

• browser or component tests for peer detail, invocation detail, denied event, and artifact preview states

Real Runtime Provider Path

Reject the unit if:

• local-process is described as production isolation
• provider behavior diverges from mock contract tests
• runtime can bypass broker proxy for Thoughtbox/MCP calls
• runtime writes final artifacts outside broker-owned artifact paths
• timeout/cancel/failure transitions are ambiguous

Required evidence:

• shared provider contract tests
• explicit development-only labeling for local-process
• queued -> running -> terminal status tests

Production Isolation And Policy Hardening

Reject the unit if:

• Cloud Run becomes the privileged execution host
• network, filesystem, secrets, or outbound tool policy is doc-only
• budget counters are not enforced and traceable
• denied outbound calls can reach the target
• mock or local-process satisfies production isolation acceptance

Required evidence:

• adversarial tests for denied network/tool/filesystem/secrets access
• isolated provider end-to-end acceptance
• persisted budget and denial trace events

5. Implementation Discipline

• Preserve broker/repository/runtime contracts unless the ADR/spec changes.
• Add real implementations beside mocks; do not mutate mocks into production implementations.
• Keep deferred surfaces deferred unless this unit explicitly owns them.
• Update .specs/ and ADR artifacts in the same commit as behavior changes.
• Do not touch unrelated dirty files.

6. Completion Report

End with:

Peer Notebook Delivery Guard Report

Unit:
Tracker/handoff reference:
ADR/spec alignment:
Mocks touched:
Mock accountability:
Acceptance evidence:
Tests run:
Deferred issues filed:
Known risks:
Ready for PR/merge: yes|no

If Ready for PR/merge is yes, there must be no untracked mock replacement work hidden in prose.