Os Optimizer

Vault Optimizer

Apply 10 frameworks to every markdown file in the vault. For each framework, read its pass-implementation file, run every check, log findings, walk the user through fixes per item, apply (or save to a plan). Save one comprehensive HTML report grouped by framework. Do not inline the HTML in chat — only the saved path and a one-paragraph summary.

Operating philosophy — read carefully, this is what makes this skill different

1. Every finding ships a concrete fix. No flag-only. No "warn and forget." No manual-review pile. When the user runs apply-mode, every finding becomes either an applied edit, a saved migration step in a dated reorg plan, or (only if the user explicitly declines this finding in walk) a recorded decline. Nothing lingers as an open warning across runs.
2. Severity is informational, not gating. fail / warn / info describes how load-bearing the issue is; it does not gate whether a fix is offered. Every check produces fixes.
3. Walk per item, user picks the target. Bulk-apply is reserved for purely mechanical fixes (em dashes, duplicate H1). Anything semantic — wikilink repointing, merges, routing rewrites, Plot.md generation, reorganizations — is walk-only with the user confirming the destination/winner/wording per item.
4. Two modes for every fix: apply now (executes in this run) or save to plan (writes the change as a checklist step into the plan file, whose path is resolved from the role registry in Step 4.3). User picks per finding for high-blast-radius items. Smaller fixes default to apply-now.
5. Visible progress, never silent. Step 0.5 creates one TaskCreate entry per stage and per framework; tasks update in_progress → completed as the run unfolds. The user watches the audit walk through the vault rather than waiting for one big report at the end.
6. Read and reason, don't just match. Every framework's triggers surface candidates; every finding requires the agent to read context, judge alignment with the user's stated world, and produce reasoning specific to the case. No paraphrased rule restatements as "reasoning."
7. Discover structure, never assume folder names. Vaults vary. One user's curated layer is Context/; another's is About/, Me/, frontmatter on root, or scattered across topic folders. The optimizer runs Step 1.5 (role discovery) before any framework, and every framework references roles (context-equivalent, decisions-equivalent, daily-equivalent, folder-index convention…) discovered from content — never hardcoded names. If a role is missing, it surfaces as a finding with a proposed fix ("you have no decisions-equivalent folder; here's a recommendation"), not as a silent assumption. Static path references in pass files are always abstractions; the agent resolves them through the role registry at run time.

Frameworks

When running a check, read the pass-implementation file and follow its regex / heuristic / finding format exactly. Don't paraphrase. Cite the framework reference in every finding.

Flow

1. Verify the cwd looks like a vault — light check (Step 0)
2. Create the visible task list — TaskCreate one task per stage + framework (Step 0.5)
3. Discover & classify every .md file — only technical skips (Step 1)
4. Iterate frameworks F1 → F10, applying each framework's lens with agent judgment; F10 = rule quality on the instruction layer, F8 = cross-vault synthesis, F9 = whole-vault structural reasoning + discoverability walk (Step 2)
5. Aggregate findings + write the architectural read paragraph (Steps 3 and 3.5)
6. Walk every finding through apply-now / save-to-plan — no skip option for fixes; every finding becomes an applied edit, a saved migration step, or an explicit per-item user decline (Step 4)
7. Apply approved fixes (Step 5)
8. Render HTML dashboard, save, open in browser, emit as artifact (Step 6)

Step 0 — Verify the cwd looks like a vault

Don't require any specific folder layout. Check (any one is sufficient):

test -f CLAUDE.md || test -f claude.md
[ "$(find . -maxdepth 4 -name 'CLAUDE.md' | head -1)" ]
[ "$(find . -maxdepth 1 -name '*.md' | wc -l)" -gt 0 ]

If none are true → stop:

This doesn't look like a markdown vault — no .md files or CLAUDE.md found. cd into your vault root and re-run.

Otherwise tell the user one line:

Auditing your vault against 10 frameworks. First I'll discover your structure (Step 1.5) — I won't assume folder names. Then I walk every fix with you. You'll see each stage as a task.

Proceed into Step 0.5.

Step 0.5 — Create the visible task list (TaskCreate)

This is mandatory. People running this skill on their second brain need to see what's happening — silent is unacceptable for a long-running vault audit.

Create one task per stage + one task per framework, in order. Use TaskCreate with explicit short titles. The user watches them tick through.

[ ] Discover & classify .md files (Step 1)
[ ] Role discovery — semantic folder/file classification, no hardcoded names (Step 1.5)
[ ] F1 Anthropic CLAUDE.md — read CLAUDE.md files, judge candidates
[ ] F2 Karpathy Wiki — wikilinks, orphans, schema
[ ] F3 Caveman — compression of instruction-layer files
[ ] F4 Chroma Context Rot — length, distractors, position
[ ] F5 Anthropic Memory — file size, naming, indexes
[ ] F6 Progressive Disclosure — SKILL.md layering
[ ] G7 General Hygiene — em dashes, frontmatter, H1 rules
[ ] F10 Claude 5 Rules — retired, bare prohibitions, one-sided, aggressive
[ ] F8 Reflection — cluster + judge cross-file synthesis
[ ] F9 Architecture — routing truth, Plot.md presence, discoverability walk
[ ] Aggregate findings + architectural read (Steps 3 / 3.5)
[ ] Walk every finding through apply / save-to-plan (Step 4)
[ ] Apply approved fixes (Step 5)
[ ] Render dashboard + open (Step 6)

Mark in_progress when entering a stage; completed when leaving it. For long frameworks (F2, F8, F9) emit a sub-update mid-run via TaskUpdate or a single chat line so the user knows progress.

Skipping the task list to "save time" defeats the purpose of this skill. The visible task list is non-optional.

Step 1 — Discover & classify every .md file

1.1 — Universal glob (every file audited)

find . -name '*.md' \
  -not -path '*/.git/*' \
  -not -path '*/.obsidian/*' \
  -not -path '*/.trash/*' \
  -not -path '*/.claude/worktrees/*' \
  -not -path '*/node_modules/*' \
  -not -path '*/dist/*' \
  -not -path '*/build/*'

No role-based skips. No "templates skipped", no "Daily skipped", no "Onboarding skipped". Every .md outside the technical skip list above gets audited against every framework rule that applies to its role. Classification routes the right rules to the right files; classification does NOT exclude files.

1.2 — Classify each file by role (first match wins) — hints only

The patterns below are hints that bias the role registry built in Step 1.5. They're not authoritative — Step 1.5 reads sample content to confirm role assignments. A file matching \d{4}-\d{2}-\d{2}\.md outside any daily-shaped folder will not be classified daily if Step 1.5 finds no daily role; it'll be a regular note.

For backwards compatibility with vaults that do use the conventional names, the patterns still apply; for vaults that don't, Step 1.5 takes over.

Build the classification map:

{
  "root_claude": "./CLAUDE.md",
  "folder_claudes": [...],
  "claude_rules": [...],
  "skills": [...],
  "indexes": [...],
  "readmes": [...],
  "dailies": [...],
  "meetings": [...],
  "transcripts": [...],
  "decisions": [...],
  "templates": [...],
  "context_files": [...],
  "notes": [...],
  "by_folder": {...},
  "stats": {"total_files": N, "total_bytes": B, "folders": F}
}

1.3 — Build supporting indexes (used by F2/F4)

1.4 — Show classification summary in chat (one block, before any framework runs)

## 📋 Discovery — {N} markdown files across {F} folders, {B-formatted} total

| Role | Count |
|---|---:|
| Root CLAUDE.md | 1 |
| Folder CLAUDE.mds | {n} |
| Skills (SKILL.md) | {n} |
| .claude/rules | {n} |
| Indexes / READMEs | {n} |
| Context files | {n} |
| Notes | {n} |
| Dailies | {n} |
| Meetings | {n} |
| Transcripts | {n} |
| Decisions | {n} |
| Templates | {n} |

**Framework targets (every file in scope is audited):**
- F1 Anthropic CLAUDE.md → {n} CLAUDE.md files
- F2 Karpathy Wiki → {n} content notes (notes + context + decision + meeting + index + readme) + 1 schema doc check
- F3 Caveman → {n} instruction-layer files (CLAUDE.md + SKILL.md + .claude/rules + skill references)
- F4 Chroma Context Rot → {N} files (every `.md`)
- F5 Anthropic Memory → {N} files (every `.md`)
- F6 Progressive Disclosure → {n} skills
- G7 General Hygiene → {N} files
- F10 Claude 5 Rules → {n} instruction files (CLAUDE.md + .claude/rules + SKILL.md)
- F8 Reflection → {n} files in discovered curated-layer roles + {n} files in discovered session-layer roles ({window} window) for cross-vault synthesis
- F9 Architecture → routing table ({n} entries), {n} folders for index presence + freshness against the discovered convention, full navigation graph for discoverability, vault-specific orientation built from the discovered identity-layer

Running role discovery (Step 1.5) now…

Step 1.5 — Role discovery (semantic, not name-based)

This step replaces every hardcoded assumption about folder/file names. The pass files reference roles (context, projects, decisions, daily, meetings, transcripts, resources, skills, archive, identity, folder_index_convention). Step 1.5 discovers what folder/file in this vault plays each role — or records that the role is absent.

1.5.1 — How discovery works

For each abstract role, the agent does the following — in order — until something resolves:

1. Read folder names + Plot/README/index/CLAUDE files at the top level, then top-2-deep. Build a candidate list: which folders look like they could play this role based on name + their own description?
2. Read 3–5 sample files per candidate folder. Does the content match the role's purpose?
3. Score and pick. Highest-confidence candidate wins. If no candidate clears medium confidence → role is missing.

The agent does not privilege a specific folder name. Context/, About/, Me/, Personal/, Identity/, or a frontmatter section on root CLAUDE.md can all play the identity role. The agent decides by reading.

1.5.2 — Standard roles (patterns the agent recognizes)

These are patterns, not an exhaustive taxonomy. Every folder/file gets classified — these standard roles match the common shapes; anything that doesn't match becomes a custom role (Step 1.5.3).

1.5.3 — Custom roles (every other folder)

After standard-role discovery, every remaining top-level folder and every meaningful subfolder must be classified, not ignored. For each unclassified folder:

1. Read the folder's index file (under the discovered convention) if present.
2. Sample 3–5 files in the folder. Read first 1500 chars + headers.
3. Read the parent folder's index (if any) to see how this folder is described upstream.
4. Assign a custom role:
   • name — a slug derived from the folder name plus content (e.g., Building/ with prototype-build content → role name building; Garden/ with idea-incubation content → garden).
   • layer — one of curated (canonical, durable), session (ephemeral, time-stamped), archive (deactivated), meta (tooling, system files), unknown (agent could not confidently classify).
   • purpose — 1-line description of what the folder holds.
   • is_standard: false.
   • confidence: high | medium | low.

If the agent cannot confidently assign a layer (confidence low) → emit an F9.0 finding asking the user to clarify the folder's purpose during walk. The answer persists in the registry going forward.

Custom roles are first-class. F8, F9, and the per-finding fixers operate on roles by layer, not by membership in the standard-role list. A custom building role with layer: curated participates in F8's curated-layer synthesis exactly like the standard context role.

1.5.4 — Output: the role registry

Build this once, cache for the rest of the run, and persist to .claude/vault-roles.json at end of Step 1.5 so future runs start from confirmed assignments instead of re-prompting:

{
  "vault_root": "./",
  "discovered_at": "2026-05-08T14:23:00Z",
  "folder_index_convention": {
    "name": "README.md",
    "confidence": "high",
    "evidence": "23 of 31 non-trivial folders have README.md",
    "coverage": 0.74
  },
  "roles": [
    {"name": "identity",  "path": "./About/me.md", "kind": "file",   "layer": "curated", "is_standard": true,  "confidence": "high",   "purpose": "Operator bio + voice"},
    {"name": "context",   "path": "./Knowledge/",  "kind": "folder", "layer": "curated", "is_standard": true,  "confidence": "high",   "purpose": "Org/strategy/brand canonical knowledge"},
    {"name": "projects",  "path": "./Work/",       "kind": "folder", "layer": "curated", "is_standard": true,  "confidence": "high",   "purpose": "Active and recent work units"},
    {"name": "daily",     "path": "./Journal/",    "kind": "folder", "layer": "session", "is_standard": true,  "confidence": "medium", "purpose": "Per-day journal entries"},
    {"name": "resources", "path": "./Library/",    "kind": "folder", "layer": "curated", "is_standard": true,  "confidence": "high",   "purpose": "Prompts, frameworks, templates"},
    {"name": "archive",   "path": "./_archive/",   "kind": "folder", "layer": "archive", "is_standard": true,  "confidence": "high",   "purpose": "Deactivated content"},
    {"name": "building",  "path": "./Building/",   "kind": "folder", "layer": "curated", "is_standard": false, "confidence": "high",   "purpose": "Active prototype builds and experiments"},
    {"name": "garden",    "path": "./Garden/",     "kind": "folder", "layer": "curated", "is_standard": false, "confidence": "medium", "purpose": "Long-form essays in slow incubation"},
    {"name": "inbox",     "path": "./Inbox/",      "kind": "folder", "layer": "session", "is_standard": false, "confidence": "high",   "purpose": "Unprocessed capture; aged out into Garden or Resources"}
  ],
  "missing_standard_roles": ["decisions", "meetings", "transcripts"],
  "low_confidence_roles": ["garden"],
  "unconfirmed_custom_roles": []
}

1.5.5 — Show the discovery summary in chat (one block)

Frame this as "here's the structure I see in your vault" — not "here's what's missing from a checklist." The user's structure is the source of truth; the reference taxonomy is just one of the lenses the agent uses to recognize patterns.

## 🔍 Your vault structure — {N_folders} folders classified

| Folder | Role | Layer | Purpose | Confidence |
|---|---|---|---|---|
| ./About/me.md | identity | curated | Operator bio + voice | high |
| ./Knowledge/ | context | curated | Org/strategy/brand | high |
| ./Work/ | projects | curated | Active and recent work | high |
| ./Journal/ | daily | session | Per-day journal | medium |
| ./Library/ | resources | curated | Prompts, frameworks, templates | high |
| ./_archive/ | archive | archive | Deactivated content | high |
| ./Building/ | building (custom) | curated | Active prototype builds | high |
| ./Garden/ | garden (custom) | curated | Long-form essays in slow incubation | medium |
| ./Inbox/ | inbox (custom) | session | Unprocessed capture | high |

**Folder-index convention I detected:** README.md (74% coverage)

I'll audit this structure as it stands. F9.0 may suggest specific structural improvements where I see concrete evidence they'd help your vault (not just because the reference taxonomy contains them) — you'll review each suggestion in walk. Confirmed assignments persist to `.claude/vault-roles.json`.

Running F1 now…

The summary frames what the user has first. F9.0 findings about gaps appear later in the walk, with reasoning grounded in observed problems — not as a deficiency table at discovery time.

1.5.6 — Hard rules for downstream frameworks

• Frameworks reference roles by layer, not by name. F8's curated layer = every role with layer == 'curated' (standard or custom). F8's session layer = every role with layer == 'session'. F9 walks every folder regardless of role membership.
• Custom roles participate in every framework that operates on their layer. If building is layer: curated, F8 looks at Building/ for merge candidates, contradictions, themes, and promotions exactly like Context/.
• Missing roles never block a framework. If decisions is missing, F8 proceeds without it; F9.0 produces a finding suggesting the user create one (or assign the role to an existing custom folder).
• The folder-index convention is what F9.2 enforces — not Plot.md by default. If the user's vault uses README.md, F9.2 generates/refreshes README.md. If no convention exists, F9.0 proposes adopting one.
• Persisted registry is read at the start of Step 1.5. If .claude/vault-roles.json exists from a prior run, the agent loads it as the baseline and only re-classifies new folders or folders the user flagged for re-review. Confirmed assignments don't re-prompt every run.
• No framework hardcodes folder paths or file names. Examples in pass files are illustrative; runtime resolves through the registry.

Step 2 — Iterate frameworks F1 → F10 with judgment

This is not a regex pass. For each framework, read its pass-implementation file, then apply every check it defines to the files in that framework's scope. Triggers in the pass files surface candidates; the agent reads context and judges each candidate before producing a finding. Every finding includes reasoning specific to the case.

Why: a regex match on \bjust\b flags "just run X" (where "just" is doing real work — contrasting with running multiple) the same as "It's just a quick check" (where it's filler). Only an agent reading the line in context can tell which is which. The same applies to "be careful" (sometimes a closing reminder, sometimes a vague platitude), IMPORTANT: (sometimes earned, sometimes inflation), voice.md + brand.md (sometimes overlapping, sometimes intentionally separated), and most other framework signals.

2.1 — For each framework F1, F2, F3, F4, F5, F6, G7, F10, F8, F9 (in this order)

F10 runs after G7: it is file-local like F1–G7 and shares their targets, so it belongs with them rather than with the whole-vault passes. F8 runs second-to-last (cross-file synthesis). F9 runs last because it consumes the structural picture F1–G7 produced and operates on the largest blast radius (whole-vault structural reasoning, Plot.md generation, reorg proposals). Running them last keeps fix application ordered smallest-to-largest in Step 5.

Update the TaskCreate task for the current framework to in_progress before starting it; completed when its findings are logged. Mid-framework sub-updates allowed for long runs (F2, F8, F9).

For each framework:

1. Read the pass-implementation file for that framework (e.g., references/passes-anthropic-claude-md.md for F1). Cache it for the duration of the framework run.

2. Determine the file scope from the table at the top of this SKILL.md (e.g., F1 = every CLAUDE.md; F6 = every SKILL.md; F4/F5/G7 = every .md; F10 = every CLAUDE.md, .claude/rules/ file and SKILL.md).

3. For each check in the pass file:

   • Apply the trigger heuristic (regex / metric / structural pattern) to surface candidates fast. Some checks have no trigger — the file itself is the candidate.
   • For each candidate, read the surrounding 5–15 lines with the Read tool, then apply the agent-judgment criteria the pass file lists. Read other files (linked targets, sibling clusters, the file's index) when judgment requires it.
   • Decide: does this case actually violate the framework rule in this file's specific context? Or is it a false positive (the pass file lists common ones to skip)?
   • If real → produce a finding. If not → drop it; the trigger was a candidate, not a verdict.
   • Every finding includes a reasoning field (1–2 sentences specific to this case, not a generic restatement of the rule).

4. Run the framework's vault-wide checks (using indexes from Step 1.3): orphan detection, dead wikilinks, distractor pairs, schema compliance, etc. — see each pass file's "vault-wide" sections.

5. Emit one progress line when the framework completes:

   F1 Anthropic CLAUDE.md — read 14 CLAUDE.md files, judged 312 candidates → 22 findings (5 fail · 17 warn)

   The judged count vs findings count is a sanity check: if they're roughly equal, the run was lazy (regex candidates became findings without judgment); if judged ≫ findings, judgment is filtering false positives — that's the intended behavior.

2.2 — Reasoning sanity gate (per framework)

After completing each framework's run, sample 5 random findings (or all findings if < 5). Read each one's reasoning field. If > 40% of sampled reasonings are paraphrases of the rule rather than case-specific judgment ("This file uses too many em dashes" — paraphrase; "These em dashes appear in callout headers where the writer was substituting for colons; replacing with colons preserves the cadence" — judgment), stop and re-run that framework with deeper reads.

This is a hard gate. The skill's value is judgment, not regex. Shipping a framework's findings without enforcing this gate is a bug.

2.3 — Finding schema (every framework, every path)

{
  "framework": "F1",
  "check_id": "F1.2",
  "check_name": "Specificity heuristic",
  "path": "./Projects/foo/CLAUDE.md",
  "line": 42,
  "severity": "warn",
  "excerpt": "Be careful with auth",
  "reasoning": "This rule sits in the top half of a CLAUDE.md that's otherwise a routing index — there's no specific auth boundary, file path, or function named anywhere else. As a primary rule it falls into the 35%-compliance bucket; either anchor it to a specific path/function or remove it.",
  "action": "Either delete or rewrite as 'All /api/admin/* routes must call requireAdmin() from src/auth/middleware.ts'.",
  "fixable": false,
  "fixed": false,
  "citation": "anthropic-claude-md.md → Specificity beats vagueness"
}

The reasoning field is mandatory. Every finding has it.

Every finding ships a fix. The pass file always emits fixable: true. Old fixable: false "manual review" findings are gone — checks that historically went flag-only (F1.x, F4.x, F5.x) now ship walk-only fix proposals like every other framework.

The fix_status field is set by Step 5 after the user walks each finding. Possible values:

• applied → fix executed this run (green FIXED pill)
• saved_to_plan → fix written into the plan file for staged execution (blue SAVED pill)
• declined → user explicitly chose not to fix this item in walk (grey DECLINED pill)
• failed → fix attempted but failed safety check (red FAILED pill, with failure_reason)

There is no "skipped" or "deferred" state. Either the fix was applied, saved as a planned step, declined explicitly per-item, or failed mechanically. Open warnings do not survive the run.

Step 3 — Aggregate findings + compute score

For each framework F1–F8, count: total findings, severity breakdown (fail/warn/info), fixable count, files touched.

Score formula (framework-weighted)

For each framework F1..G7 and F10:
  deduction = (fail_count × 5) + (warn_count × 1)
  capped_deduction = min(deduction, 25)
score = max(0, 100 - sum(capped_deduction for F1..G7, F10))

F10 does affect the score — its findings are lint-like rule defects, same as F1–G7. F8 and F9 do not affect the score. F8 surfaces synthesis opportunities; F9 surfaces structural/discoverability changes. Both are optimization opportunities, not lint failures — counting them would conflate "vault hygiene" with "vault could be reorganized." Track F8 in an "Insights surfaced / applied" tile and F9 in an "Architecture changes / proposed / applied / saved-to-plan" tile.

After scoring, do not render a long markdown summary in chat. Emit one short block:

✅ All 10 frameworks applied.

| Framework | Files | Checks | Findings | Fail | Warn | Fixes proposed |
|---|---:|---:|---:|---:|---:|---:|
| F1 Anthropic CLAUDE.md | … | … | … | … | … | … |
| F2 Karpathy Wiki | … | … | … | … | … | … |
| F3 Caveman | … | … | … | … | … | … |
| F4 Chroma Context Rot | … | … | … | … | … | … |
| F5 Anthropic Memory | … | … | … | … | … | … |
| F6 Progressive Disclosure | … | … | … | … | … | … |
| G7 Hygiene | … | … | … | … | … | … |
| F10 Claude 5 Rules | … | … | … | … | … | … |
| F8 Reflection | … | … | … | … | … | … |
| F9 Architecture | … | … | … | … | … | … |
| **TOTAL** | … | … | … | … | … | … |

Score: {score_before}/100 (F8 + F9 not scored). Walking the architectural read next…

Step 3.5 — Architectural read (the synthesis paragraph)

Before walking fixes, write a short architectural read of the vault — top 1–3 things wrong with the structure as a whole, with reasoning grounded in Context/. This is the layer the user explicitly asked for: the agent demonstrating it understood what the vault means, not just what it failed.

Format:

### Architectural read

{1–3 short paragraphs. Each paragraph: one structural observation, why it matters for *this* user's world (cite Context/), the F9 finding(s) that surfaced it, the proposed direction.}

This paragraph also goes verbatim into the HTML dashboard (above the framework rows) so it's the first thing the user sees when they open the report. Keep it under 250 words total — synthesis, not a recap of findings.

If the agent cannot identify a structural observation worth surfacing (the vault is well-organized): write one sentence saying so, citing the F9 metrics that justify the assessment. Don't pad.

Step 4 — Walk every finding through apply-now / save-to-plan

Every finding ships a fix proposal. Step 4 walks the user through them. There is no "skip this framework," no "flag only," no "fix later." Each finding ends in one of four explicit states: applied, saved_to_plan, declined, or failed.

4.1 — One opening AskUserQuestion (the apply gate)

Before walking, fire one AskUserQuestion:

"Audit complete: {N_total} findings across 9 frameworks ({fail} fail · {warn} warn · {info} info). Every finding has a proposed fix. Pick mode:"

Options:

1. Bulk-apply (apply everything, no escapes) — every finding gets applied. Walk prompts only fire where the agent genuinely needs the user to pick a target/wording (e.g., "merge target: A or B?"). All else applies without per-item confirmation. The only valid non-applied state is failed (mechanical: OS lock, file conflict, dependency missing). No saved_to_plan, no declined. Use this when you've said "apply everything."
2. Selective walk — fire a per-finding prompt for every fix; user picks apply / save-to-plan / decline per item. Use when reviewing carefully or for a first run on a new vault.
3. Save everything to plan — write all proposed fixes as checklist steps into the discovered decisions-equivalent folder; no edits applied this run.
4. Cancel — abort before any fixes.

Option 1 is the default. The user picks 2 only when they want item-by-item gating. The user's prior instruction "apply everything" maps to Option 1, not Option 2.

4.1.1 — Bulk-apply mode rules (Option 1)

Hard rules when this mode is active:

• No saved_to_plan outcomes. That state is removed from the available fix_status set.
• No declined outcomes. Same.
• The agent does not unilaterally decide a finding is "test fixture," "the user probably didn't want this," "too complex to apply mechanically," or "judgment-required-per-section" and route it to anything other than applied/failed. If applying a fix mechanically would damage content, the agent attempts the safest mechanical version (e.g., split a 222KB file at H2 boundaries with a <!-- automated split, review headings --> marker; mark the split as applied with applied_with_caveat: true).
• Walk prompts fire only when the agent genuinely cannot pick a target without the user. Example: F8.2 merge with three plausible canonical targets — fire the prompt. Example: G7.1 em-dash substitution — apply without prompting; the agent's per-occurrence reasoning already chose the substitution.
• Mechanical failures are still recorded as failed with failure_reason (OS-locked file, missing parent directory, file conflict, framework-safety check rolled back the fix). Failed fixes are reported in the dashboard with their reason — they're not silently skipped.
• The agent must not pre-classify findings as "skip in bulk-apply mode." Every finding is in scope. If applying a daystar/ test-fixture fix damages a deliberate test pattern, the user can revert that file specifically — but the agent doesn't make that call.

4.2 — Per-finding walk loop

Order: F1 → F2 → F3 → F4 → F5 → F6 → G7 → F8 → F9. Within F8/F9, smallest blast radius first (per pass file).

For each finding:

1. Show the finding compactly in chat: path, severity, 1-line excerpt, the proposed fix's proposed_edit or migration step.
2. Fire AskUserQuestion with the per-finding-type sub-prompt:

Every option reaches a terminal state for this finding. There is no "skip" option that leaves the finding open. "Decline" is recorded as an explicit user decision and shown in the report — it's a decision, not a deferral.

3. Update the finding's fix_status (applied / saved_to_plan / declined) and any per_item_target chosen by the user.
4. TaskUpdate the current framework's task with a {i}/{N} progress note every 10 findings.

4.3 — Save-to-plan file format

Save-to-plan path resolution (uses the role registry):

1. If roles.decisions.path is set → save under {decisions.path}/{YYYY-MM-DD}-reorg.md.
2. Else if any folder matches *decisions*/, *logs*/, *records*/ (case-insensitive) → use that.
3. Else create audits/ at vault root and save there. Note the missing decisions role to F9.0 — the user gets a fix proposal to formalize a decisions-equivalent folder.

When findings are routed to save-to-plan, append checklist entries to the resolved path:

---
status: pending
type: reorg-plan
tags: [optimizer, plan]
date: 2026-05-08
source: os-optimizer run 2026-05-08T14:23:00Z
---

# Vault reorg plan — 2026-05-08

Generated by os-optimizer. Each item is a fix proposal saved for staged execution. Walk them when ready.

## F9.6 Reorg proposals

- [ ] **Merge `Notes/` into `Resources/notes/`** — F9.5 finding cluster: both folders hold scratch with 38% file-name overlap. Migration:
  - Move 12 files from `Notes/` to `Resources/notes/`.
  - Redirect 4 inbound wikilinks.
  - Update root CLAUDE.md routing entry to remove `Notes/`.
  - Delete empty `Notes/` directory.
  - Reasoning: `Resources/notes/` Plot.md states it holds reference notes; `Notes/` Plot.md states the same. Per `Context/me.md`, the user's stated convention is one resource library — keeping two is structural drift.

## F8.2 Merge candidates

- [ ] **Merge `Notes/2026-q1-strategy.md` and `Projects/positioning/research/strategy-thoughts.md` into `Context/strategy.md`** — F8.2 finding. Steps: …

(continues per saved finding)

The plan file is itself audited next run — F1/G7 conventions apply.

4.4 — Failure to walk

If the agent skips a finding (forgets to fire its sub-prompt, batches multiple findings into one prompt, or treats "no answer" as decline) — that's a bug. Walk every finding individually. The visible task list catches this: if a framework's task moves to completed while findings remain unwalked, the verification step in 5.7 will flag it.

Step 5 — Apply approved fixes (set fix_status per finding)

Apply in this order (smallest blast radius first). For every finding, set fix_status to applied, saved_to_plan, declined, or failed based on what happened in Step 4 + this step. The HTML render uses fix_status directly.

Save-to-plan items are written to the plan file in Step 4.3 — this step (5) only handles the items the user picked "apply now" for. (In Bulk-apply mode there are no save-to-plan items.)

5.0 — Capture BEFORE metrics (manda

…(truncated)