Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 26 additions & 33 deletions docs/roadmap-decisions.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Roadmap decisions and implementation queue

Status date: **2026-09-19**
Status date: **2026-09-25**

This document records maintainer decisions for the remaining roadmap items in
issue #2. These decisions are authoritative scope for implementation work unless
Expand All @@ -14,16 +14,16 @@ items from being repeatedly rediscovered as if they were immediately actionable.
| Item | Decision | Implementation status / trigger |
|---|---|---|
| RM-24 Python / uv | **Keep both** | Decision complete. Built-in `python`/`pip` keep the dedicated Python provider; `uv`/`uvx` remain separate opt-in stateful profiles. |
| RM-26 Python global CLI exposure | **pipx yes; plain pip expose no** | Ready. Add a separate stateful pipx profile and managed pipx tool store; do not globally expose project/compat `/venv/bin` from plain pip. Generic shared-volume exposure already shipped. |
| RM-26 Python global CLI exposure | **pipx yes; plain pip expose no** | Completed in PR #74. The separate stateful pipx profile and managed store shipped; project/compat `/venv/bin` remains intentionally unexposed. |
| RM-34 Cargo expose enhancement | **Intentionally deferred** | Existing expose-all and explicit binary selection are sufficient. Reopen only for a concrete unmet use case. |
| WSL2 | **Native WSL frontend** | Ready for design/implementation slices. Native Linux `cb`/shims inside WSL use Docker Desktop WSL integration. No Windows↔WSL path/state guessing. |
| Enterprise policy | **Machine-owned constraint layer** | Ready. Separate administrator policy validates the resolved user/project/CLI request and can only restrict, never be weakened by lower layers. |
| Image trust | **Policy-driven Sigstore/cosign at lock time** | Ready after enterprise-policy foundation. Digest locking remains default where policy permits. Required trust never silently falls back to digest-only. |
| Per-project overlays | **Explicit digest-bound, add-only trust model** | Ready after enterprise-policy foundation. Initial overlays exclude host mounts, env prefixes and shared cross-project volumes. |
| WSL2 | **Native WSL frontend** | Host boundary shipped in PR #77. Native layout, Docker Desktop WSL integration and real WSL qualification remain. No Windows↔WSL path/state guessing. |
| Enterprise policy | **Machine-owned constraint layer** | Foundation shipped in PR #75. Authenticated registry and image-trust follow-ups must extend this boundary and cannot be weakened by lower layers. |
| Image trust | **Policy-driven Sigstore/cosign at lock time** | Ready after signed-registry policy. Digest locking remains default where policy permits. Required trust never silently falls back to digest-only. |
| Per-project overlays | **Explicit digest-bound, add-only trust model** | Implementation-ready on the merged policy foundation. Initial overlays exclude host mounts, env prefixes and shared cross-project volumes. |
| Plugin/provider architecture | **Intentionally deferred** | Reopen only after at least two concrete integrations cannot be expressed safely by the declarative model. |
| RM-31 self-update | **Explicit transactional, attestation-verifying update** | Ready after command/API slicing. Initial provenance verifier is `gh attestation verify`; Windows apply uses a post-exit helper and complete managed-set rollback. |
| RM-31 self-update | **Explicit transactional, attestation-verifying update** | Selection/check foundation shipped in PR #76. Staging, `gh attestation verify`, Windows apply, complete managed-set rollback and E2E remain. |
| RM-30 Authenticode | **Design accepted; externally blocked** | Implement only after a real code-signing certificate and protected signing mechanism exist. Stable and prerelease release artifacts are both signed. |
| RM-29 Windows ARM64 | **Lowest priority** | Native GitHub Windows ARM64 CI may be added later. Full support remains blocked on real Windows-on-Arm + Docker Desktop qualification. Do not delay other roadmap work. |
| RM-29 Windows ARM64 | **Lowest priority** | Native GitHub Windows ARM64 CI shipped in PR #78. Release packaging, ARM64 self-update selection and real Windows-on-Arm + Docker Desktop qualification remain. Do not delay other roadmap work. |
| Standalone Linux/macOS | **Demand-gated** | No support claim yet. WSL should create reusable narrow Linux host abstractions, but standalone hosts require their own contract and real Docker qualification. |
| RM-23 8.3 mount alias | **Intentionally deferred** | Current comma-path rejection remains supported behavior. Reopen only on demonstrated user demand. |
| RM-19 reserved-name migration | **Conditionally deferred** | Implement only when a future release actually proposes reserving a previously legal name. |
Expand Down Expand Up @@ -196,9 +196,9 @@ and protected signing mechanism.

### RM-29 — Windows ARM64 is last priority

Native Windows ARM64 CI may use GitHub-hosted Windows 11 ARM64 runners for
build, native management-command execution, filesystem/shim behavior and other
non-Docker qualification.
PR #78 added native Windows ARM64 CI on GitHub-hosted Windows 11 ARM64 runners
for build, native management-command execution, filesystem/shim behavior and
other non-Docker qualification.

x64-host ARM emulation is not accepted as Docker Desktop support evidence.
Full support still requires real Windows-on-Arm hardware running a supported
Expand Down Expand Up @@ -251,57 +251,50 @@ exception, expiry and outage policy.

This is priority/order guidance, not permission to merge.

1. **RM-26 pipx support**
- add a stateful pipx profile with explicit ContainerBin-owned home/bin state;
- add `cb expose pipx BINARY...`;
- add positive/negative Windows + Docker Desktop E2E;
- document the pip vs pipx vs uv-tool contract.
Merged foundations are removed from the remaining queue: RM-26 shipped in PR
#74, enterprise-policy foundation in PR #75, RM-31 selection/check in PR #76,
the WSL host boundary in PR #77, and native Windows ARM64 CI in PR #78.
Unmerged pull-request coverage is not completion.

2. **Enterprise policy foundation**
- fixed machine policy location + ownership validation;
- policy schema/versioning and stable diagnostics;
- effective-request authorization boundary;
- repository-origin allowlisting and mandatory-lock enforcement;
- diagnostics/inspect visibility.

3. **Per-project overlay trust foundation**
1. **Per-project overlay trust foundation**
- project overlay parsing independent of global registry;
- add-only collision rules;
- external trust store bound to canonical root + overlay digest;
- `cb trust` / `cb untrust` / inspect/doctor;
- initial restricted capability set.

4. **Registry-signature enterprise policy**
2. **Registry-signature enterprise policy**
- detached Ed25519 signature envelope over exact registry bytes;
- trusted-key rotation/revocation policy;
- verify before parsing/acting on registry content.

5. **Image trust**
3. **Image trust**
- cosign verifier configuration and verifier hash validation;
- per-repository trust policy;
- lock schema/evidence migration;
- online/offline verification and stale-evidence behavior.

6. **RM-31 self-update**
- selection/check/dry-run API;
4. **Remaining RM-31 self-update**
- selection/check/dry-run API is merged in PR #76;
- bounded canonical GitHub release download/staging;
- `gh attestation verify` policy integration;
- Windows helper transaction, managed-shim reconciliation and rollback;
- release/self-test E2E.

7. **WSL2**
- narrow reusable Linux host interfaces;
5. **Remaining WSL2**
- narrow reusable Linux host interfaces and fail-closed boundary are merged in PR #77;
- native WSL config/shim/state layout;
- Docker Desktop WSL integration;
- project identity and cross-boundary rejection tests;
- real WSL Docker E2E.

8. **RM-30 Authenticode**
6. **RM-30 Authenticode**
- only after certificate/protected signing prerequisites exist.

9. **RM-29 Windows ARM64**
7. **RM-29 Windows ARM64**
- **lowest priority**;
- native hosted ARM64 CI may precede real Docker qualification;
- native hosted ARM64 CI is merged in PR #78;
- architecture-specific release packaging and self-update selection remain;
- support claim only after real Windows-on-Arm + Docker Desktop E2E.

## Dormant / recurring items
Expand Down
82 changes: 57 additions & 25 deletions docs/roadmap-implementation-requirements.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,14 @@ ready items. Requirements below remain useful acceptance detail, but an older
"decision required" sentence must not be interpreted as reopening an accepted
decision.

Status snapshot: **2026-09-19**. The earlier 2026-09-17 snapshot counted every
Status snapshot: **2026-09-25**. The earlier 2026-09-17 snapshot counted every
unchecked roadmap line as unfinished work; that is no longer an accurate model.
Several items have since shipped, while the maintainer has explicitly accepted
product/security dispositions for the remaining design gates. Use the readiness
table below plus [roadmap-decisions.md](roadmap-decisions.md), not checkbox count,
to decide whether work is actionable.
RM-26 pipx, the enterprise-policy foundation, the RM-31 selection/check slice,
the WSL host boundary, and native Windows ARM64 CI have since shipped. The
maintainer has also explicitly accepted product/security dispositions for the
remaining design gates. Use the readiness table below plus
[roadmap-decisions.md](roadmap-decisions.md), not checkbox count or unmerged pull
request coverage, to decide whether work is actionable.

## Requirements that apply to every item

Expand Down Expand Up @@ -66,17 +68,17 @@ The minimum delivery gate for a code change is:
| RM-19 reserved-name migration | **Conditionally deferred** | Wake only when a future release proposes reserving a name accepted by a published older release |
| RM-23 8.3 path alias | **Intentionally deferred** | Keep explicit comma-path rejection; reconsider only on demonstrated user demand |
| RM-24 Python/uv provider choice | **Decision complete — keep both** | No provider migration; Python provider and uv/uvx remain separate |
| RM-26 Python global CLI exposure | **Implementation-ready** | Add stateful pipx + `cb expose pipx`; plain pip `/venv/bin` is not globally exposed |
| RM-29 Windows ARM64 | **Lowest priority / hardware-gated for full support** | Native hosted ARM64 CI may come later; official support requires real Windows-on-Arm + Docker Desktop E2E |
| RM-26 Python global CLI exposure | **Completed in PR #74** | Stateful pipx + `cb expose pipx` shipped; plain pip `/venv/bin` remains intentionally unexposed |
| RM-29 Windows ARM64 | **Native CI shipped / release and hardware work remain** | PR #78 added native hosted ARM64 CI; release packaging, ARM64 self-update selection, and real Windows-on-Arm + Docker Desktop E2E remain |
| RM-30 Authenticode | **Design complete / externally blocked** | Provision real code-signing certificate and protected signing mechanism |
| RM-31 self-update | **Design complete / implementation-ready** | Implement explicit attestation-verifying transactional update in reviewable slices |
| RM-31 self-update | **Selection/check foundation shipped** | PR #76 shipped selection/check behavior; staging, verification, transactional apply and E2E remain |
| RM-34 Cargo expose enhancement | **Intentionally deferred** | Existing expose-all/explicit selection are sufficient; reopen only for concrete unmet use case |
| Linux/macOS hosts | **Demand-gated** | WSL may factor reusable Linux host code; standalone support needs its own demand and qualification |
| Enterprise policy | **Design complete / implementation-ready** | Implement machine-owned constraint layer first |
| Image trust | **Design complete / sequenced** | Implement after enterprise-policy foundation using policy-driven Sigstore/cosign verification |
| Enterprise policy | **Foundation shipped / signed registry remains** | PR #75 shipped the machine-owned constraint layer; authenticated registry and image-trust slices remain |
| Image trust | **Design complete / sequenced** | Implement after signed-registry policy using policy-driven Sigstore/cosign verification |
| Plugin/provider architecture | **Intentionally deferred** | Reopen only after at least two real integrations cannot fit the declarative model |
| WSL2 | **Design complete / implementation-ready** | Native WSL frontend using Docker Desktop WSL integration |
| Per-project overlays | **Design complete / sequenced** | Implement add-only digest-bound trust model after enterprise-policy foundation |
| WSL2 | **Host boundary shipped / implementation remaining** | PR #77 shipped the fail-closed host boundary; native layout, Docker Desktop integration and real WSL qualification remain |
| Per-project overlays | **Design complete / implementation-ready** | Implement add-only digest-bound trust model on the merged enterprise-policy foundation |
| Release SBOM | **Conditionally deferred** | Trigger on shipped third-party/runtime dependencies or concrete compliance/consumer demand |
| Snyk | **Conditionally deferred** | Trigger only for a real coverage gap plus owner/account/token and triage/outage policy |
| Issue #69 | **Completed** | Superseded by merged implementation; no remaining roadmap dependency |
Expand Down Expand Up @@ -213,13 +215,16 @@ selection.
Likely areas: provider assembly in `internal/dockerrun`, default registry,
registry migration, state/backup logic, self-test and Python documentation.

## RM-26 — pipx global CLI exposure (remaining work)
## RM-26 — pipx global CLI exposure — completed

The provider-neutral shared-volume primitive shipped in PR #72 as
`cb expose --shared-file`. The accepted remaining Python scope is narrower:
`cb expose --shared-file`. The accepted Python scope then shipped in PR #74:
plain pip environments are dependency environments and are not a source for
global exposed shims; pipx is the classic-Python global application store.

The requirements and acceptance evidence below are retained as the shipped
contract, not as remaining implementation work.

### pipx requirements

- Add a separate stateful pipx profile with explicit ContainerBin-owned
Expand Down Expand Up @@ -306,6 +311,13 @@ Cross-compilation proves only that Go can emit a PE file. Support may be
claimed only after qualification on real Windows ARM64 hardware running Docker
Desktop in Linux-container mode.

PR #78 shipped native hosted ARM64 CI for non-Docker qualification. It did not
add ARM64 release assets, and PR #76's self-update foundation deliberately
rejects architectures other than Windows/amd64. The release matrix,
architecture-specific packaging and update selection below therefore remain,
along with real Windows-on-Arm + Docker Desktop qualification. Passing native
management-command CI alone is not a full support claim.

### Required implementation

- Add an explicit `windows/arm64` release matrix entry and an unambiguous asset
Expand Down Expand Up @@ -378,6 +390,12 @@ separate phases with explicit boundaries. GitHub documents both
[release asset downloads](https://docs.github.com/en/rest/releases/assets)
and [artifact-attestation verification](https://docs.github.com/en/actions/concepts/security/artifact-attestations).

PR #76 shipped the command surface, release selection, check/dry-run behavior,
strict Windows/amd64 asset selection and bounded metadata rules. Unsupported
architectures still fail closed. Download staging, provenance verification,
transactional Windows apply, rollback, broader architecture support and release
E2E remain incomplete until their implementations merge.

### Command and selection requirements

- Provide a dry-run/check mode that reports current version, selected target,
Expand Down Expand Up @@ -456,8 +474,15 @@ matrix, backup/restore and release qualification exist for that host.

## Enterprise policy controls

Implement policy before individual switches so precedence cannot be bypassed
by later features.
PR #75 shipped the machine-owned policy foundation: fixed policy location and
ownership checks, schema/versioning, stable diagnostics, effective-request
authorization, repository/image allowlisting, mandatory lock enforcement, and
diagnostics. Lower-precedence configuration cannot weaken that policy.

Authenticated registry files and image trust remain separate follow-up slices.
Host-mount/environment restrictions are not part of schema 1 and are not
implied by the merged foundation. Follow-ups must extend the merged policy
boundary rather than introducing a parallel precedence model.

### Required policy model

Expand Down Expand Up @@ -540,6 +565,10 @@ distribution and Docker Desktop's supported WSL integration. Windows `cb.exe`
interop and a Windows client talking to a Docker engine exposed by WSL are not
the supported WSL models.

PR #77 shipped the fail-closed host runtime boundary and explicit Windows/WSL
separation. Native Linux config/shim/state layout, Docker Desktop WSL
integration, project behavior and real WSL qualification remain.

Implementation must define native config/shim location, Docker endpoint,
project identity, named-volume behavior, file permissions, case sensitivity,
symlinks, stdin/TTY/signals and mixed-invocation rejection. Windows and WSL do
Expand Down Expand Up @@ -618,15 +647,18 @@ implementation task in this roadmap document.

## Recommended implementation order

1. RM-26 pipx support.
2. Enterprise-policy foundation.
3. Per-project overlay trust foundation.
4. Signed-registry enterprise policy.
5. Image trust at lock time.
6. RM-31 transactional self-update.
7. WSL2 native frontend.
8. RM-30 Authenticode only after certificate/protected-signing prerequisites exist.
9. RM-29 Windows ARM64 last; do not delay higher-value work for it.
Merged foundations are not remaining queue entries: RM-26 shipped in PR #74,
enterprise-policy foundation in PR #75, RM-31 selection/check in PR #76, the
WSL host boundary in PR #77, and native Windows ARM64 CI in PR #78.

1. Per-project overlay trust foundation.
2. Signed-registry enterprise policy.
3. Image trust at lock time, after signed-registry policy merges.
4. Remaining RM-31 staging, verification, transactional apply and E2E.
5. Remaining WSL2 native layout, Docker Desktop integration and real E2E.
6. RM-30 Authenticode only after certificate/protected-signing prerequisites exist.
7. RM-29 real Windows-on-Arm + Docker Desktop qualification last; do not delay
higher-value work for it.

RM-19, RM-23, RM-34, standalone Linux/macOS, plugins, SBOM and Snyk are dormant
until their documented triggers occur. The govulncheck pin is recurring
Expand Down
Loading