Skip to content

docs: point stale owner cites and a ci path at the merged refactors - #15645

Merged
iamwhatever merged 1 commit into
mainfrom
refactor/qf3-docs-ci-sync-wave3
Oct 1, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
refactor/qf3-docs-ci-sync-wave3

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Comments, specs and the Linux Packaging CI trigger name the modules that now own the code the merged component refactors moved.

The merged component refactors split large facade files into owner modules. Some sentences in comments, docstrings, specs and RFCs still say the facade defines the code, so a reader who follows one finds only a re-export line. One CI path filter has the same gap: linux_packaging lists website/electron/auto-update.js but not the update lanes that file composes. A PR that edits only website/electron/runtime/update/feed-lane.js, where the per-format Linux feed is chosen, therefore skips Linux Packaging (build + smoke-install).

Why it matters

A stale "defined in X" cite costs every reader a wrong turn. It also invites new code into the facade, which is where most later work on four of these refactors has landed. A Linux packaging regression in an update-lane owner would ship without the one job that installs the packages for real.

Not a goal

  • No production behaviour change. No code moves, and no gate logic, job or strictness changes: the only CI edit adds one path to an existing filter.
  • Files owned by still-open campaign work are left alone. The items that need them are listed under "Skipped" below.
  • The 33 other docs-lint baseline entries that stopped firing because of unrelated upstream commits stay in place.
  • Pre-existing content drift that no refactor caused is not fixed here (listed under "Skipped").

What changed (motivation → approach → change)

Area Change
.github/workflows/ci.yml linux_packaging also triggers on website/electron/runtime/update/** (audit M1 / F10-1).
Code comments and docstrings Re-pointed to the true owner in hooks.py, history_search.py, dep_sync.py, agent_files.py, agent_sdk/host_auth.py, providers/mirrors/registry.py, doctor_checks/agents.py, config/loader.py, config/sections.py, apps/routes.py, apps/bridges.py, apps/builtins/{meetings,issue_radar,auto_research}, and in website/src/components, website/src/hooks, website/src/lib, website/src/pages, website/src/store, website/src/types, website/src/utils, website/src/apps and website/electron.
Specs, RFCs, READMEs Same re-points in app-kit-platform.md, four RFCs and .kiro/specs/pod-cli/design.md. A "where new code goes" paragraph in config.md, acp-client.md, history.md (the chat-sidebar owner map) and website/electron/README.md. The README's auto-update export count is now 16.
Characterization notes ChatInput.refactor.ownership.test.ts records the composer's benign effect reorder; runtime/window/linux-captions.js records that its injected literals are whitespace-normalized.
.github/docs-lint-baseline.txt Six entries that stopped firing when these refactors fixed their cites are deleted. Nothing else is removed.
test/fixtures/adf_markdown_safety.json, test/ docstrings _comment and docstring re-points only.

Each new sentence was checked against the definition at the base commit: the cited file defines the named symbol. The old text was checked to be false (or, for line cites, to point at other code). No test asserts any of the changed text: no test file contains any removed fragment.

Audit items closed (IDs from the quality audit of the merged refactors and its doc follow-up list): M1/F10-1; D1 (hooks, history_search, ADF fixture and test); D2; D3; D4; D5 (six RFC sentences, plus two more in the same files and for the same cause); D6 (api.ts); D7 (five F05 cites, AboutPanel.downloadStates.test.tsx, README count); D8 (L369, L382, L385, L388, L585, L606); D9 (all four); D11 (both); the B03, B05, B08, B09, I06, F02, F03, F06 and F07 doc follow-ups that still held at the base.

Skipped, with reasons:

  • D1 sandbox.py, D7 index.css, D6 gatewayd.py:30 docstring: excluded until their owners (B10, F09, QF2) merge.
  • I04 follow-up (aws-control.md backup composition sentence): the text is delegated to the open scope that holds that spec's lease and is rewriting the same sentence.
  • D6 notify_out.py:67-68: still true at the base (routes.py still imports it).
  • D6 SettingsPanel.tsx:798 and its opsMissionControl.test.ts comment twin: the surrounding claim ("dispatch.py zero", "the only caller") has been false since before the refactor. A true rewrite reverses a user-facing string that a test asserts, so it is left as a follow-up for the ops-mission-control owner, not a text sync.
  • D5 rfc-security-conductor.md:88: a fact record measured at a named older commit, which is still true for that commit.
  • D7 rfc-i18n-measurement.md:238-239: still true at the base.
  • D8 onToolCall (L48): it stops firing only because a refactor added a same-named code identifier. Pruning it would turn a later rename into a failure on an unrelated PR.
  • Doc follow-ups already fixed at the base by earlier sync PRs: the I08, I09, B11 and B16 comment items, resource-protection.md, mcp-gateway-daemon-lifecycle.md, service/apparmor.py, pod/runtime_boot.py, memory-skills-hooks.md, check_sync_io_in_async.py, memory-benchmark.yml, bundle.py.
  • Doc follow-ups still true at the base: backend_mcp_ability.py:60, dashboard/urls.py, mcp_cleanup.py:322, issue_radar/backend/watch.py:17, rfc-issue-radar-crews.md:129, test_review_findings_prb.py:24.
  • Doc follow-ups in files owned by open scopes: security.md, platform-context.md, taskq.md, injected-messages.md, learn-cron-dashboard.md, docs/feature-map/README.md, website/docs/extension-seams.md, ChatPage.tsx, pages/chat/ActivityViewer.tsx, cli_doctor.py:857, pod/runtime.py, test_core_path_redact_before_bound.py, test_routes_composition_contract.py.
  • Not text-only: test_harness_parity._RUNTIME_PATH_MODULES and the I02 characterization rows.
  • Not caused by a refactor: knowledge.md:409 (model and tools claim), the config.md "28 sections" count, build-windows.yml:27-28, macos-on-demand.yml:148 (a deleted test file), agent_files.py:6-9.

Backwards compatibility

Compatible: the diff changes comments, docstrings, docs and one CI trigger list. The added path makes Linux Packaging run on more PRs; it never skips a PR the filter selected before.

Tests

  • test/test_ci_linux_packaging_filter.py (new). It walks the relative-require closure of each Electron .js entry the linux_packaging bucket lists, and asserts that every module in the closure matches the bucket. At the base it fails, naming runtime/update/{feed-lane,managed-lane,state-reporter}.js. With the filter line it passes. Two companion tests pin the glob matcher's */** semantics and that the walk reaches past the entries.
  • Ran locally on Python 3.12: the 3 test files in the diff, the 103 name-matched to changed modules, every test that reads ci.yml, plus test_app_mcp_scoping.py, test_docs_lint_fact_checks.py, test_mirrored_owner_storage.py and test_prepare_pr_profiles.py (10044 passed, 6 skipped). Electron unit tests (2305 passed), the 31 related vitest files (612 passed), tsc -p tsconfig.app.json, eslint on the touched files, the i18n literal check, docs-lint (34 stale baseline entries left, down from 40), and the comment-history, brand, black, flake8, isort and mypy gates. scripts/local-gate.py --dry-run selects 2104 backend and 1295 frontend files, so the broad set is left to CI.

Manual verification

N/A: no runtime behaviour changes. The CI change was checked by parsing ci.yml with the bucket's glob semantics, before and after.

Screenshots / video

Why no screenshot: the website files change only in comments; nothing renders differently.

Related Issues

no linked issue: a follow-up to the audit of the merged component refactors.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@bolichen97
bolichen97 requested a review from a team October 1, 2026 01:16
@bolichen97
bolichen97 requested a review from a team as a code owner October 1, 2026 01:16
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 1, 2026
@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — ✅ PASS

UX-level review of d8845d9ca158d012e726c3bbbf9d80386a79740c — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: PASS

Nothing to check.

[UX-REVIEWED] d8845d9

Description read

[DESCRIPTION-READ] 1009a6592a3ad15d23f3b57e442c5cec073ae3e36ee8aedc742795a60a1bd4e5

That sha256 names everything this verdict read: the PR description, plus the 3 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of d8845d9ca158d012e726c3bbbf9d80386a79740c — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

One check: _glob_regex hand-reimplements dorny/paths-filter's picomatch semantics — confirm the lane actually fires on a runtime/update/-only diff once.

[DESIGN-REVIEWED] d8845d9

Description read

[DESCRIPTION-READ] 296639aa8f0baa5aebb905dfd7720d003f3328b096b4fa9d16ab6a0b8994e531

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of d8845d9ca158d012e726c3bbbf9d80386a79740c — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Verify the test's hand-rolled glob matcher against dorny/paths-filter v4's real picomatch semantics (dotfiles, brace sets) — a divergence greens the test while the lane still skips.

What this change ships

Inventory (8 items) — 7 justified

Intent: FIX — stale "defined in X" cites left by the merged facade-split refactors, plus the CI gap where update-lane owners skipped Linux Packaging.

  1. Linux Packaging job now also runs when website/electron/runtime/update/** changes — justified
  2. New test pins that every module the bucket's entry files require is covered by the bucket (fails on base) — justified
  3. ~45 comments, docstrings, specs and RFC sentences re-pointed from facades to the owner modules — justified
  4. Four docs gain a "where new code goes" paragraph naming the owner per responsibility — justified
  5. Six docs-lint baseline entries that no longer fire are deleted — justified
  6. Two characterization notes added (composer effect reorder; linux-captions whitespace normalization) — rides along: declared, not a cite fix, harm-free
  7. agent_files.py comment corrected: guest agent file is written unguarded, unlike its siblings — justified
  8. Electron README's auto-update export count corrected to 16 (verified: 16) — justified

[FIRST-PRINCIPLES-REVIEWED] d8845d9

Description read

[DESCRIPTION-READ] d46f8d0faf1939208291e47da2582156541f74a546bfd422336117c778505945

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of d8845d9ca158d012e726c3bbbf9d80386a79740c and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] d8845d9

False positive or not applicable? A repository writer can comment:
/ai-review override gpt d8845d9ca158d012e726c3bbbf9d80386a79740c: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ human override accepted

Reviewed d8845d9ca158d012e726c3bbbf9d80386a79740c — this comment is updated in place on each push.

Human judgment by @bolichen97 overrides the Opus 5 finding for d8845d9ca158d012e726c3bbbf9d80386a79740c; the recorded reason is authoritative for this commit.

[OPUS-OVERRIDE] d8845d9

Verdict recorded from an authorized human decision for commit d8845d9ca158d012e726c3bbbf9d80386a79740c.

False positive or not applicable? A repository writer can comment:
/ai-review override fable d8845d9ca158d012e726c3bbbf9d80386a79740c: <one-sentence reason>

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=ff43b6f1b705 linux_packaging omits the Electron lockfile and the smoke script — rebutted (out of goal)

The lockfile and smoke-script gap predates this PR. Since #4174 the bucket has listed package.json, auto-update.js, bundle-location.js, build-desktop.sh, stamp-distribution.sh and build-desktop.yml, and never package-lock.json or smoke-linux-packages.sh.
This PR's goal is a path-reference sync for code the merged refactors moved: it re-adds coverage for the update lanes F10 split out of auto-update.js. Neither of the two paths in the finding was moved by any refactor.
Adding them would widen which PRs run Linux Packaging for a reason unrelated to the moved code. That is a gate-scope decision for the CI owner, and the campaign's rules keep it out of a path-sync PR.
The finding is advisory; the gap is recorded as a CI-maintainer follow-up.

@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Security Scope Review -- ✅ human override accepted

@bolichen97 overrode this lane for d8845d9ca158d012e726c3bbbf9d80386a79740c via /ai-review override (this commit only).

[SCOPE-REVIEWED] d8845d9

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 1, 2026
The merged component refactors moved code out of facade files into
owner modules, but some comments, docstrings, specs, RFCs and one CI
path filter still named the facade as the place that defines the code.
A reader who followed them landed on a re-export line. A PR that edited
only website/electron/runtime/update/* also skipped the Linux Packaging
job, because the linux_packaging filter still listed only auto-update.js.

Re-point those sentences to the module that now owns the code. Add
runtime/update/** to the linux_packaging filter; the job and its gate
logic do not change. Add a "where new code goes" paragraph to the specs
of the facades that kept most of their file (config, acp-client, the
chat sidebar in history.md, the electron README). Record the composer's
benign effect reorder and the caption literals' whitespace in the files
that own them. Fix the README's auto-update export count, and prune six
docs-lint baseline entries that stopped firing when these refactors
fixed their cites.

test_ci_linux_packaging_filter.py walks the relative-require closure of
every Electron entry file the filter lists. It fails when a module that
closure loads is outside the filter, which is the case at the base.
@bolichen97
bolichen97 force-pushed the refactor/qf3-docs-ci-sync-wave3 branch from 2a31aa2 to d8845d9 Compare October 1, 2026 02:36
@bolichen97

Copy link
Copy Markdown
Contributor Author

Infra rerun on head d8845d9. Nine runs died on gh: API rate limit exceeded for installation before any verdict was posted, so each was rerun once with gh run rerun <id> --failed after the installation budget window passed. Request ids from the logs:

  • Design Review 36806630823 (7028:1711A1:1895C7B:518DD6F:6ABDC78B)
  • First Principles Review 36806630752 (0C00:1970B7:6A25CE:77116C:6ABDC7A1)
  • GPT 5.6 Review 36806630801 (F401:153284:18A9D34:51AC36F:6ABDC824)
  • Opus 5 Review 36806630831 (8430:197DD1:8B49CA:9836EA:6ABDC79A)
  • Publish readiness signal 36806627047 (E400:129F88:26ADB09:7EAC9FC:6ABDC739)
  • Screenshot Evidence 36806630780 (08F2:1FF954:1863D8D:50C2F62:6ABDC7A7)
  • Security scope candidates / validation / review 36806630819 (E038:1B89CC:26BB65B:7F4F075:6ABDC782; the validation and review jobs failed only because the candidates job wrote nothing)
  • UX Review 36806630808 (8800:2E597:71B7F6:7EA239:6ABDC791)
  • Resolve desktop matrix 36806630838 (8553:23BA43:2301478:7399A4C:6ABDC762)

macOS Tests / Backend Tests (macOS) (4) is not rerun; it is a real failure. test_sandbox_mount_pinned_target.py::test_the_directory_loop_records_every_window_it_binds raises AttributeError: module 'os' has no attribute 'O_PATH' (O_PATH is Linux-only), and test_terminal_commands.py::TestRunProbe::test_the_environment_is_an_allowlist_not_a_filtered_inherit@sandbox_probe fails too. This PR touches neither test nor the code they exercise; it changes only comments, docs, one CI path and a new CI-filter test.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 1, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebase probe for green age. Main moved 7460284 -> 7114800. In that range, #15672 edits docs/system-specs/modules/acp-client.md near L904, away from this PR's L28 paragraph, and #15636 edits sandbox/platform_compat code this PR does not touch. git merge-tree is clean.

I cherry-picked this head (d8845d9) onto 7114800 in a throwaway worktree:

  • scripts/docs_lint.py: passes, 34 stale baseline entries (unchanged).
  • With PYTHONPATH set to the probe's src, these all pass, 476 tests: test_ci_linux_packaging_filter.py, test_local_gate.py, test_docs_lint_fact_checks.py, test_issue_radar_pipeline_routes.py, test_ask_question_roundtrip.py, test_app_mcp_scoping.py, and the two test files upstream changed in that range (test_cgroup_scope_probe_liveness.py, test_session_token_identity.py).

So no rebase push for this staleness.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 1, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

/ai-review override fable d8845d9: Opus was withheld twice by the CI installation API rate limit (runs 36806630831 attempts 1-2); the attempt-2 withheld-verdict artifact (verdict.md) reads 'Opus 5 Review — no blocking findings', and its single advisory (scripts/smoke-linux-packages.sh absent from linux_packaging) is a pre-existing CI-filter gap since #4174, out of this docs-only PR's goal and logged as a CI-maintainer follow-up.

@bolichen97

Copy link
Copy Markdown
Contributor Author

/ai-review override scope d8845d9: Security Scope attempt 1 (run 36806630819) died on the CI installation API rate limit before candidates.json was written; the attempt-2 rerun measured success but is pinned by the per-head monotonic floor to the infra failure; this head changes only comments, docs, one ci.yml path-filter line and a test, with no security-relevant code.

@github-actions

github-actions Bot commented Oct 1, 2026

Copy link
Copy Markdown
Contributor

Human judgment recorded

@bolichen97 marked the fable AI finding as false positive, not applicable, or explicitly accepted for d8845d9ca158d012e726c3bbbf9d80386a79740c.

Opus was withheld twice by the CI installation API rate limit (runs 36806630831 attempts 1-2); the attempt-2 withheld-verdict artifact (verdict.md) reads 'Opus 5 Review — no blocking findings', and its single advisory (scripts/smoke-linux-packages.sh absent from linux_packaging) is a pre-existing CI-filter gap since #4174, out of this docs-only PR's goal and logged as a CI-maintainer follow-up.

This decision applies only to this commit. A new push requires a new judgment.

@github-actions

github-actions Bot commented Oct 1, 2026

Copy link
Copy Markdown
Contributor

Human judgment recorded

@bolichen97 marked the scope AI finding as false positive, not applicable, or explicitly accepted for d8845d9ca158d012e726c3bbbf9d80386a79740c.

Security Scope attempt 1 (run 36806630819) died on the CI installation API rate limit before candidates.json was written; the attempt-2 rerun measured success but is pinned by the per-head monotonic floor to the infra failure; this head changes only comments, docs, one ci.yml path-filter line and a test, with no security-relevant code.

This decision applies only to this commit. A new push requires a new judgment.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention labels Oct 1, 2026

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed. Every hunk in host_auth.py, hooks.py, config/loader.py, config/sections.py and agent_files.py is comment or docstring text; the adf_markdown_safety.json change touches only the description strings; five re-pointed references resolve on main. Two items are not docs and should be said in the title or body: ci.yml:159-161 adds website/electron/runtime/update/** to the linux_packaging paths filter (that job now runs for diffs there, which is correct since the lane files live there), and test/test_ci_linux_packaging_filter.py is a new executable gate that follows the require() chain from each entry file. Both read as right; the macOS shard red is the inherited pair that #15680 fixes.

@iamwhatever
iamwhatever enabled auto-merge (squash) October 1, 2026 04:54
@iamwhatever
iamwhatever merged commit ac2ac45 into main Oct 1, 2026
114 of 132 checks passed
@iamwhatever
iamwhatever deleted the refactor/qf3-docs-ci-sync-wave3 branch October 1, 2026 04:54
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants