Architecture on pull requests
Put each finding on the diff with an excerpt of the code and the manifest, and give the reviewer the plan and the modules that changed outside the plan.
On this page
A plain diff is the wrong level for an architectural change. A reviewer sees forty changed lines and not that Intake now calls Billing. Two GitHub Actions put the architecture on the pull request. Both run only commands of the published CLI.
| Action | What the reviewer gets | Permissions |
|---|---|---|
miklschmidt/archboard/actions/check | Each finding as an annotation on the changed line, and a job summary | contents: read |
miklschmidt/archboard/actions/pull-request | One text comment with the proposal, the footprint and the plan check | contents: read, pull-requests: write |
Findings on the diff#
The check Action turns each finding into a GitHub annotation on the file and line of its evidence. A finding that crosses a network hop has evidence in two files: the line of code that reads the address, and the line of the manifest that sets it. Each end in the pull request’s repository gets an annotation.
GitHub cannot put an annotation on a file of another repository, so every annotation names both ends with an excerpt of each, and the reviewer reads the whole connection from one place.
name: architectureon: pull_request
permissions: contents: read
jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 - uses: actions/setup-node@v5 with: node-version: 22 # The checkout's own TypeScript is the default TypeScript server. - run: npm ci # A server for each other language in .archboard/language-servers.json. - run: pip install pyright - uses: miklschmidt/archboard/actions/check@30d365ca9caab6dad98f45568a50a890c9f105f9 # v0.5.0 with: version: "0.5.0"The code check resolves a call only through a language server, so the job installs the dependencies and the servers first. The gate in CI says which servers to install. Without a server, the finding below stays information.
In the relay example, the code is in one repository and the manifest is in another. The annotation on services/intake/src/accept.ts line 51 reads:
The code of "Accept parcel" reaches "Rate card". No relationship joins these modules. Add the relationship between the parts that make and answer the call. If this dependency is unintended, change the code.Evidence:- configured-path, resolved: services/intake/src/accept.ts:51 in github.com/miklschmidt/archboard-relay-example (BILLING_URL) 50 | // gate:break start > 51 | const billingUrl = trimUrl(process.env.BILLING_URL ?? ""); 52 | await deps.fetch(`${billingUrl}/surcharges?routeCode=${encodeURIComponent(routeBody.routeCode)}`);- configured-path, resolved: deploy/kubernetes/peer-endpoints.yaml:13 in github.com/miklschmidt/archboard-relay-example-infra (BILLING_URL) 12 | DISPATCH_JOBS_URL: http://dispatch-jobs.harbor.svc.cluster.local:9324 > 13 | BILLING_URL: http://billing.harbor.svc.cluster.local:8080 14 |The job summary lists up to 100 findings, evidence for the first 30 errors and warnings, and the skipped subjects. Each code links to its explanation. GitHub shows at most 10 annotations of each level for one step. The Action saves the complete JSON report at its report output. Upload that file as an artifact to keep the complete list for review.
Decide what blocks#
| Input | Effect |
|---|---|
fail-on: warning | The default. The job fails while a warning or a semantic diagnostic remains. |
fail-on: never | The findings show, and the job never fails on them. |
allow-codes | These codes show and never fail the job, such as CALLER_UNDRAWN. |
A check that cannot run fails the job in every case: a usage error, a refusal, an unreachable server, or a checkout without a vault when the checks read one. With checks: embeds the Action needs no vault.
The plan on the pull request#
An agent that plans a change first writes it as a proposal: the architecture after the change, beside the current one. The pull-request Action finds that proposal and posts one comment. It updates the same comment on each push. When a push removes the vault, the comment says so.
Pull request #2 of the relay example makes the same call to Billing with a plan, and its comment shows each part below.
- The proposal. Its name and summary, and what it adds, removes and changes.
- The vault. A link to the vault at the head commit.
- The plan check. Whether any module changed outside the plan, and what that does to the job.
- The footprint. The modules whose code the pull request changed, in three groups: changed outside the plan, planned and changed, and planned but unchanged. Below them, the changed files that no module is bound to, because no module shows their change. Those files are never judged. Each group is a disclosure with its count. Only the group of modules changed outside the plan starts open.
name: pull-requeston: pull_request: types: [opened, edited, synchronize, reopened, labeled, unlabeled]
permissions: contents: read pull-requests: write
concurrency: group: archboard-report-${{ github.event.pull_request.number }} cancel-in-progress: true
jobs: report: runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 with: fetch-depth: 0 - uses: miklschmidt/archboard/actions/pull-request@30d365ca9caab6dad98f45568a50a890c9f105f9 # v0.5.0 with: version: "0.5.0" out-of-plan: warnfetch-depth: 0 is required, because the Action reads the base and the head from Git history. The concurrency group cancels the run of an older push. A run that still finishes after a newer push posts nothing. The labeled and unlabeled events let the override label below take effect at once, and edited runs the Action again when the marker in the description changes.
How it finds the proposal#
The Action takes the first of these that it finds:
-
The
stateinput, by identity or name. -
The marker that the
archboard-prskill writes into the pull request’s description:<!-- archboard-pr model="rpmPjlm0" state="zu80HRHt" --> -
The only draft proposal of the model.
With none, the comment lists the changed modules and judges nothing against a plan. Pull request #1 of the relay example has such a comment.
The plan is what the proposal changes against the current architecture at the base: each module that it adds, removes or changes, and both ends of each relationship or flow step that it adds, removes or changes. This holds for a draft and for a proposal that the branch already adopted, as the skill does once the code matches it.
When the base has no vault, as on the pull request that adds the first one, the current architecture at the base is empty. Then the plan names every module of the proposal. When a model cannot be read, the comment names the commit, base or head, and the reason that the CLI gave.
Changes outside the plan#
The footprint’s middle group lists modules whose code changed although the plan did not name them. It excludes a module whose holds lists another changed module, because the modules in its holds bind each file that it changed. If an older CLI omits holds, the Action counts every changed module absent from the plan. out-of-plan says what happens then.
out-of-plan | Effect |
|---|---|
warn | The default. An annotation and a line in the comment. |
fail | The job fails. It also fails when the plan cannot be checked: the proposals or the footprint cannot be read, the pull request names a proposal that the model does not have, or the model has several drafts and the pull request names none. The label archboard: out of plan lets the pull request through, and the comment says that the label did it. |
off | The footprint shows, and nothing is judged. |
Change the label with override-label. A pull request with no proposal has no plan, so nothing in it is out of plan. When the model has one draft, the Action takes it without a marker, so removing the marker does not stop the judgement. Set out-of-plan: off for that. When the model has several drafts and the pull request names none, the plan cannot be checked.
Added modules without new code#
A proposal that adds a module whose code the base already has draws that code as added, although the diff adds none of it. The footprint lists each module that the proposal adds and whose code the pull request does not add, in the group “Added without new code”. The branch adds code to a module when it adds a file inside the module’s binding, or the declaration that its binding names. A renamed file adds no code. A module bound to a directory that gains a new file is therefore not listed. The fix is to model the existing code in the current architecture first, in a pull request below this one. A module whose binding names code that exists nowhere is listed too: repair its binding. preexisting says what happens to the listed modules.
preexisting | Effect |
|---|---|
warn | The default. An annotation and a line in the comment. |
fail | The job fails, also when the footprint cannot be read. The label archboard: out of plan lets the pull request through, as for out-of-plan. |
off | The group shows, and nothing is judged. |
Before a pull request#
A branch can merge without a pull request, for example a ticket branch that merges into an integration branch. Run a similar judgement there with the CLI:
archboard model footprint --base <integration-branch> --head <ticket-branch> --state <draft> --fail-outsideIt exits 1 when the branch changed a module that the draft does not name, and names each module on standard error. Without a draft, it refuses the option, because only a draft names modules.
If the vault’s repository holds the ticket branch, the command reads that branch’s draft. Otherwise, it reads the draft on disk.
The archboard-plan skill runs this gate in the integration worktree with --model-at checkout before each ticket merge. It edits the draft there, so the ticket branch does not hold those edits.
A module counts as changed only when its bound code differs between the merge base and the head. A change that a later commit undoes does not count. In a stack that merges instead of rebasing, a change that a lower layer also made, and that a merge brings in, does not count either. Each changed module lists the commits that changed it.
A module bound to a directory changes with each module bound inside it. It counts only when the branch changed a file that no other changed module inside it binds. Otherwise the answer lists those other modules in the module’s holds, and the module passes. The Action applies the same rule to its group of modules changed outside the plan. For example, Workspace is bound to libs/workspace, and Installation is bound to libs/workspace/src/installation.ts:
| The branch changes | The draft names | Exit status |
|---|---|---|
libs/workspace/src/installation.ts | Installation | 0. Workspace changed too, and holds Installation. |
libs/workspace/src/installation.ts | neither module | 1, for Installation. |
libs/workspace/README.md | Installation | 1, for Workspace. |
| both files | Installation | 1, for Workspace. |
The answer’s unboundFiles lists each changed file that no module is bound to, and standard error names the first few. Those files never change the exit status. Read each one, and bind it to a module or say why it belongs to none.
With a draft, the answer lists each module that the draft adds and whose code the branch does not add, by the rule of the Action above. Each module says in newSource whether the branch added code to it. With --fail-preexisting, the command exits 1 when that list is not empty. The archboard-pr skill runs this gate before it writes a pull request body.
When the comment cannot be posted#
A pull request from a fork gets a read-only token, so GitHub refuses the comment. The report is then in the job summary of the run. The same happens when the token lacks pull-requests: write.
Take the report as a file#
The report-file input names a file that takes the report in place of the comment. The Action writes the Markdown that it would post to that file, with the hidden marker that identifies its comment. It posts and changes no comment and writes no job summary, so the job needs only contents: read. The plan check annotates the log and fails the step as it does without the input. The report output names the file, and a later step puts the report where the team wants it. This workflow puts it in the job summary:
name: pull-requeston: pull_request: types: [opened, edited, synchronize, reopened, labeled, unlabeled]
permissions: contents: read
jobs: report: runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 with: fetch-depth: 0 - uses: miklschmidt/archboard/actions/pull-request@30d365ca9caab6dad98f45568a50a890c9f105f9 # v0.5.0 id: architecture with: version: "0.5.0" report-file: ${{ runner.temp }}/architecture.md - if: always() && steps.architecture.outputs.report != '' run: cat "$REPORT" >> "$GITHUB_STEP_SUMMARY" env: REPORT: ${{ steps.architecture.outputs.report }}always() runs the last step also when the plan check fails the Action’s step.
A relative path starts at the workspace. The Action creates missing parent directories. If the file cannot be written, the step fails and sets no report output.
Explain the change in the description#
The comment states facts. The archboard-pr skill, which archboard init installs, has your agent write the description around them: the problem, the resulting behavior, the evidence and the merge danger. Ask for it when you open the pull request:
Open a pull request for this branch. Use the archboard-pr skill: plan the change as a proposal,adopt it on this branch once the code matches, and explain the architecture in the description.The skill models every flowchart and sequence chart as a flow and draws it with archboard model render. A chart that an agent wrote in Mermaid by hand can contradict the model. So when the archboard-pr section of the description holds a Mermaid code block, the Action warns in the log and in the comment. The warning never fails the job.