docs: reconcile blueprint/design-doc/CLAUDE.md to shipped v1.2 state

A five-agent roadmap-verification pass found the v1.2 Hierarchies code fully and
correctly implemented, but the three source-of-truth docs carried stale
"deferred/remaining/v1.3" notes — and one self-contradiction — for features that
have since shipped (§3 M3 server-side approval gate, §6 group create/reparent, the
Track A closeout, and the 2026-07-11 audit remediation). Reconcile all three to
reflect the true code; no behavior change.

CLAUDE.md: retract the inline "groups pre-exist" / "per-env approval deferred" /
"shared-topic SSE deferred" / "group dead-letter store deferred" / "email v0/no-AAD"
notes → mark §6, §3 M3, and Track A M1–M6 shipped; add per-group KV/docs byte
quotas + set_if; note migration 0063; refresh the "Out of MVP" section.

design doc: fix the header ("Phases 4–6 remain" → all shipped); resolve the §11.6
self-contradiction (the "Deferred" list still named shared-topic SSE / byte quotas /
set_if / operator admin API, all shipped — line 1317 already said SSE shipped); mark
the D3 dead-letter store shipped; retract the stale "groups pre-exist / §6 deferred"
forward references.

blueprint (comprehensive sweep): dashboard Alpine.js → SvelteKit + CodeMirror
(diagram, §3.3, tech table); Docker-per-execution → embedded in-process Rhai
(diagram + data flow); §12 Phase 4 "current focus" → shipped through v1.1.9; Phase 5
"in active development" + "Remaining" block → Hierarchies complete; per-app RBAC
"v1.3+" → shipped Phase 3.5; SDK reference → handle-pattern notation note, S3 tag
v1.1 → v1.3+; MVP schema + docker-compose flagged non-authoritative; §9 header noted
Hierarchies-shipped / Workflows-future; top status line refreshed.

Also fix two behavior-neutral stale in-code comments (sdk/kv.rs `kv::shared` →
`kv::shared_collection`; dispatcher.rs `q_terminal` "no group dead-letter store yet"
→ dead-letters to group_dead_letters, Track A M2).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
MechaCat02
2026-07-12 14:53:34 +02:00
parent c03c0c83c5
commit c8c4f012ff
5 changed files with 150 additions and 101 deletions

View File

@@ -3,9 +3,13 @@
> **Status:** Active — design discussion captured 2026-06-18, revised 2026-06-20 with resolutions
> grounded in precedent (GitLab, Kustomize, Helm, Terraform, Kubernetes Server-Side Apply, Pulumi)
> and corrected against the codebase after three independent review passes (consistency, gaps,
> feasibility). **Scheduled as the *Hierarchies* track of v1.2** (blueprint §12 Phase 5). §11 Phases
> 13 (project tool, groups + hierarchy RBAC, group-inherited config) are **shipped**; Phases 46
> remain. NB: §11's own Phase 16 numbering is local to this initiative and is **distinct from the
> feasibility). **Scheduled as the *Hierarchies* track of v1.2** (blueprint §12 Phase 5). **§11 Phases
> 16 have all shipped** — project tool, groups + hierarchy RBAC, group-inherited config, group
> scripts/modules + extension points, nested tree apply, §4.5 trigger/route templates, §11.6 shared
> collections, §7 multi-repo ownership, §3 M3 (now server-authoritative) approval gate, §6 group
> create/reparent — plus the Track A closeout and the 2026-07-11 audit remediation. **v1.2 Hierarchies
> is complete;** only multi-node cluster propagation and the separate Workflows track remain. NB: §11's
> own Phase 16 numbering is local to this initiative and is **distinct from the
> blueprint product-phase numbering** — "Phase 3" here = group-inherited config, not the blueprint's
> admin-auth phase.
>
@@ -792,9 +796,10 @@ apps owned by OTHER projects the change fans out to (`group_blast_radius`, a sub
memoized nearest-claimed resolution). The attach ceiling is previewed at plan too (consistent with apply).
Read-only `pic projects ls` lists every project + its owned-group count (`GET /api/v1/admin/projects`,
`list_with_counts`). Pinned by the `apply_ownership` journey's plan-preview case. **With M3, the multi-repo
ownership track (§7 M1M3) is complete. Deferred (separate later work):** §6 structural-divergence detection
(`--adopt-server-structure` / `--force-local-structure`); declarative group create/reparent (lifting "groups
pre-exist"); per-env approval gating (`[project.environments]`).
ownership track (§7 M1M3) is complete.** The items once deferred here have all **since shipped**: §6
structural-divergence detection + declarative group create/reparent (see the §6 M1/M2 blocks below) and
per-env approval gating (`[project.environments]`, now server-authoritative — see §3 M3). Only multi-node
cluster propagation remains deferred.
**§6 group-tree M1 shipped — declarative group CREATE.** A `[group]` node's PARENT is now inferred from
directory nesting (the nearest ancestor directory holding a `[group]`; the topmost group binds to the repo's
@@ -1232,12 +1237,12 @@ Resolved items now live inline next to their topic. What genuinely remains:
> **Status (Phase 5): ✅ shipped — single-repo nested tree apply, atomic.** A directory tree of
> `picloud.toml` manifests (each declaring an `[app]` or `[group]` node) applies as ONE
> server-computed plan in ONE Postgres transaction. Per the §11.1 review, the **multi-repo
> single-owner / attach-point / takeover** layer (§7) is **deferred** for the solo-dev / single-repo
> start, as is **per-env approval-policy gating** (`[project.environments]`); env overlays
> (`picloud.<env>.toml`) already exist. Groups must **pre-exist** (`pic groups create`) — a manifest
> owns each node's *content*, not the tree *shape* (declarative group create/reparent is a later
> add).
> server-computed plan in ONE Postgres transaction. The **multi-repo single-owner / attach-point /
> takeover** layer (§7), **per-env approval-policy gating** (`[project.environments]`), and declarative
> **group create/reparent** were all deferred at Phase 5 and have **since shipped** (§7 M1M3, §3 M3
> server-authoritative, §6 M1/M2). Groups no longer need to pre-exist — a manifest can own the tree
> *shape* as well as each node's *content*. Env overlays (`picloud.<env>.toml`) already existed at
> Phase 5.
>
> Shipped surface:
> - **Engine:** the reconcile engine generalized from app-only to an `ApplyOwner { App | Group }`
@@ -1334,14 +1339,16 @@ Resolved items now live inline next to their topic. What genuinely remains:
> UPDATE SKIP LOCKED` — at-most-once across the subtree, horizontally scaled, each handler under its own
> `cx.app_id`. The dispatcher's queue arm routes claim/ack/nack/terminal to the group store when the
> consumer's source template is a shared queue (`ActiveQueueConsumer.shared_group`). Pinned by
> `tests/group_queue.rs` + `stateful_templates.rs` + the `shared_queues` journey. **Deferred:** a group
> dead-letter store (an exhausted shared-queue message is dropped-with-warning).
> `tests/group_queue.rs` + `stateful_templates.rs` + the `shared_queues` journey. **Group dead-letter
> store shipped** (Track A M2, `group_dead_letters` `0068`): an exhausted shared-queue message is
> preserved (atomic `GroupQueueRepo::dead_letter`) and operator-visible at read-only
> `GET /api/v1/admin/groups/{id}/dead-letters`. Deferred: fan-out to a *shared* dead-letter trigger.
>
> **Deferred (documented gaps):** shared-topic external SSE subscription; per-group total-size quotas +
> write-rate limits;
> CAS/`set_if`; an operator admin API for shared blobs (scripts use the SDK; `pic collections ls` shows
> the marker — matches KV/docs); app-declared collections. Multi-node tree-apply leans on the runtime
> backstop for no-op edges, as elsewhere.
> **Deferred (documented gaps):** per-group write-rate limits; app-declared (as opposed to group-owned)
> collections. The items once listed here — shared-topic external SSE subscription, per-group total-size
> byte quotas, CAS/`set_if`, and the read-only operator admin API for shared blobs — have all **shipped**
> (Track A M4M6 and §11.6 M4). Multi-node tree-apply leans on the runtime backstop for no-op edges, as
> elsewhere.
### 11.1 Re-sequencing review (post-Phase-3)