doc-sync-cocos

Doc Sync — Cocos TypeScript (automation contract)

cocos-doc-turn-tracker (PostToolUse) queues edited Cocos .ts. cocos-doc-drift-stop (Stop) drains that queue once per turn, unions it with a git sweep of the same project, regenerates docs-ts-out/ for zero LLM tokens, then delegates only the symbols still undocumented in files changed that turn.

The sweep is not redundant with the queue. Only Edit/Write/MultiEdit produce a PostToolUse event, so a git mv, a sed -i, a heredoc, a node script, or an edit made inside a forked sub-agent enqueues nothing — and a bypass-permissions session is instructed to prefer Bash for file work, which makes that the majority path, not an edge case (#339). The sweep reads git diff HEAD plus untracked files instead, and takes a path when it is new to the changed set (this is what carries a rename: git mv preserves mtime) or its mtime beats the watermark. A tree that has simply been dirty for a week contributes nothing. The first Stop in a project seeds the watermark and takes no files, so git-discovered coverage engages from the second turn.

The audit is intersected with the changed-file set before anything reaches an LLM — the automated path never runs a full-codebase pass. annotate runs without --force, so authored prose is never overwritten. Both hooks are advisory and dormant without t1k-cocos-base-script-graph. Opt out of tier 2 with T1K_SKIP_COCOS_DOC_SYNC=1.

Why tier 2 re-exports after annotating, how the delegated provider/model is resolved, and how the git sweep bounds its own cost: docs/doc-sync-cocos.md.