docs: add docs-watch protocol guardrails

Author: hesreallyhim

docs/MAINTAINERS.md

@@ -101,11 +101,15 @@ The docs-watch process is local-only and intended for maintainers.
 - Monitored metadata lives in `docs/github-documentation/watch-list.json`.
 - Local private state defaults to `.tmp/docs-watch/state` and stores snapshots
   used for diffing.
+- For recurring runs, prefer a stable private path outside the worktree via
+  `DOC_WATCH_STATE_DIR` so snapshots survive `.tmp/` cleanup and worktree churn.
 
 ### Local commands
 
 - Seed or refresh baseline snapshots:
   - `npm run sync:github-docs-state`
+- Bootstrap-aware review entrypoint (recommended):
+  - `npm run docs-watch:review`
 - Run check + diff + report (standard weekly run):
   - `npm run docs-watch:local`
 - Individual steps:
@@ -122,13 +126,25 @@ The docs-watch process is local-only and intended for maintainers.
 
 ### Maintainer review loop
 
-1. Run `npm run docs-watch:local` (or let weekly Codex automation run it).
+1. Prefer `npm run docs-watch:review` (or let weekly Codex automation use the
+   same protocol).
 2. Review `.tmp/docs-watch/docs-watch-report.md` for correctness.
-3. If docs changed, validate impact classification and decide if project updates
-   are required.
-4. If required, open/update a draft fix PR with project and metadata changes
+3. If the report status is `bootstrap-required`, do not open or update a PR from
+   that run. Seed private state with `npm run sync:github-docs-state`, then rerun
+   the exact review.
+4. Only if the synced exact review still reports `changed: true`, validate impact
+   classification and decide if project updates are required.
+5. If required, open/update a draft fix PR with project and metadata changes
    only.
 
+### Recommended protocol
+
+1. Set a stable private state directory, for example:
+   - `export DOC_WATCH_STATE_DIR="$HOME/.local/state/github-api-usage-monitor/docs-watch"`
+2. Run `npm run docs-watch:review`.
+3. Treat the first seeded run as bootstrap, not as a source of patch review.
+4. Only create PRs from an exact synced run with `changed: true`.
+
 ## Notes
 
 - `CHANGELOG.md` is generated by Release Please; avoid manual edits.

docs/github-documentation/README.md

@@ -16,13 +16,27 @@ Readable diffs require a private local state directory that stores snapshot bodi
 Example local state location:
 
 - `.tmp/docs-watch/state` (default for local scripts)
+- For recurring local or automated runs, prefer a stable external path via
+  `DOC_WATCH_STATE_DIR`, for example
+  `$HOME/.local/state/github-api-usage-monitor/docs-watch`
 
 ## Local workflow
 
-1. (Optional, first run) `npm run sync:github-docs-state`
-2. `npm run check:github-docs`
-3. `npm run diff:github-docs`
-4. `npm run report:github-docs`
-5. Ask Codex to review `.tmp/docs-watch/docs-watch-report.md` and classify project impact.
+1. Recommended entrypoint: `npm run docs-watch:review`
+2. If you are running manually and want explicit control:
+   - first run or missing snapshots: `npm run sync:github-docs-state`
+   - exact review run: `npm run docs-watch:local`
+3. Ask Codex to review `.tmp/docs-watch/docs-watch-report.md` and classify project impact.
+
+## Protocol notes
+
+- If a run reports `status: bootstrap-required`, do not open or update a PR from
+  that run alone.
+- `bootstrap-required` means the manifest differs from current upstream docs, but
+  there is no private baseline snapshot for at least one changed page, so the run
+  cannot produce a reliable readable diff.
+- After seeding private state with `npm run sync:github-docs-state`, rerun the
+  exact review. Only act on a PR if that synced exact review still reports
+  `changed: true`.
 
 Outputs are written under `.tmp/docs-watch/` by default.

package.json

@@ -27,6 +27,7 @@
     "diff:github-docs": "node scripts/render-github-doc-diff.mjs --check .tmp/docs-watch/docs-check.json --output .tmp/docs-watch/docs-diff.md --patch-output .tmp/docs-watch/docs-diff.patch --write-summary",
     "report:github-docs": "node scripts/write-docs-watch-report.mjs --check .tmp/docs-watch/docs-check.json --diff .tmp/docs-watch/docs-diff.patch --diff-markdown .tmp/docs-watch/docs-diff.md --output .tmp/docs-watch/docs-watch-report.md --write-summary",
     "docs-watch:local": "npm run check:github-docs && npm run diff:github-docs && npm run report:github-docs",
+    "docs-watch:review": "node scripts/run-docs-watch-review.mjs",
     "sync:github-docs-state": "node scripts/check-github-docs.mjs --state-dir \"${DOC_WATCH_STATE_DIR:-.tmp/docs-watch/state}\" --write-state --update-manifest --output .tmp/docs-watch/docs-check-sync.json --write-summary",
     "clean": "rm -rf dist",
     "prepare": "husky",

scripts/run-docs-watch-review.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import { spawnSync } from 'child_process';
+
+function resolveStateDir() {
+  return process.env.DOC_WATCH_STATE_DIR || '.tmp/docs-watch/state';
+}
+
+function hasSnapshotFiles(stateDir) {
+  const snapshotsDir = path.join(stateDir, 'snapshots');
+  if (!fs.existsSync(snapshotsDir)) {
+    return false;
+  }
+
+  const entries = fs.readdirSync(snapshotsDir, { withFileTypes: true });
+  return entries.some((entry) => entry.isFile());
+}
+
+function npmCommand() {
+  return process.platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+
+function runNpmScript(scriptName) {
+  const result = spawnSync(npmCommand(), ['run', scriptName], {
+    stdio: 'inherit',
+    env: process.env,
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}
+
+async function main() {
+  const stateDir = resolveStateDir();
+
+  console.log(`# Docs watch review entrypoint`);
+  console.log(`- state_dir: ${stateDir}`);
+
+  if (!hasSnapshotFiles(stateDir)) {
+    console.log(
+      '- no private snapshots found; bootstrapping current upstream docs into private state first',
+    );
+    runNpmScript('sync:github-docs-state');
+  } else {
+    console.log('- existing private snapshots found; running exact local review');
+  }
+
+  runNpmScript('docs-watch:local');
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

scripts/write-docs-watch-report.mjs

@@ -69,6 +69,23 @@ function parsePatchStats(patchText) {
 }
 
 function defaultAssessment(payload) {
+  const changedWithoutBaseline = payload.results.some(
+    (item) => item.changed && item.baseline_source === 'none',
+  );
+
+  if (changedWithoutBaseline) {
+    return {
+      status: 'bootstrap-required',
+      impactLevel: 'unknown',
+      requiresProjectChanges: 'unknown',
+      confidence: 'n/a',
+      rationale:
+        'Changes were detected relative to the committed manifest, but at least one changed file has no private baseline snapshot. This run cannot produce a reliable readable diff or justify a project-impact review on its own.',
+      recommendedAction:
+        'Run `npm run sync:github-docs-state`, then rerun `npm run docs-watch:local` (or `npm run docs-watch:review`). Do not open or update a PR from this run alone.',
+    };
+  }
+
   if (!payload.changed) {
     return {
       status: 'completed',
@@ -123,6 +140,7 @@ async function main() {
   lines.push(`- changed: ${checkPayload.changed}`);
   lines.push(`- changed_count: ${checkPayload.changed_count}`);
   lines.push(`- state_dir: ${checkPayload.state_dir ?? 'none'}`);
+  lines.push(`- bootstrap_required: ${assessment.status === 'bootstrap-required'}`);
   lines.push('');
 
   lines.push('## Monitored Files');
@@ -185,6 +203,10 @@ async function main() {
     fs.appendFileSync(process.env.GITHUB_OUTPUT, `changed=${checkPayload.changed}\n`);
     fs.appendFileSync(process.env.GITHUB_OUTPUT, `changed_count=${checkPayload.changed_count}\n`);
     fs.appendFileSync(process.env.GITHUB_OUTPUT, `assessment_status=${assessment.status}\n`);
+    fs.appendFileSync(
+      process.env.GITHUB_OUTPUT,
+      `bootstrap_required=${assessment.status === 'bootstrap-required'}\n`,
+    );
   }
 
   if (writeSummary) {
@@ -195,6 +217,7 @@ async function main() {
       `- changed: ${checkPayload.changed}`,
       `- changed_count: ${checkPayload.changed_count}`,
       `- assessment_status: ${assessment.status}`,
+      `- bootstrap_required: ${assessment.status === 'bootstrap-required'}`,
     ];
 
     if (process.env.GITHUB_STEP_SUMMARY) {