@oh-story/dsh 0.1.3 → 0.1.5

package/lib/oh-story/skills/story-long-write/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-long-write/scripts/check-outline-contract.js

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+/**
+ * Deterministic 细纲 structural verifier for story-long-write.
+ *
+ * Usage:
+ *   node scripts/check-outline-contract.js --json <细纲路径...>
+ *   node scripts/check-outline-contract.js --json --project <书目录> --chapter N
+ * Exit: 0 = pass, 1 = blocking contract failures, 2 = invalid invocation.
+ *
+ * Scope is structural only: it decides whether the blueprint carries the fields,
+ * subsections and table shape the authoritative template names. It never judges
+ * whether a value is good. The contract itself sets this granularity —
+ * artifact-protocols.md 要求未知字段写 `[待补充]`，所以字段必须在场，值可以未知。
+ */
+
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+// 权威模板：references/workflow-setup.md「细纲（全书每章）」
+const FIELDS = [
+  '核心事件', '字数目标', '字数口径', '阶段位置', '单元ID/位置', '目标情绪',
+  '主角目标/关键选择', '章节定位', '本章结构公式', '章首钩子', '爽点',
+  '本章禁止提前释放', '契约风险',
+]
+const SUBSECTIONS = ['内容概括', '情节安排', '人物关系和出场顺序', '情节细化']
+const FIVE_ACT = ['起因', '发展', '转折', '高潮', '结尾']
+const PLOT_HEADER_FIRST = /^(?:#|序号)$/
+// 这两个字段实测直接影响正文质量，必须有实际内容
+const INTENT_FIELDS = ['目标情绪', '主角目标/关键选择']
+const CALIBER = 'visible_chars_v1'
+
+function fieldPattern(name) {
+  // 允许 -/*/+ 项目符号、可选 ** 加粗、全角或半角冒号
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  return new RegExp(`^\\s*[-*+]\\s*\\*{0,2}${escaped}\\*{0,2}\\s*[：:]`, 'm')
+}
+
+function readUtf8(file) {
+  try {
+    const text = fs.readFileSync(file, 'utf8').replace(/^/, '')
+    return { ok: text.trim().length > 0, text }
+  } catch (error) {
+    return { ok: false, text: '', error: error.message }
+  }
+}
+
+function makeCheck(id, ok, file, evidence, expected, repair) {
+  return {
+    id,
+    ok,
+    severity: 'blocking',
+    file,
+    evidence,
+    expected,
+    references: ['references/workflow-setup.md', 'references/artifact-protocols.md'],
+    repair,
+  }
+}
+
+function parseTableRow(line) {
+  const trimmed = line.trim()
+  if (!trimmed.startsWith('|') || !trimmed.endsWith('|')) return null
+  return trimmed.slice(1, -1).split('|').map((cell) => cell.replace(/\*\*/g, '').replace(/`/g, '').trim())
+}
+
+function verify(file) {
+  const name = path.basename(file)
+  const read = readUtf8(file)
+  const checks = []
+
+  checks.push(makeCheck(
+    'outline.readable',
+    read.ok,
+    name,
+    read.ok ? '文件存在且非空' : (read.error || '文件为空'),
+    '细纲文件存在且非空',
+    '只补建缺失的细纲文件，不改动同批其他章。'
+  ))
+  if (!read.ok) return report(file, checks)
+  const text = read.text
+
+  const missingFields = FIELDS.filter((field) => !fieldPattern(field).test(text))
+  checks.push(makeCheck(
+    'outline.required-fields',
+    missingFields.length === 0,
+    name,
+    missingFields.length ? `缺字段：${missingFields.join('、')}` : `${FIELDS.length} 个字段齐全`,
+    `按权威模板列出全部字段：${FIELDS.join('、')}；值未知时写 [待补充]，不杜撰剧情`,
+    '只补报告里缺的字段行；确实还定不下来的写 [待补充]，不为补字段新增副线或人物关系。'
+  ))
+
+  // 隔离实验（同章、同写作流程，只改细纲）：只补这两个字段就能复现补齐全部字段的收益，
+  // 盲评 3/3 胜过不补；补满五个字段与只补这两个不可区分。所以这两个字段不接受占位符，
+  // 其余字段仍按契约允许 [待补充]。
+  const hollow = INTENT_FIELDS.filter((field) => {
+    const match = text.match(new RegExp(`^\\s*[-*+]\\s*\\*{0,2}${field.replace('/', '\\/')}\\*{0,2}\\s*[：:]\\s*(.*)$`, 'm'))
+    if (!match) return false
+    const value = match[1].replace(/\[待补充\]/g, '').replace(/[\s、，,。;；]/g, '')
+    return value.length === 0
+  })
+  checks.push(makeCheck(
+    'outline.intent-fields-substantive',
+    hollow.length === 0,
+    name,
+    hollow.length ? `只有占位符，没有实际内容：${hollow.join('、')}` : '目标情绪与主角目标/关键选择都写了实际内容',
+    '目标情绪写清前状态→后状态；主角目标/关键选择写清本章要什么、必须做出的判断。这两项不接受 [待补充]',
+    '只把这两个字段替换成本章的实际情绪变化与实际取舍；其余字段不动。'
+  ))
+
+  const missingSubs = SUBSECTIONS.filter((sub) => !new RegExp(`^#{3,4}\\s*${sub}`, 'm').test(text))
+  checks.push(makeCheck(
+    'outline.subsections',
+    missingSubs.length === 0,
+    name,
+    missingSubs.length ? `缺小节：${missingSubs.join('、')}` : '四个小节齐全',
+    '包含 内容概括 / 情节安排 / 人物关系和出场顺序 / 情节细化 四个小节',
+    '只补缺失的小节标题及其条目，不重写已成立的内容。'
+  ))
+
+  const missingActs = FIVE_ACT.filter((act) => !fieldPattern(act).test(text))
+  checks.push(makeCheck(
+    'outline.five-act',
+    missingActs.length === 0,
+    name,
+    missingActs.length ? `五段式缺：${missingActs.join('、')}` : '五段式齐全',
+    '内容概括写全 起因 / 发展 / 转折 / 高潮 / 结尾',
+    '只补缺的那一段，不改其余四段。'
+  ))
+
+  const lines = text.split(/\r?\n/)
+  let header = null
+  for (const line of lines) {
+    const cells = parseTableRow(line)
+    if (cells && cells.length === 4 && PLOT_HEADER_FIRST.test(cells[0])) {
+      header = cells
+      break
+    }
+  }
+  const headerOk = Boolean(header) && header[2].includes('功能标签') && header[3].includes('执行边界')
+  checks.push(makeCheck(
+    'outline.plotpoint-table',
+    headerOk,
+    name,
+    header ? `表头：${header.join(' | ')}` : '未找到 | # | 情节点 | 功能标签 | 执行边界 | 表头',
+    '情节细化使用四列表格：# / 情节点（谁做了什么） / 功能标签 / 执行边界',
+    '只把情节点序列改成四列表格，逐点补功能标签与执行边界；不增删情节点本身。'
+  ))
+
+  const targetMatch = text.match(/字数目标\s*[：:]\s*(?:约\s*)?([\d,，]+)/)
+  const target = targetMatch ? Number(targetMatch[1].replace(/[,，]/g, '')) : null
+  const caliberOk = new RegExp(`字数口径\\s*[：:]\\s*${CALIBER}`).test(text)
+  checks.push(makeCheck(
+    'outline.wordcount-target',
+    Boolean(target) && Number.isFinite(target) && target >= 500 && target <= 20000 && caliberOk,
+    name,
+    `字数目标：${target === null ? '未识别' : target}；字数口径 ${CALIBER}：${caliberOk}`,
+    `字数目标为 500-20000 的正整数，并声明 字数口径：${CALIBER}`,
+    '只补字数目标或字数口径行，不调整情节安排。'
+  ))
+
+  return report(file, checks)
+}
+
+function report(file, checks) {
+  const failures = checks.filter((check) => !check.ok)
+  return {
+    schema_version: 1,
+    verifier: 'story-long-write.outline-contract',
+    file: path.resolve(file),
+    ok: failures.length === 0,
+    checks,
+    failures,
+    repair_scope: failures.map((failure) => ({
+      id: failure.id,
+      file: failure.file,
+      evidence: failure.evidence,
+      expected: failure.expected,
+      references: failure.references,
+      repair: failure.repair,
+    })),
+  }
+}
+
+function resolveChapter(project, chapter) {
+  const dir = path.join(project, '大纲')
+  let entries
+  try {
+    entries = fs.readdirSync(dir)
+  } catch (error) {
+    return { error: `无法读取 ${dir}：${error.message}` }
+  }
+  const wanted = Number(chapter)
+  const hit = entries.find((entry) => {
+    const match = entry.match(/^细纲_第0*(\d+)章.*\.md$/)
+    return match && Number(match[1]) === wanted
+  })
+  if (!hit) return { error: `${dir} 下没有第 ${wanted} 章细纲` }
+  return { file: path.join(dir, hit) }
+}
+
+function parseArgs(argv) {
+  const files = []
+  let project = null
+  let chapter = null
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index]
+    if (arg === '--json') continue
+    if (arg === '--project' || arg === '--chapter') {
+      if (index + 1 >= argv.length || argv[index + 1].startsWith('--')) return null
+      const value = argv[++index]
+      if (arg === '--project') project = value
+      else chapter = value
+      continue
+    }
+    if (arg.startsWith('--')) return null
+    files.push(arg)
+  }
+  if (project || chapter) {
+    if (!project || !chapter || files.length || !/^\d+$/.test(chapter)) return null
+    return { project, chapter }
+  }
+  if (!files.length) return null
+  return { files }
+}
+
+function main(argv) {
+  const parsed = parseArgs(argv)
+  if (!parsed) {
+    process.stderr.write('用法: node scripts/check-outline-contract.js --json <细纲路径...> | --json --project <书目录> --chapter N\n')
+    return 2
+  }
+  let targets = parsed.files
+  if (!targets) {
+    const resolved = resolveChapter(parsed.project, parsed.chapter)
+    if (resolved.error) {
+      process.stderr.write(`${resolved.error}\n`)
+      return 2
+    }
+    targets = [resolved.file]
+  }
+  const reports = targets.map((file) => verify(file))
+  const ok = reports.every((entry) => entry.ok)
+  process.stdout.write(`${JSON.stringify(reports.length === 1 ? reports[0] : reports, null, 2)}\n`)
+  return ok ? 0 : 1
+}
+
+if (require.main === module) process.exitCode = main(process.argv.slice(2))
+
+module.exports = { verify, FIELDS, SUBSECTIONS, FIVE_ACT }

package/lib/oh-story/skills/story-long-write/scripts/storyctl.py

@@ -0,0 +1,303 @@
+#!/usr/bin/env python3
+"""Measure, checkpoint, check, and commit long-form story chapters."""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any, Sequence
+
+
+def _load_local_module(name: str, filename: str) -> Any:
+    path = Path(__file__).with_name(filename)
+    spec = importlib.util.spec_from_file_location(name, path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"TOOL_UNAVAILABLE: {filename}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+core = _load_local_module("story_wordcount_core", "wordcount_core.py")
+for _name in dir(core):
+    if not _name.startswith("_"):
+        globals()[_name] = getattr(core, _name)
+
+CHAPTER_CHECK_SCHEMA = "story-chapter-check/v1"
+CHAPTER_ERROR_SCHEMA = "story-chapter-error/v1"
+
+
+class CliArgumentError(ValueError):
+    pass
+
+
+class StructuredArgumentParser(argparse.ArgumentParser):
+    def error(self, message: str) -> None:
+        raise CliArgumentError(message)
+
+
+def _tracking_module() -> Any:
+    return _load_local_module("story_tracking_for_storyctl", "tracking_commit.py")
+
+
+def _tracking_call(function: Any, *args: Any) -> Any:
+    try:
+        return function(*args)
+    except Exception as exc:
+        if exc.__class__.__name__ == "TrackingError":
+            raise WordcountError(str(exc)) from exc
+        raise
+
+
+def _json_line(payload: dict[str, Any]) -> None:
+    rendered = json.dumps(payload, ensure_ascii=False, separators=(",", ":")) + "\n"
+    # Windows runners may expose a cp1252 console even when callers explicitly
+    # consume UTF-8.  Write protocol output as bytes so JSON never depends on
+    # the host console code page.
+    sys.stdout.buffer.write(rendered.encode("utf-8"))
+    sys.stdout.buffer.flush()
+
+
+def _read_json_object(path: Path, label: str) -> dict[str, Any]:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise WordcountError(f"unable to read {label}: {exc}") from exc
+    require(isinstance(value, dict), f"{label} must be an object")
+    return value
+
+
+def _project_files(project: Path, chapter: int) -> tuple[Path, Path, int]:
+    root = project.resolve()
+    outline = find_chapter_file(root / "大纲", chapter, outline=True)
+    body = find_chapter_file(root / "正文", chapter, outline=False)
+    try:
+        target = target_from_outline(outline.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError) as exc:
+        raise WordcountError(f"unable to read outline: {exc}") from exc
+    return outline, body, target
+
+
+def _json_findings(output: str) -> list[dict[str, Any]]:
+    try:
+        value = json.loads(output or "{}")
+    except json.JSONDecodeError:
+        return []
+    findings = value.get("findings", []) if isinstance(value, dict) else []
+    return findings if isinstance(findings, list) else []
+
+
+def check_blocking_quality(outline: Path, body: Path) -> dict[str, Any]:
+    node = shutil.which("node")
+    if node is None:
+        return {
+            "status": "fail",
+            "blocking_findings": [{"type": "TOOL_UNAVAILABLE", "message": "node is required for quality checks"}],
+            "advisories": [],
+        }
+    root = Path(__file__).parent
+    blocking: list[dict[str, Any]] = []
+    advisories: list[dict[str, Any]] = []
+    for name, script in (
+        ("ai-pattern", "check-ai-patterns.js"),
+        ("degeneration", "check-degeneration.js"),
+    ):
+        path = root / script
+        if not path.is_file():
+            blocking.append({"type": "TOOL_UNAVAILABLE", "message": f"missing {script}"})
+            continue
+        completed = subprocess.run(
+            [node, str(path), "--check", "--json", "--fail-on=blocking", str(body)],
+            text=True, encoding="utf-8", capture_output=True, check=False,
+        )
+        findings = _json_findings(completed.stdout)
+        for finding in findings:
+            row = {"source": name, **finding}
+            (blocking if finding.get("severity") == "blocking" else advisories).append(row)
+        if completed.returncode not in {0, 1}:
+            blocking.append({"type": "TOOL_ERROR", "source": name, "message": completed.stderr.strip()})
+
+    punctuation = root / "normalize-punctuation.js"
+    if not punctuation.is_file():
+        blocking.append({"type": "TOOL_UNAVAILABLE", "message": "missing normalize-punctuation.js"})
+    else:
+        completed = subprocess.run(
+            [node, str(punctuation), "--check", str(body)],
+            text=True, encoding="utf-8", capture_output=True, check=False,
+        )
+        if completed.returncode != 0:
+            blocking.append(
+                {"type": "PUNCTUATION_NOT_NORMALIZED", "message": (completed.stdout or completed.stderr).strip()}
+            )
+
+    outline_copy = root / "check-outline-copy.js"
+    if not outline_copy.is_file():
+        blocking.append({"type": "TOOL_UNAVAILABLE", "message": "missing check-outline-copy.js"})
+    else:
+        completed = subprocess.run(
+            [node, str(outline_copy), "--outline", str(outline), str(body)],
+            text=True, encoding="utf-8", capture_output=True, check=False,
+        )
+        if completed.returncode != 0:
+            advisories.append(
+                {"source": "outline-copy", "type": "OUTLINE_COPY_REVIEW", "message": completed.stdout.strip()}
+            )
+    return {
+        "status": "fail" if blocking else "pass",
+        "blocking_findings": blocking,
+        "advisories": advisories,
+    }
+
+
+def chapter_check(project: Path, chapter: int) -> dict[str, Any]:
+    outline, body_path, target = _project_files(project, chapter)
+    try:
+        body = body_path.read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as exc:
+        raise WordcountError(f"unable to read body: {exc}") from exc
+    length = evaluate_wordcount(body, target, chapter=chapter)
+    quality = check_blocking_quality(outline, body_path)
+    length_ok = length["status"] in {"internal_pass", "borderline"}
+    if quality["status"] != "pass" or length["status"] == "invalid":
+        actions: list[str] = []
+    elif length_ok:
+        actions = ["commit"]
+    elif length["status"] == "over":
+        actions = ["compress-once", "accept-current-length", "revise-outline-or-target", "discard"]
+    else:
+        actions = ["accept-current-length", "revise-outline-or-target", "discard"]
+    tracking = _tracking_module()
+    state = _tracking_call(tracking.load_state, project)
+    compression = None
+    if length["status"] == "over" and quality["status"] == "pass":
+        actual = length["actual"]
+        compression = {
+            "mode": "single_pass_remove_only",
+            "remove_to_internal_band": {
+                "min": actual - length["internal_band"]["max"],
+                "max": actual - length["internal_band"]["min"],
+            },
+            "remove_to_user_band": {
+                "min": actual - length["user_band"]["max"],
+                "max": actual - length["user_band"]["min"],
+            },
+        }
+    return {
+        "schema": CHAPTER_CHECK_SCHEMA,
+        "chapter": chapter,
+        "length": length,
+        "quality": quality,
+        "compression": compression,
+        "state_revision": state["state_revision"],
+        "tracking_committed": state["last_committed_chapter"] >= chapter,
+        "next_chapter_started": state["last_committed_chapter"] > chapter,
+        "available_actions": actions,
+    }
+
+
+def chapter_commit(project: Path, chapter: int, input_path: Path, *, accept_current_length: bool) -> dict[str, Any]:
+    checked = chapter_check(project, chapter)
+    require(checked["quality"]["status"] == "pass", "blocking quality findings must be fixed before commit")
+    length_status = checked["length"]["status"]
+    in_user_band = length_status in {"internal_pass", "borderline"}
+    if accept_current_length:
+        require(length_status in {"under", "over"}, "accept-current-length requires a valid out-of-band chapter")
+        resolution = "accepted_current_length"
+    else:
+        require(in_user_band, "chapter length is outside the user band; use accept-current-length or revise it")
+        resolution = "within_user_band"
+    document = _read_json_object(input_path, "tracking transaction")
+    require(document.get("chapter") == chapter, "tracking transaction chapter does not match command")
+    require("wordcount" not in document, "tracking transaction must not provide wordcount")
+    document["wordcount"] = build_project_wordcount_record(project, chapter, resolution=resolution)
+    tracking = _tracking_module()
+    state = _tracking_call(tracking.apply_transaction, project, document)
+    checked["tracking_committed"] = state["last_committed_chapter"] >= chapter
+    checked["next_chapter_started"] = state["last_committed_chapter"] > chapter
+    checked["wordcount"] = state["wordcount_records"].get(str(chapter))
+    return checked
+
+
+def _build_parser() -> StructuredArgumentParser:
+    parser = StructuredArgumentParser(prog="storyctl.py")
+    commands = parser.add_subparsers(dest="command", required=True)
+    wordcount = commands.add_parser("wordcount")
+    wordcount_commands = wordcount.add_subparsers(dest="wordcount_command", required=True)
+    for command in ("measure", "check", "checkpoint"):
+        subparser = wordcount_commands.add_parser(command)
+        subparser.add_argument("--file", required=True)
+        subparser.add_argument("--chapter")
+        subparser.add_argument("--case-id")
+        if command != "measure":
+            subparser.add_argument("--target", required=True)
+    chapter = commands.add_parser("chapter")
+    chapter_commands = chapter.add_subparsers(dest="chapter_command", required=True)
+    for command in ("check", "commit", "accept-current-length"):
+        subparser = chapter_commands.add_parser(command)
+        subparser.add_argument("--project", type=Path, required=True)
+        subparser.add_argument("--chapter", type=int, required=True)
+        if command != "check":
+            subparser.add_argument("--input", type=Path, required=True)
+    return parser
+
+
+def _wordcount_command(args: argparse.Namespace) -> int:
+    try:
+        body = Path(args.file).read_text(encoding="utf-8")
+    except (OSError, UnicodeError):
+        result = (
+            {"schema": MEASUREMENT_SCHEMA, "metric": METRIC, "chapter": args.chapter, "case_id": args.case_id,
+             "actual": None, "status": "invalid", "invalid_reason": "INVALID_FILE"}
+            if args.wordcount_command == "measure"
+            else invalid_wordcount_result("INVALID_FILE", chapter=args.chapter, case_id=args.case_id)
+        )
+        _json_line(result)
+        return 2
+    if args.wordcount_command == "measure":
+        result = measure_wordcount(body, chapter=args.chapter, case_id=args.case_id)
+    elif args.wordcount_command == "checkpoint":
+        try:
+            result = checkpoint_wordcount(body, args.target, chapter=args.chapter, case_id=args.case_id)
+        except WordcountError:
+            result = invalid_wordcount_result("INVALID_TARGET", chapter=args.chapter, case_id=args.case_id)
+    else:
+        result = evaluate_wordcount(body, args.target, chapter=args.chapter, case_id=args.case_id)
+    _json_line(result)
+    return 2 if result.get("status") == "invalid" else 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    raw = list(argv) if argv is not None else sys.argv[1:]
+    try:
+        args = _build_parser().parse_args(raw)
+    except CliArgumentError as exc:
+        payload = (
+            {"schema": CHAPTER_ERROR_SCHEMA, "error_code": "INVALID_ARGUMENT", "message": str(exc)}
+            if raw[:1] == ["chapter"] else invalid_wordcount_result("INVALID_ARGUMENT", case_id=str(exc))
+        )
+        _json_line(payload)
+        return 2
+    if args.command == "wordcount":
+        return _wordcount_command(args)
+    try:
+        if args.chapter_command == "check":
+            result = chapter_check(args.project, args.chapter)
+        else:
+            result = chapter_commit(
+                args.project, args.chapter, args.input,
+                accept_current_length=args.chapter_command == "accept-current-length",
+            )
+    except (WordcountError, OSError, UnicodeError) as exc:
+        _json_line({"schema": CHAPTER_ERROR_SCHEMA, "error_code": "CHECK_FAILED", "message": str(exc)})
+        return 2
+    _json_line(result)
+    return 2 if result["quality"]["status"] != "pass" else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())