CIP-3849: Document local agent ownership of PR CI failures

AGENTS.md

@@ -0,0 +1,72 @@
+# Agent guidance
+
+CipherStash Proxy is a Rust workspace providing transparent, searchable
+encryption between applications and PostgreSQL.
+
+## Domain context
+
+Before exploring or changing package code, read `CONTEXT-MAP.md` and the
+applicable package `CONTEXT.md`. Treat those files as the source of truth for
+architecture, domain boundaries, request flow, and vocabulary.
+
+## Development workflow
+
+Before setting up a local environment; starting or stopping Proxy or
+PostgreSQL; running tests or benchmarks; configuring logging; building; or
+releasing, read `DEVELOPMENT.md`. It owns the development procedures and
+operational gotchas for those workflows.
+
+Use `mise tasks` to discover the current build, test, database, proxy, and
+cross-compilation commands instead of duplicating that reference here. Run the
+smallest relevant validation while iterating and the broader applicable checks
+before completion.
+
+### Coding conventions
+
+- Define errors in `packages/cipherstash-proxy/src/error.rs`, grouped by
+  problem domain rather than module. Use descriptive variant names without an
+  `Error` suffix and give customer-facing errors helpful messages and
+  documentation links.
+- In tests, prefer `unwrap()` over `expect()` unless the expectation adds
+  meaningful context. Prefer `assert_eq!` for equality checks.
+
+### Release documentation
+
+For user-facing or notable changes, update the `CHANGELOG.md` `[Unreleased]`
+section using Keep a Changelog categories and user-facing language. For a
+significant release, prepare `ANNOUNCEMENT.md` for GitHub Discussions and
+remove that temporary file after publishing it.
+
+## Pull request CI ownership
+
+When a task authorizes pushing changes to a pull request, use passing required
+GitHub checks as the completion criterion unless the user explicitly says not
+to wait for CI.
+
+After every push:
+
+1. The main agent must spawn a background subagent whose role is **monitor
+   only**. The monitor may inspect the PR, wait for checks with
+   `gh pr checks --watch`, and collect failed-run logs with read-only `gh`
+   commands. It must not edit files, run formatting that changes files, commit,
+   push, or perform any other repository mutation.
+2. The monitor must return the final check state and, for failures, the failed
+   check names, run identifiers, and relevant failure output to the main agent.
+3. The main agent is the sole writer. It must diagnose the failure, edit the
+   current local worktree, run relevant validation, commit the fix, and push it
+   to the PR branch.
+4. After each fix push, the main agent must start a new monitor-only background
+   subagent and repeat the loop.
+
+The main agent may finish only when all required checks pass or when it reports
+a genuine external blocker that it cannot resolve from the local worktree.
+
+## Work tracking
+
+- Issues live in Linear under Product Engineering (`CIP-`), not GitHub Issues.
+  Read `docs/agents/issue-tracker.md` before creating, updating, or linking an
+  issue.
+- Read `docs/agents/triage-labels.md` before assigning or changing triage
+  labels.
+- Read `docs/agents/domain.md` when creating or maintaining domain context
+  documentation.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

DEVELOPMENT.md

@@ -5,6 +5,11 @@
 >  - [mise](https://mise.jdx.dev/) — see the [installing mise](#installing-mise) instructions
 >  - [Docker](https://www.docker.com/) — see Docker's [documentation for installing](https://docs.docker.com/get-started/get-docker/) and ensure that your Docker daemon is running. On *macOS* and *Linux* you can do this by running Docker Desktop.  See: [Docker Desktop docs](https://docs.docker.com/get-started/introduction/get-docker-desktop/). If you have installed Docker without Docker Desktop then you will need to launch `dockerd` manually.
 
+> [!NOTE]
+> On macOS, if development fails with `Too many open files`, raise the limit
+> for the current shell with `ulimit -n 10240`. Add the command to your shell
+> profile if you need the setting to persist.
+
 Local development quickstart:
 
 ```shell
@@ -797,4 +802,3 @@ git push origin :refs/tags/v2.1.9
 # Create the release again
 mise run release v2.1.9
 ```
-