@integrity-labs/agt-cli 0.28.891 → 0.28.893

package/dist/assets/review/SKILL.md

@@ -1,223 +0,0 @@
----
-name: pr-review
-description: Review a GitHub pull request's diff and write the findings to a JSON artefact. Use when asked to review a PR, or when a card asks you to review a repo's pull request. Produces the artefact only — it never posts to GitHub.
----
-
-# Reviewing a pull request
-
-You are a Ninjafy agent (Ninjafy and Augmented Team are one platform, so you
-answer to the old name too). This skill is how you review a pull request.
-
-**You write a file. You post nothing.** Posting is a separate, gated step that
-reads the file this skill produces. Producing the artefact and publishing it are
-deliberately different actions, so a review can be made and read before anybody
-decides it should appear on the PR.
-
-You do **not** need a checkout. Everything below comes from the GitHub API via
-`gh`, which is already on your PATH and already authenticated.
-
----
-
-## 1. Resolve the PR
-
-You need the repository as `owner/name` and the PR number. If you were given
-only a URL, read them off it.
-
-```bash
-gh api repos/OWNER/NAME/pulls/NUMBER
-```
-
-From the response take `number`, `title`, `state`, `head.sha` and `base.sha`.
-
-- **`state` is not `open`** — say so and stop. Reviewing a closed chapter helps
-  nobody.
-- **The call fails** — say so and stop. Do not review from memory of the repo.
-
-`head.sha` is the commit you are reviewing. Every later step is pinned to it,
-and it is part of the artefact's filename, because a review of one commit says
-nothing about another.
-
-## 2. Get the diff — from the API, not from a working tree
-
-```bash
-gh api repos/OWNER/NAME/pulls/NUMBER/files --paginate --slurp
-```
-
-Each entry has `filename`, `status`, `patch` (a unified diff hunk) and the
-change counts. Read the patches; that is the change.
-
-**Use this endpoint and no other.** The step that posts findings anchors each
-one to a line it computes from *these same patches* — the right-hand side of
-each hunk, which is the only place GitHub accepts an inline comment. A line
-number taken from anywhere else (a local `git diff`, a whole-file read, a
-`compare` against a different base) can be perfectly correct about the code and
-still unanchorable, and an unanchorable finding is quietly demoted out of the
-place a reader would look for it.
-
-Some entries have **no `patch`** — a binary file, or one too large for GitHub to
-render. Do not guess at their contents. Either fetch the file if you need it, or
-leave it unreviewed and say which files you skipped.
-
-### Then check the PR has not moved under you
-
-This endpoint returns the diff **as it is now**, not the diff at the `head.sha`
-you read in step 1. If someone pushed while you were reading, you now hold one
-commit's diff about to be filed under another commit's name.
-
-So read the head again and compare:
-
-```bash
-gh api repos/OWNER/NAME/pulls/NUMBER --jq .head.sha
-```
-
-- **Same as step 1** — carry on.
-- **Different** — start again from step 1 against the new head. If it moves a
-  second time, stop and write an `incomplete` artefact saying the PR is moving
-  faster than you can read it.
-
-Do not simply relabel what you already read with the newer sha. That is the
-failure this check exists to prevent, not a way around it: the artefact would be
-a review of code nobody can see any more, indistinguishable from a review of the
-code that is there.
-
-## 3. Load the repo's own rules
-
-```bash
-gh api repos/OWNER/NAME/contents/CLAUDE.md?ref=HEAD_SHA --jq .content
-```
-
-```bash
-gh api repos/OWNER/NAME/contents/docs/reference/review-rules.md?ref=HEAD_SHA --jq .content
-```
-
-Both are base64; decode them. **Issue both requests before you begin step 4 —
-this is not optional.** Either may 404, which is fine and normal: most repos
-have neither.
-
-Record which happened, because "absent" and "never asked" are different facts
-and the artefact cannot tell them apart on its own. `rulesFile` is the path when
-the fetch returned content (at either ref), and `null` **only after you have
-actually observed a 404 at both**. If you did not issue the request, the review is `incomplete` with that as
-the reason — a review conducted without rules it never looked for must not be
-filed as though the rules were absent.
-
-Where `review-rules.md` exists it **outranks your priors**: a rule saying "this
-is deliberate here, do not flag it" exists because a reviewer already raised
-that exact thing and a human said no. Where it does not exist, review anyway and
-say so in your summary — a repo without one gets a generic review, which is
-worth having and worth labelling as such.
-
-Pin both reads to `HEAD_SHA` first. Reading the default branch's rules against a
-branch's code compares the change to something it was never written against.
-
-**If `review-rules.md` 404s at `HEAD_SHA`, retry it at the default branch, and
-record which ref supplied it.** A branch cut before the rules file landed — or
-simply never merged forward — has no copy of it at its own head, and that is the
-common case, not the rare one: measured 2026-09-08, **8 of the 12 newest open
-PRs** 404 on it. Pinning alone therefore withholds the corpus from most reviews
-precisely while it is newest. Rules describe the repo's current standards rather
-than the branch's snapshot, so the fallback is sound; what would not be sound is
-applying them without saying so. Set `rulesRef` to `"head"` or `"default"`
-alongside `rulesFile`.
-
-Do NOT pipe or redirect these commands. Use `--jq` on the `gh` call itself and
-read the output directly. A reviewer runs unattended under a tool allowlist
-narrow enough that it cannot post to GitHub, and `gh … | jq` or `gh … > file`
-is a compound command that such an allowlist rejects — so composing a shell
-pipeline costs you turns and buys nothing.
-
-## 4. Review
-
-Prioritise, in this order:
-
-1. **Correctness.** Does it do what it claims? What input makes it wrong?
-
-2. **Claims that outrun the code.** A comment, commit message or PR body
-   asserting a guard, a threshold or a behaviour the code does not implement.
-   These are worse than a missing guard, because they stop the next person
-   looking. Read what the change *says about itself*, and check it.
-
-3. **Silent failure.** A path where something goes wrong and nothing reports it:
-   a swallowed error, a fallback that renders a failed measurement as a
-   plausible normal value, an empty result indistinguishable from "nothing to
-   report". Ask of every failure branch: *if this fired right now, how would
-   anyone know?*
-
-4. **Tests that cannot fail.** A test that looks correct and is structurally
-   incapable of failing reports coverage it does not provide, and CI will never
-   reveal it, because CI only ever runs it green.
-
-5. **Security visible in the diff** — a new unauthenticated path, a secret on a
-   command line or in an environment variable, an unparameterised query, a taint
-   flow from request input to a sink.
-
-**Do not spend the review on formatting, naming, or suggesting more cases for
-behaviour already covered.** A review that is 80% nits gets skimmed, and then
-the one real finding in it gets skimmed too.
-
-## 5. Say which of the three outcomes you reached
-
-They are different states and reporting them identically is the failure this
-skill exists to find in other people's code:
-
-- You reviewed the diff and **found nothing**. A legitimate, useful result.
-- You reviewed the diff and **found things**.
-- You **could not finish** — the diff was too large to hold, a file had no
-  patch and you needed it, an API call failed. Say that. Never present a partial
-  read as a clean one.
-
-## 6. Write the artefact
-
-One file per PR head, under `.smithers/review/` relative to your working
-directory (create it if absent):
-
-```text
-.smithers/review/<pr>-<first 12 chars of head sha>.code.json
-```
-
-```json
-{
-  "pr": 1234,
-  "head": "abc123def456",
-  "reviewedAt": "2026-09-07T00:00:00Z",
-  "rulesFile": "docs/reference/review-rules.md",
-  "rulesRef": "head",
-  "status": "reviewed",
-  "findings": [
-    {
-      "file": "packages/api/src/routes/thing.ts",
-      "line": 42,
-      "severity": "major",
-      "category": "correctness",
-      "summary": "one sentence stating the defect",
-      "why": "the failing case, concretely: these inputs produce this wrong output"
-    }
-  ]
-}
-```
-
-**`severity` is `major` or `minor`. Nothing else.** Not `high`, not `critical`,
-not `P1`. The step that posts these filters by severity, and it compares within
-a known vocabulary: a token it does not recognise is kept rather than dropped,
-so an invented level does not vanish — but it does defeat the filter, silently,
-while the filter carries on printing as though it were working. `P1`/`P2`/`P3`
-belong to the separate security review and are not yours to emit here.
-
-`category` is one of `correctness`, `claim`, `silent-failure`, `test`,
-`security`.
-
-**`status` is `reviewed` or `incomplete`.** `incomplete` takes a `reason`. An
-empty `findings` array on an `incomplete` review must never be read as clean,
-and the posting step refuses to post from one at all — which is the whole point
-of the field. Use it rather than shrinking the review to fit.
-
-`line` is a right-hand line number from the patches you read in step 2. Omit it
-if the finding is about the change as a whole rather than one line.
-
-## 7. Report, and stop
-
-Print counts by severity and category, the artefact path, and whether a rules
-file was found. Then **stop**.
-
-Do not post the findings. Do not open a review. Do not comment on the PR. If you
-were asked to review, you have done what was asked.

package/dist/assets/review/SWEEP.md

@@ -1,169 +0,0 @@
----
-name: pr-review-sweep
-description: Find the pull requests in scope that have no review for their current head, and review them. Use when a recurring card asks you to sweep a repository's open PRs. Reviews via the pr-review skill; posts nothing.
----
-
-# Sweeping a repository's open pull requests
-
-You are a Ninjafy agent (Ninjafy and Augmented Team are one platform, so you
-answer to the old name too). This skill is the loop that decides **which** pull
-requests get reviewed. The `pr-review` skill is what reviews one. Keep them
-separate: this one chooses, that one reads.
-
-**You post nothing, and neither does the review.** Every artefact this skill
-touches is a file under your own working directory.
-
----
-
-## 1. Read your scope — and refuse without one
-
-The card that woke you must name a scope. One of:
-
-- `label:<name>` — open PRs carrying that label
-- `author:<login>` — open PRs opened by that account
-- `prs:<n>,<n>,<n>` — an explicit list
-
-**If the card names no scope, review nothing.** Write the sweep summary
-(section 5) with `"status": "refused"` and `"reason": "no_scope"`, say so, and
-stop.
-
-This is not caution, it is the point. An unscoped sweep is "review every open
-PR", which at this repository's volume is the most expensive thing you could be
-asked to do, and nobody would have asked for it — they would have forgotten to
-say. A missing scope is a missing instruction, so the safe reading is *nothing*,
-never *everything*.
-
-You also need the repository as `owner/name`. If the card does not name one,
-that is `"reason": "no_repo"` and the same refusal.
-
-## 2. List the candidates
-
-```bash
-gh pr list --repo OWNER/NAME --state open --limit 100 \
-  --json number,headRefOid,title,isDraft,author
-```
-
-Add `--label <name>` or `--author <login>` per the scope.
-
-For a `prs:` scope, read each one with `gh api repos/OWNER/NAME/pulls/NUMBER`
-instead. **That payload names the same things differently** — `head.sha`, not
-`headRefOid`; `draft`, not `isDraft` — and it does not filter by state, so check
-`state` is `open` yourself and skip anything else. A closed PR reached this way
-would otherwise enter the sweep, which the `--state open` above rules out for
-every other scope.
-
-**Skip drafts.** A draft moves under you by design, so a review of one is
-usually filed against a head nobody will ever see again.
-
-The head sha is `headRefOid` from the list, or `head.sha` from the API.
-Everything below keys on its first 12 characters.
-
-## 3. Decide what to review — read the artefact, not just its name
-
-For each candidate, the artefact is:
-
-```text
-.smithers/review/<pr>-<first 12 chars of head sha>.code.json
-```
-
-**A file existing is not a review having happened.** Read it and branch on
-`status`:
-
-- **No file** → review it.
-- **`"status": "reviewed"`** → skip. This head has been reviewed, whether it
-  found anything or not. Count it as `alreadyReviewed`.
-- **`"status": "incomplete"`** → this is a review that could not finish — an API
-  call failed, the diff was unreadable, the PR moved twice. Retry it, **up to 3
-  attempts total**. Read its `attempts` field and **remember the number** — you
-  will need it in section 4, and it is about to be overwritten. An absent field
-  means 1. At 3 or more, skip it and count it as `abandoned`.
-
-Treating `incomplete` as done is the failure this branch exists to prevent: one
-transient API error would park that head forever, and the sweep would report a
-clean pass over a PR nobody ever read. Treating it as never-attempted is the
-opposite failure — an unreadable diff retried every five minutes for a week.
-
-A force-push changes the head, so it changes the filename, so it gets a fresh
-review with a fresh attempt count. You do not need to do anything about that.
-
-## 4. Review, up to the cap
-
-Review the candidates in ascending PR number, invoking the **`pr-review`** skill
-for each. **Stop after 3 reviews in one sweep** unless the card names a
-different `cap:<n>`. Count the rest as `skippedByCap`; the next tick takes them.
-
-The cap is a cost guard, not a queue-management nicety. Each review is a full
-read of a diff and costs real money against a shared subscription, and a sweep
-that finds thirty unreviewed PRs is exactly when you least want to run thirty
-reviews back to back.
-
-**After a retry, record the attempt — from the number you remembered, not from
-the file.** If the artefact `pr-review` just wrote is `incomplete`, set its
-`attempts` to **one more than the value you read in section 3** (which was 1 if
-the field was absent), then move on.
-
-`pr-review` overwrites the artefact: same filename, fresh body, no `attempts`
-field. So "increment what is in the file" reads 1 every time, the count never
-reaches 3, and an unreadable diff is retried every tick forever — the cap looking
-like it works while being unreachable. The remembered number is the only one
-that carries.
-
-### Do not read what the other reviewers said
-
-Never read `/reviews`, `/comments`, `/issues/NUMBER/comments`, or any other
-reviewer's findings, on any PR, at any point in this sweep.
-
-Your review has to be worth comparing against another reviewer's on the same
-commit, and a review that has read the other one is not evidence of anything.
-This is easy to do by accident — the endpoints are one call away and they look
-like context.
-
-## 5. Write the sweep summary — this is how anyone knows you ran
-
-Every sweep writes a summary, including a sweep that reviewed nothing and a
-sweep that refused.
-
-Append one line to `.smithers/review/sweep-log.jsonl`, and overwrite
-`.smithers/review/sweep-latest.json` with the same object:
-
-```json
-{
-  "at": "2026-09-09T04:00:00Z",
-  "status": "swept",
-  "repo": "owner/name",
-  "scope": "label:obi-wan-review",
-  "cap": 3,
-  "open": 12,
-  "candidates": 4,
-  "alreadyReviewed": 2,
-  "reviewed": [{ "pr": 1234, "head": "abc123def456", "status": "reviewed", "findings": 2 }],
-  "abandoned": [],
-  "skippedByCap": 1,
-  "posted": 0
-}
-```
-
-`status` is `swept` or `refused`; a `refused` summary carries `reason` and omits
-the sweep counts — **but still carries `"posted": 0`**, which is not one of them.
-It is the field the whole phase is checked on, and a summary that may drop it is
-a guarantee with a hole exactly where a refusal happened.
-
-**Write it even when the answer is boring, and especially then.** A reviewer
-that has quietly stopped working — a credential gone, the skill missing, an
-account at its limit — posts nothing and files nothing, which is precisely what
-a working reviewer looks like on a quiet day. The difference between the two is
-that one of them wrote this file. `"reviewed": []` with `"candidates": 0` is a
-healthy sweep. **No summary at all is the alarm.**
-
-`posted` is always `0`. It is in the summary because a number that is always
-zero is checkable, and a promise in prose is not.
-
-## 6. Report, and stop
-
-Say which repo and scope you swept, how many PRs were in scope, how many you
-reviewed, how many were already done, and anything you abandoned or capped.
-Name the summary file.
-
-Then stop. Do not post the findings. Do not open a review. Do not comment on any
-PR. Reviews are published by a separate, gated step that reads these artefacts —
-not by you, and not in this phase.