ToppleCat 0.2.2

ToppleCat 0.2.2 lets Java/JUnit teams place each checked acceptance projection
at one explicit business-Spec marker, so changing a Markdown heading or adding
an ordinary AC reference can no longer silently change selected scope.

Place executable acceptance material exactly where it belongs

Each selected AC now uses one exact standalone marker, such as
<!-- topplecat:acceptance:AC-CHECKOUT-001 -->, as both its machine identity
and its Spec Review insertion point. Review inserts one complete checked
projection there, in marker order, including every bound scenario, typed row,
and ordered Given/When/Then/And/But Step. Different markers may be consecutive
or appear anywhere at the supported document level.

Reject ambiguous selected-Spec input before Review

Headings, ordinary AC references, and marker proximity are authored prose, not
declarations. Check rejects duplicate IDs across the supplied selected Markdown
documents and reports every conflicting location. It also gives repairable
diagnostics for generic legacy markers, malformed directives, and container or
inline lookalikes; none falls back to heading-based pairing. Unselected files
and .feature files remain outside selected scope.

Upgrade

This is a breaking selected-Spec authoring change from 0.2.1. Replace every
generic <!-- topplecat:acceptance --> marker with an exact ID-bearing marker,
and pass the same repository-relative --spec paths to Check, Review, and
scoped Verify. No change is required for whole-contract Check, Seal, or Verify.
toppleCatSeal continues to seal the complete executable contract, not a
selected Spec scope.

Requirements

ToppleCat still runs on JDK 21 or 25; consumer source may target Java 17, 21,
or 25 when Gradle runs on a supported execution JDK. Maven Central publication
remains a separate maintainer action.

Full changelog

Compare ToppleCat 0.2.1 to 0.2.2

=============
ToppleCat 0.2.2 讓 Java/JUnit 團隊可以在業務 Spec 的一個明確 marker 位置放入已檢查的
驗收投影，因此調整 Markdown 標題或新增一般 AC 引用時，不會再悄悄改變 selected scope。

在正確位置放入可執行驗收內容

每個 selected AC 現在使用一個精確、獨立一行的 marker，例如
<!-- topplecat:acceptance:AC-CHECKOUT-001 -->，同時作為 machine identity 與 Spec Review
插入點。Review 會依 marker order 在該處插入一份完整、已檢查的 projection，包含所有綁定的
scenario、typed row，以及有序的 Given/When/Then/And/But Step。不同 marker 可以連續出現，
也可以放在支援的文件層級任意位置。

在 Review 前拒絕含糊的 selected-Spec input

標題、一般 AC 引用與 marker 鄰近性都是作者文字，不是 declaration。Check 會拒絕 supplied
selected Markdown documents 中重複的 ID，並列出所有衝突位置；也會為 generic legacy marker、
格式錯誤 directive、container 或 inline lookalike 提供可修復診斷，絕不 fallback 到 heading-based
pairing。unselected files 與 .feature files 仍不在 selected scope 內。

升級

這是從 0.2.1 起的 breaking selected-Spec authoring change。請把每個 generic
<!-- topplecat:acceptance --> marker 換成精確的帶 ID marker，並將相同的
repository-relative --spec paths 傳給 Check、Review 與 scoped Verify。whole-contract Check、
Seal 與 Verify 不需要改動。
toppleCatSeal 仍封存完整可執行契約，而不是 selected Spec scope。

要求

ToppleCat 仍在 JDK 21 或 25 執行；使用端 source 可以 target Java 17、21 或 25，但 Gradle
執行環境必須是支援的 JDK。Maven Central 發布仍是維護者另外執行的工作。

完整變更

比較 ToppleCat 0.2.1 與 0.2.2

ToppleCat 0.2.1

ToppleCat 0.2.1 lets Java/JUnit teams review the complete business Spec beside its exact executable acceptance contract—without switching between Markdown, Java tests, and case-data files.

Highlights

Review the complete selected Spec

Spec Review now renders every selected Markdown document in full and inserts the checked Java/JUnit acceptance projection at each authored marker:

<!-- topplecat:acceptance -->

The report preserves authored Markdown, multiple Given/When/Then/And/But narratives, public and reviewer-owned case rows, AC navigation, nested data, and source snapshots.

Select one or more Specs explicitly

Check, Review, and scoped Verify use the same repository-relative .md paths:

./gradlew toppleCatCheck \
  --spec docs/specs/checkout.md \
  --spec docs/specs/payment.md

./gradlew toppleCatReview \
  --spec docs/specs/checkout.md \
  --spec docs/specs/payment.md

./gradlew toppleCatVerify \
  --spec docs/specs/checkout.md \
  --spec docs/specs/payment.md

Review always requires at least one --spec. Without a Spec selection, Check, Seal, and Verify continue to operate on the complete executable contract.

Remove the separate Spec registry

The former topplecat-specs.json locator, stable Spec keys, AC inventory mirror, and Python maintenance helper are removed.

ToppleCat now reads the explicitly selected Markdown documents directly. .feature files are not read, registered, translated, or executed.

Safer checked input

Selected paths reject absolute paths, repository traversal, symbolic-link escapes, missing documents, invalid marker structures, and duplicate AC declarations.

Check snapshots the selected Markdown, Java source, and report assets. Review refuses content changed after Check and clears stale selected-Spec output after a failed selection.

More readable reports

Spec Review now supports:

• English and Traditional Chinese;
• keyboard and screen-reader navigation;
• narrow screens and large reports;
• safe rendering of raw HTML;
• stable links from ordinary AC references;
• accessible nested JSON and YAML case data.

Upgrade notes

If you used the earlier selected-Spec prototype:

1. Remove topplecat-specs.json and its maintenance scripts.
2. Pass the same repository-relative --spec paths to Check, Review, and scoped Verify.
3. Add an exact <!-- topplecat:acceptance --> marker where each AC projection should appear.

Users upgrading from 0.2.0 should note that toppleCatReview now requires an explicit Spec selection.

Installation

ToppleCat 0.2.1 is available from Maven Central.

plugins {
    java
    id("io.github.samzhu.topplecat") version "0.2.1"
}

dependencies {
    testImplementation(
        "io.github.samzhu.topplecat:topplecat-junit:0.2.1"
    )
}

ToppleCat runs on JDK 21 or 25. Consumer source may target Java 17, 21, or 25 when Gradle runs on a supported JDK.

Full changelog

Compare ToppleCat 0.2.0 to 0.2.1

---

繁體中文

ToppleCat 0.2.1 讓 Java/JUnit 團隊能在同一份 Spec Review 中閱讀完整業務規格與確切的可執行驗收契約，不必再來回切換 Markdown、Java 測試與案例資料。

完整呈現選定的規格

Spec Review 現在會完整呈現每一份選定的 Markdown 文件，並在作者放置的標記處插入已經 Check 的 Java/JUnit 驗收內容：

<!-- topplecat:acceptance -->

報告會保留原始 Markdown、多組 Given/When/Then/And/But 敘事、公開及審閱者案例、AC 導覽、巢狀資料與原始碼快照。

明確選擇一份或多份規格

Check、Review 與指定範圍的 Verify 使用相同的專案相對 .md 路徑：

./gradlew toppleCatCheck \
  --spec docs/specs/checkout.md \
  --spec docs/specs/payment.md

./gradlew toppleCatReview \
  --spec docs/specs/checkout.md \
  --spec docs/specs/payment.md

./gradlew toppleCatVerify \
  --spec docs/specs/checkout.md \
  --spec docs/specs/payment.md

Review 一律需要至少一個 --spec。沒有選擇規格時，Check、Seal 與 Verify 仍會處理完整的可執行契約。

移除額外的規格索引

舊的 topplecat-specs.json、固定 Spec key、AC 清單副本與 Python 維護工具均已移除。

ToppleCat 現在直接讀取明確選定的 Markdown 文件，也不會讀取、登記、轉譯或執行 .feature 文件。

更安全的檢查內容

選定的路徑會拒絕絕對路徑、跳出專案目錄、symbolic link 越界、文件不存在、marker 結構錯誤，以及重複的 AC 宣告。

Check 會保存當下的 Markdown、Java source 與報告資源。若內容在 Check 後遭到修改，Review 會拒絕產生報告；選取失敗時也會清除舊結果。

更容易閱讀的報告

Spec Review 現在支援：

• 英文與繁體中文；
• 鍵盤及螢幕閱讀器操作；
• 窄螢幕與大型報告；
• 安全呈現 raw HTML；
• 一般 AC 引用的穩定導覽；
• 容易展開閱讀的巢狀 JSON、YAML 案例資料。

升級注意事項

如果曾使用先前的 selected-Spec 原型：

1. 移除 topplecat-specs.json 與相關維護工具。
2. 將同一組專案相對 --spec 路徑傳給 Check、Review 與指定範圍的 Verify。
3. 在每個 AC 要插入驗收內容的位置加入精確的 <!-- topplecat:acceptance --> marker。

從 0.2.0 升級的使用者請注意：toppleCatReview 現在必須明確選擇 Spec。

安裝

ToppleCat 0.2.1 已發布至 Maven Central。

plugins {
    java
    id("io.github.samzhu.topplecat") version "0.2.1"
}

dependencies {
    testImplementation(
        "io.github.samzhu.topplecat:topplecat-junit:0.2.1"
    )
}

ToppleCat 的執行環境需要 JDK 21 或 25。只要 Gradle 使用支援的 JDK，使用端程式碼可以 target Java 17、21 或 25。

完整變更

比較 ToppleCat 0.2.0 與 0.2.1

0.2.0

ToppleCat 0.2.0 lowers the runtime requirement from Java 25 to Java 21 while keeping Java 25 as the primary build and release JDK.

Highlights

• Minimum ToppleCat runtime: JDK 21
• Supported runtime JDKs: 21 and 25
• Published artifacts target Java 21 bytecode
• Built with JDK 25 using --release 21
• All four Gradle modules and the Gradle plugin use the Java 21 bytecode baseline
• Java 25 remains supported for runtime and consumer projects

Consumer compatibility

Consumer projects may continue to use:

• Java 17 source on JDK 21 or JDK 25
• Java 21 source on JDK 21 or JDK 25
• Java 25 source on JDK 25

A JDK 17-only environment is not supported because ToppleCat 0.2.0 artifacts target Java 21 bytecode.

No Java 17 source rewrite is required when the consumer executes on JDK 21 or JDK 25.

Verification

The release validation includes:

• JDK 21 minimum compatibility CI
• JDK 25 primary build and release CI
• JDK 17 unsupported-runtime guard
• Consumer source/runtime compatibility matrix
• Gradle plugin functional tests
• Hidden tests, property-based tests, and mutation testing
• Artifact bytecode and publication metadata scanning

All 260 ToppleCat class files were verified as Java 21 bytecode (class file major version 65), with no preview features.

Upgrade

Update the Gradle plugin and JUnit dependency to 0.2.0:

plugins {
    id("io.github.samzhu.topplecat") version "0.2.0"
}

dependencies {
    testImplementation("io.github.samzhu.topplecat:topplecat-junit:0.2.0")
}

ToppleCat requires JDK 21 or JDK 25 to build and execute.

If a project carries reviewer custody from 0.1.0, restore it, run Check and Review, then reseal it under the 0.2.0 policy before formal Verify.

ToppleCat 0.1.0

ToppleCat 0.1.0 makes both sides of an agent handoff reviewable: read the executable contract before implementation starts, then verify fresh, AC-attributed evidence after the agent finishes. The delivery decision remains with the human.

Review the contract before handoff

toppleCatReview --spec ... produces a reviewer-only Spec Review that shows the selected Markdown Spec alongside the executable material bound to each Acceptance Condition: scenarios, public and reviewer-owned Typed Case Rows, properties, and public Acceptance Method source.

It is a reading surface for handoff preparation. It does not run verification or decide whether the upstream Spec is complete.

Verify a completed feature without weakening the full-project seal

toppleCatVerify remains the complete-contract command for CI. Reviewers can also select repeated Spec paths or AC IDs for focused feedback on recently completed work.

Scoped verification runs Public Acceptance, Hidden Tests, Property-Based Testing, and Mutation Testing for the selected ACs. The report makes the scope explicit and states that a scoped PASS is not a complete-contract result. Contract Integrity, toppleCatSeal, and toppleCatReseal always use the complete contract and policy.

Keep mutation evidence with the AC that earned it

Formal Mutation Testing uses ToppleCat’s managed PIT profile. Mutation Attribution matches the complete Acceptance Method identity, so every AC must detect the mutations attributed to its own public method. Project-wide mutation scores and percentage thresholds do not substitute for AC-level evidence.

When evidence is incomplete or a mutation is missed, the Verification Report shows what was assessed, detected, and undetected without exposing reviewer-only details to the implementation agent.

Start with the result, then inspect the details

Verification Report opens with each Acceptance Condition’s status, plain-language result, and safeguard outcomes. Failed cases show authored input plus expected-versus-actual differences before deeper technical evidence.

Property completion counts now require a complete lifecycle from the current run, matched to the sealed AC, full Java method identity, and source digest.

Read reports in English or Traditional Chinese

Spec Review and Verification Report support --language en and --language zh-TW. The option translates ToppleCat-owned interface text while preserving selected Markdown, test names, case data, AC IDs, Gate names, verdicts, PIT outcomes, producer text, and raw failures.

Keep public demonstrations separate from real deliveries

The public project page includes five synthetic checkout examples for Public Acceptance, Hidden Tests, Property-Based Testing, Mutation Testing, and Contract Integrity. These examples explain the product; they are not evidence or approval for an actual delivery.

Requirements

ToppleCat 0.1.0 requires Java 25 and a compatible Gradle version. Formal Verify manages PIT 1.25.5. Reviewer report bundles work offline and do not load external UI, fonts, analytics, syntax highlighting, or a Mermaid runtime.

0.0.10

0.0.10 makes formal Mutation Testing comparable across AI deliveries: every
Verify run now owns the PIT version, operator set, public Acceptance Methods,
and full result matrix while preserving the producer's raw evidence for human
review.

Upgrade: remove custom formal mutation producers

Formal toppleCatVerify no longer accepts mutationTesting.producerTask or
mutationTesting.reportFile. Remove those settings before upgrading. A project
may still run its own PIT workflow separately, but ToppleCat does not read,
merge, or use that result for its Mutation Gate.

The public Java/JUnit acceptance-authoring API is otherwise unchanged.

Run the same mutation challenge for every delivery

Formal Verify now runs PIT 1.25.5 with the versioned
topplecat-managed-v1 profile. The profile explicitly selects return-value,
forced-conditional, conditional-boundary, void-call, and arithmetic operators;
it never inherits PIT's DEFAULTS, STRONGER, or ALL groups.

The producer is fresh for every formal run and targets only compiler-emitted
public Acceptance Methods. Hidden Tests, Properties, helpers, and a project's
own PIT tasks cannot contribute mutation coverage or detection credit.

See which exact Acceptance Method detected a change

ToppleCat keeps PIT's original status, detected, mutator, description,
coveringTests, killingTests, and succeedingTests. Mutation Attribution
matches the complete class, method, overload, and parameter types. Each AC's
detection rate therefore counts only mutants covered by that Acceptance Method
and killed by that same method.

A usable matrix with no exact public attribution fails the Mutation Gate. Once
some exact attribution exists, remaining unattributed mutants and ACs with no
covered managed-profile mutant stay visible to the reviewer without directly
changing the Gate. The sealed threshold still applies to every AC that has
covered mutants; lowering it remains a human verification-policy decision.

Review independent evidence without a blended score

Verification HTML presents Mechanical Seal, Hidden Tests, Property-Based
Testing, and Mutation Testing as separate sections. Mutation details include
the managed profile, operator summaries, per-AC rates, attribution gaps, and
expandable raw PIT relationships. Every enabled Independent Safeguard finishes
and retains its own current-run result even when another one fails.

Contract Review also includes the reviewer-only, non-blocking Contract Quality
Advisory introduced since the previous published GitHub Release. It flags
possible expected-shape drift or opaque identifier literals for human review;
it never infers business rules or affects a Gate.

Public reports and agent-feedback.json remain safe: profile details, raw PIT
fields, selectors, classes, methods, counts, hidden data, and private failures
stay reviewer-only.

Upgrade actions

1. Update the Gradle plugin and topplecat-junit dependency to 0.0.10.
2. Remove producerTask and reportFile from mutationTesting configuration.
3. Restore reviewer custody, Check, Review, and Reseal before Verify because
   the Mechanical Seal is current-version-only.

Reviewer tooling that reads generated projections must adapt to the directly
updated topplecat.mutation-results.v1 managed-profile fields and the current
topplecat.review-view.v6 and topplecat.verification-view.v8 projections.
There is no migration or dual-format reader.

Requirements

Java 25 and the existing compatible Gradle and JUnit requirements are
unchanged. PIT 1.25.5 is managed internally by formal Verify.

========================
0.0.10 讓不同 AI 交付的正式突變測試可以互相比較：每次 Verify 都由 ToppleCat
管理 PIT 版本、operator 清單、公開 Acceptance Method 與完整結果矩陣，同時保留
producer 的原始證據供人類判讀。

升級：移除自訂的正式 mutation producer

正式 toppleCatVerify 不再接受 mutationTesting.producerTask 或
mutationTesting.reportFile。升級前請移除這兩項設定。專案仍可另外執行自己的 PIT
工作流，但 ToppleCat 不會讀取、合併或將其結果用於 Mutation Gate。

公開 Java/JUnit 驗收撰寫 API 除此之外沒有改變。

每次交付都執行相同的突變挑戰

正式 Verify 現在固定執行 PIT 1.25.5 與版本化的 topplecat-managed-v1 profile。
這個 profile 明確選取回傳值、強制條件、條件邊界、void call 與算術運算相關
operators，不會繼承 PIT 的 DEFAULTS、STRONGER 或 ALL 群組。

每次正式執行都重新建立 producer，只以 compiler 產生的公開 Acceptance Methods
為目標。隱藏測試、Properties、helper 與專案自己的 PIT task 都不能替 Mutation Gate
提供 coverage 或 detection credit。

看見是哪個精確 Acceptance Method 偵測到改變

ToppleCat 原樣保留 PIT 的 status、detected、mutator、description、
coveringTests、killingTests 與 succeedingTests。Mutation Attribution 會完整比對
class、method、overload 與參數型別，因此每個 AC 的 detection rate 只計算該
Acceptance Method 自己覆蓋、並由同一方法殺死的 mutants。

若可用矩陣完全無法精確歸因到任何公開方法，Mutation Gate 會失敗。一旦已有部分
精確歸因，其餘 unattributed mutants 與沒有被 managed profile mutant 覆蓋的 AC
仍會呈現給審閱者，但不直接改變 Gate。所有已有 covered mutants 的 AC 仍套用
sealed threshold；降低 threshold 仍是人類選擇的驗證政策。

分開判讀各項證據，不建立綜合分數

Verification HTML 將 Mechanical Seal、隱藏測試、Property-Based Testing 與
Mutation Testing 分區呈現。Mutation 區塊包含 managed profile、operator 摘要、
每個 AC 的 rate、attribution gap，以及可展開的 PIT 原始關係。即使某一項失敗，
每個已啟用的 Independent Safeguard 仍會完成並保留本次執行的獨立結果。

自上一個已公開的 GitHub Release 起，Contract Review 也加入 reviewer-only、非阻擋的
Contract Quality Advisory，提醒人類檢查可能的 expected shape drift 或 opaque
identifier literal。它不推測業務規則，也不影響任何 Gate。

公開報告與 agent-feedback.json 仍維持安全邊界：profile 細節、PIT 原始欄位、
selectors、class、method、計數、隱藏資料與私密失敗都只提供給審閱者。

升級步驟

1. 將 Gradle plugin 與 topplecat-junit dependency 更新為 0.0.10。
2. 移除 mutationTesting 中的 producerTask 與 reportFile。
3. Mechanical Seal 只適用目前版本；更新後請先 Restore reviewer custody，再 Check、
   Review、Reseal，最後才 Verify。

若 reviewer tooling 會讀取產生的投影，必須配合直接更新的
topplecat.mutation-results.v1 managed-profile 欄位，以及目前的
topplecat.review-view.v6 與 topplecat.verification-view.v8。本版不提供 migration
或雙格式 reader。

環境需求

Java 25 與既有相容的 Gradle、JUnit 需求沒有改變。正式 Verify 會在內部管理
PIT 1.25.5。

0.0.8

0.0.8 makes every enabled Independent Safeguard leave an honest result from the same formal run. It is compatible with the 0.0.7 public authoring surface: there is no new annotation, DSL, command-line option, or verifyAll API.

See every enabled safeguard's result

After CONTRACT_INTEGRITY=PASS, toppleCatVerify runs public acceptance, Hidden Tests, Property-Based Testing, and Mutation Testing in that fixed order. A completed gate that finds a problem records FAIL and does not stop later enabled gates. Expected Consumption, evidence, reviewer/public reports, safe feedback, and reviewer-source rehide complete before Gradle returns the aggregate result.

INCOMPLETE remains distinct from FAIL: it means a producer was interrupted or current-run evidence is missing or malformed. Verify clears the configured mutation report before its producer runs, so stale evidence cannot become current evidence.

Reuse the existing Mechanical Seal

Verify checks the existing Mechanical Seal and reviewer custody without updating approval. If the seal is absent, it safely reports CONTRACT_INTEGRITY=INCOMPLETE and directs the reviewer to run toppleCatSeal; only toppleCatSeal and toppleCatReseal create or replace approval.

Write expected-value checks that can all run

Prefer one c.verify("receipt", receipt) for a full receipt projection. When separate expected keys are necessary, put their verify calls in JUnit assertAll. A failed verify is still ASSERTED; a later value not reached remains UNTOUCHED.

Upgrade

Update the plugin and JUnit dependency to 0.0.8. Existing seals use the 0.0.8 policy/version format; after upgrading, restore reviewer custody, Check, Review, and Reseal before Verify.

Requirements

Java 25 and the existing compatible Gradle requirement are unchanged.

0.0.8 讓每一個已啟用的獨立防線都留下同一次正式執行的誠實結果。它與 0.0.7 的公開
撰寫介面相容：沒有新增 annotation、DSL、命令列選項或 verifyAll API。

看見每道已啟用防線的結果

當 CONTRACT_INTEGRITY=PASS 後，toppleCatVerify 依固定順序執行公開驗收、隱藏測試、
性質導向測試與突變測試。已完整執行且發現問題的 Gate 會記錄為 FAIL，不會阻擋後續
已啟用 Gate。Expected Consumption、evidence、審閱者／公開報告、安全回饋與重新隱藏
審閱者原始碼都完成後，Gradle 才回傳唯一的整體 FAIL 或 INCOMPLETE。

INCOMPLETE 與 FAIL 的意義仍不同：它表示 producer 被中斷，或本次執行證據缺失、
損壞。Verify 會在 mutation producer 開始前清除設定的報告，所以舊報告不能變成本次證據；
即使 consumer-owned producer 被 Gradle 跳過也是如此。Verify 也會在 Integrity 比較既有 seal 前
重建已檢查的 definition，並在開始前捨棄未封存的 run workspace。Property 回饋會區分反例與 task／證據中斷；Mutation 回饋會區分存活 mutant 與 producer
證據缺失或損壞。

沿用既有 Mechanical Seal

Verify 現在會在內部檢查既有的 Mechanical Seal 與 reviewer custody，並記錄沿用 seal、
沒有更新 approval。沒有 seal 時，Verify 會安全記錄
CONTRACT_INTEGRITY=INCOMPLETE，並提示 reviewer 先執行 toppleCatSeal；只有
toppleCatSeal 與 toppleCatReseal 能建立或取代 approval。

撰寫能全部執行的預期值驗證

完整收據投影優先使用一次 c.verify("receipt", receipt)。必須驗證多個獨立 expected key
時，請把各個 verify 放在 JUnit assertAll。失敗的 verify 仍是 ASSERTED；若前一個
assertion 擲出例外，後面未呼叫的值仍是 UNTOUCHED。因此 JUnit 與 Expected Consumption
同時失敗可能各自提供有用證據，不是重複回報。

升級

將 plugin 與 JUnit dependency 更新為 0.0.8。既有 seal 使用目前限定的 0.0.8
policy/version 格式；更新 ToppleCat 座標後，先 Restore reviewer custody，再 Check、Review、
Reseal，最後才 Verify。

環境需求

Java 25 與既有相容 Gradle 的需求沒有改變。

0.0.7

ToppleCat 0.0.7

ToppleCat 0.0.7 replaces the earlier runtime-oriented acceptance API with one compiled ToppleScenario contract, and adds opt-in property-based verification.

⚠️ Breaking changes

Upgrade projects to the new acceptance-test shape:

• Replace @ToppleTest with @ToppleAcceptanceTest.
• Acceptance methods now receive ToppleCase, ToppleScenario, and a concrete ToppleStage.
• Express setup and assertions directly through scenario.given(...), scenario.when(...), scenario.then(...), and scenario.and(...).
• Replace field-based state transfer and fluent helpers. The old stage-field/state annotations, recorded/self helpers, sentence API, aliases, and runtime scenario processor are removed.
• ToppleStage implementations must be non-final concrete classes with an accessible no-argument constructor.
• Rename reviewer-custody tasks:
  • toppleCatHide → toppleCatSeal
  • toppleCatUpdateEscrow → toppleCatReseal
  • toppleCatMigrateEscrow has been removed.
• Use --all-hidden-tests in place of --all-hidden.

This release deliberately does not migrate or read pre-0.0.7 reviewer custody. Create new 0.0.7 reviewer state and seal it after upgrading.

What’s new

• A single compiled acceptance contract based on ToppleScenario, with compiler-described Given/When/Then/And steps.
• Opt-in property-based testing through @ToppleProperty, PropertyTrials, and bounded generators.
• An independent PROPERTY verification gate. Property checks fail safely and remain NOT_APPLICABLE when the safeguard is enabled but no properties are declared.
• Reviewer custody now seals typed hidden-test rows; reviewer-only Java tests are no longer verification evidence.
• Public evidence, feedback, and HTML reports align with the compiled contract while continuing to exclude reviewer-only details.
• Updated documentation, samples, website, and Codex skills for authoring acceptance contracts and preparing releases.

Upgrade checklist

1. Upgrade both the Gradle plugin and topplecat-junit dependency to 0.0.7.
2. Rewrite acceptance methods and stages for the ToppleScenario API.
3. Update renamed tasks and the hidden-test command-line option in scripts or CI.
4. Recreate reviewer custody by running the normal review flow and toppleCatSeal.
5. Run ./gradlew check and toppleCatVerify to confirm the complete contract verdict.

Requirements

ToppleCat 0.0.7 supports Java 25, Gradle, and JUnit 6.1.1.

=============================================

ToppleCat 0.0.7 以單一編譯後的 ToppleScenario 合約取代舊有的執行期驗收 API，並新增可選用的性質導向驗證。

⚠️ 破壞性變更

請將專案升級為新的驗收測試形式：

• 將 @ToppleTest 改為 @ToppleAcceptanceTest。
• 驗收方法現在會接收 ToppleCase、ToppleScenario 與具體的 ToppleStage。
• 直接使用 scenario.given(...)、scenario.when(...)、scenario.then(...) 與 scenario.and(...) 描述設定與斷言。
• 請取代欄位式狀態傳遞與 fluent helper。舊有的 stage 欄位／狀態註解、recorded/self helper、sentence API、別名與執行期 scenario processor 均已移除。
• ToppleStage 實作必須是非 final 的具體類別，並提供可存取的無參數建構子。
• 重新命名 reviewer custody 任務：
  • toppleCatHide → toppleCatSeal
  • toppleCatUpdateEscrow → toppleCatReseal
  • 已移除 toppleCatMigrateEscrow。
• 請以 --all-hidden-tests 取代 --all-hidden。

本版刻意不遷移或讀取 0.0.7 以前的 reviewer custody。升級後請建立新的 0.0.7 reviewer state，再完成 seal。

新功能

• 以 ToppleScenario 為基礎的單一編譯驗收合約，並由編譯器描述 Given/When/Then/And 步驟。
• 透過 @ToppleProperty、PropertyTrials 與有界 generator 提供可選用的性質導向測試。
• 獨立的 PROPERTY 驗證 gate。性質檢查會安全失敗；若 safeguard 已啟用但未宣告 property，則維持 NOT_APPLICABLE。
• Reviewer custody 現在 seal 的是 typed hidden-test rows；reviewer-only Java tests 不再是驗證證據。
• 公開 evidence、feedback 與 HTML report 會對齊編譯後合約，同時持續排除 reviewer-only 資訊。
• 文件、範例、網站與 Codex skills 均已更新，以支援新的驗收合約撰寫與 release 準備流程。

升級清單

1. 將 Gradle plugin 與 topplecat-junit dependency 一併升級至 0.0.7。
2. 將驗收方法與 stage 改寫為 ToppleScenario API。
3. 更新腳本或 CI 中重新命名的任務與 hidden-test 命令列選項。
4. 依正常 review 流程重新建立 reviewer custody，並執行 toppleCatSeal。
5. 執行 ./gradlew check 與 toppleCatVerify，確認完整合約 verdict。

環境需求

ToppleCat 0.0.7 支援 Java 25、Gradle 與 JUnit 6.1.1。

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 their AC-... 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.md

Repeat --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.md

Omit --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 格式。

延伸閱讀

• 選定並封存本次交付
• 撰寫可執行驗收條件
• 排查合約完整性失敗
• 完整設計紀錄

ToppleCat 0.0.5

ToppleCat 0.0.5

Review the contract more easily before handoff, and try the samples directly
from a fresh checkout.

Why upgrade

• The reviewer contract page now puts each acceptance condition beside the
  exact canonical test method that JUnit will execute. Public examples appear
  first; independent reviewer-only checks are clearly labelled. The page also
  has stronger contrast for practical review sessions.
• The JUnit and Spring Boot samples can now be tried from their own directories
  with ./gradlew. Normal interactive use resolves the released package; the
  repository demos use Maven Local only when they deliberately test the source
  checkout.
• The new FAQ explains the Java/JUnit contract approach, why ToppleCat does not
  require Cucumber or .feature files, and how PIT, BDD, and JGiven relate to
  the project.

Upgrade

Most projects only need to update the plugin and topplecat-junit dependency
to 0.0.5.

id("io.github.samzhu.topplecat") version "0.0.5"

Compatibility

No user-visible breaking changes. Existing contracts, reviewer custody, and
verification gates keep their behavior.

Learn more

• Verification and evidence guide
• Runnable samples
• FAQ: why no Cucumber or .feature files?

ToppleCat 0.0.5

交付前更容易確認真正會執行的合約，也能從剛 clone 下來的 sample 直接開始試用。

為什麼值得升級

• 審閱合約頁現在會把每個驗收條件放在真正會由 JUnit 執行的主要測試方法旁邊。
  公開案例先出現，獨立設計的審閱者專用檢查會清楚標示；畫面的對比也提高了，
  看報告比較不吃力。
• JUnit 與 Spring Boot 的 sample 現在可以直接在各自目錄執行 ./gradlew。
  一般互動試用會使用正式發佈的套件；只有要驗證這個原始碼工作副本的 demo 才會
  使用 Maven Local。
• 新增的常見問題整理了 Java/JUnit 合約的做法、為什麼 ToppleCat 不需要
  Cucumber 或 .feature，以及 PIT、BDD 和 JGiven 與本專案的關係。

升級方式

大多數專案只要把 Gradle 外掛與 topplecat-junit 的版本更新成 0.0.5。

id("io.github.samzhu.topplecat") version "0.0.5"

相容性

沒有使用者可見的破壞性變更。既有合約、審閱者保管流程與驗證關卡的行為都維持不變。

延伸閱讀

• 驗證與證據說明
• 可直接執行的 sample
• 常見問題：為什麼不用 Cucumber 或 .feature？

ToppleCat 0.0.4

ToppleCat 0.0.4

Release: 0.0.4 · 2026-07-27

ToppleCat 0.0.4 fixes a misleading mutation result: PIT could finish without
running the public acceptance test that defines an AC. The build looked
successful, but the mutation score had not checked the contract you cared
about.

Mutation must exercise the acceptance contract

ToppleCat now checks that PIT actually ran every required public canonical
@ToppleTest. This also works when production code and acceptance tests use
different Java packages.

The mutation result is now:

• PASS when the required acceptance tests ran and killed the required mutants;
• FAIL when PIT produced a usable report but skipped a required canonical
  test; or
• INCOMPLETE when PIT produced no usable current-run report.

Old mutation artifacts cannot fill a missing result. Safe agent feedback says
that public acceptance coverage is missing without revealing reviewer test
names, paths, or failures.

ToppleCat finds the canonical tests from compiler-generated contract
descriptors. This is an implementation detail; most projects do not need new
configuration.

Reviewer rows no longer need a placeholder Java test

A reviewer can keep independent JSON or YAML cases under src/hiddenTest and
run them through the public canonical @ToppleTest. A Java helper without an
executable JUnit method no longer prevents this rows-only retest.

If reviewer rows and hidden Java tests both exist, both must pass. If neither
exists while hidden retest is enabled, REVIEWER_JUNIT remains INCOMPLETE
instead of becoming an empty pass.

Do I need to change anything?

Most projects do not.

If your build sets PIT targetTests, ToppleCat keeps that setting. Make sure it
includes every public canonical acceptance test. A usable report that skips one
now fails the mutation gate.

Custom mutation producers still control their own targeting and report output.
They must produce a usable current-run report or the gate is INCOMPLETE. The
first mutation run after upgrading may take longer while ToppleCat builds the
contract descriptors and PIT matrix.

What the mutation score covers

The default mutation score measures the strength of the public executable
contract. Reviewer rows and hidden Java tests are separate hidden-retest
evidence; they do not raise the public PIT score.

ToppleCat 0.0.4

發佈版本：0.0.4 · 2026-07-27

ToppleCat 0.0.4 修正一種容易誤判的突變測試結果：PIT 雖然執行完成，卻可能
根本沒跑到某個 AC 對應的公開驗收測試。畫面看起來是綠燈，突變分數其實
沒有檢查你在意的合約。

突變測試必須真的跑到驗收合約

ToppleCat 現在會確認 PIT 是否執行了每一個必要的公開主要 @ToppleTest。
即使正式程式與驗收測試放在不同的 Java 套件，也能正確對應。

突變測試結果會明確分成：

• 必要驗收測試有執行，而且結果符合設定的突變測試要求：PASS；
• PIT 報告可用，但漏掉必要的主要驗收測試：FAIL；
• 當次沒有產生可用的 PIT 報告：INCOMPLETE。

舊的突變測試產物不能拿來補上這次缺少的結果。給代理的安全回饋只會說
公開驗收測試涵蓋不足，不會透露審閱者測試的名稱、路徑或原始錯誤。

ToppleCat 會從編譯器產生的合約描述檔找出主要驗收測試。多數專案不需要
為此新增設定。

審閱案例不再需要空的 Java 測試

審閱者可以只在 src/hiddenTest 放獨立設計的 JSON 或 YAML 案例，再用
公開的主要 @ToppleTest 執行。只有輔助類別、沒有可執行 JUnit 方法的
Java 原始碼，不會阻擋只有案例資料列的隱藏重測。

審閱者案例與隱藏 Java 測試同時存在時，兩邊都必須通過。如果兩者都沒有，
但隱藏案例重測仍處於啟用狀態，REVIEWER_JUNIT 會維持
INCOMPLETE，不會因為沒有測試而自動通過。

升級後需要改設定嗎？

大多數專案不用。

如果 Gradle 建置已設定 PIT targetTests，ToppleCat 會保留原設定。請確認
它包含所有公開的主要驗收測試；只要可用的報告漏掉其中一個，突變測試關卡
現在就會失敗。

自訂的突變測試執行方式，仍由專案自行管理測試目標與報告。這次執行沒有
產生可用報告時，該關卡會是 INCOMPLETE。升級後第一次執行突變測試可能
會比較久，因為 ToppleCat 需要建立合約描述檔與 PIT 執行資料。

突變分數算的是什麼

預設的突變分數衡量公開可執行合約的強度。審閱者案例與隱藏 Java 測試是
另一組隱藏案例重測證據，不會提高公開合約的 PIT 突變分數。