feat: review faculty — the ship gate's automatic-review leg#37
Merged
Conversation
Adds agents/faculties/review/: a read-only faculty that prepares a feature branch's ReviewSurface (merge-base, commits ahead, diff stat, changed files, risk flags) via a stdlib entrypoint; the reviewing agent maps it to CLEAN/FINDINGS/BLOCKED per the documented procedure. Boundary settled in AGENTS.md: a diff review is a side-effect-free opinion (faculty), not a Heart check — Heart stays the sole release authority. Registered in bin/pyauto-brain; ship-path gate composition lands with series tasks 3-4. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013UptUDNTYiB7izaQJBAKgS
There was a problem hiding this comment.
Pull request overview
Adds a new review faculty to PyAutoBrain as the automatic-review leg of the autonomous ship gate: a read-only surface generator (ReviewSurface) that the reviewing agent uses to produce a CLEAN / FINDINGS / BLOCKED verdict, without involving Heart or performing side effects.
Changes:
- Introduces
agents/faculties/review/with docs + deterministic entrypoint that emits per-repo ReviewSurface (merge-base vsorigin/main, commits ahead, changed files, risk flags). - Registers the new faculty in
bin/pyauto-braindispatch/help and in the repo-level agent documentation. - Notes the review faculty’s role in the workflow autonomy doctrine (
skills/WORKFLOW.md).
Reviewed changes
Copilot reviewed 5 out of 6 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| skills/WORKFLOW.md | Documents the review faculty as the ship gate’s automatic-review leg. |
| bin/pyauto-brain | Adds review faculty to CLI dispatch, help text, and ordering. |
| agents/faculties/review/review.sh | New deterministic entrypoint wrapper invoking the stdlib surface script. |
| agents/faculties/review/AGENTS.md | Defines boundary, verdict semantics, and the review procedure contract. |
| agents/faculties/review/_review.py | Implements ReviewSurface generation and CLI output (--json / human). |
| AGENTS.md | Adds the review faculty to the canonical agent inventory and run examples. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+115
to
+117
| if not a.task and not a.repo: | ||
| print("review: pass --task <name> or --repo <path>", file=sys.stderr) | ||
| return 5 |
Comment on lines
+118
to
+121
| repos = resolve_repos(a.task or None, a.repo) | ||
| if not repos: | ||
| print("review: could not resolve any repo checkout", file=sys.stderr) | ||
| return 4 |
Comment on lines
+2
to
+3
| # agents/faculties/review/review.sh — the review faculty (a PyAutoBrain | ||
| # read-only reasoning capability). It reviews the change. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
agents/faculties/review/— a read-only faculty, the automatic-review leg of the autonomous-ship gate (AUTONOMY.md). A stdlib entrypoint (bin/pyauto-brain review --task <name>/--repo <path>/--json) prepares the ReviewSurface per repo: merge-base againstorigin/main, commits ahead, diff stat, changed files, risk flags. The verdict (CLEAN / FINDINGS / BLOCKED) is produced by the reviewing agent following the procedure in the faculty'sAGENTS.md— code review at high effort + a verify pass — mirroring how vitals' script reads Heart and the agent reasons over the result.Boundary settled and recorded in the faculty doc: a diff review is a side-effect-free opinion (the definition of a faculty), not a Heart check — Heart never sees feature branches and stays the sole release authority; this faculty gates the dev workflow's ship step only and never fixes what it finds.
Registered in
bin/pyauto-brain(help/dispatch), theAGENTS.mdfaculties list, and noted in WORKFLOW.md's Autonomy section. Ship-path gate composition is series tasks 3–4. Task 2 ofPyAutoMind/feature/autonomy/.Closes #36.
API Changes
Added CLI surface:
pyauto-brain review [--task <name> | --repo <path>] [--json]— read-only; exit codes 0/4/5. No changes to existing commands.Test Plan
bin/pyauto-brain helplists the faculty;help reviewprints its docreview --task <this-task>emits the correct surface for this very branch (dogfooded)--jsonparsesFull API Changes (for automation & release notes)
Added
pyauto-brain review(faculty) — ReviewSurface preparation; verdict semantics CLEAN/FINDINGS/BLOCKED defined inagents/faculties/review/AGENTS.md🤖 Generated with Claude Code
https://claude.ai/code/session_013UptUDNTYiB7izaQJBAKgS