Files

T

Jon Chery 152a7fc375 docs(P00): grill PASS (0.82) — 3 binding conditions, 3 phase challenges

---ci---
project: orca
phase: 0
milestone: v0.10
status: grill
---/ci---

2026-08-05 20:47:50 +00:00

3.0 KiB

Raw Blame History

Grill: v0.10 Docs & Install Milestone

Verdict: PASS (confidence 0.82)

The plan is sound for a documentation + install-hardening milestone. No replan required. Three binding conditions adopted below.

Axis review

Scope justification — PASS

The milestone closes a real gap (no CLI/jobspec/ingress docs, stale README, broken release pipeline) with a bounded scope (5 phases, no Go orchestration code changes). The v0.9 re-architecture shipped functionality without operator-facing docs; this milestone ships the docs. The install fix (P1) addresses a measured production bug (v0.4.5 install), not a speculative enhancement.

Feasibility — PASS

All tasks are markdown authoring (P2-P4) or bash script hardening (P1). No new dependencies, no schema changes, no Go code changes. The jobspecs in P3 must parse against the current parser — risk R1 is real but mitigated by validation before commit.

Vertical slice integrity — PASS

Each phase ships an independently valuable deliverable:

P1: install.sh works (resolves to a release with an asset)
P2: an operator can read the CLI/jobspec/ingress docs
P3: an operator can copy the examples and deploy a stack
P4: README + namespace.md are accurate
P5: milestone complete, merged, released

Wave ordering — PASS

P1 (Wave 1) unblocks all subsequent ship operations (each phase ship needs a correctly-asseted release). P2 + P3 (Wave 2) are parallel with no dependencies. P4 (Wave 3) depends on P2/P3 for cross-links. P5 (Wave 4) depends on all.

Risk register — PASS

Three risks identified, all mitigated. R1 (jobspec parse drift) is the highest; mitigation is validation before commit. R2 (tea CLI asset bug) has a curl fallback. R3 (v0.8.15 still asset-less) is handled by install.sh's fallback walk.

Binding conditions

ID	Condition	Phase	Status
C-20	Every jobspec in `examples/full-stack/` MUST parse with `internal/jobspec.ParseFile` and pass `internal/spec/schema.ValidatorFor(kind)` before P3 commits	P3	pending
C-21	`scripts/release.sh` post-create asset verification MUST query the Gitea API and assert the tarball in attachments (not rely on `tea` exit code alone)	P1	pending
C-22	Every factual claim in `docs/cli.md`, `docs/jobspec.md`, `docs/ingress.md` MUST be grounded in the live codebase (struct fields, flag definitions, paths) — verified by the docs-engineer persona before P2 commits	P2	pending

Phase challenges

ID	Challenge	Phase
PC-11	The jobspecs in P3 must not use fields that don't exist yet (e.g., `resources:` which lands in v0.11-P0c). Validate against the current `WorkloadSpec` struct.	P3
PC-12	The rendered artifacts in P3 must match what the emitters actually produce, not an idealized version. Cross-check against `internal/emitter/` test fixtures.	P3
PC-13	The README subcommand table must match `internal/cli/` exactly — no stale commands, no missing commands.	P4

3.0 KiB Raw Blame History