docs(P00): ideate — 8 ideas accepted (REQ-091..098), ROADMAP renumbered
---ci--- project: orca phase: 0 milestone: v0.10 status: ideate ---/ci---
This commit is contained in:
Jon Chery
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"phase": 0,
|
||||
"stage": "research",
|
||||
"stage": "ideate",
|
||||
"milestone": "v0.10",
|
||||
"milestone_slug": "docs-cli-examples",
|
||||
"phase_role": "pre_execution",
|
||||
|
||||
@@ -0,0 +1,39 @@
|
||||
# Ideation: v0.10 Docs & Install Milestone
|
||||
|
||||
## Tier 1 — Mechanical (codebase-grounded, no new deps)
|
||||
|
||||
| ID | Idea | Source | Accepted | REQ |
|
||||
|----|------|--------|----------|-----|
|
||||
| I-M-091 | `docs/cli.md` comprehensive CLI reference | README subcommand table is stale (missing cert/daemon/doctor/audit/ns/node-capacity/node-key-reset); no `docs/` CLI reference exists | ✅ | REQ-091 |
|
||||
| I-M-092 | `docs/jobspec.md` markdown frontmatter schema reference | Operators must read `internal/jobspec/markdown.go` source to author jobspecs; no reference doc exists | ✅ | REQ-092 |
|
||||
| I-M-093 | `docs/ingress.md` Traefik ingress reference | The service→Traefik mapping (R-007, atomic reload, drain, TLS) is undocumented; the user explicitly asked for "ingress configured" | ✅ | REQ-093 |
|
||||
| I-M-094 | `examples/full-stack/` with 5 valid jobspecs + rendered artifacts + walkthrough | No examples directory exists; `testdata/` holds legacy HCL test fixtures, not operator examples | ✅ | REQ-094 |
|
||||
| I-M-095 | README.md refresh (status, subcommand table, install example, dev targets, docs/examples sections) | README says "v0.1: Foundation"; subcommand table missing 5 commands; install example pins v0.4.2 | ✅ | REQ-095 |
|
||||
| I-M-096 | `docs/namespace.md` v0.9 multi-namespace layout update | Documents the v0.8 flat layout, not the v0.9 `cluster/`+`_defaults/`+per-ns layout | ✅ | REQ-096 |
|
||||
|
||||
## Tier 2 — Backend-enriched (API/behavior-grounded)
|
||||
|
||||
| ID | Idea | Source | Accepted | REQ |
|
||||
|----|------|--------|----------|-----|
|
||||
| I-B-097 | `scripts/release.sh` cross-build amd64 + post-create asset verification | v0.8.x releases shipped with zero binary assets; install.sh resolves to v0.8.15 then errors on missing tarball; root cause of v0.4.5 install | ✅ | REQ-097 |
|
||||
| I-B-098 | `scripts/install.sh` asset fallback walk + `--check` dry-run | install.sh has no fallback when the latest release lacks the expected tarball; a broken release blocks all installs | ✅ | REQ-098 |
|
||||
|
||||
## Tier 3 — Cross-project (deferred — single-project mode)
|
||||
|
||||
No cross-project ideas. Orca is single-project mode.
|
||||
|
||||
## Rejected ideas
|
||||
|
||||
- **Backfill the existing v0.8.15 release with a binary asset** —
|
||||
rejected per D-192. Backfilling a past release is an ops task, not a
|
||||
docs milestone deliverable. The next tagged phase (P1 ship at v0.9.1)
|
||||
will be the first correctly-asseted release; install.sh's fallback
|
||||
walk handles the gap.
|
||||
- **Document both v0.8 and v0.9 paths equally** — rejected per D-191.
|
||||
The v0.8 path is deprecated and scheduled for removal; documenting it
|
||||
as primary misleads new operators.
|
||||
- **arm64 tarball in release.sh** — rejected for this milestone per
|
||||
D-193. The install user base is amd64 today; arm64 is a separate
|
||||
enhancement.
|
||||
- **Per-command `docs/cli/*.md` subdirectory** — rejected per D-188.
|
||||
Single-file `docs/cli.md` matches the existing flat `docs/` layout.
|
||||
+76
-30
@@ -249,7 +249,53 @@ HCL-canonical, single-namespace, no-container-runtime, no-SPIFFE). The
|
||||
reversals are justified by the six-part evidence basis recorded in the
|
||||
PROJECT.md Supersession Table.
|
||||
|
||||
## Milestone v0.10: Production Hardening
|
||||
## Milestone v0.10: Docs & Install Hardening — **IN PROGRESS**
|
||||
|
||||
**Scope**: close the documentation gap left by the v0.9 re-architecture
|
||||
and fix the release/install pipeline bug that caused `install.sh` to
|
||||
resolve to v0.4.5 instead of the latest release. The v0.9
|
||||
re-architecture shipped a complete CLI surface (markdown jobspec,
|
||||
`orca ns`, `orca node capacity`, CLI-side scheduler, emitters, Traefik
|
||||
ingress) but no operator-facing reference documentation. This milestone
|
||||
ships that documentation plus a worked full-stack example with ingress
|
||||
configured, and hardens the release pipeline so every Gitea release
|
||||
carries a Linux binary asset.
|
||||
|
||||
**Milestone type**: feature (P1 ships `fix` phases; P2/P3/P4 ship `docs`
|
||||
phases; at least one non-docs phase makes this a feature milestone per
|
||||
the versioning logic).
|
||||
|
||||
- [ ] Phase 0: Pre-execution (specify → clarify → research → ideate → plan → grill) — tag `v0.9.0`
|
||||
- [ ] Phase P1: release.sh + install.sh fix (REQ-097, REQ-098) — tag `v0.9.1`
|
||||
- [ ] Phase P2: docs/cli.md + docs/jobspec.md + docs/ingress.md (REQ-091, REQ-092, REQ-093) — tag `v0.9.2`
|
||||
- [ ] Phase P3: examples/full-stack/ (REQ-094) — tag `v0.9.3`
|
||||
- [ ] Phase P4: README.md + docs/namespace.md refresh (REQ-095, REQ-096) — tag `v0.9.4`
|
||||
- [ ] Phase P5: Final review + ship + audit (milestone release) — tag `v0.9.5` = v0.10.0 milestone release
|
||||
|
||||
**Milestone tag**: `v0.9.5` (final phase patch = milestone release per
|
||||
feature-milestone progressive-patch rule). Per-phase tags: `v0.9.0`…`v0.9.5`.
|
||||
Tags run on the previous minor's patch line (v0.9.x) per
|
||||
branch-strategy.md. The milestone branch label uses the milestone
|
||||
number (`milestone/v0.10-docs-cli-examples`); no separate minor tag.
|
||||
|
||||
### Per-phase REQ coverage (v0.10 docs milestone)
|
||||
|
||||
- **P1** — release.sh cross-build + asset verification (REQ-097); install.sh fallback walk (REQ-098)
|
||||
- **P2** — CLI reference (REQ-091); jobspec reference (REQ-092); ingress guide (REQ-093)
|
||||
- **P3** — full-stack examples (REQ-094)
|
||||
- **P4** — README refresh (REQ-095); namespace.md v0.9 layout (REQ-096)
|
||||
|
||||
### Root cause of the v0.4.5 install (documented in RESEARCH_v0.10.md)
|
||||
|
||||
The v0.8.x releases (v0.8.0–v0.8.15) shipped with zero binary assets
|
||||
attached to their Gitea releases. `install.sh` resolves "latest" →
|
||||
v0.8.15, looks for `orca-v0.8.15-linux-amd64.tar.gz`, finds nothing, and
|
||||
errors out. The v0.4.5 install came from an earlier run or a pinned
|
||||
`--version`. The fix is forward: release.sh cross-builds amd64 and
|
||||
verifies the asset post-create; install.sh walks backward through
|
||||
releases if the latest lacks the asset.
|
||||
|
||||
## Milestone v0.11: Production Hardening
|
||||
|
||||
**Scope**: ship a cluster that operators can run. Builds on the v0.9
|
||||
re-architecture foundation with the production-grade subsystems:
|
||||
@@ -258,36 +304,36 @@ the v0.8→v1.0 migration.
|
||||
|
||||
**Milestone type**: feature (multiple `feat` phases).
|
||||
|
||||
- [ ] Phase 0: Pre-execution (specify → clarify → research → plan → grill) — tag `v0.9.0`
|
||||
- [ ] Phase P00: CLI cache layer (REQ-062 cache floor; R-008) — tag `v0.9.1`
|
||||
- [ ] Phase P01: Metrics endpoint (hand-rolled text exposition) — tag `v0.9.2`
|
||||
- [ ] Phase P01.5: SPIFFE SVID minting spike (REQ-076; **gate C-08** — if spike fails, fall back to mTLS identity) — tag `v0.9.3`
|
||||
- [ ] Phase P02: ACL (SPIFFE + token identities) — tag `v0.9.4`
|
||||
- [ ] Phase P03: Secrets subsystem (REQ-080; **gate C-19** threat model) — tag `v0.9.5`
|
||||
- [ ] Phase P04: Backup/restore (tar + signed) — tag `v0.9.6`
|
||||
- [ ] Phase P05: Drain + daemon drain-and-stop (REQ-061) — tag `v0.9.7`
|
||||
- [ ] Phase P06: Alloc history (CLI-side SQLite retention; REQ-071 cache DB) — tag `v0.9.8`
|
||||
- [ ] Phase P07: Recovery (`orca restore`) — tag `v0.9.9`
|
||||
- [ ] Phase P08: Integration tests — expand hermetic harness (REQ-087) — tag `v0.9.10`
|
||||
- [ ] Phase P09: Collector + aggregator (opt-in; **gates C-11, C-12, C-14**) — tag `v0.9.11`
|
||||
- [ ] Phase P10: Transactional plane (REQ-075, REQ-079; **gate C-09** orca-pull.sh failure contract) — tag `v0.9.12`
|
||||
- [ ] Phase P11: `orca job lint` (REQ-084) — tag `v0.9.13`
|
||||
- [ ] Phase P12: `orca job verify` (dry-run txn through lead) — tag `v0.9.14`
|
||||
- [ ] Phase P13: `orca ns` subcommands (full surface) + deprecation warnings (REQ-068) — tag `v0.9.15`
|
||||
- [ ] Phase P14a: v0.8→v1.0 data migration (REQ-066; **gate C-07** CA migration spec) — tag `v0.9.16`
|
||||
- [ ] Phase P14b: Daemon cutover + running-allocation adoption — tag `v0.9.17`
|
||||
- [ ] Phase P14c: Mixed-version tolerance + no-orca-on-server enforcement (REQ-065, REQ-086; implements C-13) — tag `v0.9.18`
|
||||
- [ ] Phase P15: README quickstart (REQ-089) — tag `v0.9.19`
|
||||
- [ ] Phase P15.5: Threat model + security review (**gate C-19**) — tag `v0.9.20`
|
||||
- [ ] Phase P16: Final review + ship + audit — **v0.10.0 milestone release** — tag `v0.9.21` (v1.0.0 cut separately after UAT sign-off)
|
||||
- [ ] Phase 0: Pre-execution (specify → clarify → research → plan → grill) — tag `v0.10.0`
|
||||
- [ ] Phase P00: CLI cache layer (REQ-062 cache floor; R-008) — tag `v0.10.1`
|
||||
- [ ] Phase P01: Metrics endpoint (hand-rolled text exposition) — tag `v0.10.2`
|
||||
- [ ] Phase P01.5: SPIFFE SVID minting spike (REQ-076; **gate C-08** — if spike fails, fall back to mTLS identity) — tag `v0.10.3`
|
||||
- [ ] Phase P02: ACL (SPIFFE + token identities) — tag `v0.10.4`
|
||||
- [ ] Phase P03: Secrets subsystem (REQ-080; **gate C-19** threat model) — tag `v0.10.5`
|
||||
- [ ] Phase P04: Backup/restore (tar + signed) — tag `v0.10.6`
|
||||
- [ ] Phase P05: Drain + daemon drain-and-stop (REQ-061) — tag `v0.10.7`
|
||||
- [ ] Phase P06: Alloc history (CLI-side SQLite retention; REQ-071 cache DB) — tag `v0.10.8`
|
||||
- [ ] Phase P07: Recovery (`orca restore`) — tag `v0.10.9`
|
||||
- [ ] Phase P08: Integration tests — expand hermetic harness (REQ-087) — tag `v0.10.10`
|
||||
- [ ] Phase P09: Collector + aggregator (opt-in; **gates C-11, C-12, C-14**) — tag `v0.10.11`
|
||||
- [ ] Phase P10: Transactional plane (REQ-075, REQ-079; **gate C-09** orca-pull.sh failure contract) — tag `v0.10.12`
|
||||
- [ ] Phase P11: `orca job lint` (REQ-084) — tag `v0.10.13`
|
||||
- [ ] Phase P12: `orca job verify` (dry-run txn through lead) — tag `v0.10.14`
|
||||
- [ ] Phase P13: `orca ns` subcommands (full surface) + deprecation warnings (REQ-068) — tag `v0.10.15`
|
||||
- [ ] Phase P14a: v0.8→v1.0 data migration (REQ-066; **gate C-07** CA migration spec) — tag `v0.10.16`
|
||||
- [ ] Phase P14b: Daemon cutover + running-allocation adoption — tag `v0.10.17`
|
||||
- [ ] Phase P14c: Mixed-version tolerance + no-orca-on-server enforcement (REQ-065, REQ-086; implements C-13) — tag `v0.10.18`
|
||||
- [ ] Phase P15: README quickstart (REQ-089) — tag `v0.10.19`
|
||||
- [ ] Phase P15.5: Threat model + security review (**gate C-19**) — tag `v0.10.20`
|
||||
- [ ] Phase P16: Final review + ship + audit — **v0.11.0 milestone release** — tag `v0.10.21` (v1.0.0 cut separately after UAT sign-off)
|
||||
|
||||
**Milestone tag**: `v0.10.0` (the v0.10 milestone release tag; v1.0.0 is
|
||||
UAT-gated and cut separately after v0.10 completion per operator decision —
|
||||
**Milestone tag**: `v0.11.0` (the v0.11 milestone release tag; v1.0.0 is
|
||||
UAT-gated and cut separately after v0.11 completion per operator decision —
|
||||
the v1.0.0 tag marks production-ready sign-off, not a separate milestone).
|
||||
Per-phase patches run on the v0.9.x line per branch-strategy.md. Per-phase
|
||||
tags: `v0.9.0`…`v0.9.21`.
|
||||
Per-phase patches run on the v0.10.x line per branch-strategy.md. Per-phase
|
||||
tags: `v0.10.0`…`v0.10.21`.
|
||||
|
||||
### Per-phase REQ coverage (v0.10)
|
||||
### Per-phase REQ coverage (v0.11)
|
||||
|
||||
- **P00** — CLI cache (R-008)
|
||||
- **P01.5** — SPIFFE spike (REQ-076; C-08)
|
||||
@@ -309,9 +355,9 @@ tags: `v0.9.0`…`v0.9.21`.
|
||||
- **wasmtime CGO breaks cross-compile** (mitigation: C-01 spike; fallback to podman/process primary)
|
||||
- **bash control plane drift** (mitigation: C-15..C-18 render-format contract + bats gate)
|
||||
- **daemon cutover orphans running allocs** (mitigation: P14b split; test adoption)
|
||||
- **27→35+ phase scope** (mitigation: C-04 resolved — operator decision: keep 2 milestones v0.9 + v0.10, keep all phases, v1.0 is UAT-gated after v0.10; current count v0.9=18 + v0.10=22 = 40 phases, exceeds 35 soft limit but operator accepted)
|
||||
- **27→35+ phase scope** (mitigation: C-04 resolved — operator decision: keep 2 milestones v0.9 + v0.11, keep all phases, v1.0 is UAT-gated after v0.11; current count v0.9=18 + v0.11=22 = 40 phases, exceeds 35 soft limit but operator accepted)
|
||||
|
||||
## Deferred to v1.x (out of scope for v0.10)
|
||||
## Deferred to v1.x (out of scope for v0.11)
|
||||
|
||||
- `sqlite-wal-shared` state backend (R-009 abstractions ship in v1.0; backend in v1.x)
|
||||
- `git` state backend
|
||||
|
||||
Reference in New Issue
Block a user