# v1.29 L2 Knowledge-Network MVP Activation 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:** Make `L2` start growing for real by seeding one bounded knowledge direction, materializing non-empty `index.jsonl` and `edges.jsonl`, and exposing a minimal profile-guided consultation path that can retrieve useful units.

**Architecture:** Add one focused `l2_graph` helper that owns canonical-unit pathing, schema validation, seed-direction materialization, index rebuilding, and lexical-plus-profile retrieval. Keep the first activation bounded to one real public direction from the repo itself, then expose it through thin `AITPService` and CLI entrypoints instead of wiring it directly into every runtime loop immediately.

**Tech Stack:** Python 3.10+, `unittest`, `pytest`, JSON Schema, existing `canonical/` and `schemas/` surfaces, AITP CLI/service

---

## Scope Guard

This plan activates the first useful internal `L2` graph slice.

It does **not** implement:

- full graph-traversal maturity across all families,
- embedding search,
- automatic promotion from arbitrary topics into canonical `L2`,
- `physical_picture` canonical activation,
- or full runtime-loop integration of consultation retrieval.

## File Structure

### New files

- `research/knowledge-hub/knowledge_hub/l2_graph.py`
  - canonical unit pathing, seed data, index materialization, and MVP consultation retrieval
- `research/knowledge-hub/tests/test_l2_graph_activation.py`
  - focused regressions for seeding, index growth, edge growth, and consultation retrieval
- `research/knowledge-hub/canonical/topic-skill-projections/topic_skill_projection--tfim-benchmark-first-route.json`
  - first seeded reusable execution-memory node in canonical `L2`

### Existing files to modify

- `research/knowledge-hub/knowledge_hub/aitp_service.py`
  - thin public wrappers over `l2_graph` activation and consultation
- `research/knowledge-hub/knowledge_hub/aitp_cli.py`
  - register and dispatch `seed-l2-demo` and `consult-l2`
- `research/knowledge-hub/tests/test_aitp_cli.py`
  - parser and dispatch coverage for the new commands
- `research/knowledge-hub/canonical/index.jsonl`
  - materialized non-empty canonical unit index
- `research/knowledge-hub/canonical/edges.jsonl`
  - materialized non-empty canonical edge layer
- `research/knowledge-hub/canonical/concepts/*.json`
  - seeded concept nodes for the first bounded direction
- `research/knowledge-hub/canonical/methods/*.json`
  - seeded method nodes
- `research/knowledge-hub/canonical/workflows/*.json`
  - seeded workflow nodes
- `research/knowledge-hub/canonical/validation-patterns/*.json`
  - seeded validation-pattern nodes
- `research/knowledge-hub/canonical/warning-notes/*.json`
  - seeded warning nodes
- `research/knowledge-hub/canonical/bridges/*.json`
  - seeded bridge nodes
- `research/knowledge-hub/canonical/claim-cards/*.json`
  - seeded reusable claim nodes
- `research/knowledge-hub/README.md`
  - document the first seeded `L2` direction and the new CLI entrypoints

## Task 1: Add The `l2_graph` Activation Helper

**Files:**
- Create: `research/knowledge-hub/knowledge_hub/l2_graph.py`
- Create: `research/knowledge-hub/tests/test_l2_graph_activation.py`

- [ ] **Step 1: Write the failing activation tests**

```python
from __future__ import annotations

import shutil
import tempfile
import unittest
from pathlib import Path

from knowledge_hub.l2_graph import consult_canonical_l2, seed_l2_demo_direction


class L2GraphActivationTests(unittest.TestCase):
    def setUp(self) -> None:
        self._tmpdir = tempfile.TemporaryDirectory()
        self.kernel_root = Path(self._tmpdir.name)
        source_kernel = Path(__file__).resolve().parents[1]
        shutil.copytree(source_kernel / "canonical", self.kernel_root / "canonical", dirs_exist_ok=True)
        shutil.copytree(source_kernel / "schemas", self.kernel_root / "schemas", dirs_exist_ok=True)

    def tearDown(self) -> None:
        self._tmpdir.cleanup()

    def test_seed_direction_populates_index_and_edges(self) -> None:
        payload = seed_l2_demo_direction(self.kernel_root, direction="tfim-benchmark-first", updated_by="test")
        self.assertGreaterEqual(payload["unit_count"], 8)
        self.assertGreaterEqual(payload["edge_count"], 8)

    def test_profile_guided_consultation_returns_seeded_hits(self) -> None:
        seed_l2_demo_direction(self.kernel_root, direction="tfim-benchmark-first", updated_by="test")
        payload = consult_canonical_l2(
            self.kernel_root,
            query_text="TFIM exact diagonalization benchmark workflow",
            retrieval_profile="l3_candidate_formation",
        )
        ids = {row["id"] for row in payload["primary_hits"]}
        self.assertIn("method:tfim-exact-diagonalization-helper", ids)
        self.assertIn("workflow:tfim-benchmark-workflow", ids)
```

- [ ] **Step 2: Run the new activation tests to verify they fail**

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

Expected: FAIL with `ModuleNotFoundError` for `knowledge_hub.l2_graph`.

- [ ] **Step 3: Implement `l2_graph.py`**

Create:

```python
CANONICAL_DIR_BY_TYPE = {
    "concept": "concepts",
    "claim_card": "claim-cards",
    "method": "methods",
    "workflow": "workflows",
    "topic_skill_projection": "topic-skill-projections",
    "bridge": "bridges",
    "example_card": "examples",
    "validation_pattern": "validation-patterns",
    "warning_note": "warning-notes",
}
```

Implement:

- `seed_l2_demo_direction(kernel_root, direction, updated_by)`
- `materialize_canonical_index(kernel_root)`
- `consult_canonical_l2(kernel_root, query_text, retrieval_profile, max_primary_hits=None)`

Use schema validation against:

- `canonical/canonical-unit.schema.json`
- `schemas/edge.schema.json`

The initial seed direction is:

- `tfim-benchmark-first`

And it must write:

- non-empty unit JSON files
- non-empty `canonical/index.jsonl`
- non-empty `canonical/edges.jsonl`

- [ ] **Step 4: Run the activation tests**

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

Expected: PASS

- [ ] **Step 5: Commit**

```bash
git add research/knowledge-hub/knowledge_hub/l2_graph.py research/knowledge-hub/tests/test_l2_graph_activation.py
git commit -m "feat: add l2 graph activation helper"
```

## Task 2: Expose Seed And Consultation Through Service And CLI

**Files:**
- Modify: `research/knowledge-hub/knowledge_hub/aitp_service.py`
- Modify: `research/knowledge-hub/knowledge_hub/aitp_cli.py`
- Modify: `research/knowledge-hub/tests/test_aitp_cli.py`

- [ ] **Step 1: Add failing CLI coverage**

Append tests like:

```python
    def test_l2_graph_commands_are_registered(self) -> None:
        parser = aitp_cli.build_parser()
        seed_args = parser.parse_args(["seed-l2-demo"])
        consult_args = parser.parse_args(["consult-l2", "--query", "TFIM benchmark workflow"])
        self.assertEqual(seed_args.command, "seed-l2-demo")
        self.assertEqual(consult_args.command, "consult-l2")
```

and:

```python
    def test_main_dispatches_consult_l2(self) -> None:
        with patch.object(aitp_cli, "_service_from_args") as mock_factory:
            mock_service = MagicMock()
            mock_service.consult_l2.return_value = {"primary_hits": []}
            mock_factory.return_value = mock_service
            with patch.object(sys, "argv", ["aitp", "consult-l2", "--query", "TFIM workflow"]):
                exit_code = aitp_cli.main()
        self.assertEqual(exit_code, 0)
        mock_service.consult_l2.assert_called_once()
```

- [ ] **Step 2: Run the CLI tests to verify they fail**

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

Expected: FAIL because the commands are not registered or dispatched yet.

- [ ] **Step 3: Add thin service wrappers and CLI commands**

In `aitp_service.py`, add:

```python
    def seed_l2_demo_direction(self, *, direction: str = "tfim-benchmark-first", updated_by: str = "aitp-cli") -> dict[str, Any]:
        return seed_l2_demo_direction(self.kernel_root, direction=direction, updated_by=updated_by)

    def consult_l2(
        self,
        *,
        query_text: str,
        retrieval_profile: str = "l3_candidate_formation",
        max_primary_hits: int | None = None,
        updated_by: str = "aitp-cli",
    ) -> dict[str, Any]:
        payload = consult_canonical_l2(
            self.kernel_root,
            query_text=query_text,
            retrieval_profile=retrieval_profile,
            max_primary_hits=max_primary_hits,
        )
        payload["updated_by"] = updated_by
        return payload
```

In `aitp_cli.py`, register:

- `seed-l2-demo`
- `consult-l2`

and dispatch them through the new service methods.

- [ ] **Step 4: Run the CLI tests**

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

Expected: PASS

- [ ] **Step 5: Commit**

```bash
git add research/knowledge-hub/knowledge_hub/aitp_service.py research/knowledge-hub/knowledge_hub/aitp_cli.py research/knowledge-hub/tests/test_aitp_cli.py
git commit -m "feat: expose l2 graph activation through aitp cli"
```

## Task 3: Materialize The First Real Seed Direction In The Repo

**Files:**
- Modify: `research/knowledge-hub/canonical/index.jsonl`
- Modify: `research/knowledge-hub/canonical/edges.jsonl`
- Create: `research/knowledge-hub/canonical/concepts/*.json`
- Create: `research/knowledge-hub/canonical/methods/*.json`
- Create: `research/knowledge-hub/canonical/workflows/*.json`
- Create: `research/knowledge-hub/canonical/validation-patterns/*.json`
- Create: `research/knowledge-hub/canonical/warning-notes/*.json`
- Create: `research/knowledge-hub/canonical/bridges/*.json`
- Create: `research/knowledge-hub/canonical/claim-cards/*.json`
- Create: `research/knowledge-hub/canonical/topic-skill-projections/*.json`
- Modify: `research/knowledge-hub/README.md`

- [ ] **Step 1: Generate the seed direction in the actual worktree**

Run:

```bash
python -m knowledge_hub.aitp_cli --kernel-root research/knowledge-hub seed-l2-demo --json
```

Expected:

- seeded TFIM benchmark-first units are written into canonical family folders
- `canonical/index.jsonl` becomes non-empty
- `canonical/edges.jsonl` becomes non-empty

- [ ] **Step 2: Add a readme note for the seed direction**

In `research/knowledge-hub/README.md`, add language like:

```md
The first seeded internal `L2` direction is the public TFIM benchmark-first
code-method route. It provides the initial non-empty `canonical/index.jsonl`,
`canonical/edges.jsonl`, and a bounded set of reusable units for profile-guided
consultation.
```

- [ ] **Step 3: Run the end-to-end activation regressions**

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

Expected: PASS

- [ ] **Step 4: Commit**

```bash
git add research/knowledge-hub/canonical/index.jsonl research/knowledge-hub/canonical/edges.jsonl research/knowledge-hub/canonical/concepts research/knowledge-hub/canonical/methods research/knowledge-hub/canonical/workflows research/knowledge-hub/canonical/validation-patterns research/knowledge-hub/canonical/warning-notes research/knowledge-hub/canonical/bridges research/knowledge-hub/canonical/claim-cards research/knowledge-hub/canonical/topic-skill-projections research/knowledge-hub/README.md
git commit -m "feat: seed first internal l2 knowledge direction"
```

## Final Verification

- [ ] **Step 1: Run the full `v1.29` first-slice regression set**

Run: `python -m pytest research/knowledge-hub/tests/test_l2_graph_activation.py research/knowledge-hub/tests/test_aitp_cli.py 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 explicitly:

```text
1. Does `L2` now contain reusable physics-facing units instead of only empty scaffolding?
2. Can a realistic query retrieve benchmark workflow, method, limitation, and projection memory together?
3. Does the seed remain honest about provenance and scope?
4. Does this improve collaborator usefulness without pretending full graph maturity already exists?
```

- [ ] **Step 3: Commit the plan**

```bash
git add docs/superpowers/plans/2026-04-08-v1.29-l2-knowledge-network-mvp-activation.md
git commit -m "docs: add v1.29 l2 activation plan"
```
