#!/usr/bin/env python3 """Fail when the work manual stops being readable without history or grows past its size limits. The work manual is the root `AGENTS.md` (the map and the rules that must hold) plus `docs/work/`. A Claude Code session reads the map through the root `CLAUDE.md`, which imports it (`@AGENTS.md`) and adds a few Claude-only lines. A session that has never seen this repository's history reads the map, `docs/work/README.md` and one playbook, and must be able to finish the job from those alone. Two things break that, and both are mechanical: 1. History IDs in the body. A sentence such as "fixed as in 1103/11-07" means nothing to a reader who does not know that review. History belongs in `docs/work/evidence.md` and the two reference files that are indexes of history (`reference/decisions.md`, `reference/defect-patterns.md`). The same rule covers the other files a new session reads first: the root `AGENTS.md` and `CLAUDE.md` and the documents under `.claude/` (rules, skills, subagents). Review documents keep their IDs. 2. Length. Each entry file has a line limit and the entry path (map + root `CLAUDE.md` + README + one playbook) has a total limit, so a session reads the whole path instead of skimming it. The map limit is 40 lines (owner decision 2026-11-07: the root holds the rules, the map and the router only). It also checks that every playbook keeps the shared nine-section skeleton, that the "common mistakes" section stays short, that `CLAUDE.md` starts with the import, and that relative links in the checked files resolve. The same layout and limits as the paired backend template's checker. Standard library only, so it runs on the laptop and in the edit hook (scripts/hooks/hooks.py, N2). `verify:documentation` (FE-GATE-017) checks the paths, scripts and gate IDs these documents name. python3 scripts/check-work-docs.py python3 scripts/check-work-docs.py --links docs README.md # relative links only, any files python3 scripts/check-work-docs.py --history docs/manual # history IDs only, any files """ from __future__ import annotations import re import sys from pathlib import Path REPO_ROOT = Path(__file__).resolve().parent.parent MAP = REPO_ROOT / "AGENTS.md" CLAUDE_ENTRY = REPO_ROOT / "CLAUDE.md" IMPORT_LINE = "@AGENTS.md" CLAUDE_FOLDERS = ("rules", "skills", "agents") WORK = REPO_ROOT / "docs/work" README = WORK / "README.md" PLAYBOOKS = [ "new-feature.md", "improve.md", "research-design.md", "docs-writing.md", "operate.md", "delegate.md", ] REFERENCES = [ "reference/gates.md", "reference/review-criteria.md", "reference/structure.md", "reference/testing.md", "reference/performance.md", "reference/defect-patterns.md", "reference/decisions.md", ] EVIDENCE = "evidence.md" # Files that may name history, relative to docs/work/. Everything else must not. HISTORY_ALLOWED = {EVIDENCE, "reference/decisions.md", "reference/defect-patterns.md"} MAP_LIMIT = 40 CLAUDE_ENTRY_LIMIT = 15 README_LIMIT = 80 PLAYBOOK_LIMIT = 150 ENTRY_PATH_LIMIT = 350 MISTAKES_LIMIT = 10 SKELETON = [ "1. 언제 쓰나", "2. 받아야 할 것", "3. 크기와 사고 순서", "4. 절차", "5. 완료 기준", "6. 하지 말 것", "7. 막혔을 때", "8. 보고 형식", "9. 자주 하는 실수", ] # Each pattern names a kind of history identifier. A match is a sentence that only a reader who # knows the past can follow. re.ASCII keeps \b and \w to ASCII: Python counts Korean letters as # word characters, so "1105/12-01과" would otherwise slip through. HISTORY_PATTERNS = [ ("review ID with a date prefix (MMDD/NN-MM)", re.compile(r"(? str: return path.relative_to(REPO_ROOT).as_posix() def line_count(path: Path) -> int: return len(path.read_text(encoding="utf-8").splitlines()) def check_exists(errors: list[str]) -> bool: expected = [MAP, CLAUDE_ENTRY, README, WORK / EVIDENCE] expected += [WORK / name for name in PLAYBOOKS + REFERENCES] missing = [rel(path) for path in expected if not path.is_file()] for name in missing: errors.append(f"{name}: missing") return not missing def check_limits(errors: list[str], report: list[str]) -> None: for path, limit in [(MAP, MAP_LIMIT), (CLAUDE_ENTRY, CLAUDE_ENTRY_LIMIT), (README, README_LIMIT)]: lines = line_count(path) report.append(f"{rel(path)}: {lines}/{limit}") if lines > limit: errors.append(f"{rel(path)}: {lines} lines, limit {limit}") base = line_count(MAP) + line_count(CLAUDE_ENTRY) + line_count(README) for name in PLAYBOOKS: path = WORK / name lines = line_count(path) entry = base + lines report.append(f"{rel(path)}: {lines}/{PLAYBOOK_LIMIT}, entry path {entry}/{ENTRY_PATH_LIMIT}") if lines > PLAYBOOK_LIMIT: errors.append(f"{rel(path)}: {lines} lines, limit {PLAYBOOK_LIMIT}") if entry > ENTRY_PATH_LIMIT: errors.append( f"{rel(path)}: entry path AGENTS.md + CLAUDE.md + docs/work/README.md + this file is {entry} lines," f" limit {ENTRY_PATH_LIMIT}" ) def outside_code_blocks(lines: list[str]) -> list[str]: """Blank out fenced code blocks, so an example such as a report template is not a section.""" kept: list[str] = [] fenced = False for line in lines: if line.lstrip().startswith("```"): fenced = not fenced kept.append("") else: kept.append("" if fenced else line) return kept def check_skeleton(errors: list[str]) -> None: for name in PLAYBOOKS: path = WORK / name lines = outside_code_blocks(path.read_text(encoding="utf-8").splitlines()) headings = [line[3:].strip() for line in lines if line.startswith("## ")] if headings != SKELETON: errors.append(f"{rel(path)}: sections must be exactly {SKELETON} in that order, found {headings}") continue start = lines.index("## " + SKELETON[-1]) items = [line for line in lines[start + 1:] if re.match(r"^(?:[-*]|\d+\.) ", line)] if len(items) > MISTAKES_LIMIT: errors.append( f"{rel(path)}: '{SKELETON[-1]}' has {len(items)} items, limit {MISTAKES_LIMIT}" " (move one to a reference file or delete one)" ) def check_claude_entry(errors: list[str]) -> None: """The root CLAUDE.md starts with the import, so a Claude Code session reads the map.""" lines = CLAUDE_ENTRY.read_text(encoding="utf-8").splitlines() if not lines or lines[0].strip() != IMPORT_LINE: errors.append(f"{rel(CLAUDE_ENTRY)}: the first line must be '{IMPORT_LINE}'") def claude_documents() -> list[Path]: """The tracked Claude Code documents a session reads: path rules, skills, subagent definitions. Only these folders: the rest of .claude/ is local state (worktrees, hook state, settings.local.json).""" return sorted(path for folder in CLAUDE_FOLDERS for path in (REPO_ROOT / ".claude" / folder).rglob("*.md")) def history_checked_files() -> list[Path]: files = [MAP, CLAUDE_ENTRY] + claude_documents() for path in sorted(WORK.rglob("*.md")): if path.relative_to(WORK).as_posix() not in HISTORY_ALLOWED: files.append(path) return files def history_match(line: str, following: str) -> tuple[str, str] | None: """The first history ID on this line, or one that a line break splits ("review\n1103/11-07").""" for label, pattern in HISTORY_PATTERNS: match = pattern.search(line) if match: return label, match.group(0) if not following.strip(): return None joined = line.rstrip() + " " + following.strip() for label, pattern in HISTORY_PATTERNS: for match in pattern.finditer(joined): if match.start() < len(line.rstrip()) < match.end(): return label, match.group(0) return None def history_hits(files: list[Path]) -> list[tuple[Path, int, str, str]]: hits = [] for path in files: lines = path.read_text(encoding="utf-8").splitlines() for number, line in enumerate(lines, start=1): found = history_match(line, lines[number] if number < len(lines) else "") if found: hits.append((path, number, *found)) return hits def broken_links(files: list[Path]) -> tuple[int, list[tuple[Path, int, str]]]: checked = 0 broken = [] for path in files: for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1): for target in LINK.findall(line): if re.match(r"^[a-z][a-z0-9+.-]*:", target) or target.startswith("#"): continue checked += 1 if not (path.parent / target.split("#", 1)[0]).exists(): broken.append((path, number, target)) return checked, broken def check_history(errors: list[str], report: list[str]) -> None: hits = history_hits(history_checked_files()) for path, number, label, text in hits: errors.append( f"{rel(path)}:{number}: {label} '{text}'" " - write the content instead, and move the ID to docs/work/evidence.md" ) report.append(f"history ID lines in checked files: {len(hits)}") def check_links(errors: list[str], report: list[str]) -> None: checked, broken = broken_links([MAP, CLAUDE_ENTRY] + sorted(WORK.rglob("*.md")) + claude_documents()) for path, number, target in broken: errors.append(f"{rel(path)}:{number}: broken relative link '{target}'") report.append(f"relative links checked: {checked}") def markdown_files(targets: list[str]) -> list[Path]: files: list[Path] = [] for target in targets: path = (Path.cwd() / target).resolve() files += sorted(path.rglob("*.md")) if path.is_dir() else [path] return files def links_only(targets: list[str]) -> int: files = markdown_files(targets) checked, broken = broken_links(files) print(f"files: {len(files)}, relative links checked: {checked}, broken: {len(broken)}") for path, number, target in broken: print(f" {path}:{number}: broken relative link '{target}'", file=sys.stderr) return 1 if broken else 0 def history_only(targets: list[str]) -> int: files = markdown_files(targets) hits = history_hits(files) print(f"files: {len(files)}, lines with history IDs: {len(hits)}") for path, number, label, text in hits: print(f" {path}:{number}: {label} '{text}'", file=sys.stderr) return 1 if hits else 0 MODES = {"--links": links_only, "--history": history_only} def main() -> int: if sys.argv[1:2] and sys.argv[1] in MODES: if len(sys.argv) < 3: print(f"usage: check-work-docs.py {sys.argv[1]} ...", file=sys.stderr) return 2 return MODES[sys.argv[1]](sys.argv[2:]) errors: list[str] = [] report: list[str] = [] if check_exists(errors): check_limits(errors, report) check_claude_entry(errors) check_skeleton(errors) check_history(errors, report) check_links(errors, report) for line in report: print(line) if errors: print(f"\nFAILED: {len(errors)} problem(s)", file=sys.stderr) for error in errors: print(f" {error}", file=sys.stderr) return 1 print("\nOK") return 0 if __name__ == "__main__": sys.exit(main())