Skip to content

refactor(core): Compact the Engine's comments #747

Closed

Description

@omesser

Part 3 of #744. The largest slice.

Scope

crates/core/** — 22 files, 16,094 code lines, 4,124 comment lines (20%), 367 blocks over 3 lines, 295 citing an issue or ADR.

Heaviest: engine.rs (1,241), director.rs (416), character.rs (412), roster.rs (202), input.rs (198), window_source.rs (193), visibility.rs (192), overlay.rs (183), memory.rs (174), snapshot.rs (165), engine/geometry.rs (151).

Land it as three PRs, not one

A diff touching 4,124 comment lines is not reviewable in any grouping.

  1. engine.rs alone — 1,241 lines
  2. director.rs + character.rs — 828
  3. The remaining 19 files

Watch out

#689 (feat(engine): Land a dropped Prop on a Perch) is open against engine.rs. Its owner goes first — rebase after it lands rather than fighting it. #608 (timber-wolf) touches the character and animation path.

crates/core/src/character.rs has a 64-line module doc, the longest block in the repo, and it is the file the current standard draws its exemplary example from. Expect to cut hard there.

crates/core/src/memory.rs carries a sanctioned ponytail: comment. Leave it whole.

Before you start

Read #744 in full. It carries the bar, the five-step decision procedure, the hazards and the verification checklist. This issue only names your slice. Wait for #745 (the amended standard) so you compact to the new bar, not the old one.

The rule, in one line

Cap blocks at 3 lines. Delete blocks that only restate the code. Keep the one-line summary on any public item. A comment you do not understand is not a comment you are qualified to delete.

Truncating alone lands at 13.4%, not 10%. Two rules, not one.

Verify

  • The diff touches no code line. Prove it over git diff -U0, do not assert it.
  • cargo test --workspace and node --test tests/*.test.js green, same counts before and after.
  • cargo clippy --workspace --all-targets -- -D warnings green.
  • Add the windows label to each PR, or that leg is lint-only and will not run the tests.
  • Census before and after in each PR description.

— Claude Code agent, on @omesser's behalf.

Activity

  1. added
    ready-for-agentFully specified, ready for an AFK agent
    p2Eventually: real, but nothing waits on it
    on Sep 15, 2026
  2. added this to the V1 milestone on Sep 15, 2026
  3. omesser commented on Sep 16, 2026

    @omesser
    OwnerAuthor

    Progress: slice 3 landed

    PR #780 merged on main (6d7713d).

    Done: the remaining-files slice — 12 files under crates/core/src/ (everything outside engine.rs, director.rs, character.rs, and the five #689 touches). Comment-only rewrite: 1460 → 898 comment lines in that batch, 133 → 8 blocks over three lines (eight named #744 exceptions). Proven no code-line changes; tests/clippy/fmt green.

    Still open on this issue:

    1. Slice 1 — engine.rs alone
    2. Slice 2 — director.rs + character.rs
    3. Follow-up after #689 lands — character/manifest.rs, character/resolve.rs, dispatch.rs, roster.rs, scheduler.rs (those five appear in the feat(engine): Land a dropped Prop on a Perch #689 diff; its owner goes first)

    Leaving this issue open. Umbrella #744 stays open.

    — Cursor agent (Coder), on @omesser's behalf.

  4. self-assigned this
    on Sep 17, 2026
  5. omesser commented on Sep 17, 2026

    @omesser
    OwnerAuthor

    Progress: slice 2 opened

    PR #807 is slice 2 (director.rs + character.rs). Comment-only. Census 831 → 580 comment lines. Three leftover >3 blocks are the two //! module docs and the Trigger ponytail:.

    Still open on this issue:

    1. Slice 1 — engine.rs (in flight on a separate branch)
    2. Follow-up after #689 lands — the five files that PR still owns

    — Cursor agent (Coder), on @omesser's behalf.

  6. omesser commented on Sep 17, 2026

    @omesser
    OwnerAuthor

    Progress: slice 1 opened

    PR #808 is slice 1 (engine.rs alone). Comment-only. Census 1193 → 814 comment lines, 114 → 3 blocks over three lines (module doc, PRIMITIVE_MS ponytail, #98 yank bound).

    Still open on this issue: follow-up after #689 for character/manifest.rs, character/resolve.rs, dispatch.rs, roster.rs, scheduler.rs.

    — Cursor agent (Coder), on @omesser's behalf.

  7. omesser commented on Sep 17, 2026

    @omesser
    OwnerAuthor

    Landed note: slice 2 (director.rs + character.rs) shipped in #807 (d5cd208). Comment-only; three named #744 exceptions kept (module docs + Trigger ponytail block).

    Still open on this issue: slice 1 (engine.rs) and the remaining 19-file pass. Out of scope leftovers called out on the PR (manifest/resolve/dispatch/roster/scheduler) stay under #689. Docs requote of the old PERSONALITY_LIMIT block is #745.

    Leaving this open.

    — Cursor agent (Coder), on @omesser's behalf.

  8. omesser commented on Sep 17, 2026

    @omesser
    OwnerAuthor

    Landed slice 1 (engine.rs) via #808 (fb09b278).

    Still open for this issue: slice 2 (director.rs + character.rs) as #807, then the remaining-files slice. Does not close #747.

    — Cursor agent (Coder), on @omesser's behalf.

  9. omesser commented on Sep 17, 2026

    @omesser
    OwnerAuthor

    Correction: slice 2 also landed — #807 (d5cd2087) merged just before #808.

    #747 still open for the remaining-files slice (the other ~19 core files). #689 follow-up noted in both PR bodies remains separate.

    — Cursor agent (Coder), on @omesser's behalf.

  10. omesser commented on Sep 17, 2026

    @omesser
    OwnerAuthor

    Progress: slice 1 landed (and slices 2–3 already on main)

    PR #808 merged on main (fb09b278). Slice 1 — engine.rs alone, comment-only. Census 1193 → 814 comment lines, 114 → 3 blocks over three lines (module doc, PRIMITIVE_MS ponytail, #98 yank bound). Proven no code-line changes on the PR.

    Correcting the notes just above: the three planned #747 slices are all on main now.

    Slice Scope PR Merge
    3 Remaining core files (12; not the #689 five) #780 6d7713d
    2 director.rs + character.rs #807 d5cd208
    1 engine.rs #808 fb09b278

    Still open on this issue: follow-up after #689 for character/manifest.rs, character/resolve.rs, dispatch.rs, roster.rs, scheduler.rs. Docs requote stays #745.

    Leaving this open. Umbrella #744 stays open.

    — Cursor agent (Coder), on @omesser's behalf.

  11. moved this from 👷 Todo to 🏗 In Progress in Fidgeton Sep 17, 2026
  12. omesser commented on Sep 17, 2026

    @omesser
    OwnerAuthor

    Claimed for a parallel implement run. One owner, one PR off main. Watch reviews until approved. Will not merge.

    — Grok Build agent, on @omesser's behalf.

  13. omesser commented on Sep 17, 2026

    @omesser
    OwnerAuthor

    Progress: leftover remaining-files slice opened

    Slice 2 (director.rs + character.rs) is already compact on main via #807. This run did not rewrite those files.

    PR #832 takes the next reviewable leftover: roster.rs, dispatch.rs, and scheduler.rs. Comment-only. Census 269 → 152 comment lines, 20 → 0 blocks over three lines. Proven no code-line changes.

    Still open on this issue:

    1. character/manifest.rs and character/resolve.rs after #689 (those two still have large diffs there)
    2. Slice 1 engine.rs already landed in refactor(core): Compact Engine comments #808. Slice 3 already landed in refactor(core): Compact the Engine's comments, remaining files (#747 slice 3) #780.

    Does not close #747.

    — Grok Build agent, on @omesser's behalf.

  14. moved this from 🏗 In Progress to 🏁 Done in Fidgeton Sep 18, 2026
  15. omesser commented on Sep 18, 2026

    @omesser
    OwnerAuthor

    Reopened: #832 landed part of the leftover, not the whole issue

    #832 merged on main (b30e4f37). Comment-only on roster.rs, dispatch.rs, and scheduler.rs (269 → 152 comment lines, 20 → 0 blocks over three lines). The PR body and commit both said Refs #747 — does not close.

    GitHub still closed this issue via the merge link. That was too early.

    On main for #747 now:

    Slice Scope PR
    3 Remaining core files (12; not the #689 five) #780
    2 director.rs + character.rs #807
    1 engine.rs #808
    leftover (partial) roster.rs, dispatch.rs, scheduler.rs #832

    Still open on this issue: character/manifest.rs and character/resolve.rs after #689 (draft; those two still have large diffs there). Umbrella #744 stays open.

    — Cursor agent (Coder), on @omesser's behalf.

  16. omesser commented on Sep 26, 2026

    @omesser
    OwnerAuthor

    Progress: Character Manifest parser comments landed

    #1030 merged on main (d3497e0b). Comment-only on crates/core/src/character/manifest.rs (100 → 69 comment lines, 11 → 0 blocks over three lines). Proven no code-line changes on the PR.

    On main for #747 now:

    Slice Scope PR
    3 Remaining core files (12; not the #689 five) #780
    2 director.rs + character.rs #807
    1 engine.rs #808
    leftover (partial) roster.rs, dispatch.rs, scheduler.rs #832
    leftover (partial) character/manifest.rs #1030

    Still open on this issue: character/resolve.rs (still 9 blocks over three lines on main as of this check). Draft #689 remains open/V2 and still edits overlapping character paths.

    Does not close #747. Umbrella #744 stays open.

    — Cursor agent (Coder), on @omesser's behalf.

  17. omesser commented on Sep 26, 2026

    @omesser
    OwnerAuthor

    Done: last leftover on main

    #1031 merged on main (5dd08e3a). Comment-only on crates/core/src/character/resolve.rs (95 → 57 comment lines, 9 → 0 blocks over three lines; //! module header exempt). Re-checked on main after the merge: 57 comment lines, 0 blocks over three lines.

    On main for #747 now:

    Slice Scope PR
    3 Remaining core files (12; not the #689 five) #780
    2 director.rs + character.rs #807
    1 engine.rs #808
    leftover roster.rs, dispatch.rs, scheduler.rs #832
    leftover character/manifest.rs #1030
    leftover character/resolve.rs #1031

    Acceptance for this child is met. Closing as completed. Draft #689 (Prop / V2) stays open and is a different job.

    — Cursor agent (Coder), on @omesser's behalf.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

p2Eventually: real, but nothing waits on itready-for-agentFully specified, ready for an AFK agentrefactoring

Projects

  • Status
    Done

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions