ngerakines/jd/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.

1. Write the new JDex, merging filesystem reality with JDex metadata.
2. 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.

1. Provide a combined summary at the end.