Skip to content

v1.4.4 — 升級前驗證可復原收據，policy/ 退役

Latest
Latest

Choose a tag to compare

View all tags
@yama-learns yama-learns released this 02 Sep 21:16
v1.4.4
467ee7c

v1.4.4 — 有一支程式從 v1.4.1 起就在替你簽名

A program had been signing your name since v1.4.1

🔴 v1.4.3 從未發布。 它在發布前的覆核中被找到五項缺陷，三項紅級。
⇒ 你不會在任何地方看到 v1.4.3，⛔ 那不是遺漏。

Upgrading now verifies a recoverable pre-image, and policy/ retires

這一版由一次外部稽核開始：有人用 v1.4.2 升級他的專案，然後把出問題的地方寫成報告。
This release started with an outside audit: someone upgraded a real project to v1.4.2 and wrote up what broke.

🔴 這一版最重要的一件事

v1.4.1 與 v1.4.2 有一個缺陷：按下升級之後，reviewed 標籤會被移到升級前的提交，
畫面上還會印「人工檢查點：我看過了」——⛔ 而你並沒有按下那個按鈕。

🔴 後果⛔ 不是標籤變了，是你的「還沒看過」被清空：
如果升級當下有 AI 做完、而你還沒審閱的工作，那些變更會從「查看變更」裡消失。

v1.4.4 已經修好。⛔ 但已經被移動過的標籤，程式修好也不會自己還原——
⇒ 請照「升級前必讀」的第 ④ 項檢查一次。

🔴 升級前必讀：四件要你動手的事

Before you upgrade: four things only you can do

① 你填的構想搬家了 / Your filled-in idea has moved

如果你曾經把構想填進 prompts/TEMPLATE_decompose.txt，它現在住在專案根目錄，改名叫
第一個想法.md（英文版 FIRST_IDEA.md），與 PROJECT.md 同層。

🔴 prompts/ 是升級時整包替換的資料夾——⛔ 你填的東西不該住在那裡。
升級工具現在會擋下來並列出檔名，⛔ 而不是換掉它。 照它說的搬，再重跑一次。

If you had filled in prompts/TEMPLATE_decompose.txt, it now belongs at the project root as
FIRST_IDEA.md, beside PROJECT.md. prompts/ is replaced wholesale on upgrade — your text
should never have lived there. The upgrader now stops and names the file instead of replacing it.

② policy/ 退役了 / policy/ has retired

它的四份文件（SOURCES.md、MODEL_IDENTITY.md、HANDOFF.md、EXTERNAL_TOOLS.md）
已經搬進 governance/。

⛔ 升級工具⛔ 不會刪掉你專案裡的 policy/——框架不刪使用者的檔案。
⚠️ 但它會在 check、diff 與每一次成功的 apply 之後把它列出來：

⚠️ 這幾個資料夾已經退役，⛔ 而升級工具⛔ 不會刪掉你的東西：
      ⛔ `policy/`（於 v1.4.4 併入 `governance/`）——內容已經在 `governance/` 了；
         確認之後這個資料夾可以自己刪掉

🔴 為什麼要講這件事：一個沒有人告訴你的孤兒資料夾，與一份過期的框架文件完全一樣——
它看起來還是框架的一部分，而⛔ 再也不會有任何東西更新它。

③ 框架第一次修訂了一條既有規則 / A shipped rule was revised for the first time

R-34 補了一句：「權威敘述的效力範圍，本身也是需要被查的東西。」

升級完 governance/ 之後跑：

python3 scripts/harness/tool_sync_my_rules.py

它會印出逐行差異，+ 開頭的就是新增的句子。
🔴 把那幾行逐字貼進 my/MY_RULES.md 裡 R-34 的正文，然後再跑一次確認。

⛔ ⛔ 沒有工具會替你做這一步，這是刻意的。
⚠️ ⛔ 也不要整份取代 MY_RULES.md——那會刪掉你的 P-xx 與覆寫紀錄。
標了 [本專案覆寫] 的條目工具一律不碰，並且會逐條印出來。

R-34 gained a clause. After replacing governance/, run the rule-sync tool: it prints a
line-by-line difference, and the + lines are the new sentences. Paste them verbatim into
R-34's body in my/MY_RULES.md, then run it again to confirm. ⛔ No tool does this for you,
and that is deliberate — a tool that overwrote your rules file was found, in this version's own
review, to still write when its safety check had failed.

④ 🔴 檢查你的 reviewed 基準 / Check your reviewed baseline

⛔ 這一項⛔ 不是「跑一行指令就知道」——SETUP.md §9 有完整的三步，請照那裡做。
這裡只講為什麼它需要三步：

git log --oneline -1 reviewed

🔴 ⛔ 「訊息開頭是不是 snapshot …」⛔ 不能當判準。
⚠️ 在乾淨工作區升級時（最常見的情形），舊版升級是把標籤移到一個既有的 auto: 提交上——
⛔ 而那也正是「你在 AI 做完之後按了一次記錄快照」的樣子。⇒ 兩者長得一模一樣。

⇒ 第二步是查 git-checkpoint.log 裡 mode=human 的時間，與你自己的記憶對照。
⇒ 第三步：兩步都判不出來時，⛔ 不猜、⛔ 不重設——退回一個你確定看過的提交重看一次。
⚠️ ⛔ 這一段不要用「查看變更」按鈕做：那個按鈕的基準就是 reviewed，⛔ 而它正是被懷疑的東西。

⛔ ⛔ 不建議放著不管——一個指向你沒看過的地方的「我看過了」，比沒有標籤更糟：
沒有標籤時「查看變更」會拿 HEAD 當基準並明說，⚠️ 而錯的標籤不會說。

SETUP.md §9 walks three steps. ⛔ The commit message alone is not a criterion: on a clean
working tree — the common case — the old upgrader moved the tag onto an existing auto:
commit, which is also what a legitimate human review looks like. Step 2 reads the
mode=human timestamps in git-checkpoint.log against what you remember; step 3, when
neither can tell, is ⛔ do not guess and do not reset — drop back to a commit you are certain
about and read forward. ⛔ Not with the review-changes button: its baseline is the very tag
under suspicion.

這一版做的事 / What this release does

🔴 升級會在整包替換前證明既有內容可依 Git 語意取回

整包替換仍然是整包替換——⛔ 沒有改成逐檔合併。
⚠️ 但在覆蓋之前，如果那一包裡有新版來源沒有的檔案，程式會先停下來、逐一列名，
⛔ 而且不建立檢查點、不動任何東西。

[FAIL] 「scripts」內有新版來源沒有的檔案，⛔ 尚未建立檢查點，也沒有替換任何東西。
       這些檔案可能屬於專案；請先逐一搬到整包替換範圍外，再重跑：
      ⛔ scripts/my_tool.py

🔴 它⛔ 不猜所有權。 你自己寫的工具請搬到 my/tools/——那裡升級永遠不會碰。

新增第十支感測器：這幾包是不是同一版

觸發個案： 有一個專案的 policy/ 停在 v1.3.0，而 governance/、profiles/、docs/
已經是 v1.4.2。九支感測器全綠、自測全過。
🔴 ⛔ 沒有任何一支在看「這幾包是不是同一版」——那個狀態是靜默的，靠一次外部稽核才被發現。

⛔ 它不宣稱的事： 版本標記只回答「這個資料夾自稱哪一版」。
同一個專案還有另一半：prompts/_VERSION 寫 v1.4.2，而裡面的內容仍是 v1.3.0。
⇒ 這支抓得到「自稱不一致」，⛔ 抓不到「自稱一致而內容不同」——那件事要跑 upgrade.py diff。

修掉一個會冤枉你的假警報

根目錄的 *.command 這類樣式，掃描目錄被算成了專案的「父目錄」。
🔴 於是隔壁專案的一個檔案，就能讓你這個健康的專案被判成「查不了」。
⚠️ 而第二層檢查又忽略了排除清單，所以 _upgrade/（升級說明叫你建的那個資料夾）
裡的檔案會重現同一個假警報。

⇒ 兩處都修了，並補了三組成對樣本：父目錄一例、_upgrade/ 一例，
加上一個「真的覆蓋崩潰仍然必須報」的正例。
🔴 第三例不能省——只加排除很容易把真正的警報一起關掉。

中文版的 讀我 改叫 說明書

「讀我」是 README 的直譯，⛔ 不是中文說法。 英文版的 READ_ME 也統一成 README。

🔴 規則同步工具⛔ 不會覆蓋你的檔案

v1.4.3 曾經有一個 --adopt 會替你把漂移的規則換成公版原句。⛔ 那一版沒有發布，
而那個功能已經被整個退回。

現在這一支只做兩件事：把缺少的規則附加進去、把不同的地方逐行印出來。
⛔ 它永遠不會覆蓋 MY_RULES.md 裡任何一個既有的字。
⚠️ 那份逐行差異就是告訴你「要手動貼哪幾行」的東西。

🔴 升級之後想把手動改動找回來：使用持久收據

升級在覆蓋之前一定會先建立還原點。⛔ 而 v1.4.4 之前，完成訊息叫你用「查看變更」把改動找回來
——那是假的： 那個按鈕以 reviewed 為基準，⛔ 而工具建立的還原點刻意不移動 reviewed。
🔴 ⇒ 你的 pre-image 確實還在，卻落在那個按鈕的視野之外。

第一版修正只印出提交編號，⛔ 仍有缺口： ignored、assume-unchanged 或
skip-worktree 可能讓 checkpoint commit 與即將被覆蓋的工作檔不同。
Windows 實測曾出現「checkpoint exit 0、提交內沒有手改檔、apply 仍覆蓋」；手改內容隨即消失。

現在 apply 會在替換前逐檔核對： 每個即將被同路徑覆蓋的既有非暫存檔都必須受 Git
追蹤，且依 Git 自己的 attributes／EOL 語意與 checkpoint tree 完全相符；任一項不成立就
列出路徑、exit 2、零替換。

驗證後會建立專案本地持久收據：Git 私有 ref 同時固定 checkpoint 與權威 manifest，可讀 JSON
鏡像放在 Git 自己的目錄。它能在同一個 Git 倉庫內抵抗一般垃圾回收，⛔ 但一般 git clone
或只備份工作檔案不會自動帶走這些私有 ref；它不是跨倉庫備份。

在同語言、同版本且完整的 v1.4.4 套件中，使用者不需要輸入 raw Git 指令：

列出收據：      python3 scripts/harness/upgrade.py receipts
查看單檔差異：  python3 scripts/harness/upgrade.py receipt-diff <收據> <檔案路徑>
還原一個檔案：  python3 scripts/harness/upgrade.py restore <收據> <檔案路徑>

restore 一次只還原一個目前存在的一般檔案，動手前會先建立反向收據，只改 working tree，
且⛔ 不移動 reviewed。apply 與 restore 都先找執行中升級器同目錄、具有相符 tool API
標記的 checkpoint.py，再考慮專案內版本；兩者都不相符時零寫入，並要求重新下載完整同版套件。
讀不回或驗不過收據時，程式不會開始覆蓋或還原。

🔴 中文／英文套件不能再互相覆蓋

v1.4.2 沒有 edition 檢查；中文專案若誤放英文下載包，apply governance 會 exit 0 並把治理文件
整包換成英文。v1.4.4 先用既有三個語言專屬啟動器辨認來源與專案：Windows 可只有 .bat、
macOS 可只有 .command，也可兩套都有。兩邊必須都能唯一辨認且語言相同；跨語言、混合或缺漏
都在檢查點、收據與替換之前拒絕。
🔴 ⚠️ 判定只讀這六個框架啟動器的檔名，⛔ 不看是誰放的——其他名字的
.bat／.command 不參與判定，⛔ 而專案若自己建了一個與它們同名的檔案
（例如自己寫的 snapshot.bat），會被算成另一個語言版本，整次升級被擋下。

🔴 ⇒ 發布前的覆核抓到這件事，所以訊息已經改掉：它現在會逐一列出兩側實際看到的啟動器與所屬版本，
⇒ 你一眼就看得到是哪一個檔案。⇒ 規定動作：把它改名（或搬進 my/），再跑一次。

⚠️ 判定只讀下列十二個框架啟動器檔名，⛔ 不看是誰放的。實際看到的是：
  升級來源：查看變更.bat［中］、檢查更新.bat［中］、記錄快照.bat［中］……
  目前專案：查看變更.bat［中］、檢查更新.bat［中］、記錄快照.bat［中］、snapshot.bat［英］

⚠️ 缺了自己這一版的任何一個啟動器，也會被判成不完整而整次拒絕——同樣是零寫入。

The gate reads only these six framework launcher names and ⛔ not who put them there, so a
project file that happens to carry one — your own snapshot.bat, say — counts as the other
edition and blocks the whole upgrade. Pre-release review caught this, so the refusal now
lists the launchers found on each side with their edition: rename the offending file (or move
it under my/) and run again. A missing launcher from your own edition is likewise refused,
with zero writes.

🔴 同一道閘門帶來另一項行為變更：_upgrade/ 裡⛔ 不能再只放一個資料夾。
v1.4.2 以前，只把 governance/ 丟進 _upgrade/ 就能升級那一包；
v1.4.4 要在來源端也看到完整的語言啟動器，⇒ 只放單一套件會被判成不完整並 exit 1（零寫入）。
⇒ 請解壓完整套件。

One more behaviour change from the same gate: _upgrade/ can no longer hold a single package.
Dropping just governance/ in there worked before v1.4.2; v1.4.4 needs the source side to show
a complete launcher set, so a single-package source is now rejected as incomplete with exit 1
and no writes. Unpack the complete package.

⚠️ 這是 v1.4.4 的相容性修補；正式 machine-readable edition 欄位排入 v1.5.0 套件 schema。

🔴 語料庫的雜湊會在「換一台機器」時整片變紅——⛔ 而內容沒有被動過

如果你曾在 Windows 上跑過 tool_pdf_to_md.py，這一項與你有關。

提取工具寫檔時沒有固定行尾，⇒ Windows 上檔案以 CRLF 落地，
而 _manifest.json 記的就是 CRLF 的雜湊。⛔ 而框架的 .gitattributes 會把倉庫內正規化成 LF。

🔴 ⇒ 下一次乾淨簽出（clone 到第二台機器、git checkout、或照 SETUP.md §9 復原）
工作區變成 LF，每一個提取物的雜湊都對不上 → CORPUS_MD_MODIFIED 整片 FAIL。
⚠️ ⛔ 而你的內容一個字都沒有被動過。

v1.4.4 已修（newline="\n"）。⇒ 規定動作：重跑一次提取工具，
manifest 與檔案會一起變成 LF，⇒ 自洽。

If you have ever run tool_pdf_to_md.py on Windows, this affects you. The extractor did not
fix its line ending, so files landed as CRLF while .gitattributes normalises the repository
copy to LF. On the next clean checkout every recorded hash mismatches and the corpus goes red
with nothing actually changed. Fixed in v1.4.4; run the extractor once more so the
manifest and the files agree again.

感測器現在會說出它比對了幾份

主張台帳感測器一直在逐檔重算語料庫的雜湊，⛔ 而它從來沒有說過。
🔴 兩位不同的稽核者、隔了七天，各自得到「找不到哪一支感測器在做這件事」的結論——⛔ 而它一直都在。
⇒ 統計欄現在印「逐檔比對雜湊：N 份」；語料庫是空的時候印 0，⛔ 不是省略。

事故登記簿新增三個失效家族

⑨ 批次編輯成功了、⛔ 而它做的不是你要的事（🔴 讀 diff 抓不到它）；
⑩ 為一個環境調好的常數，原封不動搬到另一個（🔴 兩邊逐字相同，⇒「一致」正是它的偽裝）；
⑪ 兩個寫入者共用一個編號空間，而各自看來都配號成功（碰撞只在合併後出現）。
另加「索引當權威」的兩個新變體。⚠️ 三個新家族都標 [框架自身]——它們發生在維護這套框架的過程中。

其他

  • tool_sync_my_rules.py 以前會忽略 --root，可能寫到你沒有指名的那個專案，而且退出碼 0。

  • tool_my_index.py --help 以前會覆寫你的索引。 兩支現在都先驗參數再動檔案。

  • 可替換清單的數字從說明文字裡全部拿掉了。 那個數字已經漂過三次（九 → 16 → 15）。
    🔴 清單才是權威；一個複述它的數字只是第二份拷貝，而它會過期。

  • 🔴 框架自己的原始碼引用了一條不存在的規則。 anchor_norm.py 兩處寫 R-43，
    ⛔ 而 RULES.md 只到 R-35；那兩句其實都是 R-27。⛔ 沒有任何一支感測器在查規則 ID 引用
    （一支查檔案存不存在、一支查章節解不解析得出來），⇒ 它在每一次全綠中存活。
    ⚠️ 英文版⛔ 從來沒有這兩處引用。⇒ 補上感測器留給 v1.5.0 的保證地圖。

  • CITATION.cff 曾經連續三個版本停在 1.1.0，因為它不在 _VERSION 機制裡、也沒有感測器看它。
    已對齊為 1.4.4，並在維護側加了一道發版閘門。

  • 人工檢查點以前會在標籤建不起來時謊報成功。 專案裡只要先有一個 reviewed/<某某> 標籤，
    Git 就再也放不下 reviewed，⛔ 而程式照樣印「基準已移到最新的檢查點」並回 0。
    🔴 現在它檢查退出碼、把標籤讀回來與 HEAD 比對，任一步不成立就非零退出並說清楚。

  • --adopt 已經從程式移除，⛔ 而三處說明還在叫你用它。 都清掉了，
    並加了一道靜態掃描：任何已退回的旗標只要出現在現行說明裡而沒標「已退回」就會讓自測失敗。

自測 79 → 159 項。感測器 9 → 10 支。

⛔ 本版不宣稱 / This release does not claim

  • ⛔ 六份 .command 從來沒有在真的 macOS 上被雙擊執行過。 兩位維護者都沒有 macOS 環境；
    ⚠️ Git Bash 與 Linux 的實跑⛔ 不是 macOS 的證明。
  • ⛔ corpus_md/ ⛔ 沒有併進 corpus/。 policy/ 是框架資料夾（框架自己搬得動），
    corpus_md/ 是你的資料（⛔ 只有人搬得動）——風險不同級，刻意分兩版做。
  • ⛔ 既有專案殘留的 policy/ 資料夾，沒有任何東西會刪掉它。 工具只負責告訴你。
  • ⛔ v1.4.4 不自動清除升級收據。 跨工具共用 receipt 核心與清理政策留到 v1.5.0。
  • ⛔ 工具打錯參數仍然退出碼 2，與框架的「查不了」撞號。 這是介面級決定，留待之後統一。
  • ⛔ 綠燈只涵蓋已機械化的環節。 論證品質、來源是否實質支持結論、外推是否誠實——
    這三件事刻意不機械化，⛔ 因為它們是人的工作。

升級步驟 / How to upgrade

本節是 v1.4.4 的版本專屬升級說明。 公開 SETUP.md 保留版本中立的通用步驟；
若從 v1.4.3 或更早版本升級，本節只在第一次替換 scripts 時取代通用步驟，完成後立即回到
專案內的新版升級器。這個特例不會被寫進長期 SETUP.md，避免 v1.5.0 改變升級架構後留下過期指示。

This section is specific to the v1.4.4 release. The public SETUP.md keeps the
version-neutral route. When upgrading from v1.4.3 or earlier, this section overrides only the
first scripts replacement; after that, return immediately to the upgraded in-project tool.

  1. 下載本版 ZIP，解壓到專案裡的 _upgrade/ 資料夾

  2. 按「檢查更新」按鈕（它會自動接著做唯讀差異檢查，⛔ 兩步都不會改檔案）

  3. 🔴 若目前是 v1.4.3 或更早版本，第一次 apply 必須直接執行下載包裡的 v1.4.4
    upgrade.py，先換 scripts；不要使用舊專案內那支：

    python3 "_upgrade/Spark2Groundwork_zh/scripts/harness/upgrade.py" apply scripts --root .

    英文版把路徑中的 Spark2Groundwork_zh 改成 Spark2Groundwork_en。若解壓後外面另包一層
    資料夾，路徑也要包含那一層。判準是：執行的檔案必須位於剛下載的新版內。

  4. scripts 成功後，才用目前專案內的新版升級器一次換一包：
    python3 scripts/harness/upgrade.py apply governance

  5. 依上方「升級前必讀」處理 ①②③④

  6. 重跑 python3 scripts/harness/run_all_sensors.py

⚠️ 這個 bootstrap 是必要的：舊版 upgrade.py 沒有 v1.4.4 的逐檔驗證與持久收據，
⛔ 它不會因為 _upgrade/ 裡放了新版而自動獲得新保護。

English steps:

  1. Download the v1.4.4 ZIP and unpack it under _upgrade/ in your project.

  2. Press check update. Its version check and automatic diff are read-only.

  3. If the project is on v1.4.3 or earlier, run the v1.4.4 upgrader from the downloaded package
    for the first scripts replacement. Do not run the old in-project upgrader for this step:

    python3 "_upgrade/Spark2Groundwork_en/scripts/harness/upgrade.py" apply scripts --root .

    If the ZIP unpacked with another enclosing directory, include it in the path. The executable
    file must be the one inside the newly downloaded v1.4.4 package.

  4. After scripts succeeds, return to the now-upgraded in-project tool and replace one package at
    a time, for example: python3 scripts/harness/upgrade.py apply governance.

  5. Complete items ①–④ in Before you upgrade above.

  6. Run python3 scripts/harness/run_all_sensors.py again.

⚠️ This bootstrap is necessary because an old upgrade.py does not gain v1.4.4's per-path
pre-image verification or durable receipts merely because a new package exists under _upgrade/.

⚠️ 你也可以完全不跑升級工具：備份整個專案，再逐包把舊資料夾移走、放入新版同名資料夾。
🔴 但手動路徑⛔ 沒有自動檢查點——SETUP.md 步驟 9.1 有完整說明。

Assets 2
Loading