@0xcraft/powershot 1.1.5 → 1.2.0

package/README.md

@@ -180,8 +180,8 @@ commands.
 flowchart LR
     START["Selected files and checks"] --> ACCOUNT{"Required work accounted for?"}
     ACCOUNT -- "yes" --> DEPTH{"Enriched semantic depth available?"}
-    DEPTH -- "yes" --> FULL["full coverage"]
-    DEPTH -- "no · portable policy" --> PORTABLE["portable coverage · gaps named"]
+    DEPTH -- "yes" --> FULL["full applicable-oracle coverage"]
+    DEPTH -- "no · portable policy" --> PORTABLE["portable oracle coverage · gaps named"]
     FULL --> FINDINGS{"Findings?"}
     PORTABLE --> FINDINGS
     FINDINGS -- "no" --> CLEAN["exit 0 · complete and clean"]
@@ -206,11 +206,11 @@ flowchart LR
 | `2` | Command or Git input was invalid |
 | `3` | Review is incomplete; findings may be missing |
 
-A clean report names its effective severity threshold, deterministic/model mode, file
-and check counts, and coverage level. A partial or failed review instead says it is not
-a verdict and keeps the missing work visible. Use `--format manifest` to inspect file
-dispositions, executed and unavailable checks, failures, judge units, and
-`notLookedAt`.
+A clean report names its effective severity threshold, deterministic/model mode,
+reviewed/changed file ratio, check count, and oracle coverage level. A partial or
+failed review instead says it is not a verdict and keeps the missing work visible. Use
+`--format manifest` to inspect file dispositions, executed and unavailable checks,
+failures, judge units, and `notLookedAt`.
 
 ## CI integration
 
@@ -298,6 +298,20 @@ psh delegate > /tmp/powershot-brief.md
 psh review --verify-only --absorb /tmp/powershot-findings.json
 ```
 
+Delegation uses the same `SelectionPlan` and target snapshot as a real review. The
+brief names every changed file as selected, policy-waived, or failed, so unsupported
+or oversized files cannot disappear between task creation and absorption. For an
+agent that consumes structured input, request the versioned task directly:
+
+```bash
+psh delegate --format json > /tmp/powershot-task.json
+```
+
+`powershot.delegate/v1` contains the resolved file dispositions, applicable judges,
+bounded review units, changed-line excerpts, intent, and the exact output contract.
+Creating either form is LLM-free and does not create a session. Deterministic checks
+run when the returned finding array is absorbed by `psh review --verify-only`.
+
 ## Language coverage
 
 | Language | Available oracles |

package/dist/cli/args.js

@@ -6,7 +6,8 @@ psh — code review for machine-written code
   psh review --from main --to feat/x  branch range
   psh review --commit <hash>          a single commit
   psh scan <path>                     audit existing files, no git history needed
-  psh delegate                        emit the judging work for an agent you already pay for
+  psh delegate [--format text|markdown|json]
+                                      emit a selection-accounted task for your existing agent
   psh session list | view <id>        runs that can be resumed, or replayed as a page
   psh session diff <a> <b>            what one review found that the other did not
   psh dismiss <id> [--reason "..."]   record that a finding is correct, and stop showing it

package/dist/cli/review-command.js

@@ -1,8 +1,8 @@
 import { createHash } from 'node:crypto';
-import { readFileSync } from 'node:fs';
+import { readFileSync, writeFileSync } from 'node:fs';
 import { Budget, parseLimits } from '#app/budget.js';
 import { loadConfig, policyChanged } from '#app/config.js';
-import { absorbDelegated, delegateBrief } from '#app/delegate.js';
+import { absorbDelegated, buildDelegateTask, delegateBrief, delegateJson } from '#app/delegate.js';
 import { baseRefOf, checkRange, headSha, repoRoot, shaOf } from '#app/git.js';
 import { JUDGES } from '#app/judges/prompts.js';
 import { RunManifest, coverageProblems, hashOf, writeManifest } from '#app/manifest.js';
@@ -13,6 +13,7 @@ import { progress, stage } from '#app/report/terminal.js';
 import { summarizeRun } from '#app/report/summary.js';
 import { review } from '#app/review.js';
 import { scanPaths } from '#app/scan.js';
+import { SelectionPlan } from '#app/plan.js';
 import { Session } from '#app/session.js';
 import { withTargetTree } from '#app/snapshot.js';
 import { SEVERITIES } from '#app/types.js';
@@ -33,6 +34,10 @@ export async function runReviewCommand(command, values, positionals) {
         process.stderr.write('--format must be one of: ' + REPORT_FORMATS.join(', ') + '\n');
         return 2;
     }
+    if (command === 'delegate' && !['text', 'markdown', 'json'].includes(values.format)) {
+        process.stderr.write('delegate --format must be one of: text, markdown, json\n');
+        return 2;
+    }
     if ((values.from && !values.to) || (values.to && !values.from)) {
         process.stderr.write('--from and --to must be given together.\n');
         return 2;
@@ -142,19 +147,32 @@ export async function runReviewCommand(command, values, positionals) {
     if (command === 'delegate') {
         const { buildGround } = await import('#app/ground.js');
         const { collectChanges, statedIntent } = await import('#app/git.js');
-        const { matchesAny } = await import('#app/config.js');
-        const changes = collectChanges(root, range).filter((change) => !matchesAny(change.path, config.ignore));
-        if (changes.length === 0) {
+        const all = collectChanges(root, range);
+        if (all.length === 0) {
             process.stderr.write('Nothing to review.\n');
             return 0;
         }
-        const ground = await withTargetTree(root, range, (tree) => buildGround(tree, changes));
-        process.stdout.write(delegateBrief(ground, config, {
-            intent: statedIntent(root, range),
-            maxBundleLines: maxBundle,
-            checks: requestedChecks,
-        }));
-        return 0;
+        const task = await withTargetTree(root, range, async (tree) => {
+            const plan = SelectionPlan.build(tree, all, config);
+            const selected = plan.keep(all);
+            const ground = await buildGround(tree, selected, undefined, all);
+            plan.accountForGround(selected, ground);
+            return buildDelegateTask(ground, config, plan.items(), {
+                intent: statedIntent(root, range),
+                maxBundleLines: maxBundle,
+                checks: requestedChecks,
+                target: { from: values.from, to: values.to, commit: values.commit },
+            });
+        });
+        const rendered = values.format === 'json' ? delegateJson(task) : delegateBrief(task);
+        if (values.output !== undefined) {
+            writeFileSync(values.output, rendered);
+            process.stderr.write(dim(' written to ' + values.output) + '\n');
+        }
+        else {
+            process.stdout.write(rendered);
+        }
+        return task.state === 'failed' ? 3 : 0;
     }
     const canceller = new AbortController();
     let interrupted = false;

package/dist/cli/session-command.js

@@ -46,6 +46,7 @@ export function runSessionCommand(positionals) {
             verifyOnly: session.report.verifyOnly,
             minSeverity: session.report.minSeverity,
             filesReviewed: session.report.filesReviewed,
+            filesChanged: session.report.filesChanged,
             deterministicChecks: session.report.deterministicChecks,
             scopeDetails: session.report.scopeDetails,
         }));

package/dist/delegate.js

@@ -2,44 +2,120 @@ import { bundle, bundleName } from './bundle.js';
 import { renderChanges } from './judges/judge.js';
 import { COMMON, JUDGES } from './judges/prompts.js';
 import { enabled } from './config.js';
-export function delegateBrief(g, cfg, opts) {
+import { stripPath } from './text.js';
+export const DELEGATE_SCHEMA = 'powershot.delegate/v1';
+export function buildDelegateTask(g, cfg, files, opts) {
     const units = bundle(g, opts.maxBundleLines ?? 1200);
     const judges = JUDGES.filter((j) => opts.checks ? opts.checks.includes(j.name) : enabled(cfg.judges, j.name));
+    return {
+        schema: DELEGATE_SCHEMA,
+        state: files.some((file) => file.disposition === 'failed') ? 'failed' : 'complete',
+        target: opts.target ?? {},
+        intent: opts.intent,
+        files: files.map(({ path, disposition, reason, bytes, addedLines, language }) => ({
+            path,
+            disposition,
+            reason,
+            bytes,
+            addedLines,
+            language,
+        })),
+        judges: judges.map((judge) => {
+            const usesIntent = judge.needsIntent === true;
+            const applicable = !usesIntent || Boolean(opts.intent);
+            return {
+                name: judge.name,
+                brief: judge.brief,
+                applicable,
+                usesIntent,
+                reason: applicable ? undefined : 'no stated intent available',
+            };
+        }),
+        instructions: {
+            summary: 'Perform only the judgement work in this task. PowerShot runs its deterministic checks when these findings are absorbed.',
+            groundRules: COMMON,
+            output: {
+                type: 'json-array',
+                empty: [],
+                example: [{
+                        file: 'src/a.ts',
+                        line: 12,
+                        severity: 'high',
+                        confidence: 'firm',
+                        check: 'plausible-logic',
+                        title: '…',
+                        why: '…',
+                        fix: '…',
+                    }],
+            },
+        },
+        units: units.map((unit, index) => ({
+            id: index + 1,
+            name: bundleName(unit, g.root),
+            files: unit.files.map((file) => file.path),
+            changes: renderChanges(unit.files),
+        })),
+    };
+}
+const cell = (value) => stripPath(value).replace(/\|/g, '\\|');
+export function delegateBrief(task) {
+    const scope = task.files.length === 0
+        ? ['_No changed files._']
+        : [
+            '| File | Disposition | Language | Added | Reason |',
+            '|---|---|---|---:|---|',
+            ...task.files.map((file) => '| ' + cell(file.path) + ' | ' + file.disposition + ' | ' + file.language + ' | ' + file.addedLines +
+                ' | ' + cell(file.reason ?? '') + ' |'),
+        ];
     const out = [
         '# PowerShot review brief',
         '',
-        'The deterministic checks have already run; what follows is the judgement work.',
+        task.instructions.summary,
         'Act as each judge below over each review unit, then reply with a single JSON array',
         'combining every finding. Add nothing outside the array.',
         '',
+        '## Scope',
+        '',
+        'Task state: **' + task.state + '**.',
+        '',
+        ...scope,
+        '',
         '## Output contract',
         '',
         '```json',
-        '[{"file":"src/a.ts","line":12,"severity":"high","confidence":"firm",',
-        '  "check":"plausible-logic","title":"…","why":"…","fix":"…"}]',
+        JSON.stringify(task.instructions.output.example, null, 2),
         '```',
         '',
-        'Return `[]` when a judge finds nothing. An empty array is a success, not a failure.',
+        'Return `' + JSON.stringify(task.instructions.output.empty) +
+            '` when a judge finds nothing. An empty array is a success, not a failure.',
         '',
         '## Ground rules',
         '',
-        COMMON,
+        task.instructions.groundRules,
         '',
     ];
-    for (const judge of judges) {
+    for (const judge of task.judges) {
         out.push('## Judge: ' + judge.name, '', judge.brief, '');
-        if (judge.needsIntent) {
-            out.push(opts.intent
-                ? 'This change states that it does the following:\n\n> ' + opts.intent.split('\n').join('\n> ')
+        if (judge.usesIntent) {
+            out.push(task.intent
+                ? 'This change states that it does the following:\n\n> ' + task.intent.split('\n').join('\n> ')
                 : '_No stated intent available (no commit in range) — skip this judge._', '');
         }
     }
     out.push('## Review units', '');
-    units.forEach((unit, i) => {
-        out.push('### Unit ' + (i + 1) + ' — ' + bundleName(unit, g.root), '', '```', renderChanges(unit.files), '```', '');
-    });
+    if (task.units.length === 0) {
+        out.push('_No judgement units. Every changed file was excluded or failed preparation; inspect Scope._', '');
+    }
+    else {
+        task.units.forEach((unit) => {
+            out.push('### Unit ' + unit.id + ' — ' + cell(unit.name), '', '```', unit.changes, '```', '');
+        });
+    }
     return out.join('\n');
 }
+export function delegateJson(task) {
+    return JSON.stringify(task, null, 2) + '\n';
+}
 export function absorbDelegated(json) {
     let parsed;
     try {

package/dist/plan.js

@@ -92,6 +92,31 @@ export class SelectionPlan {
     keep(changed) {
         return changed.filter((c) => this.rows.get(c.path)?.disposition === 'selected');
     }
+    /**
+     * Finish the file-level selection after parsers have had one chance to load it.
+     *
+     * Review and delegation both promise to describe the same change. Keeping this
+     * transition on the plan prevents either caller from silently inventing its own
+     * meaning for a deleted, unsupported, or unavailable source file.
+     */
+    accountForGround(changed, ground) {
+        const grounded = new Set([
+            ...ground.files.map((file) => file.changed.path),
+            ...ground.foreign.map((file) => file.path),
+        ]);
+        for (const file of changed) {
+            if (file.deleted) {
+                this.waive(file.path, 'deleted file has no current source to review');
+                continue;
+            }
+            if (grounded.has(file.path))
+                continue;
+            if (packFor(file.path))
+                this.fail(file.path, 'declared language parser unavailable');
+            else
+                this.waive(file.path, 'no parser for this language');
+        }
+    }
     items() {
         return [...this.rows.values()];
     }

package/dist/report/summary.js

@@ -73,6 +73,7 @@ export function summarizeRun(record) {
         filesReviewed: hasFiles
             ? record.files.filter((file) => file.disposition === 'selected').length
             : undefined,
+        filesChanged: hasFiles ? record.files.length : undefined,
         deterministicChecks: hasChecks ? new Set(record.checks.ran).size : undefined,
         scopeDetails: scopeDetails(record),
     };
@@ -88,13 +89,20 @@ export function noFindingsLabel(summary) {
 }
 export function scopeLine(summary) {
     const parts = [];
-    if (summary.filesReviewed !== undefined)
-        parts.push(plural(summary.filesReviewed, 'file') + ' reviewed');
+    if (summary.filesReviewed !== undefined) {
+        parts.push(summary.filesChanged === undefined
+            ? plural(summary.filesReviewed, 'file') + ' reviewed'
+            : summary.filesReviewed + '/' + summary.filesChanged + ' changed ' +
+                (summary.filesChanged === 1 ? 'file' : 'files') + ' reviewed');
+    }
     if (summary.deterministicChecks !== undefined) {
         parts.push(plural(summary.deterministicChecks, 'deterministic check'));
     }
-    if (summary.coverage !== undefined)
-        parts.push(summary.coverage + ' coverage');
+    if (summary.coverage !== undefined) {
+        parts.push(summary.coverage === 'full'
+            ? 'full applicable-oracle coverage'
+            : 'portable oracle coverage');
+    }
     return parts.length > 0 ? parts.join(' · ') : undefined;
 }
 export function modeNote(summary, verifyOnly = 'verify-only') {

package/dist/review.js

@@ -12,7 +12,6 @@ import { apiKey } from './judges/llm.js';
 import { enabled } from './config.js';
 import { SelectionPlan, capabilitiesOf } from './plan.js';
 import { Budget } from './budget.js';
-import { packFor } from './lang/packs.js';
 import { SEVERITIES } from './types.js';
 import { stripControl, stripPath } from './text.js';
 export function atLeast(severity, min) {
@@ -174,21 +173,10 @@ export async function review(opts) {
     // Naming a check explicitly is a request for that oracle, even under the portable
     // default. Strict policy makes the same promise for every configured verifier.
     const requireEnrichedOracles = config.coverage === 'strict' || opts.checks !== undefined;
-    // a file the change touched that no parser produced a tree for was not reviewed,
-    // whatever the summary says about the ones that were
-    const grounded = new Set([...g.files.map((f) => f.changed.path), ...g.foreign.map((f) => f.path)]);
-    for (const c of changed) {
-        if (c.deleted) {
-            plan.waive(c.path, 'deleted file has no current source to review');
-            continue;
-        }
-        if (grounded.has(c.path))
-            continue;
-        if (packFor(c.path))
-            plan.fail(c.path, 'declared language parser unavailable');
-        else
-            plan.waive(c.path, 'no parser for this language');
-    }
+    // A file the change touched that no parser produced a tree for was not reviewed,
+    // whatever the summary says about the ones that were. Delegation uses this exact
+    // transition too, so its task cannot disagree with the review it will feed.
+    plan.accountForGround(changed, g);
     // Capabilities belong to files, not runs. A typed file beside one excluded from
     // tsconfig must not make the latter look checked, and an old Ruby file must not
     // make a new Python file eligible for a before/after oracle.

package/dist/selftest.js

@@ -35,7 +35,7 @@ import { dirname, join, sep } from 'node:path';
 import { runTool } from './judges/tools.js';
 import { codeQuality } from './report/codequality.js';
 import { viewer } from './report/viewer.js';
-import { absorbDelegated, delegateBrief } from './delegate.js';
+import { absorbDelegated, buildDelegateTask, delegateBrief } from './delegate.js';
 import { TARGETS, findTarget } from './agents.js';
 import { PACKS, packFor, parseIsolated } from './lang/packs.js';
 import { isPhantom, pythonManifest, localModules } from './lang/python-deps.js';
@@ -1175,9 +1175,14 @@ check('portable coverage is a verdict, but never masquerades as full semantic co
         filesReviewed: 1, deterministicChecks: 1, scopeDetails: unavailable,
     });
     assert.match(out, /No medium-or-higher deterministic findings\./);
-    assert.match(out, /1 file reviewed · 1 deterministic check · portable coverage/);
+    assert.match(out, /1 file reviewed · 1 deterministic check · portable oracle coverage/);
     assert.match(out, /1 reviewed file lacked type information and a reference graph/);
     assert.doesNotMatch(out, /not a verdict/);
+    const full = terminal([], {
+        subtitle: 'workspace', verified: 0, judged: 0, state: 'complete', notLookedAt: [],
+        coverage: 'full', filesReviewed: 2, filesChanged: 2, deterministicChecks: 3,
+    });
+    assert.match(full, /2\/2 changed files reviewed · 3 deterministic checks · full applicable-oracle coverage/);
     const selected = Array.from({ length: 20 }, (_, index) => ({
         path: 'web/file-' + index + '.ts',
         disposition: 'selected',
@@ -1202,7 +1207,7 @@ check('portable coverage is a verdict, but never masquerades as full semantic co
         },
     }));
     assert.match(md, /✅ \*\*No medium-or-higher deterministic findings\*\*/);
-    assert.match(md, /20 files reviewed · 19 deterministic checks · portable coverage/);
+    assert.match(md, /20\/36 changed files reviewed · 19 deterministic checks · portable oracle coverage/);
     assert.match(md, /Model review was disabled \(`verify-only`\)\./);
     assert.match(md, /<summary>Coverage details<\/summary>/);
     const rendered = md.replace(/\\/g, '');
@@ -1958,6 +1963,16 @@ check('the public action persists judge answers and publishes only a verdict', (
     assert.match(action, /m\.coverage === "full" \|\| m\.coverage === "portable" \? m\.coverage : "unknown"/);
     assert.match(action, /Approve a clean review[\s\S]+steps\.review\.outputs\.coverage == 'full'/);
 });
+check('the public action keeps every pull request write inside the base repository', () => {
+    const action = readFileSync(join(process.cwd(), 'action.yml'), 'utf8');
+    for (const name of ['Post inline comments', 'Comment on the pull request', 'Approve a clean review']) {
+        const start = action.indexOf('    - name: ' + name);
+        const end = action.indexOf('\n    - name: ', start + 1);
+        const step = action.slice(start, end === -1 ? undefined : end);
+        assert.ok(start >= 0, name + ' step is missing');
+        assert.match(step, /github\.event\.pull_request\.head\.repo\.full_name == github\.repository/, name);
+    }
+});
 check('published CI examples preserve one verdict and its exit status', () => {
     const action = readFileSync(join(process.cwd(), 'examples', 'github-actions', 'action.yml'), 'utf8');
     const github = readFileSync(join(process.cwd(), 'examples', 'github-actions', 'cli.yml'), 'utf8');
@@ -1997,10 +2012,11 @@ check('the viewer labels a complete portable session', () => {
     const html = viewer([], {
         id: 'portable', target: 'workspace', started: '2026-01-01T10:00:00Z',
         state: 'complete', notLookedAt: [], coverage: 'portable',
-        verifyOnly: true, minSeverity: 'medium', filesReviewed: 1, deterministicChecks: 2,
+        verifyOnly: true, minSeverity: 'medium', filesReviewed: 1, filesChanged: 3,
+        deterministicChecks: 2,
         scopeDetails: ['1 reviewed file lacked type information'],
     });
-    assert.match(html, /1 file reviewed · 2 deterministic checks · portable coverage/);
+    assert.match(html, /1\/3 changed files reviewed · 2 deterministic checks · portable oracle coverage/);
     assert.match(html, /No medium-or-higher deterministic findings\./);
     assert.match(html, /<summary>Coverage details<\/summary>/);
 });
@@ -2033,9 +2049,11 @@ check('delegate --checks selects only the requested judging brief', () => {
         provider: 'anthropic', model: 'm', verifiers: ['*'], judges: ['*'],
         minSeverity: 'low', ignore: [], coverage: 'portable', promptCache: true,
     };
-    const brief = delegateBrief(ground([{ path: 'a.ts', after: 'export const a = 1\n' }]), cfg, {
-        checks: ['intent'], intent: 'add a',
-    });
+    const task = buildDelegateTask(ground([{ path: 'a.ts', after: 'export const a = 1\n' }]), cfg, [{
+            path: 'a.ts', disposition: 'selected', bytes: 19, addedLines: 1,
+            language: 'typescript', checks: [],
+        }], { checks: ['intent'], intent: 'add a' });
+    const brief = delegateBrief(task);
     assert.match(brief, /## Judge: intent/);
     assert.doesNotMatch(brief, /## Judge: plausible-logic/);
 });
@@ -2190,6 +2208,17 @@ check('a finding is matched past a line that moved under it', () => {
     assert.equal(Session.compare(at(12), at(22)).remaining.length, 1);
     rmSync(dir, { recursive: true, force: true });
 });
+check('a finished session preserves the reviewed and changed file counts', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'psh-scope-session-'));
+    const session = Session.create(dir, 'workspace');
+    session.saveReport([], {
+        state: 'complete', notLookedAt: [], filesReviewed: 2, filesChanged: 5,
+    });
+    const reopened = Session.open(dir, session.id);
+    assert.equal(reopened?.report?.filesReviewed, 2);
+    assert.equal(reopened?.report?.filesChanged, 5);
+    rmSync(dir, { recursive: true, force: true });
+});
 check('partial sessions cannot be compared or rendered as clean', () => {
     const dir = mkdtempSync(join(tmpdir(), 'psh-partial-session-'));
     const partial = Session.create(dir, 'workspace');
@@ -3475,6 +3504,7 @@ check('CLI rejects selections that would otherwise run nothing and report clean'
         assert.equal(status(['scan', 'example.rb', '--verify-only', '--checks', 'plausible-logic', '--format', 'manifest']), 2);
         assert.equal(status(['delegate', '--checks', 'phantom-api']), 2);
         assert.equal(status(['delegate']), 0);
+        assert.equal(status(['delegate', '--format', 'manifest']), 2);
         assert.equal(existsSync(join(dir, '.powershot', 'sessions')), false, 'delegate must not create an unused session');
         assert.equal(status(['scan', 'example.rb', '--format', 'unknown']), 2);
         assert.equal(status(['scan', 'example.rb', '--report', 'unknown=report.txt']), 2);
@@ -3489,6 +3519,58 @@ check('CLI rejects selections that would otherwise run nothing and report clean'
         rmSync(dir, { recursive: true, force: true });
     }
 });
+check('delegate JSON uses the review selection contract and names excluded files', () => {
+    const dir = realpathSync(mkdtempSync(join(tmpdir(), 'psh-delegate-plan-')));
+    const cli = join(process.cwd(), 'dist', 'cli.js');
+    try {
+        execFileSync('git', ['init', '-q', '.'], { cwd: dir });
+        writeFileSync(join(dir, 'source.rs'), 'pub fn value() -> i32 { 1 }\n');
+        writeFileSync(join(dir, 'notes.md'), '# Notes\n');
+        writeFileSync(join(dir, 'large.ts'), 'x'.repeat(512 * 1024 + 1));
+        const raw = execFileSync(process.execPath, [cli, 'delegate', '--format', 'json'], {
+            cwd: dir,
+            env: { ...process.env, CI: 'true' },
+            encoding: 'utf8',
+            maxBuffer: 2 * 1024 * 1024,
+        });
+        const task = JSON.parse(raw);
+        const files = new Map(task.files.map((file) => [file.path, file]));
+        assert.equal(task.schema, 'powershot.delegate/v1');
+        assert.equal(task.state, 'complete');
+        assert.equal(files.get('source.rs')?.disposition, 'selected');
+        assert.equal(files.get('notes.md')?.disposition, 'waived');
+        assert.match(files.get('notes.md')?.reason ?? '', /no parser/);
+        assert.equal(files.get('large.ts')?.disposition, 'waived');
+        assert.match(files.get('large.ts')?.reason ?? '', /over 512KB/);
+        assert.ok(task.judges.some((judge) => judge.name === 'plausible-logic' && judge.applicable));
+        assert.deepEqual([...new Set(task.units.flatMap((unit) => unit.files))], ['source.rs']);
+        assert.match(task.units[0]?.changes ?? '', /pub fn value/);
+        const markdown = execFileSync(process.execPath, [cli, 'delegate'], {
+            cwd: dir,
+            env: { ...process.env, CI: 'true' },
+            encoding: 'utf8',
+            maxBuffer: 2 * 1024 * 1024,
+        });
+        assert.match(markdown, /## Scope/);
+        assert.match(markdown, /source\.rs.*selected/);
+        assert.match(markdown, /notes\.md.*no parser/);
+        assert.match(markdown, /large\.ts.*over 512KB/);
+        assert.ok(markdown.length < 100_000, 'an oversized source leaked into the delegate brief');
+        assert.equal(existsSync(join(dir, '.powershot', 'sessions')), false, 'delegate must stay LLM-free');
+        rmSync(join(dir, 'source.rs'));
+        rmSync(join(dir, 'large.ts'));
+        const waivedOnly = JSON.parse(execFileSync(process.execPath, [cli, 'delegate', '--format', 'json'], { cwd: dir, env: { ...process.env, CI: 'true' }, encoding: 'utf8' }));
+        assert.equal(waivedOnly.state, 'complete');
+        assert.deepEqual(waivedOnly.files, [{
+                path: 'notes.md', disposition: 'waived', bytes: 8, addedLines: 2, language: 'other',
+                reason: 'no parser for this language',
+            }]);
+        assert.deepEqual(waivedOnly.units, []);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
 check('a budget stop is partial and the manifest names what was not reviewed', () => {
     const b = new Budget({ requests: 1 }, 0);
     b.spend({ requests: 1 });

package/dist/session.js

@@ -110,6 +110,7 @@ export class Session {
             verifyOnly: verdict.verifyOnly,
             minSeverity: verdict.minSeverity,
             filesReviewed: verdict.filesReviewed,
+            filesChanged: verdict.filesChanged,
             deterministicChecks: verdict.deterministicChecks,
             scopeDetails: verdict.scopeDetails ? [...verdict.scopeDetails] : undefined,
         };

package/docs/architecture.md

@@ -121,6 +121,14 @@ A branch or commit review reads source from the target revision, not from whatev
 currently present in the working directory. Grounding, verification, bundling, and
 positioning all receive the same tree.
 
+### Delegation shares file selection
+
+`psh delegate` builds the same target snapshot, `SelectionPlan`, and parser ground as
+`psh review`, then stops before deterministic verification, model calls, sessions, or
+manifests. Its Markdown brief and `powershot.delegate/v1` JSON are renderings of one
+task object. Both therefore expose the same selected, waived, and failed files and the
+same bounded judge units; an output adapter cannot silently choose a different scope.
+
 ### Capabilities belong to files
 
 A run can contain a typed TypeScript file beside a Python file or a TypeScript file

package/docs/ci.md

@@ -90,10 +90,15 @@ newest unmarked legacy `## PowerShot` summary from v1.1.2 or older without claim
 ambiguous legacy comment through `PATCH`.
 
 The comment leads with the verdict, effective severity threshold, review mode, and
-aggregate file/check counts. Portable gaps and files outside parser coverage stay
-visible under a collapsed coverage section without filling the timeline with paths.
-The generated `powershot.manifest.json` keeps the per-file accounting for workflows
-that want to persist it as an artifact.
+reviewed/changed file ratio and check count. Portable gaps and files outside parser
+coverage stay visible under a collapsed coverage section without filling the timeline
+with paths. The generated `powershot.manifest.json` keeps the per-file accounting for
+workflows that want to persist it as an artifact.
+
+For a `pull_request` from a fork, GitHub gives the workflow token read-only pull-request
+permissions. PowerShot still runs and writes the complete report to the job summary,
+but skips summary comments, inline comments, and approval because those operations
+require a write-capable token.
 
 PowerShot checks the target head throughout reconciliation and removes its own
 just-created candidate if it observes a changed head. Simultaneous same-head runs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0xcraft/powershot",
-  "version": "1.1.5",
+  "version": "1.2.0",
   "description": "Oracle-first code review for machine-written code, with deterministic verification and CI-ready reports.",
   "license": "Apache-2.0",
   "author": "aglumova <alina.glumova@gmail.com>",