orca/.ciagent/PLAN_v0.10.md

Plan: v0.10 Docs & Install Milestone

Milestone: v0.10 — Docs & Install Hardening

• Type: feature (P1 fix, P2-P4 docs; at least one non-docs phase)
• Tags: v0.9.0 (P0) → v0.9.1 (P1) → v0.9.2 (P2) → v0.9.3 (P3) → v0.9.4 (P4) → v0.9.5 (P5 = milestone release)
• Branch: milestone/v0.10-docs-cli-examples

Phase breakdown

Phase P1 — release.sh + install.sh fix (Wave 1)

REQs: REQ-097, REQ-098 Persona: backend-engineer Territory: scripts/release.sh, scripts/install.sh, scripts/tests/*.bash Vertical slice: a broken release → a correctly-asseted release that install.sh resolves.

Task	Description	REQ
P1-T1	scripts/release.sh: replace host-arch build (lines 84, 89-98) with explicit GOOS=linux GOARCH=amd64 go build cross-build; produce orca-${VERSION}-linux-amd64.tar.gz regardless of host arch	REQ-097
P1-T2	scripts/release.sh: after tea releases create (line 132), add post-create asset verification — query /api/v1/repos/$OWNER/$REPO/releases/tags/$VERSION, assert the tarball appears in attachments, retry once if missing, fail loudly with clear error if still missing	REQ-097
P1-T3	scripts/install.sh: add asset fallback walk — if the resolved release (latest or --version) lacks the matching orca-<ver>-<os>-<arch>.tar.gz, query /releases?limit=20, walk backward, use the most recent release that carries the asset, print a warning	REQ-098
P1-T4	scripts/install.sh: add --check dry-run mode that prints version + asset URL + install path without writing	REQ-098
P1-T5	scripts/tests/release.bats + scripts/tests/install.bats: add/extend bats tests for the new behavior (happy path: asset present; fallback: latest release asset-less, older release has asset; --check prints without writing)	REQ-097, REQ-098

Must-haves: release.sh produces an amd64 tarball on any host arch; install.sh resolves to a release with an asset (walking back if needed); --check works; bats tests pass.

Phase P2 — CLI + jobspec + ingress docs (Wave 2)

REQs: REQ-091, REQ-092, REQ-093 Persona: docs-engineer (phase-specific), lead-developer Territory: docs/cli.md, docs/jobspec.md, docs/ingress.md Vertical slice: an operator with no orca background → can author a jobspec, run it, and understand the ingress model from docs alone.

Task	Description	REQ
P2-T1	docs/cli.md: full CLI reference — global flags, every command/subcommand with synopsis + flag tables + one-line example, output modes (text/json/watch), exit codes, deprecated surface callout boxes (daemon/cert/node-join-mTLS/HCL-jobspec)	REQ-091
P2-T2	docs/jobspec.md: markdown frontmatter schema reference — top-level keys, block reference (runtime/ports/env-secrets/volumes/restart/update/service/health/lifecycle/constraints/affinity/tasks), kinds matrix, CEL subset grammar, body semantics, deprecated HCL callout	REQ-092
P2-T3	docs/ingress.md: Traefik ingress reference — service→Traefik mapping, R-007 socket-vs-TCP-bind, generated YAML shape, atomic reload (C-10), drain, TLS, worked-example pointer to examples/full-stack/, v0.10 forward limitations	REQ-093

Must-haves: every command/flag in internal/cli/ is documented; every jobspec field in internal/jobspec/markdown.go is documented; every factual claim is grounded in the live codebase; cross-links resolve; deprecated surface is clearly marked.

Phase P3 — full-stack examples (Wave 2, parallel with P2)

REQs: REQ-094 Persona: docs-engineer (phase-specific), lead-developer Territory: examples/full-stack/** Vertical slice: an operator → can deploy a multi-service stack with ingress by copying the examples.

Task	Description	REQ
P3-T1	examples/full-stack/web-app.md: kind Service, process runtime, port http, service block (socket default), health, restart (service), update (rolling), constraints (CEL), task group (app + sidecar)	REQ-094
P3-T2	examples/full-stack/api.md: kind Service, process runtime, port api, service bind 127.0.0.1 (TCP opt-in), health, restart, update (canary)	REQ-094
P3-T3	examples/full-stack/worker.md: kind Job, process runtime, one-shot, timeout, env, lifecycle hooks	REQ-094
P3-T4	examples/full-stack/log-shipper.md: kind DaemonSet, schedule (every-node), restart, constraints	REQ-094
P3-T5	examples/full-stack/postgres.md: kind Service, process runtime, port pg, volumes + replication (syncthing), health, restart, update (blue-green)	REQ-094
P3-T6	examples/full-stack/rendered/: the Traefik dynamic YAML + systemd units orca generates for the stack (traefik-dynamic-web-app.yaml, traefik-dynamic-api.yaml, systemd-web-app.service, systemd-api.service, systemd-log-shipper.service)	REQ-094
P3-T7	examples/full-stack/README.md: walkthrough (init → node join → capacity set → ns create → job run → list --watch → inspect rendered → drain/rollback notes → cross-link to docs/ingress.md)	REQ-094

Must-haves: all 5 jobspecs parse with the current internal/jobspec parser and pass internal/spec/schema validators; rendered artifacts match what the emitters would produce; README walkthrough is end-to-end coherent.

Phase P4 — README + namespace.md refresh (Wave 3, after P2/P3)

REQs: REQ-095, REQ-096 Persona: lead-developer Territory: README.md, docs/namespace.md Vertical slice: a new visitor to the repo → sees accurate status, all commands, install instructions that work, and a link to the docs + examples.

Task	Description	REQ
P4-T1	README.md: 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; new Documentation + Examples sections	REQ-095
P4-T2	docs/namespace.md: replace v0.8 flat path table with v0.9 multi-namespace 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	REQ-096

Must-haves: README subcommand table matches internal/cli/ exactly; install example pins a current tag; namespace.md path table matches internal/paths/paths.go; both files cross-link to the new docs.

Phase P5 — final review + ship + audit (Wave 4)

REQs: all (REQ-091..REQ-098) Persona: lead-developer Vertical slice: milestone complete → merged to main, tagged, released.

Task	Description	REQ
P5-T1	Code review across all phases (P1-P4); auto-apply P0 fixes, flag P1+ for post-hoc	all
P5-T2	Audit: reconstruction test (git log matches .ciagent/), file discipline, branch hygiene, commit discipline	all
P5-T3	Milestone ship: merge phase/05 → milestone → main; tag v0.9.5 (= v0.10.0 milestone release); create release with full milestone summary + Linux binary asset (verified by the P1 fix); delete all milestone branches	all
P5-T4	Complete milestone: mark REQ-091..098 complete in REQUIREMENTS.md; mark v0.10 docs milestone complete in ROADMAP.md; clear checkpoint	all

Must-haves: milestone merged to main; release carries the Linux binary (the fix from P1 proving itself); all REQs marked complete; checkpoint cleared.

Wave ordering

• Wave 1: P1 (release/install fix) — unblocks the ship of every subsequent phase (each phase ship needs a correctly-asseted release)
• Wave 2: P2 (docs) + P3 (examples) — parallel, no dependencies between them
• Wave 3: P4 (README + namespace.md) — depends on P2/P3 existing (cross-links)
• Wave 4: P5 (final review + ship) — depends on all prior phases

Risks

• R1: The jobspecs in P3 might not parse if a field shape has drifted since the explore report. Mitigation: validate each jobspec against the current parser before committing (write a throwaway test or run orca job run with --dry-run if available).
• R2: tea releases create asset verification in P1 might reveal a tea CLI bug that can't be worked around in bash. Mitigation: fall back to a direct curl upload to the Gitea attachments API if tea is unreliable.
• R3: The v0.8.15 release still has no asset after P1 ships (P1 only fixes forward). Mitigation: install.sh's fallback walk (P1-T3) handles the gap; users installing between P1 ship and the first correctly-asseted release (P1's own ship tag v0.9.1) will get a clear warning + fallback.