docs: add .github/copilot-instructions.md and AGENTS.md

.github/copilot-instructions.md

@@ -0,0 +1,70 @@
+# Copilot coding-agent instructions — source-os
+
+## Guiding principle
+
+Use the GitHub issue body as the source of truth for every task.
+Do not infer scope beyond what the issue explicitly states.
+
+## Workflow rules
+
+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.
+
+## High-risk paths — mandatory human review before merge
+
+Changes touching any of the following paths require an explicit maintainer
+review and approval before merging:
+
+| 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 |
+
+## SourceOS-specific boundaries
+
+- **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.
+
+## PR body template
+
+```
+## What changed
+<!-- Short description of the change -->
+
+## Commands run
+<!-- Exact commands, in order -->
+
+## Output summary
+<!-- pass / fail, truncated where long -->
+
+## Known gaps
+<!-- Anything incomplete, untested, or deferred -->
+
+## Blocked on
+<!-- External dependencies or decisions needed -->
+```

AGENTS.md

@@ -0,0 +1,83 @@
+# AGENTS — source-os operating instructions
+
+## Cardinal rule
+
+One repo, one issue, one PR.
+
+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.
+
+## Scope rules
+
+- **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.
+
+## Validation evidence
+
+Every PR body must contain:
+
+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.
+
+## High-risk path rules
+
+The following paths carry elevated risk. Changes here require explicit
+maintainer approval before merge and must include validation evidence:
+
+- `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
+
+### Boot / install / recovery
+
+Scripts and configs that write to `/etc/` or `/boot/`, or that are invoked
+during OS installation or recovery, must be:
+
+- 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.
+
+Do not claim production readiness unless a full integration test result is
+included.
+
+### Host mutation
+
+Nix expressions (`profiles/`, `modules/`, `flake.nix`) must evaluate cleanly
+(`nix flake check` or equivalent) before the PR is opened.
+
+### Workflows
+
+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.