Repository navigation
Conversation
…mdsh-dev#155) Both user-visible text caps were hardcoded and cut the text silently: the stored next-prompt suggestion at 120 characters (no marker, mid-word) and the delivered advice note at 768 (marker, mid-word). Add two config keys and one shared bound helper: - `nextPromptMaxChars` (default 120, 0 = unbounded): read live per prediction attempt; one snapshot feeds both the prompt budget (a "keep the reply within N characters" line in the predictor system prompt) and the shaping step, so an attempt can never mix two bounds. - `noteMaxChars` (default 768, 0 = unbounded): a runtime construction constant threaded into the runtime options and folded into `runtimeSignature`, so an edit rebuilds the session runtime once, like `proseFallback`. The shared `limitText` helper (`src/text-limit.ts`) counts CODE POINTS (never splitting a surrogate pair), cuts on a word boundary when the boundary keeps at least 60% of the budget, and appends a `…` marker that counts toward the bound. Defaults keep the historical limits, so an absent key behaves exactly as before — except that an over-long text now lands on a word boundary and carries the marker. Surfaces: schema + strict key set, `/advisor config` readback, the settings wire (get/set), the web card (two number inputs) and both locales. Docs, READMEs and the example YAMLs updated. Closes omdsh-dev#155
✅ Verdict:
|
| Findings | Count |
|---|---|
| 🔴 must-fix | 0 |
| 🟠 should-fix | 0 |
| 🟡 may-fix | 2 |
| 🔵 nit | 1 |
📋 Review
What this PR does: This PR replaces the two hardcoded advisor text caps — a silent, mid-word 120-code-point slice on the stored next-prompt suggestion and a 768-code-point slice on the delivered advice note — with two config keys, nextPromptMaxChars (default 120, range 0–2000) and noteMaxChars (default 768, range 0–20000), both .volatile(), added to CONFIG_KEYS, the resolved snapshot, the gateway wire, the /advisor config readback, the web card and the en/zh locales. One shared helper, limitText in src/text-limit.ts, now performs every cut: code-point counted, word boundary preferred with a … marker that counts toward the bound, hard cut when a single token exceeds the budget, and maxChars <= 0 meaning unbounded. The suggestion bound is read once per prediction attempt (one snapshot feeding both the predictor prompt budget and the shaping step), while noteMaxChars is a runtime construction constant folded into runtimeSignature, so an edit rebuilds the session runtime exactly like proseFallback; defaults keep the historical limits and only the cut shape changes at defaults, by design.
Findings
🔵 Containment fallback duplicates the 120/768 bound defaults as literals instead of the shared constants
-
Evidence:
[DEBT-01] Containment fallback duplicates the 120/768 bound defaults as literals instead of the shared constants
- Evidence:
src/gateway.ts:748-749— the S1 containment arm ofreadConfig()seeds the two bounds with raw literals:nextPromptMaxChars: raw?.nextPromptMaxChars ?? 120,/noteMaxChars: raw?.noteMaxChars ?? 768,;gateway.tsimports nothing from./text-limit.js.
src/index.ts:281-282— the sibling containment arm introduced by the same diff does the identical fallback through the constants:raw?.nextPromptMaxChars ?? DEFAULT_NEXT_PROMPT_MAX_CHARS/raw?.noteMaxChars ?? DEFAULT_ADVISOR_NOTE_MAX_CHARS(imported atsrc/index.ts:72).
src/config.ts:266-269— the schema is the declared default SSOT (.default(DEFAULT_NEXT_PROMPT_MAX_CHARS)/.default(DEFAULT_ADVISOR_NOTE_MAX_CHARS)). - Impact: No behavioral difference today (the literals equal the constants). The cost is drift: there are now three places that must agree on the historical defaults, and the two containment arms in the same feature answer the same question two different ways. A future default change edits
text-limit.ts+config.ts+index.tsand silently missesgateway.ts, so/api/advisor/getand the settings card would report a bound the resolver never used for the disabled-with-reason arm — exactly the misreport class the S1 seeding exists to prevent. - Effort: XS — two lines plus one import.
- Risk: LOW — pure substitution of equal values; the
??nullish test (0 stays 0, absent → default) is unchanged. - Confidence: HIGH — read both fallback arms and the schema defaults; the values currently match.
- Merge class: nit
- Fix sketch: Import
DEFAULT_NEXT_PROMPT_MAX_CHARS/DEFAULT_ADVISOR_NOTE_MAX_CHARSfrom./text-limit.jsingateway.tsand use them in thereadConfig()fallback, matchingsrc/index.ts:281-282. Judgement-class fix (cross-file consistency), not machinery-detectable: the pattern is two?? <number>exp…
- Evidence:
-
Location:
src/gateway.ts:748-749 -
Category: tech-debt
-
Merge class: nit
🟡 Live-reapply doc omits noteMaxChars from the runtime-signature list it presents as exhaustive
-
Evidence:
[DOCS-01] Live-reapply section omits
noteMaxCharsfrom the runtime-signature list- Evidence:
docs/configuration.md:173— 「每个会话 runtime 仅在其「运行影响签名」(provider / model / systemPrompt / proseFallback / reasoningEffort)变化时重建 —— 只改免疫/窗口的编辑不会中断在途调用或丢弃 backlog。」 The list is presented as the complete set. - Evidence:
docs/configuration.md:31— the same change's field-table row fornoteMaxChars: 「它是运行期构造常量,因此进 runtime 签名——修改会重建会话 runtime(与proseFallback同一路径)。」 - Evidence:
src/index.ts:487-489—runtimeSignatureinsertsglobalResolved.noteMaxChars ?? DEFAULT_ADVISOR_NOTE_MAX_CHARS, and the inline comment on line 487-488 saysnextPromptMaxCharsis deliberately ABSENT because it is read live. So the code's signature set containsnoteMaxCharsand excludesnextPromptMaxChars; the doc at :173 has it the other way round fornoteMaxChars(silently absent). - Evidence:
src/index.ts:792-794— a signature change callsdisposeRuntime+ensureRuntime, so the consequence the section describes (in-flight call abort, backlog drop) is exactly what anoteMaxCharsedit now triggers. - Impact: a reader who edits
noteMaxCharsand consults this section (the section that owns "what does a live config edit do to a running session") is told the edit re-applies without a runtime rebuild, i.e. that it does not interrupt in-flight review calls — the opposite of the shipped behavior. The same document asserts both answers, so the reader cannot resolve which one governs. - Effort: XS
- Risk: LOW — adding one item to a prose list; no code touched.
- Confidence: HIGH — cited both sides of the contradiction (doc row :31, code :487-489) and the rebuild path (:792-794).
- Merge class: may-fix
- Fix sketch: add
noteMaxCharsto the parenthesized signature list atdocs/configuration.md:173(and keepnextPromptMaxCharsout, matching the code comment), so the section agrees with the :31 row.
- Evidence:
-
Location:
docs/configuration.md:173 -
Category: docs
-
Merge class: may-fix
🟡 nextPromptMaxChars row promises an unconditional word-boundary cut; the code hard-cuts mid-word on a long token
-
Evidence:
[DOCS-02]
nextPromptMaxCharsrow states a word-boundary guarantee the helper only honors conditionally- Evidence:
docs/configuration.md:30— 「截断落在词边界并追加…标记(标记计入上限)」, stated unconditionally for the new field. - Evidence:
src/text-limit.ts:33-36— the helper's own contract: 「A single word longer than the bound falls back to a hard cut: there is no word boundary to land on」; and the body atsrc/text-limit.ts:49-52only accepts the boundary whenlastSpace >= Math.ceil(budget * 0.6), otherwisecutstays the full budget body. A note whose tail is a URL/hash/long token is cut inside that token. - Evidence:
tests/text-limit.test.ts:55-61— this change pins the mid-word path as intended behavior:limitText('a'.repeat(130), 120) === 'a'.repeat(119) + '…', andprefix+ 1000×xat bound 120 ends mid-word. - Impact: the field row is the reader's contract for user-visible suggestion text. A reader who relies on 「截断落在词边界」 to know that a suggested prompt containing a long identifier never gets split gets a mid-word cut in exactly the case the code documents as routine (long single token, or a trailing token holding < 60 % of the budget). The doc and the helper state different rules for the same bound.
- Effort: XS
- Risk: LOW — prose-only change.
- Confidence: HIGH — implementation, its docstring, and the new tests all read directly.
- Merge class: may-fix
- Fix sketch: qualify the row at
docs/configuration.md:30the waysrc/text-limit.ts:30-36does — word boundary when it keeps most of the budget, otherwise a code-point hard cut (and mention the 60 % rule if the doc intends to state it).
Seat coverage declaration (not a finding). Soft cap reached; scope declared truncated. Read in full:
docs/configuration.md,docs/consumer-api.md,tests/text-limit.test.ts, plus the new feat: configurable text limits for advice notes and next-prompt suggestions (0 = no truncation) #155 sections oftests/next-prompt.test.ts:755-843,tests/advisor-runtime.test.ts:1601-1650, `tests/advisor-store.test.ts:16… - Evidence:
-
Location:
docs/configuration.md:30 -
Category: docs
-
Merge class: may-fix
Revalidated findings
none
Linked-issue AC
- Configurable nextPromptMaxChars (integer, 0–2000, default 120): met — src/config.ts:266-267 declares z.number().step(1).min(0).max(MAX_NEXT_PROMPT_MAX_CHARS).default(DEFAULT_NEXT_PROMPT_MAX_CHARS).
- Configurable noteMaxChars (integer, 0–20000, default 768): met — src/config.ts:268-269 declares the matching schema default/bounds via MAX_ADVISOR_NOTE_MAX_CHARS / DEFAULT_ADVISOR_NOTE_MAX_CHARS.
- Both fields .volatile(), added to CONFIG_KEYS, the resolved snapshot, the gateway write payload, the settings card and the en/zh locales: met — .volatile() at src/config.ts:267,269, CONFIG_KEYS at :191-192, resolved defaults at :421-422, wire round-trip at src/gateway.ts:787-788, card inputs at src/client/advisor-card.tsx:463-496, locale keys at src/client/locales.ts:35-38 (en) and :134-137 (zh).
- One snapshot per attempt, used for both the prompt budget and the shaping step (no mixed limits inside one attempt): met — src/next-prompt.ts:413-415 reads config.nextPromptMaxChars once into attemptMaxChars and passes that same value to callOnce(...) and shapeNextPrompt(raw, attemptMaxChars).
- Word-boundary cut appending … with the marker counting toward the cap, result <= cap, hard cut for a single over-long word: met — src/text-limit.ts:37-59 reserves one code point for the marker and only accepts a boundary at lastSpace >= Math.ceil(budget * 0.6); the hard-cut path is pinned by tests/text-limit.test.ts:55-61.
- 0 = keep the full text: met — src/text-limit.ts:38 returns the text unchanged for maxChars <= 0, and the schema allows 0 on both keys.
- Pass the budget into the predictor system prompt ("keep the reply under N characters"): met — src/prompts.ts:53-56 documents the advisory budget and the prompt is built from the same attemptMaxChars snapshot; enforcement remains the shaping step.
- Config schema bounds and settings round-trip covered by tests: met — tests/config.test.ts:452-495 (defaults/bounds/null/unknown) and the tests/gateway.test.ts bound-field fixtures exercise the wire; the field row at docs/configuration.md:31 already states the noteMaxChars signature consequence.
✅ Verified
- src/text-limit.ts read in full: code-point counting via Array.from, maxChars <= 0 opt-out, one-code-point marker reserve so body + … <= maxChars, and the Math.ceil(budget * 0.6) acceptance rule for a word boundary all match the PR's stated cut shape.
- src/config.ts:190-194,263-269,305-308,362-376,420-422 read: both keys are in CONFIG_KEYS, .volatile(), bounded by the shared MAX constants, unwrapped through unwrapReference, and defaulted on the resolved arm.
- src/index.ts:281-282,487-489,537,1070-1071 read: noteMaxChars is inserted into runtimeSignature and threaded into the runtime options while nextPromptMaxChars is deliberately absent (read live per attempt); the S1 containment arm falls back through the shared constants.
- src/next-prompt.ts:33,167,193,413-415 read: shapeNextPrompt ends in limitText(text, maxChars) and the per-attempt snapshot feeds both the prediction call and the shaping step.
- src/gateway.ts:747-749,786-788 read: both keys ride every resolved get (0 is a real value, never absent) and the S1 containment fallback uses raw 120 / 768 literals.
- src/client/advisor-card.tsx:463-496, src/client/advisor-store.ts:324-354,877-884,1013 and src/client/locales.ts:35-38,134-137 read: two number inputs with min=0 step=1, empty input mapped to 0, draft seeded/clamped/patch-listed on both keys, en+zh label and hint present.
- tests/text-limit.test.ts:55-61 read: the mid-word hard-cut path ('a'.repeat(130) at bound 120) is asserted as intended behavior.
- docs/configuration.md:30,31,173 read: the field rows match the code, while :173's runtime-signature list omits noteMaxChars (DOCS-01) and :30 states the word-boundary rule unconditionally (DOCS-02).
- ❓ PR body reports pnpm test (28 files, 767 tests), pnpm typecheck and pnpm build all passing; the review document shows no command output, so none of those runs are claimed here.
- ❓ PR body promises a truncation debug log carrying only rawLength and a truncated flag; a search of src/ finds no rawLength/truncated logging (only unrelated truncated doc comments), and the review raised no finding on it — confirm whether that detail was dropped from #155's scope.
🗑️ Considered & rejected
- docs/configuration.md:182 (empty number input treated as 0) — rejected as a doc defect: src/client/advisor-card.tsx:475,492 maps an empty input to 0, so the card matches the doc.
- tests/next-prompt.test.ts:767,791 assertions that rebuild the expectation via nextPromptSystemPrompt(...) — rejected: src/prompts.ts:67-70 returns the plain prompt for maxChars <= 0, so no wrong behavior is pinned.
- tests/config.test.ts:476-478 "null treated as absent" — dropped as a candidate: settling it would require execution, so it was excluded under the evidence rules rather than raised.
- nextPromptMaxChars being absent from runtimeSignature — rejected as a defect: the inline comment at src/index.ts:487-488 states the predictor reads it live per attempt, exactly like nextPrompt; only the doc's signature list (DOCS-01) is wrong.
- noteMaxChars in the runtime signature aborting in-flight calls on edit — rejected as a defect: src/index.ts:792-794 (disposeRuntime + ensureRuntime) is the intended proseFallback-style path documented at docs/configuration.md:31.
🛠️ Plan to fix
Expand fix plan
Nothing here blocks merge (0 must-fix); the two doc items and the nit are consistency cleanups. Ordered smallest-first:
1. DEBT-01 (nit) — kill the duplicated bound literals in the containment fallback.
- src/gateway.ts: add an import of DEFAULT_NEXT_PROMPT_MAX_CHARS / DEFAULT_ADVISOR_NOTE_MAX_CHARS from ./text-limit.js.
- src/gateway.ts:748-749: replace raw?.nextPromptMaxChars ?? 120 / raw?.noteMaxChars ?? 768 with the imported constants, mirroring the sibling arm at src/index.ts:281-282.
- Keep the ?? nullish test untouched (0 still stays 0; absent still means the default).
- Gate: pnpm typecheck; a repo search for ?? 120 / ?? 768 under src/ returns no remaining bound defaults.
2. DOCS-01 (may-fix) — make the live-reapply signature list exhaustive.
- docs/configuration.md:173: add noteMaxChars to the parenthesized runtime-signature list and leave nextPromptMaxChars out, matching the code comment at src/index.ts:487-489 and the field row at docs/configuration.md:31 (which already says an edit rebuilds the session runtime via the proseFallback path).
- Re-read the surrounding paragraph so the consequence sentence still reads correctly with the added item (an edit to noteMaxChars aborts in-flight calls and drops backlog, per src/index.ts:792-794).
- Gate: cross-check the list against src/index.ts:487-537; search the doc for other signature enumerations so none is left stale.
3. DOCS-02 (may-fix) — qualify the word-boundary guarantee in the field row.
- docs/configuration.md:30: state the rule the helper actually enforces — a word boundary is used when it keeps at least 60% of the budget (lastSpace >= Math.ceil(budget * 0.6)), otherwise the cut is a code-point hard cut inside the trailing token; the … marker counts toward the bound.
- Keep the row's existing statements (0 = unbounded, code-point counting, one snapshot per attempt, not in the runtime signature) as-is.
- Gate: read docs/configuration.md:30 against src/text-limit.ts:30-59 and tests/text-limit.test.ts:55-61; the doc must no longer promise an unconditional boundary cut.
4. Regression gate for the whole change set.
- pnpm typecheck (main + client + spec configs) and pnpm test — expected green: steps 1-3 touch one import pair and two prose lines, and the substituted constants equal the literals, so no test expectation changes.
- Optional final read: git diff limited to src/gateway.ts and docs/configuration.md to confirm no other file moved.Review 1 · commit d371965
| // an absent raw key keeps the schema default (120 / 768), so the S1 | ||
| // fallback never invents an unbounded read. | ||
| nextPromptMaxChars: raw?.nextPromptMaxChars ?? 120, | ||
| noteMaxChars: raw?.noteMaxChars ?? 768, |
There was a problem hiding this comment.
Containment fallback duplicates the 120/768 bound defaults as literals instead of the shared constants · 🔵 nit
[DEBT-01] Containment fallback duplicates the 120/768 bound defaults as literals instead of the shared constants
- Evidence:
src/gateway.ts:748-749— the S1 containment arm ofreadConfig()seeds the two bounds with raw literals:nextPromptMaxChars: raw?.nextPromptMaxChars ?? 120,/noteMaxChars: raw?.noteMaxChars ?? 768,;gateway.tsimports nothing from./text-limit.js.
src/index.ts:281-282— the sibling containment arm introduced by the same diff does the identical fallback through the constants:raw?.nextPromptMaxChars ?? DEFAULT_NEXT_PROMPT_MAX_CHARS/raw?.noteMaxChars ?? DEFAULT_ADVISOR_NOTE_MAX_CHARS(imported atsrc/index.ts:72).
src/config.ts:266-269— the schema is the declared default SSOT (.default(DEFAULT_NEXT_PROMPT_MAX_CHARS)/.default(DEFAULT_ADVISOR_NOTE_MAX_CHARS)). - Impact: No behavioral difference today (the literals equal the constants). The cost is drift: there are now three places that must agree on the historical defaults, and the two containment arms in the same feature answer the same question two different ways. A future default change edits
text-limit.ts+config.ts+index.tsand silently missesgateway.ts, so/api/advisor/getand the settings card would report a bound the resolver never used for the disabled-with-reason arm — exactly the misreport class the S1 seeding exists to prevent. - Effort: XS — two lines plus one import.
- Risk: LOW — pure substitution of equal values; the
??nullish test (0 stays 0, absent → default) is unchanged. - Confidence: HIGH — read both fallback arms and the schema defaults; the values currently match.
- Merge class: nit
- Fix sketch: Import
DEFAULT_NEXT_PROMPT_MAX_CHARS/DEFAULT_ADVISOR_NOTE_MAX_CHARSfrom./text-limit.jsingateway.tsand use them in thereadConfig()fallback, matching `src/index.ts:2…
| | `proseFallback` | boolean | `false` | Opt-in 散文容错(issue #102):开启后,未产出有效 note(无可解析 JSON 帧,或帧的 note 为空/非法)但正文非空的回复经清理(trim → 剥外围 markdown 围栏 → 768 字符截断)作为 `severity: 'nit'` 的 note 走正常 guard/投递管线。可用的帧 note 始终优先;默认关闭时同样回复仍被丢弃。 | | ||
| | `proseFallback` | boolean | `false` | Opt-in 散文容错(issue #102):开启后,未产出有效 note(无可解析 JSON 帧,或帧的 note 为空/非法)但正文非空的回复经清理(trim → 剥外围 markdown 围栏 → `noteMaxChars` 截断,默认 768 码点)作为 `severity: 'nit'` 的 note 走正常 guard/投递管线。可用的帧 note 始终优先;默认关闭时同样回复仍被丢弃。 | | ||
| | `nextPrompt` | boolean | `true` | 下一提示预测开关(plan dsh-advisor-next-prompt-n12):每个完成的 turn 后预测用户可能的下一提示,作为 composer 下方提示条显示。**仅 web 配置面**(web 卡片可编辑;`/advisor config` 回读与 TUI 分节不包含该键)。 | | ||
| | `nextPromptMaxChars` | number(整数 ≥ 0,≤ 2000) | `120` | 存储的下一提示建议的字数上限(**码点**计数,GitHub issue #155):`0` = 无上限。截断落在词边界并追加 `…` 标记(标记计入上限);同一快照同时喂给该次预测的 prompt 预算(系统提示追加「Keep the reply within N characters」)与塑形步骤,一次预测内不会混用两个上限。该键**不**进 runtime 签名——每次预测实时读取。**仅 web 配置面**(web 卡片可编辑;`/advisor config` 回读,TUI 分节不含)。 | |
There was a problem hiding this comment.
nextPromptMaxChars row promises an unconditional word-boundary cut; the code hard-cuts mid-word on a long token · 🟡 may-fix
[DOCS-02] nextPromptMaxChars row states a word-boundary guarantee the helper only honors conditionally
- Evidence:
docs/configuration.md:30— 「截断落在词边界并追加…标记(标记计入上限)」, stated unconditionally for the new field. - Evidence:
src/text-limit.ts:33-36— the helper's own contract: 「A single word longer than the bound falls back to a hard cut: there is no word boundary to land on」; and the body atsrc/text-limit.ts:49-52only accepts the boundary whenlastSpace >= Math.ceil(budget * 0.6), otherwisecutstays the full budget body. A note whose tail is a URL/hash/long token is cut inside that token. - Evidence:
tests/text-limit.test.ts:55-61— this change pins the mid-word path as intended behavior:limitText('a'.repeat(130), 120) === 'a'.repeat(119) + '…', andprefix+ 1000×xat bound 120 ends mid-word. - Impact: the field row is the reader's contract for user-visible suggestion text. A reader who relies on 「截断落在词边界」 to know that a suggested prompt containing a long identifier never gets split gets a mid-word cut in exactly the case the code documents as routine (long single token, or a trailing token holding < 60 % of the budget). The doc and the helper state different rules for the same bound.
- Effort: XS
- Risk: LOW — prose-only change.
- Confidence: HIGH — implementation, its docstring, and the new tests all read directly.
- Merge class: may-fix
- Fix sketch: qualify the row at
docs/configuration.md:30the waysrc/text-limit.ts:30-36does — word boundary when it keeps most of the budget, otherwise a code-point hard cut (and mention the 60 % rule if the doc intends to state it).
Seat coverage declaration (not a finding). Soft cap reached; scope declared truncated. Read in full: docs/configuration.md, docs/consumer-api.md, tests/text-limit.test.ts, plus the ne…
|
CI run https://github.com/omdsh-dev/dsh-advisor/actions/runs/44010247313 currently reports Local verification on this branch ( |
|
Superseding this PR with #157, which keeps your work and credits you as co-author ( What we kept, essentially unchanged
What we changed
Everything else you touched — docs, tests and surfaces — carried over with those bounds adjusted. Thanks for the diagnosis, the helper and the test coverage — the word-boundary shaping was the right call. |
Closes #155.
Both user-visible text caps were hardcoded, applied silently, and cut mid-word without a marker for the suggestion (
120characters) / with a mid-word marker for the note (768). This PR makes both bounds configurable and gives the cuts a single, documented shape.New config keys
nextPromptMaxChars1200= unbounded. Read live per prediction attempt; one snapshot feeds both the prompt budget and the shaping step.noteMaxChars7680= unbounded. A runtime construction constant, folded intoruntimeSignature(an edit rebuilds the session runtime once, exactly likeproseFallback).Both are
.volatile()live fields, joinCONFIG_KEYS(strict unknown-key rejection unchanged), ride the settings wire (/api/advisor/get+set), appear in the/advisor configreadback, and are editable on the web card (two number inputs with hints; an empty input is treated as0).Truncation shape
One shared helper —
src/text-limit.tslimitText:…, with the marker counting toward the bound;maxChars <= 0returns the text unchanged (the opt-out).Defaults keep the historical limits, so an absent key changes only the cut shape: the next-prompt suggestion still lands within 120 code points, but now on a word boundary and marked with
…, and the predictor system prompt now states the char budget it enforces.Evidence
Reproduced on the pre-PR build: a 187-char prediction was stored as exactly 120 characters with
endsWith('…') === falseand a mid-word tail ("…адержке, потом добав"), while the predictor system prompt carried no budget at all; a 900-char note became768+…mid-word. After the change the same inputs are cut on a word boundary and marked.Tests
pnpm test— pass: 28 files, 767 tests.pnpm typecheck— pass (main + client + spec configs).pnpm build— pass.New coverage:
tests/text-limit.test.ts(bounds,0/negative opt-out, word boundary, 60 % fallback,maxChars = 1, code points, idempotence), plus per-surface cases intests/config.test.ts(schema defaults/bounds/null/unknown near-miss),tests/next-prompt.test.ts(custom bound, live per-attempt read, prompt budget,0= whole text),tests/advisor-runtime.test.ts(runtime option + extraction functions),tests/advisor-store.test.ts(draft seeding, patch, clamping) andtests/gateway.test.ts(wire round-trip).Docs:
README.md/README.zh.md(YAML example, bounds paragraph, surface notes),docs/configuration.md(field table, example YAML, defaults paragraph, card fields, KD-2 notes),docs/consumer-api.md,CONCEPTS.md,docs/verification.md.