@tduyng/pi-review 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,178 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+Use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2026 tduyng

package/README.md

@@ -1,3 +1,60 @@
-# Temporary Holding Version
+# @tduyng/pi-review
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A `/review` command that works out what to review and sends one focused review prompt.
+
+## The incremental loop
+
+Every `/review` snapshots the whole worktree (tracked and untracked) as a dangling git commit. No ref, no stash change, no branch commit. The snapshot sha sits in the session as a custom entry that never enters model context.
+
+Run `/review` and the agent reviews what moved since the last run. The delta is a tree-to-tree diff, so it covers edits to files that were untracked at checkpoint time and deletions of tracked files. When nothing moved, the command says so and sends nothing.
+
+Every review refreshes the snapshot, whichever target you named, so the next bare `/review` starts from that point. Git prunes the snapshot objects after roughly two weeks, and a pruned snapshot falls back to the default below. In an ephemeral `--no-session` run the snapshot lasts only for that process.
+
+## Targets
+
+A bare `/review` is resolved in code, with no model in the loop:
+
+1. The staged changes with `--staged`, which names the target outright, whatever the snapshot says.
+2. What moved since the last snapshot, if that snapshot still exists.
+3. Any uncommitted work, untracked files included.
+4. This branch against its merge base with the default branch.
+
+## What it adds
+
+- `/review [target]`. Bare resolves as above, anything else is passed through.
+- `--lean`. Adds a second pass for removable implementation complexity in the same change, and prints `Lean already.` when there is none.
+- `--extra "<text>"`. Acceptance criteria for the review. Repeatable, last wins.
+- `--model provider/model`. Runs the review on that model through the `subagent` tool. Without that tool the review runs inline and says the override could not be honored.
+- `--staged`. Reviews only the staged changes.
+
+Anything you type is the reviewer's request and goes to the prompt as written: `/review the change between main and HEAD`, `/review src/auth`, `/review first commit on this branch`. The prompt caps target resolution at three commands and tells the reviewer not to narrate them.
+
+## Focused review contract
+
+The extension resolves the diff and hands it over with two lines of context around each change, so the reviewer spends no tool calls on git. The diff is capped at 12,000 characters. Past that the stat still lists every file, and the reviewer is told how many characters it did not read.
+
+The reviewer writes the change's intent in one line first and judges the implementation against it. Supplied criteria replace that line. It reads the diff before opening any file, opens at most two files the diff does not already show, and runs at most one targeted command, all inside a budget of eight tool calls including any target resolution.
+
+The response is under 15 lines: a verdict, the intent line, one line per finding with a P0 to P3 severity and a concrete fix, and one `Checks:` line.
+
+## Examples
+
+```
+/review                                    # what moved, or the branch default
+/review --staged                           # staged changes only
+/review the change between main and HEAD   # any target you describe
+/review --lean --extra "retries must not double-charge" src/auth
+/review --model opencode-go/gpt-6-luna the retry logic
+```
+
+## Install
+
+```bash
+pi install npm:@tduyng/pi-review
+```
+
+Local checkout: `pi install /path/to/dotfiles/pi/agent/extensions/pi-review`
+
+## Configure
+
+None. It works out of the box inside a git repository.

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@tduyng/pi-review",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "/review resolves a target from git, collects project ground truth, and sends a structured review prompt inline or through a subagent.",
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "code-review",
+    "git"
+  ],
+  "homepage": "https://gitlab.com/tduyng/pi-agent/-/tree/main/extensions/pi-review#readme",
+  "bugs": "https://gitlab.com/tduyng/pi-agent/-/issues",
+  "license": "Apache-2.0",
+  "author": "tduyng",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/tduyng/pi-agent.git",
+    "directory": "extensions/pi-review"
+  },
+  "type": "module",
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "dependencies": {
+    "ata-validator": "^1.62.1"
+  }
+}

package/src/README.md

@@ -0,0 +1,143 @@
+# review
+
+A native `/review` command. It resolves what to review from a sentence and injects
+a focused code-change review prompt into the current session. The review runs here,
+on the model you are already talking to. Change the model with `--model`, which
+asks the agent to delegate through the `subagent` tool when that tool is active.
+
+Every review leaves a checkpoint, so a bare `/review` afterwards reviews only
+what changed since (see Checkpoints below).
+
+## Usage
+
+```
+/review                                            # smart default
+/review current diff
+/review staged
+/review the change between feature and main
+/review from v1.2.0 to HEAD
+/review commit 3f9a1c2
+/review HEAD~2
+/review first commit
+/review https://github.com/org/repo/pull/123
+/review https://gitlab.com/group/proj/-/merge_requests/45
+/review pr 42
+/review src/auth tests                    # snapshot of these paths
+/review --lean --extra "focus on the retry logic"
+/review --model opencode-go/gpt-6-luna src/auth
+```
+
+## How it picks the target
+
+`resolve.ts` walks a fixed order and stops at the first match. It runs on a
+lowercase copy for keywords but resolves every ref against the original text.
+
+1. `--base <ref>` overrides everything and reviews `HEAD` against that ref.
+2. An empty query uses the smart default below.
+3. A PR or MR URL. GitHub, GitLab, and Bitbucket links are recognized.
+4. `pr 42`, `mr 42`, `pull request 42`, `merge request 42`.
+5. A range. `a...b` is a merge-base diff, `a..b` is a two-dot diff.
+6. Keywords. `current diff`, `current changes`, `working tree`, `uncommitted`,
+   `local changes`, `my changes`, `my diff`, `what i changed`, `staged`,
+   `unstaged`, `first commit`, `initial commit`, `root commit`, `last commit`,
+   `latest commit`, `head commit`, `tip`, and `since last review` (with its
+   variants).
+7. A pair. `from X to Y`, `between X and Y`, `compare X and Y`, `X vs Y`,
+   `X versus Y`, `X against Y`. The base side is the default branch when one of
+   the two is the default branch, otherwise the first ref is the base.
+8. A single base ref. `against X`, `vs X`, `compared to X`, `base X`, `branch X`.
+9. A single commit. A 7 to 40 char hex sha, or `HEAD`, `HEAD~2`, `HEAD^`, `@`.
+10. A single branch or ref name that is not the current branch. It becomes the
+    base and `HEAD` is the head.
+11. One or more existing paths. This is a snapshot review of the current state,
+    not a diff. A leading `folder`, `files`, `path`, or `dir` is dropped.
+12. Anything left becomes a free-form request. The prompt tells the agent to work
+    out the refs with `git status`, `git branch`, `git log`, and `git remote`
+    before reviewing.
+
+## Smart default
+
+With no arguments:
+
+- With a checkpoint from a previous review and a non-empty delta: review only
+  what changed since that checkpoint.
+- Dirty tree, tracked or untracked: review the uncommitted changes.
+- Clean, on a branch other than the default base, and ahead of that base: review
+  the whole active branch against its merge-base with the default base.
+- Otherwise: review `HEAD`.
+
+## Focused review
+
+The default review reads the exact git target, then inspects changed implementation
+files and only the direct imports, callers, serializers, migrations, generated
+interfaces, and tests needed to prove that contracts still fit. It uses the
+conventions of each changed language and follows direct consumers across language
+boundaries. It checks renamed symbols, signatures, schemas, required and optional
+fields, nullability, runtime producers and consumers, and changed behavior. It
+does not scan the whole repository, inspect unrelated history, or run the full
+test suite. It uses at most eight tool calls and returns a verdict, concrete
+findings, and the exact checks it ran.
+
+`--extra` is the acceptance criteria for the review. Use it to state the specific
+requirement to verify.
+
+## Checkpoints
+
+After every `/review` (any target), the extension snapshots the whole worktree,
+tracked and untracked, as a dangling git commit object: no ref, no commit on
+your branch, no index or stash change. The snapshot sha and a timestamp are
+appended to the session as a `review/checkpoint` custom entry, which never
+enters model context.
+
+The next bare `/review` diffs the checkpoint snapshot against a fresh snapshot
+and reviews only that delta. This is the review loop without any GUI: run
+`/review`, let the agent work, run `/review` again and pay only for the new
+changes. When nothing changed since the checkpoint, the command says so and
+sends nothing.
+
+Details that follow from the mechanism:
+
+- Any explicit target (`review uncommitted`, `review main`, a PR, whatever)
+  still refreshes the checkpoint, so the next bare `/review` is a delta from
+  there. This is also the reset path.
+- `since last review` asks for the delta explicitly. Without a checkpoint it
+  falls back to the smart default.
+- The delta is a tree-to-tree diff, so it covers edits to files that were
+  untracked at checkpoint time and deletions, not just edits to tracked files.
+- Checkpoints ride the session: resuming or branching a session keeps its own
+  review state. Git prunes the snapshot objects after roughly two weeks, and a
+  pruned checkpoint falls back to the full smart default.
+- In an ephemeral `--no-session` run, the checkpoint lasts only for that
+  process.
+
+## Rubric
+
+`prompt.ts` carries the focused review contract. It limits the review to the
+requested change and its direct consumers in any language, calibrates severity,
+and requires each finding to name `file:line` and a concrete fix. The response
+stays under 15 lines and includes one `Checks:` line.
+
+## Flags
+
+| Flag                     | Effect                                                                                                                                                                                         |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--lean`                 | Adds a second pass for removable implementation complexity in the same change. A clean pass reads `Lean already.`                                                                              |
+| `--model provider/model` | Asks the agent to run the review on that model through the `subagent` tool when it is active. With no such tool, the prompt says the override could not be honored and the review runs inline. |
+| `--extra "<text>"`       | Sets the acceptance criteria for the review. Repeatable, the last wins.                                                                                                                        |
+| `--base <ref>`           | Reviews `HEAD` against `<ref>` regardless of the rest of the query.                                                                                                                            |
+| `--staged`               | Reviews only staged changes when the target is otherwise uncommitted.                                                                                                                          |
+
+## Files
+
+- `index.ts` registers `/review` and runs resolve, prompt, send.
+- `resolve.ts` turns a query and flags into a `ReviewTarget`.
+- `args.ts` splits flags from the free-form query with a quote-aware tokenizer.
+- `git.ts` is the real `Git` implementation over `pi.exec`, including the
+  worktree snapshot and the empty-delta probe.
+- `checkpoint.ts` reads and writes the session checkpoint entries.
+- `prompt.ts` holds the rubric and builds the injected prompt.
+- `types.ts` holds the shared types and the `Git` interface.
+
+Tests live in `../tests/review-*.test.ts` and cover the resolver, the arg parser,
+the prompt builder, the command handler, and the git layer against a real
+repository.

package/src/args.ts

@@ -0,0 +1,40 @@
+import type { ParsedArgs, ReviewFlags } from './types.js'
+
+const VALUE_FLAGS = ['extra', 'model'] as const
+const BOOLEAN_FLAGS = ['lean', 'staged'] as const
+
+function takeValue(raw: string, name: string): [string | null, string] {
+    const match = new RegExp(`--${name}(?:=|\\s+)("([^"]*)"|'([^']*)'|(\\S+))`).exec(raw)
+    if (match === null) return [null, raw]
+    const value = match[2] ?? match[3] ?? match[4] ?? ''
+    if (value.startsWith('--')) return [null, raw]
+    const rest = raw.slice(0, match.index) + ' ' + raw.slice(match.index + match[0].length)
+    return [value, rest]
+}
+
+export function parseReviewArgs(raw: string): ParsedArgs {
+    const flags: ReviewFlags = { lean: false, staged: false }
+    let query = raw
+
+    for (const name of VALUE_FLAGS) {
+        let taken = takeValue(query, name)
+        while (taken[0] !== null) {
+            if (taken[0].trim() !== '') flags[name] = taken[0]
+            query = taken[1]
+            taken = takeValue(query, name)
+        }
+    }
+
+    for (const name of BOOLEAN_FLAGS) {
+        const match = new RegExp(`(?:^|\\s)--${name}(?=\\s|$)`).exec(query)
+        if (match !== null) {
+            flags[name] = true
+            query = query.slice(0, match.index) + ' ' + query.slice(match.index + match[0].length)
+        }
+    }
+
+    const dangling = /(?:^|\s)--(extra|model)(?=\s|$)/.exec(query)
+    if (dangling !== null) return { flags, query: '', error: `Missing value for --${dangling[1]}` }
+
+    return { flags, query: query.replace(/\s+/g, ' ').trim() }
+}

package/src/checkpoint.ts

@@ -0,0 +1,26 @@
+import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-coding-agent'
+import { Validator } from 'ata-validator'
+import { t } from 'ata-validator/t'
+
+import type { ReviewCheckpoint } from './types.js'
+
+export const CHECKPOINT_ENTRY = 'review/checkpoint'
+
+const CheckpointSchema = t.object({
+    version: t.literal(1),
+    baseSha: t.string({ pattern: '^[0-9a-f]{40}$' }),
+    createdAt: t.number()
+})
+const isCheckpointSchema = new Validator(CheckpointSchema).isValidObject
+
+export function latestCheckpoint(ctx: ExtensionCommandContext): ReviewCheckpoint | null {
+    for (const entry of ctx.sessionManager.getBranch().toReversed()) {
+        if (entry.type !== 'custom' || entry.customType !== CHECKPOINT_ENTRY) continue
+        if (isCheckpointSchema(entry.data)) return entry.data
+    }
+    return null
+}
+
+export function saveCheckpoint(pi: ExtensionAPI, baseSha: string): void {
+    pi.appendEntry<ReviewCheckpoint>(CHECKPOINT_ENTRY, { version: 1, baseSha, createdAt: Date.now() })
+}

package/src/git.ts

@@ -0,0 +1,93 @@
+import { randomUUID } from 'node:crypto'
+import { rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+
+import type { Git } from './types.js'
+
+interface RunResult {
+    code: number
+    stdout: string
+}
+
+export function createGit(pi: ExtensionAPI, cwd: string): Git {
+    async function run(args: string[]): Promise<RunResult> {
+        const result = await pi.exec('git', args, { cwd })
+        return { code: result.code, stdout: result.stdout }
+    }
+
+    async function revParse(ref: string): Promise<string | null> {
+        const { code, stdout } = await run(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`])
+        const sha = stdout.trim()
+        return code === 0 && sha ? sha : null
+    }
+
+    async function emptyTree(): Promise<string | null> {
+        const indexFile = join(tmpdir(), `pi-review-${randomUUID()}`)
+        try {
+            const tree = await pi.exec('env', [`GIT_INDEX_FILE=${indexFile}`, 'git', 'write-tree'], { cwd })
+            const sha = tree.stdout.trim()
+            return tree.code === 0 && /^[0-9a-f]{40}$/.test(sha) ? sha : null
+        } catch {
+            return null
+        } finally {
+            rmSync(indexFile, { force: true })
+        }
+    }
+
+    return {
+        revParse,
+        emptyTree,
+
+        async mergeBase(a: string, b: string): Promise<string | null> {
+            const { code, stdout } = await run(['merge-base', a, b])
+            const sha = stdout.trim()
+            return code === 0 && sha ? sha : null
+        },
+
+        async defaultBranch(): Promise<string> {
+            const symbolic = await run(['symbolic-ref', 'refs/remotes/origin/HEAD', '--short'])
+            const remoteHead = symbolic.stdout.trim()
+            if (symbolic.code === 0 && remoteHead.startsWith('origin/')) return remoteHead.slice('origin/'.length)
+            if ((await revParse('refs/heads/main')) !== null) return 'main'
+            if ((await revParse('refs/heads/master')) !== null) return 'master'
+            return 'main'
+        },
+
+        async isDirty(): Promise<boolean> {
+            const { code, stdout } = await run(['status', '--porcelain'])
+            return code === 0 && stdout.trim().length > 0
+        },
+
+        async snapshotWorktree(): Promise<string | null> {
+            const indexFile = join(tmpdir(), `pi-review-${randomUUID()}`)
+            const env = (args: string[]) => pi.exec('env', [`GIT_INDEX_FILE=${indexFile}`, 'git', ...args], { cwd })
+            try {
+                const head = await revParse('HEAD')
+                if (head !== null) await env(['read-tree', 'HEAD'])
+                await env(['add', '-A'])
+                const tree = await env(['write-tree'])
+                const treeSha = tree.stdout.trim()
+                if (tree.code !== 0 || !/^[0-9a-f]{40}$/.test(treeSha)) return null
+                const parent = head !== null ? ['-p', head] : []
+                const commit = await run(['commit-tree', treeSha, ...parent, '-m', 'review checkpoint'])
+                const sha = commit.stdout.trim()
+                return commit.code === 0 && /^[0-9a-f]{40}$/.test(sha) ? sha : null
+            } catch {
+                return null
+            } finally {
+                rmSync(indexFile, { force: true })
+            }
+        },
+
+        async diffEmpty(a: string, b: string): Promise<boolean> {
+            return (await run(['diff', '--quiet', a, b])).code === 0
+        },
+
+        async diffText(args: string[]): Promise<string | null> {
+            const { code, stdout } = await run(['diff', ...args])
+            return code === 0 ? stdout : null
+        }
+    }
+}

package/src/index.ts

@@ -0,0 +1,75 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+
+import { parseReviewArgs } from './args.js'
+import { latestCheckpoint, saveCheckpoint } from './checkpoint.js'
+import { createGit } from './git.js'
+import { buildReviewPrompt, describeTarget } from './prompt.js'
+import { defaultTarget, targetRefs } from './target.js'
+import type { Git, ReviewDiff, ReviewTarget } from './types.js'
+
+const MAX_DIFF_CHARS = 12_000
+const SINCE_LAST_REVIEW = /\bsince (?:my )?(?:the )?last review\b/
+
+async function reviewDiff(git: Git, target: ReviewTarget, worktree: string | null): Promise<ReviewDiff | null> {
+    const refs = await targetRefs(git, target, worktree)
+    if (refs === null) return null
+    const [stat, diff] = await Promise.all([git.diffText([...refs, '--stat']), git.diffText([...refs, '-U2'])])
+    if (diff === null) return null
+    return {
+        stat: stat ?? '',
+        body: diff.slice(0, MAX_DIFF_CHARS),
+        truncated: diff.length > MAX_DIFF_CHARS,
+        total: diff.length
+    }
+}
+
+export default function reviewExtension(pi: ExtensionAPI): void {
+    pi.registerCommand('review', {
+        description: 'Review a diff, what moved since the last review, or a target you describe.',
+        handler: async (args, ctx) => {
+            const repo = await pi.exec('git', ['rev-parse', '--git-dir'], { cwd: ctx.cwd })
+            if (repo.code !== 0) {
+                ctx.ui.notify('Not a git repository', 'error')
+                return
+            }
+
+            const parsed = parseReviewArgs(args)
+            if (parsed.error !== undefined) {
+                ctx.ui.notify(parsed.error, 'error')
+                return
+            }
+
+            const git = createGit(pi, ctx.cwd)
+            const checkpoint = latestCheckpoint(ctx)
+            const target =
+                parsed.query === '' || (checkpoint !== null && SINCE_LAST_REVIEW.test(parsed.query))
+                    ? await defaultTarget(git, checkpoint, parsed.flags.staged)
+                    : { kind: 'request' as const, text: parsed.query }
+            if (target === null) {
+                ctx.ui.notify('Nothing to review.', 'info')
+                return
+            }
+
+            const boundary = target.kind === 'since' ? target.nowSha : await git.snapshotWorktree()
+            const diff = await reviewDiff(git, target, boundary)
+            if (diff !== null && diff.total === 0) {
+                ctx.ui.notify('Nothing to review.', 'info')
+                return
+            }
+            // A request target has no refs to diff, so the reviewer resolves it itself; every
+            // other target that could not produce a diff must not advance the checkpoint, or
+            // the next bare /review would skip the changes that were never reviewed.
+            if (boundary !== null && (diff !== null || target.kind === 'request')) saveCheckpoint(pi, boundary)
+
+            ctx.ui.notify('Reviewing ' + describeTarget(target), 'info')
+            pi.sendUserMessage(
+                buildReviewPrompt({
+                    target,
+                    diff,
+                    flags: parsed.flags,
+                    subagentAvailable: pi.getActiveTools().includes('subagent')
+                })
+            )
+        }
+    })
+}

package/src/prompt.ts

@@ -0,0 +1,103 @@
+import type { ReviewDiff, ReviewFlags, ReviewTarget } from './types.js'
+
+export const FOCUSED_REVIEW_RUBRIC = `# Focused code-change review
+
+Review only the requested change, and judge whether the changed implementation does what the
+change claims. This is not a repository audit.
+
+Write the change's intent in one line before anything else, from the diff and the request alone.
+That line is your criteria. Supplied acceptance criteria replace it.
+
+Then, in this order:
+1. Read the whole diff below before opening any file. When it is truncated, say in the Checks
+   line how many characters you did not read, and review only what you can see.
+2. Read the changed implementation files. Open at most two files the diff does not already
+   show you, and only when a changed line names a symbol whose definition you have not seen.
+3. Check what the change breaks: renamed symbols, signatures, schemas, required and optional
+   fields, nullability, runtime producers and consumers, changed behavior. Cross into another
+   language only when the diff changes a contract that crosses it.
+4. Run at most one targeted compiler, typecheck, lint or test command, only to settle a doubt
+   the diff raised. Never the full suite.
+
+Eight tool calls is the whole budget, including any spent working out the target. Never announce a
+tool call or restate the plan before making it. Do not search the repository, read unrelated
+history or broad project documentation. A doubt you cannot prove from what you read is not a
+finding: say it is unproven and stop.
+
+Report only what this change introduced and the author would fix: a stale symbol, a caller that
+was not updated, a wrong runtime value, an invalid contract, a broken test. Not findings:
+pre-existing problems, style preference, unrequested refactors, and anything you cannot point at
+a changed line for.
+
+P0 release-blocking. P1 urgent correctness. P2 normal bug. P3 minor. Use the lowest severity the
+evidence supports.`
+
+const LEAN_PASS = `## Lean pass
+
+Only after correctness, list removable implementation complexity in the same diff. One line per
+finding: \`file:line\`, what to cut, and the replacement. Do not propose removing input validation,
+security, accessibility, or error handling. On a clean pass write exactly \`Lean already.\``
+
+const OUTPUT_BLOCK = `## Output
+
+Keep the response under 15 lines:
+1. First line: \`correct\` or \`needs attention\`.
+2. Second line: \`Intent: <the one-line intent>\`.
+3. Findings, one per line: \`[P0|P1|P2|P3] file:line - problem. fix: <specific change>\`.
+   Reference changed lines. If none, write \`No findings.\`
+4. One \`Checks:\` line with the exact command run and its result, or \`not run\`.`
+
+function resolveMergeBase(base: string): string {
+    return `Review what this branch would merge into \`${base}\`. Run \`git merge-base ${base} HEAD\` first, then read that diff with \`--no-prefix -U0\`.`
+}
+
+function resolveRequest(text: string): string {
+    return `The reviewer's request: ${text}\n\nWork the target out yourself in at most three commands: \`git status --porcelain\`, \`git log --oneline -10\`, \`git branch -a\`. Do not narrate them. Then read that diff with \`--no-prefix -U0\`. If the request is ambiguous, name the target you picked in one line and review it.`
+}
+
+function whatToReview(target: ReviewTarget, diff: ReviewDiff | null): string {
+    if (target.kind === 'request') return resolveRequest(target.text)
+    if (target.kind === 'base' && target.mergeBase === null) return resolveMergeBase(target.base)
+    if (diff === null) return 'git returned no diff for this target.'
+
+    const cut = diff.truncated ? `\n\n[truncated: ${diff.total} characters in total]` : ''
+    return `The stat, then the diff.\n\n${diff.stat}\n${diff.body}${cut}`
+}
+
+export function describeTarget(target: ReviewTarget): string {
+    switch (target.kind) {
+        case 'uncommitted':
+            return target.staged ? 'staged changes' : 'uncommitted changes'
+        case 'since':
+            return 'changes since the last review'
+        case 'base':
+            return `this branch against ${target.base}`
+        case 'request':
+            return `request "${target.text}"`
+    }
+}
+
+export interface BuildReviewPromptInput {
+    target: ReviewTarget
+    diff: ReviewDiff | null
+    flags: ReviewFlags
+    subagentAvailable: boolean
+}
+
+function modelOverride(model: string, subagentAvailable: boolean): string {
+    if (!subagentAvailable) {
+        return `## Model override\n\nThe user asked for model \`${model}\` and no delegation tool is available here. Review on the current model and say in one line that \`--model ${model}\` could not be honored.`
+    }
+    return `## Model override\n\nThe user asked for this review to run on model \`${model}\`. Delegate it to the subagent tool with model: "${model}" and a read-only profile. Pass this entire prompt, then relay the result verbatim.`
+}
+
+export function buildReviewPrompt(input: BuildReviewPromptInput): string {
+    const blocks = [FOCUSED_REVIEW_RUBRIC, '---', `## What to review\n\n${whatToReview(input.target, input.diff)}`]
+
+    if (input.flags.extra !== undefined) blocks.push(`## Acceptance criteria\n\n${input.flags.extra}`)
+    if (input.flags.lean) blocks.push(LEAN_PASS)
+    if (input.flags.model !== undefined) blocks.push(modelOverride(input.flags.model, input.subagentAvailable))
+    blocks.push(OUTPUT_BLOCK)
+
+    return blocks.join('\n\n')
+}

package/src/target.ts

@@ -0,0 +1,41 @@
+import type { Git, ReviewCheckpoint, ReviewTarget } from './types.js'
+
+export async function defaultTarget(
+    git: Git,
+    checkpoint: ReviewCheckpoint | null,
+    staged: boolean
+): Promise<ReviewTarget | null> {
+    if (staged) return { kind: 'uncommitted', staged: true }
+    if (checkpoint !== null && (await git.revParse(checkpoint.baseSha)) !== null) {
+        const nowSha = await git.snapshotWorktree()
+        if (nowSha !== null) {
+            return (await git.diffEmpty(checkpoint.baseSha, nowSha))
+                ? null
+                : { kind: 'since', baseSha: checkpoint.baseSha, nowSha }
+        }
+    }
+
+    if (await git.isDirty()) return { kind: 'uncommitted', staged: false }
+
+    const base = await git.defaultBranch()
+    const mergeBase = await git.mergeBase(base, 'HEAD')
+    if (mergeBase !== null && (await git.diffEmpty(mergeBase, 'HEAD'))) return null
+    return { kind: 'base', base, mergeBase }
+}
+
+export async function targetRefs(git: Git, target: ReviewTarget, worktree: string | null): Promise<string[] | null> {
+    switch (target.kind) {
+        case 'uncommitted': {
+            if (target.staged) return ['--cached']
+            if (worktree === null) return ['HEAD']
+            const base = (await git.revParse('HEAD')) ?? (await git.emptyTree())
+            return base === null ? ['HEAD'] : [base, worktree]
+        }
+        case 'since':
+            return [target.baseSha, target.nowSha]
+        case 'base':
+            return target.mergeBase === null ? null : [target.mergeBase, 'HEAD']
+        case 'request':
+            return null
+    }
+}

package/src/types.ts

@@ -0,0 +1,42 @@
+export type ReviewTarget =
+    | { kind: 'uncommitted'; staged: boolean }
+    | { kind: 'since'; baseSha: string; nowSha: string }
+    | { kind: 'base'; base: string; mergeBase: string | null }
+    | { kind: 'request'; text: string }
+
+export interface ReviewFlags {
+    lean: boolean
+    staged: boolean
+    model?: string
+    extra?: string
+}
+
+export interface ParsedArgs {
+    flags: ReviewFlags
+    query: string
+    error?: string
+}
+
+export interface ReviewDiff {
+    stat: string
+    body: string
+    truncated: boolean
+    total: number
+}
+
+export interface Git {
+    revParse(ref: string): Promise<string | null>
+    emptyTree(): Promise<string | null>
+    mergeBase(a: string, b: string): Promise<string | null>
+    defaultBranch(): Promise<string>
+    isDirty(): Promise<boolean>
+    snapshotWorktree(): Promise<string | null>
+    diffEmpty(a: string, b: string): Promise<boolean>
+    diffText(args: string[]): Promise<string | null>
+}
+
+export interface ReviewCheckpoint {
+    version: 1
+    baseSha: string
+    createdAt: number
+}