docs: reconcile the groups/project-tool initiative into the roadmap
The groups/project-tool work had no home in the blueprint's version scheme, two "Phase N" numbering schemes overlapped, and CLAUDE.md's "current focus" was stale (claimed v1.1.0 SDK foundation; we're at v1.1.9 with the SDK line complete). Reconcile all three: * blueprint §12 Phase 5 (v1.2, already titled "Advanced Workflows & Hierarchies") — split into a Hierarchies track (the groups + project tool initiative, with §11 Phases 1–3 marked shipped) and a Workflows track, with sequencing flagged as an open call. This gives the work an explicit version home: the Hierarchies half of v1.2. * design doc header — Status Draft → Active, "scheduled as the Hierarchies track of v1.2", and an explicit warning that §11's local Phase 1–6 numbering is distinct from the blueprint product-phase numbering. * design doc §11.1 — a post-Phase-3 re-sequencing review: resolve Phase 4 scripts LIVE (drop the fan-out-invalidation sub-project, per the Phase 3 result); consider a "Phase 5-lite" (declarative apply of vars/secrets + app scripts) before the hard group-scripts work; and force the two deferred decisions (trigger/route templates vs tenant cardinality; multi-repo ownership vs a single-repo start). * CLAUDE.md — refresh "current focus" to v1.2 Hierarchies, and correct the now-broken "every v1.1+ table is app_id NOT NULL" invariant: the new group-inheritable config tables (vars, secrets) use a polymorphic owner (group_id XOR app_id), not app_id NOT NULL. Doc-only; no code change. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -1,9 +1,13 @@
|
||||
# Groups, Projects & the Declarative Project Tool
|
||||
|
||||
> **Status:** Draft — design discussion captured 2026-06-18, revised 2026-06-20 with resolutions
|
||||
> **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). Not yet scheduled into a phase.
|
||||
> feasibility). **Scheduled as the *Hierarchies* track of v1.2** (blueprint §12 Phase 5). §11 Phases
|
||||
> 1–3 (project tool, groups + hierarchy RBAC, group-inherited config) are **shipped**; Phases 4–6
|
||||
> remain. NB: §11's own Phase 1–6 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.
|
||||
>
|
||||
> **Scope:** turns the imperative `pic` CLI into a declarative, file-based project tool, and
|
||||
> introduces a server-side **groups** hierarchy so apps can share and inherit config/scripts
|
||||
@@ -944,6 +948,32 @@ Resolved items now live inline next to their topic. What genuinely remains:
|
||||
real shared-scope authz model. Optionally, trigger/route **templates** (§4.5) if cardinality
|
||||
demands.
|
||||
|
||||
### 11.1 Re-sequencing review (post-Phase-3)
|
||||
|
||||
A review after Phase 3 shipped surfaced three adjustments to the 4→6 plan; carried here as decisions
|
||||
to take, not yet taken:
|
||||
|
||||
- **Phase 4 should resolve scripts *live*, not materialize.** §11.4 carries "cache-invalidation
|
||||
fan-out hardening" as a deliverable, a holdover from the materialized-view model. Phase 3 proved
|
||||
**live resolution** (recursive CTE per call) is sufficient and sidesteps the §10 invalidation SLA,
|
||||
and script *bodies are already live-resolved per request today* (§5.1). So Phase 4 should resolve
|
||||
group-owned scripts live too and **drop the fan-out-invalidation sub-project** unless a *measured*
|
||||
hot-path cost appears. This removes the scariest item from Phase 4; the real remaining cost is the
|
||||
**module/import resolver redesign** (§5.5), which is unaffected by this and stays the gating risk.
|
||||
- **Consider a "Phase 5-lite" *before* Phase 4.** The declarative project tool already applies app
|
||||
scripts (Phase 1) and Phase 3 shipped the group vars/secrets CRUD, so a project tool that declares
|
||||
**group vars/secrets + app scripts** needs *nothing* from Phase 4 (group-owned scripts). The
|
||||
highest-leverage day-to-day workflow (declarative config apply) can ship ahead of the hard
|
||||
module-resolver work. Phase 4 then adds group-owned *scripts* to an already-working project tool.
|
||||
- **Two deferred decisions to force, not default:**
|
||||
- *Trigger/route templates (§4.5):* bundled into Phase 6 as "much later," but the per-app binding
|
||||
tax bites in Phase 5 at high tenant cardinality (100 tenants × 5 triggers = 500 declarations).
|
||||
Decide against **actual** target tenant counts before defaulting it late.
|
||||
- *Multi-repo ownership (§7):* the single-owner / attach-point / takeover machinery is substantial
|
||||
and only earns its keep with a **second** managing repo. For a solo-dev / single-repo start, a
|
||||
"one repo owns the whole subtree" model covers the near term; confirm the multi-repo need exists
|
||||
before building the ownership layer.
|
||||
|
||||
---
|
||||
|
||||
## 12. Contracts still to draft
|
||||
|
||||
Reference in New Issue
Block a user