Skip to content

Commit 5a5d065

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 and a components diagram with both hosts, the judge and code review in a sandbox. 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 version 2 save note and the missing package rows are fixed.
1 parent 9858ab8 commit 5a5d065

12 files changed

Lines changed: 159 additions & 68 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: `.corbits-triage.yml` on its default branch, or a stored policy through the stock tenant artifact route. 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 (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 sidecar per hub.** The listener, managers and judges share the hub's local sidecar up to its cap; code review always runs in a sandbox.
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: 91 additions & 35 deletions
Large diffs are not rendered by default.

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

Lines changed: 6 additions & 6 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**. Enabling a repository switches on Comment and Labels for it; every other action waits for a person to click until you decide which actions Triage may run by itself, and in which repositories. 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**. Enabling a repository switches on Comment and Labels for it; every other action waits for a person to click until you decide which actions Triage may run by itself, and in which repositories. Code review, too, runs only in repositories whose [policy file](#writing-the-file) turns it on, and it 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** 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.** In Triage's reading pane, 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

@@ -599,7 +599,7 @@ Every secret Triage holds can be replaced from Settings without disconnecting an
599599

600600
![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)
601601

602-
[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.
602+
[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.
603603

604604
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.
605605

@@ -678,7 +678,7 @@ Type in the search box to narrow the list by actor, action or pull request. The
678678
| Role | A workspace role (Owner, Admin, Member) that controls what a person may do in Triage. |
679679
| CI | Continuous integration: the automated tests and checks a repository runs on every pull request. |
680680
| Draft | A pull request its author has marked as not ready. Triage waits until it is marked ready. |
681-
| 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. |
681+
| 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. |
682682
| Finding | One bug code review reports, with its severity (P0 is the most severe), file and line. |
683683
| First-timer | Someone opening their first pull request in a repository. |
684684
| 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

‎docs/IMPLEMENTATION.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -91,14 +91,16 @@ A WXT browser extension that checks the open GitHub pull request locally; see
9191

9292
| Package | Holds |
9393
| --- | --- |
94-
| `triage-workflows` | The triage steps, `pr-triage`, the definition that runs them locally, `repo-scan`, the judge's director, the actions under `actions/`, the deterministic logic under `logic/`, and the decision-model eval. |
94+
| `triage-workflows` | The shared triage steps, `pr-triage`, the definition that runs them locally, `repo-scan`, the judge's director, the actions under `actions/`, the deterministic logic under `logic/`, and the decision-model eval. |
95+
| `triage-manager` | The listener and the manager: each host's listener deploys a manager per pull request, and the manager runs the shared triage steps, deploys the judge and code review, and makes every post; see [its README](../packages/triage-manager/README.md). |
96+
| `triage-judge` | The judge a manager deploys when the rules need the decision model; it reports the verdict and posts nothing. |
9597
| `triage-contracts` | Policy schema and parsers, the policy file, resolving a file over the one it extends, repository settings, triage state, labels, trigger mail, the manager chain's workflows and the `release.json` each publishes (`workflow-release.ts`), and shared types; see [its README](../packages/triage-contracts/README.md). |
9698
| `github-reads`, `bitbucket-datacenter-reads` | Host read helpers, both returning the GitHub shapes. |
9799
| `github-tool`, `bitbucket-datacenter-tool` | The sidecar tool bundles: reads, the mirror, and actions. |
98100
| `repo-read-tool` | `read_file`, `grep` and `list`, read-only and confined to a checkout folder under the sidecar data dir's `checkouts` (no `..`, absolute path or symlink out); the host tool packages export `checkout` and their read bundles add `*_read_file`. |
99101
| `pr-code-review`, `pr-code-review-anthropic` | The provider-neutral code review workflow and the Anthropic provider's package and eval; see [its README](../packages/pr-code-review/README.md). |
100102
| `policy-check-action` | The GitHub Action that checks `.corbits-triage.yml` as the hub reads it, and runs the policy's rules that need no model on a pull request through pr-triage's `runLocal`. |
101-
| `provisioner-docker`, `provisioner-template`, `provisioner-test` | The Docker provisioner, a template for a new backend, and the contract tests; see [provisioners/](provisioners/README.md). |
103+
| `provisioner-docker`, `provisioner-e2b`, `provisioner-railway`, `provisioner-template`, `provisioner-test` | The Docker, E2B and Railway Sandboxes provisioners, a template for a new backend, and the contract tests; see [provisioners/](provisioners/README.md). |
102104
| `openai-null-delta` | Inference adapter fix for null stream deltas. |
103105
| `common` | Dependency-free helpers shared across apps and packages. |
104106

0 commit comments

Comments
 (0)