jd-jdex-audit

Johnny.Decimal JDex Audit

This skill compares a system's JDex (the authoritative index) against the actual folder structure on disk, identifying mismatches and suggesting fixes.

---

1. Locate the System

1.1 Find the JD Root

Check common locations:

• ~/Library/Mobile Documents/com~apple~CloudDocs/JD/ (iCloud Drive)
• ~/Documents/JD/
• ~/JD/

If the user specifies a system code (e.g., "audit my P10 system"), target that specific system. Otherwise, list all available systems and ask which to audit.

1.2 Load the JDex

Read the JDex file at:

SYS/00-09 */00 */00.00 *JDex*

Parse it into a structured list of areas, categories, and IDs. Each entry should capture:

• The AC.ID (or SYS.AC.ID) address
• The description/name
• Any +SUB entries

1.3 Snapshot the Filesystem

List all folders to depth 3 under the system root. Parse folder names to extract AC.ID addresses, area ranges, and category numbers.

---

2. Compare JDex vs. Filesystem

Run three checks:

2.1 Orphaned JDex Entries

JDex entries that have no corresponding folder on disk.

These indicate either:

• A folder was deleted without updating the JDex
• A planned ID that was never created
• A typo in the JDex entry

2.2 Undocumented Folders

Folders on disk that have no corresponding JDex entry.

These indicate either:

• A folder was created without updating the JDex
• The JDex fell out of sync during manual organization
• A folder created by another tool or process

2.3 Name Mismatches

JDex entries whose description doesn't match the folder name, or folders whose name doesn't follow the expected AC.ID Description format.

---

3. Check +SUB Indexes

For categories that use +SUB extensions:

3.1 Locate Index Files

+SUB categories typically have an index file (e.g., 51.01 Open-source project index.md). Find these by looking for files matching *.md at the category or ID level that contain +SUB listings.

3.2 Compare Index vs. Folders

• List all +NNNN or +CODE folders within the ID
• Compare against the index file entries
• Flag missing or extra entries

---

4. Report Findings

Present a clear audit report to the user:

Report Format

## JDex Audit: [System name]

**Audit date:** YYYY-MM-DD
**JDex location:** [path]
**System root:** [path]

### Summary

| Check | Count |
|-------|-------|
| JDex entries | N |
| Filesystem folders | N |
| Orphaned JDex entries | N |
| Undocumented folders | N |
| Name mismatches | N |
| +SUB index issues | N |

### Orphaned JDex Entries (in JDex but no folder)

| AC.ID | Description | Suggested Action |
|-------|-------------|-----------------|
| 11.05 | Home improvement | Create folder or remove from JDex |

### Undocumented Folders (folder exists but not in JDex)

| Folder | Path | Suggested Action |
|--------|------|-----------------|
| 11.08 Garage storage | 10-19/11/11.08 | Add to JDex |

### Name Mismatches

| AC.ID | JDex says | Folder says | Suggested Action |
|-------|-----------|-------------|-----------------|
| 11.03 | Home insurance | Homeowners insurance | Reconcile names |

### +SUB Index Issues

| Category | Issue | Details |
|----------|-------|---------|
| 51.01 | Missing from index | +0004 folder exists, not in index |

---

5. Offer Fixes

After presenting the report, offer to fix issues:

Safe Fixes (do automatically with confirmation)

• Add undocumented folders to JDex: Append new entries matching the folder names.
• Update +SUB index files: Add missing entries to index files.

Requires User Decision

• Orphaned JDex entries: Ask whether to create the missing folder or remove the JDex entry.
• Name mismatches: Ask which name is correct (JDex or folder) and update the other.

Never Do Automatically

• Delete folders: Even if they appear orphaned, never delete without explicit user confirmation.
• Rename folders: Name changes can break references. Always confirm first.
• Create new areas or categories: These are structural decisions.

---

6. Regenerate JDex (Optional)

If the user requests it, offer to regenerate the JDex entirely from the folder structure:

1. Walk the filesystem and build a complete list of areas, categories, and IDs.
2. Preserve any JDex-only metadata (cross-system references, notes, +SUB descriptions) from the existing JDex.
3. Write the new JDex, merging filesystem reality with JDex metadata.
4. Present the result for user approval before overwriting.

Warning: Regeneration loses any JDex entries that don't have corresponding folders. Always confirm before proceeding.

---

7. Multi-System Audit

When auditing multiple systems:

1. Audit each system independently.
2. Present per-system reports.
3. Optionally check cross-system references: if P10.34.01 is referenced by F50.32.01, verify that both the source and the reference exist.
4. Provide a combined summary at the end.