@webpieces/rules-config 0.4.537 → 0.4.539

package/src/review-provenance.js

@@ -0,0 +1,319 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReviewProvenanceService = exports.ReviewProvenance = exports.ProvenanceWriteRequest = exports.OfferedContext = exports.ReviewerTranscript = exports.ReviewerPaths = exports.DEFAULT_RETENTION_DAYS = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const os = tslib_1.__importStar(require("os"));
+const inversify_1 = require("inversify");
+const to_error_1 = require("./to-error");
+// The audit record `wp-finish-upsert-pr` writes beside review.json, and where a consumed one is retired to.
+const PROVENANCE_FILE = 'provenance.json';
+const OLD_PROVENANCE_FILE = 'old-provenance.json';
+/**
+ * Claude Code deletes transcripts after `cleanupPeriodDays`; 30 is its default and what applies when the
+ * setting is absent, which is the common case. Recorded in every provenance file so a reader knows how
+ * long the links it is holding remain resolvable rather than discovering it by following a dead path.
+ */
+exports.DEFAULT_RETENTION_DAYS = 30;
+const WHAT_THIS_IS = 'AUDIT RECORD — written by wp-finish-upsert-pr, never by an AI. It links each reviewer verdict to the ' +
+    'transcript of the subagent that produced it, and records what that reviewer was OFFERED versus what it ' +
+    'demonstrably READ. Open it to audit the review process itself: whether a verdict was written by an ' +
+    'agent that actually opened the diff and its checklist doc. Do not hand-edit it, and do not treat it as ' +
+    'a review — it says nothing about whether the code is good, only about how it was looked at. The linked ' +
+    'transcripts expire (see transcriptsExpireOn); the counters recorded here do not.';
+/** Where ONE reviewer's inputs and output live on disk. Data-only (per CLAUDE.md). */
+class ReviewerPaths {
+    verdictFile; // the review-<id>.json this reviewer was told to write
+    instructionsFile; // its generated <subagent>.instructions.md
+    docPath; // its checklist's guidance doc ('' when the checklist names none)
+    constructor(verdictFile, instructionsFile, docPath) {
+        this.verdictFile = verdictFile;
+        this.instructionsFile = instructionsFile;
+        this.docPath = docPath;
+    }
+}
+exports.ReviewerPaths = ReviewerPaths;
+/**
+ * ONE reviewer's provenance row: which agent ran, where its transcript is, and the evidence counters read
+ * out of that transcript. Data-only, and its FIELD NAMES ARE THE JSON KEYS — the file is written by
+ * serializing these objects directly, so renaming a field renames it in every consumer's audit record.
+ *
+ * The counters are copied here rather than left to be re-derived because the transcript they came from is a
+ * wasting asset (~30 days). After it expires this row still answers "did that reviewer read the diff?".
+ */
+class ReviewerTranscript {
+    id;
+    agentType;
+    agentId;
+    transcript; // absolute path to agent-<id>.jsonl, '' when it could not be resolved
+    transcriptExists;
+    verdictFile;
+    instructionsFile;
+    docPath;
+    readDiff;
+    readDoc;
+    toolCallCount;
+    offRepoSearches;
+    constructor(evidence, paths) {
+        this.id = evidence.agentType; // a checklist's id IS its subagent name (see ChecklistDefinition)
+        this.agentType = evidence.agentType;
+        this.agentId = evidence.agentId;
+        this.transcript = evidence.transcriptPath;
+        this.transcriptExists = evidence.transcriptPath !== '' && fs.existsSync(evidence.transcriptPath);
+        this.verdictFile = paths.verdictFile;
+        this.instructionsFile = paths.instructionsFile;
+        this.docPath = paths.docPath;
+        this.readDiff = evidence.readDiff;
+        this.readDoc = evidence.readDoc;
+        this.toolCallCount = evidence.toolCallCount;
+        this.offRepoSearches = evidence.offRepoSearches;
+    }
+}
+exports.ReviewerTranscript = ReviewerTranscript;
+/** What the reviewers were handed, whether or not any of them opened it. Data-only. */
+class OfferedContext {
+    diffDir;
+    instructionsDir;
+    constructor(diffDir, instructionsDir) {
+        this.diffDir = diffDir;
+        this.instructionsDir = instructionsDir;
+    }
+}
+exports.OfferedContext = OfferedContext;
+/**
+ * What {@link ReviewProvenanceService.write} is asked to record. Data-only; `offered` and `reviewers` are
+ * assigned after construction (the same shape ChecklistCommentRow uses) so this never becomes a 7-param
+ * constructor.
+ */
+class ProvenanceWriteRequest {
+    prDir;
+    branch;
+    headSha;
+    provenanceStatus; // PROVENANCE_OK | PROVENANCE_MISSING | PROVENANCE_SKIPPED
+    offered = new OfferedContext('', '');
+    reviewers = [];
+    // eslint-disable-next-line @typescript-eslint/max-params
+    constructor(prDir, branch, headSha, provenanceStatus) {
+        this.prDir = prDir;
+        this.branch = branch;
+        this.headSha = headSha;
+        this.provenanceStatus = provenanceStatus;
+    }
+}
+exports.ProvenanceWriteRequest = ProvenanceWriteRequest;
+/**
+ * The written record. Field names are the JSON keys, in this order — `_WHAT_THIS_IS` is declared FIRST so
+ * anything that opens the file reads what it is before it reads anything it might act on, exactly as
+ * ReviewJsonService.archiveReviewJson stamps its note first.
+ */
+class ReviewProvenance {
+    // webpieces-disable naming-convention -- the leading underscore marks a note-to-the-reader key, not data
+    _WHAT_THIS_IS = WHAT_THIS_IS;
+    sessionId;
+    mainTranscript;
+    branch;
+    headSha;
+    stampedAt;
+    transcriptRetentionDays;
+    transcriptsExpireOn;
+    provenanceStatus;
+    offered;
+    reviewers;
+    constructor(request) {
+        this.sessionId = '';
+        this.mainTranscript = '';
+        this.branch = request.branch;
+        this.headSha = request.headSha;
+        this.stampedAt = '';
+        this.transcriptRetentionDays = exports.DEFAULT_RETENTION_DAYS;
+        this.transcriptsExpireOn = '';
+        this.provenanceStatus = request.provenanceStatus;
+        this.offered = request.offered;
+        this.reviewers = request.reviewers;
+    }
+}
+exports.ReviewProvenance = ReviewProvenance;
+/**
+ * Records WHICH transcript produced which verdict, so the review process itself can be audited later.
+ *
+ * Why a service and not a field the AI writes: a reviewer subagent CANNOT know its own transcript path. The
+ * environment exposes `CLAUDE_CODE_SESSION_ID` — the PARENT session — and no agent id, so a self-reported
+ * link would be invented. Every path here is derived from the harness's own artifacts:
+ *   ~/.claude/projects/&#42;/<sessionId>.jsonl                            → the main agent's transcript
+ *   ~/.claude/projects/&#42;/<sessionId>/subagents/agent-<id>.jsonl       → one reviewer's transcript
+ * The subagent half is already resolved by {@link SubagentProvenanceService}; this carries it to disk and
+ * adds the session-level facts (which session, how long the links live).
+ *
+ * Deliberately a SEPARATE file from review.json / review-<id>.json: those are AI-authored and stay
+ * byte-untouched, so nothing here can be confused for something a reviewer claimed about itself.
+ *
+ * Best-effort throughout — an unreadable ~/.claude degrades the record to empty links, never fails a PR.
+ * Same reasoning as SubagentProvenanceService: this reads undocumented Claude Code internals, and a format
+ * change must not wedge a consumer's PR.
+ *
+ * `@injectable(bindingScopeValues.Singleton)` so it is drawn in the DI design and injected by type.
+ */
+let ReviewProvenanceService = class ReviewProvenanceService {
+    // Where the audit record for a branch lives, beside review.json.
+    provenancePath(prDir) {
+        return path.join(prDir, PROVENANCE_FILE);
+    }
+    // Where a consumed record is retired to — the mirror of ReviewJsonService.oldReviewJsonPath, so an
+    // archived old-review.json keeps the transcript links belonging to the round that produced it.
+    oldProvenancePath(prDir) {
+        return path.join(prDir, OLD_PROVENANCE_FILE);
+    }
+    // The current Claude Code session id, or '' outside a Claude Code session (plain terminal / CI).
+    sessionId() {
+        return (process.env['CLAUDE_CODE_SESSION_ID'] ?? '').trim();
+    }
+    /**
+     * The main agent's own transcript: `~/.claude/projects/<cwd-slug>/<sessionId>.jsonl`. Located by
+     * scanning every project dir for the file named after the session, so the cwd-slug — which is a
+     * mangling of the working directory we would otherwise have to reproduce exactly — never has to be
+     * derived. '' when there is no session or the file is not there.
+     */
+    mainTranscript() {
+        const session = this.sessionId();
+        if (session === '')
+            return '';
+        const projects = path.join(os.homedir(), '.claude', 'projects');
+        for (const proj of this.readDir(projects)) {
+            const candidate = path.join(projects, proj, `${session}.jsonl`);
+            if (fs.existsSync(candidate))
+                return candidate;
+        }
+        return '';
+    }
+    /**
+     * How many days Claude Code keeps transcripts: `cleanupPeriodDays` from ~/.claude/settings.json (then
+     * settings.local.json), else {@link DEFAULT_RETENTION_DAYS}. The setting is usually absent, which is
+     * why the default is documented rather than left implicit.
+     */
+    retentionDays() {
+        const dir = path.join(os.homedir(), '.claude');
+        for (const file of ['settings.json', 'settings.local.json']) {
+            const settings = this.readJson(path.join(dir, file));
+            const days = settings?.['cleanupPeriodDays'];
+            if (typeof days === 'number' && Number.isFinite(days) && days > 0)
+                return days;
+        }
+        return exports.DEFAULT_RETENTION_DAYS;
+    }
+    /**
+     * The date the FIRST of these transcripts becomes unreadable: the oldest one's mtime + retentionDays,
+     * as an ISO date. The oldest rather than the newest because that is when the audit trail starts losing
+     * links, and a reader planning to follow them needs the pessimistic answer. '' when none exist.
+     */
+    expiresOn(transcripts, retentionDays) {
+        let oldest = 0;
+        for (const file of transcripts) {
+            const mtime = this.mtimeOf(file);
+            if (mtime !== 0 && (oldest === 0 || mtime < oldest))
+                oldest = mtime;
+        }
+        if (oldest === 0)
+            return '';
+        const expiry = new Date(oldest + retentionDays * 24 * 60 * 60 * 1000);
+        return expiry.toISOString().slice(0, 10);
+    }
+    /**
+     * Write the record to `<prDir>/provenance.json` and return its path ('' if it could not be written).
+     *
+     * Written on EVERY finish, including one that refuses for a missing reviewer: a refused round is
+     * precisely the one worth auditing, and a record that only ever appears on success cannot answer "what
+     * did the reviewers do the time this was rejected?".
+     */
+    write(request) {
+        const provenance = this.build(request);
+        const target = this.provenancePath(request.prDir);
+        // webpieces-disable no-unmanaged-exceptions -- chokepoint: the audit record is never worth failing a PR over
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            fs.mkdirSync(request.prDir, { recursive: true });
+            fs.writeFileSync(target, JSON.stringify(provenance, null, 2) + '\n');
+            return target;
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+            return '';
+        }
+    }
+    // Retire the record for the round that just shipped: copy it to old-provenance.json beside the
+    // old-review.json it belongs to. A COPY, not a move — unlike review.json this file is not an input to
+    // anything, so leaving it in place cannot mislead a later reviewer, and the next finish overwrites it.
+    archive(prDir) {
+        const source = this.provenancePath(prDir);
+        if (!fs.existsSync(source))
+            return '';
+        const target = this.oldProvenancePath(prDir);
+        // webpieces-disable no-unmanaged-exceptions -- chokepoint: a failed archive must not fail the command
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            fs.copyFileSync(source, target);
+            return target;
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+            return '';
+        }
+    }
+    // Fill in the session-level facts the caller cannot know: which session, which transcripts, how long.
+    build(request) {
+        const provenance = new ReviewProvenance(request);
+        provenance.sessionId = this.sessionId();
+        provenance.mainTranscript = this.mainTranscript();
+        provenance.stampedAt = new Date().toISOString();
+        provenance.transcriptRetentionDays = this.retentionDays();
+        const linked = [provenance.mainTranscript, ...request.reviewers.map((r) => r.transcript)].filter((p) => p !== '');
+        provenance.transcriptsExpireOn = this.expiresOn(linked, provenance.transcriptRetentionDays);
+        return provenance;
+    }
+    // Epoch millis of a file's mtime, or 0 when it cannot be read.
+    mtimeOf(filePath) {
+        // webpieces-disable no-unmanaged-exceptions -- chokepoint: an unstattable transcript contributes no expiry
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            return fs.statSync(filePath).mtime.getTime();
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+            return 0;
+        }
+    }
+    readDir(dir) {
+        // webpieces-disable no-unmanaged-exceptions -- chokepoint: an unreadable dir yields [] (best-effort)
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            return fs.readdirSync(dir);
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+            return [];
+        }
+    }
+    // webpieces-disable no-any-unknown -- opaque parsed JSON object, keys read by the caller
+    readJson(filePath) {
+        // webpieces-disable no-unmanaged-exceptions -- chokepoint: malformed settings → null (fall through to the default)
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            // webpieces-disable no-any-unknown -- parsed JSON is opaque until narrowed by the caller
+            return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+            return null;
+        }
+    }
+};
+exports.ReviewProvenanceService = ReviewProvenanceService;
+exports.ReviewProvenanceService = ReviewProvenanceService = tslib_1.__decorate([
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton)
+], ReviewProvenanceService);
+//# sourceMappingURL=review-provenance.js.map

package/src/review-provenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-provenance.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/review-provenance.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'fs';\nimport * as path from 'path';\nimport * as os from 'os';\nimport { injectable, bindingScopeValues } from 'inversify';\nimport { toError } from './to-error';\nimport { ReviewerEvidence } from './subagent-provenance';\n\n// The audit record `wp-finish-upsert-pr` writes beside review.json, and where a consumed one is retired to.\nconst PROVENANCE_FILE = 'provenance.json';\nconst OLD_PROVENANCE_FILE = 'old-provenance.json';\n\n/**\n * Claude Code deletes transcripts after `cleanupPeriodDays`; 30 is its default and what applies when the\n * setting is absent, which is the common case. Recorded in every provenance file so a reader knows how\n * long the links it is holding remain resolvable rather than discovering it by following a dead path.\n */\nexport const DEFAULT_RETENTION_DAYS = 30;\n\nconst WHAT_THIS_IS =\n    'AUDIT RECORD — written by wp-finish-upsert-pr, never by an AI. It links each reviewer verdict to the ' +\n    'transcript of the subagent that produced it, and records what that reviewer was OFFERED versus what it ' +\n    'demonstrably READ. Open it to audit the review process itself: whether a verdict was written by an ' +\n    'agent that actually opened the diff and its checklist doc. Do not hand-edit it, and do not treat it as ' +\n    'a review — it says nothing about whether the code is good, only about how it was looked at. The linked ' +\n    'transcripts expire (see transcriptsExpireOn); the counters recorded here do not.';\n\n/** Where ONE reviewer's inputs and output live on disk. Data-only (per CLAUDE.md). */\nexport class ReviewerPaths {\n    verdictFile: string;       // the review-<id>.json this reviewer was told to write\n    instructionsFile: string;  // its generated <subagent>.instructions.md\n    docPath: string;           // its checklist's guidance doc ('' when the checklist names none)\n\n    constructor(verdictFile: string, instructionsFile: string, docPath: string) {\n        this.verdictFile = verdictFile;\n        this.instructionsFile = instructionsFile;\n        this.docPath = docPath;\n    }\n}\n\n/**\n * ONE reviewer's provenance row: which agent ran, where its transcript is, and the evidence counters read\n * out of that transcript. Data-only, and its FIELD NAMES ARE THE JSON KEYS — the file is written by\n * serializing these objects directly, so renaming a field renames it in every consumer's audit record.\n *\n * The counters are copied here rather than left to be re-derived because the transcript they came from is a\n * wasting asset (~30 days). After it expires this row still answers \"did that reviewer read the diff?\".\n */\nexport class ReviewerTranscript {\n    id: string;\n    agentType: string;\n    agentId: string;\n    transcript: string;       // absolute path to agent-<id>.jsonl, '' when it could not be resolved\n    transcriptExists: boolean;\n    verdictFile: string;\n    instructionsFile: string;\n    docPath: string;\n    readDiff: boolean;\n    readDoc: boolean;\n    toolCallCount: number;\n    offRepoSearches: number;\n\n    constructor(evidence: ReviewerEvidence, paths: ReviewerPaths) {\n        this.id = evidence.agentType; // a checklist's id IS its subagent name (see ChecklistDefinition)\n        this.agentType = evidence.agentType;\n        this.agentId = evidence.agentId;\n        this.transcript = evidence.transcriptPath;\n        this.transcriptExists = evidence.transcriptPath !== '' && fs.existsSync(evidence.transcriptPath);\n        this.verdictFile = paths.verdictFile;\n        this.instructionsFile = paths.instructionsFile;\n        this.docPath = paths.docPath;\n        this.readDiff = evidence.readDiff;\n        this.readDoc = evidence.readDoc;\n        this.toolCallCount = evidence.toolCallCount;\n        this.offRepoSearches = evidence.offRepoSearches;\n    }\n}\n\n/** What the reviewers were handed, whether or not any of them opened it. Data-only. */\nexport class OfferedContext {\n    diffDir: string;\n    instructionsDir: string;\n\n    constructor(diffDir: string, instructionsDir: string) {\n        this.diffDir = diffDir;\n        this.instructionsDir = instructionsDir;\n    }\n}\n\n/**\n * What {@link ReviewProvenanceService.write} is asked to record. Data-only; `offered` and `reviewers` are\n * assigned after construction (the same shape ChecklistCommentRow uses) so this never becomes a 7-param\n * constructor.\n */\nexport class ProvenanceWriteRequest {\n    prDir: string;\n    branch: string;\n    headSha: string;\n    provenanceStatus: string; // PROVENANCE_OK | PROVENANCE_MISSING | PROVENANCE_SKIPPED\n    offered: OfferedContext = new OfferedContext('', '');\n    reviewers: ReviewerTranscript[] = [];\n\n    // eslint-disable-next-line @typescript-eslint/max-params\n    constructor(prDir: string, branch: string, headSha: string, provenanceStatus: string) {\n        this.prDir = prDir;\n        this.branch = branch;\n        this.headSha = headSha;\n        this.provenanceStatus = provenanceStatus;\n    }\n}\n\n/**\n * The written record. Field names are the JSON keys, in this order — `_WHAT_THIS_IS` is declared FIRST so\n * anything that opens the file reads what it is before it reads anything it might act on, exactly as\n * ReviewJsonService.archiveReviewJson stamps its note first.\n */\nexport class ReviewProvenance {\n    // webpieces-disable naming-convention -- the leading underscore marks a note-to-the-reader key, not data\n    _WHAT_THIS_IS = WHAT_THIS_IS;\n    sessionId: string;\n    mainTranscript: string;\n    branch: string;\n    headSha: string;\n    stampedAt: string;\n    transcriptRetentionDays: number;\n    transcriptsExpireOn: string;\n    provenanceStatus: string;\n    offered: OfferedContext;\n    reviewers: ReviewerTranscript[];\n\n    constructor(request: ProvenanceWriteRequest) {\n        this.sessionId = '';\n        this.mainTranscript = '';\n        this.branch = request.branch;\n        this.headSha = request.headSha;\n        this.stampedAt = '';\n        this.transcriptRetentionDays = DEFAULT_RETENTION_DAYS;\n        this.transcriptsExpireOn = '';\n        this.provenanceStatus = request.provenanceStatus;\n        this.offered = request.offered;\n        this.reviewers = request.reviewers;\n    }\n}\n\n/**\n * Records WHICH transcript produced which verdict, so the review process itself can be audited later.\n *\n * Why a service and not a field the AI writes: a reviewer subagent CANNOT know its own transcript path. The\n * environment exposes `CLAUDE_CODE_SESSION_ID` — the PARENT session — and no agent id, so a self-reported\n * link would be invented. Every path here is derived from the harness's own artifacts:\n *   ~/.claude/projects/&#42;/<sessionId>.jsonl                            → the main agent's transcript\n *   ~/.claude/projects/&#42;/<sessionId>/subagents/agent-<id>.jsonl       → one reviewer's transcript\n * The subagent half is already resolved by {@link SubagentProvenanceService}; this carries it to disk and\n * adds the session-level facts (which session, how long the links live).\n *\n * Deliberately a SEPARATE file from review.json / review-<id>.json: those are AI-authored and stay\n * byte-untouched, so nothing here can be confused for something a reviewer claimed about itself.\n *\n * Best-effort throughout — an unreadable ~/.claude degrades the record to empty links, never fails a PR.\n * Same reasoning as SubagentProvenanceService: this reads undocumented Claude Code internals, and a format\n * change must not wedge a consumer's PR.\n *\n * `@injectable(bindingScopeValues.Singleton)` so it is drawn in the DI design and injected by type.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class ReviewProvenanceService {\n    // Where the audit record for a branch lives, beside review.json.\n    provenancePath(prDir: string): string {\n        return path.join(prDir, PROVENANCE_FILE);\n    }\n\n    // Where a consumed record is retired to — the mirror of ReviewJsonService.oldReviewJsonPath, so an\n    // archived old-review.json keeps the transcript links belonging to the round that produced it.\n    oldProvenancePath(prDir: string): string {\n        return path.join(prDir, OLD_PROVENANCE_FILE);\n    }\n\n    // The current Claude Code session id, or '' outside a Claude Code session (plain terminal / CI).\n    sessionId(): string {\n        return (process.env['CLAUDE_CODE_SESSION_ID'] ?? '').trim();\n    }\n\n    /**\n     * The main agent's own transcript: `~/.claude/projects/<cwd-slug>/<sessionId>.jsonl`. Located by\n     * scanning every project dir for the file named after the session, so the cwd-slug — which is a\n     * mangling of the working directory we would otherwise have to reproduce exactly — never has to be\n     * derived. '' when there is no session or the file is not there.\n     */\n    mainTranscript(): string {\n        const session = this.sessionId();\n        if (session === '') return '';\n        const projects = path.join(os.homedir(), '.claude', 'projects');\n        for (const proj of this.readDir(projects)) {\n            const candidate = path.join(projects, proj, `${session}.jsonl`);\n            if (fs.existsSync(candidate)) return candidate;\n        }\n        return '';\n    }\n\n    /**\n     * How many days Claude Code keeps transcripts: `cleanupPeriodDays` from ~/.claude/settings.json (then\n     * settings.local.json), else {@link DEFAULT_RETENTION_DAYS}. The setting is usually absent, which is\n     * why the default is documented rather than left implicit.\n     */\n    retentionDays(): number {\n        const dir = path.join(os.homedir(), '.claude');\n        for (const file of ['settings.json', 'settings.local.json']) {\n            const settings = this.readJson(path.join(dir, file));\n            const days = settings?.['cleanupPeriodDays'];\n            if (typeof days === 'number' && Number.isFinite(days) && days > 0) return days;\n        }\n        return DEFAULT_RETENTION_DAYS;\n    }\n\n    /**\n     * The date the FIRST of these transcripts becomes unreadable: the oldest one's mtime + retentionDays,\n     * as an ISO date. The oldest rather than the newest because that is when the audit trail starts losing\n     * links, and a reader planning to follow them needs the pessimistic answer. '' when none exist.\n     */\n    expiresOn(transcripts: readonly string[], retentionDays: number): string {\n        let oldest = 0;\n        for (const file of transcripts) {\n            const mtime = this.mtimeOf(file);\n            if (mtime !== 0 && (oldest === 0 || mtime < oldest)) oldest = mtime;\n        }\n        if (oldest === 0) return '';\n        const expiry = new Date(oldest + retentionDays * 24 * 60 * 60 * 1000);\n        return expiry.toISOString().slice(0, 10);\n    }\n\n    /**\n     * Write the record to `<prDir>/provenance.json` and return its path ('' if it could not be written).\n     *\n     * Written on EVERY finish, including one that refuses for a missing reviewer: a refused round is\n     * precisely the one worth auditing, and a record that only ever appears on success cannot answer \"what\n     * did the reviewers do the time this was rejected?\".\n     */\n    write(request: ProvenanceWriteRequest): string {\n        const provenance = this.build(request);\n        const target = this.provenancePath(request.prDir);\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: the audit record is never worth failing a PR over\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            fs.mkdirSync(request.prDir, { recursive: true });\n            fs.writeFileSync(target, JSON.stringify(provenance, null, 2) + '\\n');\n            return target;\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return '';\n        }\n    }\n\n    // Retire the record for the round that just shipped: copy it to old-provenance.json beside the\n    // old-review.json it belongs to. A COPY, not a move — unlike review.json this file is not an input to\n    // anything, so leaving it in place cannot mislead a later reviewer, and the next finish overwrites it.\n    archive(prDir: string): string {\n        const source = this.provenancePath(prDir);\n        if (!fs.existsSync(source)) return '';\n        const target = this.oldProvenancePath(prDir);\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: a failed archive must not fail the command\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            fs.copyFileSync(source, target);\n            return target;\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return '';\n        }\n    }\n\n    // Fill in the session-level facts the caller cannot know: which session, which transcripts, how long.\n    private build(request: ProvenanceWriteRequest): ReviewProvenance {\n        const provenance = new ReviewProvenance(request);\n        provenance.sessionId = this.sessionId();\n        provenance.mainTranscript = this.mainTranscript();\n        provenance.stampedAt = new Date().toISOString();\n        provenance.transcriptRetentionDays = this.retentionDays();\n        const linked = [provenance.mainTranscript, ...request.reviewers.map(\n            (r: ReviewerTranscript): string => r.transcript)].filter((p: string): boolean => p !== '');\n        provenance.transcriptsExpireOn = this.expiresOn(linked, provenance.transcriptRetentionDays);\n        return provenance;\n    }\n\n    // Epoch millis of a file's mtime, or 0 when it cannot be read.\n    private mtimeOf(filePath: string): number {\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: an unstattable transcript contributes no expiry\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            return fs.statSync(filePath).mtime.getTime();\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return 0;\n        }\n    }\n\n    private readDir(dir: string): string[] {\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: an unreadable dir yields [] (best-effort)\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            return fs.readdirSync(dir);\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return [];\n        }\n    }\n\n    // webpieces-disable no-any-unknown -- opaque parsed JSON object, keys read by the caller\n    private readJson(filePath: string): Record<string, unknown> | null {\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: malformed settings → null (fall through to the default)\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            // webpieces-disable no-any-unknown -- parsed JSON is opaque until narrowed by the caller\n            return JSON.parse(fs.readFileSync(filePath, 'utf8')) as Record<string, unknown>;\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return null;\n        }\n    }\n}\n"]}

package/src/reviewer-instructions.d.ts

@@ -6,11 +6,22 @@ export declare class ContextEntry {
     note: string;
     constructor(label: string, entryPath: string, note?: string);
 }
-/** One reviewer's matched file and the extracted diff for it. Data-only. */
+/**
+ * One reviewer's matched file, the extracted diff for it, AND the absolute path of the file itself.
+ *
+ * `sourcePath` exists because of a measured 0/4: four reviewers on one PR read the diff and not one opened a
+ * single full source file. The instructions handed them an absolute path per diff and only a parent DIRECTORY
+ * per source, so reading the diff was a paste and reading the source was "join this dir to that filename
+ * yourself". Identical affordance, or the cheaper one wins every time. Data-only.
+ */
 export declare class BriefedFile {
     file: string;
     diffPath: string;
-    constructor(file: string, diffPath: string);
+    sourcePath: string;
+    status: string;
+    diffBytes: number;
+    truncated: boolean;
+    constructor(file: string, diffPath: string, sourcePath?: string, status?: string, diffBytes?: number, truncated?: boolean);
 }
 /**
  * Everything ONE reviewer needs, with every path already resolved to an ABSOLUTE one.
@@ -34,8 +45,24 @@ export declare class ReviewerBriefing {
     checklistId: string;
     fileDiffCommand: string;
     dirty: boolean;
+    changedFileCount: number;
+    truncatedCount: number;
+    excludedCount: number;
+    allDiffLines: number;
+    allDiffBytes: number;
+    hashForkPoint: string;
+    hashFeatureHead: string;
+    hashMainHead: string;
+    ownAgentFileInDiff: string;
     constructor(subagent: string, checklistId: string, repoRoot: string);
 }
+/**
+ * The Read tool truncates at roughly this many lines, silently. Any path this file prints alongside a bigger
+ * line count has to say so, or a reviewer reviews a fraction of a change and reports on all of it.
+ */
+export declare const READ_TRUNCATION_LINES = 2000;
+/** Comfortably under {@link READ_TRUNCATION_LINES} — the size at which ALL.diff really is one clean Read. */
+export declare const ALL_DIFF_ONE_READ_LINES = 1500;
 /**
  * Renders the per-reviewer instructions file that `wp-review-upsert-pr` writes to
  * `.webpieces/pr-review/<feature>/instructions/<subagent>.instructions.md`.
@@ -63,13 +90,61 @@ export declare class ReviewerInstructionsService {
     pathFor(repoRoot: string, featureName: string, subagent: string): string;
     render(briefing: ReviewerBriefing): string;
     private identity;
+    /**
+     * Every PR that edits the review gate hits this: on the measured run, 5 of 8 changed files were the
+     * reviewer agent files themselves, two reviewers reviewed their OWN definition, and neither flagged it —
+     * neither had any guidance to. Detected by the tooling rather than left to the reviewer to notice.
+     */
+    private selfEditWarning;
     private checklistSection;
     /**
-     * The change itself. The materialized diff leads because it is ONE Read instead of a shell-out per file,
-     * and because a hand-assembled range can come back empty (it did — see DiffBasis).
+     * The change itself. The MANIFEST leads, and the per-file table with it; `ALL.diff` is demoted to one
+     * option among several, recommended only where it is actually the right read.
+     *
+     * That ordering is the fix for a measured 4/4 failure. `ALL.diff` used to be bolded, first, and framed as
+     * "everything", with the manifest one unbolded line below it called a "path map" — which reads like a
+     * lookup aid, not something to open. All four reviewers on that PR read `ALL.diff`, none opened the
+     * manifest, and none could therefore have established that the combined view was complete. Reviewers did
+     * exactly what the emphasis told them to; so the emphasis moved.
      */
     private diffSection;
+    /**
+     * The manifest, named as the authority AND with its own headline facts inlined. Inlining them is the
+     * point: a reviewer that never opens the manifest still learns whether anything was truncated or
+     * excluded, which is the one thing it could not otherwise have known it was missing.
+     */
+    private manifestLines;
+    /**
+     * What the diff is taken AGAINST. Two bare shas in a `git diff` command said nothing about this, so a
+     * reviewer could not tell a fork-point diff from a diff against main's current tip — and therefore could
+     * not tell that anything merged to main since the fork is simply absent from what it is judging.
+     * Rendering C beside A makes "main has moved" self-evident exactly when it has.
+     */
+    private basisLines;
+    /**
+     * Source and diff get IDENTICAL affordance — an absolute path each, in adjacent columns. The previous
+     * table gave an absolute path for the diff and nothing for the source, and the source went unread 4/4.
+     */
     private myFilesTable;
+    /**
+     * One row. A truncated or excluded diff is flagged HERE, in the row, not left as a field inside a file the
+     * reviewer has to think to open — and an oversized diff states the line count that makes a single Read
+     * come back silently incomplete.
+     */
+    private fileRow;
+    /**
+     * `ALL.diff`, recommended ONLY where it is the right read. It is kept — for a patternless reviewer on a
+     * small diff it is genuinely one Read instead of N, which is why all four used it — but the blanket
+     * "everything on this branch" line was wrong in two different ways at once: it invited a pattern-scoped
+     * reviewer to spend its budget on files it was explicitly not asked about, and it pointed a reviewer on a
+     * large PR at a file that cannot survive one Read.
+     */
+    private allDiffLines;
+    /**
+     * The rule that used to say "when you need to", and lost 4/4 to the more emphatic budget section 40 lines
+     * later. "When you need to" delegates the judgment to a reviewer that, by construction, does not yet know
+     * what it is missing. It has no opt-out now.
+     */
     private sourceSection;
     /**
      * The section that deletes the `node_modules` greps. Entries come from config, because the tooling
@@ -82,5 +157,13 @@ export declare class ReviewerInstructionsService {
      * reviewer's own checklist id so there is nothing to substitute and nothing to get wrong.
      */
     private verdictSection;
+    /**
+     * The anti-hunting rule, with the changed files carved out explicitly.
+     *
+     * It used to read as "stay inside what you were given" and, being the LAST thing in the file, it beat
+     * the source-reading instruction 4 times out of 4. It never distinguished HUNTING — greps into
+     * `node_modules`, re-deriving the dependency graph — from OPENING A FILE IT WAS EXPLICITLY HANDED. The
+     * distinction is now stated, because where two instructions conflict the later and more emphatic one wins.
+     */
     private budgetSection;
 }