# Proposal: Public Release and Maintainer Boundaries How capOS can become publicly visible without accidentally promising general support, production security, broad feature review, or an always-on community moderation role. ## Purpose Open-sourcing capOS should be a controlled publication step, not a commitment to operate a public support queue. The project can benefit from public inspection, reproducible demos, and selected outside contributions while still rejecting vague bug reports, low-effort questions, unsupported feature requests, and large drive-by changes. The first public release should optimize for: - accurate public claims, - narrow maintainer commitments, - security honesty, - reproducible build and QEMU evidence, - curated contribution paths. It should not optimize for community growth, support volume, or broad roadmap input. ## Release Position capOS should be described publicly as: - experimental research software, - x86_64/QEMU-first, - capability-system focused, - not production-ready, - not independently security-audited, - not suitable for hostile multi-user deployment, - not a supported general-purpose OS. Top-level public wording should be direct: ```md capOS is experimental research software. It has not undergone an independent security audit. Treat the current code as unsafe for production use, unsafe for hostile multi-user deployment, and unsuitable for protecting real secrets or availability-sensitive workloads. Security boundary documents in this repository describe design intent and current proof coverage, not certification or a guarantee of correctness. QEMU demos, host tests, model checks, and review notes are engineering evidence. ``` This statement belongs in `README.md` and `SECURITY.md` before the repository is made public. ## Non-Goals - No public support promise for local build environments. - No support guarantee for platforms beyond the documented QEMU path. - No expectation that maintainers answer questions already covered by docs. - No roadmap voting or feature-request queue. - No public chat server at launch. - No production-security claim. - No response-time SLA for ordinary issues or pull requests. - No acceptance of large unplanned subsystem PRs. ## Maintainer Load Model The initial public repository should run in source-visible mode: 1. The code, docs, and reproducible demo paths are public. 2. Issues are enabled only through strict templates. 3. Pull requests are allowed but scoped by contribution rules. 4. Discussions and chat are disabled at launch. 5. Maintainers publish a small set of curated tasks they are willing to review. Public visibility does not imply public support. Maintainers may close issues without extended discussion when they are: - usage questions answered by `README.md`, `docs/`, or command output; - vague bug reports without exact commands, commit hash, host/QEMU versions, or relevant log excerpts; - broad feature requests outside `docs/roadmap.md`; - requests to support unrelated platforms, package managers, or deployment environments; - debates about project direction without a concrete proposal; - large implementation PRs that did not start from an accepted design. Closed issues should usually receive one short reason and, when possible, a link to the relevant document. Maintainers should not spend review time rewriting low-quality reports into actionable work. ## Issue Intake The public repository should not allow blank issues at launch. Use issue templates for: - reproducible bug report, - QEMU transcript failure, - documentation problem, - design proposal, - private security report pointer. Bug reports should require: - capOS commit hash, - host OS and architecture, - QEMU version when QEMU is involved, - exact command run, - expected result, - actual result, - relevant bounded log excerpt. Default labels should include: - `needs-repro`, - `needs-design`, - `docs`, - `qemu`, - `security`, - `not-planned`, - `support-boundary`, - `maintainer-curated`, - `agent-assisted`, - `needs-human-owner`, - `agent-spam`, - `review-capacity`, - `too-large`. Suggested policy: - close `needs-repro` reports after 14 days without requested reproduction details; - close broad roadmap requests as `not-planned`; - convert recurring valid questions into documentation, then close later duplicates by linking the docs; - do not promise ordinary issue response times. Automated issue batches should be closed without triage when they are not attached to a concrete human-owned reproduction, design proposal, or patch. Large generated reports are not useful by themselves; they must be reduced to one actionable issue with exact evidence. ## Pull Request Intake Small fixes, regression tests, docs corrections, and narrow bug fixes may be accepted without prior design discussion when they fit existing architecture. Large changes should start as an accepted design proposal or maintainer-curated issue. This includes changes to: - kernel capability semantics, - schema or ABI, - userspace runtime behavior, - boot flow, - security boundaries, - dependencies, - hardware or architecture support, - public command surfaces, - persistent storage, - networking beyond the selected milestone. Every non-trivial PR should state: - motivation, - changed trust boundary or `docs-only`, - commands run, - QEMU proof when behavior is user-visible, - generated-code and dependency notes when relevant, - design proposal link for large changes. Maintainers may close unplanned large PRs without detailed review. That rule is necessary to avoid turning public visibility into unpaid architecture consulting. ## Agent-Assisted Contributors Public capOS will likely attract contributors using Claude Code, Codex, and similar tools to run long agent loops. That is acceptable only when the human owner remains accountable for the work. Agent-assisted work must: - disclose that automation was used; - have one human owner who understands the diff and can answer review questions; - stay attached to an accepted issue, proposal, or maintainer-curated task unless it is a narrow obvious fix; - include exact verification commands and relevant output summary; - preserve the repo's worktree, review, and security rules; - keep generated logs, prompts, transcripts, and local secrets out of the repository; - avoid opening batches of speculative issues or PRs from broad scans. Suggested public policy: - one active non-trivial PR per new external contributor by default; - no more than two active PRs per established external contributor unless a maintainer explicitly raises the limit; - agent-generated drive-by refactors, mass lint churn, dependency churn, or roadmap reshuffles are closed as `too-large` or `not-planned`; - PRs without a responsive human owner are closed as `needs-human-owner`; - repeated automated noise is labeled `agent-spam` and may be blocked at the account level. The merge rule still stays positive: a useful PR with the required review context, relevant verification, and no unresolved blocking findings should be merged. The throttles exist to protect review capacity, not to reject good work because an agent helped produce it. ## Review Capacity Maintainers should publish the current review mode in a pinned issue, project view, or `CONTRIBUTING.md` section: - `open`: accepting curated external work; - `limited`: reviewing only bugs, security reports, and maintainer-curated tasks; - `paused`: no new external PR review except private security reports. When review capacity is full: - new feature PRs may be closed as `review-capacity` without technical review; - stale `needs-repro` issues may be closed after the documented timeout; - stale `needs-changes` PRs may be closed after the maintainer-requested changes are not addressed; - emergency capacity is reserved for private security reports and regressions in documented release/demo paths; - public contributors should be pointed toward existing reviewed tasks instead of creating new backlog entries. Passing CI is evidence, not entitlement to review. The review bar remains `REVIEW.md`, useful project value, relevant verification, and no unresolved blocking findings. ## Workflow Transition The current private workflow uses local branches, dedicated worktrees, `WORKPLAN.md`, backlog files, and local review loops as the planning and review source of truth. That is appropriate while capOS is mostly private and agent-driven, but it is not the right public collaboration model forever. At some point after public release, the project should migrate public work to: - GitHub Issues for user-visible bugs, accepted design tasks, support-boundary closures, and curated contributor work; - GitHub Pull Requests for review, CI evidence, design-grounding notes, and merge decisions; - GitHub Projects for milestone planning, sequencing, and status views. That transition should replace roadmap/backlog-driven operational planning for public work. `docs/roadmap.md` should remain a high-level narrative roadmap, not the active task board. `docs/backlog/` should become design context and historical decomposition, not the queue maintainers are expected to triage by hand. The migration should not happen in the first quiet source-visible launch. It needs explicit gates: - issue templates and labels are stable enough to reject low-quality reports; - PR templates capture trust-boundary, verification, and design-grounding requirements; - CI exposes the baseline checks public contributors can run and cite as evidence; - `REVIEW.md` remains the merge bar: a useful PR with the required review context, relevant verification, and no unresolved blocking findings should be merged; - maintainers have decided which roadmap/backlog items become public issues; - a GitHub Project exists for the selected public milestone; - stale local backlog entries have been either converted to issues or marked as historical context; - private/security-sensitive planning remains outside public issues until the security policy says where it belongs. During the transition, avoid dual sources of truth. If a task is public and tracked in GitHub Projects, its active status should live there. Repo docs should link to the project or issue instead of duplicating the live state. ### Planning Source Migration Model The private planning files should migrate by role, not by copying their whole contents into GitHub: - `docs/roadmap.md` remains a narrative of visible outcomes and design order. It should name the current public milestone and link to the GitHub Project view, but it should not list every public task status. - `WORKPLAN.md` remains the private/operator scratchpad for local agent loops, security-sensitive tasks, and unreleased integration state. For public work, it should contain issue or PR URLs plus the reason the item is active, not a duplicate checklist. - `docs/backlog/` becomes design context, decomposition history, and migration notes. Actionable public tasks move to issues with one owner, acceptance criteria, verification gates, and links back to the relevant design/backlog section. - `REVIEW_FINDINGS.md` remains the private unresolved-review log until a finding is safe to disclose. Public findings become GitHub issues only after the security policy says disclosure is acceptable; the local finding should then link to the issue instead of restating live public status. Issue bodies should preserve the review discipline already used locally: problem statement, affected files or trust boundary, design-grounding links, expected proof command, QEMU or host-test acceptance criteria, and explicit non-goals. GitHub Projects should track only status and sequencing fields such as milestone, area, risk, owner, review mode, and blocked-by. The design rationale belongs in docs or issue discussion, not in project-card metadata. Before converting a backlog slice, maintainers should de-duplicate it against current docs and closed commits. A converted issue should be either: - a visible outcome that maps to a roadmap milestone; - a review finding with concrete remediation and verification; - a scoped implementation task under an accepted proposal; or - a documentation correction tied to a known drift point. Avoid migrating stale checklists verbatim. If an item has already landed, move the historical note to `docs/changelog.md` or leave it in commit history. If an item is still speculative design, keep it in the proposal/backlog until a maintainer is ready to review implementation. ## Communication Channels Launch with: - GitHub Issues for reproducible bugs and accepted work tracking; - pull requests for reviewable scoped changes; - private security contact from `SECURITY.md`. Do not launch with: - Discord, - Matrix, - Slack, - public support email, - office-hours promises, - GitHub Discussions unless maintainers explicitly budget moderation time. Chat systems create interrupt-driven support load and reward questions that should become docs or issue templates. They should wait until the project has a known moderation policy and enough maintainers to enforce it. ## Security Statement `SECURITY.md` should state: ```md # Security Policy capOS is experimental research software and has not undergone an independent security audit. Do not use it to protect real secrets, production workloads, or hostile multi-user environments. Security reports are still useful. Report suspected vulnerabilities privately to . Do not open public issues containing exploit details, private keys, tokens, credential material, or instructions for attacking third-party systems. At this stage, maintainers do not provide a security-fix SLA. Accepted reports are triaged based on project relevance, reproducibility, and impact on documented capOS security boundaries. ``` The security page should link to: - `docs/security/trust-boundaries.md`, - `docs/security/verification-workflow.md`, - `REVIEW_FINDINGS.md`, - `docs/trusted-build-inputs.md`. It should also distinguish security evidence from security assurance. Current checks, QEMU smokes, Kani proofs, Loom models, fuzz targets, and reviews are useful engineering evidence. They are not an independent audit. ## Repository Hygiene Gates Before public visibility: - add a license file; - add `CONTRIBUTING.md`; - add `SECURITY.md`; - add issue templates and a pull request template; - add top-level experimental/no-audit wording; - split the adventure game server, client, NPC processes, content generator, and proposal/backlog/demo docs out of this repository into a dedicated adventure repository before public visibility (see "Adventure Repository Split" below); - rewrite git history into a curated public-import history before publication (see "Git History Rewrite" below); do not publish the current private agent-driven commit log unchanged; - run a secret and history scan against the rewritten history, not just the current tree; - scan the rewritten history and the public tree for personal identifiers (maintainer GitHub account names, personal cloud project / bucket names, personal home-directory paths, personal email addresses, personal host or user names) and either remove the artifact or replace those values with neutral placeholders or environment-driven configuration; - remove or sanitize local operator infrastructure that is not part of the public OS: maintainer-private CI configs (for example `tools/cloudbuild-kani.yaml` GCS bucket names and project IAM references), maintainer-side agent-loop services and scripts (for example `systemd/capos-codex-ralph.service`, `scripts/codex-ralph-*`), and any other path that exists only because the current maintainer runs the project that way; - remove local-only artifacts from the public tree; - run the documented baseline checks; - create only maintainer-curated public starter issues. Local-only and generated artifacts need an explicit policy before publication. Source-controlled generated bindings are acceptable when freshness checks remain documented. Generated adventure content moves with the adventure split and is no longer a capOS-repository hygiene concern after the split lands. Local caches, build output, QEMU images, transient manifests, agent logs, maintainer-private cloud infrastructure configs, and agent-loop service units should not be part of a public source snapshot. ### Adventure Repository Split The Local MUD/adventure prototype, NPC-as-process fleet, Aurelian expedition content, save vault work, and contributor-quest framing exist primarily as a shared-service demo and as motivation for service-object capabilities and agent-shell tool surfaces. They are not part of the capability-OS core claim the first public capOS release should defend. Keeping adventure in the same public repository would: - conflate "experimental research OS" with "experimental research game", making the public scope statement and security boundaries harder to defend; - attract game-feature requests, balance debates, and content contributions through the same maintainer queue as kernel/capability/security issues; - pull narrative, world-building, and content-generation review onto the same review capacity that should be focused on capability semantics, schema/ABI, security boundaries, and the documented QEMU proofs; - expand the public attack surface and the public claim surface beyond what the OS work is ready to defend. Before the first public capOS release, adventure-specific code, content, generators, proposals, backlog, and demo docs must move to a dedicated adventure repository that depends on capOS as a downstream consumer. In the capOS repository, only the minimum hooks needed for capOS's own service-object and shared-service-demo proofs may remain, and they must be defensible without reference to game design. Concretely the split must, at minimum, relocate or remove: - `demos/adventure-server/`, `demos/adventure-client/`, `demos/adventure-content/`, `demos/adventure-chat-actors/`, `demos/adventure-npc-shopkeeper/`, `demos/adventure-npc-wanderer/`, `demos/adventure-scenario-test/`, and any future adventure-named demo crates; - `tools/adventure-content-gen/` and any adventure-specific generator fixtures or content blobs; - adventure-named manifests (for example `system-adventure.cue` and any derived `manifest-adventure.bin` / `capos-adventure.iso` build artifacts), `make run-adventure*` targets, and harness scripts that exist only to drive adventure demos; - adventure-only modes embedded in shared tooling -- for example the `drive adventure` / `assert adventure` modes in `tools/qemu-shell-smoke.sh` and any adventure-shaped output handling inside other shared `tools/qemu-*-smoke.sh` or `tools/qemu-*-harness.sh` scripts -- which must be removed from the core scripts and re-homed in the adventure repository; - adventure-specific build/check tooling such as `tools/check-generated-adventure-content.sh`, the `generated-adventure-content-check` Makefile target, and any adventure-named recipe stanzas, `MANIFEST_SOURCE`/`MANIFEST_BIN`/`ISO` overrides, and `.PHONY` entries (`run-adventure`, `generated-adventure-content-check`, etc.) that exist only to build or exercise adventure demos; - adventure entries in `DEPENDENCY_POLICY_MANIFESTS`/`LOCKFILES`, `cargo` workspace lists, and any other Makefile or CI list that names `tools/adventure-content-gen/` or adventure-named crates; - `docs/proposals/aurelian-frontier-proposal.md`, `docs/proposals/contributor-quest-mechanics-proposal.md` (when its scope is game-shaped), `docs/backlog/aurelian-frontier.md`, `docs/demos/adventure.md`, and any other adventure-shaped narrative or content docs; - adventure-specific entries in `WORKPLAN.md`, `docs/roadmap.md`, `REVIEW_FINDINGS.md`, and changelog narrative — keep only items that describe capability-OS invariants the core repository must continue to defend after the split. The adventure-files/paths/assets prohibition in the history-rewrite gate applies to all of the above. The split is not complete while adventure-only logic still lives in shared tooling under names that do not say "adventure" -- for example a generic-looking `drive` mode that in practice exists only to script adventure transcripts. A reviewed inventory of these shared-tooling crossings is part of the split task and must be cleared before the curated public-import history is built. The split must not silently weaken capOS's own proofs. Any adventure-anchored service-object, IPC, save-store, ledger, or chat-identity invariant currently enforced inside `kernel/`, `capos-config/`, `capos-rt/`, `init/`, or `shell/` and exercised only by an adventure demo needs an equivalent non-adventure proof in capOS before the adventure code leaves, or the invariant moves to the new repository together with its proof. A reviewed inventory of these crossings is a prerequisite of the split task, not a follow-up. The split is a release-time gate, not a routine refactor. Before it lands: - the new adventure repository must build against a tagged or pinned capOS reference so the cross-repo dependency direction is verified; - adventure-anchored capOS proofs must either be replaced by non-adventure equivalents or be moved to the adventure repository; - the public-release readme, security, and roadmap statements must reflect the narrowed capOS scope; - the rewritten public-import history (below) must not contain adventure-specific commits, paths, or assets. ### Git History Rewrite The current commit history was produced under a private agent-driven workflow with high commit volume, mid-task narrative messages, exploratory branches, intermediate worktree state, and adventure-shaped commits that no longer belong in capOS once the adventure split is enforced. Publishing that history unchanged would: - expose private workflow detail (worktree names, agent loop checkpoints, intermediate planning notes) that is not valuable to public readers; - make the public claim surface match every speculative direction explored privately, instead of the actual current capability-OS shape; - carry adventure-specific paths, assets, and commit messages into the OS repository the split is meant to leave behind; - complicate any future secret/history scan by mixing release-relevant history with disposable agent narrative. Before the first public release the maintainer must produce a curated public-import history. The acceptable approach is one of: - a single squashed initial-public-import commit on a fresh public branch, with a short message that describes the project state at publication and links to `docs/changelog.md` for historical milestone narrative; or - a small number of curated, signed commits that group related capability subsystems and proofs in a way that is reviewable by an outside reader, with the same forward link to the changelog. The rewritten history must: - contain no adventure-specific files, paths, generated content, or commit messages; - contain no agent-loop narrative, private worktree names, internal reviewer-only notes, or local-only artifacts; - contain no personal identifiers (maintainer GitHub account names, personal home-directory paths, personal cloud project / bucket names, personal email addresses, personal host or user names) in committed files, commit messages, author/committer fields beyond the maintainer's intended public attribution, or generated content; - pass a secret and history scan and a personal-identifier scan over the rewritten commits, not just the current tree; - carry an explicit license and attribution from the first public commit; - preserve `docs/changelog.md` as the narrative record of completed milestones and reviews so historical context is not lost when the raw commit history is collapsed. Force-pushing a rewritten history over an already-public branch is not the intended use of this gate. The rewrite happens before the repository becomes public. The current private repository may continue to exist as an internal mirror; only the rewritten history is published. ## Repository Composition The adventure split is the first concrete instance of a wider rule: the public capOS repository should defend a narrow, recognizable claim, and non-core tracks should live in downstream repositories that depend on capOS rather than ride along inside it. The detailed scope rule, the full list of split candidates (whitepaper, public website, userspace network stack, production remote-access services, protocol stacks, language runtimes, GPU, agent shell, cloud images, volume encryption), the when-to-split criteria, the cross-repository mechanics, and the intended `cap-os-dev` GitHub organization placement live in `docs/proposals/repository-composition-proposal.md`. For public-release readiness the only repository-composition gates are: - the adventure split (above) must be complete; - the rewritten public-import history (above) must respect the core/sibling scope rule defined in `docs/proposals/repository-composition-proposal.md`, so that no sibling-bound paths or assets enter the public capOS history; - public-facing READMEs, security pages, and roadmap statements must describe the narrowed core scope rather than the pre-split private workspace; - if the GitHub organization move to `cap-os-dev` happens before public release, the public-import history is published into that organization rather than into a personal account. Other splits described in the Repository Composition proposal happen on their own readiness timelines and are not public-release prerequisites. ## Launch Phases ### Phase A: Quiet Source-Visible Launch - Repository is public. - Issues use templates. - Discussions and chat remain disabled. - PRs are accepted only for narrow fixes or maintainer-curated work. - README and security pages make the experimental/no-audit status explicit. ### Phase B: Curated Contribution Phase - Publish a small list of tasks maintainers are willing to review. - Add `good-first-issue` only to tasks with enough context and an expected verification command. - Close unrelated feature requests instead of expanding the backlog. - Move repeated valid questions into docs. ### Phase C: Broader Community Phase Only after Phase A and B produce manageable signal: - consider GitHub Discussions; - consider a public chat room; - broaden accepted issue categories; - publish a maintainer rotation or moderation policy if more maintainers exist. This phase is optional. capOS can remain source-visible and selectively contribution-friendly indefinitely. ### Phase D: Hosted Public Demo A public WebShellGateway or Adventure Game deployment is a separate operational milestone, not a side effect of making the source repository public. A Reddit-scale traffic spike should be assumed before any public link is posted. The hosted demo must be treated as an untrusted public service: - demo sessions use guest-only or demo-only profiles; - no public demo path grants operator shell authority; - no public demo shell receives raw `BootPackage`, broad `ProcessSpawner`, provider-token, model-admin, storage-admin, or unrestricted network authority; - each browser session gets isolated caps, bounded resources, and deterministic teardown on logout, tab close, timeout, crash, or quota exhaustion; - sessions have maximum wall-clock duration, idle timeout, input/output byte limits, process/cap/resource quotas, and bounded transcript storage; - per-IP, per-session, and per-account rate limits exist before launch; - queueing and overload pages are preferred to silently starting unbounded VMs or capOS sessions; - maintainers have a kill switch that disables new sessions without affecting repository access; - logs are redacted and retention is documented; - the public page states that the demo is best-effort, may disappear, has no persistence guarantee, and is not a support channel. Adventure Game traffic adds game-specific gates: - anonymous players cannot mutate authoritative public world state; - public profiles, rewards, and contributor-quest identity links are opt-in; - saved state, if offered, goes through the reviewed `AdventureProfileService`, `AdventureLedger`, and `AdventureSaveStore` boundaries; - public multiplayer uses service-created player objects, not user-selected identity badges; - NPC or agent-assisted game features hold only narrow per-NPC or demo caps; - abuse reports and moderation controls exist before public chat-like features are exposed. The first hosted demo should be capacity-limited and disposable. It should not share credentials, sessions, storage, or authority with maintainer-operated development environments. ## Public Claim Checklist Public-facing docs should avoid claiming: - production readiness, - real-hardware support beyond documented experiments, - secure remote access, - independently audited security, - compatibility with ordinary OS workloads, - stable ABI, - stable contributor API, - support for every future roadmap track. They may claim only what current docs and verification support: - x86_64/QEMU-focused research OS; - typed capability interfaces; - capability-ring transport; - current shell/login demos; - selected service demos; - documented verification commands; - known limitations and future tracks. ## Design Grounding Grounding files for this proposal: - `README.md` - `WORKPLAN.md` - `REVIEW.md` - `REVIEW_FINDINGS.md` - `docs/roadmap.md` - `docs/proposals/aurelian-frontier-proposal.md` - `docs/proposals/boot-to-shell-proposal.md` - `docs/proposals/contributor-quest-mechanics-proposal.md` - `docs/proposals/llm-and-agent-proposal.md` - `docs/proposals/mdbook-docs-site-proposal.md` - `docs/proposals/repository-composition-proposal.md` - `docs/proposals/resource-accounting-proposal.md` - `docs/proposals/security-and-verification-proposal.md` - `docs/proposals/shell-proposal.md` - `docs/proposals/user-identity-and-policy-proposal.md` - `docs/backlog/aurelian-frontier.md` - `docs/backlog/runtime-network-shell.md` - `docs/security/trust-boundaries.md` - `docs/security/verification-workflow.md` - `docs/trusted-build-inputs.md` No `docs/research/` report is directly applicable. This proposal is release governance and maintainer-load policy layered on existing project docs, not a new OS architecture or runtime design.