repo hygiene: add agent operating instructions

.github/copilot-instructions.md

@@ -0,0 +1,45 @@
+Use the GitHub issue body as the source of truth.
+
+Before editing:
+
+1. Read the issue.
+2. Inspect the repository.
+3. Identify existing validation commands.
+4. Keep the PR bounded to the issue scope.
+
+When implementing:
+
+- 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.
+
+When opening the PR:
+
+- 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.
+
+SourceOS-specific boundaries:
+
+- 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.
+
+Validation expectations:
+
+- 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.

AGENTS.md

@@ -0,0 +1,57 @@
+# Agent Operating Instructions
+
+Work issue-first.
+
+Rules:
+
+- One repo, one issue, one PR.
+- Inspect the live repository before editing.
+- Use the GitHub issue body as the source of truth.
+- 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.
+
+PR body must include:
+
+- What changed.
+- Exact commands run.
+- Pass/fail output summary.
+- Known gaps.
+- Anything blocked.
+
+Never:
+
+- 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.
+
+High-risk paths require explicit review and narrow scope:
+
+- `.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.
+
+For high-risk work, prefer this progression:
+
+1. docs/spec first;
+2. fixtures second;
+3. tests third;
+4. dry-run fourth;
+5. real mutation only behind explicit review.
+
+Repository-specific notes:
+
+- `SociOS-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.