diff --git a/.ciagent/CHECKPOINT.json b/.ciagent/CHECKPOINT.json index 41a0192..b0400c9 100644 --- a/.ciagent/CHECKPOINT.json +++ b/.ciagent/CHECKPOINT.json @@ -1,24 +1,20 @@ { - "phase": 99, - "stage": "complete", - "milestone": "v0.9", - "milestone_slug": "rearchitecture", - "phase_role": "final", - "updated_at": "2026-08-05T05:25:00Z", - "milestone_complete": true, - "next_milestone": "v0.10", + "phase": 0, + "stage": "specify", + "milestone": "v0.10", + "milestone_slug": "docs-cli-examples", + "phase_role": "pre_execution", + "attempts": 0, + "updated_at": "2026-08-05T20:00:00Z", + "milestone_complete": false, "ship": { - "tag": "v0.8.15", - "merged_to_main": true, - "milestone_branch_deleted": true, - "all_phase_branches_deleted": true + "tag": null, + "merged_to_main": false, + "milestone_branch_deleted": false, + "all_phase_branches_deleted": false }, "requirements": { - "covered": [62,63,64,67,68,69,70,71,72,73,74,76,77,78,81,82,83,85,88,89,90], - "partial": [61,65,66,75,79,80,84,86,87] - }, - "gates": { - "cleared": ["C-01","C-02","C-03","C-04","C-05","C-06","C-07","C-10","C-14","C-15","C-16","C-17","C-18"], - "deferred_v0_10": ["C-08","C-09","C-11","C-12","C-13","C-19"] + "covered": [], + "partial": [] } -} +} \ No newline at end of file diff --git a/.ciagent/PROJECT.md b/.ciagent/PROJECT.md index fc9e190..f42ecc6 100644 --- a/.ciagent/PROJECT.md +++ b/.ciagent/PROJECT.md @@ -446,3 +446,61 @@ are recorded in `REQUIREMENTS.md`. The reordered phase plan is in | D-179 | Jobspec format: HCL canonical (AD-007) or Markdown? | **Markdown with YAML frontmatter canonical (R-013); HCL legacy** | PRD §8 — Markdown + body preservation is the operator-facing format. HCL adapter (REQ-064) preserves `orca job run old-spec.hcl` during migration. | 0.85 | | D-185 | Re-architecture justification: incremental additive or full re-architecture? | **Full re-architecture (overridden by user)** | Six-part evidence basis above; the grill's REPLAN mechanics (PC-01..PC-10, C-01..C-19) adopted as gates. The incremental-additive path was evaluated and rejected on grounds 1 + 5 (daemon failing; SSH-push only viable). | 0.88 | | D-187 | wasmtime Go binding (bytecodealliance/wasmtime-go) is CGO-based — does adopting it revoke D-002 (modernc/sqlite CGO-free cross-compile story)? | **Use the wasmtime CLI (apt-installed on peer) via SSH exec; do NOT import wasmtime-go.** | The Go binding links libwasmtime via cgo and would revoke D-002's CGO-free cross-compile story. The CLI-via-SSH approach (same pattern as podman/qm/pct) avoids CGO entirely. `internal/runtime/wasm.go` imports only stdlib + sshpush. `CGO_ENABLED=0 go build ./...` succeeds. C-01 grill gate SATISFIED; D-002 NOT revoked. Full evaluation in `internal/runtime/C01_WASMTIME_CGO_EVAL.md`. | 0.90 | + +--- + +# v0.10 Docs & Install Milestone — Scope Summary + +v0.10 is a focused milestone that closes the documentation gap left by +the v0.9 re-architecture and fixes 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. + +## Root cause of the v0.4.5 install + +The v0.8.x releases (v0.8.0 through v0.8.15) shipped with **zero binary +assets attached** to their Gitea releases. `scripts/install.sh` resolves +"latest" by hitting `/releases/latest` (returns v0.8.15), then looks for +`orca-v0.8.15-linux-amd64.tar.gz` in that release's assets. Since the +asset is missing, install.sh errors out — there is no fallback walk to +older releases that DO carry a binary. The user's v0.4.5 install came +from an earlier run or a pinned `--version`. The fix is forward: harden +`scripts/release.sh` to cross-build the amd64 tarball and verify the +asset attached post-create; harden `scripts/install.sh` to walk +backward through releases if the latest lacks the asset. + +## v0.10 Phases + +- **Phase 0 (pre-execution)**: specify → clarify → research → ideate → plan → grill. Tag `v0.9.0`. +- **Phase P1 — release/install fix** (REQ-097, REQ-098): cross-build amd64 tarball in release.sh, post-create asset verification, install.sh fallback walk. Tag `v0.9.1`. +- **Phase P2 — CLI + jobspec + ingress docs** (REQ-091, REQ-092, REQ-093): `docs/cli.md`, `docs/jobspec.md`, `docs/ingress.md`. Tag `v0.9.2`. +- **Phase P3 — full-stack examples** (REQ-094): `examples/full-stack/` with 5 valid jobspecs + rendered artifacts + walkthrough README. Tag `v0.9.3`. +- **Phase P4 — README + namespace.md refresh** (REQ-095, REQ-096): README subcommand table + install example + docs/examples sections; `docs/namespace.md` v0.9 layout. Tag `v0.9.4`. +- **Phase P5 — final review + ship + audit** (milestone release). Tag `v0.9.5` = v0.10.0 milestone release. + +**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). Tags run on the v0.9.x patch line. The milestone +branch label is `milestone/v0.10-docs-cli-examples`. + +The vision ("minimalist, offline-first, CLI-first orchestration +engine") is unchanged. v0.10 is a documentation + install-hardening +milestone, not a direction change. It builds on the v0.9 +re-architecture foundation without modifying any Go orchestration code. + +## v0.10 Clarified Decisions (D-series, full autonomy — Phase 0 pre-execution) + +| ID | Question | Decision | Rationale | Confidence | +|----|----------|----------|-----------|------------| +| D-188 | Should the CLI docs be a single `docs/cli.md` reference or a per-command `docs/cli/` subdirectory? | **Single `docs/cli.md` reference** | Mirrors the existing flat `docs/` pattern (install.md, docker.md, namespace.md, security-scanning.md). One file is more discoverable for a CLI tool and avoids navigation overhead. A per-command subdirectory diverges from the established layout. | 0.92 | +| D-189 | Should the examples live in `examples/full-stack/` or in `testdata/`? | **`examples/full-stack/` as a new top-level directory** | `testdata/` holds legacy HCL fixtures (`hello.hcl`, `fail.hcl`) used by Go tests; mixing operator-facing examples with test fixtures conflates audiences. A new `examples/` directory is the conventional location for worked examples and is what an operator expects to find. | 0.93 | +| D-190 | How deep should the ingress/Traefik documentation go? | **Dedicated `docs/ingress.md` plus a worked example in `examples/full-stack/`** | Ingress is the user's explicit ask ("full stack with ingress configured") and the Traefik/service-block model (R-007 socket vs TCP, atomic reload, drain, TLS) is non-trivial. A dedicated doc is the clearest answer; a section buried in `docs/cli.md` would be less discoverable. | 0.90 | +| D-191 | Should the docs frame the v0.9 canonical path or document both v0.8 and v0.9 equally? | **Document the v0.9 canonical path; flag deprecated surface with callout boxes** | The v0.8 daemon/mTLS/HCL path is deprecated and scheduled for removal in v0.10-P14. Documenting it as primary misleads new operators; documenting both equally doubles the surface and risks documenting soon-removed code. Callout boxes with "deprecated in v0.9, removed in v0.10" point operators to the canonical path. | 0.91 | +| D-192 | Should the existing v0.8.15 release be backfilled with a binary asset, or only fix the pipeline forward? | **Fix forward only; no backfill** | Backfilling a past release is an ops task, not a docs milestone deliverable. The next tagged phase (this milestone's P1 ship at v0.9.1) will be the first correctly-asseted release; install.sh's new fallback walk handles the gap until then. | 0.88 | +| D-193 | Should `release.sh` build only `linux-amd64` or also `linux-arm64`? | **Cross-build `linux-amd64` explicitly (host-arch-independent); arm64 deferred to a follow-up** | The install.sh user base is amd64 today (the `.coreci.yml` release step hardcodes `--asset orca-${VERSION}-linux-amd64.tar.gz`). Building amd64 regardless of host arch (via `GOOS=linux GOARCH=amd64 go build`) guarantees the asset the install script expects. arm64 support is a separate enhancement. | 0.85 | +| D-194 | Should `install.sh` add a `--check` dry-run mode? | **Yes, lightweight** | A dry-run mode (`--check`) that prints the version + asset URL + install path without writing is cheap to add and useful for debugging the "which release will I get?" question that the v0.4.5 incident surfaced. | 0.80 | diff --git a/.ciagent/REQUIREMENTS.md b/.ciagent/REQUIREMENTS.md index 8adc1c7..8e252ca 100644 --- a/.ciagent/REQUIREMENTS.md +++ b/.ciagent/REQUIREMENTS.md @@ -182,3 +182,22 @@ and `GRILL_v0.9.md`. | REQ-088 | Security-engineer + network-engineer persona reactivation: reactivate security-engineer (step-ca provisioner model, SSH-push blast radius, Traefik edge, .env.secrets crypto) and network-engineer (socket exposure R-007, Syncthing P2P ports, Traefik routing); cross-cutting review not single phase (I-C-004). Implements grill C-05 | High | **v0.9 P00** → v0.10 P16 | Complete | | REQ-089 | Documentation rewrite: ARCHITECTURE.md/PROJECT.md/README + AD-010 supersession: v0.9-P00 adds "v0.9 Architecture (Supersedes v0.8)" section + banners + Superseded Decisions table; v0.10-P15 rewrites README quickstart for new curl|sh + orca init + orca ns create flow (I-C-005) | Medium | **v0.9 P00** + v0.10 P15/P16 | Complete | | REQ-090 | Dual-write window: v0.9 `orca job run` dispatches on extension (`.md`→SSH-push new path, `.hcl`→old daemon path) via parser dispatcher (REQ-064); daemon not removed until v0.10-P05; SSH-push path writes to separate systemd unit namespace (`orca-v1-.service`) while daemon uses `orca-.service` — no unit name overlap = no conflict (I-C-006) | High | **v0.9 P00** | Complete | + +## v0.10 Docs & Install Milestone Requirements + +The following requirements are scoped to the v0.10 docs/cli-examples +milestone. They cover the CLI reference documentation, jobspec +reference, ingress guide, full-stack example jobspecs, README refresh, +namespace.md v0.9 layout update, and the release/install pipeline fix +that guarantees every Gitea release carries a Linux binary asset. + +| ID | Requirement | Priority | Phase | Status | +|----|-------------|----------|-------|--------| +| REQ-091 | `docs/cli.md` comprehensive CLI reference: every command/subcommand with synopsis, flags (name/type/default/description), and one-line example; global flags (`--json`, `--system`, `--config`, `--no-deprecation-warnings`); output modes (text vs `--json`, `--watch` table vs NDJSON); exit codes; deprecated surface (`orca daemon`, `orca cert`, `orca node join` mTLS path, legacy `.hcl` jobspec) flagged with callout boxes pointing to v0.10 removal | High | **v0.10 P2** | Pending | +| REQ-092 | `docs/jobspec.md` markdown frontmatter schema reference: all top-level keys, block reference (runtime, ports, env/secrets, volumes, restart, update, service, health, lifecycle, constraints, affinity, tasks), kinds matrix (Job/Service/DaemonSet required vs allowed), CEL subset grammar, body byte-exact preservation (R-015), deprecated HCL form callout | High | **v0.10 P2** | Pending | +| REQ-093 | `docs/ingress.md` Traefik ingress reference: `kind: Service` implies Traefik route (D-175), R-007 socket-vs-TCP-bind semantics, generated Traefik YAML shape (routers/services/healthCheck), atomic reload (C-10), drain (`weight: 0`), TLS (certResolver, trust domain, step-ca), worked-example pointer to `examples/full-stack/`, v0.10 forward limitations (socket activation, transactional update) | High | **v0.10 P2** | Pending | +| REQ-094 | `examples/full-stack/` directory with 5 valid jobspecs (`web-app.md`, `api.md`, `worker.md`, `log-shipper.md`, `postgres.md`) exercising ports/service/health/restart/update/constraints/affinity/lifecycle/task-groups/volumes/replication/DaemonSet; `rendered/` subdir showing the Traefik dynamic YAML + systemd units orca generates; `README.md` walkthrough (init → node join → capacity set → ns create → job run → list --watch → inspect rendered) | High | **v0.10 P3** | Pending | +| REQ-095 | README.md refresh: status line (v0.9 complete, v0.10 in progress), install `--version` example updated to current tag, subcommand table expanded to all commands with deprecation markers, update-in-place example updated, development targets complete (`verify-reqs`, `security-scan`, `test-race`, `changelog`), new Documentation + Examples sections linking all `docs/*.md` and `examples/` | High | **v0.10 P4** | Pending | +| REQ-096 | `docs/namespace.md` v0.9 multi-namespace layout update: replace v0.8 flat path table with v0.9 layout (`cluster/`, `_defaults/`, per-ns `db/jobs/alloc/ns.md`), `ORCA_HOME`/`--system` resolution, `orca ns` subcommand cross-link, v0.8 flat layout flagged deprecated | Medium | **v0.10 P4** | Pending | +| REQ-097 | `scripts/release.sh` release pipeline fix: cross-build `linux-amd64` tarball regardless of host arch (`GOOS=linux GOARCH=amd64 go build`); post-create asset verification (query `/releases/tags/$VERSION`, assert the tarball in attachments, retry/fail loudly if missing). Guarantees every Gitea release carries the Linux binary asset (root cause of v0.4.5 install) | High | **v0.10 P1** | Pending | +| REQ-098 | `scripts/install.sh` asset fallback walk: if the latest/pinned release lacks the matching `orca---.tar.gz`, walk backward through `/releases?limit=20` to the most recent release that has it, with a clear warning. Keeps pulling from releases (not main). Optional `--check` dry-run mode | High | **v0.10 P1** | Pending | diff --git a/.ciagent/config.json b/.ciagent/config.json index 47ff4c4..c4305b5 100644 --- a/.ciagent/config.json +++ b/.ciagent/config.json @@ -5,7 +5,7 @@ "slug": "orca", "name": "Orca", "description": "Offline/CLI-first orchestration engine (Orca) — Nomad-inspired, far simpler than Kubernetes", - "milestone": "v0.9", + "milestone": "v0.10", "phase": 0, "milestone_type": "feature", "default_branch": "main",