Release scripts check the tree for cleanliness once, then build from it for minutes

[kiki830621]

Problem

The release scripts check for a clean working tree once, at step 0, then spend several minutes building from that same tree. Anything that edits a source file during the build lands in the signed, notarized artifact — and no gate downstream can see it.

# step 0
[[ -z "$(git status --porcelain)" ]] \
    || { echo "error: working tree not clean …"; exit 3; }

# step 1 — minutes later, reads the tree again
swift build -c release

This is the same TOCTOU shape the scripts already defend against for the upload artifact: step 6 re-verifies the signature and sha256 of the exact bytes about to be uploaded, with the comment FINAL GATE — re-verify the exact upload artifact (TOCTOU guard). The source tree gets no equivalent, and it has the wider window: the universal build is the longest step in the pipeline.

Near-miss (this is not hypothetical)

Today, during a scripts/release.sh 4.0.4 run on che-word-mcp, I edited Sources/CheWordMCP/Server.swift while the build was in progress — working on an unrelated issue and treating the release as a background job. Caught it by checking the build log:

93%: Compile CheWordMCP (x86_64)
93%: Compiling AuthorAliasMap.swift, …, Server.swift, SessionState.swift

The compiler was reading that file at that moment. The run was killed before it reached notarization; no tag and no release were created, and the release was redone from a clean tree afterwards.

Had it completed, the output would have been a Developer ID signed, Apple notarized binary containing an uncommitted, untested edit — with every downstream gate passing, because they all verify the artifact's provenance, never its correspondence to a commit. The wrapper's sha256 and signature checks would have been satisfied. git tag v4.0.4 would have pointed at a commit whose source is not what shipped.

Why the existing gates cannot catch it

gate	what it proves	catches this?
step 0 clean-tree	the tree was clean then	no — point-in-time
step 3 signature gate	Developer ID, correct team	no — a tampered build is still correctly signed
step 6 final gate	uploaded bytes == verified bytes	no — both are the wrong bytes
wrapper install verify	sha256 + signature match the release	no — matches the wrong binary faithfully

Every check is about the artifact. None ties the artifact to a revision.

Suggested fix

Re-check the tree immediately after the build, before signing, and fail if it moved:

# step 0
TREE_AT_START=$(git rev-parse HEAD)
DIRT_AT_START=$(git status --porcelain)

# after step 1, before codesign
[[ "$(git rev-parse HEAD)" == "$TREE_AT_START" && "$(git status --porcelain)" == "$DIRT_AT_START" ]] \
    || { echo "error: working tree changed during the build — the binary may contain code that is in no commit; refusing to sign" >&2; exit 3; }

Cheap, and it closes the window where it matters: before the signature is applied, so nothing carrying an unknown edit ever gets a Developer ID.

Worth considering alongside it: stamp the built commit into the release notes (--target already uses git rev-parse HEAD), so an artifact can be traced to a revision after the fact rather than only forward from one.

Scope

Same code in at least:

• PsychQuant/macdoc — scripts/release-cli.sh
• PsychQuant/che-word-mcp — scripts/release.sh

and likely the other che-*-mcp release scripts, which share this pipeline's shape. Filed here because both gate blocks cite PsychQuant/macdoc#119 as the origin of the requirement.

Honest note on severity

The window only opens if someone edits during a release, which is unusual for a human running one release at a time. It is much less unusual for an agent treating the release as a background task and continuing to work — which is exactly how it happened. That makes this cheaper to fix than to remember.

Current Status

Phase: verified
Last updated: 2026-08-24 by idd-verify

Key Decisions

• Build every release from a fresh detached worktree at captured SOURCE_HEAD with a fresh .build.
• Concurrent primary-tree edits are isolated; isolated-tree drift fails before codesign.
• Pin release target and notes to the captured commit.

Scope Changes

• Replaced the initial post-build primary-tree snapshot with source isolation after adversarial review.
• Explicitly trust compiler/build plugins; reproducible-toolchain attestation remains outside this issue.

Blocking

• (none — four verify-gated PRs await human review/merge)

Commits / PRs

• macdoc 2d7bfd0 — PR Build macdoc releases from isolated source snapshots #168
• che-word-mcp fa94ca9 — PR Build releases from an isolated source snapshot che-word-mcp#196
• che-pdf-mcp 2edb9c7 — PR Build releases from an isolated source snapshot che-pdf-mcp#5
• che-pptx-mcp 3eb00e7 — PR Build releases from an isolated source snapshot che-pptx-mcp#3

Cross-repo implementation checklist

• Release scripts check the tree for cleanliness once, then build from it for minutes #163 — PR Build macdoc releases from isolated source snapshots #168
• bug: refuse release when source tree changes during build che-word-mcp#195 — PR Build releases from an isolated source snapshot che-word-mcp#196
• bug: refuse release when source tree changes during build che-pdf-mcp#4 — PR Build releases from an isolated source snapshot che-pdf-mcp#5
• bug: refuse release when source tree changes during build che-pptx-mcp#2 — PR Build releases from an isolated source snapshot che-pptx-mcp#3

[kiki830621]

Diagnosis

Type

bug

Root Cause / Analysis

The TOCTOU report is reproducible by inspection across four release pipelines: macdoc scripts/release-cli.sh and the che-word/che-pdf/che-pptx scripts/release.sh files all check cleanliness before a long build, then sign the build output without rechecking that HEAD and the working-tree state stayed unchanged.

Artifact signature/hash gates only prove the uploaded bytes are intact and signed; they do not prove those bytes were built from the tagged commit. The near-miss is therefore a real provenance failure class.

Impact

• Repositories: PsychQuant/macdoc, PsychQuant/che-word-mcp, PsychQuant/che-pdf-mcp, PsychQuant/che-pptx-mcp.
• Security boundary: signed/notarized release provenance and tag-to-source correspondence.
• No release should be run during implementation; tests must stub the expensive/signing commands.

Strategy

• Use Release scripts check the tree for cleanliness once, then build from it for minutes #163 as umbrella and create one child issue in each MCP repository; root macdoc work remains here.
• At step 0 capture the exact source revision and require a clean tree.
• Immediately after build and before codesign, fail if HEAD changed or git status --porcelain is non-empty.
• Add shell-level tests that mutate a tracked file or advance HEAD during a stubbed build and assert codesign/notarization/release are never called.
• Preserve successful clean builds and existing final artifact gates.
• Include the captured commit in release notes/diagnostics without claiming cryptographic reproducible-build equivalence.
• Land and verify each repository independently; update the umbrella checklist.

Conflict Class

A_parallel_safe

Each repository owns an independent release script and test harness; child implementations can be isolated without a shared mutable code resource. The umbrella only coordinates consistent policy wording.

Complexity

Plan

Layer P triggers on a risk-sensitive supply-chain boundary, four-repo rollout, ordering of gates, and fail-before-sign semantics. The scripts are internal release tooling rather than a published caller API, so Spectra is not required.

Risks

• A post-sign tree check is too late: it allows unknown source to receive a Developer ID signature.
• Comparing only HEAD misses uncommitted edits; comparing only status misses a commit switch.
• Build products must remain ignored or the new check will reject every normal build.
• Do not conflate source-tree stability with fully reproducible binaries.

Residue

The guard proves the working tree did not change during the build; it does not independently attest compiler/toolchain inputs or make builds reproducible.

Vagueness Pre-check

• V1: 1 — guard the source tree between preflight and pre-sign.
• V4: 2 — mutation-during-build tests and no-sign assertions are explicit.
• Triggered: no — both axes ≤ 3
• Hard-gate: not triggered — files are independent across repositories; Layer P already captures the security risk.

Sister Concerns Filed (mid-diagnose, v2.47.0+ #528)

• (none surfaced)

[kiki830621]

Implementation Plan — macdoc root slice

Plan-tier deliberation skipped under idd-all unattended mode; executing the diagnosed cross-repo pattern sequentially.

• Add a RED harness that mutates a tracked source during the stubbed build and proves the current release still signs/uploads it.
• Capture SOURCE_HEAD after the initial clean-tree gate.
• Recheck HEAD and porcelain immediately after build, before codesign; exit 3 on either change.
• Pin gh release create --target and release notes to the captured source commit.
• Cover dirty-file, changed-HEAD, and clean success paths; prove signing/notary/upload never run after mutation.
• Apply the same contract to child issues che-word-mcp#195, che-pdf-mcp#4, and che-pptx-mcp#2.

[kiki830621]

Implementation Complete

Checklist (synced from cross-repo execution)

• macdoc scripts/release-cli.sh builds from an isolated SOURCE_HEAD worktree.
• che-word-mcp child #195 implements the same source-stability contract.
• che-pdf-mcp child feat: LaTeXEnvChecker — 環境配對檢查與修復 #4 implements the same source-stability contract.
• che-pptx-mcp child feat: AIConfig — AI CLI 工具設定系統 #2 implements the same source-stability contract.
• Each repository tests isolated file/HEAD drift, concurrent primary-tree edits, clean success, and captured release target.
• Signing/notary/upload never run after isolated-tree drift.

Changes

• macdoc: bcd6d00 → 50dc46c → 2d7bfd0
• che-word-mcp: 2f0cb7e → 4d0c5a7 → fa94ca9
• che-pdf-mcp: 75a49e1 → 9258e21 → 2edb9c7
• che-pptx-mcp: e2a54c7 → ac573fe → 3eb00e7

TDD evidence

• RED: all four original pipelines signed/uploaded after a stub build mutated tracked source.
• Review RED: end-state-only gates missed mutate→restore and reused the primary .build.
• GREEN: releases build in fresh detached worktrees, reject drift inside the isolated tree, safely ignore concurrent primary-tree edits, and pin gh release --target to the captured commit.

Scope Compliance

No release was executed. Compiler/build-plugin trust and reproducible-toolchain attestation remain explicitly outside #163.

Sister Bugs Filed (mid-impl, v2.44.0+ #526)

• (none surfaced)

Next: verification complete

[kiki830621]

Verify: #163 cross-repo release source stability

Engine

Per-repo requirements and logic review, cross-repo security review, repeated adversarial fix rounds, sequenced Devil’s Advocate, and coordinator execution of all four harnesses.

Process Gap

• Current subagents are from the Codex/GPT model family; this report does not claim Claude-vs-Codex cross-model diversity.

Aggregate

verify-gated PASS — 0 blocking, 0 follow-up across four repositories.

Scope coverage

• Release scripts check the tree for cleanliness once, then build from it for minutes #163 — final 2d7bfd0
• bug: refuse release when source tree changes during build che-word-mcp#195 — final fa94ca9
• bug: refuse release when source tree changes during build che-pdf-mcp#4 — final 2edb9c7
• bug: refuse release when source tree changes during build che-pptx-mcp#2 — final 3eb00e7

Requirements coverage

Repository	Clean capture	Isolated source/build	Pre-sign drift gate	Target pin	Harness
macdoc	FULLY	FULLY	FULLY	FULLY	PASS
che-word-mcp	FULLY	FULLY	FULLY	FULLY	PASS
che-pdf-mcp	FULLY	FULLY	FULLY	FULLY	PASS
che-pptx-mcp	FULLY	FULLY	FULLY	FULLY	PASS

Test evidence

• All four release-source-stability.sh harnesses passed.
• File drift and detached-HEAD drift inside the build tree exit 3 before codesign.
• Concurrent edits to the primary tree cannot enter the isolated artifact and release still targets the captured commit.
• Clean harness paths reach codesign/notary/upload and use --target SOURCE_HEAD.
• Bash 3.2 syntax, ShellCheck, and git diff --check passed in all repositories.

Review convergence

• R1 caught that post-build snapshots fail open on git errors and cannot detect transient source changes.
• R2 replaced primary-tree builds with fresh detached worktrees and fresh .build directories.
• R3 fixed preflight ordering and explicitly bounded the trusted compiler/build-plugin assumption.

Threat boundary

The fix prevents the reported near-miss: another person or agent editing the primary checkout while a release runs. A compromised compiler/build plugin can emit arbitrary bytes without any source mutation; reproducible toolchain attestation is a separate supply-chain problem and is not silently claimed here.

Verdict

Ready for human review of four PRs. This workflow does not merge or close any issue.

[kiki830621]

Note（2026-09-01 batch close 決策）：macdoc root slice 已 merge（PR #168 → 432538f），但本 issue 是 umbrella——三個 children 尚 OPEN：PsychQuant/che-word-mcp#195、PsychQuant/che-pdf-mcp#4、PsychQuant/che-pptx-mcp#2（同款 mid-build tree-mutation gate）。依 cross-repo-umbrella 紀律，umbrella 留開作 dashboard，children 各自 land + verify 後再 close 本 issue 並勾 umbrella checklist。