From db954af13cc6e11e383c96844dced3ac69b28bc0 Mon Sep 17 00:00:00 2001 From: maxwellsantoro <35202769+maxwellsantoro@users.noreply.github.com> Date: Thu, 25 Jun 2026 00:25:18 -0400 Subject: [PATCH] docs: compress README public face + add GitHub hygiene files Opening identity becomes "an evidence-gated OS lab for agent-native computing". Add a compressed "Short Version" and promote the smoke proof to its own "Try the Smallest Proof" section; restructure contributor help into three tracks; surface a secondary Governance & Research section. Add SECURITY.md (vulnerability reporting + posture), CODE_OF_CONDUCT.md (Contributor Covenant 2.1), and GitHub issue/PR templates (bug, hardware-evidence, docs-confusion, pull request) so the public contribution flow matches the project's evidence discipline. CHANGELOG + DECISIONS entries. Docs-only: foundry gate skips on CI. --- .github/ISSUE_TEMPLATE/bug_report.md | 32 +++++ .github/ISSUE_TEMPLATE/docs_confusion.md | 21 +++ .../hardware_evidence_report.md | 33 +++++ .github/PULL_REQUEST_TEMPLATE.md | 37 +++++ CHANGELOG.md | 8 ++ CODE_OF_CONDUCT.md | 133 ++++++++++++++++++ DECISIONS.md | 14 +- README.md | 51 +++++-- SECURITY.md | 39 +++++ 9 files changed, 357 insertions(+), 11 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/docs_confusion.md create mode 100644 .github/ISSUE_TEMPLATE/hardware_evidence_report.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 SECURITY.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..6583145 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,32 @@ +--- +name: Bug report +about: A gate, build, or runtime path is not behaving as documented +title: "[bug] " +labels: bug +--- + +Thank you for taking the time to file a reproducible report. RamenOS favors +evidence-bearing reports over summaries — paste the actual output. + +**Which gate or command?** + + +**What did you expect?** + +**What happened instead?** + + +**Environment** +- OS / host: +- Rust toolchain (`rustc --version --verbose`): +- QEMU version (for target gates): +- OVMF / AVMF firmware source (for S0 / S2): + +**Evidence level involved** (see [EVIDENCE_LEVELS.md](../../EVIDENCE_LEVELS.md)) + + +**Reproducer** + + +**Claim boundary** + diff --git a/.github/ISSUE_TEMPLATE/docs_confusion.md b/.github/ISSUE_TEMPLATE/docs_confusion.md new file mode 100644 index 0000000..fed72a4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/docs_confusion.md @@ -0,0 +1,21 @@ +--- +name: Docs confusion +about: Report where the docs lost you, so we can compress them +title: "[docs] " +labels: documentation +--- + +RamenOS documentation aims to be falsifiable and compressed. If a section lost +you, this report helps us fix the funnel. + +**Where did you start?** + + +**What were you looking for?** + +**Where did it get unclear?** + + +**What did you expect to find?** + +**In one sentence: what is the single thing a new visitor should grasp in 30 seconds?** diff --git a/.github/ISSUE_TEMPLATE/hardware_evidence_report.md b/.github/ISSUE_TEMPLATE/hardware_evidence_report.md new file mode 100644 index 0000000..00902f6 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/hardware_evidence_report.md @@ -0,0 +1,33 @@ +--- +name: Hardware evidence report +about: Report HIL appliance behavior, a golden-machine run, or a provenance question +title: "[hil] " +--- + + + +**Claim level observed** + + +**claim_path** + + +**Appliance / target** +- Appliance id (if `RAMEN_HIL_APPLIANCE=1`): +- Target board / device: +- Controller evidence ref / log (with SHA256 if available): + +**Environment flags used** +- `RAMEN_HIL_APPLIANCE`= +- `RAMEN_HIL_GRADUATION`= +- `RAMEN_HIL_GOLDEN_MACHINE`= +- `RAMEN_HIL_SERIAL_DEV` / `RAMEN_HIL_SERIAL_LOG`= + +**Serial / power transcript** + + +**Provenance** + diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..6dbbb0e --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,37 @@ + + +## Summary + + + +## Pillar / slice + + + +## Evidence + + + +- Gate command(s): +- Result: +- Evidence level claimed (see EVIDENCE_LEVELS.md): + +## Claim-boundary check + +- [ ] Does not claim metal graduation, security readiness, or release readiness beyond its evidence. +- [ ] Any native-interface change went through `idl/` + `just codegen` (no hand-edited `*.generated.rs`). +- [ ] Preserves boundaries: kernel ≠ services ≠ store. + +## Docs + +- [ ] `CURRENT_STATUS.md` / `CHANGELOG.md` updated if a milestone landed. +- [ ] `DECISIONS.md` updated for any design choice or Constitution-affecting change. + +## Separation of duties + +PRs are opened by `ramen-implementer[bot]` (A2) and approved + merged by a +**different** identity (A3). Outside contributors: a maintainer will review and +merge your change. diff --git a/CHANGELOG.md b/CHANGELOG.md index 35c9926..528e1a3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,10 @@ ## [Unreleased] ### Changed +- Sharpened the public README identity to "an evidence-gated OS lab for + agent-native computing", added a compressed "Short Version" and a "Try the + Smallest Proof" framing, restructured contributor help into three tracks, and + surfaced a secondary Governance & Research note. - Made HIL metal evidence path-disclosing: per-gate HIL JSON now carries `claim_path` plus appliance metadata, and docs distinguish standalone `operator-golden-machine` PASS/METAL from `appliance-mediated` graduation. @@ -20,6 +24,10 @@ S13, HIL appliance, security, risk, and contributor documentation. ### Added +- Added root `SECURITY.md` (vulnerability reporting + posture), + `CODE_OF_CONDUCT.md` (Contributor Covenant 2.1), and GitHub issue/PR templates + (bug, hardware-evidence, docs-confusion, pull request) so the public + contribution flow matches the project's evidence discipline. - Added Foundry checks for per-gate HIL `claim_path` evidence and for the POSIX runner default sandbox profile contract. - G0 RamenOrg / research-backed OS scaffold: diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..8a83256 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,133 @@ +# Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the maintainers responsible for enforcement via +[https://maxwellsantoro.com](https://maxwellsantoro.com), or through the +repository's private reporting flow on the **Security** tab. All complaints will +be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/DECISIONS.md b/DECISIONS.md index 229f26d..58c3594 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -1,6 +1,6 @@ # DECISIONS (ADR-lite) -**Last Updated:** 2026-06-24 +**Last Updated:** 2026-06-25 **Status:** Active ## 2026-02-03 — Monorepo with hard boundaries @@ -411,3 +411,15 @@ serial capture emits `PASS/HIL-APPLIANCE`. **Authority boundary:** G0.8.1 is A2-local only and grants no merge, release, self-approval, HIL actuation, public support, credential, or identity-level role authority. + +## 2026-06-25 — Public identity is "evidence-gated OS lab"; governance surfaced secondarily +The README's opening identity is "RamenOS is an evidence-gated OS lab for +agent-native computing." We chose "OS lab" over the prior "Rust OS experiment" +to lead with the testable, evidence-gated nature of the project rather than the +implementation language; Rust remains visible in the workspace table, build +section, and badges. RamenOrg governance and the research program are now +surfaced as a single secondary "Governance and Research" section, kept strictly +parallel to the OS execution track and granting no merge, release, hardware, or +public-support authority on their own — the public hook stays OS-first while the +dual-product reality is stated honestly. This is a positioning decision, not a +technical or constitutional change. diff --git a/README.md b/README.md index e27ff23..153f02d 100644 --- a/README.md +++ b/README.md @@ -5,15 +5,14 @@ [![ci](https://github.com/maxwellsantoro/RamenOS/actions/workflows/ci.yml/badge.svg)](https://github.com/maxwellsantoro/RamenOS/actions/workflows/ci.yml) [![license: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](Cargo.toml) -**Last Updated:** 2026-06-24 +**Last Updated:** 2026-06-25 **Status:** Public pre-alpha, active development **Current focus:** hardware evidence loop, then persistent-storage graduation -RamenOS is an evidence-gated Rust OS experiment for agent-native computing. -Instead of making agents and applications drive Unix through screens, files, -shells, and ambient authority, RamenOS is building typed OS interfaces, -explicit capabilities, observable semantic state, and hardware support backed -by reproducible proof. +RamenOS is an evidence-gated OS lab for agent-native computing. Instead of +making agents drive Unix through screens, files, shells, and ambient authority, +RamenOS builds typed OS interfaces, explicit capabilities, and observable +semantic state — backed by reproducible proof. Founded by [Maxwell Santoro](https://maxwellsantoro.com). @@ -22,6 +21,19 @@ security readiness, or release readiness without matching evidence. The current default CI path proves QEMU and Foundry gates; physical hardware claims require explicit HIL evidence. +## The Short Version + +RamenOS is trying to prove a narrow, testable idea: agents should interact with +an OS through **typed capabilities** and **observable semantic state**, not by +driving a Unix desktop through shells, pixels, and ambient authority. + +The current repo proves the first pieces of that model in QEMU — boot, typed +IPC, trace emission, IDL contract gates, Store/service fail-closed paths, and +Driver Foundry replay loops. + +The next public milestone is **live hardware evidence** through the HIL +appliance. + ## Why This Exists The bet: future agents should not be trapped inside a human desktop metaphor. @@ -54,7 +66,10 @@ state allowed by that capability, and leave an auditable trail of effects. - Has hardware-in-the-loop appliance scaffolding, but no broad `PASS/METAL` claim yet. -The canonical public smoke proof is: +## Try the Smallest Proof + +This does not boot a daily-driver OS. It proves the current public baseline: +QEMU boot, init startup, typed IPC smoke behavior, and trace emission. ```bash git clone https://github.com/maxwellsantoro/RamenOS.git @@ -273,13 +288,27 @@ configuration. - **Gates and docs:** [tools/ci/](tools/ci/), [tools/hil/](tools/hil/), [docs/](docs/). +## Governance and Research + +This repository also hosts the **RamenOrg** governance scaffolding and the +research program. Both are kept strictly parallel to the OS execution track and +grant no merge, release, hardware, or public-support authority on their own. + +- Governance artifacts, the authority ladder, and the merge gate: [docs/org/](docs/org/). +- Research program and open questions: [docs/research/](docs/research/). + ## Contributing RamenOS favors small, evidence-bearing slices over large subsystem drops. -The most useful outside help right now is review and implementation support for -the S12.4 hardware evidence loop: serial observation, power/reset actuation, -and the claim boundaries around HIL appliance evidence. +### Useful help right now + +- **Serious systems help:** the S12.4 HIL appliance loop — serial observation, + power/reset actuation, and the claim boundaries around HIL appliance evidence. +- **Newcomer help:** run `just foundry-s0` on your machine and report any + host/QEMU/OVMF boot issues you hit. +- **Docs help:** tighten setup notes for macOS/Linux hardware combinations, and + flag anywhere the docs lose a new reader. Before proposing a change: @@ -300,6 +329,8 @@ to produce code whose observed behavior matches the Oracle, then gate it. - [CONSTITUTION.md](CONSTITUTION.md): project principles. - [EVIDENCE_LEVELS.md](EVIDENCE_LEVELS.md): claim/evidence vocabulary. - [SECURITY_STATUS.md](SECURITY_STATUS.md): security posture and boundaries. +- [SECURITY.md](SECURITY.md): how to report a vulnerability. +- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md): community standards. - [SLICES.md](SLICES.md): completed slice inventory. - [STORE_SPEC.md](STORE_SPEC.md): store platform contracts. - [CONTRIBUTING.md](CONTRIBUTING.md): local preflight and lint policy. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..93c6aa4 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,39 @@ +# Security Policy + +**Status:** Pre-alpha. RamenOS is **not** production software and makes **no** +security-readiness claim. Do not rely on it to protect untrusted workloads or +hardware. + +## Reporting a vulnerability + +**Do not open a public issue for a security problem.** Report privately via +GitHub's **Report a vulnerability** flow on the **Security** tab (private +vulnerability reporting / security advisories). If that channel is unavailable +to you, contact the maintainer through the profile linked in the README. + +Please include, as far as you can: + +- The affected component or gate. +- The evidence level the issue undermines (see [EVIDENCE_LEVELS.md](EVIDENCE_LEVELS.md)). +- A reproducer or gate command. +- The claim boundary it violates (e.g. a gate asserting more than its evidence). + +## Supported versions + +Only the `main` branch tip is in scope. There are **no tagged releases** and no +stable API/ABI. Pre-alpha means interfaces and behavior may change without notice. + +## Current posture + +RamenOS is pre-alpha. Foundational controls have landed — fail-closed defaults +across the Store, runner, wire-format, capability, and trace-isolation paths — +but **architectural risk remains** and no formal verification, independent audit, +or stable release threat model exists. + +- Current controls and residual risk: [SECURITY_STATUS.md](SECURITY_STATUS.md) +- Active risk register: [RISKS.md](RISKS.md) +- Claim/evidence vocabulary: [EVIDENCE_LEVELS.md](EVIDENCE_LEVELS.md) + +Treat any `PASS/QEMU` or replay result as **non-metal** evidence. The default +POSIX runner profile is host-portable rlimits-only; seccomp, namespaces, and +chroot are tested helpers, not current default containment.