LE0-Lin · Nov 4, 2026 · Nov 4, 2026 · Nov 4, 2026 · Nov 4, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,8 @@
 
 ### Added
 
+- Unreleased `scope compare` and Git-backed `scope diff` for the same declared Cursor file context: file lifecycle, trigger matches and aggregated exact-directive availability, with original line evidence and captured source hashes. Optional caller-owned flags gate recognized active losses and unknowns separately; active duplicate/renamed sources and remaining multi-file triggers retain availability. Includes four runnable synthetic examples and source-build CI guidance. This is bounded attachment/recognition analysis, not general semantic impact or runtime enforcement; normal scoring, policy schema, published packages and Action refs are unchanged.
+
 - An opt-in, unscored `scope` command predicting root Cursor project-rule activation for explicitly declared file context. A bounded scalar-metadata parser and iterative glob model retain unknowns, source-line evidence and multi-file opposing-directive signals even for disjoint patterns. Includes a runnable synthetic example, installed-wheel acceptance and aligned core guides. It does not observe Cursor, prove semantic conflicts, alter scan/gate scores or ship in the published v0.24.0 artifacts or rolling Action.
 
 - An offline runnable design lab with five synthetic before/after scenarios and two passing controls, comparing baseline new-error gating, score-delta-only gating and explicit candidate-threshold caller overrides through the real CLI. Retains observed decisions, commands and source/scenario hashes without claiming independent accuracy, AI superiority or user adoption. Runtime rules, scores, package artifacts and Action refs are unchanged.

diff --git a/docs/README.md b/docs/README.md
@@ -14,6 +14,7 @@ read the result, and troubleshoot a failing gate.
 - [Instruction templates](../examples/README.md)
 - [Opt-in deletion safeguard review and completion](guardrail-suggestions.md) (v0.24.0+)
 - [Cursor rule activation for declared file context](cursor-scope.md) (unreleased, unscored)
+- [Cursor attachment changes and opt-in review gate](cursor-scope-impact.md) (unreleased)
 - [Repository doctor](doctor.md)
 - [Optional PR comments](pr-comments.md)
 - [Score-history workflow](score-history.md) and [local history command](score-history-cli.md)

diff --git a/docs/cursor-scope-impact.md b/docs/cursor-scope-impact.md
@@ -0,0 +1,144 @@
+# Comparing Cursor attachment changes
+
+**Unreleased.** Source builds after v0.24.0 extend the [Cursor file-context
+profile](cursor-scope.md) with two entrypoints:
+
+```bash
+agent-config-score scope compare ../repo-base . --target src/api/service.py --json
+agent-config-score scope diff origin/main --target src/api/service.py --json
+```
+
+`compare` reads two supplied repository trees. `diff` compares a local Git ref
+with the repository's working tree, including uncommitted files. It retains the
+resolved baseline commit and removes its temporary detached worktree on success
+or failure. Omit the ref for conservative local default-branch detection; use
+`--path REPOSITORY` outside the target repository. No ref is fetched.
+
+Both sides use the **same** normalized `--target` set and activation profile.
+Each selected source is captured once per side for both metadata and directive
+evidence. Both trees must complete source preflight/reads. A changed tool-source
+identity during comparison aborts instead of mixing implementations.
+
+## Three distinct kinds of evidence
+
+1. **Rule lifecycle:** added, removed or modified files, with before/after modes,
+   activation reasons, metadata lines, original body lines and source hashes.
+2. **Trigger changes:** which supplied paths stop/start matching. A rule may lose
+   an API-file trigger but remain attached because another declared file matches.
+3. **Recognized directive availability:** aggregate sources across the rules in
+   each context. Renaming a rule or retaining the same directive in another
+   active rule need not lose its recognized active availability.
+
+Source hashes cover UTF-8 decoded, newline-normalized text of read `.mdc`
+sources. Plain `.md` and unmodelled extension casing are not read and have null
+hashes. Changed bodies/metadata can be visible even when their effect on the
+supplied targets is unchanged. This is not an arbitrary-glob equivalence or
+global narrowing proof; changes affecting undeclared files are outside the run.
+
+An exact directive is identified by its existing normalized English body hash
+and polarity. Original evidence keeps source paths and one-based line numbers.
+Raw directive and metadata values are not exported. An identical hash is not
+proof of semantic equivalence, safe behavior or authentic evidence.
+
+| Availability | Meaning for this recognized directive and declared context |
+|---|---|
+| `active` | At least one recognized source is predicted automatically attached |
+| `unknown` | No active source is established, and a matching source has unknown activation or a non-inactive rule body is uninterpreted |
+| `inactive` | Recognized sources exist, all are predicted inactive, and no potentially active opaque body obscures the result |
+| `not_recognized` | No source of this exact directive was recognized and no potentially active opaque body obscures the result |
+
+Uninterpreted, potentially active bodies conservatively leave missing identities
+unknown: the checker cannot establish whether they contain replacements. A
+manual/model-selected rule with an interpretable body contributes uncertainty
+to identities recognized in that body. Unsupported English paraphrases do not
+establish equivalence. Rephrasing a directive can therefore require review even
+if a human considers its meaning preserved.
+
+`rule_changes` records file/activation/trigger changes. `directive_changes`
+records changed availability or source evidence, including harmless line shifts
+and moves whose availability stays `active_to_active`. Summary counts keep
+baseline-active identities, retained identities, recognized losses/gains, unknown
+rules and uninterpreted non-inactive bodies separate. Gains include newly
+established active availability from unknown; they do not prove improvement.
+Both full side reports and their tool identities are retained.
+
+## Optional review gate
+
+```bash
+agent-config-score scope diff origin/main --target src/api/service.py --fail-on-lost-directives --fail-on-unknown --json
+```
+
+- Without flags, completed comparisons return **0**, including changes/unknowns.
+- `--fail-on-lost-directives` returns **1** when a baseline-active identity becomes
+  `inactive` or `not_recognized`. It does not equate unknown with definite loss.
+- `--fail-on-unknown` returns **1** when **either** side has unknown rule activation
+  or an uninterpreted non-inactive body. This also covers an uninspectable
+  baseline, not just a newly uncertain candidate.
+- Input, source, encoding, Git, pair-budget or identity-consistency failures use
+  **2**, with no successful/partial JSON report.
+
+Use both flags when uncertainty requires review. `review_gate` records the
+chosen flags, failure reasons and decision. The flags belong to the caller;
+existing repository score-policy JSON and suppressions do not configure this
+profile. Review workflow/tool changes normally. This does not extend the
+baseline-governed policy schema or alter normal scan/diff/Action defaults.
+
+An empty recognized baseline protects zero directive identities. Exit 0 does
+not imply that required safeguards exist. Neither flag blocks new opposing
+directives automatically; side reports retain those separate review signals.
+Full semantic conflicts, harmful unrecognized text and runtime enforcement
+remain outside this gate.
+
+## Source-build GitHub Actions example
+
+```yaml
+name: Cursor attachment review
+on: [pull_request]
+permissions:
+  contents: read
+env:
+  ACS_TOOL_REVISION: dd208c9302737f6d61b4f327de87b197479f8d0d
+jobs:
+  scope:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Check out the reviewed tool source
+        uses: actions/checkout@v7
+        with:
+          repository: LE0-Lin/AgentConfigScore
+          ref: ${{ env.ACS_TOOL_REVISION }}
+          path: build/agent-config-score-tool
+          fetch-depth: 1
+          persist-credentials: false
+      - name: Install the reviewed tool source
+        run: python -m pip install ./build/agent-config-score-tool
+      - name: Review declared API-task context
+        env:
+          BASE_COMMIT: ${{ github.event.pull_request.base.sha }}
+        run: >-
+          agent-config-score scope diff "$BASE_COMMIT"
+          --target src/api/service.py
+          --fail-on-lost-directives --fail-on-unknown
+```
+
+The recipe pins tool source containing these unreleased commands separately
+from the repository being checked. Installing the published v0.24.0 package or
+using the rolling `v0` Action does not supply them. Choose task files relevant to
+your repository and review each declared context; one context is not
+whole-repository coverage. The workflow uses ordinary read-only PR permissions.
+The separate tool checkout sits under `build/`, which this profile skips during
+instruction-source discovery. A depth-one tool checkout avoids cloning its full
+history; the repository under review still needs its baseline commit available.
+
+The profile inherits its bounded metadata/glob/prose grammar, whole-repository
+supported-source preflight, ignore rules and non-atomic filesystem limits.
+Targets are logical names whose existence is not checked. No Cursor process,
+model API, agent execution, maintainer contact or upload is involved. Try the
+[four synthetic examples](../examples/cursor-scope-impact/README.md).
diff --git a/docs/cursor-scope.md b/docs/cursor-scope.md
@@ -120,6 +120,8 @@ explicit. Each rule records mode, activation/reason, pattern count, metadata
 line numbers, body start, matched targets, directive-analysis status and the
 number of recognized directives considered for pairing. Inactive rules have
 zero considered directives even when their body contains supported prose.
+Read `.mdc` sources additionally carry a newline-normalized `source_sha256`;
+unread formats have a null hash. This binds captured text without exporting it.
 
 Reports retain source paths and supplied target paths. Raw descriptions, glob
 values and directive bodies are not exported; hashes are not anonymization or
@@ -135,13 +137,16 @@ formats are counted but not interpreted. Unknown extension casing remains
 unknown. Existing containment checks and their non-atomic filesystem limits
 apply; this is not an isolated selected-file traversal.
 
-Exit `0` means the advisory analysis completed, including signals and unknowns.
+For standalone `scope PATH`, exit `0` means the advisory analysis completed, including signals and unknowns.
 Invalid inputs, unreadable/invalid UTF-8 sources or resource-limit failures use
 exit `2` without a successful JSON report. There is no exit `1` conflict gate,
 score, policy threshold, suppression handling or pass/fail safety result.
 
 Normal scan, compare, diff and Action scoring are unchanged. In particular,
 the old general contradiction check is not suppressed by this new command.
-This is the first activation-model phase, not effective-policy inheritance,
-configuration-change impact analysis, or execution-invariant verification.
+The [comparison commands](cursor-scope-impact.md) additionally report bounded
+before/after attachment and exact recognized-directive availability, with
+explicit opt-in review gates. General effective-policy inheritance, semantic
+constraint-impact analysis and execution-invariant verification remain outside
+the implementation.
 Try the [runnable synthetic example](../examples/cursor-scope/README.md).
diff --git a/docs/limitations.md b/docs/limitations.md
@@ -96,8 +96,15 @@ not semantic-conflict proofs. Uninterpreted bodies and unknown activation stay
 visible; no signals is not a clean bill of health. Completed advisory analysis
 returns `0` even with signals; input/read/limit errors use `2`. Whole-repository
 supported-source preflight still applies. See the [grammar, report and limits](cursor-scope.md).
-This first activation-model phase is not in published v0.24.0 artifacts and
-does not implement constraint-impact comparison or execution verification.
+Unreleased [comparison commands](cursor-scope-impact.md) additionally compare
+the same declared context across trees/a local Git baseline. File lifecycle and
+trigger losses are distinct from loss of aggregated exact recognized directives;
+another active copy or remaining trigger may retain availability. Opt-in
+caller-owned flags gate known recognition losses and unknowns separately with
+exit `1`; default comparisons remain advisory. Neither semantic paraphrase
+equivalence, arbitrary scope narrowing nor runtime compliance is established.
+An unrecognized/empty baseline protects zero identities. These additions are not
+in published v0.24.0 artifacts or the existing baseline score-policy schema.
 
 ## Command interpretation
 

diff --git a/docs/simplified/limitations.md b/docs/simplified/limitations.md
@@ -46,7 +46,9 @@ v0.24.0+ 提供[工具源码身份（英文）](../report-identity.md)，用于
 
 可选 `scope` 根据声明的文件路径，预测根目录 `.cursor/rules/` 规则的自动加载。它不计分，不观察 Cursor、不检查目标存在性、不解析其他格式／优先级，也不改变正常扫描和回归发现。inactive 仅表示这些路径未触发规则；手动引用、模型选择、不支持的元数据与运行设置仍未被观察。多个文件可触发不同 glob 的规则共同加载。
 
-有限英文语法识别的相反指令对只提供带来源行号的审核信号，不是语义冲突证明。未知加载条件和未解释的正文会保留；没有信号不代表没有问题。分析完成返回 `0`，包括存在信号的情况；输入／读取／限制错误返回 `2`。仍会执行全仓库支持来源预检查。详见[语法、报告与限制（英文）](../cursor-scope.md)。这是加载条件模型的第一阶段，尚未包含在已发布 v0.24.0 中，也未实现约束变更影响比较或执行验证。
+有限英文语法识别的相反指令对只提供带来源行号的审核信号，不是语义冲突证明。未知加载条件和未解释的正文会保留；没有信号不代表没有问题。独立上下文分析完成返回 `0`，包括存在信号的情况；输入／读取／限制错误返回 `2`。仍会执行全仓库支持来源预检查。详见[语法、报告与限制（英文）](../cursor-scope.md)。这些能力尚未包含在已发布 v0.24.0 中，也未实现通用语义约束影响分析或执行验证。
+
+尚未发布的 [scope 比较命令（英文）](../cursor-scope-impact.md)还可比较两个目录或本地 Git 基线下相同的声明上下文，区分文件／触发路径变化与精确识别的指令失去全部活动来源。相同指令的另一份活动来源或其他仍匹配的任务文件可以保留可用性。可选调用方标志分别对已知识别丢失和未知返回 `1`；默认比较仍只给建议。不证明语义改写等价、任意路径上的范围收缩或运行时遵守。空／未识别基线保护零个指令身份。这些能力尚未进入 v0.24.0 或现有基线评分策略格式。
 
 ## 命令与禁止上下文
 

diff --git a/docs/simplified/user-guide.md b/docs/simplified/user-guide.md
@@ -137,6 +137,15 @@ v0.24.0 之后的源码构建可根据你声明在上下文中的逻辑文件路
 
 这是带来源行号、不计分的审核建议，不是实际 Agent 轨迹或阻断门禁。分析完成返回 `0`，包括存在信号／未知的情况；输入或读取失败返回 `2`。原有扫描和回归评分不变。该命令仍使用全仓库支持来源预检查，无关的失效指令链接也可能导致失败。详见[模型与限制（英文）](../cursor-scope.md)及[可运行的合成示例（英文）](../../examples/cursor-scope/README.md)。已发布的 v0.24.0 包和滚动 Action 不包含此命令。
 
+比较修改前后同一组声明的上下文：
+
+```bash
+agent-config-score scope compare ../repo-base . --target src/web/app.ts --fail-on-lost-directives --fail-on-unknown
+agent-config-score scope diff origin/main --target src/web/app.ts --fail-on-lost-directives --fail-on-unknown --json
+```
+
+这些尚未发布的命令分别报告文件变化、触发路径减少，以及精确识别的指令失去全部预计活动来源。另一条活动规则中的相同指令，或仍匹配的其他任务文件，可以保留可用性。两个标志显式启用调用方配置的审核门禁：丢失或未知返回 `1`，操作失败返回 `2`；不带标志时，完成的比较仍为建议性结果（`0`）。基线未识别到活动指令，就没有受保护的指令身份。详见[比较约定与 CI 示例（英文）](../cursor-scope-impact.md)及[四个合成对照（英文）](../../examples/cursor-scope-impact/README.md)。
+
 ## 可选：面向维护者的具体建议（v0.24.0+）
 
 ```bash

diff --git a/docs/traditional/limitations.md b/docs/traditional/limitations.md
@@ -46,7 +46,9 @@ v0.24.0+ 提供[工具原始碼身分（英文）](../report-identity.md)，用
 
 選用 `scope` 根據宣告的檔案路徑，預測根目錄 `.cursor/rules/` 規則的自動載入。它不計分，不觀察 Cursor、不檢查目標存在性、不解析其他格式／優先順序，也不改變正常掃描和回歸發現。inactive 僅表示這些路徑未觸發規則；手動引用、模型選擇、不支援的中繼資料與執行設定仍未被觀察。多個檔案可觸發不同 glob 的規則共同載入。
 
-有限英文語法識別的相反指令對只提供帶來源行號的審閱訊號，不是語意衝突證明。未知載入條件和未解釋的正文會保留；沒有訊號不代表沒有問題。分析完成回傳 `0`，包括存在訊號的情況；輸入／讀取／限制錯誤回傳 `2`。仍會執行全儲存庫支援來源預先檢查。詳見[語法、報告與限制（英文）](../cursor-scope.md)。這是載入條件模型的第一階段，尚未包含在已發布 v0.24.0 中，也未實現約束變更影響比較或執行驗證。
+有限英文語法識別的相反指令對只提供帶來源行號的審閱訊號，不是語意衝突證明。未知載入條件和未解釋的正文會保留；沒有訊號不代表沒有問題。獨立上下文分析完成回傳 `0`，包括存在訊號的情況；輸入／讀取／限制錯誤回傳 `2`。仍會執行全儲存庫支援來源預先檢查。詳見[語法、報告與限制（英文）](../cursor-scope.md)。這些能力尚未包含在已發布 v0.24.0 中，也未實現通用語意約束影響分析或執行驗證。
+
+尚未發布的 [scope 比較命令（英文）](../cursor-scope-impact.md)還可比較兩個目錄或本機 Git 基準下相同的宣告上下文，區分檔案／觸發路徑變化與精確識別的指令失去全部活動來源。相同指令的另一份活動來源或其他仍符合的任務檔案可以保留可用性。選用呼叫端旗標分別對已知識別遺失和未知回傳 `1`；預設比較仍只給建議。不證明語意改寫等價、任意路徑上的範圍收縮或執行時遵守。空／未識別基準保護零個指令身分。這些能力尚未進入 v0.24.0 或現有基準評分策略格式。
 
 ## 命令與禁止上下文