Skip to content

Session Handoff [sentence-length]: Hub Code Comment Sweep Next, Hub-Only Markdown Sweep Shipped in 2.0.1251 #3575

Closed

Description

@ptr727

Next steps, in priority order

  1. Sweep the hub code comments and docstrings. 1662 hits at main 77d7ca35, all outside Markdown, mostly under scripts/ and tests/. Re-count with python3 scripts/prose_lint.py --check sentence-length and group by file before slicing. A comment-only pull request needs the comments label and PROSE_ALLOW_COMMENTS=1 on its commits, as Split the Over-Length Sentences in the Secrets Shell Library Comments #3581 did. Also align the "Copies left for the comment sweep" pairs listed in the bodies of Split the Over-Length Sentences in scripts/README.md #3594, Split the Over-Length Sentences in the Host Setup Docs #3595, and Split the Over-Length Sentences in the Spec and Repo-Config Docs #3597 with their Markdown splits. Use the Say What a Carrier's Local Strict Review Does With Sentence-Length Hits on Hub-Verbatim Text #3531 brief and its round 3 and round 4 addenda as the worker brief. Done: the whole tree reads zero.
  2. Make sentence-length a default check once the tree reads zero. Delete the comment-and-doc-style text calling it opt-in "because the existing corpus predates the cap". Done: Say What a Carrier's Local Strict Review Does With Sentence-Length Hits on Hub-Verbatim Text #3531 closes on that promotion.
  3. Move the Dispatch-Refresh Note Out of the Docker Clause in branching-and-release-model #3588: move the dispatch-refresh note out of the Docker clause in branching-and-release-model. One small skill edit, sharing no file with step 1.
  4. Make pr_review.py and Merge Gate Item 2 Agree on an Earlier-Head Copilot Refusal #3571: make pr_review.py and Merge Gate item 2 agree on a Copilot refusal that landed on an earlier head. Independent of the steps above.
  5. Nothing Checks That the Host CLAUDE.md Blocks Stay in Sync With Their Governance Sections #3601, filed this round: nothing checks that the host CLAUDE.md blocks stay in sync with their governance sections. It lists three choices and needs a design pick before any code.

External blockers

Internal dependencies

  • Step 1 before step 2. The gate fails on any remaining hit.
  • Within a round, no two slices share a file. A comment that restates a Markdown sentence follows the Markdown's split. So a slice takes the pair list from the PR bodies named in step 1.
  • A skills-touching slice (step 3, or any comment in a generated tree) holds the single .source-digest line, so at most one runs at a time.

State

Re-derive each of these. Do not trust the copy here.

The parked decision queue

Zero open decision issues at close. The maintainer answered this round's questions in session. They granted develop merges for this session's slices, Sonnet workers with opus review in two waves of four, and Markdown-only scope. They accepted the recorded local pass for Copilot-refused slices, and feature-pull-request coverage on #3600. They chose merge, Skills refresh, and release.

What the last round did

What not to repeat

  • Merging on coverage=none. Split the Over-Length Sentences in the Spec and Repo-Config Docs #3597 merged with its local pass recorded but never attested, and Copilot had reviewed only an earlier head. Read coverage= on the status line before every merge.
  • Letting a worker merge. The auto-mode classifier refused two workers' develop merges as "Merge Without Review". Workers hand back at ready, and the orchestrator merges.
  • A stop rule with room for a budget. Three of eight workers stopped with findings on new sentences unfixed, reading the per-sentence rule as a pass cap. Brief "no pass cap" explicitly at dispatch.
  • Splitting a long list into two partial lists. Reviewers read "the first three ... the last two" as closed. Convert to a lead sentence plus bullets.

New learnings

Activity

  1. added
    handoffA link in the session handoff chain, one open issue per track
    on Oct 28, 2026
  2. ptr727 commented on Oct 28, 2026

    @ptr727
    OwnerAuthor

    Added to this track, to be ranked into the next round's next steps: #3577, the 23 sentence-length hits in lib/sh/secrets.sh at b72f50f3. The file is carried byte-locked into lib/fleet/sh, so every carrier's first carry pull request reports these hits and cannot fix them. That ranks it with the skill-source sweep (step 2) rather than with the hub-only text (step 3). The slice is that one file, and it shares no file with the split audits in flight. The Blog session filed it while carrying lib/fleet/sh (Blog #561).

  3. ptr727 commented on Oct 28, 2026

    @ptr727
    OwnerAuthor

    Round 1, closed 2026-10-28: Session Handoff [sentence-length]: Split Audit of the Swept GOVERNANCE, AGENTS and WORKFLOW Text Next

    Next steps, in priority order

    1. Split-audit the sweeps already on main: Bring GOVERNANCE.md Sentences to 25 Words or Fewer #3551 (GOVERNANCE.md), Bring AGENTS.md and copilot-instructions.md Sentences to 25 Words or Fewer #3559 (AGENTS.md, .github/copilot-instructions.md), Bring WORKFLOW.md Sentences to 25 Words or Fewer #3561 (WORKFLOW.md). Compare every split each made with its original (git show <squash>) and repair any that lost meaning. Done: one PR per source file group, each split listed in its body, with a Copilot round whose table names every changed file. Each audit of a later sweep found 12 to 16 broken splits, so expect some here.
    2. Sweep the remaining skill sources under .agents/skills/: 484 hits across 29 files. The largest are local-strict-review, comment-and-doc-style (with its references/), skill-lifecycle, repo-worktree, branching-and-release-model/references/release-publish-mechanics.md, and merge-and-release. Done: zero hits per file. Each brief requires split-by-split comparison before review, per the Say What a Carrier's Local Strict Review Does With Sentence-Length Hits on Hub-Verbatim Text #3531 brief comment.
    3. Sweep the hub-only text: 1685 hits in code comments and docstrings, and 1518 in other Markdown (scripts/README.md, TODO.md, docs/, reports/). Lower priority, since no carrier copies it, but the ruling covers the whole hub.
    4. Make sentence-length a default check once the tree reads zero. Delete the comment-and-doc-style text calling it opt-in "because the existing corpus predates the cap". Done: Say What a Carrier's Local Strict Review Does With Sentence-Length Hits on Hub-Verbatim Text #3531 closes on that promotion.
    5. Make pr_review.py and Merge Gate Item 2 Agree on an Earlier-Head Copilot Refusal #3571: make pr_review.py and Merge Gate item 2 agree on a Copilot refusal that landed on an earlier head. Independent of the steps above.

    External blockers

    Internal dependencies

    • Step 1 before step 4. The gate locks in whatever the text says, so meaning drift is fixed first.
    • Step 2 before step 4, and step 3 before step 4. The gate fails on any remaining hit.
    • Within a round, no two slices share a file, generated copies included. Each GOVERNANCE.md, AGENTS.md, CODESTYLE.md, or WORKFLOW.md section included by a skill regenerates that skill. Read the include markers (grep -rhoE 'include: [A-Z]+\.md > [^>]*' .agents/skills) before grouping.

    State

    Re-derive each of these. Do not trust the copy here.

    The parked decision queue

    Zero open decision issues at close. #3502 is a held design proposal, not a parked decision.

    What the last round did

    Driven by the backlog-burndown skill over four rounds and four promotions. Promotion #3544 went to main 65adbf17, #3553 to 54f477a6, #3562 to a5bfc9c2, and #3572 to 1abb46f2.

    What not to repeat

    New learnings

  4. changed the title [-]Session Handoff [sentence-length]: Split Audit of the Swept GOVERNANCE, AGENTS and WORKFLOW Text Next[/-] [+]Session Handoff [sentence-length]: Skill-Source Sweep and lib/sh/secrets.sh Next, Split Audits Shipped in 2.0.1234[/+] on Oct 28, 2026
  5. ptr727 commented on Oct 28, 2026

    @ptr727
    OwnerAuthor

    Closing answers for round 2, from the maintainer on 2026-10-28:

    • Worktree sweep: approved. cleanup --sweep --apply removed ProjectTemplate-lint-homepage and hub-w1493. It kept the two dirty Financial-Modeling scratch hubs.
    • Host-safety kit: the maintainer is running the installer from the primary checkout. Re-check it with install.py --report at resume rather than assuming it reads CURRENT.

    Parked decision queue: zero open decision issues.

  6. ptr727 commented on Oct 29, 2026

    @ptr727
    OwnerAuthor

    Round 2, closed 2026-10-28: Session Handoff [sentence-length]: Skill-Source Sweep and lib/sh/secrets.sh Next, Split Audits Shipped in 2.0.1234

    Next steps, in priority order

    1. Sweep the remaining skill sources under .agents/skills/: 484 hits across 29 files at develop b82a4a0d. The largest are local-strict-review (54), comment-and-doc-style (48, plus 24 in references/line-endings.md), skill-lifecycle (36), repo-worktree (35), branching-and-release-model/references/release-publish-mechanics.md (34), and merge-and-release (32). Two known leftovers sit there: 12 hits in agent-conduct outside its include regions, and one 28-word sentence in the workflow-ci-contract references/d-guarantees.md preamble. Done: zero hits per file. Each worker compares every split with its original before review, per the Say What a Carrier's Local Strict Review Does With Sentence-Length Hits on Hub-Verbatim Text #3531 brief comment.
    2. Split the Over-Length Comment Sentences in lib/sh/secrets.sh #3577: the 23 hits in lib/sh/secrets.sh. The file is carried byte-locked into lib/fleet/sh, so every carrier's first carry PR reports them and cannot fix them. One-file slice, sharing no file with step 1. Done: prose_lint.py --check sentence-length lib exits 0.
    3. Sweep the hub-only text: about 1685 hits in code comments and docstrings, and 1518 in other Markdown (scripts/README.md, TODO.md, docs/, reports/). Lower priority, since no carrier copies it, but the ruling covers the whole hub. Re-count before slicing.
    4. Make sentence-length a default check once the tree reads zero. Delete the comment-and-doc-style text calling it opt-in "because the existing corpus predates the cap". Done: Say What a Carrier's Local Strict Review Does With Sentence-Length Hits on Hub-Verbatim Text #3531 closes on that promotion.
    5. Make pr_review.py and Merge Gate Item 2 Agree on an Earlier-Head Copilot Refusal #3571: make pr_review.py and Merge Gate item 2 agree on a Copilot refusal that landed on an earlier head. Independent of the steps above.

    External blockers

    Internal dependencies

    • Steps 1, 2 and 3 before step 4. The gate fails on any remaining hit.
    • Within a round, no two slices share a file, generated copies included. Read the include markers (grep -rhoE 'include: [A-Z]+\.md > [^>]*' .agents/skills) before grouping. A skill-source slice edits text outside the include regions, so its only generated files are that skill's own copies and digest.

    State

    Re-derive each of these. Do not trust the copy here.

    The parked decision queue

    Zero open decision issues at close.

    What the last round did

    What not to repeat

    • Trusting a sweep's local passes for meaning. All five audits so far found 10 to 16 broken splits per sweep. A sweep worker compares each split with its original before review. An audit is still owed for any sweep merged without that.
    • Running hub scripts with bare python3 on this host. build_dist.py and pr_review.py import markdown_it, which the system Python lacks. Use uv run --no-project --script scripts/<name>.py.
    • Posting text before its check passes. Gate the post as prose_lint.py --check sentence-length F && gh .... The promotion worker's first body draft failed the gate, and the gate stopped it.

    New learnings

  7. changed the title [-]Session Handoff [sentence-length]: Skill-Source Sweep and lib/sh/secrets.sh Next, Split Audits Shipped in 2.0.1234[/-] [+]Session Handoff [sentence-length]: Hub-Only Markdown and Comment Sweep Next, Skill-Source Sweep Shipped in 2.0.1242[/+] on Oct 29, 2026
  8. ptr727 commented on Oct 29, 2026

    @ptr727
    OwnerAuthor

    Closing answers for round 3, from the maintainer on 2026-10-28:

    Parked decision queue: zero open decision issues.

  9. ptr727 commented on Oct 29, 2026

    @ptr727
    OwnerAuthor

    Round 3, closed 2026-10-29: Session Handoff [sentence-length]: Hub-Only Markdown and Comment Sweep Next, Skill-Source Sweep Shipped in 2.0.1242

    Next steps, in priority order

    1. Sweep the hub-only Markdown: 1518 hits at main 13c2b8b1. The largest are scripts/README.md (303), TODO.md (178), docs/reusable-workflows.md (126), STANDUP.md (83), docs/fleet-map.md (78), AUDIT.md (73), docs/host-setup.md (70), and README.md (61). Re-count before slicing. Done: zero hits per file. Use the Say What a Carrier's Local Strict Review Does With Sentence-Length Hits on Hub-Verbatim Text #3531 brief and its round 3 addendum as the worker brief.
    2. Sweep the hub code comments and docstrings: 1662 hits, mostly under scripts/ and tests/. A comment-only pull request needs the comments label and PROSE_ALLOW_COMMENTS=1 on its commits, as Split the Over-Length Sentences in the Secrets Shell Library Comments #3581 did. Done: the whole tree reads zero.
    3. Make sentence-length a default check once the tree reads zero. Delete the comment-and-doc-style text calling it opt-in "because the existing corpus predates the cap". Done: Say What a Carrier's Local Strict Review Does With Sentence-Length Hits on Hub-Verbatim Text #3531 closes on that promotion.
    4. Move the Dispatch-Refresh Note Out of the Docker Clause in branching-and-release-model #3588: move the dispatch-refresh note out of the Docker clause in branching-and-release-model. One small skill edit, sharing no file with steps 1 and 2.
    5. Make pr_review.py and Merge Gate Item 2 Agree on an Earlier-Head Copilot Refusal #3571: make pr_review.py and Merge Gate item 2 agree on a Copilot refusal that landed on an earlier head. Independent of the steps above.

    External blockers

    Internal dependencies

    • Steps 1 and 2 before step 3. The gate fails on any remaining hit.
    • Within a round, no two slices share a file. A hub-only doc may be an include source, so read the include markers (grep -rhE '^<!--\s*include:' .agents/skills) before grouping. Keep a doc that feeds a skill in the same slice as that skill's regenerated copies.

    State

    Re-derive each of these. Do not trust the copy here.

    The parked decision queue

    Zero open decision issues at close. The maintainer answered this round's two questions in session. They accepted feature-pull-request coverage on #3589, and chose merge, Skills refresh, and release.

    What the last round did

    What not to repeat

    • A stop rule that does not say what it counts. "More than two fix rounds" was read as two review passes over the branch. One worker stopped unpushed, and another pushed with known drifts. State it per sentence.
    • Letting workers settle a contested sentence. On slice A, opus reviewers flipped one description sentence for four rounds. An orchestrator ruling against the original, marked final, ended it in one pass.
    • Calling a pull request clean at 0 threads. The body of a Copilot round can carry [P2] items with no thread, and on Split the Over-Length Sentences in the Codestyle and Guard Skills #3583 both were real drifts.

    New learnings

  10. changed the title [-]Session Handoff [sentence-length]: Hub-Only Markdown and Comment Sweep Next, Skill-Source Sweep Shipped in 2.0.1242[/-] [+]Session Handoff [sentence-length]: Hub Code Comment Sweep Next, Hub-Only Markdown Sweep Shipped in 2.0.1251[/+] on Oct 29, 2026
  11. ptr727 commented on Oct 29, 2026

    @ptr727
    OwnerAuthor

    Closing answers for round 4, 2026-10-29:

    • Host-safety kit: the maintainer re-ran install.py after release 2.0.1251. install.py --report reads CURRENT at a tree identical to main 77d7ca35, so the round 4 "Host-safety kit is stale" blocker is resolved.

    Parked decision queue: zero open decision issues.

  12. ptr727 commented on Oct 29, 2026

    @ptr727
    OwnerAuthor

    Outcome: track complete (round 5, closed 2026-10-29)

    The sentence-length track's goal is done. The whole hub tree reads 0 sentence-length hits, down from 6964 when the track started. The rule is now a default prose-gate check fleet-wide, and #3531 is closed. Shipped in release 2.0.1262, from main f24e9f17 (promotion #3619, publish run 40935484439, success).

    What round 5 did

    Where the remaining work lives

    Each is an ordinary backlog issue now rather than a step on this track:

    State at close

    • main is f24e9f17 and develop is 487deaa6. The primary checkout is on develop, current, and clean.
    • Every branch and worktree this round created is removed. cleanup --sweep lists only other sessions' worktrees, kept as too recent.
    • The skills snapshot reads current at f24e9f17.
    • The host-safety kit reads STALE, since Split the Over-Length Comment Sentences in the Agent-Safety Kit, Repo Config, and Snippets #3615 changed its comments. Only the maintainer reruns host-setup/agent-safety/claude/install.py.

    What not to repeat

    • Recording a local pass no reviewer ran. One worker recorded digests for two unreviewed commits "itself". A real whole-branch pass afterwards found about 15 genuine split drifts. The brief now says a recorded pass must be one a reviewer actually ran.
    • Handing back before ready. Two workers called the handback while their own reviewer or CI wait was still running, which ends the run. Brief "do not hand back until ready or blocked".
    • Force-pushing after a rebase. One worker tried it, and the permission system denied it. A squash merge needs no rebase, so merge develop in instead.
    • Assuming a develop merge leaves a promotion alone. A promotion's head is develop, so any develop merge moves it and triggers a new Copilot round.
    • A shared scratch helper. Two workers overwrote each other's apply.py. Namespace helpers per branch.
    • Splitting a shared .ps1/.sh comment in two parallel slices. F1 and F2 split the same copies differently (Align the Comment Copies the Sentence Sweep Split Two Ways, and Fix Three Stale Counts #3622). Put both halves of a copy pair in one slice.

    New learnings

    The parked decision queue

    There is one open decision issue: #3616, ruff pinning, filed this round. It is put to the maintainer in this session, and the answer is commented here.

  13. ptr727 commented on Oct 29, 2026

    @ptr727
    OwnerAuthor

    Closing answer, 2026-10-29: the maintainer decided #3616 as a Dependabot-managed ruff pin with no fleet canary, recorded on #3616, and its decision label is removed.

    Parked decision queue after this round: zero open decision issues.

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    handoffA link in the session handoff chain, one open issue per track

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions