ThothII/docs/superpowers/plans/2026-08-11-p2-p6-adaptation-to-p1-1-registry.md

# P2–P6 Adaptation to the P1.1 Workspace-Directory Registry — Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to apply this plan task-by-task. This plan only edits documentation (PRD, design, plans, manual verification); it changes no application code.

**Goal:** Bring every P2–P6 planning artifact in line with the P1.1 repository contract (root catalog `thoth-workspaces.yaml`, `<id>/workspace.yaml`, `<id>/evidence`, `<id>/schema/annotations.yaml`, generated docs `workspace-docs/<id>`), so the future P2–P10 implementation starts from the correct layout and identity semantics.

**Architecture:** The P1.1 contract is the single source of truth for registry layout and ownership. P2–P6 documents must stop referencing the retired flat layout (`workspaces/<id>.yaml`, `workspace-content/<id>/evidence`) and must bind preprocessing identity to the catalog+descriptor+evidence objects at one immutable commit.

**Tech Stack:** Markdown (PRD, specs, plans, manual verification). Verification is grep-based plus the existing schema/doc gates.

**Approved design / source of truth:** `docs/superpowers/specs/2026-08-11-p1-1-workspace-directory-registry-design.md` and the P1.1 implementation.

---

## Completion contract

The adaptation is complete when:

1. No active P2–P10 planning artifact (PRD, P2–P6 design, P2 plan, P2–P6 manual verification, and any later P3–P6 plan files created after this adaptation) references `workspace-content/<id>/evidence`, `workspaces/<id>.yaml`, or `workspaces/<workspace-id>/schema/annotations.yaml` as a canonical path.
2. Every reference to the canonical Evidence root uses `<id>/evidence`; every reference to curated FK annotations uses `<id>/schema/annotations.yaml`; every descriptor reference uses `<id>/workspace.yaml`; the catalog is named `thoth-workspaces.yaml`.
3. Identity semantics state that a preprocessing run binds the exact workspace ID, the exact 40-hex commit, the catalog blob, the descriptor blob/digest, and (for filesystem Evidence/annotations) the Git objects at that same commit; a docs-only follow-up commit is a valid new revision even when descriptor/catalog blobs are unchanged.
4. The P1.1 supersession is recorded: P2 depends on P1.1, not on the P1 flat layout; the "active P1 snapshot" language becomes "active P1.1 snapshot" or "active registry snapshot".
5. Historical changelog/revision-history entries that describe the P1-era layout are preserved as history (they are not active contract); a superseded-note is added where a reader could mistake them for current contract.
6. P1/P1.1 docs, design, plans, and accepted evidence are not rewritten by this plan.
7. Grep gates and the existing verifier suites (`bash scripts/test-verify-workspace-install-docs.sh`, `./scripts/verify-workspace-install-docs.sh --fixtures-only`, schema-v3 gates) pass unchanged.

## Explicit decisions frozen by this plan

- Canonical paths after adaptation:

  ```text
  catalog                         thoth-workspaces.yaml
  workspace descriptor            <id>/workspace.yaml
  embedded filesystem Evidence    <id>/evidence
  curated FK annotations (P5)     <id>/schema/annotations.yaml
  generated docs                  workspace-docs/<id>/{contract.env.example,README.md}
  materialized Evidence (P6)      <data>/workspace-registry/snapshots/<commit>/<id>/evidence
  runtime annotation sync (P5)    <data>/sessions/<id>/revisions/<commit>/artifacts/mschema/annotations.yaml
  ```

- "Descriptor identity" in preprocessing language means the catalog entry plus the descriptor blob at one exact commit; the descriptor blob may stay byte-identical across a content-only or docs-only revision, so identity must bind the commit, not the blob alone.
- No application code changes are made by this plan. Any fixture/script path inside `docs/` prose that names old registry files is corrected only in prose.
- Historical P1 evidence (`.artifacts/p1-integration/**`, `.artifacts/manual-acceptance/p1/**`) and P1 acceptance documents remain untouched and are treated as immutable history.

---

### Task 1: Record P1.1 supersession in the PRD

**Files:**
- Modify: `docs/prd/2026-08-09-workspace-preprocessing-prd.md`

**Step 1: Add a supersession notice**

Insert a short status block near the top (after the header/status paragraph) stating that the P1-era layout is superseded by P1.1 (accepted 2026-08-11) and that all canonical paths in this PRD follow the P1.1 contract: `thoth-workspaces.yaml`, `<id>/workspace.yaml`, `<id>/evidence`, `<id>/schema/annotations.yaml`, `workspace-docs/<id>`.

**Step 2: Replace the canonical path references in active requirement/decision/roadmap sections**

Apply the path mapping:

- line ~106-107 (`workspaces/<id>.yaml` + `workspace-content/<id>/evidence/`): `workspaces/<id>.yaml` → `<id>/workspace.yaml`; `workspace-content/<id>/evidence/` → `<id>/evidence/`.
- line ~141 (namespace confinement `workspace-content/<workspace_id>/`): → `<id>/` (a workspace owns its top-level directory).
- line ~175-176 (RF5.1 PSD evidence tree): `workspace-content/psd/evidence/` → `psd/evidence/`; `workspace-content/<workspace_id>/evidence/` → `<id>/evidence/`.
- line ~342-343 (D1): same mapping.
- line ~383 (D6): same mapping.
- roadmap rows P1 (~419) and P6 (~424): update the evidence-path phrases; P1 row may gain a note "P1.1" where it is referenced as the executed predecessor.
- line ~515 (v0.4 changelog): keep as history, add "(historical P1-era path; superseded by P1.1)" inline or leave and rely on the top supersession note — choose the inline parenthetical only if it does not rewrite the revision history content.

Do not touch the preprocessing engine requirements (RF2–RF8) beyond path references.

**Step 3: Verify with grep**

```bash
git grep -n 'workspace-content/' -- docs/prd/2026-08-09-workspace-preprocessing-prd.md
```

Expected: only the historical changelog line(s) (if any kept as history) remain; all active contract lines use the P1.1 paths.

**Step 4: Commit**

```bash
git add docs/prd/2026-08-09-workspace-preprocessing-prd.md
git commit -m "docs: align PRD preprocessing contract with the P1.1 registry"
```

---

### Task 2: Align the P2–P6 design document

**Files:**
- Modify: `docs/superpowers/specs/2026-08-10-p2-p6-workspace-preprocessing-design.md`

**Step 1: Replace the P5 annotation source path**

Line ~172: `workspace-content/<workspace-id>/schema/annotations.yaml` → `<workspace-id>/schema/annotations.yaml`. Verify the surrounding prose still says the registry validates the blob at the same commit and rejects symlinks/trees/submodules; keep the runtime sync target at `/data/sessions/<workspace-id>/revisions/<commit>/artifacts/mschema/annotations.yaml` unchanged.

**Step 2: Replace the P6 materialization source path**

Line ~209: `workspace-content/<id>/evidence` → `<id>/evidence` (from the pinned commit into an immutable revision content root). Keep the materialized target under the snapshot content root and the containment/symlink rules unchanged.

**Step 3: Tighten identity wording**

Wherever the design binds "descriptor snapshot" or "exact descriptor snapshot", add the catalog: preprocessing binds workspace ID, exact 40-hex commit, catalog blob, descriptor blob/digest, and any same-commit Evidence/annotation objects. Add one sentence that a docs-only or content-only commit is still a distinct revision even when the descriptor blob is unchanged (the commit is authoritative).

**Step 4: Verify with grep**

```bash
git grep -n 'workspace-content/' -- docs/superpowers/specs/2026-08-10-p2-p6-workspace-preprocessing-design.md
```

Expected: zero matches.

**Step 5: Commit**

```bash
git add docs/superpowers/specs/2026-08-10-p2-p6-workspace-preprocessing-design.md
git commit -m "docs: align P2-P6 design with the P1.1 registry layout"
```

---

### Task 3: Align the P2 host-CLI plan

**Files:**
- Modify: `docs/superpowers/plans/2026-08-10-p2-host-workspace-preprocessing-cli.md`

**Step 1: Update dependency and identity language**

- Completion contract (~line 22): "descriptor blob/digest" → "catalog blob and descriptor blob/digest"; "active, validated registry snapshot" stays, but ensure it means a P1.1 snapshot.
- State manifest (~lines 143-144): bind "revision, descriptor blob, config SHA-256" → "revision, catalog blob, descriptor blob, config SHA-256".
- Same-revision resume (~line 145): unchanged, but confirm the wording uses commit identity.
- Fixture topology (~line 476): "active P1 snapshot" → "active P1.1 snapshot (root catalog + `<id>/workspace.yaml` + `<id>/evidence`)".

**Step 2: Verify**

```bash
git grep -n 'active P1 snapshot\|workspace-content/\|workspaces/<id>.yaml' -- docs/superpowers/plans/2026-08-10-p2-host-workspace-preprocessing-cli.md
```

Expected: zero matches.

**Step 3: Commit**

```bash
git add docs/superpowers/plans/2026-08-10-p2-host-workspace-preprocessing-cli.md
git commit -m "docs: align the P2 host-CLI plan with the P1.1 registry"
```

---

### Task 4: Align the P2–P6 manual verification document

**Files:**
- Modify: `docs/testing/p2-p6-manual-verification.md`

**Step 1: Update the annotation curation path**

Line ~82: `workspace-content/<id>/schema/annotations.yaml` → `<id>/schema/annotations.yaml`. Scan the rest of the file for any other old-layout examples (evidence paths, flat descriptor names, "P1 snapshot" phrasing) and apply the mapping.

**Step 2: Verify**

```bash
git grep -n 'workspace-content/\|workspaces/<id>.yaml\|active P1 snapshot' -- docs/testing/p2-p6-manual-verification.md
```

Expected: zero matches.

**Step 3: Commit**

```bash
git add docs/testing/p2-p6-manual-verification.md
git commit -m "docs: align P2-P6 manual verification with the P1.1 registry"
```

---

### Task 5: Final grep gate and consistency sweep

**Files:**
- None modified (verification only), or minimal edits if the sweep finds a straggler in the four P2–P6 artifacts.

**Step 1: Grep the whole P2–P6 surface for retired paths**

```bash
git grep -n 'workspace-content/' -- docs/prd docs/superpowers/specs docs/superpowers/plans docs/testing
git grep -n 'workspaces/<id>.yaml' -- docs/prd docs/superpowers/specs docs/superpowers/plans docs/testing
```

Expected: no matches in active P2–P6 contract text. Allowed exceptions: the PRD historical changelog line (if deliberately retained with a historical note) and any P1-era historical plans that are explicitly marked superseded.

**Step 2: Confirm new canonical paths appear where expected**

```bash
git grep -n '<id>/evidence\|thoth-workspaces.yaml' -- docs/superpowers/specs/2026-08-10-p2-p6-workspace-preprocessing-design.md docs/superpowers/plans/2026-08-10-p2-host-workspace-preprocessing-cli.md docs/testing/p2-p6-manual-verification.md
```

Expected: matches in each file where the layout is described.

**Step 3: Run the existing gates**

```bash
bash scripts/test-verify-workspace-install-docs.sh
./scripts/verify-workspace-install-docs.sh --fixtures-only
bash scripts/test-verify-schema-v3-only.sh
./scripts/verify-schema-v3-only.sh
```

Expected: PASS (this plan touches docs only; the gates must not regress).

**Step 4: Commit any stragglers**

```bash
git add docs
git commit -m "docs: finish P2-P6 path adaptation sweep"
```

(Only if Task 5 changed files; otherwise skip.)

---

## Owner checkpoint

After Task 5 the adaptation is complete and the implementation session stops for the final recap (step 8 of the owner sequence). The next owner action is to authorize the P2 implementation against the updated P1.1-based documents, then proceed with P2 (and later P3–P10) using the new canonical paths.

## Non-goals

- No change to preprocessing engine code, fixtures under `deploy/`, scripts, or the registry implementation.
- No change to P1/P1.1 design, plans, PROJECT_STATE acceptance blocks, or retained evidence.
- No migration of real repository content (that remains a curator operation documented in `docs/migrations/p1-to-p1-1-registry-layout.md`).