docs(context): answer the review of the repo-map split

- repo-stats reads the gotcha list from context/gotchas.md (the digest in
  repo-map.md no longer measures the doc-growth signal) and reports it as
  `docs.gotchas`; the test fixture and its derived expectations follow.
- AGENTS.md and the wave agent-rules protect gotchas.md and
  file-inventory.md like the repo map they were split from.
- doc-site.md's publication table lists the two new pages.
- file-inventory.md's Context docs rows describe the three files correctly.
- the code-review skill points at gotchas.md for the long form.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

scripts/repo-stats

@@ -189,12 +189,9 @@ def read_rows(path):
 
 
 def gotchas(text):
-    """(number, lines, chars) for each numbered item of repo-map's Gotchas section."""
-    out, cur, inside = [], None, False
+    """(number, lines, chars) for each numbered item of context/gotchas.md."""
+    out, cur, inside = [], None, True
     for line in text.split("\n"):
-        if line.startswith("## "):
-            inside = line.startswith("## Gotchas")
-            continue
         if inside and line.startswith("---"):
             inside = False
         if not inside:
@@ -214,13 +211,13 @@ def doc_sizes(repo, sha):
                             "context").split("\n") if p.endswith(".md")]
     show = lambda p: git(repo, "show", f"{sha}:{p}")
     lines = {p: len(show(p).splitlines()) for p in sorted(files)}
-    gs = gotchas(show("context/repo-map.md")) if "context/repo-map.md" in files else []
+    gs = gotchas(show("context/gotchas.md")) if "context/gotchas.md" in files else []
     longest = max(gs, key=lambda g: g[2], default=None)
     evidence = {p: sum(1 for l in show(p).split("\n") if re.match(r"^#{3,4} ", l))
                 for p in sorted(files) if p.startswith("context/test-evidence/")}
     return {
         "context_lines": lines,
-        "repo_map": {"gotchas": len(gs), "longest": longest and
+        "gotchas": {"count": len(gs), "longest": longest and
                      {"number": longest[0], "lines": longest[1], "chars": longest[2]}},
         "test_evidence": {"entries": sum(evidence.values()), "per_file": evidence},
     }
@@ -270,9 +267,9 @@ def text(r, top):
             out += ["", TITLES[t]] + table(r["tables"][t])
     out += ["", "Doc sizes (lines)"]
     out += [f"  {n:>6}  {path}" for path, n in r["docs"]["context_lines"].items()]
-    rm, te = r["docs"]["repo_map"], r["docs"]["test_evidence"]
+    rm, te = r["docs"]["gotchas"], r["docs"]["test_evidence"]
     lg = rm["longest"]
-    out.append(f"  repo-map gotchas: {rm['gotchas']}" + (
+    out.append(f"  gotchas: {rm['count']}" + (
         f"; longest is {lg['number']} ({lg['lines']} lines, {lg['chars']} chars)"
         if lg else ""))
     out.append(f"  test-evidence entries: {te['entries']}")

scripts/repo-stats-test.sh

@@ -76,10 +76,9 @@ put context/code/x.md 8 x3
 mkdir -p "$repo/context/test-evidence"
 printf '### t_one\ntext\n#### t_two\n## not an entry\n### t_three\n' \
   > "$repo/context/test-evidence/y.md"
-cat > "$repo/context/repo-map.md" <<'EOF'
-# Map
-
-## Gotchas (read before editing)
+printf '# Map\n' > "$repo/context/repo-map.md"
+cat > "$repo/context/gotchas.md" <<'EOF'
+# Gotchas
 
 1. **One.** short.
 2. **Two.** a much longer gotcha, with plenty of words in it to be the longest one
@@ -136,25 +135,25 @@ if run "$work/stats" text; then
   row "docs/*.md is other docs" by-area "other docs" '["2","0","0.000"]'
   row "context/code" by-area "context/code" '["8","0","0.000"]'
   row "context/test-evidence" by-area "context/test-evidence" '["5","0","0.000"]'
-  row "repo-map is its own area" by-area "repo-map" '["13","0","0.000"]'
-  row "other context" by-area "other context" '["2","0","0.000"]'
+  row "repo-map is its own area" by-area "repo-map" '["1","0","0.000"]'
+  row "other context" by-area "other context" '["13","0","0.000"]'
   row "kb.pl" by-area "kb.pl" '["5","0","0.000"]'
   row "scripts/CI takes .github, and a rename is a delete and an add" \
       by-area "scripts/CI" '["15","7","0.467"]'
   row "web and harness, and its deletion ratio" by-area "web and harness" '["14","9","0.643"]'
   row "a lock file, .beads/ and site/ are generated" by-area "generated" '["14","0","0.000"]'
   row "the pre-window README counts nowhere" by-area "other" '["4","0","0.000"]'
-  row "prose is the context areas, other docs and agent docs" by-kind prose '["43","6","0.140"]'
+  row "prose is the context areas, other docs and agent docs" by-kind prose '["42","6","0.143"]'
   row "code is rust, scripts/CI and web" by-kind code '["82","45","0.549"]'
-  row "prose to code is prose over code" by-kind ProseToCode '["0.524","0.133",""]'
+  row "prose to code is prose over code" by-kind ProseToCode '["0.512","0.133",""]'
   is "weeks are columns, first-seen first" '.tables["area-by-week"][0][1:]' '["2026-W24","2026-W23"]'
   row "an area is split by ISO week" area-by-week "web and harness" '["3","11"]'
   is "every day's churn.csv total equals code-maat's abs-churn" \
      '[.tables["by-day"][1:][]|.[1]==.[2]]|all' 'true'
-  row "a day's total is every file changed that day" by-day 2026-06-04 '["72","72"]'
-  is "gotchas end with their section" '.docs.repo_map.gotchas' '3'
+  row "a day's total is every file changed that day" by-day 2026-06-04 '["71","71"]'
+  is "gotchas end with their section" '.docs.gotchas.count' '3'
   is "the longest gotcha is measured over its lines" \
-     '.docs.repo_map.longest|[.number,.lines]' '[2,2]'
+     '.docs.gotchas.longest|[.number,.lines]' '[2,2]'
   is "test-evidence entries are ### and #### headings" '.docs.test_evidence.entries' '3'
   is "coupling finds the 15 pairs of six files, and web/app.js with scripts/foo.sh" \
      '.coupling|length' '16'