Skip to content

Commit b164d6e

Browse files
committed
docs: document the pull request lifecycle once and remove passages against it
ARCHITECTURE.md gains a Lifecycle of a pull request section after Components, matching main: the hub mails a live manager directly and holds unrouted heads, the listener deploys only for pull requests with no manager and retries a failed wake once, a head waiting only on CI ends its manager until the reconciler wakes it, and each deployment has a local sidecar of its own up to the cap. The components diagram shows both hosts, the judge and code review in a sandbox, and the triage pipeline names the workflow that runs each step and adds the review post. Code review is described as posted by the manager with the verdict in ARCHITECTURE, PRODUCT and the user manual. Root AGENTS.md gains the writer, isolation, placement and size rules; triage-manager and triage-judge get an AGENTS.md and triage-workflows' is rewritten around the shared steps. References to the deleted pr-triage deployment, hedges, host data wording, the stored version 1 and step `for` reading and the missing package rows are fixed.
1 parent cc30552 commit b164d6e

12 files changed

Lines changed: 178 additions & 75 deletions

File tree

‎AGENTS.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,11 +23,15 @@ Repository-wide rules. `apps/*` and some `packages/*` have their own AGENTS.md w
2323
- **The policy drives everything.** A repository's rules and actions live in its policy file, `.corbits-triage.yml` on its default branch, and nowhere else; under the workspace's `policy` automation that file also decides what Triage does on its own. Nothing repository-specific is written into workflow code.
2424
- **Workflows are deterministic.** Agents exist only where inference happens (packages/triage-workflows/AGENTS.md).
2525
- **Effects are idempotent** under their effect id, host writes included.
26+
- **One writer per pull request.** The manager is the only workflow that writes to a pull request, and it lives until its final post or until its head waits only on CI (docs/ARCHITECTURE.md, Lifecycle of a pull request).
27+
- **Three isolated parts.** Deterministic checks, the judge and code review each have their own limits; one part's limit never changes what another reads.
28+
- **One local sidecar per deployment.** The listener, each manager and each judge run in a local sidecar of their own, up to a capped number; past the cap a deployment goes to a sandbox, and code review always runs in one.
29+
- **Size is a risk signal**, never a hold: a crossed size limit labels a pull request and never makes it wait.
2630
- **Grants decide automation.** Whether an action runs on its own is decided from the workspace's role grants, never a hard-coded limit.
27-
- **Downstream work is another workflow.** Reviewing, fixing or cleaning up a pull request is a workflow of its own, started by mail or a signal from an action; never a step inside pr-triage.
31+
- **Downstream work is another workflow.** Reviewing, fixing or cleaning up a pull request is a workflow of its own, started by mail or a signal from an action; never a step inside the manager.
2832
- **API first.** Every custom hub route is described in `/openapi.json`. The portal and the extension wrap those routes and are never the only way to do anything.
2933
- **Credentials, grants and tenants are Interchange's.** Secrets live in the hub vault and reach sidecars at launch and rotation; never read them anywhere else, never persist them.
30-
- **Hosts.** GitHub and Bitbucket Data Center. A repository record carries `source` (absent = GitHub), every mail names it as `repoSource`, and each host has its own pr-triage package. A change to host behaviour covers both, or says why not.
34+
- **Hosts.** GitHub and Bitbucket Data Center. A repository record carries `source` (absent = GitHub), every mail names it as `repoSource`, and each host has its own listener, manager, judge and code review workflows. A change to host behaviour covers both, or says why not.
3135

3236
## Interchange reference
3337

‎docs/ARCHITECTURE.md‎

Lines changed: 110 additions & 40 deletions
Large diffs are not rendered by default.

‎docs/Corbits Triage User Manual/Corbits Triage User Manual.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ Think of it as a first reader. It does the routine checking (Did the tests pass?
2626

2727
### What it never does on its own
2828

29-
Nothing runs until you turn it on. Connecting GitHub or Bitbucket Data Center only records your repositories, with triage switched off. A repository is checked only after someone turns on **Triage pull requests in this repository**, and only once its policy file is on the default branch. What Triage then does on its own is what that file names, unless your workspace is set to ask first (see [Actions Triage takes on its own](#actions-triage-takes-on-its-own)); closing on Unsure, and merging on anything but Pass, always wait for a person. Code review, too, runs only in repositories whose [policy file](#writing-the-file) turns it on, and it writes to the pull request only when someone sends it.
29+
Nothing runs until you turn it on. Connecting GitHub or Bitbucket Data Center only records your repositories, with triage switched off. A repository is checked only after someone turns on **Triage pull requests in this repository**, and only once its policy file is on the default branch. What Triage then does on its own is what that file names, unless your workspace is set to ask first (see [Actions Triage takes on its own](#actions-triage-takes-on-its-own)); closing on Unsure, and merging on anything but Pass, always wait for a person. Code review, too, runs only in repositories whose [policy file](#writing-the-file) turns it on, and Triage posts its review on the pull request with the verdict.
3030

3131
### The three parts
3232

@@ -42,9 +42,9 @@ Code review reads each new commit of a pull request for bugs: mistakes in the ch
4242
- **What it costs.** Each commit it reviews is billed to your Anthropic account. It reviews a pull request when it is opened and after every push while it is not a draft, and **Review again**, offered once a pull request has a review, is one more review. A push that leaves the change exactly as it was reviewed, such as a rebase onto a newer base that changed none of the files it touches, is not reviewed again: the new commit keeps the last review, and the section says **Carried over from** the commit it was made for. **Review again** reviews it anyway.
4343
- **Approve and merge.** With code review on, Triage approves or merges a pull request on its own only once the review of its latest commit is clean: it found nothing, or, with `clean: { below: <severity> }` in the policy file, nothing at that severity or above (P0 is critical, P1 high, P2 medium, P3 low). A review with such a finding fails a pull request that would otherwise pass: its comment says how many problems the review found, the actions you set for Fail run, and Triage takes back an approval it gave an earlier commit. A pull request that is Unsure or already fails keeps its verdict with the review's problems added to its reasons, and approve and merge wait for you. Either way, Triage's comment asks the author to fix the review's problems. A review that failed or ran past its hour, one that read only part of the change, and a review that never ran because the rules failed or had not settled leave approve and merge waiting for you in the Inbox, with the reason beside them, and Triage takes back an approval it gave an earlier commit. A check the file turns on that can't run yet, such as `security`, holds approve and merge until it can. A pull request the policy file chose not to review, by its author, its verdict or its changed files, is approved as if code review were off.
4444
- **Where you see it.** While a review runs, the line at the top of Triage's reading pane says **In progress: Waiting on code review**, and until the first review its **Code review** section says **Code review: awaited**. Once it is done it is under **Code review**: each bug with how severe it is, its file and line, and the code it points at. **Review again** reviews the latest commit once more. A very large change is read up to a size limit, and the review says how much of it was read and lists the files it did not review in full (a long list starts collapsed), or says some files were not reviewed when it cannot tell which. A review that stopped before it finished reading the repository says **Stopped early: the reviewer reached its limit for reading the repository.**
45-
- **Sending it to GitHub.** On a GitHub pull request, **Send to GitHub** posts the review as one review from the Triage App: each finding on a changed line is a comment on that line, and the rest are listed in the review. A finding whose lines run past the changed ones sits on its first changed lines and names the others. A review that stopped early carries the same line in the posted review, and a review of a cut change lists the files it did not review in full. A review too long for GitHub lists what fits and says how many more are in the portal. It is sent once per commit; the section then says **Sent to GitHub**, and sending it again only tells you it is already there. A review carried over to a newer commit is sent on that commit, unless it was already sent on the earlier one, where its comments stay on the same lines. A review of a newer commit is sent as a new review, and the earlier one stays.
46-
- **Sending it to Bitbucket.** On a Bitbucket Data Center pull request, **Send to Bitbucket** posts each finding on a changed line as a comment on that line, then one comment with the summary and the rest. A finding whose lines run past the changed ones sits on its first changed line and names the others. It is sent once per commit: sending it again posts only what is missing, then says **Sent to Bitbucket**. It needs the Comment permission for the repository.
47-
- **What it does not do.** It only reads code; it never runs it. Nothing is posted to the pull request until someone sends it.
45+
- **On the pull request.** Triage posts the review with its verdict. On GitHub it is one review from the Triage App: each finding on a changed line is a comment on that line, and the rest are listed in the review. A finding whose lines run past the changed ones sits on its first changed lines and names the others. A review that stopped early carries the same line in the posted review, and a review of a cut change lists the files it did not review in full. A review too long for GitHub lists what fits and says how many more are in the portal. A review of a newer commit is posted as a new review, and the earlier one stays. On Bitbucket Data Center each finding on a changed line is a comment on that line, then one comment holds the summary and the rest.
46+
- **Sending it yourself.** A finished review that is not on the pull request yet offers **Send to GitHub** or **Send to Bitbucket**. It is sent once per commit: on GitHub the section then says **Sent to GitHub**, and sending it again only tells you it is already there; on Bitbucket sending it again posts only what is missing, then says **Sent to Bitbucket**. It needs the Comment permission for the repository.
47+
- **What it does not do.** It only reads code; it never runs it.
4848

4949
## Getting started
5050

@@ -456,7 +456,7 @@ Clicking a pull request opens it on the right. The pane is built to be read top
456456

457457
Under the line are the actions the policy held. One Triage may take on its own but holds while CI runs reads **Will run when CI finishes:** and what it does, such as **Will run when CI finishes: add label risk: medium**; Triage takes it then without you. Any other reads **Held:** and what it does, such as **Held: Merge**, with why it is held under it, and waits for you. The list names what each does: adding a label, a merge off a fail or unsure verdict, which says so, and a held comment or change request, which shows the start of what it posts, such as **Comment "Please split this."**. **Do it** beside each runs it now, **Always, in this repository** leaves it to Triage there from then on (see [Taking action](#taking-action)), and **Hide for me** under the list hides them in this browser only.
458458
3. **The problems**, if any, failed rules first. Each one names the rule, then why, such as **Linked issue: Pull request does not reference an issue.**, with the evidence, such as the name of the failing check. A rule you need to decide is marked with a question mark and named once, such as **Focused: Triage could not tell whether the changed files serve this pull request.**, since the status line above already says **Decide**. A pull request with no problems skips straight to the description.
459-
4. **Code review**: before the first review of a pull request whose policy file turns code review on, it says **Code review: awaited**, and a pull request the policy left out of code review says **Not reviewed:** and why. Once reviewed: what the change does, then each bug it found as a comment from **Code review**, with the commit it reviewed, how severe it is (P0 is the most severe), the file and line, and the code it points at. A bug in a file code review could not read says **Not checked against the file**, here and on GitHub. If the review fails or runs past its hour, the section shows **The last review did not finish** instead of **No findings**. **Review again** reviews the latest commit once more; it is hidden on a draft. A commit that left the change as it was keeps the last review and says **Carried over from** the commit it was made for. On a GitHub pull request, **Send to GitHub** posts the review to the pull request, inline where the lines are part of the change; it then says **Sent to GitHub**. On a Bitbucket Data Center pull request, **Send to Bitbucket** does the same with a comment per finding and one summary comment. Either needs the Comment permission for the repository, and is refused once the pull request has newer commits that did not keep the review: review again, then send.
459+
4. **Code review**: before the first review of a pull request whose policy file turns code review on, it says **Code review: awaited**, and a pull request the policy left out of code review says **Not reviewed:** and why. Once reviewed: what the change does, then each bug it found as a comment from **Code review**, with the commit it reviewed, how severe it is (P0 is the most severe), the file and line, and the code it points at. A bug in a file code review could not read says **Not checked against the file**, here and on GitHub. If the review fails or runs past its hour, the section shows **The last review did not finish** instead of **No findings**. **Review again** reviews the latest commit once more; it is hidden on a draft. A commit that left the change as it was keeps the last review and says **Carried over from** the commit it was made for. Triage posts the review on the pull request with the verdict, inline where the lines are part of the change. A finished review that is not on the pull request yet offers **Send to GitHub**, which then says **Sent to GitHub**, or on Bitbucket Data Center **Send to Bitbucket**, which posts a comment per finding and one summary comment. Either needs the Comment permission for the repository, and is refused once the pull request has newer commits that did not keep the review: review again, then send.
460460
5. **The description** the author wrote.
461461
6. **Folded rows** you can expand: the linked issues, the changed files (with the diff), and the rules that passed. Evidence for a file cites its changed lines and links them at the exact commit Triage judged. Linked issues are the GitHub issues the title, description or commits mention, and the Linear issues linked in the description, the commits or a comment from one of Linear's bots. Links hidden in the description are ignored.
462462
7. **Commits and conversation** opens the pull request's page. That page reads the verdict, the evidence, then **Commits** and **Conversation**. See [The pull request page](#the-pull-request-page).
@@ -605,7 +605,7 @@ Every secret Triage holds can be replaced from Settings without disconnecting an
605605

606606
![The Code review section: Review code with Anthropic, No key, with the Anthropic key field and Save key, then Where it runs: Docker on this machine, In use; Docker on another machine (TLS), Not set up, with its .env lines, Copy and Setup guide](images/43.png)
607607

608-
[Code review](#code-review) runs with the provider whose key is stored here; today that is Anthropic. **Review code with Anthropic** says **Key stored** or **No key**. With no key, the Anthropic key field is open: paste the key and press **Save key**. When a key is stored, that field is hidden and the key itself is not shown. **Rotate** opens a blank field for a new key; press **Save key** to replace the stored one. **Remove** deletes it after you confirm. As for the decision model, when Triage cannot read the saved keys, the row says so and shows no field.
608+
[Code review](#code-review) runs with the provider whose key is stored here, Anthropic. **Review code with Anthropic** says **Key stored** or **No key**. With no key, the Anthropic key field is open: paste the key and press **Save key**. When a key is stored, that field is hidden and the key itself is not shown. **Rotate** opens a blank field for a new key; press **Save key** to replace the stored one. **Remove** deletes it after you confirm. As for the decision model, when Triage cannot read the saved keys, the row says so and shows no field.
609609

610610
When no place is in use, the top of this section says **Code review needs an isolated place to run** and names the place recommended, the first in **Where it runs**, with the lines to add to the Triage server's `.env`, **Copy**, and its **Setup guide**. Once a place says **In use**, that notice is gone.
611611

@@ -684,7 +684,7 @@ Type in the search box to narrow the list by actor, action or pull request. The
684684
| Role | A workspace role (Owner, Admin, Member) that controls what a person may do in Triage. |
685685
| CI | Continuous integration: the automated tests and checks a repository runs on every pull request. |
686686
| Draft | A pull request its author has marked as not ready. Triage waits until it is marked ready. |
687-
| Code review | Triage's optional bug finder, turned on by a repository's policy file. It reads each new commit and lists the bugs it finds in Triage, and on GitHub sends them to the pull request when you ask. |
687+
| Code review | Triage's optional bug finder, turned on by a repository's policy file. It reads each new commit, lists the bugs it finds in Triage and posts them on the pull request with the verdict. |
688688
| Finding | One bug code review reports, with its severity (P0 is the most severe), file and line. |
689689
| First-timer | Someone opening their first pull request in a repository. |
690690
| Webhook | The channel GitHub or Bitbucket uses to tell Triage about new events. |

‎docs/DECISION_MODEL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# The decision model
22

3-
Triage answers its judged rules (focused, docs, duplicates-open-pull-request and custom model rules) and decides each pull request's verdict with a decision model: TypeSafe's Jev, a System One model. Every other rule is a hard rule over GitHub data. This page describes how Triage asks the model, how it reads the answers, the limits it works within, what it costs and how accurate it has measured.
3+
Triage answers its judged rules (focused, docs, duplicates-open-pull-request and custom model rules) and decides each pull request's verdict with a decision model: TypeSafe's Jev, a System One model. Every other rule is a hard rule over host data. This page describes how Triage asks the model, how it reads the answers, the limits it works within, what it costs and how accurate it has measured.
44

55
TypeSafe's docs: [index (llms.txt)](https://docs.typesafe.ai/llms.txt), [System One](https://docs.typesafe.ai/concepts/system-one.md), [models and limits](https://docs.typesafe.ai/models.md), [primitives](https://docs.typesafe.ai/primitives.md), [confidence](https://docs.typesafe.ai/confidence.md), [jev-1.13 jagged edges](https://docs.typesafe.ai/model-jaggedness/jev-1.13.md).
66

0 commit comments

Comments
 (0)