lodestar-fix

You are running lodestar-fix. The job is to triage and execute the action items produced by a lodestar-audit run, marking each with a status so re-runs pick up where you left off. This skill modifies application source code.

Scripts live beside this SKILL.md under scripts/. Keep the process cwd as the target repository. Invoke scripts with an absolute path to that file (or node <skill-dir>/scripts/<name>.mjs). --file and --run-dir are paths in the target repository. Use them for status writes and file moves instead of POSIX mv.

How to talk to the user

Anything you print or ask is read by a person who is skimming. The Step 4 report and commit messages keep their given shape.

• Ask one clear question at a time. Say what happens for each answer.
• Describe a fix by what it changes, not by its category key or item id.
• Keep status values out of questions — say "left for later", not "deferred".
• Never trim or postpone a warning.
• Point first. Bullets, not paragraphs. Blank line between blocks.
• Bold the first few words of each bullet.

Milestones

Concise chat progress — not diagnostic logs or run files:

• Opening — selected items, output path, checks, mutation/commit policy
• Before long work — current item
• At boundaries — done/skipped/deferred counts and next item
• Closing — artifacts, skipped coverage, actionable failures

Inputs

The skill operates on one <output-root>/<RUN_ID>/ directory at a time (outputRoot from node <lodestar-audit-skill>/scripts/audit-state.mjs validate-input --root <repo>, default docs/audit). Substitute that value for the output directory — do not hardcode docs/audit. Required contents:

• INDEX.md (written by lodestar-audit's Plan phase).
• One or more NNN-<category>-<slug>.md action items.

If any are missing, stop and ask the user to run lodestar-audit first.

Capture from the same validate-input payload:

• outputRoot — where audit runs land.
• git — commit policy. Every key is populated; a missing git row in

## Audit Configuration yields today's defaults (commits: ask, subject <category>: <slug>, trailer Closes <item>., no protected branches, require-clean: no).

Capture from .agents/lodestar/context.md (the file lodestar-setup writes; AGENTS.md is not read):

• <typecheck>, <lint>, <test> — context build commands. n/a

skips that command when an item's acceptance names it. The item's Acceptance check is the contract; stop only when that section names no usable method.

• ## Package Layout — the Package and Path glob(s) columns, read only

when Step 2's "By area" option is chosen. A missing table does not stop the skill.

Then run command-only freshness (layout facts are not this skill's):

node <lodestar-audit-skill>/scripts/audit-state.mjs check-freshness --root <repo> --facts commands

Exit 2: stop. Name the stale command and point at lodestar-setup. n/a is not drift. Do not run a layout check.

Step 1 — Pick a run

Git preconditions (before applying anything):

1. If git.requireClean is yes, run git status --porcelain. A

dirty tree → stop. Name the dirty files. Do not pick a run.

1. If the current branch (git branch --show-current) is in

git.protected and git.commits is not never, stop and offer to continue this session without committing. On yes, set sessionCommits = never for the rest of the session — do not write context.md. On no, stop entirely. Otherwise sessionCommits = git.commits.

Then:

1. List <output-root>/*/ directories that contain both INDEX.md and

at least one NNN-<category>-<slug>.md file in the run root (not under done/). Exclude <output-root>/done/ itself. Never offer a run that lacks INDEX.md.

1. An "unfinished" run is one where the run root (not the done/

subfolder) still holds at least one action-item file. If exactly one run is unfinished, default to that. Otherwise list the unfinished runs and ask which one. If no candidate run qualifies, say so and point the user at lodestar-audit's Plan phase.

1. Print: "Working through the fixes in <output-root>/<RUN_ID>/."

Steps

References load one hop from this file; a reference must not load another.

If the run root has in_progress or deferred, load references/resume.md first.

1. Triage — references/triage.md. Choose the

batch and set AUTO_COMMIT.

1. Execute — references/execute.md. One item

at a time, serially. No mutating sub-agent fan-out.

1. Report — references/report.md. Session

summary, archive run (Step 4a); do not refresh Dependency Policy (Step 4b).

Resuming a previous run: references/resume.md.

Rules

• Read each item before acting. The action item is the contract —

evidence, files, requested change, decision, scope exceptions, and acceptance. Do not load whole category documents; the item must stand alone with these resident rules.

• Resident safety (always). Apply unless the item's **Scope

exceptions or Acceptance check** override them:

• Edit only paths in files: (plus paths named in Scope exceptions).
• Do not rewrite unrelated dirty hunks; stop on dirty listed files.
• Never git add -A; stage only the item's files.
• Honor stop conditions in Scope exceptions; hitting one → deferred.
• Run the item's Acceptance check; when it names <typecheck> /

<lint> / <test>, use context commands (n/a skips that cell).

• One concern per item — do not expand into multi-stage redesign

(lodestar-plan).

• Scope exceptions are stop conditions. Hitting one → status: deferred,

never "ignore and proceed".

• `requires_decision: true` always asks. Even under a bulk pick. Use

the item's Decision section when present.

• Never modify the body of an action-item file. Only frontmatter

gains status:, completed_at:, commit:, note:. Problem / fix / scope / acceptance stay immutable.

• Never delete an action-item file. done/skipped move to

<output-root>/<RUN_ID>/done/; deferred stay in the run root.

• No `git add -A`. Stage only the item's files:. Never stage a

whole dirty file that already had unrelated edits.

• Never rewrite Dependency Policy from observation. Step 4b does not

refresh context.md from the live import graph after cycle fixes.

• Stop conditions:
• No INDEX.md or no action-item files in the run directory.
• The item's acceptance method is empty or unusable (no command and no

deterministic inspection named in the item).

• check-freshness --facts commands reports drift → point at

lodestar-setup.

• The user says stop.
• A files: path already has unrelated uncommitted changes the user

has not resolved.