From d5059d9a9fb4ef4857d439303a30f4c2bcd0e298 Mon Sep 17 00:00:00 2001 From: Dylan Roy <249851642+d6g8k5htny-coder@users.noreply.github.com> Date: Thu, 22 Oct 2026 12:14:36 -0500 Subject: [PATCH] docs: explain complete changed-path inventories and capped API fallbacks Add only the reviewed WORKSPACE.md subsection about independent file counts, GitHub's 3000/300 file-list caps, merge-base Git diffs, NUL-separated paths, rename endpoints, and bounded tree comparisons. No new governance or tooling. Actual author/publisher: OpenAI / GPT-6 Astra Pro, RESUME-LINK-SEMANTICS. Canonical pickup: main#275 comment 6346306539. Frozen proposal: main#275 comment 6346493723. Separate xAI Grok 4.7 PASS_SCOPED: main#389 comment 6346504769. The review is source-bound evidence, not native PR approval or merge clearance. Scientific effect NONE. No proof, status, workflow, protection or schedule change. --- docs/WORKSPACE.md | 50 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/docs/WORKSPACE.md b/docs/WORKSPACE.md index f0e52e55e..0b3740e54 100644 --- a/docs/WORKSPACE.md +++ b/docs/WORKSPACE.md @@ -170,6 +170,56 @@ editing the body, and an integrator that edits the body lets the new run finish before merging. On 20 October 2026 this refused the first merge attempt on main#450 and on main#467. +### Complete changed-path inventories + +Finishing pagination does not by itself establish a complete overlap check. +GitHub's [pull-request files endpoint](https://docs.github.com/en/rest/pulls/pulls#list-pull-requests-files) +returns at most 3,000 files; the +[compare endpoint's file list](https://docs.github.com/en/rest/commits/commits#compare-two-commits) +contains at most 300. In the [21 October #436 reconciliation](https://github.com/d6g8k5htny-coder/main/pull/389#issuecomment-6328963128), +`files.totalCount=3000` and `hasNextPage=false` coexisted with 5,943 actual changed +paths. The terminal page was real; the completeness inference was wrong. + +For an as-of inventory, record the repository, PR number, full head and base +SHAs, and observation time. Page the native open-PR collection and each file +list, comparing its unique returned-file count with the individual PR's +`changed_files` (or `changedFiles`) at the same head. Include `previous_filename` +when checking renamed-path overlap. Recheck head/base identities after collection +and before a dependent write; refresh changed entries. Missing pages, count +mismatches, failed requests or truncated responses leave coverage partial, not +an empty change set. This records evidence for the existing workflow's overlap +check; it adds no approval step or ownership register. + +For a capped list, use a complete Git comparison from the PR's actual merge base +to its frozen head, not from a newer base tip. Establish the merge base using +complete history or the compare API's `merge_base_commit` metadata as described +above; its capped **file list** is not the fallback. In the repository root, set +these variables to the verified full SHAs and use a new scratch output path: + +```sh +MERGE_BASE='' +HEAD_SHA='' +git cat-file -e "${MERGE_BASE}^{commit}" && +git cat-file -e "${HEAD_SHA}^{commit}" && +git diff --no-ext-diff --no-renames --name-only -z \ + "$MERGE_BASE" "$HEAD_SHA" -- > changed-paths.z +``` + +Require a successful command before consuming the output. Parse NUL-delimited +names, not lines: filenames can contain newlines. `--no-renames` exposes both +old and new paths; its path count can differ from GitHub's rename-aware file +count, so explain that difference rather than forcing numerical equality. +Retain the command, frozen identities, output count and digest with the result. + +Without local Git, qualified nontruncated tree comparisons can establish the +same **bounded path** result: compare the relevant mode/type/object identities +at the merge base and head. Equal subtree identities cover that subtree only. +When a [recursive tree response is truncated](https://docs.github.com/en/rest/git/trees#get-a-tree), +walk nonrecursive subtrees instead; infer absence only from successfully read, +complete parent entries, never an unexplained 404. Unavailable evidence remains +unknown, and no access denial is waived. A target-path nonoverlap result is not +a complete file-content audit, proof review, or current ownership determination. + ## Local navigation check The landing workflow's `landing-checks` job first requires that the same run's