maintainable-update

# Maintainable update You are the orchestrator. **You do not edit source yourself.** You measure the repository, launch the engine once, and report what it did. `SKILL_DIR` is the directory that contains this `SKILL.md`. | File | Path | | --- | --- | | Operations catalogue | `SKILL_DIR/references/operations.md` | | Clarity bar | `SKILL_DIR/references/clarity-bar.md` | | Copy bar | `SKILL_DIR/references/copy-bar.md` | | Roles | `SKILL_DIR/references/roles.md` | | Safety rules | `SKILL_DIR/references/safety.md` | | Discover | `SKILL_DIR/scripts/discover-shards.py` | | Inertness proof | `SKILL_DIR/scripts/verify-inert.py` | | Engine (Claude Code) | `SKILL_DIR/workflows/maintainable-update.js` | Read `operations.md` once so you can brief the user. Do not start reformatting anything in the parent session. ## The seven operations | Op | What it changes | Semantics | | --- | --- | --- | | `copy` | User-facing strings | Wording only | | `clarity` | Concepts: dead state, duplicate derivations, one-caller wrappers, redundant error cases | Behaviour-preserving by construction, reviewed | | `wrap` | One parameter per line in multi-line declarations and calls | Inert — proven | | `width` | Lines over the column limit broken at semantic groups | Inert — proven | | `split` | Oversized files split into focused files / extensions | Inert — proven | | `rename` | Each file named after the code it owns | `git mv` only | | `tidy` | Folders grouped by ownership | `git mv` only | Default set: `clarity,wrap,width,split,rename,tidy`. `copy` is opt-in — add it explicitly, or pass `all`. ## Arguments Parse `$ARGUMENTS`: - `--ops a,b,c` → the operations to run (aliases: `all`, `shape` = `wrap,width,split`, `identity` = `rename,tidy`) - `--column-limit N` → soft column limit for `width` (default 120) - `--split-threshold N` → line count above which `split` considers a file (default 600) - `--max-shards N` → cap parallel shards (default 12) - `--include-tests` → let the sweep touch test sources too. By default `clarity`, `copy`, `split`, `rename` and `tidy` skip them; `wrap` and `width` still apply, because a crammed signature is just as unreadable in a test. - `--languages a,b` → restrict to these languages - `--no-commit` / `--no-push` → stop before committing / before pushing - `--no-checkpoint` → one commit at the end instead of one per stage (not recommended) - Any other token is a filesystem root or an op alias, passed through to `discover-shards.py`. - Empty → discover from the current working directory with the default op set. Defaults: `commit: true`, `push: true`, `checkpoint: true`. **Never pick the column limit silently.** 80 is too low for Swift, Kotlin and TypeScript and produces a worse diff than it fixes. If the user did not name a limit and the repo has no formatter config that names one, say which limit you are using and why in the same line you brief them. ## Step 1 — Measure ```bash python3 "<SKILL_DIR>/scripts/discover-shards.py" --cwd "<PWD>" \ --ops <ops> --column-limit <N> --split-threshold <N> <roots...> ``` The script prints JSON: `workspace`, `roots`, `ops`, `languages` (counts), `language_filter` (the `--languages` restriction, empty if none), `shards` (each with `paths` and `exclude`, disjoint by construction), `work` (one list per op), `formatters`, `git_roots`, `checks`, `counts`. Pass the JSON through to the engine unchanged so remeasure keeps the same filter. It works on any layout — a single Xcode app, an npm package, a Cargo workspace, a Go module, a Django site, an Android or Flutter app, a monorepo of several — because it classifies by suffix and well-known directory names, and picks a cheap check per git root (`make check`, `swift build`, the `typecheck`/`lint` npm script, `cargo check`, `go build`, …). If every `work` list is empty, stop and say the repository already meets the bar. Do not launch agents. **If the script reports a formatter for a root, say so.** A repository whose mechanical style is already owned by `gofmt`, `rustfmt`, `swift-format`, `clang-format`, `prettier`, `black` or `dart format` does not need agents for `wrap` and `width` — running the formatter is the whole fix, it is faster, and it cannot introduce a semantic change. The engine runs the formatter first and only sends agents at what the formatter leaves alone. Never introduce a formatter to a repository that does not already have one. Tell the user in one line: how many shards, the op set, the column limit, the split threshold, which formatters were found, and which checks will run. Stay inside the git repos the script named. ## Step 2 — Launch the engine once Build `args` = the discover JSON plus: ```json { "skill_dir": "<SKILL_DIR>", "operations_path": "<SKILL_DIR>/references/operations.md", "clarity_bar_path": "<SKILL_DIR>/references/clarity-bar.md", "copy_bar_path": "<SKILL_DIR>/references/copy-bar.md", "roles_path": "<SKILL_DIR>/references/roles.md", "safety_path": "<SKILL_DIR>/references/safety.md", "discover_script": "<SKILL_DIR>/scripts/discover-shards.py", "inert_script": "<SKILL_DIR>/scripts/verify-inert.py", "commit": true, "push": true, "checkpoint": true, "commit_trailers": "<any trailer lines your host requires, else omit>" } ``` **Claude Code** — call the `Workflow` tool once with `scriptPath: "<SKILL_DIR>/workflows/maintainable-update.js"` and the `args` above. The user invoking this skill is the opt-in the tool requires. Set `read_only_agent_type` in `args` if your session's read-only agent is not called `Explore`. **Any other host** — use the fallback below. After launching, stop spawning your own finders and fixers, and do not poll. Tell the user the workflow display name, that each stage commits with an explicit pathspec before the next one starts, and that nothing is force-pushed and nothing is staged with `git add -A`. ## The engine Four stages. Each stage measures, fans out over disjoint shards, proves what it changed, runs the repository's own checks, and commits before the next stage starts. **The measurement is repeated between stages, not reused** — `split` changes the file set, so a wrap plan computed before it is stale; `rename` changes every path, so it must come after everything that edits content. ``` Stage 1 CONTENT copy, clarity find → verify → fix → review⇄fix (max 3) → check → commit Stage 2 SHAPE split remeasure → split → prove inert → check → commit wrap, width remeasure → formatter → agents → prove inert → check → commit Stage 3 IDENTITY rename, tidy remeasure → plan (parallel) → apply (serial, git mv) → check → commit Stage 4 SHIP final check, push ``` Within a stage, every shard runs its own chain concurrently; fixers never edit outside their shard or inside its `exclude` list. Between stages there is a barrier, because the next stage's plan depends on the previous stage's output. `rename` and `tidy` apply serially through **one** agent, because `git mv` touches the index and two agents moving files at once produce a corrupted staging area. Their *planning* is parallel; only the application is serial. ## Fallback (only if no workflow engine is available, or it errors) Reproduce the same stages with subagents. Cold-start every child: it reads `operations.md`, the bar for its op, and the matching section of `roles.md` before touching anything, and every prompt carries the op, the shard's `paths` and its `exclude` list. 1. **Find** — one read-only subagent per shard per op. Empty findings only after grep. 2. **Verify** — one read-only subagent per shard that returned findings. Keep only items with quoted evidence. Drop out-of-shard paths. 3. **Fix** — one read-write subagent per shard with confirmed items. Confirmed items only, no drive-by cleanups. 4. **Prove** — for `wrap`, `width` and `split`, run `verify-inert.py` over the changed files. A file whose non-whitespace token stream changed is a bug: revert it and report. 5. **Review → fix loop** — one read-only reviewer per edited shard, max 3 rounds, stop when a round returns nothing new or repeats itself. 6. **Checkpoint** — run the `checks` for each changed git root, then `git commit -m "…" -- <paths>`. 7. Repeat 1–6 for the next stage after re-running `discover-shards.py`. 8. **Ship** — final check, push `HEAD` if `push` is true. Wait for each panel to finish before starting the next. Do not repair unrelated breakage. Do not touch dirty files this run did not create. ## Hard rules - **Behaviour is not part of the deliverable.** Every op except `copy` and `clarity` must leave observable behaviour byte-identical, and `wrap`, `width` and `split` must leave the token stream identical — proven, not asserted. - **Never rename a wire value to match a Swift symbol.** Serialized names, `UserDefaults` keys, `Codable` `CodingKeys`, enum raw values, database columns, JSON fields, environment variables, xattr and pasteboard type names, localization keys, and on-disk file names are contracts. `rename` moves *files*, never these. - **Shards are disjoint.** Two agents never hold the same file. The script emits `exclude` lists for exactly this reason; honour them. - **Pathspec commits.** `git commit -m "…" -- <paths>` only. Never `git add -A`, `git add .`, `git add -u`, `git commit -a`. Another session may be editing this tree; its dirty files stay dirty. - **One repo at a time at git time.** The script already split by `git_roots`. - **Give every parallel builder its own build directory.** Shared build output across concurrent workers hands out false greens and false reds. - **No silent caps.** If a list was truncated, or a file was skipped, say which and why. A quiet skip reads as "covered everything". - **A check that cannot fail is not a check.** Before trusting a new gate, run it against the pre-fix tree and confirm it fails there.