lodestar-audit

You are running a lodestar audit. Discover and document violations as compact findings, then expand a chosen slice into single-concern action items. Do not fix them.

Each action-item file is a contract for lodestar-fix: evidence, files, requested change, decision (when needed), scope exceptions, and acceptance — without repeating generic executor boilerplate.

Scripts live beside this SKILL.md under scripts/. Run them with node scripts/<name>.mjs from this skill directory, or with an absolute path to that file.

How to talk to the user

Anything you print or ask is read by a person who is skimming. Findings and action-item files are exempt from the layout rules; their prose still follows plain-language rules.

• Ask one clear question at a time. Say what happens for each answer.
• Name a file by its path, not by an internal key.
• Give counts, not ratios; never ask the user to compare a number to a threshold.
• 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 — scope, output path, checks, mutation/commit policy (audit is read-only)
• Before long work — current category or phase
• At boundaries — completed categories/count and next step
• Closing — artifacts, skipped coverage, actionable failures

Structure model

This audit is structure-agnostic. It does not assume roles like core, api, or ui. It uses five things from .agents/lodestar/context.md:

1. ## Package Layout — package names, paths, aliases, a one-sentence

responsibility per package, and optional Scannable (yes / no; absent means yes). Rows marked no are not scanned.

1. Optional ## Dependency Policy — user-stated intended import order.

Absent means wrong-direction (#6) is gated; cycles still run.

1. ## Conventions — which style conventions the repo follows. Detectors

skip at a row's skip value (see the Categories table). A missing section means every default.

1. ## Review Rubric — repo-owned paths to read as extras on top of

the installed lodestar-setup/principles.md. Absent means principles only. Do not invent extra checklist items beyond that list.

1. ## Audit Configuration — optional category subset, output-root

(default docs/audit). Fallow is always required (omit fallow or set required; optional is rejected).

Detectors run against the selected file and category scope. Kind-of-code rules use the Responsibility column and path patterns, never the package name alone.

Two-phase structure

Phase 1 — DISCOVER     →  <output-root>/<RUN_ID>/findings.md
Phase 2 — PLAN         →  <output-root>/<RUN_ID>/INDEX.md + NNN-….md files

findings.md is the seam. Discover writes finding blocks only — limited to the scan scope. Plan expands a chosen slice of findings into action items. A human may edit findings.md between phases, including flipping in_scope. Both phases are restartable with the same <RUN_ID>. INDEX.md reports compact (not expanded) findings and states what was not scanned; it does not invent an exact whole-repo backlog for unscanned code. A later session promotes one category or package at a time without re-discovering completed scope.

Never overwrite a previous run. Output stays under <output-root>/<RUN_ID>/ (outputRoot from validate-input / resolve-run; default docs/audit).

Preconditions

If .agents/lodestar/context.md is missing, stop and tell the user to run lodestar-setup. That file is the only repo context this skill reads; do not fall back to AGENTS.md even if it happens to hold a layout table from an older setup.

Then run:

node scripts/audit-state.mjs validate-input --root <repo>

If that command exits non-zero, print its error and stop. It rejects a missing Package Layout, placeholder Responsibilities (shorter than 20 characters, TODO/TBD/???/one sentence, or a bare noun like core), a Scannable: yes row with zero TypeScript or JavaScript files, an unparseable ## Conventions value, an unparseable ## Audit Configuration value, and fallow: optional.

Then, unless the user is resuming an existing run, run:

node scripts/audit-state.mjs check-freshness --root <repo>

Exit 0: continue. Exit 2: print the stderr list and ask once:

The repo has changed since setup ran, so what I know about it is out of date: [list, in plain words]. I can audit anyway — findings may be off where the notes are wrong — or stop so you can re-run lodestar-setup first. (carry on / stop)

On stop, create no run directory. Do not run lodestar-setup inline. On proceed, pass the stdout JSON to resolve-run as --drift. A resumed run does not re-run check-freshness; it inherits the drift key recorded at creation.

A package marked Scannable: no is excluded from allPkgRoots and from every detector. How that appears in INDEX.md is owned by references/plan.md.

pkgManagerProvenance is lockfile, context.md, or none. Setup always resolves and records the package manager; pkgManagerProvenance: none is a warning that setup predates this requirement — re-run setup rather than asking mid-audit. If <lint> is n/a or probePlan is none, skip linter probes and use grep heuristics — do not error. Otherwise use validate-input probePlan as the linter probe command (see references/linter-probe.md).

Read .agents/lodestar/context.md for commands, optional Dependency Policy, conventions, and the layout table. Read every path under ## Review Rubric when that section is present — extras on top of the installed setup skill's principles.md. Absent means principles only (resolve principles.md beside the installed lodestar-setup SKILL.md). Do not bake in repo-specific checklist items beyond those paths.

Validate Fallow once at startup (fallow-contract resolve-bin). Missing or invalid Fallow is a hard stop with the install / setup remedy — never degrade to grep-only audit.

Categories

Read the category sub-doc before scanning that category. Read categories/fallow-seed.md once before Discover. A category doc names sibling categories in prose; it does not load them, and it does not load references/.

Known blind spots for INDEX.md: copy blindSpots from validate-input output, then append runtime entries as described in references/plan.md.

Consent and phase selection

Load references/resume.md before resolving or creating a run. Load references/discover.md before any detector. Load references/plan.md before writing action items. Load references/output-contracts.md before writing or merging findings.md.

1. Run node scripts/audit-state.mjs resolve-run --root <repo>

(add --drift '<json>' when Preconditions chose proceed). Capture outputRoot and path from the JSON.

1. If inProgress is non-empty (any date — not only today), ask: "There's

an unfinished audit from <run-id>. Pick up where it left off, or start over? (pick up / start over)". Resume with resolve-run --root <repo> --resume <RUN_ID>. Today’s date is used only when creating a new run ID. If inProgress is empty, look at the latest run directory under outputRoot (not only today's date). When INDEX.md exists and findings.md has any in_scope: false (or ## Backlog total > 0), offer: "The last audit left <N> findings without fix instructions. Want me to write those up now, instead of scanning again? (write them up / scan again)". On the first: --resume that id, skip Discover, flip in_scope: true on the chosen slice (one category, one package, or all), re-run Plan only. Do not re-merge. Do not ask the Discover consent questions.

1. Print: "I'll put the results in <output-root>/<RUN_ID>/."
2. List the categories in plain words, not as bare keys — e.g. "imports

(how files depend on each other)", "errors (how failures are handled)". If validate-input's categories is a subset of the nine, present that subset as the default: "Setup says to check these: <list>. Go ahead? (yes / choose different ones / check everything)". The user can widen this run without editing context.md. If categories is all nine, ask: "I'll check all nine areas. Go ahead? (yes / choose a smaller set)". Wait. After they pick a subset (this run, or confirming a stored subset), ask once: "Should future audits default to this same set? (yes / no — either way, this run uses it)". On yes, replace the categories row; do not change output-root. Do not ask when they chose all nine, or when the stored subset already matches. This edits context.md, not application source.

1. If validate-input scope.mode is changed-since, say in plain words

that setup limited this audit to code changed since <date>, and that the rest of the repo will not be scanned (no exact backlog count for unscanned paths). Then offer, for this run only (do not write the answer to context.md): keep that file scope / widen to all files / widen to one package's files. Widening starts Discover only for newly selected files and merges into this run — it does not rescan completed scope. Say that widening here changes this run only, not the setting.

1. After Discover, ask which slice needs fix instructions: recommended

low-risk items in the current scan scope / one category / one package / all / stop. Expand only that slice; preserve the rest as compact findings. If they stop, the run stays resumable.

Skip steps 4–6 and Discover when step 2 chose promote.

Do not scan before those confirmations.

Discover (Phase 1)

Follow references/discover.md for package set, file/category scope, Fallow seed, passes, merge, validate, and checkpoints. Discovery never modifies application source — allowed writes are under Rules.

Plan (Phase 2)

Follow references/plan.md for recover, expansion slice, grouping, numbering, action items, INDEX (incl. blind spots), and category order.

Rules

• Read-only. Never modify application source. Writes: <output-root>/,

an optional consented ## Audit Configuration edit, the transient .audit-fallow-seed.json, plus .agents/lodestar/fallow-compat.json when a newer Fallow schema is accepted.

• Consent first. Category subset, file-scope widen, and Plan expansion

slice are questions. Wait for answers.

• Stop conditions: missing setup files; validate-input failure

(including a Scannable: yes package with zero scannable files, or fallow: optional); freshness drift when the user chooses stop; Fallow missing or invalid; required commands missing; the user says stop.

• Scoped work. Detectors honor the scan file list and category set.

Work scales with selection.

• In-scope only. Write an action item only for in_scope: true.

Compact findings are reported in INDEX.md Backlog, never silently dropped.

• One concern per action item. Split "and also…". Multi-stage redesign

→ lodestar-plan.

• Lean contracts. No "see the audit skill", no ready-made executor

prompts, no copied category Scope rules blocks in generated files.

• No placeholder leaks. Treat any <typecheck>-style leftover as a

bug; validate-output must pass.

• `requires_decision: true` is the default for semantic findings.
• Don't fix. Don't propose layout changes; mention

lodestar-architecture in notes: if needed.

• No mechanical sub-agent fan-out. Deterministic recipes run in the

orchestrator; bounded judgment sub-agents only for semantic candidates.

• Restartable. Interrupted runs resume from checkpoints. Past run

epochs are never replaced. Promoting a backlog slice may append NNN-*.md files and rewrite INDEX.md in that same run. Widening discovery merges without rescanning completed scope.

Re-running

Load references/resume.md. Invoke again; resume from the last checkpoint. To re-run Plan from scratch after editing findings.md, delete NNN-….md plus INDEX.md first. To promote a backlog slice, keep those files: skip Discover, flip in_scope on the slice, re-run Plan so new files append and INDEX.md is rewritten. To widen scan scope, Discover only the newly selected files or categories and merge.