amadan
spec: Astra review brief for the deploy credential
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 file changed,
+74
−0
docs/superpowers/specs/CODEX-REVIEW-BRIEF-DEPLOY-CREDENTIAL.md+74 −0
CI passed — run details
diff --git a/docs/superpowers/specs/CODEX-REVIEW-BRIEF-DEPLOY-CREDENTIAL.md b/docs/superpowers/specs/CODEX-REVIEW-BRIEF-DEPLOY-CREDENTIAL.md| new file mode 100644 |
| index 000000000..2d0cb9d67 |
| --- /dev/null |
| +++ b/docs/superpowers/specs/CODEX-REVIEW-BRIEF-DEPLOY-CREDENTIAL.md |
| @@ -0,0 +1,74 @@ |
| +# Review brief: the deploy credential spec |
| + |
| +You are Astra reviewing a design spec independently of its author. Your |
| +output is a findings report, not an edit. Do not modify any file. |
| + |
| +## What to read |
| + |
| +1. The spec under review: |
| + `docs/superpowers/specs/2026-10-05-deploy-credential-design.md`. |
| + §3's rulings R1 to R4 are fixed. Report a mechanism that fails one. Do |
| + not re-argue one. |
| +2. The code it fits into, in this worktree: |
| + - `internal/svcrole/svcrole.go` (roles, `Allow`, `Permits`); |
| + - `internal/console/authcli.go` (`cliRoute` near 411, the route table |
| + from 470 to 740, how a principal is resolved from a bearer token); |
| + - `internal/console/svcprincipal.go` (`Principal`, |
| + `NewServicePrincipal`, rotate, revoke) and |
| + `internal/console/authstore.go` (the `cli_tokens` schema near 183 to |
| + 255); |
| + - `internal/console/apicli.go` (`apiAccountAppBy` near 58, |
| + `handleAPIPromote` near 701, `handleAPIRollback` near 970, |
| + `handleAPIShip` near 1569); |
| + - `internal/console/controlplane.go` (`refuseServiceControlPlane`); |
| + - `internal/console/apiservices.go` and `internal/console/svcpage.go` |
| + (the two mint doors); |
| + - `internal/release/ladder.go`, `grant.go`, `signer.go`, `pipeline.go`, |
| + `serial.go`; |
| + - the CLI at the repo root: `apimode.go` (`resolveMode`), `auth.go`, |
| + `services.go`, `canary.go`, and the promote, rollback and ship verbs |
| + in `cli.go`; |
| + - `README.md` lines 100 to 185, and `docs/site/cli.md` around 1319 to |
| + 1440. |
| + |
| +## What matters most |
| + |
| +- **Escapes from the rung scope.** Look for any way a `deploy` credential |
| + moves a pointer outside its rungs: a channel name `release.Rung` maps |
| + unexpectedly, the proposal path, a pending approval it can create or |
| + execute, rollback's own paths, the hotfix flag, a pipelined app whose |
| + pipeline names a rung, a version-target or tag door, or any other door |
| + on the §6 list that writes more than the spec says. Check §7.1's order |
| + and §7.2's placement against the handlers as written. |
| +- **Doors.** Is §6's list complete for `carlos ship`, `promote`, |
| + `rollback` and `channels` in API mode as the CLI actually calls them? |
| + Does any door on the list expose or change more than a deploy pipeline |
| + needs? Is anything missing that makes the CLI fail? |
| +- **Mint and read-back (§5).** Can either mint door bypass the rules? Can |
| + rotate, or any other write to `cli_tokens`, produce a `deploy` row with |
| + no rungs or a non-`deploy` row with rungs? Is fail-closed at resolve |
| + achievable where the spec puts it? |
| +- **Mixed versions (§9).** Is "an old console refuses an unknown role at |
| + every door" true of `cliRoute` as written? Is there any path that |
| + resolves a service token without going through `cliRoute`, or treats an |
| + unknown role as something permissive? |
| +- **The CLI in CI (§8).** Does reading `CARLOS_SERVICE_TOKEN` in |
| + `resolveMode` collide with anything: the in-instance variable of the |
| + same name, box-side callers, `carlos auth` verbs, the `--owner` path? |
| + Is the refusal beside a store variable consistent with the existing |
| + `--console` ruling? |
| +- **§7.4's trade.** The limit moves from a grant every box verifies to a |
| + check in the console. Is the exposure stated honestly? Is there a cheap |
| + way to keep a box-side check that the spec missed, without breaking R3 |
| + or R4? |
| +- **Claims about the code.** Every `file:line` and every "already does" |
| + claim: check it at this commit. Report each one that is wrong. |
| + |
| +## How to report |
| + |
| +Number findings R1-1 onward. For each: severity (P1 breaks a trust |
| +guarantee or makes the design unbuildable; P2 a contract or claim defect |
| +to fix before the plan; P3 advisory), the section, the problem, the |
| +evidence with citations, a proposed correction. End with a verdict: |
| +accept, accept with corrections, or request changes. Do not soften, do |
| +not pad, do not restate the spec. |