---
name: audit
description: Scan thinking folder and Obsidian vault inbox for organizational drift — loose files, missing metadata, stale items, broken references. Reports only; never acts without approval.
argument-hint: "[thinking|inbox] [--include-deferred]"
---

# Collections Audit

Scan the thinking folder and/or Obsidian vault inbox for organizational drift. Produce a structured report of what's out of place. Propose fixes but **never execute without explicit steward approval**.

## Paths

- **Thinking folder**: `/Users/davidglidden/_Dev/CapableMind-AI/docs/thinking/David/`
- **Thinking README** (living index): `/Users/davidglidden/_Dev/CapableMind-AI/docs/thinking/README.md`
- **CURATION-MAP**: `/Users/davidglidden/_Dev/CapableMind-AI/docs/thinking/David/l2-constitution/CURATION-MAP.md`
- **Vault root**: `/Users/davidglidden/Library/Mobile Documents/iCloud~md~obsidian/Documents/David, root-and-branch/`
- **Vault inbox**: `00a. _inbox/` (relative to vault root)
- **Vault People**: `03. People/` (relative to vault root)

## Scope

Parse `$ARGUMENTS` to determine scope:

- No argument or `all` → audit both targets
- `thinking` → thinking folder only
- `inbox` → vault inbox only

## Procedure

### 1. Thinking Folder Audit

Run these checks **in parallel** where possible. For frontmatter checks, read only the first 5 lines of each file (check for `---` opener), never the full content.

#### a. Loose files at root

Glob for `*.md`, `*.json`, `*.yaml` directly in the thinking folder (not recursive). Exclude `CLAUDE.md` (belongs at root by convention). Every other file is a MOVE issue.

Propose destinations using naming heuristics:
- `amendment-*` → `amendments/`
- `substrate-governance-*` → `l2-constitution/` (governance inquiry content)
- `l2-design-*` → `l2-constitution/`
- `D.Glidden - The Chamber*` → `chamber/` or `reviews/`
- `entities.json`, `mempalace.yaml` → flag for steward decision (utility files, no obvious home)

#### b. Missing YAML frontmatter

For every `.md` file across all subdirectories, check if line 1 is `---`. This is a binary check — has frontmatter or doesn't. Report as aggregate per subfolder: "N of M files in `l2-constitution/` lack frontmatter."

Do NOT propose specific fields — that's an editorial decision for the steward.

#### c. CURATION-MAP inventory drift

Read CURATION-MAP.md. Extract any file count statistics (§6 or similar). Compare against actual filesystem counts for `l2-constitution/` and its subdirectories. Report mismatches.

Also check: are there files on disk in `l2-constitution/` that appear in no CURATION-MAP section? These are "uncharted" files.

#### d. CURATION-MAP §4 — unresolved ambiguous items

Read CURATION-MAP.md §4 (Ambiguous Status). List any items still awaiting steward classification. These are AMBIGUOUS issues — the audit surfaces them but cannot resolve them.

#### e. Broken cross-references

Grep for markdown links `[...](...)` that reference `.md` files within the thinking folder. For each, check if the target file exists (resolving relative paths from the source file's location). Report broken links with source file and line number.

Keep this check scoped to `l2-constitution/` (the largest and most cross-referenced subfolder) to stay fast. Expand scope in v2 if needed.

#### f. README.md drift

Read `thinking/README.md`. Find David's section. Extract the file counts from subsection headings (pattern: `### Category (Path/) — N files`). Compare against actual file counts in each subdirectory. Report mismatches.

### 2. Vault Inbox Audit

Run these checks **in parallel**. Read only frontmatter (first 10 lines) of each inbox file.

#### a. Empty or placeholder titles

Read frontmatter of each `.md` file in the inbox. Flag files where the `title:` field is:
- Empty or whitespace-only
- `---`, `***`, `----`, or similar punctuation-only
- A single character or bracket expression like `[pattern template]`

These are MISSING issues — the file can't be triaged without a usable title.

#### b. Person-name detection

Identify files whose `title:` looks like a person or business name: 2–3 capitalized words, no markdown characters, no common sentence starters. Cross-reference against filenames in `03. People/`.

- Match found in People → skip (already handled)
- No match → MOVE issue: "Looks like a contact — propose creating People file or routing to `03. People/`"

#### c. Staleness by age

Extract `created` or `draft_created` date from frontmatter. Bucket files by age:
- 30–90 days
- 90–180 days
- 180+ days

Report as **aggregate** with count per bucket: "54 files older than 180 days (Sept 2025 Drafts migration batch)." Do NOT list every file individually — at 67+ files that's noise, not signal.

#### d. Missing type classification

Count how many inbox files have a `type:` field in frontmatter. Report the aggregate: "0 of 67 files have type classification."

If the count is low, note the proposed convention for steward consideration:
> Proposed `type:` values: `contact`, `fragment`, `prompt`, `session`, `reference`, `pedagogy`, `admin`

This is INFO severity — a convention proposal, not an error.

### 3. Compile Report

Structure the output exactly as follows:

```
## Audit Report — [date]

**Scope:** [thinking | inbox | both]
**Files scanned:** X thinking, Y inbox
**Issues found:** N

### MOVE (wrong location)
[one line per file: path → proposed destination]

### MISSING (metadata gaps)
[aggregates per subfolder for frontmatter; individual items for titles]

### STALE (drift / aging)
[CURATION-MAP mismatches, README drift, inbox age buckets]

### AMBIGUOUS (needs steward decision)
[CURATION-MAP §4 items, utility files with no obvious home]

### BROKEN (integrity)
[broken cross-references: source file:line → missing target]

### INFO
[type classification proposal, other non-actionable observations]
```

Omit any section that has zero items. End with:

```
Approve all proposed moves? Or review individually?
```

### 4. Handle Steward Response

**If "approve all":**
- Execute MOVE items: use `git mv` for thinking folder files (inside git repo), regular `mv` for vault files
- After moves in thinking folder: update `thinking/README.md` per the CLAUDE.md convention (scan filesystem, update file counts in subsection headings)
- Do NOT batch-approve AMBIGUOUS items — those always require individual decisions

**If "review individually":**
- Present each MOVE item one at a time
- For each: steward says apply / skip
- After all reviewed, execute approved moves and update README

**After execution:**
- Report what was moved and what was skipped
- Note any AMBIGUOUS items still unresolved

## Important constraints

- **Never move files without approval.** This is a reporting tool first.
- **Never read full file contents** for the audit scan — frontmatter and filenames only. Content is the steward's domain.
- **Respect the iCloud path.** The vault path contains spaces. Always quote paths in Bash commands.
- **Git awareness.** The thinking folder is inside a git repo. Use `git mv` for moves there. The vault is NOT in a git repo.
- **Don't propose content changes.** Missing frontmatter is reported; what fields to add is the steward's decision.
- **Aggregate where possible.** 67 individually listed inbox files is not a useful report. Bucket and count.
- **CURATION-MAP is governance.** Treat §4 items as the steward's decision queue, not as problems to solve.