diff --git a/PROJECT_STATE.md b/PROJECT_STATE.md index 4d749ebf..08030c53 100644 --- a/PROJECT_STATE.md +++ b/PROJECT_STATE.md @@ -32,12 +32,13 @@ PowerShell contract were not executed on a Windows host. P1's accepted historical evidence and process artifacts remain untouched; the old P1 process commands are not rerunnable against the superseding P1.1 repository contract. -- **Manual gate:** `.artifacts/manual-acceptance/p11/` is prepared for the reviewer; - follow `docs/testing/p11-manual-acceptance.md`. Project state remains: +- **Manual gate:** `.artifacts/manual-acceptance/p11/` prepared for the reviewer; + follow `docs/testing/p11-manual-acceptance.md`. The owner reviewed the walkthrough and + approved the implementation on 2026-08-11. ```text P1.1 automated integration: PASS -P1.1 manual acceptance: PENDING +P1.1 manual acceptance: PASS (owner approval 2026-08-11) ``` # P1 configuration process — ACCEPTED 2026-08-10 diff --git a/docs/superpowers/plans/2026-08-11-p2-p6-adaptation-to-p1-1-registry.md b/docs/superpowers/plans/2026-08-11-p2-p6-adaptation-to-p1-1-registry.md new file mode 100644 index 00000000..bcb06908 --- /dev/null +++ b/docs/superpowers/plans/2026-08-11-p2-p6-adaptation-to-p1-1-registry.md @@ -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`, `/workspace.yaml`, `/evidence`, `/schema/annotations.yaml`, generated docs `workspace-docs/`), 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/.yaml`, `workspace-content//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//evidence`, `workspaces/.yaml`, or `workspaces//schema/annotations.yaml` as a canonical path. +2. Every reference to the canonical Evidence root uses `/evidence`; every reference to curated FK annotations uses `/schema/annotations.yaml`; every descriptor reference uses `/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 /workspace.yaml + embedded filesystem Evidence /evidence + curated FK annotations (P5) /schema/annotations.yaml + generated docs workspace-docs//{contract.env.example,README.md} + materialized Evidence (P6) /workspace-registry/snapshots///evidence + runtime annotation sync (P5) /sessions//revisions//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`, `/workspace.yaml`, `/evidence`, `/schema/annotations.yaml`, `workspace-docs/`. + +**Step 2: Replace the canonical path references in active requirement/decision/roadmap sections** + +Apply the path mapping: + +- line ~106-107 (`workspaces/.yaml` + `workspace-content//evidence/`): `workspaces/.yaml` → `/workspace.yaml`; `workspace-content//evidence/` → `/evidence/`. +- line ~141 (namespace confinement `workspace-content//`): → `/` (a workspace owns its top-level directory). +- line ~175-176 (RF5.1 PSD evidence tree): `workspace-content/psd/evidence/` → `psd/evidence/`; `workspace-content//evidence/` → `/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//schema/annotations.yaml` → `/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//revisions//artifacts/mschema/annotations.yaml` unchanged. + +**Step 2: Replace the P6 materialization source path** + +Line ~209: `workspace-content//evidence` → `/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 + `/workspace.yaml` + `/evidence`)". + +**Step 2: Verify** + +```bash +git grep -n 'active P1 snapshot\|workspace-content/\|workspaces/.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//schema/annotations.yaml` → `/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/.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/.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 '/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`).