docs(deprecate): mark minContextLimit + modelMinLimits deprecated (soft, no behavior change)

minContextLimit (default 80%) is the lower bound for turn/iteration
reminder nudges. The growth-nudge floor (minNudgeContextPercent +
nudgeGrowthTokens, ranxianglei#343/ranxianglei#351) is the maintained mechanism — two parallel
'min' knobs confuse users. Soft deprecation: JSDoc @deprecated, schema
[DEPRECATED] prefixes, EN/zh Status DEPRECATED + removal-consequence note,
legend reworded (may still take effect until removed). zh default fixed
45% -> 80%. No behavior change; 1053/1053 unchanged.

Author: ranxianglei

CONFIGURATION.md

@@ -35,7 +35,7 @@ ACP reads config from up to three layers (later layers override earlier):
 
 ## Parameter Reference
 
-Status legend: **ACTIVE** = currently used | **DEPRECATED** = accepted but no effect | **EXPERIMENTAL** = may change
+Status legend: **ACTIVE** = currently used | **DEPRECATED** = kept for backward compatibility, scheduled for removal (may still take effect until then) | **EXPERIMENTAL** = may change
 
 ---
 
@@ -164,8 +164,8 @@ Core compression behavior.
 #### `compress.minContextLimit`
 - **Type:** `number | \`${number}%\``
 - **Default:** `"80%"`
-- **Status:** ACTIVE
-- **Description:** Lower context usage threshold for turn/iteration reminder nudges. ACP stops injecting those reminders when usage drops below this level (or when the limit cannot be resolved to a concrete value, e.g. a `"X%"` limit with an unknown model context window). Growth nudges are governed separately by `minNudgeContextPercent`.
+- **Status:** DEPRECATED
+- **Description:** **Deprecated — scheduled for removal.** Lower context usage threshold for turn/iteration reminder nudges. ACP stops injecting those reminders when usage drops below this level (or when the limit cannot be resolved to a concrete value, e.g. a `"X%"` limit with an unknown model context window). Growth nudges are governed separately by `minNudgeContextPercent`. Still honored until removed; when it is removed, the lower-bound gating for turn/iteration reminder nudges is retired along with it (new sessions should rely on the growth-nudge system).
 
 #### `compress.modelMaxLimits`
 - **Type:** `Record<string, number | \`${number}%\`>`
@@ -176,8 +176,8 @@ Core compression behavior.
 #### `compress.modelMinLimits`
 - **Type:** `Record<string, number | \`${number}%\`>`
 - **Default:** `undefined`
-- **Status:** ACTIVE
-- **Description:** Per-model override for `minContextLimit`.
+- **Status:** DEPRECATED
+- **Description:** **Deprecated — scheduled for removal alongside `minContextLimit`.** Per-model override for `minContextLimit`. Still honored until removed.
 
 #### `compress.nudgeFrequency`
 - **Type:** `number`

CONFIGURATION.zh-CN.md

@@ -35,7 +35,7 @@ ACP 从最多三层配置文件中读取（后加载的覆盖先加载的）：
 
 ## 参数参考
 
-状态说明：**ACTIVE** = 当前生效 | **DEPRECATED** = 接受但无效果 | **EXPERIMENTAL** = 可能变更
+状态说明：**ACTIVE** = 当前生效 | **DEPRECATED** = 保留向后兼容，计划移除（在此之前可能仍生效） | **EXPERIMENTAL** = 可能变更
 
 ---
 
@@ -163,9 +163,9 @@ ACP 从最多三层配置文件中读取（后加载的覆盖先加载的）：
 
 #### `compress.minContextLimit`
 - **类型：** `number | \`${number}%\``
-- **默认值：** `"45%"`
-- **状态：** ACTIVE
-- **说明：** 上下文使用率下限。使用率降至此值以下时，ACP 停止 nudge。
+- **默认值：** `"80%"`
+- **状态：** DEPRECATED
+- **说明：** **已废弃——计划移除。** 轮次/迭代提醒 nudge 的上下文使用率下限。使用率降至此值以下时，ACP 停止注入这些提醒（当限制无法换算为具体数值时同样停止，例如模型上下文窗口未知时的 `"X%"`）。增长 nudge 由 `minNudgeContextPercent` 单独控制。在此之前仍然生效；移除时，轮次/迭代提醒 nudge 的下限门控将随之取消（新配置应依赖增长 nudge 体系）。
 
 #### `compress.modelMaxLimits`
 - **类型：** `Record<string, number | \`${number}%\`>`
@@ -176,8 +176,8 @@ ACP 从最多三层配置文件中读取（后加载的覆盖先加载的）：
 #### `compress.modelMinLimits`
 - **类型：** `Record<string, number | \`${number}%\`>`
 - **默认值：** `undefined`
-- **状态：** ACTIVE
-- **说明：** 按模型覆盖 `minContextLimit`。
+- **状态：** DEPRECATED
+- **说明：** **已废弃——将与 `minContextLimit` 一同移除。** 按模型覆盖 `minContextLimit`。在此之前仍然生效。
 
 #### `compress.nudgeFrequency`
 - **类型：** `number`

dcp.schema.json

@@ -146,7 +146,7 @@
                     ]
                 },
                 "minContextLimit": {
-                    "description": "Soft lower threshold for reminder nudges. Below this, turn/iteration reminders are off (compression is less likely). At or above this, reminders are on. Accepts number or \"X%\" of the model context window.",
+                    "description": "[DEPRECATED — scheduled for removal; growth nudges (minNudgeContextPercent) are the maintained floor] Soft lower threshold for reminder nudges. Below this, turn/iteration reminders are off (compression is less likely). At or above this, reminders are on. Still honored until removed. Accepts number or \"X%\" of the model context window.",
                     "default": 50000,
                     "oneOf": [
                         {
@@ -174,7 +174,7 @@
                     }
                 },
                 "modelMinLimits": {
-                    "description": "Per-model override for minContextLimit by exact provider/model key. If set, this takes priority over the global minContextLimit.",
+                    "description": "[DEPRECATED — overrides the deprecated minContextLimit; will be removed alongside it] Per-model override for minContextLimit by exact provider/model key. If set, this takes priority over the global minContextLimit.",
                     "type": "object",
                     "additionalProperties": {
                         "oneOf": [

devlog/2026-08-29_deprecate-min-context-limit/REQ.md

@@ -0,0 +1,38 @@
+# REQ — Deprecate `minContextLimit` (and `modelMinLimits`)
+
+- **Task ID:** 2026-08-29_deprecate-min-context-limit
+- **Date:** 2026-08-29
+- **Priority:** P2
+- **Status:** Done (pending review)
+
+## Background
+
+`compress.minContextLimit` (default `"80%"`) is the soft lower bound for turn/iteration reminder nudges: `overMinLimit` gates when those anchors are set/cleared. Since #343/#351, the growth-nudge floor (`minNudgeContextPercent`, cascade via `compress.providers`) is the maintained "minimum" mechanism — two parallel "min" knobs confuse users.
+
+Maintainer direction (2026-08-29): mark `minContextLimit` as deprecated.
+
+## Requirement
+
+1. **Soft deprecation only** — annotations, no behavior change:
+   - `@deprecated` JSDoc on `CompressConfig.minContextLimit` and `CompressConfig.modelMinLimits` (the flat per-model map only feeds `minContextLimit`; same fate).
+   - `dcp.schema.json`: `[DEPRECATED — …]` description prefix (repo convention, cf. `allowSubAgents`).
+   - `CONFIGURATION.md` / `CONFIGURATION.zh-CN.md`: Status → DEPRECATED, deprecation notes, legend reworded ("kept for backward compatibility, scheduled for removal (may still take effect until then)") — the old legend "accepted but no effect" is wrong for a soft deprecation.
+2. Deprecation text must state the removal consequence: when removed, the lower-bound gating for turn/iteration reminder nudges is retired with it (those nudges depend on `overMinLimit`); the growth-nudge system (`minNudgeContextPercent` + `nudgeGrowthTokens`) is the maintained mechanism.
+3. No runtime warnings, no validation rejection, no default changes, no removal in this PR.
+
+## Non-goals
+
+- Actually removing the field or changing nudge behavior.
+- Deprecating `nudgeFrequency` / `iterationNudgeThreshold` (only meaningful to revisit at removal time).
+- Touching `maxContextLimit` / `modelMaxLimits`.
+
+## Acceptance criteria
+
+- Annotations present in code + schema + both docs.
+- `npm run typecheck` passes; full suite 1053/1053 unchanged (annotation-only change proves no behavior drift).
+- CI green.
+
+## References
+
+- PR #351 (nested providers floor, stacked-under), PR #343 (growth floor gate)
+- Deprecation precedents: `gc.algorithm`, `gc.maxBlockAge`, schema `allowSubAgents`

devlog/2026-08-29_deprecate-min-context-limit/WORKLOG.md

@@ -0,0 +1,31 @@
+# WORKLOG — 2026-08-29_deprecate-min-context-limit
+
+## 1. Overview
+
+Marks `compress.minContextLimit` and `compress.modelMinLimits` as **deprecated** (soft: annotations only, behavior unchanged). The growth-nudge floor (`minNudgeContextPercent` + `nudgeGrowthTokens`, #343/#351) is the maintained "minimum" mechanism going forward.
+
+Stacked on #351 (`2026-08-29_min-nudge-providers-models`), which is stacked on #343. Merge order: #343 → #351 → this.
+
+## 2. Changes
+
+| File | Change |
+|---|---|
+| `lib/config.ts` | `@deprecated` JSDoc on `minContextLimit` + `modelMinLimits` (removal consequence noted) |
+| `dcp.schema.json` | `[DEPRECATED — …]` description prefix on both properties |
+| `CONFIGURATION.md` | Status → DEPRECATED for both; deprecation note incl. removal consequence; legend line 38 reworded to cover soft deprecation ("may still take effect until then") |
+| `CONFIGURATION.zh-CN.md` | Same as EN; additionally fixed the stale default `45%` → `80%` (code default, `lib/config.ts`) |
+| devlog | This REQ/WORKLOG |
+
+Behavior: **none changed** — `resolveContextTokenLimit(…, "min")`, `overMinLimit`, anchor set/clear in `inject.ts` untouched.
+
+## 3. Verification
+
+- `npm run typecheck` ✓
+- Full suite: 1053/1053 ✓ (unchanged from #351 — annotation-only change, no behavior drift)
+- CI (pr-validation / test 22 / test 24 / build / build-artifact / e2e) ✓
+
+## 4. Commits
+
+| Hash | Subject |
+|---|---|
+| (pending) | docs(deprecate): mark minContextLimit + modelMinLimits deprecated (soft, no behavior change) |

lib/config.ts

@@ -32,8 +32,19 @@ export interface CompressConfig {
     showCompression: boolean
     summaryBuffer: boolean
     maxContextLimit: number | `${number}%`
+    /**
+     * @deprecated Soft lower bound for turn/iteration reminder nudges. Scheduled
+     * for removal in a future version — growth nudges (`minNudgeContextPercent` +
+     * `nudgeGrowthTokens`) are the maintained nudge mechanism. Still honored
+     * until removed; removing it will retire the lower-bound gating for
+     * turn/iteration reminder nudges.
+     */
     minContextLimit: number | `${number}%`
     modelMaxLimits?: Record<string, number | `${number}%`>
+    /**
+     * @deprecated Per-model override for the deprecated `minContextLimit`.
+     * Still honored until removed alongside `minContextLimit`.
+     */
     modelMinLimits?: Record<string, number | `${number}%`>
     /** Nested per-provider / per-model overrides (billion-context-pi style). Resolved field-by-field: model > provider > global. */
     providers?: Record<string, CompressProviderOverrides>