feat: explain Cursor rule activation for declared file context

CHANGELOG.md

@@ -4,6 +4,8 @@
 
 ### Added
 
+- 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.
 
 - An explicitly manual, read-only GitHub Actions replay of the existing pinned real-repository smoke corpus. The same runner propagates acquisition/mismatch failures and retains logs/results for seven days; it does not execute external repository code, run on every PR or establish independent accuracy/adoption.

docs/README.md

@@ -13,6 +13,7 @@ read the result, and troubleshoot a failing gate.
 - [Visual tour](visual-tour.md)
 - [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)
 - [Repository doctor](doctor.md)
 - [Optional PR comments](pr-comments.md)
 - [Score-history workflow](score-history.md) and [local history command](score-history-cli.md)

docs/cursor-scope.md

@@ -0,0 +1,147 @@
+# Cursor rule activation from declared file context
+
+**Unreleased, opt-in and unscored.** `scope` is available in source builds after
+v0.24.0, not the published v0.24.0 package or rolling Action. It predicts which
+root `.cursor/rules/` project rules attach automatically given explicitly
+declared file paths. It does not query Cursor or observe an agent run.
+
+```bash
+agent-config-score scope . --target src/web/app.ts
+agent-config-score scope . --target src/web/app.ts --target src/api/service.py --json
+```
+
+Repeat `--target` for every file assumed in context. Paths are normalized,
+deduplicated, sorted and repository-relative. Windows separators are accepted;
+absolute, drive-relative, parent-traversal and control-character paths are
+rejected. Target existence and contents are not checked: the command can model
+a proposed file that has not been created yet. Up to 64 inputs of 1,024
+characters each are accepted.
+
+## What the profile models
+
+The `cursor-file-context-v1` profile follows the activation modes described in
+the [Cursor rules documentation](https://cursor.com/docs/rules), checked on
+2026-11-03. This is a bounded interpretation of that documentation, not a claim
+of version-independent equivalence to Cursor's implementation.
+
+| Recognized metadata | Model mode | Predicted activation |
+|---|---|---|
+| `alwaysApply: true` | `always` | Active for the declared context; valid scalar description/globs do not restrict it |
+| `alwaysApply: false` and nonempty supported globs | `patterns` | Active if any declared file matches any pattern; otherwise inactive |
+| `alwaysApply: false`, no globs, nonempty description | `agent_selected` | Unknown: file paths do not determine model selection |
+| `alwaysApply: false`, no globs or description | `manual` | Unknown: manual mentions are not observed |
+| Unsupported or ambiguous metadata | `unknown` | Unknown, including when no supported pattern matches |
+| Plain `.md` under root `.cursor/rules/` | `ignored` | Inactive under the documented project-rule format |
+
+“Active” means **predicted automatic attachment under this profile**. “Inactive”
+means **not triggered by these paths**, not disabled or observed absent. Manual
+references and runtime settings can change actual context. User/team rules,
+other instruction formats, nested project roots, precedence, and the agent's
+interpretation of attached text are not modelled. Directory names or proximity
+to a rule do not add an inferred condition beyond its declared globs.
+
+Globs trigger attachment when matching files enter context. They do not prove
+an instruction can only affect those files. If a task includes both frontend
+and backend files, both rule sets may attach even with disjoint globs. The
+checker evaluates the complete declared file set instead of treating disjoint
+patterns as a proof that contradictory text cannot co-activate.
+
+## Bounded metadata and glob grammar
+
+The first line may have a UTF-8 BOM and must be `---`. Closing `---` must occur
+within the following 128 lines. Only unique, unindented `description`, `globs`
+and `alwaysApply` keys, blank lines and comment lines are accepted. Boolean
+flags must be unquoted lowercase `true` or `false`; missing flags stay unknown.
+
+Description/globs accept empty values, plain strings with optional inline
+comments, JSON double-quoted strings, or single-quoted strings with doubled
+apostrophes. Full YAML is not implemented: lists, blocks, anchors, aliases,
+duplicate/unknown keys, multiline values, implicit non-string scalars and
+ambiguous syntax stay unknown. Quote numeric-looking intended strings and
+glob strings starting with `*`. For `alwaysApply: true`, scalar syntax still
+has to be recognized, but the glob language is not evaluated.
+
+For conditional rules, globs are a comma-separated scalar with OR semantics,
+at most 32 patterns of 256 characters each. Every pattern must be supported;
+one unsupported pattern makes the rule unknown rather than falsely inactive.
+
+| Pattern | Meaning in this profile |
+|---|---|
+| `*.ts` | A root-level filename ending in `.ts` |
+| `**/*.ts` | A `.ts` file at any directory depth, including root |
+| `src/**` | Files below `src`, including nested directories |
+| `src/**/*.tsx` | `.tsx` files at any depth below `src` |
+| `tailwind.config.*` | A matching root-level filename |
+| `src/**, tests/**` | Either pattern |
+
+Matching is case-sensitive, includes dot-prefixed components, and treats `/`
+as a component boundary. `*` matches within one component; `**` is a whole
+component matching zero or more directories. Terminal `**` requires a file
+below the prefix, not a path equal to the prefix. Absolute paths, backslashes,
+empty/dot/parent components, embedded `**`, `?`, braces, character classes,
+negation and extglob syntax are unsupported. Different native matching behavior
+or runtime settings may require a future profile revision.
+
+The engine uses iterative component wildcard dynamic programming and a finite
+set of segment states with zero-directory transitions for `**`. It does not
+use recursive glob backtracking, enumerate the target filesystem, or attempt
+to prove intersection/disjointness of arbitrary pattern languages.
+
+## Opposing-directive review signals
+
+For non-inactive rules with an interpretable body, the scanner reuses its
+bounded English directive recognizer: for example, `Always use tabs` versus
+`Never use tabs`. Recognized directive text is normalized before pairing.
+Explicit examples, fences, quotes and comments are excluded using the existing
+bounded prose context. Open example sections and HTML-like body markup leave
+the body uninterpreted. This is not full Markdown, natural-language reasoning,
+or an extraction of every constraint in a document.
+
+Each pair retains both source paths, original one-based line numbers and
+polarity, plus a SHA-256 of the normalized directive. Pair activation is active
+only if both rules are predicted active; otherwise it is unknown. The report
+includes the union of matched trigger paths and any shared target matches.
+An empty shared set does not cancel multi-file co-activation. More than 10,000
+pairs fails with exit `2` instead of emitting a partial clean-looking report.
+
+These are textual review signals. Two identical opposing phrases could concern
+different entities or contain qualifiers the grammar does not understand.
+They are not proven semantic conflicts, exploitability, or a safety verdict.
+No signals can mean no supported text, an inactive rule, or an uninterpreted
+body; inspect the per-rule analysis and summary counts.
+
+## Report, privacy and failure contract
+
+JSON has `schema_version: 1`, `profile`, `status: "completed"`, `scored: false`,
+the tool identity/source fingerprint, `targets`, `rules`, `opposing_directives`
+and `summary`. `observed_agent_context` and `targets_existence_checked` are
+always false. `activation_inputs` and `unmodelled_inputs` make the boundary
+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.
+
+Reports retain source paths and supplied target paths. Raw descriptions, glob
+values and directive bodies are not exported; hashes are not anonymization or
+proof of authenticity. The command does not write reports, modify rules,
+execute their instructions, upload files or contact maintainers.
+
+Normal supported-source discovery and metadata/source preflight still run
+across the repository, with existing ignores and skipped directories. An
+unrelated unsafe/broken supported instruction link or ignore-file error can
+therefore stop analysis. Only exact lowercase `.mdc` files under root
+`.cursor/rules/` have their contents read here; other discovered instruction
+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.
+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.
+Try the [runnable synthetic example](../examples/cursor-scope/README.md).

docs/limitations.md

@@ -82,6 +82,23 @@ this guard does not claim to constrain every filesystem operation in the tool.
 Non-instruction link cycles are excluded from the path index, not judged safe or
 semantically correct. Keep repositories stable while scanning.
 
+## Cursor file-context profile (unreleased)
+
+The opt-in `scope` command predicts automatic rule attachment from declared file
+paths for root `.cursor/rules/`. It is unscored and does not observe Cursor,
+validate target existence, resolve other formats/precedence or change normal
+scan/regression findings. Inactive means not triggered under this profile;
+manual/model selection, unsupported metadata and runtime settings remain
+unobserved. Disjoint globs can co-activate in a multi-file task.
+
+Bounded English opposing-directive pairs are review signals with source lines,
+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.
+
 ## Command interpretation
 
 The `rm-rf`, `git-clean-force`, and `docker-system-prune` rules tokenize bounded

docs/simplified/limitations.md

@@ -42,6 +42,12 @@ v0.24.0+ 提供[工具源码身份（英文）](../report-identity.md)，用于
 
 中文文档是可选阅读入口。**它不表示检测规则能理解任意简体或繁体中文语义。** 英文散文规则的跨语言表现尚未得到验证；中文的否定、例子、改写和矛盾仍需要人工审核。
 
+## Cursor 文件上下文模型（尚未发布）
+
+可选 `scope` 根据声明的文件路径，预测根目录 `.cursor/rules/` 规则的自动加载。它不计分，不观察 Cursor、不检查目标存在性、不解析其他格式／优先级，也不改变正常扫描和回归发现。inactive 仅表示这些路径未触发规则；手动引用、模型选择、不支持的元数据与运行设置仍未被观察。多个文件可触发不同 glob 的规则共同加载。
+
+有限英文语法识别的相反指令对只提供带来源行号的审核信号，不是语义冲突证明。未知加载条件和未解释的正文会保留；没有信号不代表没有问题。分析完成返回 `0`，包括存在信号的情况；输入／读取／限制错误返回 `2`。仍会执行全仓库支持来源预检查。详见[语法、报告与限制（英文）](../cursor-scope.md)。这是加载条件模型的第一阶段，尚未包含在已发布 v0.24.0 中，也未实现约束变更影响比较或执行验证。
+
 ## 命令与禁止上下文
 
 `rm-rf`、`git-clean-force`、`docker-system-prune` 解析有限 shell 片段的选项，支持部分重排、拆分、长选项、引号内的选项值和显式反斜杠续行。shell 分隔符与 `--` 会停止选项解释。Git 的预览/交互模式排除在危险匹配外；`rm` 后出现的交互选项会覆盖强制模式。排除/过滤选项的值不会当成执行标志。

docs/simplified/user-guide.md

@@ -126,6 +126,17 @@ agent-config-score guardrails . --file AGENTS.md --template-language simplified
 
 尚未发布的源码可直接选择 `--file`，不先遍历整仓，因此无关指令文件的坏链接不会阻止这次单文件审阅。相关忽略规则和所选路径的祖先目录检查仍生效；目录别名或大小写有歧义的目录须手动接入。其他文件不会因此被验证或修复，普通扫描／doctor 的失败仍须单独处理；追加成功不代表整仓扫描完整或安全。此范围修正不在 v0.24.0 包中。
 
+## 可选：Cursor 文件上下文分析（尚未发布）
+
+```bash
+agent-config-score scope . --target src/web/app.ts
+agent-config-score scope . --target src/web/app.ts --target src/api/service.py --json
+```
+
+v0.24.0 之后的源码构建可根据你声明在上下文中的逻辑文件路径，预测根目录 `.cursor/rules/` 项目规则的自动加载条件。不会检查目标文件是否存在。手动引用、模型选择和不支持的元数据保留为未知；inactive 仅表示这些路径未触发规则，不代表实际未加载。多个文件可以触发不同 glob 的规则共同加载。
+
+这是带来源行号、不计分的审核建议，不是实际 Agent 轨迹或阻断门禁。分析完成返回 `0`，包括存在信号／未知的情况；输入或读取失败返回 `2`。原有扫描和回归评分不变。该命令仍使用全仓库支持来源预检查，无关的失效指令链接也可能导致失败。详见[模型与限制（英文）](../cursor-scope.md)及[可运行的合成示例（英文）](../../examples/cursor-scope/README.md)。已发布的 v0.24.0 包和滚动 Action 不包含此命令。
+
 ## 可选：面向维护者的具体建议（v0.24.0+）
 
 ```bash

docs/traditional/limitations.md

@@ -42,6 +42,12 @@ v0.24.0+ 提供[工具原始碼身分（英文）](../report-identity.md)，用
 
 中文文件是選用的閱讀入口。**它不表示偵測規則能理解任意簡體或繁體中文語意。** 英文敘述規則的跨語言表現尚未驗證；中文的否定、範例、改寫與矛盾仍須人工審查。
 
+## Cursor 檔案上下文模型（尚未發布）
+
+選用 `scope` 根據宣告的檔案路徑，預測根目錄 `.cursor/rules/` 規則的自動載入。它不計分，不觀察 Cursor、不檢查目標存在性、不解析其他格式／優先順序，也不改變正常掃描和回歸發現。inactive 僅表示這些路徑未觸發規則；手動引用、模型選擇、不支援的中繼資料與執行設定仍未被觀察。多個檔案可觸發不同 glob 的規則共同載入。
+
+有限英文語法識別的相反指令對只提供帶來源行號的審閱訊號，不是語意衝突證明。未知載入條件和未解釋的正文會保留；沒有訊號不代表沒有問題。分析完成回傳 `0`，包括存在訊號的情況；輸入／讀取／限制錯誤回傳 `2`。仍會執行全儲存庫支援來源預先檢查。詳見[語法、報告與限制（英文）](../cursor-scope.md)。這是載入條件模型的第一階段，尚未包含在已發布 v0.24.0 中，也未實現約束變更影響比較或執行驗證。
+
 ## 命令與禁止上下文
 
 `rm-rf`、`git-clean-force`、`docker-system-prune` 解析有限 shell 片段的選項，支援部分重新排序、拆分、長選項、引號內的選項值與明確反斜線續行。shell 分隔符號與 `--` 會停止解讀選項。Git 的預覽/互動模式排除於危險匹配之外；`rm` 後續的互動選項會覆蓋強制模式。排除/過濾選項的值不會被當作執行旗標。

docs/traditional/user-guide.md

@@ -126,6 +126,17 @@ agent-config-score guardrails . --file AGENTS.md --template-language simplified
 
 尚未發布的原始碼可直接選擇 `--file`，不先遍歷整個儲存庫，因此無關指令檔的失效連結不會阻止這次單檔審閱。相關排除規則及所選路徑的祖先目錄檢查仍生效；目錄別名或大小寫有歧義的目錄須手動整合。其他檔案不會因此被驗證或修復，一般掃描／doctor 的失敗仍須另行處理；追加成功不代表整個儲存庫已完整掃描或安全。此範圍修正不在 v0.24.0 套件中。
 
+## 選用：Cursor 檔案上下文分析（尚未發布）
+
+```bash
+agent-config-score scope . --target src/web/app.ts
+agent-config-score scope . --target src/web/app.ts --target src/api/service.py --json
+```
+
+v0.24.0 之後的原始碼建置可根據你宣告在上下文中的邏輯檔案路徑，預測根目錄 `.cursor/rules/` 專案規則的自動載入條件。不會檢查目標檔案是否存在。手動引用、模型選擇和不支援的中繼資料保留為未知；inactive 僅表示這些路徑未觸發規則，不代表實際未載入。多個檔案可以觸發不同 glob 的規則共同載入。
+
+這是帶來源行號、不計分的審閱建議，不是實際 Agent 軌跡或阻斷門禁。分析完成回傳 `0`，包括存在訊號／未知的情況；輸入或讀取失敗回傳 `2`。原有掃描和回歸評分不變。此命令仍使用全儲存庫支援來源預先檢查，無關的失效指令連結也可能導致失敗。詳見[模型與限制（英文）](../cursor-scope.md)及[可執行的合成範例（英文）](../../examples/cursor-scope/README.md)。已發布的 v0.24.0 套件和滾動 Action 不包含此命令。
+
 ## 選用：面向維護者的具體建議（v0.24.0+）
 
 ```bash