peer-notebook-delivery-guard-2d0095— agent skill

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 (and docs/decisions/archive/adr/staging/ADR-022.json), 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 (and docs/decisions/archive/adr/staging/ADR-022.json)
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.

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:

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.