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:

  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

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

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

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

Expected: zero matches.

Step 5: Commit

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

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

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

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

Expected: zero matches.

Step 3: Commit

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

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

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 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

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).