chore(contracts): absorb AGENTS.md

[yakimoto]

contract-files rollout — batch R · AGENTS.md

Generated by governance/bin/fleet/contract-rollout.mjs (claude-workstation, contract-files-plane E5-FLEET P2) from the origin census taken 2026-08-30T16:09:43.832Z, in which this repo's default branch head was 176774566519. The scaffold is contracts init from wave-av/contract-files v0.8.0 (engine cca6e3b87). Plan and receipts: governance/plans/contract-files-plane/E5-P1-ROLLOUT-PLAN.md and receipts/contract-census-2026-08-29.md in claude-workstation.

What this changes

• Appends one fenced yaml secrets-contract block (under a ## Machine surface heading) to the EXISTING SECRETS.md. The prose inventory above it is byte-for-byte untouched — the generator asserts the new file starts with the old file's exact bytes, and the reviewer can check the diff is append-only. Names and vault locations only; the schema makes a value key unrepresentable, so a secret value cannot validate into this file.

Guarantees

• One reversible commit. Reverting that single commit restores the repo exactly; nothing else in the tree is touched.
• Validated before it was written. contracts init refuses to emit a file that does not pass its own schema validator, and the generator re-ran contracts validate on the result inside the clone.
• Gates stay in observe. No hook in this repo is armed by this PR; arming is a separate, receipted decision under the E2-GATES false-positive budget.
• Operator-confirmed merge. This PR carries SECRETS-bearing content and therefore no auto-merge label: it merges only when the operator names batch B (confirm-before-irreversible-op).

How to verify locally

npx --yes github:wave-av/contract-files contracts validate --type agents-router --repo .

Falsifiers (from the plan): a rolled repo whose gate clears with an absent or schema-invalid contract; a prose incumbent changed outside the appended block; a census that read a working tree instead of origin. Any of those reopens E5-FLEET P2 for this repo.

---

Note

Low Risk
Documentation-only append of schema-validated routing metadata; no runtime, auth, or gate behavior changes in this PR.

Overview
Appends a Machine surface section to AGENTS.md with a validated yaml agents-router block (v0.1, 200-line budget). The block indexes the existing PERMISSIONS.md file under the permissions-contract family so tooling and agents can route to permissions prose without changing any prior guidelines or lattice-init content.

This is an append-only contract-files rollout change: revert the commit to remove the block; validate locally with contracts validate --type agents-router.

^{Reviewed by Cursor Bugbot for commit b90eb12. Bugbot is set up for automated code reviews on this repo. Configure here.}

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

Summary by Sourcery

Add the agents-router contract to AGENTS.md to support contract-files rollout validation.

New Features:

• Add a machine-readable agents-router contract describing the permissions-contract file and its validation budget.

Chores:

• Extend AGENTS.md with the generated machine-surface contract while preserving the existing guidance.

[codeant-ai]

Your free trial PR review limit of 300 PRs has been reached. Please upgrade your plan to continue using CodeAnt AI.

[qodo-code-review]

ⓘ Qodo reviews are paused because your workspace is out of credits. Ask your workspace admin to add credits to resume reviews. Manage billing

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_3b2fc51d-137e-4fcf-ab07-d3bc3dd99644)

[sourcery-ai]

Reviewer's guide (collapsed on small PRs)

Reviewer's Guide

This PR absorbs the repository’s existing agent guidance into the contract-files rollout by appending a schema-validated agents-router YAML block to AGENTS.md; the change is append-only and introduces metadata only, without altering prose or enabling enforcement.

Flow diagram for the append-only agents contract rollout

flowchart LR
    A[Existing AGENTS.md prose] --> B[contracts init]
    B --> C[Append agents-router YAML block]
    C --> D[contracts validate --type agents-router --repo .]
    D --> E[Validated metadata-only AGENTS.md]

Loading

File-Level Changes

Change	Details	Files
Appends a machine-readable agents-router contract to the existing agent guidance without changing the incumbent prose.	Adds a Machine surface section with the contract schema and version. Declares the permissions-contract family and points it to PERMISSIONS.md. Preserves the existing file as an append-only prefix, including the generated boundary comment.	AGENTS.md
Introduces a validated contract definition for automated routing and future contract-file governance.	Sets the contract budget to 200 lines. Uses the agents-router contract type expected by the rollout validator. Keeps gates in observe mode; no hooks or enforcement behavior are added.	AGENTS.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 53eaedf1-2c32-45b9-98a9-c413f67d7545

📥 Commits

Reviewing files that changed from the base of the PR and between 1767745 and b90eb12.

📒 Files selected for processing (1)

• AGENTS.md

Included review availability: 0 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

📜 Recent review details

⏰ Context from checks skipped due to timeout. (3)

• GitHub Check: semgrep-cloud-platform/scan
• GitHub Check: test
• GitHub Check: semgrep-cloud-platform/scan

🧰 Additional context used

🧠 Learnings (1)

📓 Common learnings

Learnt from: CR
Repo: wave-av/examples

Timestamp: 2026-08-30T22:26:55.199Z
Learning: Branch and open a PR; never push to the default branch. All required gates must pass before merge.

Learnt from: CR
Repo: wave-av/examples

Timestamp: 2026-08-30T22:26:55.199Z
Learning: No secrets in commits — secret-scan is a required gate and will block.

Learnt from: CR
Repo: wave-av/examples

Timestamp: 2026-08-30T22:26:55.199Z
Learning: Match the existing code conventions; keep files focused (~200-500 lines).

Learnt from: CR
Repo: wave-av/examples

Timestamp: 2026-08-30T22:26:55.199Z
Learning: Report vulnerabilities via the [Security Policy](https://github.com/wave-av/.github/blob/main/SECURITY.md) (securitywave.online) — never in a public issue.

Learnt from: CR
Repo: wave-av/examples

Timestamp: 2026-08-30T22:26:55.199Z
Learning: Every capability ships its four renderings (API + CLI + SDK + MCP); the API is the authority.

Learnt from: CR
Repo: wave-av/examples

Timestamp: 2026-08-30T22:26:55.199Z
Learning: No secrets in git — credential values live in Doppler; keys arrive via ${DOPPLER:KEY} refs or dpg.mjs.

Learnt from: CR
Repo: wave-av/examples

Timestamp: 2026-08-30T22:26:55.199Z
Learning: Tests ship with the artifact in the same PR — no test, no ship; a green suite is not a live system.

🔇 Additional comments (1)

AGENTS.md (1)

49-59: LGTM!

---

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Added project guidance for machine-readable surface definitions.
  • Documented the permissions contract reference and associated metadata.

Walkthrough

AGENTS.md adds a Machine surface YAML block with version 0.1, a 200-line budget, and a permissions-contract index entry mapped to PERMISSIONS.md.

Changes

Machine surface configuration

Layer / File(s)	Summary
Add Machine surface metadata AGENTS.md	The file defines Machine surface version 0.1, a 200-line budget, and the permissions-contract index path.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Merge Risk: ⚪ Minimal · up to b90eb

This is a localized documentation-only append that adds validated routing metadata without changing runtime, authentication, permissions, or gate behavior. No actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title identifies a contracts-related change to AGENTS.md. The wording is somewhat broad, but it is related to the main change.
Description check	✅ Passed	The description includes relevant details about adding an agents-router contract to AGENTS.md and preserving existing guidance. It also contains conflicting references to SECRETS.md, but it remains re…
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Description check

Explanation

The description includes relevant details about adding an agents-router contract to AGENTS.md and preserving existing guidance. It also contains conflicting references to SECRETS.md, but it remains related to the changeset.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (1 skipped: 1 unsupported.)

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch contract-files/rollout-r

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch contract-files/rollout-r

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 1 🔵⚪⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Description Mismatch The PR description states it appends a yaml secrets-contract block to an existing SECRETS.md and that the PR "carries SECRETS-bearing content", but the actual diff only appends a yaml agents-router block to AGENTS.md. Either the wrong template text was used for this batch or a file is missing from the commit; the stated verification steps (contracts validate --type agent vs a secrets contract) and the merge-gating rationale no longer match what is being merged. ## Machine surface ```yaml agents-router version: "0.1" budget_lines: 200 index: - family: permissions-contract path: PERMISSIONS.md </details> <details><summary><a href='https://github.com/wave-av/examples/pull/40/files#diff-a54ff182c7e8acf56acfd6e4b9c3ff41e2c41a31c9b211b2deb9df75d9a478f9R56-R59'><strong>Dangling Index Path</strong></a> The router index points at `PERMISSIONS.md`. If that file does not exist at the repo root, any consumer resolving this index will fail to load the referenced contract. Worth confirming the path exists in this repo, since the rest of the diff gives no evidence it does. </summary> ```markdown index: - family: permissions-contract path: PERMISSIONS.md </details> </td></tr> </table>

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

Sourcery assessment

Approved.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[gitar-bot]

Note

Automatic reviews are paused because your team has used its included automatic processing for this billing period (headroom scales with your seat count). You can still comment "Gitar review" to run one anytime, and automatic reviews resume on their own by September 1. Add seats for more headroom.
Learn more

Code Review ⚠️ Changes requested 0 resolved / 1 findings

PR description states this rollout appends a yaml secrets-contract block to SECRETS.md and requires operator confirmation due to secrets-bearing content, but the diff only modifies AGENTS.md with an agents-router block indexing PERMISSIONS.md. Regenerate the PR description from the correct receipt for this commit, or verify the correct artifact was rolled out before merging.

⚠️ Bug: PR description describes SECRETS.md change; diff touches AGENTS.md

🔗 link

The PR summary states this rollout "Appends one fenced yaml secrets-contract block ... to the EXISTING SECRETS.md" and asserts operator-confirm-before-merge because it "carries SECRETS-bearing content." The actual diff only modifies AGENTS.md, adding an agents-router block that indexes PERMISSIONS.md under permissions-contract — there is no SECRETS.md touched at all. This mismatch suggests the PR body was generated from the wrong batch/receipt, and the stated guarantees (byte-for-byte prose preservation of SECRETS.md, secrets-gated merge label) do not describe what this PR actually does. Regenerate the PR description from the correct receipt for this commit, or verify the correct artifact (SECRETS.md vs AGENTS.md) was rolled out for this repo before merging.

🤖 Prompt for agents

Code Review: PR description states this rollout appends a `yaml secrets-contract` block to `SECRETS.md` and requires operator confirmation due to secrets-bearing content, but the diff only modifies `AGENTS.md` with an `agents-router` block indexing `PERMISSIONS.md`. Regenerate the PR description from the correct receipt for this commit, or verify the correct artifact was rolled out before merging.

1. ⚠️ Bug: PR description describes SECRETS.md change; diff touches AGENTS.md

   The PR summary states this rollout "Appends one fenced `yaml secrets-contract` block ... to the EXISTING `SECRETS.md`" and asserts operator-confirm-before-merge because it "carries SECRETS-bearing content." The actual diff only modifies AGENTS.md, adding an `agents-router` block that indexes PERMISSIONS.md under `permissions-contract` — there is no SECRETS.md touched at all. This mismatch suggests the PR body was generated from the wrong batch/receipt, and the stated guarantees (byte-for-byte prose preservation of SECRETS.md, secrets-gated merge label) do not describe what this PR actually does. Regenerate the PR description from the correct receipt for this commit, or verify the correct artifact (SECRETS.md vs AGENTS.md) was rolled out for this repo before merging.

Options

Display: compact → Showing less information.

Comment with these commands to change the behavior for this request:

Compact

gitar display:verbose

_{Was this helpful? React with 👍 / 👎 | Gitar}

[macroscopeapp]

Approvability

Verdict: Would Approve

Macroscope's review found this PR approvable — This is a focused AGENTS.md metadata update that only improves discovery of the existing permissions contract. It introduces no application runtime, schema, deployment, or user-facing behavior changes.

Not approved because:

• Credit balance exhausted. Approvability relies on correctness review in order to determine eligibility

^{Review your spending limits in Billing settings. You can add or adjust custom eligibility rules. Learn more.}

[github-actions]

PR Code Suggestions ✨

No code suggestions found for the PR.