docs: record P1.1 manual acceptance and plan P2-P6 adaptation
This commit is contained in:
@@ -0,0 +1,228 @@
|
||||
# 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`).
|
||||
Reference in New Issue
Block a user