[sandwichlegend]

Why

p3stack copies two upstream files that live outside the folders the subtree sync merges. One is the docs check, which comes from scripts/check-pstack-docs.mjs. The other is the skill-name rule, which comes from upstream's harness generator. The sync can't see changes to either file, so a later upstream fix would be dropped silently.

What changed

• scripts/ported.txt lists each copied file with the blob hash p3stack's copy matches and the part it ports. scripts/check.sh requires the file to be committed and validates every row.
• scripts/sync-upstream.sh checks each hash before it runs the checks. If upstream changed the file, it prints the diff and stops. If the recorded blob is missing, it says so and stops without a diff. If upstream no longer has the path, it stops without guessing what happened.
• Step 4 of scripts/sync-agent.md covers both stops. For a file that is gone, it gives the commands for finding out what happened, says what each can't prove, and sends every path change or dropped line to Needs a human.
• The repo README lists scripts/ported.txt and describes the stop.

Scope

• Covers the two files p3stack copies today.
• Doesn't decide on its own whether a missing file moved or was deleted.

Tradeoffs

• An earlier version tried to work out whether a missing file had moved or been deleted. Over several review rounds, the reviewers found realistic histories where every rule guessed wrong. Examples include side-branch renames, later merges, rewrites, and identical copies elsewhere. Handing the decision to the agent and to PR review costs one investigation when this rare case happens, and it can't be wrong in a way that goes unseen.

Blast Radius

Every scripts/check.sh run, including CI, now requires scripts/ported.txt and validates its rows. The rows are valid today. sync-upstream.sh stops only when upstream changes or drops one of the two tracked files. Neither has changed since p3stack copied it.

Verification

• sync-upstream.sh passes against the real upstream.
• On built histories, it stops with a diff when a tracked file changes, and it stops on a missing path in all six move and delete shapes.
• Step 4's commands, run as written, list the real successor as a candidate in each of 11 histories that review raised. They never list a path upstream doesn't have.
• scripts/check.sh rejects a row that has no description, a short hash, or a missing local file, including a last row with no newline.
• /interrogate reviewed this work in rounds 3 to 10. In round 10, Opus found no correctness problems. GPT and Grok found gaps in the investigation steps, which the final commit fixes. No reviewer has seen that commit.

🤖 Generated with Claude Code