@oh-story/dsh 0.1.3 → 0.1.5

package/lib/oh-story/skills/story-review/scripts/check-ai-patterns.js

@@ -13,6 +13,7 @@ Detect high-risk AI-flavor prose patterns that need human rewrite:
   - repeated negative setup followed by positive flip
   - em-dash (按功能改写), 碎句号 (连续短叙述句), 长段落 (按镜头断段)
   - 微动作复读 (「了下/了一下」式轻量补语高密度，电报体指纹)
+  - 套式反应细节 (指尖/指节/目光等无功能微动作与「平静得像在念」式语气比喻成片)
   - 抽象总结复读 (命运/棋局/这一刻终于明白/才刚刚开始，AI 结尾腔)
   - 套词密度过高 (仿佛/一丝/深吸一口气/平静无波等禁用词聚集)
   - 比喻密度过高 (像/好像/仿佛/如同等比喻标记成片复现)
@@ -30,7 +31,7 @@ Detect high-risk AI-flavor prose patterns that need human rewrite:
   - 引号强调滥用 (叙述里 1-4 字短词加引号强调，密度型)
 
 Each finding carries severity: blocking by default for generation/deslop cleanup (not-is-comparison / em-dash / voice-contrast / negation-parade / reverse-not-is / trailer-ending / trailer-summary). This is a local style/readability gate, not an AIGC detector score; functional human text can be marked for review instead of hard-edited for a detector.
-或 advisory (period-stutter / long-paragraph / micro-action-tic / action-list-tic / abstract-summary-tic / cliche-density-tic / metaphor-density-tic / reasoning-chain-tic / system-notice-formality-tic / overcompressed-prose-tic / low-connective-density-tic / quote-emphasis-tic / formulaic-parallelism，是提示，justified 的长推理/氛围段可保留)。
+或 advisory (period-stutter / long-paragraph / micro-action-tic / stock-reaction-tic / action-list-tic / abstract-summary-tic / cliche-density-tic / metaphor-density-tic / reasoning-chain-tic / system-notice-formality-tic / overcompressed-prose-tic / low-connective-density-tic / quote-emphasis-tic / formulaic-parallelism，是提示，justified 的长推理/氛围段可保留)。
 --fail-on=blocking 只在出现 blocking finding 时退出 1；默认 --fail-on=all 有任何 finding 即退出 1。
 
 The script reports findings only. It never rewrites text, because the safe fix is
@@ -57,6 +58,26 @@ const MICRO_TIC_PATTERN = /了(?:[一两三几半])?[下阵圈道声眼口气会
 const MICRO_TIC_MIN_HITS = 5;
 const MICRO_TIC_PER_KILO = 6;
 
+// 套式反应细节：不是禁写身体，而是提示成片出现的“部位 + 轻微动作/状态”、
+// “胸口像被撞了一下”、喉结/眼圈/声音放轻等通用情绪尾巴，以及“平静语气 +
+// 像在念/宣判”模板。此类句子词面变化大，不能逐词 blocking；按章聚集到 4 处才
+// advisory，要求逐处做删除测试。正常受伤、打斗、生理反应若承担物理后果可保留。
+const STOCK_REACTION_PATTERNS = [
+  /(?:指尖|手指|指节|手背|掌心|拳头|袖口|衣角|裙角|下唇|嘴唇|唇角|嘴角|眉头|眼底|眸光|目光|视线|肩膀|呼吸)[^。！？!?\n]{0,16}(?:轻轻|微微|缓缓|悄然|不自觉|无意识|下意识|攥紧|握紧|收紧|绞紧|泛白|发白|叩|敲|摩挲|抿紧|抿成|移开|垂下|躲开|一颤|颤了?一下|停了?一下|顿了?一下)/g,
+  /(?:语气|声音)[^。！？!?\n]{0,12}(?:平静|冷静|平淡|冷淡|淡漠|平直)[^。！？!?\n]{0,12}(?:像|仿佛|如同|好像)[^。！？!?\n]{0,16}(?:念|读|报|说|陈述|宣判|背诵)/g,
+  /(?:胸口|心口)[^。！？!?\n]{0,16}(?:像|仿佛|如同|好像)[^。！？!?\n]{0,16}(?:撞|锤|压|攥|堵)[^。！？!?\n]{0,8}(?:一下|一记|一拳)?/g,
+  /(?:声音|嗓音|语气)[^。！？!?\n]{0,12}(?:放轻|压低|发紧|发颤|很轻|轻了些)/g,
+  /(?:喉结|喉头|喉咙)[^。！？!?\n]{0,10}(?:滚|动|紧|堵|发涩|发干)/g,
+  /(?:眼眶|眼圈|鼻子)[^。！？!?\n]{0,8}(?:发红|红了|发热|发酸|一酸)/g,
+  /(?:抿了?下唇|抿了?抿唇|抿了?下嘴|抿着笑)/g,
+];
+const STOCK_REACTION_MIN_HITS = 4;
+// 校准（真人语料，<br> 已还原为换行）：qimao 长篇 5584 章 + heiyan 短篇整篇 3983 篇。
+// 长篇章尺度（中位约 2100 字）per-kilo 1.0→1.5 误报 0.43%→0.39%，几乎不动；
+// 短篇整篇 8000-20000 字下 MIN_HITS 形同虚设、只剩密度门，1.0 时误报 5.57%，
+// 1.5 降到 1.46%。故取 1.5，把两个总体拉到同一量级（四份副本共用一组阈值）。
+const STOCK_REACTION_PER_KILO = 1.5;
+
 // 监控摄像头式动作清单：同一段连续堆叠通用动作动词（伸手/拿起/取过/挑开/放下/转身等），
 // 且用逗号/顿号串联成步骤表时，读感像无视角温度的监控记录。只做 advisory；
 // 打斗/追逐等功能性动作编排可保留或人工复核。
@@ -406,6 +427,7 @@ function scanProsePatterns(proseLines) {
   findings.push(...findQuoteEmphasisTic(proseLines));
   findings.push(...findPeriodStutter(proseLines));
   findings.push(...findMicroActionTic(proseLines));
+  findings.push(...findStockReactionTic(proseLines));
   findings.push(...findActionListTic(proseLines));
   findings.push(...findAbstractSummaryTic(proseLines));
   findings.push(...findClicheDensityTic(proseLines));
@@ -700,6 +722,47 @@ function findMicroActionTic(proseLines) {
   }];
 }
 
+// 套式反应细节：统计引号外叙述中通用的部位/声线反应与固定语气比喻。
+// 这是删除测试的候选集，不是身体描写黑名单；全篇只报一条，保留有动作后果、
+// 伤势、人物习惯或情节功能的细节。
+function findStockReactionTic(proseLines) {
+  let hits = 0;
+  let narrativeChars = 0;
+  let firstLine = null;
+  const samples = [];
+
+  for (const { text, lineNo } of proseLines) {
+    const trimmed = text.trim();
+    if (!trimmed || isDivider(trimmed) || isStructural(trimmed)) continue;
+    const narrative = stripQuoted(trimmed);
+    narrativeChars += visibleLength(narrative);
+
+    for (const pattern of STOCK_REACTION_PATTERNS) {
+      pattern.lastIndex = 0;
+      let match;
+      while ((match = pattern.exec(narrative)) !== null) {
+        hits += 1;
+        if (firstLine === null) firstLine = lineNo;
+        const sample = sentenceAround(narrative, match.index);
+        if (samples.length < 6 && sample && !samples.includes(sample)) samples.push(sample);
+      }
+    }
+  }
+
+  if (narrativeChars === 0 || hits < STOCK_REACTION_MIN_HITS) return [];
+  const perKilo = (hits / narrativeChars) * 1000;
+  if (perKilo < STOCK_REACTION_PER_KILO) return [];
+
+  return [{
+    line: firstLine,
+    column: 1,
+    type: 'stock-reaction-tic',
+    severity: 'advisory',
+    message: `套式反应细节：指尖/指节/喉结/眼圈/声音放轻等通用反应或“平静得像在念”式语气比喻 ${hits} 处（${perKilo.toFixed(1)}/千字）；逐处做删除测试，只标注情绪、不改变选择、关系、物件或动作结果的删掉，不要换部位或同义动作。`,
+    excerpt: compact(samples.join(' | ')),
+  }];
+}
+
 function findActionListTic(proseLines) {
   const findings = [];
 

package/lib/oh-story/skills/story-review/scripts/tracking_commit.py

@@ -3,25 +3,40 @@
 
 The language model supplies compact semantic JSON.  This tool validates and
 merges that input in memory, renders every derived view, then atomically writes
-``_tracking-state.json`` last as the single commit point.  One book project has
-one serial writer; concurrent commits are intentionally unsupported.
+``_tracking-state.json`` last as the single commit point. Per-project locking
+serializes concurrent writers before revision and wordcount checks.
 """
 
 from __future__ import annotations
 
 import argparse
 import copy
+import importlib.util
 import json
 import os
 import re
 import stat
 import sys
 import tempfile
+import time
 import unicodedata
+from contextlib import contextmanager
 from pathlib import Path
 from typing import Any
 
 
+_WORDCOUNT_CORE_PATH = Path(__file__).with_name("wordcount_core.py")
+if not _WORDCOUNT_CORE_PATH.is_file():  # pragma: no cover - broken deployment
+    raise RuntimeError("TOOL_UNAVAILABLE: wordcount_core.py")
+_WORDCOUNT_CORE_SPEC = importlib.util.spec_from_file_location(
+    "story_wordcount_core", _WORDCOUNT_CORE_PATH
+)
+if _WORDCOUNT_CORE_SPEC is None or _WORDCOUNT_CORE_SPEC.loader is None:  # pragma: no cover
+    raise RuntimeError("unable to load wordcount core")
+wordcount_core = importlib.util.module_from_spec(_WORDCOUNT_CORE_SPEC)
+_WORDCOUNT_CORE_SPEC.loader.exec_module(wordcount_core)
+
+
 INPUT_SCHEMA_VERSION = 1
 TRACKING_SCHEMA_VERSION = 4
 DELTA_TARGET_BYTES = 1536
@@ -74,6 +89,13 @@ def require(condition: bool, message: str) -> None:
         raise TrackingError(message)
 
 
+def wordcount_value(function: Any, *args: Any, **kwargs: Any) -> Any:
+    try:
+        return function(*args, **kwargs)
+    except wordcount_core.WordcountError as exc:
+        raise TrackingError(str(exc)) from exc
+
+
 def as_mapping(value: object, label: str) -> dict[str, Any]:
     require(isinstance(value, dict), f"{label} must be a JSON object")
     return value
@@ -188,6 +210,34 @@ def state_path(project: Path) -> Path:
     return tracking_root(project) / "_tracking-state.json"
 
 
+@contextmanager
+def project_write_lock(project: Path, *, timeout_seconds: float = 10.0):
+    tracking = tracking_root(project)
+    tracking.mkdir(parents=True, exist_ok=True)
+    path = tracking / ".tracking-commit.lock"
+    deadline = time.monotonic() + timeout_seconds
+    descriptor: int | None = None
+    while descriptor is None:
+        try:
+            descriptor = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o644)
+        except FileExistsError:
+            if time.monotonic() >= deadline:
+                raise TrackingError(
+                    "tracking commit lock is busy or stale; retry, or remove 追踪/.tracking-commit.lock after confirming no commit is running"
+                )
+            time.sleep(0.05)
+    try:
+        os.write(descriptor, f"pid={os.getpid()}\n".encode("ascii"))
+        os.fsync(descriptor)
+        yield
+    finally:
+        os.close(descriptor)
+        try:
+            path.unlink()
+        except FileNotFoundError:
+            pass
+
+
 def delta_path(tracking: Path, chapter: int) -> Path:
     width = max(3, len(str(chapter)))
     return tracking / "逐章记录" / f"第{chapter:0{width}d}章.md"
@@ -735,6 +785,18 @@ def render_delta(chapter: int, title: str, delta: dict[str, Any], core_names: se
     return payload
 
 
+def normalize_wordcount_records(value: object, last_chapter: int) -> dict[str, dict[str, Any]]:
+    records = as_mapping(value, "tracking state.wordcount_records")
+    normalized: dict[str, dict[str, Any]] = {}
+    for raw_chapter, raw_record in records.items():
+        require(isinstance(raw_chapter, str) and re.fullmatch(r"[1-9]\d*", raw_chapter) is not None,
+                "wordcount record chapter key is invalid")
+        chapter = int(raw_chapter)
+        require(chapter <= last_chapter, "wordcount record exceeds last committed chapter")
+        normalized[raw_chapter] = wordcount_value(wordcount_core.normalize_wordcount_record, raw_record)
+    return normalized
+
+
 def normalize_state(document: object) -> dict[str, Any]:
     root = as_mapping(document, "tracking state")
     require_known_keys(
@@ -742,6 +804,7 @@ def normalize_state(document: object) -> dict[str, Any]:
         {
             "schema_version", "book_title", "last_committed_chapter", "imported_through_chapter",
             "state_revision", "context", "characters", "foreshadow", "timeline",
+            "wordcount_records",
         },
         "tracking state",
     )
@@ -766,16 +829,19 @@ def normalize_state(document: object) -> dict[str, Any]:
     if last_chapter == 0:
         require(not foreshadow, "a chapter-0 project cannot have planted foreshadow facts")
         require(not timeline, "a chapter-0 project cannot have established timeline facts")
+    state_revision = as_int(root.get("state_revision"), "tracking state.state_revision")
+    wordcount_records = normalize_wordcount_records(root.get("wordcount_records", {}), last_chapter)
     return {
         "schema_version": TRACKING_SCHEMA_VERSION,
         "book_title": clean_text(root.get("book_title"), "tracking state.book_title", max_bytes=240),
         "last_committed_chapter": last_chapter,
         "imported_through_chapter": imported_through,
-        "state_revision": as_int(root.get("state_revision"), "tracking state.state_revision"),
+        "state_revision": state_revision,
         "context": context,
         "characters": characters,
         "foreshadow": foreshadow,
         "timeline": timeline,
+        "wordcount_records": wordcount_records,
     }
 
 
@@ -789,7 +855,10 @@ def normalize_initial_document(document: object) -> dict[str, Any]:
     root = as_mapping(document, "init input")
     require_known_keys(
         root,
-        {"schema_version", "book_title", "last_chapter", "context", "character_snapshots", "foreshadow", "timeline_events"},
+        {
+            "schema_version", "book_title", "last_chapter", "context", "character_snapshots",
+            "foreshadow", "timeline_events",
+        },
         "init input",
     )
     require(root.get("schema_version") == INPUT_SCHEMA_VERSION, "init input schema_version is unsupported")
@@ -826,17 +895,18 @@ def normalize_initial_document(document: object) -> dict[str, Any]:
             "characters": snapshots,
             "foreshadow": foreshadow,
             "timeline": timeline,
+            "wordcount_records": {},
         }
     )
 
 
-def normalize_transaction(state: dict[str, Any], document: object) -> dict[str, Any]:
+def normalize_transaction(project: Path, state: dict[str, Any], document: object) -> dict[str, Any]:
     root = as_mapping(document, "transaction")
     require_known_keys(
         root,
         {
             "schema_version", "mode", "chapter", "chapter_title", "expected_state_revision",
-            "delta", "context", "character_snapshots",
+            "delta", "context", "character_snapshots", "wordcount",
         },
         "transaction",
     )
@@ -845,6 +915,7 @@ def normalize_transaction(state: dict[str, Any], document: object) -> dict[str,
     require(mode in {"append", "revision"}, "mode must be append or revision")
     chapter = as_int(root.get("chapter"), "chapter", minimum=1)
     expected_revision = as_int(root.get("expected_state_revision"), "expected_state_revision")
+    wordcount_input = root.get("wordcount")
     require(expected_revision == state["state_revision"], "tracking state changed since this transaction was prepared")
     last = state["last_committed_chapter"]
     if mode == "append":
@@ -864,6 +935,11 @@ def normalize_transaction(state: dict[str, Any], document: object) -> dict[str,
         snapshots=snapshots,
         existing_core_names=existing_names,
     )
+    wordcount = None
+    if wordcount_input is not None:
+        wordcount = wordcount_value(
+            wordcount_core.validate_current_wordcount_record, project, chapter, wordcount_input
+        )
     return {
         "mode": mode,
         "chapter": chapter,
@@ -871,6 +947,7 @@ def normalize_transaction(state: dict[str, Any], document: object) -> dict[str,
         "delta": delta,
         "context": context,
         "snapshots": snapshots,
+        "wordcount": wordcount,
     }
 
 
@@ -891,6 +968,8 @@ def merge_transaction(state: dict[str, Any], transaction: dict[str, Any]) -> dic
         next_state["last_committed_chapter"] = chapter
     next_state["state_revision"] += 1
     next_state["characters"].update(transaction["snapshots"])
+    if transaction["wordcount"] is not None:
+        next_state["wordcount_records"][str(chapter)] = transaction["wordcount"]
 
     next_context = transaction["context"]
     # 退役说的是「从此刻起离开当前状态」，只有 append 的逐章记录代表此刻；
@@ -1013,7 +1092,7 @@ def warn_sizes(views: dict[str, str], delta_payload: str | None = None) -> None:
             )
 
 
-def initialize(project: Path, document: object) -> dict[str, Any]:
+def _initialize_locked(project: Path, document: object) -> dict[str, Any]:
     tracking = tracking_root(project)
     require(not state_path(project).exists(), "tracking state already exists; init never overwrites project state")
     state = normalize_initial_document(document)
@@ -1036,11 +1115,16 @@ def initialize(project: Path, document: object) -> dict[str, Any]:
     return state
 
 
-def apply_transaction(project: Path, document: object) -> dict[str, Any]:
+def initialize(project: Path, document: object) -> dict[str, Any]:
+    with project_write_lock(project):
+        return _initialize_locked(project, document)
+
+
+def _apply_transaction_locked(project: Path, document: object) -> dict[str, Any]:
     tracking = tracking_root(project)
     require_no_retired_tracking_paths(tracking)
     state = load_state(project)
-    transaction = normalize_transaction(state, document)
+    transaction = normalize_transaction(project, state, document)
     next_state = merge_transaction(state, transaction)
 
     delta_payload = render_delta(
@@ -1067,6 +1151,11 @@ def apply_transaction(project: Path, document: object) -> dict[str, Any]:
     return next_state
 
 
+def apply_transaction(project: Path, document: object) -> dict[str, Any]:
+    with project_write_lock(project):
+        return _apply_transaction_locked(project, document)
+
+
 def check_project(project: Path) -> dict[str, Any]:
     tracking = tracking_root(project)
     require_no_retired_tracking_paths(tracking)

package/lib/oh-story/skills/story-review/scripts/wordcount_core.py

@@ -0,0 +1,246 @@
+#!/usr/bin/env python3
+"""Small deterministic wordcount core shared by storyctl and tracking."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from pathlib import Path
+from typing import Any
+
+
+WORDCOUNT_SCHEMA = "story-wordcount-result/v1"
+MEASUREMENT_SCHEMA = "story-wordcount-measurement/v1"
+CHECKPOINT_SCHEMA = "story-wordcount-checkpoint/v1"
+METRIC = "visible_chars_v1"
+RESOLUTIONS = frozenset({"within_user_band", "accepted_current_length"})
+
+_WHITE_SPACE_CODEPOINTS = frozenset(
+    [*range(0x0009, 0x000E)]
+    + [
+        0x0020, 0x0085, 0x00A0, 0x1680, *range(0x2000, 0x200B),
+        0x2028, 0x2029, 0x202F, 0x205F, 0x3000,
+    ]
+)
+_FRONTMATTER_KEY_RE = re.compile(r"^[A-Za-z_\u3400-\u9FFF][^:\n]{0,80}:[ \t]*(?:.*)$")
+_LEADING_BLANK_RE = re.compile(r"^[\u0009\u0020\u3000]*$")
+_ATX_HEADING_RE = re.compile(r"^[\u0009\u0020]{0,3}#{1,6}[\u0009\u0020]+\S")
+_POSITIVE_INTEGER_RE = re.compile(r"^[1-9]\d*$")
+_TARGET_LINE_RE = re.compile(r"^[ \t>*-]*字数目标[ \t]*[:：][ \t]*([1-9]\d*)[ \t]*(?:字)?[ \t]*$", re.MULTILINE)
+_METRIC_LINE_RE = re.compile(r"^[ \t>*-]*字数口径[ \t]*[:：][ \t]*([A-Za-z0-9_-]+)[ \t]*$", re.MULTILINE)
+
+
+class WordcountError(ValueError):
+    """Expected deterministic wordcount contract failure."""
+
+
+def require(condition: bool, message: str) -> None:
+    if not condition:
+        raise WordcountError(message)
+
+
+def normalize_newlines(value: str) -> str:
+    return value.replace("\r\n", "\n").replace("\r", "\n")
+
+
+def strip_recognizable_frontmatter(value: str) -> str:
+    lines = value.split("\n")
+    if not lines or lines[0] != "---":
+        return value
+    closing = next((index for index in range(1, min(len(lines), 201)) if lines[index] in {"---", "..."}), -1)
+    if closing < 2 or not any(_FRONTMATTER_KEY_RE.match(line) for line in lines[1:closing]):
+        return value
+    return "\n".join(lines[closing + 1 :])
+
+
+def visible_body(value: str) -> str:
+    if not isinstance(value, str):
+        raise TypeError("body must be a string")
+    text = normalize_newlines(value)
+    if text.startswith("\ufeff"):
+        text = text[1:]
+    lines = strip_recognizable_frontmatter(text).split("\n")
+    while lines and _LEADING_BLANK_RE.match(lines[0]):
+        lines.pop(0)
+    if lines and _ATX_HEADING_RE.match(lines[0]):
+        lines.pop(0)
+    return "\n".join(lines)
+
+
+def count_visible_chars(value: str) -> int:
+    return sum(ord(character) not in _WHITE_SPACE_CODEPOINTS for character in visible_body(value))
+
+
+def parse_target(value: Any) -> int:
+    raw = str(value if value is not None else "")
+    if not _POSITIVE_INTEGER_RE.fullmatch(raw):
+        raise WordcountError("target must be a positive integer")
+    target = int(raw)
+    require(target <= 9_007_199_254_740_991, "target exceeds Number.MAX_SAFE_INTEGER")
+    return target
+
+
+def compute_wordcount_bands(value: Any) -> dict[str, dict[str, int]]:
+    target = parse_target(value)
+    return {
+        "internal": {"min": (target * 88 + 99) // 100, "max": target * 112 // 100},
+        "user": {"min": (target * 85 + 99) // 100, "max": target * 115 // 100},
+    }
+
+
+def invalid_wordcount_result(
+    reason: str, *, chapter: Any = None, case_id: Any = None,
+    target: int | None = None, actual: int | None = None,
+) -> dict[str, Any]:
+    return {
+        "schema": WORDCOUNT_SCHEMA, "metric": METRIC, "chapter": chapter, "case_id": case_id,
+        "target": target, "actual": actual, "internal_band": None, "user_band": None,
+        "signed_error_pct": None, "absolute_error_pct": None,
+        "status": "invalid", "invalid_reason": reason,
+    }
+
+
+def measure_wordcount(value: str, *, chapter: Any = None, case_id: Any = None) -> dict[str, Any]:
+    try:
+        actual = count_visible_chars(value)
+    except (TypeError, ValueError):
+        return {
+            "schema": MEASUREMENT_SCHEMA, "metric": METRIC, "chapter": chapter,
+            "case_id": case_id, "actual": None, "status": "invalid", "invalid_reason": "INVALID_BODY",
+        }
+    return {
+        "schema": MEASUREMENT_SCHEMA, "metric": METRIC, "chapter": chapter,
+        "case_id": case_id, "actual": actual, "status": "measured", "invalid_reason": None,
+    }
+
+
+def evaluate_wordcount(
+    value: str, target_value: Any, *, chapter: Any = None, case_id: Any = None,
+) -> dict[str, Any]:
+    try:
+        target = parse_target(target_value)
+    except (TypeError, ValueError):
+        return invalid_wordcount_result("INVALID_TARGET", chapter=chapter, case_id=case_id)
+    try:
+        actual = count_visible_chars(value)
+    except (TypeError, ValueError):
+        return invalid_wordcount_result("INVALID_BODY", chapter=chapter, case_id=case_id, target=target)
+    if actual == 0:
+        return invalid_wordcount_result("EMPTY_BODY", chapter=chapter, case_id=case_id, target=target, actual=actual)
+    bands = compute_wordcount_bands(target)
+    internal_pass = bands["internal"]["min"] <= actual <= bands["internal"]["max"]
+    user_pass = bands["user"]["min"] <= actual <= bands["user"]["max"]
+    status = "internal_pass" if internal_pass else (
+        "borderline" if user_pass else ("under" if actual < bands["user"]["min"] else "over")
+    )
+    signed_error = (actual - target) / target
+    return {
+        "schema": WORDCOUNT_SCHEMA, "metric": METRIC, "chapter": chapter, "case_id": case_id,
+        "target": target, "actual": actual,
+        "internal_band": {**bands["internal"], "status": "pass" if internal_pass else "fail"},
+        "user_band": {**bands["user"], "status": "pass" if user_pass else "fail"},
+        "signed_error_pct": signed_error, "absolute_error_pct": abs(signed_error),
+        "status": status, "invalid_reason": None,
+    }
+
+
+def checkpoint_wordcount(
+    value: str, target_value: Any, *, chapter: Any = None, case_id: Any = None,
+) -> dict[str, Any]:
+    target = parse_target(target_value)
+    actual = count_visible_chars(value)
+    user = compute_wordcount_bands(target)["user"]
+    return {
+        "schema": CHECKPOINT_SCHEMA, "metric": METRIC, "chapter": chapter, "case_id": case_id,
+        "target": target, "actual": actual, "user_band": user,
+        "remaining_user_range": {
+            "min": max(0, user["min"] - actual),
+            "max": max(0, user["max"] - actual),
+        },
+    }
+
+
+def target_from_outline(value: str) -> int:
+    text = normalize_newlines(value)
+    if text.startswith("\ufeff"):
+        text = text[1:]
+    targets = list(dict.fromkeys(_TARGET_LINE_RE.findall(text)))
+    metrics = list(dict.fromkeys(_METRIC_LINE_RE.findall(text)))
+    require(len(targets) == 1, "字数目标 must appear exactly once with one value")
+    require(metrics == [METRIC], f"字数口径 must appear exactly once as {METRIC}")
+    return parse_target(targets[0])
+
+
+def _chapter_number_from_name(name: str, *, outline: bool) -> int | None:
+    pattern = r"^细纲_第0*(\d+)章.*\.md$" if outline else r"^第0*(\d+)章(?:[_\- 　].*)?\.md$"
+    match = re.match(pattern, name)
+    return int(match.group(1)) if match else None
+
+
+def find_chapter_file(directory: Path, chapter: int, *, outline: bool) -> Path:
+    require(isinstance(chapter, int) and not isinstance(chapter, bool) and chapter >= 1, "chapter must be >= 1")
+    require(directory.is_dir(), f"chapter directory is missing: {directory}")
+    matches = sorted(
+        path for path in directory.iterdir()
+        if path.is_file() and _chapter_number_from_name(path.name, outline=outline) == chapter
+    )
+    label = "outline" if outline else "body"
+    require(len(matches) == 1, f"chapter {chapter} must have exactly one {label} file")
+    return matches[0]
+
+
+def build_project_wordcount_record(project: Path, chapter: int, *, resolution: str) -> dict[str, Any]:
+    require(resolution in RESOLUTIONS, f"unsupported wordcount resolution: {resolution}")
+    root = project.resolve()
+    outline_path = find_chapter_file(root / "大纲", chapter, outline=True)
+    body_path = find_chapter_file(root / "正文", chapter, outline=False)
+    try:
+        target = target_from_outline(outline_path.read_text(encoding="utf-8"))
+        body_bytes = body_path.read_bytes()
+        body = body_bytes.decode("utf-8")
+    except (OSError, UnicodeError) as exc:
+        raise WordcountError(f"unable to read chapter files: {exc}") from exc
+    result = evaluate_wordcount(body, target, chapter=chapter)
+    require(result["status"] != "invalid", f"invalid chapter wordcount: {result['invalid_reason']}")
+    in_user_band = result["status"] in {"internal_pass", "borderline"}
+    require(
+        (resolution == "within_user_band" and in_user_band)
+        or (resolution == "accepted_current_length" and not in_user_band),
+        "wordcount resolution does not match the current length",
+    )
+    return {
+        "metric": METRIC,
+        "target": result["target"],
+        "actual": result["actual"],
+        "status": result["status"],
+        "resolution": resolution,
+        "body_sha256": hashlib.sha256(body_bytes).hexdigest(),
+    }
+
+
+def normalize_wordcount_record(value: object) -> dict[str, Any]:
+    require(isinstance(value, dict), "wordcount record must be an object")
+    require(
+        set(value) == {"metric", "target", "actual", "status", "resolution", "body_sha256"},
+        "wordcount record fields are invalid",
+    )
+    require(value.get("metric") == METRIC, "wordcount metric is unsupported")
+    target = parse_target(value.get("target"))
+    actual = value.get("actual")
+    require(isinstance(actual, int) and not isinstance(actual, bool) and actual >= 1, "wordcount actual is invalid")
+    expected = evaluate_wordcount("字" * actual, target)
+    require(value.get("status") == expected["status"], "wordcount status does not match target and actual")
+    resolution = value.get("resolution")
+    require(resolution in RESOLUTIONS, "wordcount resolution is unsupported")
+    in_user_band = expected["status"] in {"internal_pass", "borderline"}
+    require((resolution == "within_user_band") == in_user_band, "wordcount resolution does not match status")
+    digest = value.get("body_sha256")
+    require(isinstance(digest, str) and re.fullmatch(r"[0-9a-f]{64}", digest) is not None, "body_sha256 is invalid")
+    return dict(value)
+
+
+def validate_current_wordcount_record(project: Path, chapter: int, value: object) -> dict[str, Any]:
+    record = normalize_wordcount_record(value)
+    current = build_project_wordcount_record(project, chapter, resolution=record["resolution"])
+    require(record == current, "wordcount record is stale for the current body or target")
+    return record