# v1.28 L2 Governance Plane Closure And Backend Alignment Seed Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Lock `v1.28` as a real implementation milestone by consolidating the `L2` governance-plane docs, defining consultation output symmetry, and formalizing paired-backend drift/rebuild semantics without prematurely claiming seeded graph activation.

**Architecture:** Treat `v1.28` as a documentation-and-contract milestone with regression tests. First import the missing governance-plane consolidation spec and anchor the top-level architecture docs on it, then tighten `L2` consultation semantics and paired-backend maintenance rules, and finally close the milestone with explicit Lean-reserve and non-goal language so later graph work starts from one stable contract.

**Tech Stack:** Markdown protocol docs, Python `unittest`, `pytest`, existing `research/knowledge-hub/tests` doc-contract regressions

---

## Scope Guard

This plan implements only `v1.28 L2 Governance Plane Closure And Backend Alignment Seed`.

It does **not** implement:

- seeded `L2` graph data,
- `physical_picture` canonical activation,
- graph traversal,
- progressive-disclosure retrieval over populated `L2`,
- collaborator-memory persistence,
- or `L5 Publication Factory`.

## File Structure

### New files

- `docs/superpowers/specs/2026-04-08-l2-governance-plane-consolidation-design.md`
  - imported and versioned design target for `v1.28`
- `research/knowledge-hub/canonical/L2_PAIRED_BACKEND_MAINTENANCE_PROTOCOL.md`
  - explicit audit / rebuild / backend-debt maintenance contract for paired backends
- `research/knowledge-hub/tests/test_l2_governance_docs.py`
  - focused regression coverage for `v1.28` doc semantics

### Existing files to modify

- `docs/AITP_UNIFIED_RESEARCH_ARCHITECTURE.md`
  - align the architecture doc with the new `L2` governance-plane target and cross-link the maintenance/consultation surfaces
- `research/knowledge-hub/L2_CONSULTATION_PROTOCOL.md`
  - define human-facing versus AI-facing consultation outputs and keep consultation separate from promotion
- `research/knowledge-hub/canonical/L2_BACKEND_BRIDGE.md`
  - describe paired-backend maintenance as an explicit internal `L2` operation rather than only a bridge metaphor
- `research/knowledge-hub/canonical/L2_BACKEND_INTEGRATION_PROTOCOL.md`
  - cross-link the maintenance protocol and clarify that pairing requires drift audit plus rebuild semantics
- `research/knowledge-hub/canonical/README.md`
  - link the new maintenance protocol and governance-plane consolidation doc
- `research/knowledge-hub/README.md`
  - surface the new `v1.28` governance docs in the kernel overview
- `research/knowledge-hub/canonical/backends/THEORETICAL_PHYSICS_PAIRED_BACKEND_CONTRACT.md`
  - add explicit maintenance operation language
- `research/knowledge-hub/canonical/backends/THEORETICAL_PHYSICS_BACKEND_PAIRING.md`
  - add explicit drift-audit / rebuild consequences for the pair
- `research/knowledge-hub/tests/test_theoretical_physics_backend_pairing.py`
  - extend doc regression coverage for maintenance semantics

## Task 1: Import The Governance-Plane Consolidation Target

**Files:**
- Create: `docs/superpowers/specs/2026-04-08-l2-governance-plane-consolidation-design.md`
- Modify: `docs/AITP_UNIFIED_RESEARCH_ARCHITECTURE.md`
- Modify: `research/knowledge-hub/tests/test_l2_governance_docs.py`

- [ ] **Step 1: Write the failing governance-doc regression**

```python
from __future__ import annotations

import unittest
from pathlib import Path


class L2GovernanceDocsTests(unittest.TestCase):
    def setUp(self) -> None:
        self.repo_root = Path(__file__).resolve().parents[2]
        self.kernel_root = Path(__file__).resolve().parents[1]

    def test_governance_plane_spec_exists_and_architecture_points_to_it(self) -> None:
        spec_path = (
            self.repo_root
            / "docs"
            / "superpowers"
            / "specs"
            / "2026-04-08-l2-governance-plane-consolidation-design.md"
        )
        architecture = (self.repo_root / "docs" / "AITP_UNIFIED_RESEARCH_ARCHITECTURE.md").read_text(
            encoding="utf-8"
        )

        self.assertTrue(spec_path.exists())
        spec_text = spec_path.read_text(encoding="utf-8")
        self.assertIn("L2 Governance Plane Consolidation Design", spec_text)
        self.assertIn("governance plane", architecture)
        self.assertIn("paired downstream realizations", architecture)
        self.assertIn("consultation outputs", architecture)
```

- [ ] **Step 2: Run the new doc regression to verify it fails**

Run: `python -m pytest research/knowledge-hub/tests/test_l2_governance_docs.py -q`

Expected: FAIL because the `2026-04-08-l2-governance-plane-consolidation-design.md` spec file does not exist yet in this worktree.

- [ ] **Step 3: Add the consolidation spec and architecture cross-links**

Create `docs/superpowers/specs/2026-04-08-l2-governance-plane-consolidation-design.md` with the approved design content from commit `ebd59cb`, beginning with:

```md
# AITP L2 Governance Plane Consolidation Design

Status: working design

Date: 2026-04-08

## Goal

Consolidate the current scattered `L2` doctrine into one design-level target for
the AITP `L2` governance plane.
```

In `docs/AITP_UNIFIED_RESEARCH_ARCHITECTURE.md`, extend the `Plane B: L2 governance plane`
section and later architecture sections with language like:

```md
This governance plane is further consolidated by:

- `docs/superpowers/specs/2026-04-08-l2-governance-plane-consolidation-design.md`
- `research/knowledge-hub/L2_CONSULTATION_PROTOCOL.md`
- `research/knowledge-hub/canonical/L2_PAIRED_BACKEND_MAINTENANCE_PROTOCOL.md`

The consultation outputs that humans and agents consume must be derived from the
same promoted identity even when their renderings differ.
```

- [ ] **Step 4: Run the targeted doc regression to verify the import passes**

Run: `python -m pytest research/knowledge-hub/tests/test_l2_governance_docs.py -q`

Expected: PASS

- [ ] **Step 5: Commit**

```bash
git add docs/superpowers/specs/2026-04-08-l2-governance-plane-consolidation-design.md docs/AITP_UNIFIED_RESEARCH_ARCHITECTURE.md research/knowledge-hub/tests/test_l2_governance_docs.py
git commit -m "docs: add v1.28 l2 governance plane target"
```

## Task 2: Lock Consultation Output Symmetry

**Files:**
- Modify: `research/knowledge-hub/L2_CONSULTATION_PROTOCOL.md`
- Modify: `research/knowledge-hub/README.md`
- Test: `research/knowledge-hub/tests/test_l2_governance_docs.py`

- [ ] **Step 1: Extend the failing regression with consultation-output expectations**

Append this test method to `research/knowledge-hub/tests/test_l2_governance_docs.py`:

```python
    def test_consultation_protocol_defines_human_and_ai_output_surfaces(self) -> None:
        consultation = (self.kernel_root / "L2_CONSULTATION_PROTOCOL.md").read_text(encoding="utf-8")

        self.assertIn("Human-facing consultation outputs", consultation)
        self.assertIn("AI-facing consultation outputs", consultation)
        self.assertIn("derived from the same promoted identity", consultation)
        self.assertIn("Consultation is not promotion", consultation)
```

- [ ] **Step 2: Run the consultation regression to verify it fails**

Run: `python -m pytest research/knowledge-hub/tests/test_l2_governance_docs.py::L2GovernanceDocsTests::test_consultation_protocol_defines_human_and_ai_output_surfaces -q`

Expected: FAIL because the current protocol does not yet define both output surfaces explicitly.

- [ ] **Step 3: Update the consultation protocol and kernel README**

In `research/knowledge-hub/L2_CONSULTATION_PROTOCOL.md`, add a new section after the lifecycle rules:

```md
## 6.1 Human-facing consultation outputs

Human-facing consultation outputs are operator-readable derived surfaces such as:
- consultation receipts,
- compact memory maps,
- warning-focused summary cards,
- and review packets that explain what was surfaced and what was actually applied.

These outputs must preserve:
- canonical unit ids,
- assumptions,
- regime and scope limits,
- provenance pointers,
- and warning surfaces.

## 6.2 AI-facing consultation outputs

AI-facing consultation outputs are compact machine-primary packets.
They must surface:
- selected canonical unit ids,
- why they were selected,
- the edge neighborhood or profile that shaped retrieval,
- unresolved conflicts,
- and exact pointers for deeper follow-up.

## 6.3 Symmetry rule

Human-facing and AI-facing consultation outputs are derived from the same
promoted identity.
They may differ in rendering, but they may not silently disagree about trust,
scope, assumptions, or unresolved boundaries.
```

Also add to `research/knowledge-hub/README.md` under the protocol list:

```md
- `L2_CONSULTATION_PROTOCOL.md`
  - includes the human-facing versus AI-facing consultation output contract
```

- [ ] **Step 4: Run the updated consultation regression**

Run: `python -m pytest research/knowledge-hub/tests/test_l2_governance_docs.py::L2GovernanceDocsTests::test_consultation_protocol_defines_human_and_ai_output_surfaces -q`

Expected: PASS

- [ ] **Step 5: Commit**

```bash
git add research/knowledge-hub/L2_CONSULTATION_PROTOCOL.md research/knowledge-hub/README.md research/knowledge-hub/tests/test_l2_governance_docs.py
git commit -m "docs: lock l2 consultation output symmetry"
```

## Task 3: Formalize Paired-Backend Drift Audit And Rebuild

**Files:**
- Create: `research/knowledge-hub/canonical/L2_PAIRED_BACKEND_MAINTENANCE_PROTOCOL.md`
- Modify: `research/knowledge-hub/canonical/L2_BACKEND_BRIDGE.md`
- Modify: `research/knowledge-hub/canonical/L2_BACKEND_INTEGRATION_PROTOCOL.md`
- Modify: `research/knowledge-hub/canonical/backends/THEORETICAL_PHYSICS_PAIRED_BACKEND_CONTRACT.md`
- Modify: `research/knowledge-hub/canonical/backends/THEORETICAL_PHYSICS_BACKEND_PAIRING.md`
- Modify: `research/knowledge-hub/canonical/README.md`
- Test: `research/knowledge-hub/tests/test_theoretical_physics_backend_pairing.py`
- Test: `research/knowledge-hub/tests/test_l2_governance_docs.py`

- [ ] **Step 1: Write the failing maintenance regressions**

Append this method to `research/knowledge-hub/tests/test_l2_governance_docs.py`:

```python
    def test_paired_backend_maintenance_protocol_is_present(self) -> None:
        maintenance = (
            self.kernel_root / "canonical" / "L2_PAIRED_BACKEND_MAINTENANCE_PROTOCOL.md"
        )
        self.assertTrue(maintenance.exists())
        text = maintenance.read_text(encoding="utf-8")
        self.assertIn("backend debt", text)
        self.assertIn("drift audit", text)
        self.assertIn("rebuild", text)
```

Append this method to `research/knowledge-hub/tests/test_theoretical_physics_backend_pairing.py`:

```python
    def test_pairing_contract_references_maintenance_protocol(self) -> None:
        contract = (
            self.backends_root / "THEORETICAL_PHYSICS_PAIRED_BACKEND_CONTRACT.md"
        ).read_text(encoding="utf-8")
        pairing = (
            self.backends_root / "THEORETICAL_PHYSICS_BACKEND_PAIRING.md"
        ).read_text(encoding="utf-8")

        self.assertIn("L2_PAIRED_BACKEND_MAINTENANCE_PROTOCOL.md", contract)
        self.assertIn("drift audit", contract)
        self.assertIn("rebuild", contract)
        self.assertIn("L2_PAIRED_BACKEND_MAINTENANCE_PROTOCOL.md", pairing)
```

- [ ] **Step 2: Run the maintenance regressions to verify they fail**

Run: `python -m pytest research/knowledge-hub/tests/test_l2_governance_docs.py research/knowledge-hub/tests/test_theoretical_physics_backend_pairing.py -q`

Expected: FAIL because the maintenance protocol does not exist yet and the paired-backend docs do not reference it.

- [ ] **Step 3: Add the maintenance protocol and update backend docs**

Create `research/knowledge-hub/canonical/L2_PAIRED_BACKEND_MAINTENANCE_PROTOCOL.md` with:

```md
# L2 Paired Backend Maintenance Protocol

This file defines the maintenance operation for paired downstream backends.

It exists so that paired backends do not remain only a conceptual promise.

## Required operations

1. drift audit
2. backend-debt recording
3. bounded rebuild or resynchronization
4. post-rebuild verification
```

And continue with explicit rules for:

- what counts as blocking versus non-blocking backend debt,
- when rebuild is allowed to be one-sided,
- how to record honest reductions,
- and how maintenance stays downstream of `L2` canonical identity.

Update these files to cross-link and apply the maintenance rule:

```md
research/knowledge-hub/canonical/L2_BACKEND_BRIDGE.md
research/knowledge-hub/canonical/L2_BACKEND_INTEGRATION_PROTOCOL.md
research/knowledge-hub/canonical/backends/THEORETICAL_PHYSICS_PAIRED_BACKEND_CONTRACT.md
research/knowledge-hub/canonical/backends/THEORETICAL_PHYSICS_BACKEND_PAIRING.md
research/knowledge-hub/canonical/README.md
```

Each should mention that paired-backend drift is handled through explicit
maintenance, not by silently treating one side as authoritative by format.

- [ ] **Step 4: Run the backend-maintenance regressions**

Run: `python -m pytest research/knowledge-hub/tests/test_l2_governance_docs.py research/knowledge-hub/tests/test_theoretical_physics_backend_pairing.py -q`

Expected: PASS

- [ ] **Step 5: Commit**

```bash
git add research/knowledge-hub/canonical/L2_PAIRED_BACKEND_MAINTENANCE_PROTOCOL.md research/knowledge-hub/canonical/L2_BACKEND_BRIDGE.md research/knowledge-hub/canonical/L2_BACKEND_INTEGRATION_PROTOCOL.md research/knowledge-hub/canonical/backends/THEORETICAL_PHYSICS_PAIRED_BACKEND_CONTRACT.md research/knowledge-hub/canonical/backends/THEORETICAL_PHYSICS_BACKEND_PAIRING.md research/knowledge-hub/canonical/README.md research/knowledge-hub/tests/test_theoretical_physics_backend_pairing.py research/knowledge-hub/tests/test_l2_governance_docs.py
git commit -m "docs: formalize paired backend maintenance semantics"
```

## Task 4: Close Lean Reserve And v1.28 Non-Goals

**Files:**
- Modify: `docs/AITP_UNIFIED_RESEARCH_ARCHITECTURE.md`
- Modify: `research/knowledge-hub/canonical/README.md`
- Test: `research/knowledge-hub/tests/test_l2_governance_docs.py`

- [ ] **Step 1: Add the failing Lean-boundary regression**

Append this method to `research/knowledge-hub/tests/test_l2_governance_docs.py`:

```python
    def test_governance_docs_lock_lean_reserve_and_v128_non_goals(self) -> None:
        architecture = (self.repo_root / "docs" / "AITP_UNIFIED_RESEARCH_ARCHITECTURE.md").read_text(
            encoding="utf-8"
        )
        canonical_readme = (self.kernel_root / "canonical" / "README.md").read_text(encoding="utf-8")

        self.assertIn("Lean", architecture)
        self.assertIn("downstream export path", architecture)
        self.assertIn("not the definition of `L2` success", architecture)
        self.assertIn("L2_PAIRED_BACKEND_MAINTENANCE_PROTOCOL.md", canonical_readme)
        self.assertIn("L2_MVP_CONTRACT.md", canonical_readme)
```

- [ ] **Step 2: Run the Lean-boundary regression to verify current gaps**

Run: `python -m pytest research/knowledge-hub/tests/test_l2_governance_docs.py::L2GovernanceDocsTests::test_governance_docs_lock_lean_reserve_and_v128_non_goals -q`

Expected: FAIL if the architecture doc and canonical README do not yet lock the final `v1.28` boundary strongly enough.

- [ ] **Step 3: Update the architecture and canonical README**

Add explicit Lean reserve language in `docs/AITP_UNIFIED_RESEARCH_ARCHITECTURE.md`:

```md
Lean remains a downstream export path.
It is not the definition of `L2` success, and `v1.28` does not activate
Lean-specific object-family requirements ahead of seeded graph work.
```

Add to `research/knowledge-hub/canonical/README.md`:

```md
- `L2_PAIRED_BACKEND_MAINTENANCE_PROTOCOL.md`
- `docs/superpowers/specs/2026-04-08-l2-governance-plane-consolidation-design.md`

Current `v1.28` scope stops at governance-plane closure and paired-backend
maintenance semantics.
Graph activation, traversal, and populated retrieval remain later work.
```

- [ ] **Step 4: Run the final targeted doc regressions**

Run: `python -m pytest research/knowledge-hub/tests/test_l2_governance_docs.py research/knowledge-hub/tests/test_theoretical_physics_backend_pairing.py research/knowledge-hub/tests/test_l2_backend_contracts.py -q`

Expected: PASS

- [ ] **Step 5: Commit**

```bash
git add docs/AITP_UNIFIED_RESEARCH_ARCHITECTURE.md research/knowledge-hub/canonical/README.md research/knowledge-hub/tests/test_l2_governance_docs.py
git commit -m "docs: close v1.28 lean reserve and scope guard"
```

## Final Verification

- [ ] **Step 1: Run the full v1.28 doc-contract regression set**

Run: `python -m pytest research/knowledge-hub/tests/test_l2_governance_docs.py research/knowledge-hub/tests/test_theoretical_physics_backend_pairing.py research/knowledge-hub/tests/test_l2_backend_contracts.py research/knowledge-hub/tests/test_aitp_service.py -q`

Expected: PASS

- [ ] **Step 2: Perform a theoretical-physicist-perspective review**

Check these questions explicitly:

```text
1. Does the new contract make AITP more honest about where reusable physics knowledge lives?
2. Does it clarify what a human physicist sees versus what the agent sees during consultation?
3. Does it prevent the typed backend from silently becoming fake authority?
4. Does it keep `v1.28` from overclaiming graph maturity that has not been implemented?
```

- [ ] **Step 3: Commit final integrated closure**

```bash
git add docs/superpowers/plans/2026-04-08-v1.28-l2-governance-plane-closure.md
git commit -m "docs: add v1.28 governance-plane implementation plan"
```
