codex-controller-loop/.agent/controllers/keystone-seam-audit/plan.toon

version: 1
goal_summary: "Audit the repository for oversized hand-maintained source files, prioritize safe high-value refactor targets, split them into smaller cohesive modules, and finish with passing validation and a clean diff."
steps[6]:
  - id: s1
    title: Establish Safe Refactor Scope
    purpose: "Load controller inputs and repository constraints, confirm the working tree state, and define the exact file-selection rules so execution can proceed without ambiguity."
    inputs[4]: ".agent/controllers/keystone-seam-audit/goal.md",".agent/controllers/keystone-seam-audit/standards.md",repository working tree,"repo-level instructions such as AGENTS.md if present"
    outputs[3]: confirmed execution constraints,candidate exclusion rules,list of locally modified files to avoid or handle carefully
    dependencies[0]:
    verification[2]:
      - label: Check working tree state
        commands[1]: "git status --short"
      - label: Locate repo instructions
        commands[1]: "rg --files -g 'AGENTS.md' -g '.agent/**'"
    cleanup_requirements[1]{label,description}:
      No accidental overlap with user edits,Do not modify files with unrelated local changes unless the change is required and the existing edits are understood and preserved.
    status: active
    attempts: 1
  - id: s2
    title: "Inventory Large Hand-Maintained Files"
    purpose: "Produce a ranked inventory of oversized source files while excluding generated and third-party material."
    inputs[2]: repository file list,selection thresholds from goal and standards
    outputs[3]: ranked candidate list with line counts,"excluded-path list",initial top refactor targets
    dependencies[1]: s1
    verification[2]:
      - label: Enumerate tracked files
        commands[1]: "rg --files"
      - label: Rank large files by line count
        commands[1]: "python - <<'PY'\nimport os, subprocess\nexclude = {'node_modules','dist','build','coverage','.git','.next','.svelte-kit','target','vendor'}\nfiles = subprocess.check_output(['rg','--files']).decode().splitlines()\nrows = []\nfor f in files:\n    parts = set(f.split('/'))\n    if parts & exclude:\n        continue\n    if os.path.splitext(f)[1] in {'.png','.jpg','.jpeg','.gif','.svg','.lock','.snap','.min.js','.map'}:\n        continue\n    try:\n        with open(f,'r',encoding='utf-8') as fh:\n            n = sum(1 for _ in fh)\n    except Exception:\n        continue\n    if n > 300:\n        rows.append((n,f))\nfor n,f in sorted(rows, reverse=True)[:50]:\n    print(f'{n}\\t{f}')\nPY"
    cleanup_requirements[1]{label,description}:
      Discard false positives,"Remove generated files, migration dumps, fixtures, and machine-authored artifacts from the candidate list before choosing targets."
    status: todo
    attempts: 0
  - id: s3
    title: Choose Refactor Order And Boundaries
    purpose: "Inspect the largest candidates, decide which files are safe and high-value to split first, and define intended module boundaries before editing."
    inputs[3]: ranked candidate list,current file contents,existing module structure
    outputs[3]: ordered target list,boundary notes for each target,"explicit non-goals for each refactor"
    dependencies[1]: s2
    verification[2]:
      - label: Inspect top candidates
        commands[2]: "sed -n '1,220p' <top-candidate-file>","sed -n '221,440p' <top-candidate-file>"
      - label: Map exports and dependents
        commands[1]: "rg -n \"from ['\\\"]|require\\(\" <candidate-basename-or-symbols>"
    cleanup_requirements[1]{label,description}:
      "Avoid cosmetic-only churn","Do not split files purely by line count; only proceed when coherent seams such as utilities, domain logic, adapters, routes, or components are identifiable."
    status: todo
    attempts: 0
  - id: s4
    title: Refactor First Target Incrementally
    purpose: "Split the highest-priority candidate into smaller cohesive files while preserving behavior and keeping the change reviewable."
    inputs[3]: first target file,boundary notes,repo conventions
    outputs[3]: new smaller modules,updated imports/exports,"target-specific validation result"
    dependencies[1]: s3
    verification[2]:
      - label: Run targeted tests or checks
        commands[1]: "<smallest-relevant-test-or-lint-command>"
      - label: Confirm file size reduction
        commands[1]: "wc -l <affected-files>"
    cleanup_requirements[1]{label,description}:
      Remove temporary seams,"Delete transitional helpers, dead exports, and unused imports created during the split before moving on."
    status: todo
    attempts: 0
  - id: s5
    title: "Repeat For Remaining High-Value Targets"
    purpose: "Continue the same refactor pattern for additional oversized files until the main high-value targets are addressed or diminishing returns are reached."
    inputs[2]: remaining ordered targets,lessons from first refactor
    outputs[3]: additional split modules,updated dependency wiring,"per-target validation notes"
    dependencies[1]: s4
    verification[2]:
      - label: "Run per-target validation after each split"
        commands[1]: "<smallest-relevant-test-or-lint-command>"
      - label: Track remaining oversized files
        commands[1]: "python - <<'PY'\nimport os, subprocess\nexclude = {'node_modules','dist','build','coverage','.git','.next','.svelte-kit','target','vendor'}\nfiles = subprocess.check_output(['rg','--files']).decode().splitlines()\nfor f in files:\n    parts = set(f.split('/'))\n    if parts & exclude:\n        continue\n    try:\n        with open(f,'r',encoding='utf-8') as fh:\n            n = sum(1 for _ in fh)\n    except Exception:\n        continue\n    if n > 300:\n        print(f'{n}\\t{f}')\nPY"
    cleanup_requirements[1]{label,description}:
      Stop at sensible boundary,"Do not keep splitting once modules are cohesive and maintainable; leave well-structured files intact even if they remain moderately large."
    status: todo
    attempts: 0
  - id: s6
    title: Run Full Validation And Final Cleanup
    purpose: "Verify repository health, remove leftover refactor debris, and produce a concise execution summary for the controller result."
    inputs[2]: all refactor changes,repository validation commands
    outputs[3]: final passing validation results,cleaned diff,"summary of targets, seams, and tests"
    dependencies[1]: s5
    verification[2]:
      - label: Run broadest available validation
        commands[3]: "<repo-test-command>","<repo-lint-command-if-available>","<repo-build-or-typecheck-command-if-available>"
      - label: Check for leftover issues
        commands[2]: "git diff --check","git status --short"
    cleanup_requirements[2]{label,description}:
      Leave clean refactor artifacts,"Remove unused files, stale exports, dead code, and temporary comments; ensure only intentional source changes remain."
      Record outcome,"Summarize which files were split, the new module boundaries, any tests added or updated, and any remaining large files intentionally left unchanged."
    status: todo
    attempts: 0