@wardby/cli 0.6.0 → 0.8.0

package/docs/code-review-agents.md

@@ -31,6 +31,15 @@ Once an agent is linked to a repository with the `pull_request` trigger:
   runs. When the cause is budget, the check says so ("Review could not run:
   out of budget") and names the budget that was used up; use **Re-run** after
   raising the budget or once it resets.
+- A pull request that is still a **draft**, whose latest commit was pushed by a
+  coding run that stopped at its budget, is not reviewed automatically: the
+  check completes as `neutral` with the title "Skipped: stopped at its
+  budget". This is deliberate and is not the dispatch failure above: a draft
+  is not merged, and the review would only repeat findings the continuation
+  addresses. Marking the pull request ready for review or pushing a new
+  commit starts a normal review, and so does re-running the check or a
+  review mention. See
+  [Stopped for budget](coding-agent-setup.md#stopped-for-budget-the-work-so-far-is-kept).
 - On a later review, the agent sees its own unresolved inline threads and
   can **resolve the ones the new head fixes**, so fixed findings collapse on
   the PR page. Only threads that agent started are resolved; people's
@@ -61,9 +70,30 @@ thread) right after the reaction. When the run ends, the App edits that
 comment with the outcome:
 
 - the pull requests the run's coding sub-runs opened or pushed to;
+- ⛔ **Blocked by the package registry: no changes were made.** when coding
+  sub-runs recorded package refusals and no pull request or pushed changes
+  resulted. The comment lists up to ten distinct refusals, with reasons,
+  registry codes and fixes; use `get_run` for the full list. An approver updates
+  `codingProfile.packageAllowlist` or `codingProfile.packagePolicy` with
+  `update_agent` (needs `packages:approve` or `agents:admin`), then the
+  requester mentions `@wardby` again. See [Package policy](coding-packages.md)
+  and [Status comments help](../help/status-comments.md). Jira status comments
+  and Slack notifications use the same blocked guidance;
+- a ⚠️ dependency install warning listing refusals when changes were pushed,
+  while keeping the pull request link. Without refusals, the usual ✅ / ❌
+  wording remains;
 - the agent's final reply, quoted, when no pull request came out (for
   example, a question back to the requester). `@`-mentions in the reply are
   defused so nobody is pinged;
+- when that reply is longer than about 2,000 characters, the comment says
+  "✅ Finished without opening a pull request. The full reply follows in the
+  next comment(s)." (in a review thread: "...follows in this pull request's
+  conversation."), and the reply follows in up to four numbered comments
+  ("Reply, part i of n") of about 60,000 characters each, split at headings,
+  paragraphs or lines. Anything beyond four parts is cut with a note that the
+  full text is on the run (`get_run`, `finalText`); each part is posted once,
+  and if one cannot be posted the rest are skipped. Runs that opened a pull
+  request or had a failed sub-run keep the quoted excerpt;
 - a failure when a coding sub-run it started did not succeed, even though
   the mention agent itself finished (with the agent's reply quoted);
 - that the request was **interrupted** and should be repeated, when the run
@@ -90,10 +120,78 @@ repository can trigger a run. wardby asks GitHub for the author's real
 permission on the repository (by their numeric user id) before either path
 runs; `read` and `triage` are not enough, because a mention drives an agent
 that holds its owner's tools, secrets, and write access. GitHub's
-`author_association` (owner, member, collaborator) is only a first filter:
-it would admit any organization member, or a read-only collaborator. Mentions
-by bots, and mentions from anyone without write access, are ignored silently
-(no run, no reaction).
+`author_association` is only a first filter: it drops first-time authors
+(`FIRST_TIME_CONTRIBUTOR`, `FIRST_TIMER`) and mannequins, and lets every
+other association through to the permission check. That includes
+`CONTRIBUTOR` and `NONE`, which GitHub reports for an organization member
+whose membership is private. Mentions by bots, and mentions from anyone
+without access to the repository, are ignored silently (no run, no reaction).
+The server logs an info line for each one, naming the event, repository and
+association, never the text.
+
+Someone who holds a role on the repository but lacks write access can see it
+but cannot start a run. Their mention gets a 😕 reaction and a one-line reply
+saying a mention needs write access, so they know to ask someone who has it.
+No run starts. That applies to anyone with `triage` access, and to anyone with
+`read` access on a private repository, or whose `author_association` is
+`OWNER`, `MEMBER` or `COLLABORATOR`. GitHub reports `read` for every account
+on a public repository, so a stranger there (association `NONE`,
+`CONTRIBUTOR` or unknown) is refused silently and learns nothing about the App.
+
+A mention inside Markdown code is not a request. Text in an inline code span
+(`` `@<app-slug>` ``), a fenced code block, or an indented code block is
+skipped, so you can document the App's commands in an issue, pull request or
+comment without starting a run. This applies to `@<app-slug> review` too.
+
+When someone with write access mentions the App and nothing starts, the App
+replies on the issue or pull request (in the review thread, if the mention was
+in one) instead of leaving the mention unanswered. It says which of these applies, with no 👀
+reaction:
+
+- **No agent answers mentions on the repository** — no agent is linked with
+  the `mention` trigger. Link one (see [Linking an
+  agent](#linking-an-agent-to-a-repository)).
+- **No reviewer is linked** — `@<app-slug> review` was used, but no agent is
+  linked with the `pull_request` trigger and a `checkName`.
+- **The linked agent can no longer use the repository** — the agent owner's
+  GitHub account lost access, or its authorization lapsed. The owner
+  re-authorizes or re-links the agent.
+- **The pull request is closed or comes from a fork** — wardby reviews only
+  open pull requests from branches of the repository.
+
+The reply never names the App, so it cannot be read as a mention of itself.
+
+The reply is a comment that anyone who can see the repository reads, so on a
+public repository it shows what is (or isn't) linked there. To keep that to
+yourself, set `WARDBY_MENTION_EXPLANATIONS=false` on the server: a mention that
+starts nothing then gets no reply at all. The default is `true`.
+
+If a mention from someone with write access gets no reaction or reply, check
+the server log for `mention ignored` or `mention declined`. Older versions dropped `CONTRIBUTOR` and
+`NONE` authors before the permission check. On those versions, make the
+organization membership public or post the mention as a comment.
+
+### Follow-ups on an issue
+
+If a mention lands on a GitHub **issue** that already has an open pull request
+wardby opened, the run message includes that pull request and the exact run id
+to pass as `continuePriorRun`, so the agent pushes to the same branch instead
+of opening a second pull request. This is the same behaviour, and the same
+sentence, as [follow-ups on a Jira issue](jira-agents.md): GitHub and Jira
+issues record the pull requests opened for them alike. The message lists up to
+ten open pull requests recorded for the issue, each with its own run id. A
+stopped-for-budget draft is continued this way too (see
+[Stopped for budget](coding-agent-setup.md#stopped-for-budget-the-work-so-far-is-kept)).
+A pull request opened from a mention on a GitHub issue starts its description
+with `From issue #N` for that issue when the issue is in the same repository,
+the same place a Jira issue's pull request has its `Resolves Jira issue …`
+line; follow-ups keep the line. The line only links the issue: whether merging
+closes it is up to the agent. Have the delivery or builder prompt end the
+summary with `Resolves #N` to close the issue on merge, or `Refs #N` to leave
+it open (for a plan, or one ticket of an epic). A follow-up keeps whichever
+line the previous description had. The help article
+[Run GitHub code-review agents](../help/code-review-agents.md#follow-ups-on-an-issue)
+says the same in short.
 
 ### What the mention agent receives
 
@@ -188,6 +286,52 @@ PR description:
   agent can reach only the tools and access you would give that outsider's
   text.
 
+## Follow-ups bring the pull request up to date
+
+Every follow-up run on a pull request a wardby coding run opened (a mention on
+the pull request, a delegated `continuePriorRun`, a review fix round) first
+merges the branch the pull request **currently** targets into its branch:
+
+- **The target is read from GitHub when the run starts**, so a pull request
+  retargeted since it opened (a stacked pull request whose parent merged, a
+  release branch) merges its new base. Retargeting does not make wardby treat
+  the pull request as closed.
+- **The merge happens before the agent starts**, in trusted wardby code. The
+  target branch is fetched from the same repository with the App's access;
+  a fork is never fetched. A branch that already contains its target is left
+  exactly as it was, and the run behaves as it always has.
+- **Conflicts are the agent's to resolve.** The conflicted files keep standard
+  conflict markers, and the agent's task lists them, says which side is the
+  pull request and which is the target, and asks it to resolve every conflict
+  keeping both sides' intent, fix the tests the combination broke, and run the
+  repository's checks. A conflicted file that still holds markers when the run
+  ends stops the push: the run fails with category `merge_conflict`
+  ([help](../help/errors/merge-conflict.md)) and nothing is pushed. A
+  conflicted file with no markers (a binary file, or one deleted on one side
+  and changed on the other) holds one side's version, or the changed version,
+  and the agent is asked to check it.
+- **The push is one merge commit authored by Wardby**, whose parents are the
+  head the run started from and the target. It is pushed even when the agent
+  changed nothing else, so "please update this PR" or "please fix the merge
+  conflicts" in a mention is enough. The run's status comment says what was
+  merged ("Merged `main` @ `1a2b3c4` into this branch; resolved conflicts in 2
+  files.").
+- **Checks apply to the agent's own changes**, measured against the automatic
+  merge: the target branch's changes, including to protected paths, merge as
+  they are, while an agent edit to a protected path (resolving a conflict in
+  one, or reverting the target's change to one) is refused as usual, so a
+  conflict in a protected path has to be resolved by hand. The
+  changed-file and diff-size limits count only the agent's changes, so merging
+  a busy target branch does not exhaust them.
+- **The push stays a fast-forward** of the head the run started from: a push
+  by anyone else in the meantime fails the run, with nothing pushed, as before.
+- A target branch that cannot be fetched or shares no history with the pull
+  request fails the run before the agent starts, with category `target_merge`
+  ([help](../help/errors/target-merge.md)).
+
+The clone is shallow, so wardby deepens its history step by step until the
+branch and its target share a commit, up to about 5,000 commits back.
+
 ## Automatic review fix rounds
 
 Linking an agent with the `review_fix` trigger (`access: "write"`, at most
@@ -196,6 +340,10 @@ without waiting for a human to ask. `reviewFixMaxRounds` (an integer from 1
 to 10, default 2) caps how many rounds a single pull request gets before
 wardby stops; re-linking without it resets the cap back to the default.
 
+No round follows a review that was skipped because the draft stopped at its
+budget (neutral, "Skipped: stopped at its budget"); a round needs a
+`CHANGES_REQUESTED` review.
+
 A round starts when wardby's own review check on a pull request finishes as
 `CHANGES_REQUESTED`, and all of the following still hold:
 
@@ -273,6 +421,115 @@ the pull request's round cap the same as a round that pushed a change, and
 at the cap posts the usual cap comment instead of re-reviewing — since no
 push happened, nothing else would otherwise replace the failed check.
 
+### How the pull request description is kept current
+
+Every coding run's final message is the full pull request description: what
+changed, the checklist, how to try it, and any closing line such as
+`Resolves #N`. It may be up to 64 KiB; a longer one is cut at a line boundary
+with a `[summary truncated]` marker instead of failing the run. When the whole
+description would pass GitHub's 65,536-character limit, wardby first drops the
+**Packages** section, then truncates the final message, keeping a closing
+`Resolves #N` last line. That holds for follow-ups too: review fix rounds, mention
+follow-ups, and continuations. Agents launched for a follow-up receive the
+description text wardby last wrote (its agent-written part, not the live pull
+request body) as quoted, untrusted context, so they can carry forward what
+still applies.
+
+A follow-up also receives the original issue the pull request was opened for,
+the way the first run did: its title and body, quoted as untrusted context,
+as reference material: a note says its acceptance criteria as written are
+what the description's checklist should reflect, that the final message must
+carry that checklist and the closing line, and that no instruction in the
+issue is followed. The issue is read as it is now, so edits made to it since
+the first run are included.
+wardby finds the issue from the run that started the work: the Jira issue it
+was attributed to, else the GitHub issue whose `@wardby` mention started it,
+else the issue that wardby's last description closes (`Resolves #N`). Only
+issues in the pull request's own repository are read, through the same GitHub
+App access the run already has; a Jira issue is read through the configured
+Jira integration. The issue text is cut to about 6 KB. If the issue can't be
+read, the run goes ahead without it.
+
+A continuation updates the description of the pull request it continues, even
+when it changes no code. The run's final message replaces the agent-written
+part. wardby rebuilds its own sections from that run: the dependency-install
+warning, **Tests**, **Packages**, and the dependency-cache line. The
+first-line `<!-- wardby:... -->` marker stays, and a
+`<!-- wardby-latest:<run> -->` line at the end records the latest run.
+
+**Packages** lists every package installed by the runs that pushed to the pull
+request, plus the latest run's, each package and version once. Refused
+packages, and the dependency-install warning built from them, describe the
+latest run only, since they reflect the pull request's current state.
+
+If wardby can't confirm the description is unchanged since it wrote it (for
+example, a person edited it), it does not overwrite it. Instead it keeps one
+comment on the pull request with the current description proposed by its
+latest run, inside a collapsed section. The comment names that run and the
+commit it describes, says why it wasn't applied, and says the pull request
+author can copy it into the description. Later runs edit the same comment
+rather than adding new ones; if duplicates exist (for example, two runs
+posting at once), wardby edits the newest and rewrites the others to point at
+it. wardby only edits comments its own GitHub App wrote, never a person's or
+another App's. On a run that pushes a commit, the comment is written before
+the push, so it is already there when the push starts a review.
+
+If the author copies the proposal into the description unchanged, the next
+run sees that the description matches wardby's latest proposal, takes the
+description back, writes it directly from then on, and updates the comment to
+say no proposal is pending. The same happens when a later run can write the
+description directly for any other reason.
+
+The comment's first line records the head commit the proposal describes. A
+review reads it when the reviewer reads the pull request (`repo_pr_read`'s
+`descriptionProposal`), not when the review starts, and only uses it when it
+was written for the head being reviewed. Then a description requirement
+(closing line, acceptance checklist, how to try it, test results) is met if
+either the live description or the proposal meets it. If the latest proposal
+is for another commit, the reviewer is told no proposal for this head exists
+yet and reviews the live description. The proposal reaches the reviewer as
+untrusted data, cut to 16 KB.
+
+Pull requests opened by an earlier wardby version have no record of what
+wardby wrote. For those, wardby rebuilds the description its first run would
+have written, from that run's stored final message, tests, packages,
+dependency-cache line and issue link, and compares it with the live
+description (ignoring the **Related pull requests** section, line endings and
+blank lines). If they match, nobody edited it: wardby replaces it and records
+it from then on. If anything differs, including any text a person added, or
+the stored records can't rebuild it, the description counts as edited and gets
+the comment.
+
+If the final message is empty, very short (fewer than 80 non-whitespace
+characters), or drops a
+closing keyword (such as `Resolves #N`) that the previous description had,
+wardby keeps the previous agent text and refreshes only its own sections.
+
+A description update does not start a separate review: it stays one review per
+pushed commit.
+
+`get_run` shows the result as `prDescriptionOutcome`:
+
+- `written`: the first description of a new pull request.
+- `replaced`: a continuation replaced the agent-written part.
+- `refreshed:<reason>`: the final message was invalid, so the previous agent
+  text was kept and only wardby's sections were refreshed. The reason is
+  `empty`, `too_short` (fewer than 80 non-whitespace characters), or
+  `missing_closing_keyword`.
+- `unchanged`: nothing needed to change.
+- `edited_by_hand`: wardby couldn't confirm the description is its own: a
+  person edited it, it no longer starts with wardby's marker, or (for pull
+  requests opened by an earlier version) it doesn't match the description
+  rebuilt from wardby's records. wardby posts or updates the proposal comment
+  when it can.
+- `skipped:<reason>`: the description was not updated. The reason is
+  `not_open` (the pull request is not open or was not found), `too_long` (the
+  description is still over 65,536 characters after dropping **Packages** and
+  truncating the final message), or
+  `error` (any failure, including a failed update request, a failed load of
+  wardby's last-written text, a failed hash record or access re-check, or the
+  60-second timeout; the update may still have landed).
+
 If a repository already forwards wardby's reviews to a webhook through a
 hand-written CI workflow to fix them automatically, replace that workflow
 with `review_fix`: link the trigger, then delete the workflow and its
@@ -317,6 +574,12 @@ requires more than owning the agent:
 - **A repository is the owner's binding.** Principals the agent is shared
   with (`grant_access`) can't link, unlink or change its repository, even at
   `write`.
+- **A coding agent's extra repositories follow the same rules.** A
+  `link_repository` call with `access: "write"` and no triggers on a coding
+  agent adds a repository its runs may work in; it needs the same GitHub write
+  access or admin approval as the default repository. Unlinking it
+  refuses queued runs for that repository when they start, and a run already under way is refused at
+  its final push check (`repo_access`), so nothing is pushed.
 
 The authorization is stamped on the link (`authorizedVia`: `host_permission`,
 `admin`, or `grandfathered`) and **checked again every time it is used**: on
@@ -394,26 +657,29 @@ with:
   endpoint answers 404 until this is set.
 - **Subscribe to events**: Pull request, Issue comment, Pull request review
   comment, Check run, Check suite (re-runs a review that was waiting for CI
-  once CI finishes, and starts a `waitForCi` reviewer's held review once CI
-  finishes), Issues (needed for mentions in a newly opened or
-  edited issue; without it only comment mentions are seen), and Push (needed
+  once CI finishes, starts a `waitForCi` reviewer's held review once CI
+  finishes, and lets [`markReadyWhenPassing`](#mark-ready-when-passing) mark a
+  draft ready once CI goes green; without it, those drafts stay drafts),
+  Issues (needed for mentions in a newly opened or edited issue; without it
+  only comment mentions are seen), and Push (needed
   for the `push` trigger, which starts merge-watcher agents; it is its own
   checkbox, separate from the others, and must be ticked explicitly).
 - **Repository permissions**:
 
-  | Permission      | Access          |
-  | --------------- | --------------- |
-  | Contents        | Read            |
-  | Pull requests   | Read and write  |
-  | Checks          | Read and write  |
-  | Issues          | Read and write  |
-  | Commit statuses | Read (optional) |
-
-  To let review agents resolve their own fixed threads, set **Contents** to
-  **Read and write**: GitHub gates resolving a review thread on that
-  permission, although it changes no repository content. wardby asks for it
-  only for the resolve call itself. An App that also opens coding pull
-  requests already has it.
+  | Permission      | Access                                             |
+  | --------------- | -------------------------------------------------- |
+  | Contents        | Read and write (Read for an App that only reviews) |
+  | Pull requests   | Read and write                                     |
+  | Checks          | Read and write                                     |
+  | Issues          | Read and write                                     |
+  | Commit statuses | Read (optional)                                    |
+
+  **Contents: Read and write** is required for coding agents, which push a
+  branch for each pull request they open. An App used only for review agents
+  can have **Read**, except that review agents then can't resolve their own
+  fixed threads: GitHub gates resolving a review thread on **Contents: Read
+  and write**, although it changes no repository content. wardby asks for it
+  only for the resolve call itself.
 
   **Issues: Read and write** is also what lets wardby add and remove the
   `wardby-autofix-*` labels used by [automatic review fix
@@ -540,9 +806,9 @@ linking stays disabled there.
 First link your GitHub account (`link_host_account`, above). Then use the
 `link_repository` tool (agents:write) on a native agent you own. Calling it
 again for an already-linked repository replaces that link's `access`,
-`triggers`, `checkName`, `reviewFixMaxRounds`, and `waitForCi` — omitted
-fields are cleared, not kept — and checks your access again, so always send
-the full desired state. Two common shapes:
+`triggers`, `checkName`, `reviewFixMaxRounds`, `waitForCi`, and
+`markReadyWhenPassing` — omitted fields are cleared, not kept — and checks
+your access again, so always send the full desired state. Two common shapes:
 
 **A reviewer**, which starts a check on every PR push:
 
@@ -670,6 +936,12 @@ yet.
   again: the request that opened it has already finished. A push that
   continues the pull request inside the same, still-running request is held
   like the first one.
+- From Wardby 0.7.0, a push to a pull request that is still a **draft** is
+  held while the coding run that pushed it may still be pushing (its result
+  is not recorded yet), so a run that stopped at its budget is never
+  reviewed mid-way. When that coding run was delegated by a lead that is
+  still running, as for a follow-up request, the review is held until that
+  lead finishes, the same as for the first request.
 - As with the CI fallback below, a hold here does not depend on the
   instance that started it still running when the lead run finishes:
   Wardby's reconciliation sweep reconsiders every review held for at least
@@ -757,13 +1029,203 @@ Turning `waitForCi` off (re-linking without it, or with it set to `false`)
 only changes how future pushes are handled; it never retroactively starts or
 drops a review already being held.
 
+### Large pull requests
+
+From Wardby 0.7.0, `repo_pr_read` returns a large pull request's diff in pages.
+All changed files share one character budget per call (`maxPatchChars`,
+default 60,000, at most 200,000). Source, test and configuration files get it
+first. Everything else follows: the repository root's `docs/`, `doc/` and
+`help/` folders; lockfiles; anything under a `generated/`, `__generated__/`,
+`dist/`, `vendor/`, `fixtures/`, `__fixtures__/`, `__snapshots__/` or
+`testdata/` folder at any depth; minified `.min.js` and `.min.css` files; and
+documents and images (`.md`, `.mdx`, `.rst`, `.adoc`, `.txt`, `.snap`, `.svg`,
+`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.ico`, `.pdf`, `.lock`).
+`requirements*.txt` and `CMakeLists.txt` count as code. A page that includes source, test or config files stops before the first doc, help, lockfile or generated file, so those come on later pages and a reviewer can skip them. Patches are split on line boundaries, and a file that does not fit on
+the page after other content moves to the next page. Each file has a
+`patchStatus`: `complete`, `partial`, `later_page`, `earlier_page`,
+`unavailable` (the host has no patch, for example a very large file; read it
+with `repo_read_file`) or `empty`. A `partial` file also reports
+`patchOffset`, where its part starts, and `patchContinues`, which is `true`
+when the next page carries more of the same file.
+
+When `patchesComplete` is `false`, the result lists `truncatedFiles`, gives
+`nextPatchCursor`, and estimates the files still to come in
+`remainingPatchFiles`. Call `repo_pr_read` again with the same arguments plus
+`patchCursor` to get the next page. Because code is filled first, a reviewer
+only has to page while a source, test or config file is still in
+`truncatedFiles`: the pages after that hold documentation, lockfiles and
+generated files, which the `unread_files` refusal never requires, so the
+reviewer can skim or skip them and spend less of its budget. A file the host found `unavailable` stays
+reported as such on later pages, and `patchesComplete` stays `false`. A cursor
+only works for the head and compare it was issued for: after a new push,
+`patch_cursor_stale` says to call again without it, and a damaged or oversized
+cursor returns `patch_cursor_malformed` (see
+[Patch cursor is malformed](../help/errors/patch-cursor-malformed.md)).
+
+`repo_publish_review` refuses `APPROVE` with
+`unread_files` while a source, test or config file of that head that
+`repo_pr_read` listed in the run is neither fully delivered nor read with
+`repo_read_file` at the head (one read of the path at the head counts).
+Every file any `repo_pr_read` of the head listed in the run stays gated: a
+later read with `sinceSha` lists fewer files but never takes any off.
+Removed files, documentation, lockfiles, generated files and fixtures are not
+gated, `CHANGES_REQUESTED` and `COMMENT` are always allowed, and the refusal
+changes nothing, so the agent can read the files and publish again. A file read in parts counts only
+when its parts join up from the start of its patch to its last part. The guard
+is per run attempt: a head is gated only when the attempt itself read its first
+page (a `repo_pr_read` without `patchCursor`), so an attempt resumed after a
+restart is not refused for pages an earlier attempt read. A reviewer that
+cannot read everything should publish `CHANGES_REQUESTED` and list the files it
+did not review. Not `COMMENT`: it completes the check as neutral, which GitHub
+branch protection treats as passing, so an unfinished review would let the pull
+request merge.
+
+The `unread_files` refusal applies in both execution modes. In `sandbox` mode
+(see [Native agent sandbox](native-sandbox.md)) the gateway saves what the run
+has read on its session after each `repo_pr_read` and `repo_read_file` call, so
+`repo_publish_review` checks the same reads as in `control-plane` mode.
+Reviewer prompts written before 0.7.0 still work, because the refusal tells
+the agent what to do; update them with the paging step from the shipped
+reviewer prompt.
+
+The file list itself has an upper bound: `repo_pr_read` lists at most 1,000
+changed files of a pull request, on GitHub and on a local repository alike,
+and on GitHub a `sinceSha` compare lists at most 300 (GitHub's own compare
+limit). When the pull request has more changed files than that, the result
+has `fileListComplete: false` and the files past the cut are not shown. Once
+a `repo_pr_read` of a head in the run is cut, `repo_publish_review` refuses
+`APPROVE` of that head with `file_list_truncated`, even when every listed file
+was read: an approval would cover files the agent never saw.
+`CHANGES_REQUESTED` and `COMMENT` still publish. Only a complete read of the
+whole pull request (without `sinceSha`) in the same run lifts the refusal, so
+an agent that passed `sinceSha` can call `repo_pr_read` again without it; a
+complete `sinceSha` read does not. A later run cannot approve the head through a
+`sinceSha` delta either, because a review whose list was cut never becomes a
+covered head (below). Otherwise `repo_publish_review` refuses the agent's
+`APPROVE` of that pull request: split it, or have a person review it. See
+[`file_list_truncated`](../help/errors/file-list-truncated.md).
+
+`sinceSha` accepts any earlier commit of the branch, so a read with it only
+narrows the review to the changes since that commit. `repo_pr_read` therefore
+also returns `lastCoveredSha`: the latest head this agent reviewed after
+reading every file, whatever the verdict. A review counts as covering its head
+when, in that run, no file list of the head was left cut, every source, test
+and config file it listed was read, and the run either read the whole pull
+request (no `sinceSha`) or compared only from the `lastCoveredSha` its reads
+returned. A review that does not cover its head keeps the earlier covered head.
+On GitHub the covered head is kept in the agent's summary comment marker (a
+summary comment written by a version before 0.7.0 has none, so the next review
+reads the whole pull request); on a local repository it is kept with each
+review. Only a marker at the very start of the App's own summary comment
+counts. In text an agent or a run supplies and the App posts (`repo_comment`,
+the summary, body and inline comments of `repo_publish_review`, and a mention
+run's status and reply), wardby escapes `<!--` as `&lt;!--` wherever it comes
+right before a wardby marker name, so such text shows as plain text and can
+never form a wardby marker. Any other HTML comment, such as one in a code
+block or a one-click suggestion, is posted as written. Text is escaped before
+its length limit is checked, and wardby adds its own markers after that. The coding-run status comment and the description comment are
+written by wardby and start with wardby's own marker. So an agent cannot be
+talked into vouching for a head it never read.
+
+`repo_publish_review` refuses `APPROVE` with `full_read_required` while the
+run has no `repo_pr_read` of the head without `sinceSha` and one of its reads
+compared from a commit other than the `lastCoveredSha` that read returned. A
+commit named in the pull request's own text, or `lastReviewedSha` when it
+differs from `lastCoveredSha`, is not a safe base. The agent reads the whole
+pull request (no `sinceSha`) or passes `lastCoveredSha`; the shipped reviewer
+prompt does this. See
+[`full_read_required`](../help/errors/full-read-required.md).
+
+Reviewer prompts written before 0.7.0 pass `lastReviewedSha` as `sinceSha`.
+They still work, because the refusal tells the agent to read the whole pull
+request, but update their re-review step from the shipped reviewer prompt to
+avoid the extra read. Owners of agents whose prompt is stored with the agent
+update it with `update_agent`.
+
+### Mark ready when passing (`markReadyWhenPassing`)
+
+With Wardby 0.7.0 or later, `markReadyWhenPassing` (boolean, default
+`false`, only on a write link — 400 on a read link) has wardby mark its own
+draft pull requests ready for review once they pass, instead of leaving
+that to a person. Set it with `link_repository` on the write link of the
+agent that the repository event triggers: a builder that opens the pull
+request itself, or — for a lead that delegates to a coding builder sub-agent
+— the lead's link. The coding builder needs no repository link of its own
+(coding agents can't have one). The setting counts for a pull request
+opened by that agent's own coding run or by a coding run anywhere below it
+in its run tree (up to 10 delegation levels); an opted-in agent that is not the
+opener or one of its ancestors in the run tree never counts. Re-linking that
+repository without it clears it, like every other link setting (see
+above); `list_repositories` shows its current value.
+
+Wardby marks a pull request ready for review once all of these hold, read
+fresh from GitHub on its current head:
+
+- the pull request is open and a draft;
+- Wardby's own GitHub App opened it, and its head is not in a fork;
+- the agent whose coding run opened it, or an agent that delegated to it
+  (directly or through other sub-agents), has `markReadyWhenPassing` set
+  on an authorized write link to this repository;
+- at least one authorized reviewer link with the `pull_request` trigger
+  exists on the repository, and every one of those reviewers' own checks on
+  the head completed with conclusion `success`;
+- CI is green: every check run and commit status on the head that is not
+  one of Wardby's own checks has completed with `success`, `neutral`, or
+  `skipped`, with at least one `success` — or the repository reports no CI
+  at all. All-neutral or all-skipped CI counts as inconclusive and waits. A
+  pull request with more checks and statuses than Wardby reads (about 50) is
+  truncated and never marked ready automatically. CI still pending, failing,
+  truncated, or unreadable leaves the pull request in draft; see the
+  re-evaluation triggers below for when Wardby checks again.
+- the `wardby merge order` check (see [The wardby merge order
+  check](../help/merge-order-check.md)) is `success`, or is not posted on
+  this pull request at all.
+
+A commit status only counts toward CI being green if the App can read it:
+grant **Commit statuses: Read** (see [Registering the GitHub
+App](#registering-the-github-app) above) if your CI reports commit statuses
+rather than check runs; without it, wardby judges CI from check runs alone.
+
+Wardby marks a given pull request ready at most once. If a person moves it
+back to draft afterward, wardby leaves it there — it never re-marks a pull
+request once it has done so.
+
+Wardby re-checks whether a pull request is ready to mark on any of these
+events:
+
+- a reviewer run finishing;
+- a CI check suite completing on its head;
+- its `wardby merge order` check turning `success` — for example, right
+  after an earlier step in its set merges;
+- and, as a fallback for any of the above missed, wardby's own merge-order
+  reconciliation sweep, for a pull request that is part of a merge-ordered
+  set (see [The reconciliation sweep](../help/merge-order-check.md#the-reconciliation-sweep)).
+
+CI that reports only commit statuses (no check suite) is not re-checked when
+it finishes — GitHub does not raise a check-suite event for a status-only
+commit. Such a pull request is marked ready the next time one of the events
+above fires, or stays in draft until then.
+
+With a merge-ordered set of delegated pull requests (see [Fanning out to
+several builders](agent-recipes.md#fanning-out-to-several-builders)), a
+later step only becomes ready for review once the steps it depends on have
+merged — it stays a draft until the `wardby merge order` check on it reports
+`success`.
+
+`markReadyWhenPassing` never approves, merges, or converts a pull request
+back to draft — a person's own approval stays the gate wherever branch
+protection requires one. It needs the App's **Pull requests: Read and
+write** permission, which an App that opens pull requests already has (see
+[Registering the GitHub App](#registering-the-github-app) above).
+
 ## The `repo_*` tools
 
 A linked agent gets these built-in tools automatically — they are not
 attached like ordinary tools, and never expose a token, check id, or
 internal marker to the model:
 
-- `repo_pr_read` — a pull request's metadata, per-file diff patches, the
+- `repo_pr_read` — a pull request's metadata, per-file diff patches (paged; see
+  [Large pull requests](#large-pull-requests)), the
   agent's own unresolved inline threads (`openThreads`), and `ci`: the head
   commit's check runs and commit statuses, excluding every check the wardby
   App itself reported (review checks, `wardby/continuation`), with `state`
@@ -787,6 +1249,13 @@ internal marker to the model:
   live state. The list of pull requests is current; the PR body's **Related
   pull requests** section can be stale (see
   [Related pull requests across repositories](../help/related-pull-requests.md)).
+  On a Wardby pull request whose description Wardby couldn't confirm as its
+  own text, it also returns `descriptionProposal`: `state: "current"` with
+  `forHead`, `runId`, `text` (Wardby's latest proposed description for this
+  head, cut to 16 KB, `truncated`) and a `note`, or
+  `state: "not_for_this_head"` with a `note` when the latest proposal is for
+  another commit. See
+  [How the pull request description is kept current](#how-the-pull-request-description-is-kept-current).
 - **Re-review when CI finishes.** When a review publishes `COMMENT` on its
   own check while CI on that head is `pending` or `none`, Wardby records it.
   When a CI check suite (not Wardby's own) completes on that head and no CI
@@ -801,6 +1270,24 @@ internal marker to the model:
   cases.
 - `repo_read_file` / `repo_list_files` — read a file or list a directory at
   a ref.
+- `repo_issue_read` (Wardby 0.7.0 or later) — read one issue, read-only:
+  `number`, `title`, `state` (`open` or `closed`), `body`, `labels`,
+  `author`, `url`, `createdAt`, `updatedAt`, and its 30 most recent comments
+  (`author`, `body`, `createdAt`), oldest first, with `totalComments`. The
+  body is capped at 32,000 characters and each comment at 4,000;
+  `truncated` is true when anything was cut (`bodyTruncated` and each
+  comment's `truncated` say where). A reviewer uses it to read the issue a
+  pull request says it resolves (`Resolves #N`) and check the change against
+  that issue's own acceptance criteria rather than the description's
+  restatement of them. It works on read and write links alike and needs the
+  App's **Issues: Read** permission. Issue text is written by whoever can
+  open or comment on issues: the tool description tells the agent to treat it
+  as data, never instructions. A pull request number is refused with
+  `is_pull_request` (use `repo_pr_read`), and a local repository has no
+  issues (`issues_unavailable`). For a pull request that resolves a Jira
+  issue, link the reviewer to that Jira project as well (`link_issue_project`,
+  read access is enough) so it can read the ticket with `jira_get_issue`; see
+  [Jira agents](jira-agents.md).
 - `repo_publish_review` — publish inline comments, a summary, and the check
   verdict for one PR head, in one call. A check is completed or created
   **only on the pull request the run was dispatched for** (by a push, a
@@ -818,22 +1305,30 @@ internal marker to the model:
 Every call names the `repository` explicitly; it must resolve to one of the
 agent's links. Failures are always a JSON result, never a thrown error:
 
-| `error` code                    | Meaning                                                                                                                                                                           |
-| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `invalid_arguments_json`        | The tool call's arguments were not valid JSON.                                                                                                                                    |
-| `invalid_arguments`             | Arguments failed schema validation (missing/malformed field).                                                                                                                     |
-| `repository_not_linked`         | `repository` does not match one of this agent's links, or matches more than one and needs a `host/owner/name` prefix to disambiguate.                                             |
-| `write_access_required`         | A write tool (`repo_publish_review`, `repo_comment`) was called on a read-only link.                                                                                              |
-| `repository_access_denied`      | The link is no longer authorized: the agent has no owner, the owner's GitHub account is unlinked or lost access, or it could not be checked.                                      |
-| `repository_access_unavailable` | GitHub could not be reached (or rate-limited wardby) while re-checking access, even after one retry; the call was refused for safety. Try again later.                            |
-| `host_not_configured`           | No host provider is configured for this link on this deployment.                                                                                                                  |
-| `unknown_tool`                  | Not a recognized `repo_*` tool name.                                                                                                                                              |
-| `host_not_installed`            | The GitHub App is not installed on this repository.                                                                                                                               |
-| `host_permission_missing`       | The App installation is missing a required permission.                                                                                                                            |
-| `host_invalid_response`         | The host returned something the client could not parse.                                                                                                                           |
-| `host_api_error`                | The request to GitHub failed (body-free: `github_api_error:<status>[:<request-id>]`).                                                                                             |
-| `ci_failing`                    | `repo_publish_review` called with verdict `APPROVE`, on a `waitForCi` link's own check, while CI on the head is failing. See [Review after CI](#review-after-ci-waitforci) above. |
-| `ci_pending`                    | Same, but CI on the head is still running.                                                                                                                                        |
+| `error` code                    | Meaning                                                                                                                                                                                                                                                                                                                                                                   |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `invalid_arguments_json`        | The tool call's arguments were not valid JSON.                                                                                                                                                                                                                                                                                                                            |
+| `invalid_arguments`             | Arguments failed schema validation (missing/malformed field).                                                                                                                                                                                                                                                                                                             |
+| `repository_not_linked`         | `repository` does not match one of this agent's links, or matches more than one and needs a `host/owner/name` prefix to disambiguate.                                                                                                                                                                                                                                     |
+| `write_access_required`         | A write tool (`repo_publish_review`, `repo_comment`) was called on a read-only link.                                                                                                                                                                                                                                                                                      |
+| `repository_access_denied`      | The link is no longer authorized: the agent has no owner, the owner's GitHub account is unlinked or lost access, or it could not be checked.                                                                                                                                                                                                                              |
+| `repository_access_unavailable` | GitHub could not be reached (or rate-limited wardby) while re-checking access, even after one retry; the call was refused for safety. Try again later.                                                                                                                                                                                                                    |
+| `host_not_configured`           | No host provider is configured for this link on this deployment.                                                                                                                                                                                                                                                                                                          |
+| `unknown_tool`                  | Not a recognized `repo_*` tool name.                                                                                                                                                                                                                                                                                                                                      |
+| `issue_not_found`               | `repo_issue_read`: no issue with that number in the repository (or the repository has issues turned off).                                                                                                                                                                                                                                                                 |
+| `is_pull_request`               | `repo_issue_read`: the number is a pull request; read it with `repo_pr_read`.                                                                                                                                                                                                                                                                                             |
+| `issues_unavailable`            | `repo_issue_read` on a local repository, which has no issues.                                                                                                                                                                                                                                                                                                             |
+| `host_not_installed`            | The GitHub App is not installed on this repository.                                                                                                                                                                                                                                                                                                                       |
+| `host_permission_missing`       | The App installation is missing a required permission.                                                                                                                                                                                                                                                                                                                    |
+| `host_invalid_response`         | The host returned something the client could not parse.                                                                                                                                                                                                                                                                                                                   |
+| `host_api_error`                | The request to GitHub failed (body-free: `github_api_error:<status>[:<request-id>]`).                                                                                                                                                                                                                                                                                     |
+| `ci_failing`                    | `repo_publish_review` called with verdict `APPROVE`, on a `waitForCi` link's own check, while CI on the head is failing. See [Review after CI](#review-after-ci-waitforci) above.                                                                                                                                                                                         |
+| `ci_pending`                    | Same, but CI on the head is still running.                                                                                                                                                                                                                                                                                                                                |
+| `patch_cursor_stale`            | `repo_pr_read` with a `patchCursor` issued for another head or compare (the pull request moved on). Call again without `patchCursor`.                                                                                                                                                                                                                                     |
+| `patch_cursor_malformed`        | `repo_pr_read` with a `patchCursor` it never issued (damaged, edited or over-long). Pass `nextPatchCursor` exactly as returned.                                                                                                                                                                                                                                           |
+| `unread_files`                  | `repo_publish_review` with `APPROVE` while a source, test or config file of the head was listed by `repo_pr_read` but never fully read (all pages via `patchCursor`, or `repo_read_file` at `headSha`). Read the files, or publish `CHANGES_REQUESTED` naming the files not reviewed.                                                                                     |
+| `full_read_required`            | `repo_publish_review` with `APPROVE` when the run read the head only with a `sinceSha` other than the `lastCoveredSha` that read returned. Call `repo_pr_read` without `sinceSha` (or with `lastCoveredSha`), or publish `CHANGES_REQUESTED`. See [Large pull requests](#large-pull-requests).                                                                            |
+| `file_list_truncated`           | `repo_publish_review` with `APPROVE` after a `repo_pr_read` of the head in the run had `fileListComplete: false` (more changed files than the host lists) and no complete read without `sinceSha` followed. Call `repo_pr_read` without `sinceSha` if it was passed; otherwise publish `CHANGES_REQUESTED` or `COMMENT`. See [Large pull requests](#large-pull-requests). |
 
 `repo_publish_review` also returns
 `{ "published": false, "reason": "stale_head", ... }` instead of an error when
@@ -861,6 +1356,23 @@ step.
 Check names and the description are repository content: treat them as data,
 as for every `repo_*` result.
 
+### Reviewer step: package audit mode
+
+From Wardby 0.7.0, a pull request whose coding run had
+[package audit mode](coding-packages.md#package-audit-mode) on opens with a
+`[!CAUTION]` banner. **Packages outside the allowlist** names what the
+registry installed that the agent's allowlist doesn't cover, and in `full`
+mode **Served despite advisories** lists versions with high or critical
+advisories. Wardby writes both from the registry's records, not from the
+agent. Add this to a reviewer's system prompt:
+
+    Reviewer step (package audit mode). If the description has a "Package
+    audit mode" caution banner, check every package under "Packages outside
+    the allowlist" (is it the package the change needs, spelled as its
+    upstream publishes it, and is it used?) and every row under "Served
+    despite advisories" (is the vulnerable code reachable?). Name any you
+    can't justify in your review.
+
 ## Branch protection
 
 To require a passing review before merge, add the link's `checkName` (e.g.
@@ -883,7 +1395,11 @@ of any reviewer link, tracking whether the pull requests it depends on have
 merged yet. Require it the same way — add `wardby merge order` as a
 required status check, with its expected source set to the wardby GitHub
 App — to block a merge until they have. See
-[The wardby merge order check](../help/merge-order-check.md).
+[The wardby merge order check](../help/merge-order-check.md). With Wardby
+0.7.0 or later, a builder opted into [Mark ready when passing
+(`markReadyWhenPassing`)](#mark-ready-when-passing-markreadywhenpassing)
+relies on this same check: a later step in the set is only marked ready for
+review once it reports `success`.
 
 ## Accepted gap: a run that fails outside its normal finish path leaves its check open