17 Dead References in My Handover Docs Turned Out to Be 2 Files, and the Real Risk Was a Different Site's Playbook Mixed In

Three fixes later, the count went 17 → 8 → 10 → 7

First, a bare file name is now looked up against the set of all file names in the repository. That took 17 to 8.

Second, references with brackets such as [locale] or [slug]. In Next.js those are real directory names, so a literal match works. My first version skipped them as undecidable, so they were not in the count. Once I evaluated them, the number went up from 8 to 10. The checker got smarter and the count rose, because it could now see what it had been ignoring.

Third, an explicit ignore list for references that are meant not to exist. Three of the ten qualified.

src/proxy.ts is a reference I must not "fix" even though the check calls it broken. Not existing yet is its correct state at the time it was written.

The remaining seven converged on two files: BookRecommendation.tsx and opengraph-image.tsx. The first is a book-recommendation component that has already been removed. The second is an OGP image generator that I can no longer find in the repository. What looked like 17 problems was, as a place to fix, mentions of two files.

The real danger wasn't a reference. It was whose document it was

Something bothered me at that point. Even after those two files stopped being referenced, HANDOVER.md would still be a playbook for a different site. A reference check doesn't look at who the document is about.

So I added another angle: give the checker the other domains that came from the same template, and suspect any document that mentions them at least as often as it mentions this site.

In HANDOVER.md the other site's name (including non-domain spellings) appears 34 times and this site's name 16 times. It has 40 unchecked items (- [ ]), and near the top are "create a new repository", "change the name in package.json", and "change the name and account in wrangler.toml".

A person reads that and knows it's for the other site. But picture an agent that takes root files as instructions and works down the checkboxes. A proposal to rewrite this site's package.json name would not be surprising. That strikes me as much closer to real harm than any dead reference.

What surprised me is that a script I wrote to find document drift was built in a way that could not find the biggest problem. With zero broken references, a document about another project still passes.

The full checker

It runs on the standard library alone. The final version is 53 lines.

#!/usr/bin/env python3
"""doc_drift.py - リポジトリ直下の *.md を、エージェントに読ませる前に点検する。
検出するもの: (1) 実在しないパス参照 (2) テンプレート元の別ドメインが自ドメイン以上に出てくる文書 
使い方: python3 -I doc_drift.py <repo> <own-domain> [--siblings DOMAIN ...] [--ignore PATH ...]
終了コード: 0=問題なし / 1=要確認あり（CI や起動前フックで止められる）"""
import argparse, collections, pathlib, re, sys
 
ap = argparse.ArgumentParser()
ap.add_argument("repo"); ap.add_argument("own")
ap.add_argument("--siblings", nargs="*", default=[], help="同じテンプレート由来の別ドメイン（混入検出用）")
ap.add_argument("--ignore", nargs="*", default=[], help="意図して実在しない参照（失敗例・将来の予定など）")
a = ap.parse_args()
repo = pathlib.Path(a.repo)
 
# 追跡対象の全パス。.git と node_modules は除く
files = {p.relative_to(repo).as_posix() for p in repo.rglob("*")
         if p.is_file() and not {".git", "node_modules"} & set(p.parts)}
basenames = {f.rsplit("/", 1)[-1] for f in files}
 
# バッククォートで囲まれた「パスらしい」文字列だけを拾う
REF = re.compile(r"`([\w@.\[\]{}/-]+/[\w@.\[\]{}-]*|[\w-]+\.(?:mjs|ts|tsx|js|json|toml|md|mdx|txt))`")
DOM = re.compile(r"\b([a-z0-9-]+\.(?:net|jp|org|com))\b")
 
def resolve(ref: str):
    ref = ref.strip("./")
    if "{" in ref:                            # テンプレート記法は判定しない
        return None
    if "/" not in ref:                        # 裸のファイル名は basename で探す
        return ref in basenames
    if ref in files or any(f.startswith(ref.rstrip("/") + "/") for f in files):
        return True                           # [locale] などのブラケットも実在ディレクトリ名として一致する
    return any(f.endswith("/" + ref) for f in files)   # 先頭を省略した相対参照
 
problems = 0
for doc in sorted(repo.glob("*.md")):
    text = doc.read_text(encoding="utf-8")
    dead, skipped = collections.Counter(), 0
    for ref in set(REF.findall(text)):
        if ref in a.ignore:
            continue
        r = resolve(ref)
        if r is None: skipped += 1
        elif not r: dead[ref] = text.count(f"`{ref}`")
    doms = collections.Counter(DOM.findall(text))
    foreign = {d: n for d, n in doms.items() if d in a.siblings}
    own_n = doms.get(a.own, 0)
    flag = bool(dead) or sum(foreign.values()) > own_n   # 兄弟ドメインの言及が自ドメイン以上なら疑う
    problems += flag
    print(f"{'NG' if flag else 'ok'}  {doc.name:<20} {len(text.encode()):>6}B  "
          f"dead={sum(dead.values())} skipped={skipped} own={own_n} foreign={sum(foreign.values())}")
    for ref, n in dead.items(): print(f"      dead   {ref}  ×{n}")
    for d, n in foreign.items(): print(f"      foreign {d}  ×{n}")
sys.exit(1 if problems else 0)

Three notes on why it's written this way.

resolve returns None for template syntax like {name}. Counting something whose existence can't be asked as "broken" would teach people to stop reading the warnings. Brackets, in contrast, are treated as real directory names.

The exit codes are 0 and 1 so the script can gate a launch, not only be read by eye.

The sibling-domain rule is "at least as many as this site" so a document with only a faint trace of the template isn't blocked. That threshold is my rule of thumb, not a number with evidence behind it.

What it printed on this repository

First, with no ignore list. I did not touch a line of any document. The other domains are replaced with placeholders like sibling-a.example.

ok  CONTENT_LOG.md        30371B  dead=0 skipped=0 own=0 foreign=0
NG  HANDOVER.md           14317B  dead=5 skipped=0 own=7 foreign=9
      dead   antigravitylab.net/  ×1
      dead   /home/user/project/  ×1
      dead   opengraph-image.tsx  ×1
      dead   src/app/[locale]/opengraph-image.tsx  ×1
      dead   BookRecommendation.tsx  ×1
      foreign sibling-a.example  ×8
      foreign sibling-b.example  ×1
NG  MIGRATION_GUIDE.md    11406B  dead=5 skipped=1 own=1 foreign=4
      dead   src/components/ui/BookRecommendation.tsx  ×1
      dead   opengraph-image.tsx  ×1
      dead   src/app/[locale]/opengraph-image.tsx  ×2
      dead   BookRecommendation.tsx  ×1
      foreign sibling-b.example  ×2
      foreign sibling-a.example  ×2
ok  README.md               100B  dead=0 skipped=0 own=1 foreign=0
NG  REMAINING_TASKS.md     2846B  dead=1 skipped=0 own=1 foreign=0
      dead   src/proxy.ts  ×1
ok  SKILL.md               9903B  dead=0 skipped=1 own=2 foreign=0

It ran in 0.084 seconds. CONTENT_LOG.md is ok because it only has many external links and no sibling domains.

Next, with the three intentional entries ignored.

ok  CONTENT_LOG.md        30371B  dead=0 skipped=0 own=0 foreign=0
NG  HANDOVER.md           14317B  dead=3 skipped=0 own=7 foreign=9
      dead   opengraph-image.tsx  ×1
      dead   BookRecommendation.tsx  ×1
      dead   src/app/[locale]/opengraph-image.tsx  ×1
      foreign sibling-a.example  ×8
      foreign sibling-b.example  ×1
NG  MIGRATION_GUIDE.md    11406B  dead=5 skipped=1 own=1 foreign=4
      dead   opengraph-image.tsx  ×1
      dead   src/components/ui/BookRecommendation.tsx  ×1
      dead   BookRecommendation.tsx  ×1
      dead   src/app/[locale]/opengraph-image.tsx  ×2
      foreign sibling-b.example  ×2
      foreign sibling-a.example  ×2
ok  README.md               100B  dead=0 skipped=0 own=1 foreign=0
ok  REMAINING_TASKS.md     2846B  dead=0 skipped=0 own=1 foreign=0
ok  SKILL.md               9903B  dead=0 skipped=1 own=2 foreign=0

REMAINING_TASKS.md became ok. HANDOVER.md and MIGRATION_GUIDE.md are still NG. I think staying NG is exactly this script's job. Fixing the references isn't enough to pass; it stops until a person decides whose document each one is.

A wrapper at the entrance

The ignore list lives in .doc-drift-ignore at the repository root, one reference per line. A thin wrapper reads it and calls the checker, and I put it at the entrance before launching an agent.

#!/usr/bin/env bash
# エージェントにリポジトリを渡す前の入口。引き継ぎ文書に未解決の参照が残っていれば止める。
set -euo pipefail
REPO="${1:-.}"; OWN="${2:?own domain}"
IGNORE_FILE="$REPO/.doc-drift-ignore"        # 1行1参照。意図して実在しないもの（失敗例・将来の予定）
IGNORE=(); [ -f "$IGNORE_FILE" ] && mapfile -t IGNORE < <(grep -v '^#' "$IGNORE_FILE" | sed '/^$/d')
SIBLINGS=(sibling-a.example sibling-b.example)         # 同じテンプレート由来の別ドメイン
if python3 -I "$(dirname "$0")/doc_drift_final.py" "$REPO" "$OWN" --siblings "${SIBLINGS[@]}" ${IGNORE[@]:+--ignore "${IGNORE[@]}"}; then
  echo "preflight: OK"
else
  echo "preflight: 文書の見直しが先です（上の NG を確認）" >&2; exit 1
fi

I wrote the three entries above into .doc-drift-ignore and ran it. It printed the "review the documents first" message and exited with 1. I deleted the ignore file afterwards.

Four pitfalls

First, looking bare file names up by basename is a lenient check. If a file with the same name exists anywhere, it passes even when the reference points somewhere else. In a repository with several Header.tsx files, that lets mistakes through.

Second, it only picks up strings wrapped in backticks. References written inside code blocks, such as a directory-tree diagram, are outside its reach. A stale file name left in a tree diagram will not be found.

Third, the ignore list grows. In my pre-flight check for .zip attachments I recorded acknowledged warnings per line. Here the exclusions are per path, which is coarse. If the same path breaks for a different reason, I won't notice.

Fourth, "count of other domains" is shaped around my repository. If the template's leftovers survive as product names or color names instead of domains, they slip past.

What I haven't verified

I haven't verified in what order or how heavily Antigravity reads root .md files. Every number above comes from running the script on my own repository, not from measuring agent behavior. I also didn't edit the body of any document in this pass.

Next steps

1. Check the number and byte size of the .md files at the root of the repository you're about to hand over
2. Run doc_drift.py once with no ignore list and open each entry under dead
3. Write only the references that are meant not to exist into .doc-drift-ignore, then run it again
4. For any document that shows foreign, decide whose document it is before fixing references. If it belongs to another project, moving it out of the repository is the safest option I can think of
5. Put agent_preflight.sh at the entrance and let the exit code stop you

The same pre-handoff idea shows up in the .dev.vars file that slipped past an .env* ignore rule and in files Git tracks that an agent still can't read.