Correct GOALS.md, PLAN.md, PROJECT_STATE.md and IRREDUCIBLE_SURFACE.md — audit found them materially stale

[JDonaghy]

Problem

A four-agent audit of develop @ ee26268 (2026-09-04) found the project's planning documents materially stale. Because GOALS.md is the standing objective every agent plans against, and docs/IRREDUCIBLE_SURFACE.md is what planning treats as fixed constraints, wrong entries actively misdirect work.

Per feedback_coordinator_docs, session docs are the coordinator's to write — this issue exists so the corrections are tracked, not so any agent edits them ad hoc.

Corrections required

GOALS.md

§3 "#47 was closed without its blocker" is stale. It says "No open quadraui issue mentions modal_stack_handle or drag_state_handle" and lists filing it as "the single most actionable item on this page". In fact:

• quadraui#699 was filed 2026-09-03 16:38Z, into milestone v0.3.6: Spell checker, z= suggestions, UI polish #9, and closed 17:11Z (PR#700 / 88345fb). Follow-up VS Code parity (Tier 2b of #699): GTK UI font stack (blocked on quadraui#624) + panel separator borders #704 closed 21:41Z.
• vimcode#47 was reopened 16:38Z and is OPEN in milestone fix: regenerate Flatpak vendor sources for v0.3.2 #5 — it is not closed.
• The last GOALS.md edit (5e2c7cc) was 18:32Z, 81 minutes after GTK chrome: close the visual gap with VS Code — type size, vertical rhythm, tab/breadcrumb metrics #699 had closed, and left §3, the Status block and the milestones table saying the blocker was unfiled.
• quadraui milestone v0.3.6: Spell checker, z= suggestions, UI polish #9 exists and is open (0 open / 7 closed) — the doc's instruction to "re-open" it is wrong.
• The "44 call sites" figure is wrong. It came from grep -n 'self\.backend\.' src/gtk/mod.rs — every use of the field, not the two methods. The real count is 19 (modal_stack_handle ×12, drag_state_handle ×7). Fix in PLAN.md too, which is where it originates.

§2 "the duplication moved down a level, into quadraui" is largely refuted at vimcode's own pinned rev:

Claim	Reality at pin 42e0f8f
EventOutcome declared twice verbatim	Declared once — quadraui/src/runtime.rs:95 (quadraui#496, closed 09-02)
shell_runner 45 identical lines ×2	Four runners of 4–7 non-comment lines each, all delegating to shared shell_adapter.rs::build_shell_adapter
1,671 byte-identical lines gtk↔macos	Function-level duplication is ~85 lines. quadraui#481's own correction comment (09-03 17:45Z) withdrew the headline number as "idiom coincidence"
UTF-8 fix: 7 private copies, 0 public	Public since 2026-08-15 — text_util.rs:51-107, re-exported from lib.rs (quadraui#503)
gtk_tree_layout/mac_tree_layout twins	Both 1-line wrappers over primitives/layout_metrics.rs:60 tree_layout (quadraui#499, 09-02)
"no desktop/"	quadraui/src/desktop.rs exists (754 lines) since 09-02 (quadraui#498) — the audit grepped for a directory
#482 "holds the mass"	All eight children #503–#510 are closed. #482 has zero comments and is a hollow epic

Still true: macOS dispatches WindowResized undebounced (macos/run.rs:544-561) while TUI/GTK use the shared ResizeDebouncer.

§ "the post-#735 audit" under-attributes the backend reduction. Of the −3,656, about −2,825 is #731/#732 dead-code removal. Convergence proper moved roughly 900 lines out of the backends while render.rs absorbed ~7,000. State that plainly — the current text implies the chain converged more than it did.

Regenerate the size table. Measured at ee26268 with scripts/prod_lines.py: src/gtk/ 2,607, src/app.rs 7,131, src/tui_main/ 10,366 (backends 20,104), src/render.rs 21,405. The src/gtk/ column in the current table (9,650) predates #785's move.

docs/IRREDUCIBLE_SURFACE.md

The folder-picker verdict is wrong (:24). It records the TUI-only folder picker as irreducible because GTK uses a native GtkFileChooser. quadraui::compose::FolderPickerController has existed since 2026-05-25 and its module doc explicitly instructs vimcode to remove the local copy and rewire both backends. Strike the row and note why the verdict was wrong — the aggregation did not check upstream.

Add a caveat about the unit_w/unit_h seam. The doc blesses FrameMetrics as the one unit seam; in practice the convention appears in 7 painter signatures across 33 uses, and render.rs additionally carries two explicit char_width > 1.0 backend sniffs (:10426, :17256) and five paired per-backend policy tables. Record the real state.

PROJECT_STATE.md and PLAN.md

Both repeat the "#47 blocker filed nowhere" claim and the 44-call-site figure. Correct both.

Acceptance

• Pure documentation change — may be committed directly to develop per CLAUDE.md, no branch required.
• Every corrected number regenerated with scripts/prod_lines.py / scripts/native_lines.py and cited with the revision it was measured at, per GOALS.md's own "regenerate, do not trust a number typed into prose" rule.

[JDonaghy]

Sequencing note. This is queued early — second, right after the pin bump — because the stale claims actively misdirect planning, and every worker on the 15 issues behind it reads GOALS.md at session start. The #47 blocker claim in particular tells a reader to file something that was filed, fixed and closed on 2026-09-03.

The factual corrections (blocker status, the quadraui§2 refutations, the folder-picker verdict, the 44-call-site figure) are stable and should be made now.

The size table will go stale again as this chain lands. Regenerate it with scripts/prod_lines.py when the chain drains rather than treating this pass as final, and say so in the doc so the next reader knows which revision each column was measured at.

[JDonaghy]

Coordinator Assignment

Machine: dell64
Repo: vimcode
Files: (unspecified)
Do not touch: (nothing else in flight)

Briefing

Issue #827: Correct GOALS.md, PLAN.md, PROJECT_STATE.md and IRREDUCIBLE_SURFACE.md — audit found them materially stale

Problem

A four-agent audit of develop @ ee26268 (2026-09-04) found the project's planning documents materially stale. Because GOALS.md is the standing objective every agent plans against, and docs/IRREDUCIBLE_SURFACE.md is what planning treats as fixed constraints, wrong entries actively misdirect work.

Per feedback_coordinator_docs, session docs are the coordinator's to write — this issue exists so the corrections are tracked, not so any agent edits them ad hoc.

Corrections required

GOALS.md

§3 "#47 was closed without its blocker" is stale. It says "No open quadraui issue mentions modal_stack_handle or drag_state_handle" and lists filing it as "the single most actionable item on this page". In fact:

• quadraui#699 was filed 2026-09-03 16:38Z, into milestone v0.3.6: Spell checker, z= suggestions, UI polish #9, and closed 17:11Z (PR#700 / 88345fb). Follow-up VS Code parity (Tier 2b of #699): GTK UI font stack (blocked on quadraui#624) + panel separator borders #704 closed 21:41Z.
• vimcode#47 was reopened 16:38Z and is OPEN in milestone fix: regenerate Flatpak vendor sources for v0.3.2 #5 — it is not closed.
• The last GOALS.md edit (5e2c7cc) was 18:32Z, 81 minutes after GTK chrome: close the visual gap with VS Code — type size, vertical rhythm, tab/breadcrumb metrics #699 had closed, and left §3, the Status block and the milestones table saying the blocker was unfiled.
• quadraui milestone v0.3.6: Spell checker, z= suggestions, UI polish #9 exists and is open (0 open / 7 closed) — the doc's instruction to "re-open" it is wrong.
• The "44 call sites" figure is wrong. It came from grep -n 'self\.backend\.' src/gtk/mod.rs — every use of the field, not the two methods. The real count is 19 (modal_stack_handle ×12, drag_state_handle ×7). Fix in PLAN.md too, which is where it originates.

§2 "the duplication moved down a level, into quadraui" is largely refuted at vimcode's own pinned rev:

Claim	Reality at pin 42e0f8f
EventOutcome declared twice verbatim	Declared once — quadraui/src/runtime.rs:95 (quadraui#496, closed 09-02)
shell_runner 45 identical lines ×2	Four runners of 4–7 non-comment lines each, all delegating to shared shell_adapter.rs::build_shell_adapter
1,671 byte-identical lines gtk↔macos	Function-level duplication is ~85 lines. quadraui#481's own correction comment (09-03 17:45Z) withdrew the headline number as "idiom coincidence"
UTF-8 fix: 7 private copies, 0 public	Public since 2026-08-15 — text_util.rs:51-107, re-exported from lib.rs (quadraui#503)
gtk_tree_layout/mac_tree_layout twins	Both 1-line wrappers over primitives/layout_metrics.rs:60 tree_layout (quadraui#499, 09-02)
"no desktop/"	quadraui/src/desktop.rs exists (754 lines) since 09-02 (quadraui#498) — the audit grepped for a directory
#482 "holds the mass"	All eight children #503–#510 are closed. #482 has zero comments and is a hollow epic

Still true: macOS dispatches WindowResized undebounced (macos/run.rs:544-561) while TUI/GTK use the shared ResizeDebouncer.

§ "the post-#735 audit" under-attributes the backend reduction. Of the −3,656, about −2,825 is #731/#732 dead-code removal. Convergence proper moved roughly 900 lines out of the backends while render.rs absorbed ~7,000. State that plainly — the current text implies the chain converged more than it did.

Regenerate the size table. Measured at ee26268 with scripts/prod_lines.py: src/gtk/ 2,607, src/app.rs 7,131, src/tui_main/ 10,366 (backends 20,104), src/render.rs 21,405. The src/gtk/ column in the current table (9,650) predates #785's move.

docs/IRREDUCIBLE_SURFACE.md

The folder-picker verdict is wrong (:24). It records the TUI-only folder picker as irreducible because GTK uses a native GtkFileChooser. quadraui::compose::FolderPickerController has existed since 2026-05-25 and its module doc explicitly instructs vimcode to remove the local copy and rewire both backends. Strike the row and note why the verdict was wrong — the aggregation did not check upstream.

Add a caveat about the unit_w/unit_h seam. The doc blesses FrameMetrics as the one unit seam; in practice the convention appears in 7 painter signatures across 33 uses, and render.rs additionally carries two explicit char_width > 1.0 backend sniffs (:10426, :17256) and five paired per-backend policy tables. Record the real state.

PROJECT_STATE.md and PLAN.md

Both repeat the "#47 blocker filed nowhere" claim and the 44-call-site figure. Correct both.

Acceptance

• Pure documentation change — may be committed directly to develop per CLAUDE.md, no branch required.
• Every corrected number regenerated with scripts/prod_lines.py / scripts/native_lines.py and cited with the revision it was measured at, per GOALS.md's own "regenerate, do not trust a number typed into prose" rule.

[JDonaghy]

Coordinator: Assignment Complete

Machine: dell64
Status: done
Exit code: 0
Duration: 10m 31s
Log: /home/john/.coord/logs/b4dd1ac9d239.log

[JDonaghy]

Coordinator: Assignment Complete

Machine: dell64
Status: done
Exit code: 0
Duration: 3m 11s
Log: /home/john/.coord/logs/87d6bcc9815a.log

[JDonaghy]

Coordinator: Assignment Complete

Machine: precision
Status: done
Exit code: 0
Duration: —

Summary

Verdict: approve

Review findings

Blocking findings

None.

Non-blocking concerns

• GOALS.md §2's refutation table is checked "Re-checked against quadraui's own pinned rev (42e0f8f) on 2026-09-05," but the actual current quadraui pin in Cargo.toml at the reviewed commit is 4ff2a645... (bumped by Bump quadraui pin to HEAD (42 commits) and fix the 4 removed-API call sites — next bump does not compile #811, commit a57a430, which already landed on this same branch before this commit). GOALS.md §3 of the same file correctly states Bump quadraui pin to HEAD (42 commits) and fix the 4 removed-API call sites — next bump does not compile #811 bumped the pin to 4ff2a64 — so the doc is internally inconsistent about what "vimcode's own pinned rev" actually is at the moment this correction was written. I re-ran the specific §2 claims (EventOutcome declared once at runtime.rs:95, text_util.rs public since 2026-08-15/quadraui#503, layout_metrics.rs::tree_layout shared, desktop.rs exists, all four shell_runners delegate to build_shell_adapter) against both 42e0f8f and 4ff2a64 and they hold at both — so this doesn't change the substance of the correction, but given the issue's whole premise is "regenerate, don't trust a number... cite the revision it was measured at," citing the superseded pin instead of the tree's actual current pin is a specific instance of the exact failure mode this PR exists to fix.

Nits

• GOALS.md §2's "Still true" line says macOS is undebounced "while TUI/GTK use the shared ResizeDebouncer." Verified against quadraui 4ff2a64: only tui::run actually uses the ResizeDebouncer struct (it's the cfg(feature = "tui") type in runtime.rs); GTK achieves the same 120 ms settle via its own GLib-timer cancel-and-reschedule mechanism, sharing only the RESIZE_SETTLE constant/doc, not the ResizeDebouncer type. The conclusion (GTK and TUI both debounce, macOS does not) is correct — just the "shared ResizeDebouncer" phrasing overstates what's literally shared.

Verification performed

This is a pure documentation correction (GOALS.md, PLAN.md, PROJECT_STATE.md, docs/IRREDUCIBLE_SURFACE.md only — confirmed via git diff --stat against the immediate parent commit that no other files changed, and CLAUDE.md was untouched). Spot-checked a large number of the corrected numbers directly against the repo rather than trusting prose:

• scripts/prod_lines.py re-run against git archive ee26268 reproduces the new size table exactly: src/gtk/ 2607, src/tui_main/ 10366, src/render.rs 21405, src/app.rs 7131 (sum 20104, matches the "all three files" row).
• The "19 call sites" figure (modal_stack_handle ×12 + drag_state_handle ×7) reproduces exactly from grep -n 'modal_stack_handle\|drag_state_handle' src/app.rs at ee26268 minus the two doc-comment mentions, as the PR describes its own methodology.
• The 5e2c7cc timestamp claim ("81 minutes after GTK chrome: close the visual gap with VS Code — type size, vertical rhythm, tab/breadcrumb metrics #699 had closed, at 18:32Z") checks out precisely: git show -s --format=%ad --date=iso-strict 5e2c7cc gives 2026-09-03T13:32:03-05:00 = 18:32:03 UTC, and 18:32 − 17:11 = 81 minutes exactly.
• #785 (App hoist into src/app.rs) and #811 (quadraui pin bump to 4ff2a64, TUI call-site port) are real commits on this branch's own history (5e2c7cc, a57a430), matching the narrative.
• In the actual quadraui checkout: FolderPickerController was added 2026-05-25 (matches the IRREDUCIBLE_SURFACE.md correction exactly); EventOutcome is declared once at runtime.rs:95; text_util.rs's boundary-safe fns went public 2026-08-15 via quadraui#503 (exact date match); desktop.rs exists; the four shell_runner.rs files (gtk/tui/macos/win) all delegate to shell_adapter::build_shell_adapter in ~4-8 lines each, matching the "4-7 non-comment lines" description; macOS's view_frame_did_change dispatches WindowResized with no debounce logic at all.
• No test-suite run was performed (docs-only diff; project CLAUDE.md exempts pure .md changes from the branch/smoke workflow, and the black-box-coverage testing rule only applies to user-visible behavior changes, which this isn't).

Overall this is an unusually rigorous documentation correction — nearly every regenerated number and dated claim I checked against real git/repo history matched precisely, including minute-level timestamp arithmetic. The two items above are worth a follow-up but do not change the substance of any correction.

[JDonaghy]

Review Complete — ✅ Approved

Reviewer findings could not be posted directly to PR #838 (gh pr review was rejected — likely a self-review restriction). Findings are reproduced here.

Note: a completion comment was posted earlier but findings could not be extracted at that time. These are the retroactive findings.

Blocking findings

None.

Non-blocking concerns

• GOALS.md §2's refutation table is checked "Re-checked against quadraui's own pinned rev (42e0f8f) on 2026-09-05," but the actual current quadraui pin in Cargo.toml at the reviewed commit is 4ff2a645... (bumped by Bump quadraui pin to HEAD (42 commits) and fix the 4 removed-API call sites — next bump does not compile #811, commit a57a430, which already landed on this same branch before this commit). GOALS.md §3 of the same file correctly states Bump quadraui pin to HEAD (42 commits) and fix the 4 removed-API call sites — next bump does not compile #811 bumped the pin to 4ff2a64 — so the doc is internally inconsistent about what "vimcode's own pinned rev" actually is at the moment this correction was written. I re-ran the specific §2 claims (EventOutcome declared once at runtime.rs:95, text_util.rs public since 2026-08-15/quadraui#503, layout_metrics.rs::tree_layout shared, desktop.rs exists, all four shell_runners delegate to build_shell_adapter) against both 42e0f8f and 4ff2a64 and they hold at both — so this doesn't change the substance of the correction, but given the issue's whole premise is "regenerate, don't trust a number... cite the revision it was measured at," citing the superseded pin instead of the tree's actual current pin is a specific instance of the exact failure mode this PR exists to fix.

Nits

• GOALS.md §2's "Still true" line says macOS is undebounced "while TUI/GTK use the shared ResizeDebouncer." Verified against quadraui 4ff2a64: only tui::run actually uses the ResizeDebouncer struct (it's the cfg(feature = "tui") type in runtime.rs); GTK achieves the same 120 ms settle via its own GLib-timer cancel-and-reschedule mechanism, sharing only the RESIZE_SETTLE constant/doc, not the ResizeDebouncer type. The conclusion (GTK and TUI both debounce, macOS does not) is correct — just the "shared ResizeDebouncer" phrasing overstates what's literally shared.

Verification performed

This is a pure documentation correction (GOALS.md, PLAN.md, PROJECT_STATE.md, docs/IRREDUCIBLE_SURFACE.md only — confirmed via git diff --stat against the immediate parent commit that no other files changed, and CLAUDE.md was untouched). Spot-checked a large number of the corrected numbers directly against the repo rather than trusting prose:

• scripts/prod_lines.py re-run against git archive ee26268 reproduces the new size table exactly: src/gtk/ 2607, src/tui_main/ 10366, src/render.rs 21405, src/app.rs 7131 (sum 20104, matches the "all three files" row).
• The "19 call sites" figure (modal_stack_handle ×12 + drag_state_handle ×7) reproduces exactly from grep -n 'modal_stack_handle\|drag_state_handle' src/app.rs at ee26268 minus the two doc-comment mentions, as the PR describes its own methodology.
• The 5e2c7cc timestamp claim ("81 minutes after GTK chrome: close the visual gap with VS Code — type size, vertical rhythm, tab/breadcrumb metrics #699 had closed, at 18:32Z") checks out precisely: git show -s --format=%ad --date=iso-strict 5e2c7cc gives 2026-09-03T13:32:03-05:00 = 18:32:03 UTC, and 18:32 − 17:11 = 81 minutes exactly.
• #785 (App hoist into src/app.rs) and #811 (quadraui pin bump to 4ff2a64, TUI call-site port) are real commits on this branch's own history (5e2c7cc, a57a430), matching the narrative.
• In the actual quadraui checkout: FolderPickerController was added 2026-05-25 (matches the IRREDUCIBLE_SURFACE.md correction exactly); EventOutcome is declared once at runtime.rs:95; text_util.rs's boundary-safe fns went public 2026-08-15 via quadraui#503 (exact date match); desktop.rs exists; the four shell_runner.rs files (gtk/tui/macos/win) all delegate to shell_adapter::build_shell_adapter in ~4-8 lines each, matching the "4-7 non-comment lines" description; macOS's view_frame_did_change dispatches WindowResized with no debounce logic at all.
• No test-suite run was performed (docs-only diff; project CLAUDE.md exempts pure .md changes from the branch/smoke workflow, and the black-box-coverage testing rule only applies to user-visible behavior changes, which this isn't).

Overall this is an unusually rigorous documentation correction — nearly every regenerated number and dated claim I checked against real git/repo history matched precisely, including minute-level timestamp arithmetic. The two items above are worth a follow-up but do not change the substance of any correction.