diff --git a/CHANGELOG.md b/CHANGELOG.md index c00fc05..3e53c40 100644 --- 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 index c5d3d20..dff5993 100644 --- 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 index 2609c6e..c6d46ea 100644 --- 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 index b8b4a12..174c8f6 100644 --- 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 index 17e30fa..962501e 100644 --- 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 index 2d3f79a..adec309 100644 --- 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 index e088254..3d5a95f 100644 --- 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 index b9c3663..d128775 100644 --- 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 index df7b380..1cac656 100644 --- 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 index a466e7a..13a598e 100644 --- a/docs/pr-comments.md +++ b/docs/pr-comments.md @@ -1,8 +1,8 @@ # 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 @@ -10,8 +10,8 @@ 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. diff --git a/docs/regression-coverage.md b/docs/regression-coverage.md index 9d2c3e2..8c891ee 100644 --- a/docs/regression-coverage.md +++ b/docs/regression-coverage.md @@ -1,7 +1,7 @@ # Regression input consistency and file-removal checks -The tightened behavior below is an **unreleased source change** after v0.23.0. -Existing PyPI distributions, release tags and Action refs are unchanged. +The tightened behavior below is available in **v0.24.0+**. Review new removal +signals when upgrading from v0.23.0; numeric scoring and policy defaults are unchanged. ## One captured text per selected source diff --git a/docs/release-readiness.md b/docs/release-readiness.md index b0d2842..e100d3a 100644 --- a/docs/release-readiness.md +++ b/docs/release-readiness.md @@ -81,8 +81,10 @@ Rules for the translation stage: - Do not add a CLI `--language` option until terminal-output localization is explicitly in scope and independently tested. Documentation is the first stage. -The repository's core translated pages and selector are included in the -documentation update, not retroactively in the immutable v0.23.0 distributions -or tag. See [translation scope and source revision](translations.md). +v0.24.0 is the first release tag to include the repository's core translated +pages and selector. They remain repository documentation linked by the default +English package README, not localized CLI output or bundled offline wheel docs. +The immutable v0.23.0 distributions/tag are unchanged. See +[translation scope and source revision](translations.md). Real-user feedback and independent evaluation remain separate ongoing work; they are not replaced by localization or release acceptance. diff --git a/docs/releases/v0.24.0.md b/docs/releases/v0.24.0.md new file mode 100644 index 0000000..eb9da3f --- /dev/null +++ b/docs/releases/v0.24.0.md @@ -0,0 +1,103 @@ +# AgentConfigScore v0.24.0 + +This maintainer-focused **Beta** release connects concrete lint findings to +reviewable next steps and opt-in PR results. It also hardens path, input and +initialization handling. It is still a local, dependency-free deterministic +linter and baseline-aware regression gate, not a semantic judge or runtime guard. + +## Install or upgrade + +```bash +python -m pip install --upgrade "agent-config-score==0.24.0" +agent-config-score --version +agent-config-score . --explain +``` + +Expected version: `AgentConfigScore 0.24.0`. Python 3.10+ is required; Git is +needed for `diff`. Both console aliases (`agent-config-score`, `acs`) and +`python -m agent_config_score` remain available. There are no runtime dependencies. + +## What is included + +- `--explain` adds static next steps to active scan/new regression findings in + text and Markdown. Rule help and an unscored maintainer checklist connect + findings to a fix/recheck workflow without executing commands or repairing files. +- `init --pr-comment` generates the tested, opt-in, single bot-comment workflow. + It discloses `pull-requests: write`; default initialization keeps read-only + GitHub permissions. Fork PRs retain job summaries without comments. Setup + itself makes no GitHub API calls. +- `init --workflow-only` leaves custom policy and suppression bytes entirely out + of scope, including under `--force`. Selected-file and parent checks, exclusive + creation and opened-file identity checks reduce accidental overwrites. +- `guardrails` previews narrowly recognized deletion safeguards in one existing + instruction file. A reviewed addition requires explicit content-bound + confirmation to append. English, Simplified and Traditional templates are + available; example sections, ambiguous markup and narrow approval-bypass + signals can require manual merging. This is unscored, opt-in advice. +- New reports capture the declared version and a best-effort tool-source + fingerprint. JSON, HTML, SARIF, new history snapshots and feedback retain it; + comparisons retain both scan identities. Missing source is explicitly unknown. +- Path checks avoid narrowly defined repository-slug/conditional-reference false + positives, retain package paths under build directories and no longer let + explicit relative paths pass via unrelated suffix matches. +- Unsafe/unreadable selected sources and path-index traversal failures stop the + operation instead of silently scoring incomplete input. Comparisons reuse + scan-captured instruction text. File-removal move exemptions are restricted + to one-to-one, nonempty exact decoded-text moves within the same directory. +- Optional [Simplified](https://github.com/LE0-Lin/AgentConfigScore/blob/v0.24.0/README.simplified.md) + and [Traditional](https://github.com/LE0-Lin/AgentConfigScore/blob/v0.24.0/README.traditional.md) + repository overviews, core guides and limitations. Advanced references and CLI + output remain English. The wheel links to, but does not bundle, offline docs. + +## Upgrade existing integrations deliberately + +Pin reproducible CI to `LE0-Lin/AgentConfigScore@v0.24.0` or its verified commit. +Rolling `@v0` follows releases and can change. Upgrading the local package does +not update an existing workflow's pinned Action revision. Newly generated +workflows use rolling `@v0`; inspect/pin it before committing. + +To adopt PR comments without resetting custom policy, compare the recipe with +your existing workflow, then preview before replacing it: + +```bash +agent-config-score init --workflow-only --pr-comment --force --dry-run +agent-config-score init --workflow-only --pr-comment --force +agent-config-score doctor +``` + +`--force` **replaces the selected workflow**, not a YAML merge; do not run it +without reviewing local customizations. Policy is not read or validated in this +mode. Ordinary unscoped `init --force` still replaces both generated targets. +Keep only one scanning/comment workflow. Initialization and guardrail appends +are not atomic transactions: an I/O failure may leave partial changes. Inspect +before retrying; linked/shared targets can require manual integration. + +Existing commands, configuration version 1, stable rule IDs and policy defaults +are unchanged. Report identity is additive; strict JSON consumers must allow +the new metadata. There are no new scored rules in this release, but corrected +path interpretation can change findings/scores. Tighter removal exemptions can +produce new regression-only errors even at `100` on both sides; enable baseline +`fail_on_new_errors` or `--fail-on-new-errors` to gate them. A bare CLI comparison +without policy retains its score-only default. Operational failures return exit +`2`, not a clean result; doctor error checks return `1`. + +## Verification and evidence limits + +The release workflow requires the source regression suite, a wheel/source +distribution build and installed-wheel acceptance on Linux, Windows and macOS +before publication. The installed journey covers the new opt-in commands and +exact policy preservation as well as the existing regression/permission cases. + +Maintained fixtures, synthetic workflows and package acceptance verify specified +engineering behavior, not independent accuracy or real-user adoption. The +unresolved AI pilot and deferred human annotation remain unscored. Development +reuse of public samples is disclosed; frozen research records and older release +artifacts are unchanged. + +An A 100 is not proof of useful or safe instructions. Missing recognized +safeguard text means review needed, not proven danger; adding text does not +increase the score or enforce agent behavior. A source fingerprint is not +execution attestation or a reproducibility guarantee. Read the +[limitations](https://github.com/LE0-Lin/AgentConfigScore/blob/v0.24.0/docs/limitations.md), +[maintainer guide](https://github.com/LE0-Lin/AgentConfigScore/blob/v0.24.0/docs/maintainer-workflow.md) +and [changelog](https://github.com/LE0-Lin/AgentConfigScore/blob/v0.24.0/CHANGELOG.md). diff --git a/docs/report-identity.md b/docs/report-identity.md index b00660a..232ae2e 100644 --- a/docs/report-identity.md +++ b/docs/report-identity.md @@ -1,7 +1,7 @@ # Report tool identity -This is an **unreleased source feature** after v0.23.0. The existing v0.23.0 -PyPI packages, release tag and rolling Action ref have not been replaced. +Available in **v0.24.0+**. Earlier reports and frozen research artifacts are not +retroactively relabelled with the new version or source fingerprint. Package versions alone do not distinguish unreleased checkouts or local patches. New scans capture a `tool` object at the start of `analyze()`, with: diff --git a/docs/simplified/limitations.md b/docs/simplified/limitations.md index ef9438c..2cd6b89 100644 --- a/docs/simplified/limitations.md +++ b/docs/simplified/limitations.md @@ -4,7 +4,7 @@ AgentConfigScore 的分数衡量已经检测到的、由规则定义的风险，不衡量模型智力、任务成功率或指令总体质量。**A 100 表示没有命中生效的确定性规则，不是语义质量或安全认证。** -尚未发布的源码版本提供[工具源码身份（英文）](../report-identity.md)，用于区分声明同一版本号的不同实现。相同指纹不证明准确率或可复现性：仓库输入、策略、运行环境和文件系统行为不在该指纹范围内。工具源码缺失时明确记为未知，历史报告不补标成当前版本。 +v0.24.0+ 提供[工具源码身份（英文）](../report-identity.md)，用于区分声明同一版本号的不同实现。相同指纹不证明准确率或可复现性：仓库输入、策略、运行环境和文件系统行为不在该指纹范围内。工具源码缺失时明确记为未知，历史报告不补标成当前版本。 ## 指令文件的文件系统边界 @@ -71,20 +71,20 @@ AgentConfigScore 的分数衡量已经检测到的、由规则定义的风险， - 没有支持的指令文件会产生 `no-config`；空文件会产生 `empty-instructions`，不会显示 A 等级。 - 生效的错误发现会限制等级，不能仅因数值惩罚较小就显示 A。 - 精确指令形式的矛盾可以检出，改写后的语义矛盾不保证检出。 -- 删除指令文件会产生回归专用的 `instruction-file-removed`；尚未发布的源码版本仅豁免同目录内、一对一匹配、非空且解码文本完全相同的新增文件移动。现存副本、跨目录搬移和折叠空白后才相同的内容不能豁免；不证明不同工具格式、优先级或实际作用域等价。 +- 删除指令文件会产生回归专用的 `instruction-file-removed`；v0.24.0+ 仅豁免同目录内、一对一匹配、非空且解码文本完全相同的新增文件移动。现存副本、跨目录搬移和折叠空白后才相同的内容不能豁免；不证明不同工具格式、优先级或实际作用域等价。 - 相同指令正文的明确极性翻转会产生 `directive-polarity-flip`，不推断任意语义相反的句子。 对应行为有回归测试，基线审核的豁免可记录有意接受的例外。通过测试只证明符合这些已指定的行为。 -尚未发布的对比逻辑复用每次扫描捕获的文本，不再二次读取并跳过读取失败；初次读取失败仍中止检查，原始捕获文本不保留在公开报告对象或导出中。这不是原子快照或并发修改检测，应保持两侧目录稳定，编辑后重跑。回归专用错误不扣数值分；两边 `100` 分仍需通过基线 `fail_on_new_errors` 或 `--fail-on-new-errors` 阻断。裸 CLI 的仅检查降分默认值不变。[完整边界（英文）](../regression-coverage.md)。 +v0.24.0+ 的对比逻辑复用每次扫描捕获的文本，不再二次读取并跳过读取失败；初次读取失败仍中止检查，原始捕获文本不保留在公开报告对象或导出中。这不是原子快照或并发修改检测，应保持两侧目录稳定，编辑后重跑。回归专用错误不扣数值分；两边 `100` 分仍需通过基线 `fail_on_new_errors` 或 `--fail-on-new-errors` 阻断。裸 CLI 的仅检查降分默认值不变。[完整边界（英文）](../regression-coverage.md)。 -尚未发布的[删除保护补全功能（英文）](../guardrail-suggestions.md)是独立的非计分建议，不靠安全关键词加分。它只识别选定文件里的有限句式，不继承其他文件、工具权限或沙箱设置；未识别到不证明缺少保护，识别到也不证明完整或会被执行。默认只读预览，追加必须明确确认，且不是原子事务，写入失败可能留下部分追加片段。现有评分和 CI 门禁不变。 +v0.24.0+ 的[删除保护补全功能（英文）](../guardrail-suggestions.md)是独立的非计分建议，不靠安全关键词加分。它只识别选定文件里的有限句式，不继承其他文件、工具权限或沙箱设置；未识别到不证明缺少保护，识别到也不证明完整或会被执行。默认只读预览，追加必须明确确认，且不是原子事务，写入失败可能留下部分追加片段。现有评分和 CI 门禁不变。 -尚未发布的 `--explain` 和[维护者清单（英文）](../best-practices.md)只给静态审核建议，不增加检测范围、不自动修复，也不执行引用的命令、猜测替代路径或改变评分。可选的 `init --pr-comment` 生成明确带写权限的工作流，本身不发评论；默认生成的工作流仍只申请 GitHub 只读权限。详见[维护者流程（英文）](../maintainer-workflow.md)。 +v0.24.0+ 的 `--explain` 和[维护者清单（英文）](../best-practices.md)只给静态审核建议，不增加检测范围、不自动修复，也不执行引用的命令、猜测替代路径或改变评分。可选的 `init --pr-comment` 生成明确带写权限的工作流，本身不发评论；默认生成的工作流仍只申请 GitHub 只读权限。详见[维护者流程（英文）](../maintainer-workflow.md)。 明确的示例标题会排除其章节；示例章节延续到文件末尾时须手动合并。HTML 类标签会让整个选定文件停止策略识别。少数跳过删除确认的明确句式，即使与已识别的保护并存，也须先手动处理；这些只是不计分的审核信号，不代表完整的冲突检测或实际代理行为。 -仅源码版的 `init --workflow-only` 将策略排除在读写范围外，即使使用 `--force` 也不会重置策略，但也不会验证策略。初始化选定目标若涉及链接、reparse point、共享文件或非普通文件，须手动接入。独占创建和已打开文件检查减少误写风险，不代表完全消除文件系统竞争；初始化不是原子事务，写入失败可能留下部分文件。生成的 `@v0` 不一定与本地 CLI 源码相同。 +v0.24.0+ 的 `init --workflow-only` 将策略排除在读写范围外，即使使用 `--force` 也不会重置策略，但也不会验证策略。初始化选定目标若涉及链接、reparse point、共享文件或非普通文件，须手动接入。独占创建和已打开文件检查减少误写风险，不代表完全消除文件系统竞争；初始化不是原子事务，写入失败可能留下部分文件。生成的 `@v0` 不一定与本地 CLI 源码相同。 ## 评测尚未证明什么 diff --git a/docs/simplified/user-guide.md b/docs/simplified/user-guide.md index da3bc84..10fafa1 100644 --- a/docs/simplified/user-guide.md +++ b/docs/simplified/user-guide.md @@ -68,7 +68,7 @@ agent-config-score compare ../repo-base . --max-drop 0 --fail-on-new-errors 两侧均使用基线策略和豁免。候选改动不能通过提高自己的降分预算或豁免新错误来批准自己；可信调用方的命令行覆盖必须明确传入。 -尚未发布的源码版本仅豁免同一目录内、一对一匹配、文本完全相同且目标为新增文件的移动；现存副本或把根目录规则搬入子目录不能掩盖删除。对比复用扫描时读取的文本，不再重新打开指令文件；请保持两侧目录稳定，编辑后重新检查。[回归覆盖范围（英文）](../regression-coverage.md)。两边都是 `100` 分仍可能有回归专用错误；上面的示例启用了新错误阻断，没有策略的裸 CLI 默认仍只检查降分。 +v0.24.0+ 仅豁免同一目录内、一对一匹配、文本完全相同且目标为新增文件的移动；现存副本或把根目录规则搬入子目录不能掩盖删除。对比复用扫描时读取的文本，不再重新打开指令文件；请保持两侧目录稳定，编辑后重新检查。[回归覆盖范围（英文）](../regression-coverage.md)。两边都是 `100` 分仍可能有回归专用错误；上面的示例启用了新错误阻断，没有策略的裸 CLI 默认仍只检查降分。 ## 5. 理解失败并处理 @@ -95,7 +95,7 @@ agent-config-score diff --markdown .agent-config-score/regression.md 不要把报告放在会被当成指令文件扫描的位置。JSON、HTML、SARIF 和回归报告可能包含仓库路径及发现信息，分享前先检查。输出路径不要选成源码或策略文件，避免覆盖。多个报告写入不是事务：后一个写入失败时，前一个报告可能已生成。 -尚未发布的源码版本还会在 JSON、HTML、SARIF 和新的历史快照中保留声明版本及尽力读取的工具源码 SHA-256；`compare` / `diff` JSON 分别保留两次扫描的身份。它用于区分同版本号的不同实现，本身不证明准确率或可复现性。工具源码缺失时指纹不可用，但不使扫描失效。覆盖范围、兼容性和环境／输入限制见[报告身份说明（英文）](../report-identity.md)；已发布的 v0.23.0 不变。 +v0.24.0+ 还会在 JSON、HTML、SARIF 和新的历史快照中保留声明版本及尽力读取的工具源码 SHA-256；`compare` / `diff` JSON 分别保留两次扫描的身份。它用于区分同版本号的不同实现，本身不证明准确率或可复现性。工具源码缺失时指纹不可用，但不使扫描失效。覆盖范围、兼容性和环境／输入限制见[报告身份说明（英文）](../report-identity.md)；不会为旧报告补标新的身份。 需要隐私最小化草稿时： @@ -105,7 +105,7 @@ agent-config-score feedback . --output .agent-config-score/case.md 不会上传任何内容。请自行审核、脱敏后再分享。 -## 可选：检查删除保护缺项（尚未发布） +## 可选：检查删除保护缺项（v0.24.0+） ```bash agent-config-score guardrails . --file AGENTS.md @@ -116,7 +116,7 @@ agent-config-score guardrails . --file AGENTS.md --template-language simplified 明确标注的示例章节不算有效策略；如果该章节延续到文件末尾，就不能自动追加。少数明确要求跳过删除确认的句式会产生只含行号与类型的 `review_signals`，即使其他位置已识别到保护，也不能自动追加。请先手动处理这些策略；这不是通用的矛盾检测器。 -## 可选：面向维护者的具体建议（尚未发布） +## 可选：面向维护者的具体建议（v0.24.0+） ```bash agent-config-score . --explain @@ -124,9 +124,9 @@ agent-config-score diff --explain --markdown .agent-config-score/regression.md agent-config-score init --pr-comment --dry-run ``` -`--explain` 在文本／Markdown 中为扫描的有效发现、回归比较的新增发现补充静态处理建议，不改变 JSON、评分或退出策略；不执行命令、不修复文件。[最佳实践清单（英文）](../best-practices.md)也不计分。`init --pr-comment` 显式选择生成同仓库 PR 评论工作流，并提示 `pull-requests: write` 权限；默认 `init` 生成的工作流仍只申请 GitHub 只读权限。先预览、审核，只提交一份工作流；已有冲突须主动审核，不能自动覆盖。Fork PR 保留任务摘要，不发评论。生成的 Action 引用仍为 `v0`，新解释需要包含本次改动的 Action 构建。已发布的 v0.23.0 不含这两个参数。详见[维护者流程（英文）](../maintainer-workflow.md)。 +`--explain` 在文本／Markdown 中为扫描的有效发现、回归比较的新增发现补充静态处理建议，不改变 JSON、评分或退出策略；不执行命令、不修复文件。[最佳实践清单（英文）](../best-practices.md)也不计分。`init --pr-comment` 显式选择生成同仓库 PR 评论工作流，并提示 `pull-requests: write` 权限；默认 `init` 生成的工作流仍只申请 GitHub 只读权限。先预览、审核，只提交一份工作流；已有冲突须主动审核，不能自动覆盖。Fork PR 保留任务摘要，不发评论。生成的 Action 引用仍为 `v0`，解释摘要需要 v0.24.0+ 或包含该功能的已验证 Action 版本。升级本地 CLI 不会改变已有工作流固定的 Action 版本。详见[维护者流程（英文）](../maintainer-workflow.md)。 -仅更新 CI、不读取或重置自定义策略时（仅源码版）： +仅更新 CI、不读取或重置自定义策略时（v0.24.0+）： ```bash agent-config-score init --workflow-only --pr-comment --force --dry-run diff --git a/docs/traditional/limitations.md b/docs/traditional/limitations.md index 40515c5..b9a0b55 100644 --- a/docs/traditional/limitations.md +++ b/docs/traditional/limitations.md @@ -4,7 +4,7 @@ AgentConfigScore 的分數衡量已偵測到、由規則定義的風險，不衡量模型智力、任務成功率或指令整體品質。**A 100 表示沒有命中生效的確定性規則，不是語意品質或安全認證。** -尚未發布的原始碼版本提供[工具原始碼身分（英文）](../report-identity.md)，用來區分宣告同一版本號的不同實作。相同指紋不證明準確率或可重現性：儲存庫輸入、策略、執行環境與檔案系統行為不在該指紋範圍內。工具原始碼缺失時明確記為未知，歷史報告不補標為目前版本。 +v0.24.0+ 提供[工具原始碼身分（英文）](../report-identity.md)，用來區分宣告同一版本號的不同實作。相同指紋不證明準確率或可重現性：儲存庫輸入、策略、執行環境與檔案系統行為不在該指紋範圍內。工具原始碼缺失時明確記為未知，歷史報告不補標為目前版本。 ## 指令檔的檔案系統邊界 @@ -71,20 +71,20 @@ AgentConfigScore 的分數衡量已偵測到、由規則定義的風險，不衡 - 沒有支援的指令檔會產生 `no-config`；空白檔案會產生 `empty-instructions`，不會顯示 A 等級。 - 生效的錯誤發現會限制等級，不會只因數值懲罰較小就顯示 A。 - 可以偵測精確指令形式的矛盾，但不保證識別改寫後的語意矛盾。 -- 刪除指令檔會產生回歸專用的 `instruction-file-removed`；尚未發布的原始碼版本僅豁免同目錄內、一對一配對、非空白且解碼文字完全相同的新增檔案搬移。既有副本、跨目錄搬移及折疊空白後才相同的內容不能豁免；不證明不同工具格式、優先順序或實際作用域等價。 +- 刪除指令檔會產生回歸專用的 `instruction-file-removed`；v0.24.0+ 僅豁免同目錄內、一對一配對、非空白且解碼文字完全相同的新增檔案搬移。既有副本、跨目錄搬移及折疊空白後才相同的內容不能豁免；不證明不同工具格式、優先順序或實際作用域等價。 - 相同指令正文的明確極性翻轉會產生 `directive-polarity-flip`，不推論任意語意相反的句子。 對應行為有回歸測試，基準審查的排除設定可記錄有意接受的例外。測試通過只證明符合這些已指定的行為。 -尚未發布的比較邏輯重用每次掃描擷取的文字，不再二次讀取並略過讀取失敗；初次讀取失敗仍中止檢查，原始擷取文字不保留於公開報告物件或匯出中。這不是原子快照或並行修改偵測，應保持兩側目錄穩定，編輯後重跑。回歸專用錯誤不扣數值分；兩邊 `100` 分仍須透過基準 `fail_on_new_errors` 或 `--fail-on-new-errors` 阻擋。裸 CLI 僅檢查降分的預設值不變。[完整界線（英文）](../regression-coverage.md)。 +v0.24.0+ 的比較邏輯重用每次掃描擷取的文字，不再二次讀取並略過讀取失敗；初次讀取失敗仍中止檢查，原始擷取文字不保留於公開報告物件或匯出中。這不是原子快照或並行修改偵測，應保持兩側目錄穩定，編輯後重跑。回歸專用錯誤不扣數值分；兩邊 `100` 分仍須透過基準 `fail_on_new_errors` 或 `--fail-on-new-errors` 阻擋。裸 CLI 僅檢查降分的預設值不變。[完整界線（英文）](../regression-coverage.md)。 -尚未發布的[刪除保護補全功能（英文）](../guardrail-suggestions.md)是獨立的不計分建議，不靠安全關鍵字加分。它只識別選定檔案中的有限句式，不繼承其他檔案、工具權限或沙箱設定；未識別到不證明缺少保護，識別到也不證明完整或會被執行。預設僅提供唯讀預覽，追加必須明確確認，且不是原子交易，寫入失敗可能留下部分追加片段。既有評分與 CI 檢查不變。 +v0.24.0+ 的[刪除保護補全功能（英文）](../guardrail-suggestions.md)是獨立的不計分建議，不靠安全關鍵字加分。它只識別選定檔案中的有限句式，不繼承其他檔案、工具權限或沙箱設定；未識別到不證明缺少保護，識別到也不證明完整或會被執行。預設僅提供唯讀預覽，追加必須明確確認，且不是原子交易，寫入失敗可能留下部分追加片段。既有評分與 CI 檢查不變。 -尚未發布的 `--explain` 和[維護者清單（英文）](../best-practices.md)只給靜態審閱建議，不增加偵測範圍、不自動修復，也不執行引用的命令、猜測替代路徑或改變評分。選用的 `init --pr-comment` 產生明確帶有寫入權限的工作流程，本身不發評論；預設產生的工作流程仍僅申請 GitHub 唯讀權限。詳見[維護者流程（英文）](../maintainer-workflow.md)。 +v0.24.0+ 的 `--explain` 和[維護者清單（英文）](../best-practices.md)只給靜態審閱建議，不增加偵測範圍、不自動修復，也不執行引用的命令、猜測替代路徑或改變評分。選用的 `init --pr-comment` 產生明確帶有寫入權限的工作流程，本身不發評論；預設產生的工作流程仍僅申請 GitHub 唯讀權限。詳見[維護者流程（英文）](../maintainer-workflow.md)。 明確的範例標題會排除其章節；範例章節延續到檔案末尾時須手動合併。HTML 類標籤會讓整個選定檔案停止策略識別。少數略過刪除確認的明確句式，即使與已識別的保護並存，也須先手動處理；這些只是不計分的審閱訊號，不代表完整的衝突偵測或實際代理行為。 -僅原始碼版的 `init --workflow-only` 將策略排除在讀寫範圍外，即使使用 `--force` 也不會重設策略，但也不會驗證策略。初始化選定目標若涉及連結、reparse point、共用檔案或非一般檔案，須手動整合。獨佔建立與已開啟檔案檢查減少誤寫風險，不代表完全消除檔案系統競爭；初始化不是原子交易，寫入失敗可能留下部分檔案。產生的 `@v0` 不一定與本機 CLI 原始碼相同。 +v0.24.0+ 的 `init --workflow-only` 將策略排除在讀寫範圍外，即使使用 `--force` 也不會重設策略，但也不會驗證策略。初始化選定目標若涉及連結、reparse point、共用檔案或非一般檔案，須手動整合。獨佔建立與已開啟檔案檢查減少誤寫風險，不代表完全消除檔案系統競爭；初始化不是原子交易，寫入失敗可能留下部分檔案。產生的 `@v0` 不一定與本機 CLI 原始碼相同。 ## 評測尚未證明什麼 diff --git a/docs/traditional/user-guide.md b/docs/traditional/user-guide.md index 3bdff40..a57612c 100644 --- a/docs/traditional/user-guide.md +++ b/docs/traditional/user-guide.md @@ -68,7 +68,7 @@ agent-config-score compare ../repo-base . --max-drop 0 --fail-on-new-errors 兩側都套用基準策略與排除設定。候選改動不能藉由增加自己的降分預算或排除新錯誤來核准自身；受信任呼叫端若要覆寫命令列設定，必須明確傳入。 -尚未發布的原始碼版本僅豁免同一目錄內、一對一配對、文字完全相同且目標為新增檔案的搬移；既有副本或把根目錄規則搬入子目錄不能掩蓋刪除。比較重用掃描時讀取的文字，不再重新開啟指令檔；請保持兩側目錄穩定，編輯後重新檢查。[回歸涵蓋範圍（英文）](../regression-coverage.md)。兩邊都是 `100` 分仍可能有回歸專用錯誤；上述範例啟用了新錯誤阻擋，沒有策略的裸 CLI 預設仍只檢查降分。 +v0.24.0+ 僅豁免同一目錄內、一對一配對、文字完全相同且目標為新增檔案的搬移；既有副本或把根目錄規則搬入子目錄不能掩蓋刪除。比較重用掃描時讀取的文字，不再重新開啟指令檔；請保持兩側目錄穩定，編輯後重新檢查。[回歸涵蓋範圍（英文）](../regression-coverage.md)。兩邊都是 `100` 分仍可能有回歸專用錯誤；上述範例啟用了新錯誤阻擋，沒有策略的裸 CLI 預設仍只檢查降分。 ## 5. 理解失敗並處理 @@ -95,7 +95,7 @@ agent-config-score diff --markdown .agent-config-score/regression.md 不要將報告放在會被視為指令檔掃描的位置。JSON、HTML、SARIF 與回歸報告可能包含儲存庫路徑和檢查資訊，分享前請先檢查。輸出路徑不要選擇原始碼或策略檔案，以免覆寫。多份報告寫入不是交易：後一份寫入失敗時，前一份可能已經產生。 -尚未發布的原始碼版本，也會在 JSON、HTML、SARIF 與新的歷史快照中保留宣告版本及盡力讀取的工具原始碼 SHA-256；`compare` / `diff` JSON 分別保留兩次掃描的身分。它用來區分同版本號的不同實作，本身不證明準確率或可重現性。工具原始碼缺失時指紋不可用，但不使掃描失效。涵蓋範圍、相容性及環境／輸入限制見[報告身分說明（英文）](../report-identity.md)；已發布的 v0.23.0 不變。 +v0.24.0+ 也會在 JSON、HTML、SARIF 與新的歷史快照中保留宣告版本及盡力讀取的工具原始碼 SHA-256；`compare` / `diff` JSON 分別保留兩次掃描的身分。它用來區分同版本號的不同實作，本身不證明準確率或可重現性。工具原始碼缺失時指紋不可用，但不使掃描失效。涵蓋範圍、相容性及環境／輸入限制見[報告身分說明（英文）](../report-identity.md)；不會為舊報告補標新的身分。 需要盡量減少私人資訊的草稿時： @@ -105,7 +105,7 @@ agent-config-score feedback . --output .agent-config-score/case.md 不會上傳任何內容。請自行審閱並移除敏感資訊後再分享。 -## 選用：檢查刪除保護缺項（尚未發布） +## 選用：檢查刪除保護缺項（v0.24.0+） ```bash agent-config-score guardrails . --file AGENTS.md @@ -116,7 +116,7 @@ agent-config-score guardrails . --file AGENTS.md --template-language simplified 明確標示的範例章節不算有效策略；如果該章節延續到檔案末尾，就不能自動追加。少數明確要求略過刪除確認的句式會產生只含行號與類型的 `review_signals`，即使其他位置已識別到保護，也不能自動追加。請先手動處理這些策略；這不是通用的矛盾偵測器。 -## 選用：面向維護者的具體建議（尚未發布） +## 選用：面向維護者的具體建議（v0.24.0+） ```bash agent-config-score . --explain @@ -124,9 +124,9 @@ agent-config-score diff --explain --markdown .agent-config-score/regression.md agent-config-score init --pr-comment --dry-run ``` -`--explain` 在文字／Markdown 中為掃描的有效發現、回歸比較的新增發現補充靜態處理建議，不改變 JSON、評分或退出策略；不執行命令、不修復檔案。[最佳實務清單（英文）](../best-practices.md)也不計分。`init --pr-comment` 明確選擇產生同儲存庫 PR 評論工作流程，並提示 `pull-requests: write` 權限；預設 `init` 產生的工作流程仍僅申請 GitHub 唯讀權限。先預覽、審閱，只提交一份工作流程；既有衝突須主動審閱，不能自動覆寫。Fork PR 保留工作摘要，不發評論。產生的 Action 參照仍為 `v0`，新解釋需要包含本次變更的 Action 建置。已發布的 v0.23.0 不含這兩個參數。詳見[維護者流程（英文）](../maintainer-workflow.md)。 +`--explain` 在文字／Markdown 中為掃描的有效發現、回歸比較的新增發現補充靜態處理建議，不改變 JSON、評分或退出策略；不執行命令、不修復檔案。[最佳實務清單（英文）](../best-practices.md)也不計分。`init --pr-comment` 明確選擇產生同儲存庫 PR 評論工作流程，並提示 `pull-requests: write` 權限；預設 `init` 產生的工作流程仍僅申請 GitHub 唯讀權限。先預覽、審閱，只提交一份工作流程；既有衝突須主動審閱，不能自動覆寫。Fork PR 保留工作摘要，不發評論。產生的 Action 參照仍為 `v0`，解釋摘要需要 v0.24.0+ 或包含該功能的已驗證 Action 版本。升級本機 CLI 不會改變既有工作流程固定的 Action 版本。詳見[維護者流程（英文）](../maintainer-workflow.md)。 -僅更新 CI、不讀取或重設自訂策略時（僅原始碼版）： +僅更新 CI、不讀取或重設自訂策略時（v0.24.0+）： ```bash agent-config-score init --workflow-only --pr-comment --force --dry-run diff --git a/docs/translations.md b/docs/translations.md index d80f25f..172651b 100644 --- a/docs/translations.md +++ b/docs/translations.md @@ -93,6 +93,16 @@ non-atomic failure limits and disclosure of the unchanged generated Action ref. Executable guide examples remain identical; advanced details stay in the English maintainer guide. Published artifacts and frozen research evidence are unchanged. +For v0.24.0 on 2026-10-23, built on +`5e3ef04bfbba538eacfcad0a3830778830124844`, both core guides/limitations were +reviewed for release availability of report identity, tightened regression +checks, opt-in guardrails, explanations and scoped workflow setup. Both overview +Action examples pin `v0.24.0`. This is the first release tag containing these +repository translations; the English package README links to them, but the wheel +does not bundle offline documentation or translated terminal messages. Earlier +sync notes describe their historical state; the v0.23.0 artifacts and frozen +research records remain unchanged. + When an English source page changes, review both variants together and record the new source revision here. Preserve executable examples, rule IDs and JSON keys verbatim. Keep the score limitations and failure/exit semantics aligned; diff --git a/docs/user-guide.md b/docs/user-guide.md index 9a49857..cba5bcf 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -93,7 +93,7 @@ The baseline policy and suppressions govern both sides. A candidate cannot increase its drop budget or suppress its newly introduced error to approve itself. Trusted invocation-time overrides are explicit. -In unreleased source builds, removal checks only exempt one-to-one exact-text +In v0.24.0+, removal checks only exempt one-to-one exact-text moves to newly added files in the same directory. Existing copies and moving root rules into a subtree do not hide removal. Comparisons reuse scan-time text instead of reopening sources; keep both trees stable and rerun after edits. See @@ -138,12 +138,12 @@ messages; inspect them before sharing. Do not overwrite your source or policy files by choosing their paths as report destinations. Multiple output writes are not a transaction: an earlier artifact may remain if a later write fails. -Unreleased source builds also retain the declared tool version and a best-effort +v0.24.0+ also retains the declared tool version and a best-effort tool-source SHA-256 in JSON, HTML, SARIF and new history snapshots. Compare/diff JSON retains both scan identities. This distinguishes local implementations with the same version, not accuracy or reproducibility by itself. Missing source makes the digest unavailable, not the scan invalid. See [report identity](report-identity.md) -for coverage, compatibility and environment/input limits; released v0.23.0 is unchanged. +for coverage, compatibility and environment/input limits; older reports are not relabelled. For a privacy-minimized draft instead: @@ -153,7 +153,7 @@ agent-config-score feedback . --output .agent-config-score/case.md Nothing is uploaded. Review and sanitize the draft yourself before sharing. -## Optional: review missing deletion safeguards (unreleased) +## Optional: review missing deletion safeguards (v0.24.0+) ```bash agent-config-score guardrails . --file AGENTS.md @@ -174,7 +174,7 @@ policies manually; this is not a general contradiction detector. See [guardrail suggestions](guardrail-suggestions.md) for grammar, scope, privacy and non-atomic/partial-write limits. Existing scoring and CI defaults are unchanged. -## Optional: actionable maintainer results (unreleased) +## Optional: actionable maintainer results (v0.24.0+) ```bash agent-config-score . --explain @@ -190,11 +190,12 @@ discloses `pull-requests: write`; the default generated workflow keeps read-only GitHub permissions. Preview, review and commit only one workflow. Existing conflicts require deliberate review, not an automatic overwrite. Fork PRs use job summaries without comments. -The generated Action ref remains `v0`; new explanations require an Action build -containing this change. Neither flag exists in published v0.23.0. +The generated Action ref remains rolling `v0`; explanations require v0.24.0+ +or a verified Action revision containing this feature. Older pinned workflows +remain unchanged when you upgrade the local CLI. See the [maintainer workflow](maintainer-workflow.md) for setup and limits. -To update only CI without reading/resetting custom policy (source builds only): +To update only CI without reading/resetting custom policy (v0.24.0+): ```bash agent-config-score init --workflow-only --pr-comment --force --dry-run diff --git a/pyproject.toml b/pyproject.toml index 9626d38..a2e2f4e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "agent-config-score" -version = "0.23.0" +version = "0.24.0" description = "Deterministic lint and regression gate for AGENTS.md, Claude, Cursor, Copilot, and Gemini instructions." readme = "README.md" requires-python = ">=3.10" diff --git a/src/agent_config_score/__init__.py b/src/agent_config_score/__init__.py index 8b301a7..770bb8d 100644 --- a/src/agent_config_score/__init__.py +++ b/src/agent_config_score/__init__.py @@ -1 +1 @@ -__version__ = "0.23.0" +__version__ = "0.24.0" diff --git a/tests/test_documentation_languages.py b/tests/test_documentation_languages.py index 86dd82e..658c7bc 100644 --- a/tests/test_documentation_languages.py +++ b/tests/test_documentation_languages.py @@ -4,6 +4,7 @@ import unittest from urllib.parse import unquote, urlsplit +from agent_config_score import __version__ from agent_config_score.initializer import CONFIG_CONTENT @@ -49,7 +50,7 @@ def test_overviews_use_the_same_commands_config_and_workflow(self): workflow = blocks(pages[0], "yaml")[0] self.assertIn("contents: read", workflow) self.assertIn("fetch-depth: 0", workflow) - self.assertIn("LE0-Lin/AgentConfigScore@v0.23.0", workflow) + self.assertIn(f"LE0-Lin/AgentConfigScore@v{__version__}", workflow) def test_localized_links_target_real_files_inside_the_repository(self): paths = [ROOT / f"README.{variant}.md" for variant in SCRIPT_VARIANTS]