LE0-Lin · Oct 23, 2026 · Oct 23, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,11 +2,17 @@
 
 ## Unreleased
 
+## v0.24.0
+
+A maintainer-focused Beta release: actionable findings, opt-in safeguard review,
+scoped CI setup, source identity and more conservative path/regression handling.
+See the [release notes](docs/releases/v0.24.0.md) for upgrade and compatibility details.
+
 ### Added
 
 - `init --workflow-only` generates/upgrades only the selected CI workflow without reading, creating or resetting repository policy, including under `--force`. Scope and unchanged generated `@v0` Action revision are disclosed; workflow-only setup does not certify policy validity or update remote refs. English/Simplified/Traditional guidance and installed-wheel acceptance cover preservation and explicit workflow replacement.
-- Opt-in `--explain` next steps for active scan/new regression findings in text/Markdown, detailed text rule help, an unscored best-practice checklist and a maintainer workflow guide. JSON, rule metadata, scoring, suppressions and exit policy are unchanged; guidance is static review advice, not new detection coverage or automatic repair. Source Action summaries include next steps.
-- `init --pr-comment` generates the existing tested single-comment workflow without needing the source checkout. Dry-run discloses `pull-requests: write`; the default generated workflow keeps read-only GitHub permissions, conflicting files are not silently replaced, fork comments are skipped and initialization makes no API calls. The generated Action ref remains `v0`, not a promise that published artifacts contain these source-only flags.
+- Opt-in `--explain` next steps for active scan/new regression findings in text/Markdown, detailed text rule help, an unscored best-practice checklist and a maintainer workflow guide. JSON, rule metadata, scoring, suppressions and exit policy are unchanged; guidance is static review advice, not new detection coverage or automatic repair. Action summaries include next steps.
+- `init --pr-comment` generates the existing tested single-comment workflow without needing the source checkout. Dry-run discloses `pull-requests: write`; the default generated workflow keeps read-only GitHub permissions, conflicting files are not silently replaced, fork comments are skipped and initialization makes no API calls. The generated Action ref remains rolling `v0`; review/pin it independently of the installed CLI.
 - An opt-in `guardrails` command for unscored selected-file deletion-safeguard review, line/kind evidence, read-only addition preview and explicit content-bound append confirmation. English/Simplified/Traditional addition templates do not change CLI localization, existing rule scores or CI defaults. Missing recognized wording is review-needed, not unsafe; aliases, hard links and ambiguous markup require manual merging. Appends preserve original bytes but are not atomic against concurrent edits or partial write failures.
 - Capture the declared tool version and a best-effort, LF-normalized SHA-256 of the explicit runtime Python-source manifest in new scan JSON, HTML, SARIF, history snapshots and privacy-minimized feedback; compare/diff retains both identities. Unknown source never becomes a partial digest or blocks linting; legacy reports are not relabelled. This identifies installed source, not executing bytecode, private inputs, accuracy or reproducibility by itself. Frozen research evidence and published v0.23.0 artifacts remain unchanged.
 - Optional Simplified/Traditional Chinese repository overviews, core user guides and limitation summaries, with reciprocal language links and an explicit source-revision/coverage note. Advanced references remain English; CLI messages, JSON fields, rule semantics and the published v0.23.0 distributions are unchanged.
@@ -22,7 +28,7 @@
 ### Fixed
 
 - Preflight selected initialization targets and their parents for aliases/reparse points, shared/unknown files and non-file targets before reading or writing. Use exclusive creation and check opened file identity/link count before explicit truncation; preserve regular-file permissions and avoid raw target I/O exception details. This is not an atomic multi-file transaction or hostile-filesystem sandbox; failures may leave partial selected targets and no rollback is attempted.
-- Keep explicitly labeled example sections out of opt-in guardrail recognition and require manual merging for an example section still open at EOF. Decline policy interpretation in HTML-like layouts instead of recognizing an example as active protection. Narrow approval-bypass directives now produce line/kind-only review signals and prevent automatic append, even alongside a recognized constraint; no general semantic-conflict, scoring or published-package change is implied.
+- Keep explicitly labeled example sections out of opt-in guardrail recognition and require manual merging for an example section still open at EOF. Decline policy interpretation in HTML-like layouts instead of recognizing an example as active protection. Narrow approval-bypass directives now produce line/kind-only review signals and prevent automatic append, even alongside a recognized constraint; no general semantic-conflict detection or scoring change is implied.
 - Reuse each scan's captured instruction text for regression-only checks instead of reopening source paths and silently skipping I/O failures. Later text/link replacement or deletion cannot rewrite those captured instructions, and raw text is not attached to public reports. Initial safety/read failures still stop the check; this is not an atomic snapshot or concurrent-change detector.
 - Restrict instruction-removal move exemptions to one-to-one, nonempty exact decoded-text matches at newly added supported files in the same directory. Existing copies, cross-directory moves and whitespace folding no longer hide a removal. Keep numeric scoring, rule IDs, baseline suppressions and policy defaults unchanged; equivalent agent behavior is not certified.
 - Validate selected instruction files and `.agentconfigscoreignore` as in-repository regular files before opening contents, and revalidate instruction sources at read time. Internal file aliases keep their discovered scopes/locations; child directory symlinks and Windows junctions are not traversed. Preserve ignore-glob meaning while pruning excluded trees before descent.

diff --git a/CITATION.cff b/CITATION.cff
@@ -2,8 +2,8 @@ cff-version: 1.2.0
 message: "If you use AgentConfigScore in research, please cite this software."
 title: "AgentConfigScore: deterministic lint and regression checks for AI coding-agent instructions"
 type: software
-version: 0.23.0
-date-released: 2026-10-07
+version: 0.24.0
+date-released: 2026-10-23
 authors:
   - family-names: Lin
     given-names: Zhibo

diff --git a/README.md b/README.md
@@ -97,12 +97,12 @@ agent-config-score init --force        # intentionally replace conflicting gener
 
 ## Copy-ready templates
 
-Unreleased source builds also provide an optional [deletion-safeguard review and
+v0.24.0+ provides an optional [deletion-safeguard review and
 completion workflow](https://github.com/LE0-Lin/AgentConfigScore/blob/main/docs/guardrail-suggestions.md):
 preview a selected file with `agent-config-score guardrails . --file AGENTS.md`,
 review the proposed addition, then explicitly confirm it before an append.
 This is unscored advice, not proof of danger or safety; it does not change the
-published v0.23.0 package or default regression gate.
+default regression gate.
 
 Start with a conservative template, then replace generic guidance with your
 repository's real commands, architecture, and ownership boundaries:
@@ -362,10 +362,11 @@ It updates one bot-owned comment per PR and links to the detailed report.
 See the [integration guide](https://github.com/LE0-Lin/AgentConfigScore/blob/main/docs/pr-comments.md)
 for fork behavior and permissions.
 
-Unreleased source builds add `init --pr-comment` for opt-in setup and `--explain`
+v0.24.0+ adds `init --pr-comment` for opt-in setup and `--explain`
 for rule-specific next steps. See the [maintainer workflow](https://github.com/LE0-Lin/AgentConfigScore/blob/main/docs/maintainer-workflow.md)
 and [unscored best-practice checklist](https://github.com/LE0-Lin/AgentConfigScore/blob/main/docs/best-practices.md).
-Published v0.23.0 artifacts are unchanged; the default generated workflow keeps read-only GitHub permissions.
+Use `init --workflow-only` when updating only CI without resetting custom policy.
+Preview and review replacements first; the default generated workflow keeps read-only GitHub permissions.
 
 Without a policy file, the Action preserves its conservative compatibility defaults: `max_drop = 0` and `fail_on_new_errors = true`.
 

diff --git a/README.simplified.md b/README.simplified.md
@@ -90,10 +90,10 @@ jobs:
       - uses: actions/checkout@v7
         with:
           fetch-depth: 0
-      - uses: LE0-Lin/AgentConfigScore@v0.23.0
+      - uses: LE0-Lin/AgentConfigScore@v0.24.0
 ```
 
-固定 `@v0.23.0` 有利于复现；`@v0` 是会随后续版本更新的滚动引用。PR 评论属于[可选集成（英文）](docs/pr-comments.md)，扫描器默认不替你发评论。
+固定 `@v0.24.0` 有利于复现；`@v0` 是会随后续版本更新的滚动引用。PR 评论属于[可选集成（英文）](docs/pr-comments.md)，扫描器默认不替你发评论。
 
 ## 支持的指令文件
 
@@ -109,4 +109,4 @@ jobs:
 
 本页是核心入门的中文概览，不是完整英文 README 的逐行翻译。使用指南和限制说明已提供中文；高级 Action 参数、规则语法细节、贡献及研究文档目前仍为英文。[翻译范围与维护说明](docs/translations.md)。命令、终端消息和 JSON 协议保持原样，English 仍是默认入口。
 
-项目采用 [MIT 协议](LICENSE)。[发布与升级说明](docs/releases/v0.23.0.md)目前为英文。
+项目采用 [MIT 协议](LICENSE)。[发布与升级说明](docs/releases/v0.24.0.md)目前为英文。
diff --git a/README.traditional.md b/README.traditional.md
@@ -90,10 +90,10 @@ jobs:
       - uses: actions/checkout@v7
         with:
           fetch-depth: 0
-      - uses: LE0-Lin/AgentConfigScore@v0.23.0
+      - uses: LE0-Lin/AgentConfigScore@v0.24.0
 ```
 
-固定使用 `@v0.23.0` 較容易重現；`@v0` 是會隨後續版本更新的滾動參照。PR 留言是[選用整合（英文）](docs/pr-comments.md)，檢查工具預設不會替你留言。
+固定使用 `@v0.24.0` 較容易重現；`@v0` 是會隨後續版本更新的滾動參照。PR 留言是[選用整合（英文）](docs/pr-comments.md)，檢查工具預設不會替你留言。
 
 ## 支援的指令檔
 
@@ -109,4 +109,4 @@ jobs:
 
 本頁是核心入門的中文概覽，不是完整英文 README 的逐行翻譯。使用指南與限制說明已提供中文；進階 Action 參數、規則語法細節、貢獻和研究文件目前仍為英文。[翻譯範圍與維護說明](docs/translations.md)。命令、終端機訊息和 JSON 協定維持原樣，English 仍為預設入口。
 
-專案採用 [MIT 授權](LICENSE)。[發布與升級說明](docs/releases/v0.23.0.md)目前為英文。
+專案採用 [MIT 授權](LICENSE)。[發布與升級說明](docs/releases/v0.24.0.md)目前為英文。
diff --git a/docs/README.md b/docs/README.md
@@ -8,15 +8,15 @@ read the result, and troubleshoot a failing gate.
 ## Using the tool
 
 - [User guide and exit codes](user-guide.md)
-- [Maintainer setup, actionable next steps and PR results](maintainer-workflow.md) (new setup/explanations unreleased)
+- [Maintainer setup, actionable next steps and PR results](maintainer-workflow.md) (v0.24.0+)
 - [Unscored instruction-file best-practice checklist](best-practices.md)
 - [Visual tour](visual-tour.md)
 - [Instruction templates](../examples/README.md)
-- [Opt-in deletion safeguard review and completion](guardrail-suggestions.md) (unreleased)
+- [Opt-in deletion safeguard review and completion](guardrail-suggestions.md) (v0.24.0+)
 - [Repository doctor](doctor.md)
 - [Optional PR comments](pr-comments.md)
 - [Score-history workflow](score-history.md) and [local history command](score-history-cli.md)
-- [Report tool identity and source fingerprints](report-identity.md) (unreleased)
+- [Report tool identity and source fingerprints](report-identity.md) (v0.24.0+)
 - [Policy and suppression schema](../schema/agentconfigscore.schema.json)
 
 ## Understanding findings

diff --git a/docs/guardrail-suggestions.md b/docs/guardrail-suggestions.md
@@ -1,7 +1,7 @@
 # Opt-in deletion safeguard review and completion
 
-This is an **unreleased source feature** after v0.23.0. Existing PyPI packages,
-release tags and rolling Action refs have not been replaced.
+Available in **v0.24.0+**. This command is opt-in and separate from the default
+scan and regression gate; upgrading alone does not modify instruction files.
 
 `guardrails` asks a different question from lint scoring: **does this selected
 file contain a narrowly recognized deletion-related constraint, and would a

diff --git a/docs/limitations.md b/docs/limitations.md
@@ -10,7 +10,7 @@ a task, or whether an instruction file is generally “good.”
 **An A 100 result means that no active deterministic rule matched. It is not a
 semantic quality certification.**
 
-Unreleased source builds include [tool source identity](report-identity.md) to
+v0.24.0+ includes [tool source identity](report-identity.md) to
 distinguish implementations that declare the same version. A matching digest is
 not an accuracy result or a reproducibility guarantee: repository inputs, policy,
 runtime and filesystem behavior are outside that fingerprint. Missing source is
@@ -180,14 +180,14 @@ scanner against empty, misleading, and deliberately weakened instructions.
 | Candidate deletes an instruction file | Could report no regression | `instruction-file-removed` error |
 | Candidate changes `Always X` to `Never X` | Could report no regression | `directive-polarity-flip` error |
 
-Each hardened case has an automated regression test. In unreleased source builds,
+Each hardened case has an automated regression test. In v0.24.0+,
 only one-to-one, nonempty exact decoded-text moves to newly added supported files
 in the same directory are exempt from removal. Existing copies, cross-directory
 moves and whitespace-folded lookalikes are not exemptions. This does not certify
 equivalent agent/format/scope behavior. Baseline-owned suppressions can document
 an intentional exception. See [regression coverage](regression-coverage.md).
 
-Unreleased comparisons also reuse each scan's captured instruction text rather
+v0.24.0+ comparisons also reuse each scan's captured instruction text rather
 than reopening sources and silently skipping second-read failures. Initial read
 failures still stop the check; raw captured text is not retained in public report
 objects or exports. This is not an atomic snapshot or concurrent-change detector.
@@ -197,20 +197,20 @@ The bare CLI's score-only compatibility default is unchanged.
 
 ## Known blind spots
 
-Unreleased `--explain` output and the [maintainer checklist](best-practices.md)
+v0.24.0+ `--explain` output and the [maintainer checklist](best-practices.md)
 give static review guidance, not new detection coverage or an automatic fix.
 They do not execute referenced commands, infer replacement paths, change score
 arithmetic or certify safety. Optional `init --pr-comment` generates a workflow
 with explicit write permissions; it posts nothing itself and keeps the default
 generated workflow's GitHub permissions read-only. See the [maintainer workflow](maintainer-workflow.md).
-Source-only `init --workflow-only` leaves policy outside its read/write scope,
+v0.24.0+ `init --workflow-only` leaves policy outside its read/write scope,
 including under `--force`; it does not validate that policy. Selected linked,
 reparse, shared or non-file initialization targets require manual setup. Exclusive
 creation and opened-file checks reduce accidental writes, not all filesystem
 races; initialization is not an atomic transaction and failed writes may leave
 partial selected targets. Generated `@v0` is not necessarily the local CLI source.
 
-The optional, unreleased [guardrail completion command](guardrail-suggestions.md)
+The optional v0.24.0+ [guardrail completion command](guardrail-suggestions.md)
 does not add keyword-based quality points. It checks only narrow deletion-policy
 phrases in one selected file, offers a preview and requires content-bound
 confirmation to append. Unrecognized text is review-needed, not proof of missing

diff --git a/docs/maintainer-workflow.md b/docs/maintainer-workflow.md
@@ -1,11 +1,9 @@
 # Maintainer workflow: findings, next steps and one PR comment
 
-`--explain` and `init --pr-comment` are **unreleased source features** after
-v0.23.0. The current PyPI package, release tags and rolling `v0` Action have not
-been updated. Commands below require a source build containing these changes.
-The existing [copy-ready comment recipe](../examples/pr-comment.yml) also works
-with the published Action, but that version's job summary has no new next-step
-guidance. Generating a workflow does not change which Action revision it uses.
+`--explain`, `init --pr-comment` and `init --workflow-only` are available in
+**v0.24.0+**. The [copy-ready comment recipe](../examples/pr-comment.yml) remains
+an alternative setup method. Upgrade the installed CLI and review the Action
+revision independently: generating a workflow does not update remote refs.
 
 ## 1. Inspect concrete problems locally
 
@@ -39,7 +37,7 @@ The baseline policy and suppressions still govern the comparison. Guidance is
 attached only to new findings, so unchanged historical findings do not become
 new fix requests on every PR. Review accepted exceptions separately.
 
-The Action in this source revision requests explanatory Markdown in its job
+The v0.24.0+ Action requests explanatory Markdown in its job
 summary automatically. It does not publish a comment unless a caller workflow
 opts in. Generated comments contain validated numeric results and a link to
 details, not raw instruction text or arbitrary finding messages.
@@ -73,7 +71,7 @@ comment recipe. See [PR comment security and behavior](pr-comments.md).
 
 ### Upgrade a workflow without resetting repository policy
 
-Unreleased source builds also accept `--workflow-only`. The selected targets are:
+v0.24.0+ also accepts `--workflow-only`. The selected targets are:
 
 | Mode | Policy file | Workflow file |
 |---|---|---|
@@ -104,8 +102,8 @@ targets; use workflow-only mode when that is not what you intend.
 
 The generated workflow currently uses the existing rolling `v0` Action ref.
 Review/pin the tested revision suitable for your repository before committing;
-the new source-only explanatory summaries require an Action revision containing
-this change. Keep scanning dependencies separate from candidate repository code.
+explanatory summaries require v0.24.0+ (or a verified revision containing
+that feature). Keep scanning dependencies separate from candidate repository code.
 CLI output also discloses this Action ref instead of implying it matches the
 installed CLI source. Initialization does not fetch, verify or update remote refs.
 

diff --git a/docs/pr-comments.md b/docs/pr-comments.md
@@ -1,17 +1,17 @@
 # Post results as one pull request comment
 
-Unreleased source builds can generate the same recipe with
+v0.24.0+ can generate the same recipe with
 `agent-config-score init --pr-comment --dry-run`, then
-`agent-config-score init --pr-comment` after review. The published v0.23.0 CLI
+`agent-config-score init --pr-comment` after review. The v0.23.0 CLI
 does not have this flag. It generates `.github/workflows/agent-config-score.yml`;
 choose **one** setup method rather than installing both workflows. Existing
 files are not silently overwritten, and default `init` generates a workflow with
 read-only GitHub permissions.
 See the [maintainer workflow](maintainer-workflow.md) for revision and permission
 details, and for optional rule-specific next steps in detailed summaries.
 
-To upgrade only CI while retaining an existing custom policy, source builds
-support `init --workflow-only --pr-comment --force --dry-run`, followed by the
+To upgrade only CI while retaining an existing custom policy, v0.24.0+
+supports `init --workflow-only --pr-comment --force --dry-run`, followed by the
 same command without `--dry-run` after reviewing the recipe. `--force` replaces
 only the workflow in this mode, not the policy. It does not merge custom YAML.
 Linked/reparse or shared selected targets require manual integration.