Mnemonica: audit-full

Reconcile every file in knowledge/ against the actual current state of the whole codebase — the same engine setup uses to populate knowledge/ from nothing, run here either standalone or to correct drift in an already-populated project. Read ${CLAUDE_PLUGIN_ROOT}/references/knowledge-conventions.md first; every rule below refers back to it. This skill is always invoked directly by the user (or by setup on its behalf) — never by a hook, and never automatically on commit or push.

If the user's invocation includes extra wording beyond the trigger phrase (for example, "also cross-check with graphify" or "focus on the payments module"), treat it as scoping or preference for this run. It cannot skip Step 1's pre-flight question when the project actually is large or odd enough to trigger it, and it cannot skip Step 6's confirmation before merging, splitting, renaming, or deleting an existing module file — those rules exist precisely so a casual instruction in passing can't quietly bypass them.

Step 1: Pre-flight size and anomaly check

Run ${CLAUDE_PLUGIN_ROOT}/skills/audit-full/scripts/list-tracked-files.sh <project-root> --summary. Read the TOTAL line and every DIR line's flags.

Decide whether to stop and ask — trigger the question below if either is true: any DIR line carries a FLAG:LARGE or FLAG:ODD marker, or TOTAL is 500 or more even with no individual directory flagged (many medium directories can add up to an expensive scan just as easily as one huge one). Otherwise skip straight to Step 2 without asking anything — this gate must stay invisible on the ordinary small-to-medium project it is not needed for.

When triggered, stop before reading any file content and ask the user directly, stating the concrete numbers and which directories were flagged and why (large, or odd because of a vendor-looking name or a generated-looking file extension — never just "this seems big"). Offer exactly three choices, and act only on an explicit answer:

1. Proceed anyway — run the full scan as-is, no changes to scope or ignore rules.
2. Scope this run to specific paths — using the summary to suggest which directories look like real systems worth reading, restrict every remaining step in this run to the paths the user confirms. Do not silently widen back out to the full tree partway through.
3. Permanently exclude specific directories from future scans — write the agreed patterns to knowledge/.mnemonica-ignore (one per line, create the file and knowledge/ if neither exists yet; append rather than overwrite if the file already has entries), then continue — list-tracked-files.sh picks the new exclusions up automatically on its next call, so Step 2 does not need to be told about them separately.

Mention in the Step 8 report whichever choice was made and why, even when it was "proceed anyway" — the point is that a decision was made visibly, not that a particular one is expected.

Step 2: Inventory the codebase

Run ${CLAUDE_PLUGIN_ROOT}/skills/audit-full/scripts/list-tracked-files.sh <project-root> (without --summary, and with a path argument instead of <project-root> if Step 1's answer was to scope this run) to get the actual file list this scan works from. It excludes knowledge/ and .claude/ (Mnemonica's own output, never itself a "system" to document) and respects knowledge/.mnemonica-ignore. It uses git when available (.gitignore respected automatically) or falls back to a plain directory scan with conservative excludes (node_modules, dist, build, .venv, etc.) when the project has no git repository — audit-full works either way, unlike audit-light, which requires git outright.

Step 3: Check index integrity

Run ${CLAUDE_PLUGIN_ROOT}/scripts/check-index-integrity.sh <project-root>. If it reports missing module files, that is not a separate problem to solve first — fold it directly into Step 5: a module whose file is listed in the index but absent from disk is reconciled the same way as a module that was never created, by writing it fresh from the current code, and its disappearance is worth a one-line mention in the final report so the user knows it was regenerated rather than assuming nothing was wrong.

Step 4: Identify systems

Group the codebase into architecturally independent systems using the independence test from knowledge-conventions.md. For a bootstrap run, this means deciding the module boundaries from scratch. For a project with an existing index, treat each indexed module as a working hypothesis to verify, not a fixed fact — code may have grown past what its current owned-path globs cover, or two once-separate concerns may have merged.

Do not over-fragment: apply the same default bias as everywhere else in Mnemonica — when torn, merge into an existing or broader module rather than minting a narrow one.

If an indexed module's system has been entirely removed from the codebase — nothing left anywhere that the module's content actually describes, not just partially stale — do not just empty the file out or leave it as near-blank dead weight. This is a deletion candidate: carry it to Step 6 instead of silently thinning it into an orphaned file that will sit there indefinitely.

Step 5: Reconcile each module

For each identified system:

• No module file exists yet (including one flagged missing by Step 3): create knowledge/<SYSTEM_NAME>.md (naming convention in knowledge-conventions.md) describing it from the current code — architecture, key decisions, constraints, anything a session with no prior context would need.
• A module file already exists: read it against the current code. Correct anything stale, remove anything describing code that no longer exists, add anything real that is undocumented. Do not rewrite sections that are still accurate just for style.

For each module, write or update its one line in the CLAUDE.md index (path, owned-path globs, one-line description) inside the MNEMONICA:BEGIN/END block. Keep the globs honest — they are what audit-light relies on to route future changes correctly.

Step 6: Restructuring is the one case that needs permission

If reconciliation reveals that an existing module file should be merged with another, split into several, renamed, or deleted (including the "system entirely removed" case flagged in Step 4) — per knowledge-conventions.md, this is the one category of action that requires asking the user first. Describe the specific restructuring and why, wait for explicit confirmation in the conversation, and only then perform it. Creating new module files and editing content, including in the same run, still needs no permission — only changes to files that already existed before this run count as restructuring. Declining a proposed restructuring does not undo or block the rest of the run: everything already reconciled in Step 5 stands regardless of the answer here.

Step 7: Update the checkpoint

Run ${CLAUDE_PLUGIN_ROOT}/scripts/write-checkpoint.sh <project-root> full.

• If the project has no git repository, this exits NO_GIT_REPO — expected when Step 2 used the non-git fallback. Say so in the report; there is simply no checkpoint to set yet.
• If the git repository has zero commits, this exits NO_COMMITS — the reconciliation in Step 5 still happened and stands, there is just no commit to baseline against yet. Say so in the report and mention that the first commit will make a checkpoint possible.
• Otherwise this lets a later audit-light run start from a clean baseline.

Step 8: Report

Summarize what happened: the Step 1 pre-flight decision (if it was triggered) and any .mnemonica-ignore changes, modules created, modules corrected (and roughly what was wrong), modules recreated because their file had gone missing, any restructuring (including deletion) proposed or performed, and whether a checkpoint was actually written or why not. If this run found nothing wrong, say so — do not manufacture busywork to look useful.