distribution/.agents/runs/2026-06-02-orchestration-planning/snarky-review.md

Snarky Review

Findings first, because vibes are not a roadmap.

1. P0: Opus cannot implement yet because the workspace has no git baseline.

   Branch-based implementation is mandatory, but the plan admits this workspace is not a git repo. Snarky will not approve an Opus implementation phase until git is initialized or attached and the current baseline is committed.

2. P1: Access policy is hand-waved, and this product lives or dies there.

   The plan names actors and says access policy decides install/download, but does not define auth modes, human sessions, public links, private apps, app ownership, RBAC, or scoped install access. "Authenticated and public modes" is not a model.

3. P1: Release lifecycle is internally muddy.

   Releases are supposed to be immutable and channels mutable. But Release still has channel, while Channel separately points to current_release_id. Also the CLI creates a draft release, validates, publishes, and maybe promotes, but no state machine is defined. Define draft, validating, published, rejected, superseded, etc.

4. P1: The std subplan references sections that no longer exist.

   Subplan 01 tells implementers to read Standard Library API Surface and Detailed Std Struct And Method Sketches. Those were removed from PLAN.md.

5. P1: CI manifest and idempotency are underspecified.

   The CLI plan gives required fields, but not a schema, examples, retry semantics, duplicate release behavior, idempotency keys, or what happens when CI reruns the same build.

6. P1: HTTP API is too abstract to build against.

   The API plan lists slices but no concrete routes, request bodies, response schemas, pagination/filtering, auth errors, upload protocol, or download authorization rules.

7. P2: Validation policy mixes product requirements with wishful tooling.

   "If tool support exists," "provided or checked," and "malware scan placeholder" are not acceptance criteria. For v1, mark each check as required, warning, informational, or not supported.

8. P2: Milestone 1 is too large to be a milestone.

   It includes sx primitives, local server, APK and IPA publishing, SQLite, channels, install pages, admin UI, and NAS Docker deployment.

Required Before Opus Implements

• Create a clean git baseline.
• Write a Snarky brief.md for the redesign run with hard acceptance criteria.
• Resolve the minimum product model for the mock: release states, channel behavior, access modes, token scopes, and iOS install modes.
• Provide seed data and required UI states Opus must represent.
• Let Opus produce a design proposal first. No code until Snarky accepts the product coverage.