diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 396367f..a48bcd4 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,54 +1,70 @@ -Use the GitHub issue body as the complete source of truth. +# Copilot coding-agent instructions — source-os -Copilot is the primary executor for bounded issue-first PR work in this repository. The issue body must contain the full task, acceptance criteria, validation commands, and non-goals before assignment. Do not rely on later comments as required context. +## Guiding principle -Before editing: +Use the GitHub issue body as the source of truth for every task. +Do not infer scope beyond what the issue explicitly states. -1. Read the issue body. -2. Inspect the repository. -3. Identify existing validation commands. -4. Keep the PR bounded to the issue scope. +## Workflow rules -When implementing: +1. **Issue-first.** Every change must trace back to an open GitHub issue in this + repository. Do not open PRs without a corresponding issue. +2. **Bounded PRs.** One PR addresses one issue. Do not bundle unrelated fixes, + refactors, or improvements into the same PR. +3. **Validation evidence required.** Every PR body must include the exact + commands that were run, their pass/fail output, and any known gaps. +4. **No unrelated changes.** Do not modify files that are not directly required + to satisfy the acceptance criteria in the issue. -- Prefer existing repository patterns. -- Add tests, fixtures, validators, or documentation with the implementation when appropriate. -- Keep generated files only if repository conventions require them. -- Do not modify unrelated workflows or policy files. -- Do not touch unrelated repositories. -- Do not broaden scope without asking in the issue. -- Do not claim production readiness unless the issue explicitly requests and acceptance criteria prove it. -- Open one PR against the default branch unless the issue explicitly says otherwise. +## High-risk paths — mandatory human review before merge -When opening the PR: +Changes touching any of the following paths require an explicit maintainer +review and approval before merging: -- Link the issue. -- Include what changed. -- Include exact validation commands run. -- Include pass/fail output summary. -- List known gaps. -- State non-goals preserved. -- State anything blocked. -- Do not mark ready if validation did not run. +| Path / pattern | Risk category | +|---|---| +| `hosts/` | Host-role mutation | +| `images/` | Image build definitions | +| `profiles/` | NixOS profile definitions | +| `modules/` | Shared NixOS modules | +| `builders/` | Builder configuration | +| `flake.nix`, `flake.lock` | Flake root / dependency lock | +| `scripts/install*`, `scripts/enable*` | Install / provisioning scripts | +| `*.service`, `*.timer`, `*.preset` | systemd units | +| `ebpf/` | eBPF programs (kernel boundary) | +| `runtime/` | Runtime admission and cap-checker | +| `.github/workflows/` | CI/CD workflows | +| `configs/` | Host and channel configuration | +| `channels/` | Channel promotion config | -Delivery evidence: +## SourceOS-specific boundaries -- A PR, branch, commit, or merge must exist in GitHub to count as delivery. -- Comments, local task summaries, and draft notes are not delivery artifacts by themselves. -- If blocked from creating a PR, report the blocker clearly on the issue. +- **Boot / install / recovery paths** (`hosts/`, `images/`, scripts that write + to `/etc/` or `/boot/`): changes must be syntax-checked and smoke-tested + before the PR is opened. Claim no production readiness unless a full + integration test has been run. +- **Host mutation** (`profiles/`, `modules/`): Nix expressions must evaluate + cleanly (`nix flake check` or equivalent) before merging. +- **Workflows** (`.github/workflows/`): only modify if strictly required to + validate the work in scope. Document the reason in the PR body. +- **Runtime admission** (`runtime/`, `ebpf/`): capability and policy changes + must include a quorum/anchor smoke test result. -SourceOS-specific boundaries: +## PR body template -- Be conservative around boot, install, recovery, host mutation, release automation, and runtime admission. -- Do not change privileged workflows unless the issue explicitly asks for workflow work. -- Do not add secrets, credentials, private keys, tokens, or signing material. -- Keep Mac-on-Linux workstation work bounded to documented GNOME defaults, helper scripts, validation helpers, package declarations, and docs unless the issue explicitly requests deeper changes. -- Distinguish active behavior from future or proposed parity claims. -- Preserve existing JSON contracts unless the issue explicitly requests a schema change. +``` +## What changed + -Validation expectations: +## Commands run + -- Run repo-native validation when available. -- For shell scripts, run `bash -n` and any existing smoke workflows/tests relevant to the changed path. -- For JSON examples or schemas, run `python3 -m json.tool` or repo-native schema validation. -- If a validation command cannot run, explain why and include the error. +## Output summary + + +## Known gaps + + +## Blocked on + +``` diff --git a/AGENTS.md b/AGENTS.md index 4eaf5a1..4d2784a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,73 +1,83 @@ -# Agent Operating Instructions +# AGENTS — source-os operating instructions -Work issue-first. +## Cardinal rule -## Dispatch policy +One repo, one issue, one PR. -Copilot is the primary executor for bounded issue-first PR work in this repository. +Every automated or assisted change in this repository must be backed by a +single open GitHub issue and delivered in a single, focused pull request. -Use Codex as a reviewer, cross-repo analyst, or backup implementation agent when Copilot is unavailable or when cross-repo reasoning is needed. Do not count Codex comments as delivery unless GitHub shows a PR, branch, commit, or merge. +## Scope rules -Delivery means one of the following exists in GitHub: +- **Issue-first.** Do not start work without an open issue that explicitly + describes the acceptance criteria. +- **Bounded scope.** Implement only what the issue acceptance criteria require. + Do not add improvements, refactors, or housekeeping unless the issue asks + for them. +- **No cross-repo side-effects.** Changes must stay inside this repository. + Do not open PRs or push commits to other repositories as a side effect. -- PR; -- branch; -- commit; -- merge. +## Validation evidence -Agent comments, summaries, and local-task reports are engagement signals only. +Every PR body must contain: -## Rules +1. The exact commands run (copy-paste, not paraphrased). +2. Pass/fail output for each command (truncate long output but preserve the + result line). +3. Known gaps — anything not tested, deferred, or out of scope. +4. Blocked items — external decisions or dependencies needed before the work + can be completed. -- One repo, one issue, one PR. -- Inspect the live repository before editing. -- Use the GitHub issue body as the source of truth. -- Put the full task, acceptance criteria, validation commands, and non-goals in the issue body before assignment. -- Keep scope bounded to the issue body. -- Do not broaden scope without asking in the issue. -- Do not touch unrelated files. -- Prefer existing repo patterns and validation commands. -- Add tests, fixtures, validators, or docs with implementation changes when appropriate. -- Do not claim production readiness unless acceptance criteria prove it. -- Include validation evidence in the PR body. -- Leave known gaps explicit. +## High-risk path rules -PR body must include: +The following paths carry elevated risk. Changes here require explicit +maintainer approval before merge and must include validation evidence: -- What changed. -- Exact commands run. -- Pass/fail output summary. -- Known gaps. -- Anything blocked. +- `hosts/` — machine-role definitions (host mutation risk) +- `images/` — image build definitions +- `profiles/` — NixOS profiles +- `modules/` — shared NixOS modules +- `builders/` — builder configuration +- `flake.nix`, `flake.lock` — flake root and dependency lock +- `scripts/install*`, `scripts/enable*` — install / provisioning +- `*.service`, `*.timer`, `*.preset` — systemd units +- `ebpf/` — eBPF / kernel boundary +- `runtime/` — runtime admission and capability checker +- `.github/workflows/` — CI/CD pipelines +- `configs/`, `channels/` — host and channel configuration -Never: +### Boot / install / recovery -- Commit secrets, tokens, credentials, or private keys. -- Invent release URLs, checksums, SBOMs, or provenance. -- Claim live ingestion when only fixture validation exists. -- Claim production or safety-critical authority from advisory data. -- Modify workflows, boot/install/recovery, host mutation, runtime admission, or release automation unless the issue explicitly requests that scope. +Scripts and configs that write to `/etc/` or `/boot/`, or that are invoked +during OS installation or recovery, must be: -High-risk paths require explicit review and narrow scope: +- syntax-checked (`bash -n` or `shellcheck`) before the PR is opened; +- smoke-tested in a non-production environment; +- documented with pass/fail evidence in the PR body. -- `.github/workflows/**` when privileged. -- boot, install, recovery, host mutation, and release paths. -- secrets, tokens, credentials, and signing material. -- runtime admission, policy enforcement, production infrastructure, and deployment automation. -- defense, public-safety, or effects-linked execution. +Do not claim production readiness unless a full integration test result is +included. -For high-risk work, prefer this progression: +### Host mutation -1. docs/spec first; -2. fixtures second; -3. tests third; -4. dry-run fourth; -5. real mutation only behind explicit review. +Nix expressions (`profiles/`, `modules/`, `flake.nix`) must evaluate cleanly +(`nix flake check` or equivalent) before the PR is opened. -Repository-specific notes: +### Workflows -- `SourceOS-Linux/source-os` is a Linux realization repository for SourceOS/SociOS work. -- Workstation changes should preserve bounded GNOME defaults and avoid fragile shell replacement. -- Mac-on-Linux work must distinguish implemented behavior from proposed/future parity. -- Validation helpers should emit simple, parseable output where possible. -- Keep implementation authority clear: contracts/specs belong in `SourceOS-Linux/sourceos-spec`; concrete Linux realization belongs here. +Do not modify `.github/workflows/` unless the issue explicitly requires it. +If a workflow change is required, state the reason in the PR body. + +### Runtime admission + +Changes to `runtime/` or `ebpf/` must include a quorum/anchor smoke-test +result demonstrating that capability checks and policy enforcement still pass. + +## Non-goals + +The following are explicitly out of scope for agents operating in this repo: + +- Modifying workstation implementation files beyond what the issue requires. +- Changing package manifests unless the issue requires it. +- Claiming production readiness without full integration evidence. +- Touching other repositories.