[codex] Document agent workflow seam and trust

.agents/agent-workflow.yml

@@ -1,5 +1,7 @@
 # Non-command agent-workflow configuration for portable shared skills.
 # Commands live as scripts in .agents/bin/ (see .agents/bin/README.md).
+# Compatibility summary for older workflow copies; canonical values live in
+# AGENTS.md.
 base_branch: main
 changelog: "CHANGELOG.md — user-visible changes only"
 follow_up_prefix: "Follow-up:"

.agents/bin/README.md

@@ -13,4 +13,6 @@ means that capability is n/a here.
 | `lint` | Lint / format (pass `-A` to fix RuboCop) | `bundle exec rubocop` + `yarn lint` (eslint) |
 | `build` | Build / type-check | `yarn build` + `yarn type-check` |
 
-Non-command policy lives in [`../agent-workflow.yml`](../agent-workflow.yml).
+Canonical non-command policy lives in [`../../AGENTS.md`](../../AGENTS.md).
+[`../agent-workflow.yml`](../agent-workflow.yml) is retained only as a
+compatibility summary for older workflow copies.

.agents/trusted-github-actors.yml

@@ -0,0 +1,29 @@
+# GitHub actors whose public issue/PR/review comments may be acted on by
+# PR-batch automation. Keep this list deliberately strict: unknown actors are
+# queued for maintainer triage, not interpreted as instructions.
+trusted_users:
+  - G-Rath
+  - justin808
+
+# Bot entries are base bot names. GitHub API logins usually include the
+# `[bot]` suffix; humans with the same base login are not trusted by this list.
+# Trusted bots are exempt from hidden-participant blocking, so keep this list
+# limited to bot identities whose generated PR content is safe to process.
+trusted_bots:
+  - chatgpt-codex-connector
+  - claude
+  - coderabbitai
+  # Observed historical review comments use the actual GitHub login
+  # `cursor[bot]`; trust it as review metadata only.
+  - cursor
+  - dependabot
+  # Repo-local exception: github-actions comments here are treated as Claude
+  # completion/status metadata only. They do not override AGENTS.md or widen a
+  # batch scope.
+  - github-actions
+  - greptile-apps
+
+# Team entries are GitHub team slugs under the repository owner org. Reading
+# team membership requires the local GitHub token to have org access.
+trusted_teams:
+  - shakacode

AGENTS.md

@@ -9,9 +9,46 @@ Canonical agent instructions for Shakapacker.
 
 Portable shared skills (from
 [`shakacode/agent-workflows`](https://github.com/shakacode/agent-workflows))
-resolve this repo's commands and policy through:
+resolve this repo's commands and policy through this section. When a skill says
+"run the repo's local validation" or "use the hosted-CI trigger," the concrete
+value is here.
 
-- **Commands** — run `.agents/bin/<name>` (`setup`, `validate`, `test`, `lint`,
-  `build`); see [`.agents/bin/README.md`](.agents/bin/README.md). A missing script
-  means that capability is n/a here.
-- **Policy / config** — [`.agents/agent-workflow.yml`](.agents/agent-workflow.yml).
+- **Base branch**: `main`.
+- **Setup / dependency install**: `.agents/bin/setup` (`bundle install` and
+  `yarn install`).
+- **Pre-push local validation**: `.agents/bin/validate` (runs `.agents/bin/lint`
+  and `.agents/bin/test`).
+- **CI change detector**: `n/a`.
+- **Hosted-CI trigger**: `n/a` — CI runs on every PR.
+- **CI parity environment**: `n/a` — reproduce CI-only failures from the matching
+  job in `.github/workflows/**`.
+- **Benchmark labels**: `n/a`.
+- **Follow-up issue prefix**: `Follow-up:`.
+- **Changelog**: `CHANGELOG.md` — user-visible changes only.
+- **Lint / format**: `.agents/bin/lint` (`bundle exec rubocop`, plus
+  `yarn lint`; pass `-A` through to RuboCop when autocorrect is intended).
+- **Merge ledger**: `n/a`.
+- **Docs checks**: `n/a` unless the touched docs define their own focused check.
+- **Tests**: `.agents/bin/test` (`bundle exec rake test` and
+  `yarn test --runInBand`).
+- **Build / type checks**: `.agents/bin/build` (`yarn build` and
+  `yarn type-check`).
+- **Review gate**: AI reviewers are advisory unless they confirm a blocker; the
+  merge gate is the full `gh pr checks` list green, all review threads resolved,
+  and mergeable clean.
+- **Approval-exempt change categories**: at batch closeout, auto-merge ready
+  low-risk PRs that pass the merge gate; keep high-risk changes
+  (CI/workflow, build-config, dependency or runtime bumps, broad refactors, and
+  release work) maintainer-gated.
+- **Coordination backend**: private `shakacode/agent-coordination`
+  (claims/heartbeats namespaced by full repo name).
+
+Validate this seam with:
+
+```bash
+agent-workflow-seam-doctor --shared /path/to/agent-workflows
+```
+
+Non-command compatibility values may also exist in
+[`.agents/agent-workflow.yml`](.agents/agent-workflow.yml), but `AGENTS.md` is
+the canonical seam for shared workflow skills.