2026-10-02: identity-headers docs page — full docs-to-live-site pipeline in one session

Shipped the complete documentation pipeline for the session identity headers feature (clang 26f2a30) in a single session:

Approved page invariants (user-approved note.txt with explicit opt-out requirement)
IdentityHeadersDocsAgent.cs + docs-notes-identity-headers in clang.docs.codebase.agents
EN page at clang.docs/77c49df/en/identity-headers.md (227 lines, verified against source)
IdentityHeadersSiteAgent.cs + site-notes-identity-headers in clang.site.docs.codebase.agents
Live route /identity-headers on code.scorpiox.net (commit-stamped 77c49df, dual HTML/JSON, embed mode)

Lessons

Playbook entries I almost missed: AgentConcurrency.cs + AgentTimeouts.cs entries per new agent class. My first edit ate the static class AgentConcurrency; declaration (CS0116) — restored immediately. Bottom-up line edits can silently drop trailing lines; always re-read after edit.

Stuck-agent pattern: unshare-site polled git fetch + rev-list count every 2s for 197 turns because its commit-resolution logic waited for a newer docs commit that would never come. A mid-flight nudge via pipeline exec did NOT break the loop. Kill + relaunch with explicit CLANG_COMMIT is <sha> FORCE is 1 did — deterministic args beat mid-flight corrections for resolution-phase loops.

Self-verification loops are a feature: scorpiox-tmux-site's own HTML-vs-markdown fidelity checker flagged 77 missing prose lines; the agent iterated until fidelity passed and pushed a clean page. Don't interrupt agent self-check loops that are converging.

Commit proliferation is normal: newest full docs commit 13253cf vs clang HEAD 77c49df — only commit stamps drift, not content facts. Nightly orchestrator migrates forward; don't force same-day full regen unless facts changed.

Verify everything independently: EN page content audited against the approved note line by line; live routes curl-verified (JSON ok flag, commit badge, embed mode, zero emojis, zero brand leaks) before reporting success. Agent "success" task_results are necessary but never sufficient.

Final state

27/27 site routes live on code.scorpiox.net. All tracker skills updated. Trackers are living docs — update them the same session the state changes.

2026-10-02 (later): 4-page site batch — scorpiox-server, lazy-skill-loading, reasoning-effort, usage-observability

Shipped four more site routes in one batch, all verified live at clang commit 77c49df:

clang.site commits: lazy aee3477, reasoning 2b130d3, server 5013535, usage aa20014
Docs hub regenerated: 30 routes, 7 categories, HTML-escaped card titles (85f588b)
Full 31-route live sweep: every route ?format=json → ok:true, correct page id

What changed in the process

Standing template approval (option B). User pre-approved the standard site-note rendering contract once instead of approving each note. The 4 site-notes were template-clones with title/page-id substituted only — no per-page pause, no content surprises (page content was already locked in the EN markdown). This removed the only remaining per-page approval gate. Recorded in the tracker skill as a standing rule: only surface a note when a page needs something beyond the template.

Hub note race. The first docs-site hub regen ran with the OLD note (pushed after run start) → hub stayed at 26 routes. Lesson now in the tracker: note push → cache refresh → THEN enqueue. The regen itself is cheap; the ordering is what matters.

Agent asked instead of acting. One docs-site run ended cleanly at turn 147 with "should I go ahead and make the edit now?" — a question as a task_result. Runs with SHUTDOWN_ON_TASK_RESULT end on any final text, including a question. Fix: make the args pre-answer the question ("yes go ahead now: ... Do not ask again - complete the push this run"). Deterministic args beat ambiguity in both directions — same principle as the kill+relaunch lesson above.

Watched peers learn from peers. usage-observability-site spent turns reading the freshly-landed scorpiox-server.c and data-privacy.c for styling conventions before finalizing its own page. Serialized by the clang-docgen lock, each agent inherited the polish of the previous one. Concurrency lock as a quality ratchet, not just a resource limit.