Repository navigation
docs(specs): add the min box CLI spec (BCLI) for inbox#731 - #1991
Merged
Merged
Conversation
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. Walkthrough
Merge Risk:
 |
| Check name | Status | Explanation |
|---|---|---|
| Linked Issues check |  |
Check skipped because no linked issues were found for this pull request. |
| Out of Scope Changes check | |
Check skipped because no linked issues were found for this pull request. |
| Title check | |
The title follows Conventional Commit form (docs(specs): ...) and names the main change: adding the min box CLI spec (BCLI) for inbox#731. It is short, specific, and matches the single added spec file… |
| Description check | |
The description covers the purpose and scope of the spec. It explains why the document is split out of #1697, lists the spec id, requirement count, tiers, and what the spec owns, and names the depende… |
Full details: Title check
-
Explanation
The title follows Conventional Commit form (docs(specs): ...) and names the main change: adding the min box CLI spec (BCLI) for inbox#731. It is short, specific, and matches the single added spec file, so it is clearly related to the changeset.
Full details: Description check
-
Explanation
The description covers the purpose and scope of the spec. It explains why the document is split out of
#1697, lists the spec id, requirement count, tiers, and what the spec owns, and names the dependency on BOX (#1697). It links the epic stories (S10–S13 of gominimal/inbox#731) and reports the spec-lint result. It does not follow the template's headings. It has no '## Summary', '## Testing', or '## Checklist' sections. The Testing section lacks command output and only mentions spec-lint, and the checklist items (docs updated, BREAKING CHANGE footer) are not addressed. The content is mostly complete, so the check passes, but the template structure should be applied.
Finishing Touches
-
🧪 Generate unit tests (beta)
-
- Commit to this branch
- Create a new PR
-
- Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
A rabbit reads the box command page,
Then hops through verbs from stage to stage.
It guards each secret, keeps them hid,
And checks the hints for aliases slid.
The CLI spec is neatly laid;
The rabbit hops, content and glad.
CodeRabbit Verify
- Run CodeRabbit Verify to test the changes in this pull request.
ℹ️ Recent review info
-
⚙️ Run configuration
-
- Configuration used: Organization UI
- Review profile: CHILL
- Plan: Essentials
- Run ID:
09264cc2-9fad-4758-9c7f-ea87ebdb8618
📒 Files selected for processing (1)
-
docs/specs/28-spec-box-cli/28-spec-box-cli.md
🚧 Files skipped from review as they are similar to previous changes (1)
-
- docs/specs/28-spec-box-cli/28-spec-box-cli.md
Included review availability: This review used your included allowance. 4 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 5 reviews per hour.
ℹ️ Recent review info
-
⚙️ Run configuration
-
- Configuration used: Organization UI
- Review profile: CHILL
- Plan: Essentials
- Run ID:
09264cc2-9fad-4758-9c7f-ea87ebdb8618
📒 Files selected for processing (1)
-
docs/specs/28-spec-box-cli/28-spec-box-cli.md
🚧 Files skipped from review as they are similar to previous changes (1)
-
- docs/specs/28-spec-box-cli/28-spec-box-cli.md
Included review availability: This review used your included allowance. 4 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 5 reviews per hour.
-
Member
Author
|
/review |
Contributor
|
Reviewed: no findings; approval withheld, 3 threads unresolved at APPROVE withheld: 3 unresolved threads — norrietaylor docs/specs/28-spec-box-cli/28-spec-box-cli.md, norrietaylor docs/specs/28-spec-box-cli/28-spec-box-cli.md, norrietaylor docs/specs/28-spec-box-cli/28-spec-box-cli.md. Resolving the last thread releases the approval on this head. Resolve the open threads. Resolving the last one releases the approval on this head; no new review is required. Clobber: none: the file is new. |
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Contributor
Spec lint
Advisory. None of this blocks the merge; the review decides. Advisory, and never a merge gate. Linter: |
Member
Author
|
/review |
BCLI-001 prints the records BOX-158 lists, BCLI-003 renders the record BOX-159 returns, and BCLI-021 names each value's layer and type as BOX-161 reports them. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Member
Author
|
/review |
norrietaylor
reviewed
Oct 5, 2026
Contributor
There was a problem hiding this comment.
minimal-review — approval withheld
Verdict COMMENT — APPROVE withheld: 9 unresolved threads — norrietaylor docs/specs/28-spec-box-cli/28-spec-box-cli.md:15, norrietaylor docs/specs/28-spec-box-cli/28-spec-box-cli.md:28, norrietaylor docs/specs/28-spec-box-cli/28-spec-box-cli.md, norrietaylor docs/specs/28-spec-box-cli/28-spec-box-cli.md:71, norrietaylor docs/specs/28-spec-box-cli/28-spec-box-cli.md:82, …. 1 finding, 1 inline.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Member
Author
|
/review |
Contributor
There was a problem hiding this comment.
minimal-review — approval withheld
Verdict COMMENT — APPROVE withheld: 8 unresolved threads — norrietaylor docs/specs/28-spec-box-cli/28-spec-box-cli.md:15, norrietaylor docs/specs/28-spec-box-cli/28-spec-box-cli.md:28, norrietaylor docs/specs/28-spec-box-cli/28-spec-box-cli.md, norrietaylor docs/specs/28-spec-box-cli/28-spec-box-cli.md:71, norrietaylor docs/specs/28-spec-box-cli/28-spec-box-cli.md:82, …. No findings.
Member
Author
|
/review |
Drop the daily shortcuts (min shell, min run, min attach, min ls) in favour of the long forms and record them as a non-goal; retire BCLI-008, BCLI-031, BCLI-045, BCLI-054 and BCLI-065, which had no long form. Make BCLI-001's columns a floor, drop BCLI-018's per-type flags, list project types in BCLI-019, and raise BCLI-063 to T1 with a property. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
mitodrummer
force-pushed
the
docs/spec-box-cli
branch
from
October 5, 2026 22:28
b3d0cac to
7f7e600
Compare
Member
Author
|
/review |
BCLI-068 re-attaches a live PTY exec by id on the long form, with refusals for an unknown id (exit 4), a non-PTY exec (exit 2) and an ended exec (exit 4). BCLI-026 lists attach; Design reasoning and Open questions note min box attach as an architecture follow-up. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Member
Author
|
/review |
Member
Author
|
/review |
This was referenced Nov 3, 2026
Cite #2868 for the verbs with no owner, gominimal/arch#160 for the 124 row, gominimal/arch#161 for --no-hooks and --sync, and #2834 for both halves of BCLI-006, whose disk figure excludes Box Volumes (BVOL-008). From minimal-review on c4896c0: attach fails off a TTY before it resumes the box; a stop or removal ends an attach with 254, not 0; `session hooks <name>` resolves a box, never an entry; and an alias's window ends one release after its listed citers move, stated in the requirement as well as the Rollout. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NSAwDroXL6KqsSxUzdbZGw
… map short flags From minimal-review on 4b494ed: a failing alias under -o json puts its hint in BCLI-033's error object rather than a second stderr line, and a short flag (-n, -f) maps wherever its long form maps. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NSAwDroXL6KqsSxUzdbZGw
…it code From minimal-review on 990008d: `host stop` stops running boxes, so the bare `stop` alias is not a pure mapping. It checks for running boxes first and refuses with exit 2, keeping today's message byte for byte because the installer matches it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NSAwDroXL6KqsSxUzdbZGw
norrietaylor
requested changes
Nov 3, 2026
Member
There was a problem hiding this comment.
Thanks. Re-checked at 990008df4. Points 1, 2, 5, 6, 7 and 9 are fixed. Merging main instead of rebasing is fine: the branch is current and the spec diff is isolated. Two of the fixes introduce new problems, so I'm still requesting changes:
- BCLI-022's hooks sub-bullet (L193) can't pass against BOX as written. It makes
box spec <box>list each hook with "the loadout or project that declared it" from the stored spec. BOX doesn't keep that for a box. BOX-068 stores the expanded spec, in which BOX-064 mergeslifecycle_hooksfrom every layer into one list. BOX-161 reports layer provenance only when an entry is expanded, never in the spec's bytes, and it names a layer, not a particular loadout. Sobox_spec_box_lists_hooks_with_declarerneeds a BOX amendment. Either list that amendment in Rollout or drop the declarer column. Todaysession hooksgets it from the daemon's saved composition snapshot (11-spec-lifecycle-hooks:324). - The alias expiry gate (L451, L579-586) doesn't cover the e2e scripts. Expiry waits on the requirements and scripts Rollout lists, but scripts are listed only for bare
min stop.scripts/session-e2e.shalone callssession activate262×,destroy203×,exec385×,policy82×,rename11× andhooks3×.bulk-upload-e2e.sh,stress-session-e2e.shandkernel-bump-review.shcallactivateanddestroytoo.session renamehas no Rollout entry at all. As written, an alias can expire while the VM-lane session proof that BCLI-049's verify line runs still uses it.
Smaller:
- L439: "The networking and egress-proxy specs define the values of each flag" holds only for
--deny-all-egress(NET) and--credentialed-upstream(BEP).--dynamic-ingress,--dynamic-range,--allow-subnets,--allow-dns-hosts,--allow-protocolsand--deny-subnetsaren't named in any other spec, and NET defines only the keys. State the flag-to-key mapping here,--dynamic-rangeespecially, soactivate_alias_maps_network_policy_flags_to_override_layerhas something to check. - L428/L447,
session destroy:--allis now refused as an unmapped flag, andbulk-upload-e2e.sh:141,338usessession destroy --all --force … || truefor cleanup. Today's--forcealso treats an already-destroyed session as success (cli.rs:1124), which BCLI-064 turns into exit 4. Map both, or list them in Rollout. - L428,
session hookshint: say that the hint names the box id.min box spec <name>resolves the entry form first (L190) and would show the entry's hooks, not the box's. - L307-308: the "parse before address resolution" order that settles BCLI-064 vs BCLI-042 lives only in an HTML comment. Put it in the requirement text.
- minimal-foundry's two newest threads (L217 BCLI-026's missing
--exec/--timeout, and L428 the barestoprefusal's exit code) have no reply yet.
From minimal-review on ef58775: BCLI-029 closed stdin on every unattached start, including the `start --detach` that a plain `session activate` now maps to, which would leave a later attach unable to type. The close now applies only without `pty_enabled`. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NSAwDroXL6KqsSxUzdbZGw
Contributor
There was a problem hiding this comment.
minimal-review — approval withheld
Verdict COMMENT — APPROVE withheld: 3 unresolved threads — norrietaylor docs/specs/28-spec-box-cli/28-spec-box-cli.md, norrietaylor docs/specs/28-spec-box-cli/28-spec-box-cli.md, norrietaylor docs/specs/28-spec-box-cli/28-spec-box-cli.md. No findings.
Panel: 3 of 3 personas ran (correctness, security, supply-chain).
- BCLI-022 lists hooks without a declarer: BOX-068 stores the merged expanded spec, so the record keeps none. Open question for the BOX amendment that would restore it. - Rollout lists the scripts each alias's window waits on, session-e2e.sh among them, and gains `session rename`. - The activate alias's network flags each name the spec key they set. - `session destroy --all` and `--force` on a missing box keep today's behaviour through the window. - The `session hooks` hint names the box id. - BCLI-064 states the parse-first order in its text. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NSAwDroXL6KqsSxUzdbZGw
Member
Author
|
Thanks, Norrie. All of this is in 1bd4c43.
Smaller:
The spec linter reports only P004. The requirement count is unchanged at 62. |
…t prune --dry-run From minimal-review on 1bd4c43: `session destroy --all` now removes only boxes of type `session`, as BCLI-030 filters the session verbs; a dry-run prune needs no --yes off a TTY; and the design reasoning no longer claims `box spec` shows each hook's declarer. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NSAwDroXL6KqsSxUzdbZGw
From minimal-review on b3d698f: an ended exec without a PTY matched the exit 2 and both exit 4 rules. The unknown-id check now comes first, then the ended exec, then the live exec with no PTY. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NSAwDroXL6KqsSxUzdbZGw
Contributor
There was a problem hiding this comment.
minimal-review — approval withheld
Verdict COMMENT — APPROVE withheld: 3 unresolved threads — norrietaylor docs/specs/28-spec-box-cli/28-spec-box-cli.md, norrietaylor docs/specs/28-spec-box-cli/28-spec-box-cli.md, norrietaylor docs/specs/28-spec-box-cli/28-spec-box-cli.md. No findings.
Panel: 3 of 3 personas ran (correctness, security, supply-chain).
norrietaylor
approved these changes
Nov 3, 2026
Member
|
A Rollout note from NET's amendment, #2679. After #2679, NET-058 binds VM resolution by box name to This PR merged first, so #2679 lands second and updates this spec's Rollout list itself. It adds NET-058 to the |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Split out of #1697 so the BOX model spec can land on its own. The document is byte-identical to the one that was on that branch at d8b1e23, where it went through the same spec-author checkpoints, the review-fix loop, and the CodeRabbit and minimal-foundry threads recorded there.
docs/specs/28-spec-box-climin boxverb set (withmin box attach --execfor re-attaching a PTY exec) and type nouns, exec flags, output schemas and machine-mode errors, the exit-code table, the one-release alias window (min sessionspellings canonicalise and expire;session destroy→box rm --force;session policykept as an alias since NET-061/GWI-003 cite it), docs,min hostandmin provider. Daily shortcuts are a non-goal. Each requirement binds to a BOX operation by id.Depends on BOX (#1697): every requirement binds to a BOX operation. Lands after #1697, so the model ships first, the grammar migration is scheduled and reviewed separately, and a non-CLI client binds to the model.
Epic stories: S10–S13 of gominimal/inbox#731.
spec-lintreports onlyP004, one per named test that does not exist yet.🤖 Generated with Claude Code
Summary by CodeRabbit
minCLI, covering box lifecycle and execution, address resolution, initialization, terminal access, network overrides, and host shutdown.