[iscekic]

Issue

No tracking issue — driven by review remarks on auto-docs PR #12521 (see Context). Checklist exception explained below.

Context

Review of the auto-generated docs PR #12521 surfaced three mistake classes in the docs-sync pipeline (.github/docs-sync/):

1. A reverted feature was documented anyway. fix(cli): prevent stalled agent streams #12249's default-on stream watchdog was reverted in-window by revert(cli): restore opt-in stream idle timeouts #12497 (revert(cli): restore opt-in stream idle timeouts), but the rolling PR documented it — collect's DROP_TITLE filter silently drops revert(...) PRs, so the pipeline never learns the feature is gone.
2. GitHub-native reverts pass the title filter. Revert "original title" (no colon) does not match DROP_TITLE, so a revert PR can itself be triaged docs-worthy.
3. Over-eager documentation. Triage/edit prompts lacked the calibration to skip internal plumbing changes with no user-visible behavior.

Root cause for 1–2 is deterministic: DROP_TITLE = /^(chore|test|ci|build|docs|style|refactor|revert)(\(.+\))?!?:/i drops conventional revert titles (hiding the signal) while GitHub-native titles pass through.

A fourth remark (command aliases "made up" in the docs) was verified incorrect — the aliases exist on main, added by the documented PR itself — so no rule was added for it.

Implementation

• New pure module reverts.mjs (no I/O, no imports): revertTitleKind (both title conventions), parseRevertTargets (line-anchored Reverts trailers; bare #N and owner/repo#N forms), computeRevertAnnotations (revert-of-revert cancels — a reverter that is itself reverted in-window annotates nothing), applyRevertAnnotations (applies to digest entries in place, returns applied pairs for reporting).
• collect.mjs intercepts revert PRs after the label check and before DROP_TITLE: fetches the full PR, parses its targets, excludes the revert from the digest, and annotates affected entries with reverted_by: { url, merged_at } before the digests are written (the slim digest inherits it via ...rest). DROP_TITLE is byte-identical — its revert alternative is now unreachable (comment explains). One dead revert fetch counts fetch_error only and never aborts the run.
• Prompt calibration. Triage: new NOT-worthy categories (internal plumbing with no user-visible behavior, UI polish) plus a reverted_by rule requiring the reason to cite the revert. Edit: verify-against-current-tree step scoped to kilocode PRs (the edit agent runs on the kilocode checkout; cloud PRs rely on diff/body + reverted_by), skip-is-a-first-class-outcome lead, and a reverted_by skip rule.
• selftest.mjs case 9: unit tests against reverts.mjs (including the full verbatim revert(cli): restore opt-in stream idle timeouts #12497 body as a no-false-positives fixture), source-order guards pinning the interception before DROP_TITLE and the annotation before digest writes, and prompt-text guards locking the calibration strings.

No docs-sync.yml changes; no retroactive doc removal (locked non-goals).

Screenshots / Video

N/A — CI workflow/prompt logic, no UI. Visual Changes: N/A.

How to Test

Manual/local verification

• node .github/docs-sync/selftest.mjs — all 9 cases pass, including the new case 9 (executed by agent).
• Live read-only replay of the real incident window (collect.mjs --since 2026-07-17T01:19:29.999Z, executed by agent, fail-closed jq -e gate): revert: 5 intercepted, zero revert-titled digest entries, and exactly the expected annotations:

[
  { "repo": "Kilo-Org/kilocode", "number": 12249, "reverted_by": { "url": "https://github.com/Kilo-Org/kilocode/pull/12497" } },
  { "repo": "Kilo-Org/kilocode", "number": 12481, "reverted_by": { "url": "https://github.com/Kilo-Org/kilocode/pull/12497" } },
  { "repo": "Kilo-Org/cloud",    "number": 4653,  "reverted_by": { "url": "https://github.com/Kilo-Org/cloud/pull/4731" } },
  { "repo": "Kilo-Org/cloud",    "number": 4685,  "reverted_by": { "url": "https://github.com/Kilo-Org/cloud/pull/4735" } }
]

The step summary also renders the chain explicitly (final-head replay):

**revert chains (not annotated):**
- https://github.com/Kilo-Org/cloud/pull/4759 (targets: https://github.com/Kilo-Org/cloud/pull/4709)
- https://github.com/Kilo-Org/cloud/pull/4709 (targets: https://github.com/Kilo-Org/cloud/pull/4698)

Kilo-Org/cloud#4698 (reverted by #4709, itself reverted by #4759 in-window) correctly carries no annotation — the revert-of-revert cancellation working on the live chain. (#4653's body notes a partial re-land in #4712; annotate-anyway is intended — documenting or not is triage's call via the new prompt rule.)

Reviewer test steps

1. Check out this branch; bun install is not required for the selftest.
2. Run node .github/docs-sync/selftest.mjs — expect selftest: all cases passed.
3. Read reverts.mjs + the collect.mjs interception block against the revert(cli): restore opt-in stream idle timeouts #12497 body quoted in case 9.

Blocked checks and substitute verification

• None blocked. E2E verification is intentionally skipped as inert: the deliverable is CI-workflow/prompt logic with no local product runtime; meaningful verification is the offline selftest plus the live read-only collect replay above.

Post-merge runbook

After this merges, regenerate the full window with:

gh workflow run docs-sync.yml -f since=2026-07-17T01:19:29.999Z

This is required because closing #12521 makes the watermark fall back to the 72h default and the 07-17→07-29 window would be lost. If the daily cron fires first with old logic, the later dispatch self-heals (prepare-branch update mode appends to the same PR); close any cron-created rolling PR unmerged.

Checklist

• Issue linked above, or exception explained — no tracking issue; driven by review remarks on docs: auto-sync with merged PRs (through 2026-07-29) #12521, explained in Context.
• Tests/verification described
• Screenshots/video included for visual changes, or marked N/A
• Changeset considered for user-facing changes — none (.github/docs-sync/ only, no packages)
• I personally reviewed the diff and can explain the changes, including any AI-assisted work.

Get in Touch

iscekic on Discord.

[iscekic]

(bot) Post-merge runbook: after this merges, regenerate the full window with gh workflow run docs-sync.yml -f since=2026-07-17T01:19:29.999Z — closing #12521 drops the watermark to the 72h fallback, so skipping this loses the 07-17→07-29 window.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs (docs-staging)	Ready	Preview	Jul 30, 2026 5:17pm

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Files Reviewed (2 files)

• .github/docs-sync/reverts.mjs
• .github/docs-sync/selftest.mjs

Resolved since previous review

• selftest.mjs: r3Url is now pull/301, so the depth-3 case builds a genuine R1→F, R2→R1, R3→R2 chain instead of a self-referential signal.
• reverts.mjs: cancelled and chain-linked signals are now split — a cancelled signal reports all its targets in chains, while a non-cancelled chain link reports only its chain-link targets and lets its plain targets flow through missed. This also removes the earlier gap where a mixed signal's genuinely unannotated plain targets were swallowed out of missed, and keeps the chains listing free of annotated targets in the normal case (chain-link targets are intercepted reverts, which never enter the digest and so can never be annotated).

Notes and assumptions

• Incremental review of 0d8f9eb..8b614ae (2 files, ~45 changed lines). Traced the new bucket logic by hand against all unannotatedRevertSignals fixtures (partial, fully-covered, depth-2, depth-3, mixed, zero-target, case-insensitivity) and each matches the asserted result.
• The selftest was not executed here (running code is out of scope in review mode); CI covers execution.
• Unchanged files from earlier commits were not re-reviewed, so previously discussed items outside this diff are not restated.
• No changeset expected: the change is confined to .github/docs-sync/ with no shipped-product impact.
• CI-owned checks (lint/format, marker rules, workflow allowlist) were not reviewed.

Previous Review Summaries (4 snapshots, latest commit 0d8f9eb)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit 0d8f9eb)

Status: 2 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	1

Issue Details (click to expand)

WARNING

File	Line	Issue
.github/docs-sync/selftest.mjs	1680	r3Url duplicates r2Url (pull/300), so the "depth-3 chain" case builds a self-referential signal instead of a real 3-deep chain; it passes coincidentally

SUGGESTION

File	Line	Issue
.github/docs-sync/collect.mjs	175	"revert chains (not annotated)" can list targets that were annotated, and swallows genuinely missed non-chain targets out of the missed bucket

Files Reviewed (3 files)

• .github/docs-sync/reverts.mjs - 0 issues
• .github/docs-sync/collect.mjs - 1 issue
• .github/docs-sync/selftest.mjs - 1 issue

Resolved since previous review

• Depth-3+ revert chains are no longer silent: unannotatedRevertSignals returns a chains bucket covering both cancelled signals and re-land chain links, and collect.mjs prints it in the step summary. The behavior change is documented in the module docstring, and missed no longer needs the signalUrls filter.

Notes and assumptions

• Incremental review of 7673a09..0d8f9eb (3 files, ~80 changed lines); unchanged files from earlier commits were not re-reviewed.
• Reporting every chain member (including 2-deep cancellations that are fully understood) is a deliberate visibility-over-noise tradeoff, not flagged.
• The selftest could not be executed here (running code is out of scope in review mode), so pass/fail status is unverified locally; the r3Url finding is from reading the fixture values against reverts.mjs. CI covers execution.
• No changeset expected: the change is confined to .github/docs-sync/ with no shipped-product impact.
• CI-owned checks (lint/format, marker rules, workflow allowlist) were not reviewed.

Fix these issues in Kilo Cloud

Previous review (commit 7673a09)

Status: 1 Issue Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	0
SUGGESTION	1

Issue Details (click to expand)

SUGGESTION

File	Line	Issue
.github/docs-sync/reverts.mjs	134	signalUrls drops signal-targeted misses unconditionally, so a depth-3+ revert chain gets neither a reverted_by annotation nor a summary line

Files Reviewed (3 files)

• .github/docs-sync/reverts.mjs - 1 issue
• .github/docs-sync/collect.mjs - 0 issues
• .github/docs-sync/selftest.mjs - 0 issues

Resolved since previous review

• The some-based reporting is gone: unannotatedRevertSignals now reports per-target misses, so a partially-covered revert surfaces exactly its uncovered targets.
• 2-deep revert-of-revert cancellations no longer surface as false anomalies, and the predicate moved into the pure, unit-tested module instead of living inline in collect.mjs.
• New selftest coverage exercises the real implementation (partial coverage, full coverage, cancelled re-land, zero-target, case-mismatch, live revert(cli): restore opt-in stream idle timeouts #12497 shape) with no mocks.

Notes and assumptions

• Incremental review of b2f7cbd..7673a09 (3 files, ~154 changed lines); unchanged files from earlier commits were not re-reviewed.
• unparsed entries are now reported in both the ::warning:: at intercept time and the step summary; the duplication is intentional-looking and harmless.
• Targets in repos outside SOURCE_REPOS will always appear under "revert targets with no in-window annotation"; low-volume noise, not flagged.
• No changeset expected: the change is confined to .github/docs-sync/ with no shipped-product impact.
• The selftest could not be executed in this sandbox (node is not permitted in review mode), so test-pass status is unverified here; CI covers it.
• CI-owned checks (lint/format/typecheck, marker rules, workflow allowlist) were not reviewed.

Fix these issues in Kilo Cloud

Previous review (commit b2f7cbd)

Status: 2 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	0
SUGGESTION	2

Issue Details (click to expand)

SUGGESTION

File	Line	Issue
.github/docs-sync/collect.mjs	136	some marks a revert covered when only one of several targets was annotated, so partially-covered reverts stay invisible; cancelled revert-of-revert chains also surface as anomalies
.github/docs-sync/selftest.mjs	1631	Byte-exact source-line assertion is redundant with the surrounding index guards and breaks on harmless reformatting

Files Reviewed (3 files)

• .github/docs-sync/collect.mjs - 1 issue
• .github/docs-sync/reverts.mjs - 0 issues
• .github/docs-sync/selftest.mjs - 1 issue

Resolved since previous review

• collect.mjs — intercepted reverts with no in-window annotation are now reported in the step summary, closing the "disappear without a trace" gap (residual edges noted above).
• reverts.mjs — trailer regex now allows bulleted/quoted prefixes and uses \b, so - Reverts #7 / > Reverts #8 parse and Revertsomething #5 is inert; new selftest assertions cover all three.
• reverts.mjs — target urls are matched case-insensitively in both computeRevertAnnotations and applyRevertAnnotations, with an end-to-end case-mismatch test.

Notes and assumptions

• Incremental review of 9943f0d..b2f7cbd (3 files, ~62 changed lines); unchanged files from the earlier commits were not re-reviewed.
• parseRevertTargets's seen set still dedupes case-sensitively, so a body mixing kilo-org/... and Kilo-Org/... for the same PR yields two target entries; harmless because both map to the same annotation.
• Allowing a > prefix means a revert body quoting someone else's Reverts #N line can produce a target; judged low risk since the quoted trailer is almost always the PR's own, and the parser only runs on revert-titled PRs.
• No changeset expected: the change is confined to .github/docs-sync/ with no shipped-product impact.
• CI-owned checks (lint/format/typecheck/tests, marker rules, workflow allowlist) were not reviewed.

Fix these issues in Kilo Cloud

Previous review (commit 9943f0d)

Status: 4 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	3

Issue Details (click to expand)

WARNING

File	Line	Issue
.github/docs-sync/collect.mjs	134	Reverts whose targets are not in this window's digest produce no annotation and no summary entry, and the revert PR itself no longer reaches triage — a revert of an already-documented feature is now silently invisible

SUGGESTION

File	Line	Issue
.github/docs-sync/reverts.mjs	32	Trailer regex misses bulleted/quoted Reverts #N lines, and the zero-width [ \t:]* lets Revertsomething #5 parse as a target
.github/docs-sync/reverts.mjs	42	Target urls are compared case-sensitively against pr.html_url, so Reverts kilo-org/kilocode#N silently matches nothing
.github/docs-sync/selftest.mjs	1599	Byte-exact source-line assertion is redundant with the surrounding index guards and breaks on harmless reformatting

Files Reviewed (5 files)

• .github/docs-sync/collect.mjs - 1 issue
• .github/docs-sync/reverts.mjs - 2 issues
• .github/docs-sync/selftest.mjs - 1 issue
• .github/docs-sync/edit-prompt.md - 0 issues
• .github/docs-sync/triage-prompt.md - 0 issues

Notes and assumptions

• Verified the claim on collect.mjs:31 that the revert alternative in DROP_TITLE is unreachable: revertTitleKind's conventional pattern is byte-equivalent to that alternative and runs first, so the comment is accurate.
• Confirmed reverted_by survives the whole pipeline: applyRevertAnnotations mutates before both digest writes, the slim digest inherits it via ...rest, triage.mjs chunks pass entries through verbatim, and filter-worthy.mjs copies entries wholesale into the edit batch.
• Confirmed no watermark regression from excluding reverts: processed-through derives from bot PR bodies and uncovered merged_at values, not from the dropped set.
• The revert-of-revert cancellation deliberately does not walk chains (single set lookup), so a depth-3 chain or a partial re-land can leave a still-reverted PR unannotated. Not flagged separately since the docstring documents the tradeoff explicitly.
• No changeset expected: the change is confined to .github/docs-sync/ with no shipped-product impact.
• CI-owned checks (lint/format/typecheck/tests, kilocode_change markers, workflow allowlist) were not reviewed.

Fix these issues in Kilo Cloud

---

_{Reviewed by claude-opus-5 · Input: 26 · Output: 6K · Cached: 579.5K}

_{Review guidance: REVIEW.md from base branch main}