Skip to content

Scripts refactor — low-risk cleanups across the long tail (gate framework, orphans, bash/script dedup) #601

Open

Description

@loganfinney27

Sub-issue of #586 (Map v1). Refactor track: the structure-preserving cleanups Map v1 surfaced — each independent, none requiring the big Cluster A redesign (its redesign sibling). Sources: the three deep-dive docs on PR #597.

Items

  1. Parameterized Cluster C gate framework (long-tail doc Q1). ~6 near-identical event-gate scaffolds (checkout → setup → run one guard script → fail/pass): check-portable-paths, check-dotfolder-anchors, check-notebooks-paired, laf-usb-manifest-policy, version-transition-policy, validate-agent-content. One reusable job taking script / trigger / paths would absorb the scaffold without forcing the gates' distinct logic together. Keep the scheduled-sweep + reconciler-reporting third leg opt-in (only the large-file twin-pair uses it; secret-pattern has event+sched but no reconciler issue).

  2. Account for the 9 orphan scripts (long-tail doc Q2). Scripts referenced by no workflow: audit_repo_payloads, backfill_daily_notes, bind_ai_book, date_tagger, expand_date_aliases, generate_name_forms, normalize_tags, obsidian_rest_api_client, phone_link_intake, tag_stubs. Identify each one's real caller (pre-commit hook / local runtime / manual / none) before any cleanup — confirming a caller is the line between infrastructure and dead code.

  3. Resolve the bash-vs-script domain splits (long-tail doc Q3). wayback-preserve reimplements URL-extraction in inline bash while its sibling wayback-audit already has wayback_audit.py; sync-dependencies runs inline uv lock/gh pr create overlapping dependency-submission-uv's uv_dependency_submission.py. Reuse the existing Python halves. (The 7 other inline-gh workflows are right-sized glue over vetted actions — leave them.)

  4. Unify the gh wrapper (reporting-substrate doc Q2). issue_reconciler.py's gh()/gh_json() duplicates review_feedback_loop.py's _run()/_graphql() (same run-capture-raise pattern). Extract into the shared lib — concrete first member of the redesign's lib, but landable independently.

  5. Make reconciler issue-identity marker-based (reporting-substrate doc Q1). issue_reconciler.find_open_issue_number matches an exact title string with --limit 20; a manual rename or >20 matching issues orphans the report and spawns a duplicate. Look the persistent issue up by a stable <!-- reconciler-id:… --> marker instead. Optionally add close-hysteresis (flapping findings currently close + recreate).

Note

Item 4 overlaps the redesign's shared-lib, and pr_lifecycle.py's lifecycle/* ownership is tracked there (redesign Q4), not here — these two are the only seams that touch the engine track. Everything else is independent.

Done when

Each item is either landed or explicitly declined with a recorded reason. None of these should require touching the Cluster A engine's core control flow.

Recorded from Map v1 (#586). Generated by Claude Code.

Activity

  1. loganfinney27 commented on Jun 24, 2026

    @loganfinney27
    MemberAuthor

    Orphan-accounting (item 2): the root _-prefixed helper-script variants

    Grounded pass on a cluster surfaced while reviewing #597's CI (a Sourcery scan flagged them). Recording per this issue's rule — identify the caller before any cleanup; a caller is the line between infrastructure and dead code. No deletion proposed yet — accounting only.

    What they actually are (read, not pattern-matched)

    Real programs at repo root, each a variant of a canonical .github/scripts/ script:

    Root variant(s) Canonical sibling (live) Relationship
    _375main.py, _375pr.py .github/scripts/branch_garden_report.py (tested by tests/test_branch_garden_report.py) _375main diverges from canonical
    _pr128jsweep.py, _mainjsweep.py .github/scripts/janitor_sweep.py (called by .github/workflows/janitor-sweep.yml) _mainjsweep diverges from canonical
    _main-um.py, _pr94-um.py .github/scripts/update_manifest.py _main-um is byte-identical to canonical

    The main/pr#### pairing = side-by-side comparison copies keyed to PRs 375 / 128 / 94.

    Caller status

    • No code caller for any of the six (grep across *.py/*.yml/*.yaml/*.toml/*.sh/*.cfg → none).
    • Provenance: commit f911a5d5 "user root cache"; one is referenced in .codex-pr561-comments.json.
    • Not deletable-as-debris: doctrinal_flatten.py:33 treats _-prefixed names as a protected namespace (alongside ! and .). These live in a reserved class with deliberate flatten/cache semantics.

    Distinguish — these ARE live (exclude from any cleanup)

    __check_syntax__.py and run_checks.py are active helpers, exercised by tests/test_helper_scripts.py. Keep.

    Recommended disposition (for the refactor, not unilateral)

    The six numbered variants read as uncalled cached comparison snapshots of canonical .github/scripts/ programs. Candidates for removal once the flatten/cache lifecycle owner confirms they aren't retained-as-record or regenerated by the flatten system — the _-protected namespace means this is a flatten-system call, not ad-hoc cleanup. They also generate cross-PR Sourcery noise (false positives on safe list-form subprocess.run).

    Grounded accounting recorded by Claude Code; no files touched.


    Generated by Claude Code

  2. loganfinney27 commented on Jun 24, 2026

    @loganfinney27
    MemberAuthor

    Correction to the comment above — witnessing an error in my own accounting.

    I claimed the six root variants are in a "protected namespace" per doctrinal_flatten.py:33 and therefore carry "deliberate flatten/cache semantics." That is wrong. Reading the code properly:

    • is_protected_dir (L33) is consumed only by iter_top_level_dirs (L97), which filters path.is_dir(). It makes flatten skip _/!/.-prefixed top-level directories.
    • collect_candidates (L102) only descends into those top-level dirs via rglob. Root-level files like _375main.py are never iterated — the flatten system does not process them at all. They are out of scope, not protected.

    So the corrected accounting: the six numbered variants are plain uncalled root-level files — divergent-or-identical snapshots of canonical .github/scripts/ programs (_main-um.py byte-identical to update_manifest.py; _375main.py/_mainjsweep.py divergent), committed once as "user root cache," referenced by no code. There is no special flatten protection on them.

    That makes them more ordinary cleanup candidates than my first comment implied — but the caution still stands for non-namespace reasons: they were deliberately committed (likely PR-comparison snapshots), one is referenced in .codex-pr561-comments.json, and "no grep caller" isn't absolute proof of dead. Disposition remains a refactor/owner decision; no files touched. The everything-else in the prior comment (callers=none, canonical siblings, identical-vs-divergent) was verified and still holds.


    Generated by Claude Code

  3. loganfinney27 commented on Jun 29, 2026

    @loganfinney27
    MemberAuthor

    Item 3 disposition (bash/script domain-split dedup) — split into landed + declined:

    • wayback half: landed in Dedup wayback-preserve onto wayback_audit's URL primitives (#601 item 3) #693. wayback-preserve.yml reimplemented URL: extraction and Save Page Now submission as inline-bash heredocs that duplicated wayback_audit.py's extract_url / save_page_now. New wayback_preserve.py imports those primitives; the workflow keeps only git-diff plumbing in bash.
    • sync-dependencies half: declined, with reason. The item's premise doesn't hold against the code. sync-dependencies.yml runs uv lock --upgrade / uv export / gh pr create — a lock refresh + PR over vetted CLI tools. uv_dependency_submission.py reads uv.lock to build a dependency-graph snapshot for GitHub's Submission API — a separate concern with no shared Python half to reuse. It's right-sized glue, the same category this issue says to leave for the 7 inline-gh workflows. No change.

    Item 4 landed in #691. Item 2 (orphan audit) resolved earlier: all confirmed manual/local callers, none dead. Remaining open: item 1 (gate-framework parameterization), item 5 (reconciler marker-identity — held until #691 merges, to avoid stacking on issue_reconciler.py).

    Generated by Claude Code


    Generated by Claude Code

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

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions