Repository navigation
0.0.6
Verify the Spec being delivered today without rerunning every older hidden
retest, while keeping the full public and mutation safeguards in place.
Why upgrade
- Keep verification focused on the current delivery. Pass one or more
Markdown files with--spec. ToppleCat uses theirAC-...IDs to run the
matching reviewer-only checks. Public JUnit and mutation still cover the
complete executable contract. - Catch a changed question before accepting the answer. Hide seals the
selected Spec paths, contents, and AC set. Verify fails contract integrity if
the selection or document changes after handoff. - Require proof that reviewer checks actually ran. Every selected AC needs
current-run evidence from an executed hidden row or tagged reviewer Java
test. A comment, string, plain@Test, or disabled test cannot make the
reviewer gate pass. - See exactly what was verified. Review and verification reports show the
selected delivery scope and render each case as readable Given, When, and Then
steps from the same Java contract that JUnit executes.
For example:
./gradlew toppleCatCheck --spec specs/023-checkout/spec.md
./gradlew toppleCatReview --spec specs/023-checkout/spec.md
./gradlew toppleCatHide --spec specs/023-checkout/spec.md
# The implementation agent works against the public contract.
./gradlew test
./gradlew toppleCatVerify --spec specs/023-checkout/spec.mdRepeat --spec when one delivery spans several documents. Add --all-hidden
to Verify only when the reviewer wants every AC-bound hidden check to run.
Upgrade
Update both the plugin and topplecat-junit dependency to 0.0.6.
plugins {
id("io.github.samzhu.topplecat") version "0.0.6"
}
dependencies {
testImplementation(
"io.github.samzhu.topplecat:topplecat-junit:0.0.6"
)
}Projects without existing reviewer custody need no migration.
If reviewer custody was created by 0.0.5, an authorized reviewer must reseal it
once because 0.0.6 adds the delivery scope to the integrity snapshot. ToppleCat
validates and reads the old approval as the previous full-contract scope; it
does not silently approve the new policy.
./gradlew toppleCatRestore
./gradlew toppleCatCheck --spec specs/023-checkout/spec.md
./gradlew toppleCatReview --spec specs/023-checkout/spec.md
./gradlew toppleCatUpdateEscrow --spec specs/023-checkout/spec.mdOmit --spec in all three scoped commands if the project intends to keep
full-contract verification. Use the same Spec selection for the later Verify.
Compatibility changes
There are no breaking changes to the Java authoring API or to commands that do
not use --spec.
Tools that parse reviewer-only report data.json files must accept
topplecat.review-view.v3 and topplecat.verification-view.v5. The added
delivery-scope fields do not change the public evidence.json or
agent-feedback.json schema.
Learn more
- Select and seal a delivery
- Author executable acceptance conditions
- Troubleshooting contract-integrity failures
- Full design record
只重測今天要交付的 Spec,不必每次把過去所有隱藏案例都跑一遍;完整的公開測試
與突變測試仍然保留。
為什麼值得升級
- 驗證範圍跟著本次交付走。 在指令後指定一份或多份
--spec,ToppleCat
會依裡面的AC-...找到這次需要執行的審閱者檢查。公開 JUnit 與突變測試
仍會檢查完整的可執行合約。 - 代理不能寫完答案後再偷偷換題目。 Hide 會封存本次 Spec 的路徑、內容與
AC 清單。交付後只要換檔案、改內容或改選其他 Spec,Verify 就會讓合約完整性
檢查失敗。 - 確定審閱案例真的有執行。 每個選定的 AC 都要有本次實際執行的隱藏資料列,
或有標記 AC 的審閱者 Java 測試。註解、字串、一般@Test或停用的測試,
都不能冒充執行證據。 - 報告說清楚這次驗證了什麼。 審閱與驗證報告會顯示本次 Spec 範圍,也會把
每個案例整理成容易閱讀的前提、動作與結果(Given、When、Then);內容仍
來自 JUnit 真正執行的同一份 Java 合約。
例如:
./gradlew toppleCatCheck --spec specs/023-checkout/spec.md
./gradlew toppleCatReview --spec specs/023-checkout/spec.md
./gradlew toppleCatHide --spec specs/023-checkout/spec.md
# 實作代理只使用公開合約進行開發。
./gradlew test
./gradlew toppleCatVerify --spec specs/023-checkout/spec.md一次交付橫跨多份文件時,可以重複指定 --spec。只有在審閱者想把所有已綁定
AC 的隱藏檢查都跑過一次時,才在 Verify 加上 --all-hidden。
升級方式
把 Gradle 外掛與 topplecat-junit 一起更新成 0.0.6。
plugins {
id("io.github.samzhu.topplecat") version "0.0.6"
}
dependencies {
testImplementation(
"io.github.samzhu.topplecat:topplecat-junit:0.0.6"
)
}還沒有審閱資料保管區的專案不需要搬移資料。
如果審閱資料保管區是由 0.0.5 建立,授權審閱者需要重新封存一次,因為
0.0.6 會把本次交付範圍也納入完整性快照。ToppleCat 會先驗證舊核准封存,
再把它當成原本的「完整合約範圍」讀取;不會悄悄把新版政策當成已核准。
./gradlew toppleCatRestore
./gradlew toppleCatCheck --spec specs/023-checkout/spec.md
./gradlew toppleCatReview --spec specs/023-checkout/spec.md
./gradlew toppleCatUpdateEscrow --spec specs/023-checkout/spec.md若專案打算繼續驗證完整合約,上面三個有範圍的指令都不要加 --spec。之後
執行 Verify 時,必須沿用同一組 Spec。
相容性變更
Java 合約寫法沒有破壞性變更;不使用 --spec 的既有指令也維持原本行為。
若有工具會自行解析審閱者專用報告的 data.json,需要接受
topplecat.review-view.v3 與 topplecat.verification-view.v5。新增的交付
範圍欄位不會改變公開的 evidence.json 或 agent-feedback.json 格式。