enhance(#2554): resolve code review depth from path-scoped override rules (#3695)

* test(#2554): failing-first suite for path-scoped code review depth overrides

Binds the not-yet-built code-review-depth module: segment-aware path-prefix
matching of a changed-file set against ordered {paths,depth} rules, resolution
order flag > strongest matching rule > global > standard, typed validation
errors, and the large-scope downgrade boundary. Also proves behaviorally that
workflow.code_review_depth_overrides is not yet a registered config key.

Refs #2554

* feat(#2554): resolve code review depth from path-scoped override rules

Adds workflow.code_review_depth_overrides — an ordered array of {paths, depth}
rules matched against a review's changed-file set by segment-aware path-prefix
comparison. Resolution order is --depth= flag, then the strongest matching rule,
then workflow.code_review_depth, then standard; a matching rule replaces the
global rather than being max'd with it, so quick and standard rules stay
meaningful. Glob metacharacters are a hard configuration error rather than sugar
for a prefix, and malformed rules halt the review instead of degrading to
standard. The resolver is pure and reports its own provenance, so the workflow
can print the resolved depth and the rule that matched. The pre-existing
>50-file deep-to-standard downgrade moves into the module and now names the rule
it overrode.

The key is registered centrally rather than as a capability config slice: the
federated slice channel admits only boolean/string/number/enum, so an array
slice would be dropped as malformed.

Closes #2554

* test(#2554): correct depth-provenance assertions and pin out-of-repo paths

Two corrections to the failing-first suite. The source assertion for a
non-matching rule with no global configured expected 'config'; with no global
set the depth comes from the default, and a companion assertion tolerated
either value, so both passed against an implementation that derived provenance
from whether any rules existed rather than from where the depth came from.

The out-of-repo absolute-path case used a home-directory path that matched
neither implementation, so it never exercised the defect it named. It now pins
the discriminating cases: an absolute path outside the repo root must not match
a repo-relative rule, and one under the root must.

* docs(#2554): document path-scoped code review depth overrides

Reference rows for workflow.code_review_depth_overrides in the configuration,
features and commands references plus the locale copies that carry those tables,
and in the planning-config reference. Explanation of why escalation is
whole-review rather than per-file and why v1 is prefix-only. New how-to for
scoping review depth by path, carrying the configuration-error reason table and
the distinction between nothing to report and could not look. CONTEXT.md
glossary entry and the INVENTORY row for the new CLI module.

ja-JP and ko-KR CONFIGURATION.md carry no code_review keys at all, and ko-KR and
pt-BR FEATURES.md carry no code-review config table, so those files are
deliberately untouched.

* fix(#2554): make the depth-misconfiguration halt executable and reject control chars

Three review findings, all in this change.

The misconfiguration halt was prose rather than shell: the error-printing fence
was followed by an unconditional extraction fence, so an ok:false result threw
and left the depth empty instead of stopping the review. Prose is not a guard —
the two fences are now one block with a real conditional, and anything that is
not the literal string true fails closed.

An interior control character in a rule path survived validation and reached the
provenance string and the summary box; rule paths now reject control characters
via a new PATH_CONTROL_CHAR reason, after the glob check so precedence is
unchanged. That in turn makes the field record safe to delimit, so the seven
node invocations that each re-parsed the same result to read one field collapse
to one.

Also corrects the glossary entry's illustrative paths, which the glossary-ref
check read as real repository references.

* fix(#2554): use the fast-check v4 string API and acknowledge workflow growth

Two failures from the remote matrix on d3111f45, both this branch's.

The property block built its segment arbitrary with fc.stringOf, removed in
fast-check v4. Because the arbitrary is constructed in the describe body, the
throw took out all four property tests rather than one — they had never
executed. Rewritten to fc.string({unit, ...}), the form this repo already uses
in emitted-attribution.test.cjs. Every other fast-check helper in the file was
audited against the installed module.

The emitted-attribution growth arm needed an acknowledgment for code-review.md,
which grew 5376 bytes. The pre-existing 3503 fragment keying the same file is
spent — its ripple was absorbed when #3503 merged, and the base file is exactly
the 34435-byte baseline this growth is measured against — so it cannot clear
anything, while the ack lint hard-fails on a duplicate key across two sources.
Removed it in favor of the new fragment, which is exactly how #3503 itself
replaced the spent 3191 fragment.

* docs(#2554): backfill changeset PR number

---------

Co-authored-by: sim <sim@local>

docs/COMMANDS.md

@@ -1562,7 +1562,7 @@ Review source files changed during a phase for bugs, security vulnerabilities, a
 | Argument | Required | Description |
 |----------|----------|-------------|
 | `N` | **Yes** | Phase number whose changes to review (e.g., `2` or `02`) |
-| `--depth=quick\|standard\|deep` | No | Review depth level (overrides `workflow.code_review_depth` config). `quick`: pattern-matching only (~2 min). `standard`: per-file analysis with language-specific checks (~5–15 min, default). `deep`: cross-file analysis including import graphs and call chains (~15–30 min) |
+| `--depth=quick\|standard\|deep` | No | Review depth level. Overrides both `workflow.code_review_depth` and any matching `workflow.code_review_depth_overrides` path rule — the flag always wins. `quick`: pattern-matching only (~2 min). `standard`: per-file analysis with language-specific checks (~5–15 min, default). `deep`: cross-file analysis including import graphs and call chains (~15–30 min) |
 | `--files file1,file2,...` | No | Explicit comma-separated file list; skips SUMMARY/git scoping entirely |
 | `--fix` | No | Auto-fix issues after review — reads REVIEW.md, spawns fixer agent, commits each fix atomically |
 | `--fix --all` | No | Include Info findings in fix scope (default: Critical + Warning only) |

docs/CONFIGURATION.md

@@ -47,6 +47,7 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd-new
     "use_worktrees": true,
     "code_review": true,
     "code_review_depth": "standard",
+    "code_review_depth_overrides": [],
     "plan_bounce": false,
     "plan_bounce_script": null,
     "plan_bounce_passes": 2,
@@ -369,6 +370,7 @@ All workflow toggles follow the **absent = enabled** pattern. If a key is missin
 | `workflow.worktree_skip_hooks` | boolean | `false` | When `true`, executor agents in worktree mode pass `--no-verify` (skipping pre-commit hooks) and post-wave hook validation runs against the merged result instead. Opt-in escape hatch for projects whose hooks cannot run in agent worktrees. Default `false` runs hooks on every commit (#2924). |
 | `workflow.code_review` | boolean | `true` | Enable `/gsd-code-review` and `/gsd-code-review --fix` commands. When `false`, the commands exit with a configuration gate message. Added in v1.34 |
 | `workflow.code_review_depth` | string | `standard` | Default review depth for `/gsd-code-review`: `quick` (pattern-matching only), `standard` (per-file analysis), or `deep` (cross-file with import graphs). Can be overridden per-run with `--depth=`. Added in v1.34 |
+| `workflow.code_review_depth_overrides` | array | `[]` | Ordered list of `{ paths: string[], depth }` rules that escalate `/gsd-code-review` depth for specific directories, e.g. `[{ "paths": ["src/auth"], "depth": "deep" }]`. Each rule's `paths` are matched against the review's changed-file set by whole-segment directory-path prefix (`src/auth` matches `src/auth/token.ts`, never `src/authfoo/x.ts` or `docs/src/auth/x.ts`); matching is case-sensitive, following git. Glob syntax (`*`, `?`) is a configuration error, not sugar for a prefix. One matched file escalates the entire review — depth is not applied per file. Resolution order: `--depth=` flag → strongest matching rule → `workflow.code_review_depth` → `standard`; a matching rule wins even when its tier is weaker than the global default. A malformed rule (bad `depth`, glob syntax, absolute path, `..` segment, empty path, non-array `overrides`, non-object rule, malformed `paths`) is a configuration error and the review halts rather than falling back silently. The resolved depth and the matching rule are printed in the review output. Added in #2554 |
 | `workflow.plan_bounce` | boolean | `false` | Run external validation script against generated plans. When enabled, the plan-phase orchestrator pipes each PLAN.md through the script specified by `plan_bounce_script` and blocks on non-zero exit. Added in v1.36 |
 | `workflow.plan_bounce_script` | string | (none) | Path to the external script invoked for plan bounce validation. Receives the PLAN.md path as its first argument. Required when `plan_bounce` is `true`. Added in v1.36 |
 | `workflow.plan_bounce_passes` | number | `2` | Number of sequential bounce passes to run. Each pass feeds the previous pass's output back into the validator. Higher values increase rigor at the cost of latency. Added in v1.36 |

docs/FEATURES.md

@@ -2219,6 +2219,15 @@ Test suite that scans all agent, workflow, and command files for embedded inject
 |---------|------|---------|-------------|
 | `workflow.code_review` | boolean | `true` | Enable code review commands |
 | `workflow.code_review_depth` | string | `standard` | Default review depth: `quick`, `standard`, or `deep` |
+| `workflow.code_review_depth_overrides` | array | `[]` | Ordered `{ paths, depth }` rules that escalate depth for directories matched by path prefix against the changed-file set (#2554). See below. |
+
+**Path-scoped code review depth overrides**
+
+`workflow.code_review_depth_overrides` matches rules against the review's changed-file set by whole-segment directory-path prefix — `src/auth` matches `src/auth/token.ts` and `src/auth` itself, never `src/authfoo/x.ts` or `docs/src/auth/x.ts` — and is case-sensitive, following git.
+
+Escalation is **whole-review, not per-file**: depth is a single scalar handed to the reviewer agent, not a per-file setting, so the strongest matching tier across the whole rule set applies to every file in the review — a sensitive file is never reviewed shallowly because it shared a review with an unrelated one.
+
+v1 supports **directory-prefix matching only, not glob syntax**: no glob engine (`minimatch`, `picomatch`, `fast-glob`) exists in this project and none was added for this feature. A path containing `*` or `?` (e.g. `src/auth/**`) is a configuration error rather than a silent near-miss, because accepting it as sugar for a prefix would make unsupported patterns look armed when they match nothing. Every use case in the issue is expressible as a directory prefix. See [Scope code review depth by path](how-to/scope-code-review-depth-by-path.md) for the resolution order, error table, and a worked example.
 
 ---
 

docs/INVENTORY-MANIFEST.json

@@ -339,6 +339,7 @@
       "cli-skew-check.cjs",
       "clock.cjs",
       "clusters.cjs",
+      "code-review-depth.cjs",
       "code-review-flags.cjs",
       "codex-agent-toml.cjs",
       "command-aliases.cjs",

docs/INVENTORY.md

@@ -472,6 +472,7 @@ Full listing: `gsd-core/bin/lib/*.cjs`.
 | `host-integration-adapters/cline-sdk-binding.cjs` | Cline SDK binding — pure AgentPlugin `beforeTool` planning-artifact guard and `createAgentModel` model-override resolution adapters, no `@cline/sdk` import (ADR-1239 Phase D, #2090) |
 | `clock.cjs` | Injectable clock seam (now/sleep) for deterministic lock testing |
 | `clusters.cjs` | Skill cluster definitions for the runtime surface module (ADR-0011 Phase 2) |
+| `code-review-depth.cjs` | Pure resolver for a code review's depth tier (#2554); exports `resolveCodeReviewDepth({ flagDepth, configDepth, overrides, files, repoRoot })` (→ `{ ok, depth, resolvedDepth, source, matchedRule, downgraded, fileCount }` or `{ ok: false, errors }`), the frozen `REASON` enum, `DEPTH_TIERS`, `LARGE_SCOPE_THRESHOLD`, and the matching primitives `normalizeRelPath`/`ruleMatchesFile`; resolves `--depth=` flag → strongest matching `workflow.code_review_depth_overrides` rule (segment-aware path prefix, no globs) → `workflow.code_review_depth` → `standard`, and owns the >50-file `deep`→`standard` downgrade |
 | `code-review-flags.cjs` | Typed flag parser for `/gsd-code-review`; exports `parseCodeReviewFlags(argv)` (→ `{ fix, all, auto, depth, files }`) and `resolveCodeReviewWorkflow(flags)` (→ `'code-review.md' \| 'code-review-fix.md'`); canonical dispatch seam for `--fix`/`--all`/`--auto` routing |
 | `codex-agent-toml.cjs` | Typed IR (genuine leaf) for `~/.codex/agents/<agent>.toml` — `parseCodexAgentToml`/`renderCodexAgentToml` round-trip byte-identically; `stripModel`/`stripReasoningEffort` remove exactly one targeted line; `scanTomlLines`/`stripBOM`/`findDeveloperInstructionsBlockRange`/`unquoteTomlValue` are the lenient reader primitives moved here from `agent-install-check.cjs` (#3242 Phase 2); consumed by the Codex `.toml` sync (`commands.cjs cmdEffortSyncCodex`, ADR-2313 D7, #3243) |
 | `command-aliases.cjs` | Alias/subcommand metadata for manifest-backed family routers |

docs/README.md

@@ -38,6 +38,7 @@ Language versions: [English](README.md) · [Português (pt-BR)](pt-BR/README.md)
 - [Configure model profiles](how-to/configure-model-profiles.md) — switch between quality, balanced, and budget model tiers
 - [Control which host runtime GSD reports](how-to/control-the-reported-host-runtime.md) — read the `agent_runtime` ladder, understand what host detection looks at, and pin the runtime when detection is not what you want
 - [Set up cross-AI review](how-to/set-up-cross-ai-review.md) — configure a second AI to review code produced by the primary agent
+- [Scope code review depth by path](how-to/scope-code-review-depth-by-path.md) — escalate `/gsd-code-review` to `deep` for sensitive directories while the rest of the repo stays at the default depth
 - [Work in parallel with workstreams](how-to/work-in-parallel-with-workstreams.md) — run independent lines of work simultaneously using workstreams
 - [Isolate work with workspaces](how-to/isolate-work-with-workspaces.md) — use workspaces to sandbox experimental or risky changes
 - [Debug a failed execution](how-to/debug-a-failed-execution.md) — diagnose and recover from broken or incomplete phase execution

docs/how-to/scope-code-review-depth-by-path.md

@@ -0,0 +1,124 @@
+# How to scope code review depth by path
+
+**Goal:** Escalate `/gsd-code-review` to `deep` for sensitive directories (auth, billing, payments) while the rest of the repository keeps reviewing at the project's normal default — without having to remember `--depth=deep` on every review that happens to touch one of those paths.
+
+**Prerequisites:** A project with `/gsd-code-review` enabled (`workflow.code_review: true`). This guide assumes you already have a working default depth via `workflow.code_review_depth`; see [Configuration Reference](../CONFIGURATION.md#workflow-toggles) if you don't.
+
+---
+
+## The shortest working sequence
+
+1. **Set the global default**, if you haven't already:
+
+   ```bash
+   gsd config-set workflow.code_review_depth standard
+   ```
+
+2. **Add path-scoped rules** to `workflow.code_review_depth_overrides` in `.planning/config.json`. It's an ordered array of `{ "paths": [...], "depth": "quick" | "standard" | "deep" }` objects:
+
+   ```json
+   {
+     "workflow": {
+       "code_review_depth": "standard",
+       "code_review_depth_overrides": [
+         { "paths": ["src/auth"], "depth": "deep" },
+         { "paths": ["src/billing"], "depth": "deep" }
+       ]
+     }
+   }
+   ```
+
+3. **Run the review** as usual:
+
+   ```bash
+   /gsd-code-review 12
+   ```
+
+4. **Read the provenance line** in the output to confirm which rule (if any) fired — see [Read the resolved-depth line](#read-the-resolved-depth-line) below.
+
+---
+
+## Worked example: escalate `src/auth` and `src/billing`, leave everything else at `standard`
+
+With the config above, a phase that only touches `src/lib/formatter.ts` reviews at `standard` (no rule matches, falls through to the global default). A phase that touches `src/auth/token.ts` and nothing else in an escalated path reviews at `deep`, because a rule matched.
+
+**Escalation is whole-review, not per-file.** If a phase touches both `src/lib/formatter.ts` and `src/auth/token.ts`, the *entire* review — including `formatter.ts` — runs at `deep`. Depth is a single scalar handed to the reviewer agent; one matched sensitive file is enough to raise the whole review, so a sensitive file is never reviewed shallowly because it shared a phase with unrelated code.
+
+Matching is by **whole path segment**, not substring:
+
+| Changed file | Matches rule `src/auth`? |
+|---|---|
+| `src/auth/token.ts` | Yes |
+| `src/auth` (the file itself) | Yes |
+| `src/authfoo/x.ts` | No — `authfoo` is a different segment |
+| `docs/src/auth/x.ts` | No — prefix is anchored at the path root, not a substring search |
+
+Matching is case-sensitive, following git: a rule written `Src/Auth` will not match `src/auth/x.ts`.
+
+**Rules win over the global default, even when weaker.** If `workflow.code_review_depth` is `deep` but a matched rule says `quick`, the review runs at `quick` — the rule always replaces the global for files it matches. This is deliberate: if the strongest tier always won, a `quick` or `standard` rule could never actually take effect whenever the project default was `deep`, making it silently inert.
+
+**Only globs are rejected — not the paths themselves.** `workflow.code_review_depth_overrides` supports directory-prefix strings only (`src/auth`, not `src/auth/**`). There is no glob engine in this project; write the prefix and let segment-aware matching do the rest.
+
+---
+
+## Read the resolved-depth line
+
+Every review prints one line naming the resolved depth and why:
+
+```
+Review depth: deep (matched rule 0: src/auth)
+```
+
+The parenthetical names the source:
+
+| Provenance text | Meaning |
+|---|---|
+| `from --depth flag` | The `--depth=` CLI flag was passed; it always wins over both rules and config. |
+| `matched rule N: <path>` | Rule at index `N` (0-based, in declaration order) matched on prefix `<path>` and set the depth. |
+| `from workflow.code_review_depth` | No rule matched this review's file set; the global config value was used. |
+| `default` | Neither a rule, config value, nor flag applied; the built-in `standard` default was used. |
+
+If the review scope exceeds 50 files and the resolved depth is `deep`, the existing large-scope downgrade still fires — but now it names the rule it overrode:
+
+```
+Switching from deep to standard depth for large file count (overrides matched rule 0: src/auth).
+```
+
+A configured sensitive-path policy is not exempt from this downgrade — the same guard that downgrades `--depth=deep` on a large scope also downgrades a rule-sourced `deep`.
+
+---
+
+## Nothing to report vs. could not look
+
+Two outcomes look similar but mean opposite things:
+
+- **A rule matches nothing.** This is not an error and is not reported specially — it means this review simply didn't touch any path the rule covers. The provenance line falls through to `from workflow.code_review_depth` or `default`, exactly as if the rule didn't exist. This is "nothing to report": the policy exists, was checked, and had nothing to say about this particular review.
+- **The configuration is rejected.** This is "could not look": the review halts before doing any file-level work and prints every collected validation error. Never conflate the two — a validly-configured rule set with no match for this review is a healthy, silent no-op; a malformed rule set is a hard stop.
+
+---
+
+## Configuration error reasons
+
+If `workflow.code_review_depth_overrides` is malformed, `/gsd-code-review` prints one error per defect (all of them, not just the first) and stops — it never silently falls back to a default depth. Errors report the reason as one of the following typed values (from `src/code-review-depth.cts`):
+
+| Reason | Meaning | Fix |
+|---|---|---|
+| `not_an_array` | `workflow.code_review_depth_overrides` itself is not an array (object, string, number, `null`, etc.) | Set it to an array of rule objects, or `[]` to disable overrides. |
+| `rule_not_object` | An entry in the array is not a plain object (a string, an array, `null`, `0`, etc.) | Each entry must be a `{ "paths": [...], "depth": "..." }` object. |
+| `paths_malformed` | A rule's `paths` is missing, not an array, empty, or contains a non-string entry | Give `paths` a non-empty array of strings, e.g. `["src/auth"]`. |
+| `invalid_depth` | A rule's `depth` is missing or not one of `quick`, `standard`, `deep` | Set `depth` to exactly one of `quick`, `standard`, or `deep`. |
+| `glob_unsupported` | A rule path contains `*` or `?` (e.g. `src/auth/**`) | Use a directory prefix instead: `src/auth`, not `src/auth/**` or `src/auth/*.ts`. |
+| `path_traversal` | A rule path contains a `..` segment | Remove the `..` segment; write a plain repo-relative prefix. |
+| `path_absolute` | A rule path is absolute (`/src/auth`, `C:\src\auth`) | Use a path relative to the repo root: `src/auth`, not `/src/auth`. |
+| `path_empty` | A rule path is empty, whitespace-only, or normalizes to empty or `.` | Give the path real content, e.g. `src/auth` rather than `""` or `"."`. |
+
+Each printed error names the rule index (and, where applicable, the offending path or depth value) so you can find the exact entry to fix without guessing which rule in the array is broken.
+
+---
+
+## Related
+
+- [Configuration Reference](../CONFIGURATION.md#workflow-toggles) — full schema for `workflow.code_review_depth_overrides` and `workflow.code_review_depth`
+- [Feature Reference — Code Review Pipeline](../FEATURES.md#93-code-review-pipeline) — why escalation is whole-review and why v1 is prefix-only, not glob
+- [`/gsd-code-review`](../COMMANDS.md#gsd-code-review) — command reference and the `--depth=` flag
+- [docs index](../README.md)

docs/ja-JP/COMMANDS.md

@@ -1163,7 +1163,7 @@ AI システムの構築を含むフェーズの AI-SPEC.md デザインコン
 | 引数 | 必須 | 説明 |
 |----------|----------|-------------|
 | `N` | **Yes** | レビューする変更のフェーズ番号（例: `2` または `02`） |
-| `--depth=quick\|standard\|deep` | No | レビューの深さレベル（`workflow.code_review_depth` 設定を上書き）。`quick`: パターンマッチングのみ（約2分）。`standard`: 言語固有のチェックを含むファイルごとの分析（約5〜15分、デフォルト）。`deep`: インポートグラフとコールチェーンを含むクロスファイル分析（約15〜30分） |
+| `--depth=quick\|standard\|deep` | No | レビューの深さレベル。`workflow.code_review_depth` と、一致する `workflow.code_review_depth_overrides` のパスルールの両方を上書きします — フラグが常に優先します。`quick`: パターンマッチングのみ（約2分）。`standard`: 言語固有のチェックを含むファイルごとの分析（約5〜15分、デフォルト）。`deep`: インポートグラフとコールチェーンを含むクロスファイル分析（約15〜30分） |
 | `--files file1,file2,...` | No | 明示的なカンマ区切りのファイルリスト; SUMMARY/git スコーピングを完全にスキップ |
 | `--fix` | No | レビュー後に問題を自動修正 — REVIEW.md を読み込み、修正エージェントを起動し、各修正をアトミックにコミット |
 | `--fix --all` | No | 修正スコープに Info の発見事項を含める（デフォルト: Critical + Warning のみ） |

docs/ja-JP/FEATURES.md

@@ -2119,6 +2119,15 @@ Claude が GSD ワークフローコンテキスト外でファイル編集を
 |------|-----|-----------|------|
 | `workflow.code_review` | boolean | `true` | コードレビューコマンドを有効化 |
 | `workflow.code_review_depth` | string | `standard` | デフォルトのレビュー深度：`quick`、`standard`、または `deep` |
+| `workflow.code_review_depth_overrides` | array | `[]` | 変更ファイル集合に対するパスプレフィックス一致で特定ディレクトリのレビュー深度をエスカレートする、順序付き `{ paths, depth }` ルール（#2554）。詳細は下記参照。 |
+
+**パススコープのコードレビュー深度オーバーライド**
+
+`workflow.code_review_depth_overrides` は、レビュー対象の変更ファイル集合に対して、セグメント単位のディレクトリパスプレフィックスでルールを照合します。`src/auth` は `src/auth/token.ts` および `src/auth` 自体に一致しますが、`src/authfoo/x.ts` や `docs/src/auth/x.ts` には一致しません。照合は git と同様に大文字小文字を区別します。
+
+エスカレーションは**レビュー全体単位であり、ファイル単位ではありません**：深度はレビューエージェントに渡される単一のスカラー値であり、ファイルごとの設定ではないため、ルールセット全体で一致した最も強いティアがレビュー内のすべてのファイルに適用されます — 機密ファイルが無関係なファイルと同じレビューに含まれたために浅くレビューされることはありません。
+
+v1 は**ディレクトリプレフィックス一致のみをサポートし、glob 構文はサポートしません**：このプロジェクトには glob エンジン（`minimatch`、`picomatch`、`fast-glob`）が存在せず、この機能のために追加もされていません。`*` や `?` を含むパス（例：`src/auth/**`）は、静かな近似一致ではなく設定エラーとして扱われます。
 
 ---
 

docs/ko-KR/COMMANDS.md

@@ -1169,7 +1169,7 @@ AI 시스템 구축을 포함하는 단계에 대한 AI-SPEC.md 디자인 계약
 | 인수 | 필수 | 설명 |
 |----------|----------|-------------|
 | `N` | **예** | 검토할 변경사항이 있는 단계 번호 (예: `2` 또는 `02`) |
-| `--depth=quick\|standard\|deep` | 아니요 | 검토 깊이 수준 (`workflow.code_review_depth` 설정 재정의). `quick`: 패턴 매칭만 (~2분). `standard`: 언어별 검사를 통한 파일별 분석 (~5–15분, 기본값). `deep`: 임포트 그래프와 호출 체인을 포함한 크로스 파일 분석 (~15–30분) |
+| `--depth=quick\|standard\|deep` | 아니요 | 검토 깊이 수준. `workflow.code_review_depth`와 일치하는 `workflow.code_review_depth_overrides` 경로 규칙을 모두 재정의합니다 — 플래그가 항상 우선합니다. `quick`: 패턴 매칭만 (~2분). `standard`: 언어별 검사를 통한 파일별 분석 (~5–15분, 기본값). `deep`: 임포트 그래프와 호출 체인을 포함한 크로스 파일 분석 (~15–30분) |
 | `--files file1,file2,...` | 아니요 | 명시적 쉼표 구분 파일 목록; SUMMARY/git 범위 지정을 완전히 건너뜀 |
 | `--fix` | 아니요 | 검토 후 자동 문제 수정 — REVIEW.md를 읽고, 수정자 에이전트를 생성하고, 각 수정을 원자적으로 커밋 |
 | `--fix --all` | 아니요 | 수정 범위에 Info 결과 포함 (기본값: Critical + Warning만) |

docs/pt-BR/COMMANDS.md

@@ -1166,7 +1166,7 @@ Revisa arquivos de código-fonte alterados durante uma fase em busca de bugs, vu
 | Argumento | Obrigatório | Descrição |
 |-----------|-------------|-----------|
 | `N` | **Sim** | Número da fase cujas mudanças revisar (por exemplo, `2` ou `02`) |
-| `--depth=quick\|standard\|deep` | Não | Nível de profundidade da revisão (substitui a configuração `workflow.code_review_depth`). `quick`: somente correspondência de padrões (~2 min). `standard`: análise por arquivo com verificações específicas de linguagem (~5–15 min, padrão). `deep`: análise entre arquivos incluindo grafos de importação e cadeias de chamadas (~15–30 min) |
+| `--depth=quick\|standard\|deep` | Não | Nível de profundidade da revisão. Substitui tanto `workflow.code_review_depth` quanto qualquer regra de caminho correspondente em `workflow.code_review_depth_overrides` — a flag sempre prevalece. `quick`: somente correspondência de padrões (~2 min). `standard`: análise por arquivo com verificações específicas de linguagem (~5–15 min, padrão). `deep`: análise entre arquivos incluindo grafos de importação e cadeias de chamadas (~15–30 min) |
 | `--files file1,file2,...` | Não | Lista explícita de arquivos separados por vírgula; ignora completamente o escopo SUMMARY/git |
 | `--fix` | Não | Corrige automaticamente problemas após a revisão — lê REVIEW.md, cria agente corretor, faz commit de cada correção atomicamente |
 | `--fix --all` | Não | Inclui descobertas Info no escopo de correção (padrão: somente Critical + Warning) |

docs/pt-BR/CONFIGURATION.md

@@ -47,6 +47,7 @@ O GSD armazena as configurações do projeto em `.planning/config.json`. Criado
     "use_worktrees": true,
     "code_review": true,
     "code_review_depth": "standard",
+    "code_review_depth_overrides": [],
     "plan_bounce": false,
     "plan_bounce_script": null,
     "plan_bounce_passes": 2,
@@ -248,6 +249,7 @@ Todos os controles de fluxo de trabalho seguem o padrão **ausente = habilitado*
 | `workflow.worktree_skip_hooks` | boolean | `false` | Quando `true`, os agentes executores no modo worktree passam `--no-verify` (ignorando hooks de pré-commit) e a validação de hook pós-onda é executada contra o resultado mesclado. Válvula de escape opt-in para projetos cujos hooks não podem ser executados em worktrees de agente. Padrão `false` executa hooks em cada commit (#2924). |
 | `workflow.code_review` | boolean | `true` | Habilita os comandos `/gsd-code-review` e `/gsd-code-review --fix`. Quando `false`, os comandos saem com uma mensagem de gate de configuração. Adicionado na v1.34 |
 | `workflow.code_review_depth` | string | `standard` | Profundidade de revisão padrão para `/gsd-code-review`: `quick` (somente correspondência de padrão), `standard` (análise por arquivo) ou `deep` (entre arquivos com grafos de importação). Pode ser substituído por execução com `--depth=`. Adicionado na v1.34 |
+| `workflow.code_review_depth_overrides` | array | `[]` | Lista ordenada de regras `{ paths: string[], depth }` que aumentam a profundidade de `/gsd-code-review` para diretórios específicos, ex.: `[{ "paths": ["src/auth"], "depth": "deep" }]`. Cada `paths` da regra é comparado com o conjunto de arquivos alterados da revisão por prefixo de diretório com segmentos completos (`src/auth` corresponde a `src/auth/token.ts`, nunca a `src/authfoo/x.ts` ou `docs/src/auth/x.ts`); a comparação diferencia maiúsculas/minúsculas, como o git. Sintaxe glob (`*`, `?`) é um erro de configuração, não um atalho para prefixo. Um único arquivo correspondido eleva a profundidade de toda a revisão — a profundidade não é aplicada por arquivo. Ordem de resolução: flag `--depth=` → regra correspondente mais forte → `workflow.code_review_depth` → `standard`; uma regra correspondente prevalece mesmo quando seu nível é mais fraco que o padrão global. Uma regra malformada (`depth` inválido, sintaxe glob, caminho absoluto, segmento `..`, caminho vazio, `overrides` que não é array, regra que não é objeto, `paths` malformado) é um erro de configuração e a revisão é interrompida em vez de usar um valor padrão silenciosamente. A profundidade resolvida e a regra correspondente são exibidas na saída da revisão. Adicionado em #2554 |
 | `workflow.plan_bounce` | boolean | `false` | Executa script de validação externo nos planos gerados. Quando habilitado, o orquestrador de fase de planejamento encaminha cada PLAN.md pelo script especificado por `plan_bounce_script` e bloqueia em saída diferente de zero. Adicionado na v1.36 |
 | `workflow.plan_bounce_script` | string | (nenhum) | Caminho para o script externo invocado na validação de bounce de plano. Recebe o caminho do PLAN.md como primeiro argumento. Obrigatório quando `plan_bounce` é `true`. Adicionado na v1.36 |
 | `workflow.plan_bounce_passes` | number | `2` | Número de passagens sequenciais de bounce a executar. Cada passagem alimenta a saída da passagem anterior de volta no validador. Valores maiores aumentam o rigor ao custo de latência. Adicionado na v1.36 |

docs/zh-CN/COMMANDS.md

@@ -1163,7 +1163,7 @@ node gsd-tools.cjs intel api-surface              # 渲染 api-map.json → API-
 | 参数 | 必填 | 描述 |
 |----------|----------|-------------|
 | `N` | **是** | 要审查的阶段编号（例如 `2` 或 `02`） |
-| `--depth=quick\|standard\|deep` | 否 | 审查深度级别（覆盖 `workflow.code_review_depth` 配置）。`quick`：仅模式匹配（约 2 分钟）。`standard`：按文件分析，含特定语言检查（约 5-15 分钟，默认）。`deep`：跨文件分析，包括导入图和调用链（约 15-30 分钟） |
+| `--depth=quick\|standard\|deep` | 否 | 审查深度级别。同时覆盖 `workflow.code_review_depth` 和任何匹配的 `workflow.code_review_depth_overrides` 路径规则——该标志始终优先。`quick`：仅模式匹配（约 2 分钟）。`standard`：按文件分析，含特定语言检查（约 5-15 分钟，默认）。`deep`：跨文件分析，包括导入图和调用链（约 15-30 分钟） |
 | `--files file1,file2,...` | 否 | 显式逗号分隔的文件列表；完全跳过 SUMMARY/git 范围界定 |
 | `--fix` | 否 | 审查后自动修复问题 — 读取 REVIEW.md，生成修复代理，原子性地提交每个修复 |
 | `--fix --all` | 否 | 将 Info 级别的发现纳入修复范围（默认：仅 Critical + Warning） |

docs/zh-CN/CONFIGURATION.md

@@ -47,6 +47,7 @@ GSD 将项目设置存储在 `.planning/config.json` 中。该文件在 `/gsd-ne
     "use_worktrees": true,
     "code_review": true,
     "code_review_depth": "standard",
+    "code_review_depth_overrides": [],
     "plan_bounce": false,
     "plan_bounce_script": null,
     "plan_bounce_passes": 2,
@@ -248,6 +249,7 @@ API 密钥字段接受字符串值（密钥本身）。也可以设置为哨兵
 | `workflow.worktree_skip_hooks` | boolean | `false` | 为 `true` 时，worktree 模式下的执行器 agent 传递 `--no-verify`（跳过提交前钩子），波次后的钩子验证改为针对合并结果运行。适用于钩子无法在 agent worktree 中运行的项目的可选逃生舱口。默认 `false` 对每次提交运行钩子（#2924）。 |
 | `workflow.code_review` | boolean | `true` | 启用 `/gsd-code-review` 和 `/gsd-code-review --fix` 命令。为 `false` 时，命令以配置门禁消息退出。v1.34 新增 |
 | `workflow.code_review_depth` | string | `standard` | `/gsd-code-review` 的默认审查深度：`quick`（仅模式匹配）、`standard`（按文件分析）或 `deep`（带导入图的跨文件）。可通过 `--depth=` 按次运行覆盖。v1.34 新增 |
+| `workflow.code_review_depth_overrides` | array | `[]` | 有序的 `{ paths: string[], depth }` 规则列表，按目录前缀匹配对特定目录提升 `/gsd-code-review` 的审查深度，例如 `[{ "paths": ["src/auth"], "depth": "deep" }]`。每条规则的 `paths` 按整段目录路径前缀与本次审查的变更文件集合匹配（`src/auth` 匹配 `src/auth/token.ts`，但绝不匹配 `src/authfoo/x.ts` 或 `docs/src/auth/x.ts`）；匹配区分大小写，与 git 一致。glob 语法（`*`、`?`）是配置错误，而非前缀的简写形式。一个匹配的文件会将整次审查提升到该深度——深度并非逐文件应用。解析顺序：`--depth=` 标志 → 匹配到的最强规则 → `workflow.code_review_depth` → `standard`；即使规则的档位比全局默认值弱，匹配到的规则依然生效。格式错误的规则（`depth` 无效、glob 语法、绝对路径、`..` 段、路径为空、`overrides` 非数组、规则非对象、`paths` 格式错误）是配置错误，审查会中止，而不会静默回退。解析出的深度及匹配的规则会打印在审查输出中。#2554 新增 |
 | `workflow.plan_bounce` | boolean | `false` | 针对生成的计划运行外部验证脚本。启用后，计划阶段编排器将每个 PLAN.md 通过 `plan_bounce_script` 指定的脚本管道处理，并在非零退出时阻塞。v1.36 新增 |
 | `workflow.plan_bounce_script` | string | （无） | 用于计划反弹验证的外部脚本路径。接收 PLAN.md 路径作为第一个参数。当 `plan_bounce` 为 `true` 时必需。v1.36 新增 |
 | `workflow.plan_bounce_passes` | number | `2` | 顺序执行的反弹轮数。每轮将上一轮的输出反馈给验证器。较高的值提升严格性，但会增加延迟。v1.36 新增 |

docs/zh-CN/FEATURES.md

@@ -2135,6 +2135,15 @@ PreToolUse 钩子，检测 Claude 在 GSD 工作流上下文之外尝试文件
 |---------|------|---------|-------------|
 | `workflow.code_review` | boolean | `true` | 启用代码审查命令 |
 | `workflow.code_review_depth` | string | `standard` | 默认审查深度：`quick`、`standard` 或 `deep` |
+| `workflow.code_review_depth_overrides` | array | `[]` | 按目录路径前缀匹配变更文件集合、为特定目录提升审查深度的有序 `{ paths, depth }` 规则列表（#2554）。详见下文。 |
+
+**按路径限定代码审查深度**
+
+`workflow.code_review_depth_overrides` 通过整段目录路径前缀，将规则与本次审查的变更文件集合进行匹配 —— `src/auth` 匹配 `src/auth/token.ts` 及 `src/auth` 本身，但绝不匹配 `src/authfoo/x.ts` 或 `docs/src/auth/x.ts`。匹配区分大小写，与 git 保持一致。
+
+升级是**针对整次审查，而非逐文件**的：深度是传递给审查代理的单一标量值，而非逐文件设置，因此规则集中匹配到的最强档位适用于本次审查中的每一个文件 —— 一个敏感文件不会因为与无关文件同处一次审查中而被浅层审查。
+
+v1 **仅支持目录前缀匹配，不支持 glob 语法**：本项目中不存在 glob 引擎（`minimatch`、`picomatch`、`fast-glob`），本功能也未引入。路径中包含 `*` 或 `?`（例如 `src/auth/**`）会被视为配置错误，而不是悄悄地按前缀近似处理。
 
 ---