memory-index-sync

name	memory-index-sync
description	Detect and heal index.md drift — finds memory files on disk not registered in index.md and registers them. Run when /gaai-status reports unregistered files, after batch memory operations, or as a post-delivery gate.
license	ELv2
compatibility	Works with any filesystem-based AI coding agent
metadata	{"author":"gaai-framework","version":"1.0","category":"cross","track":"cross-cutting","id":"SKILL-MEMORY-INDEX-SYNC-001","updated_at":"2026-05-08T00:00:00.000Z","status":"stable"}
inputs	["contexts/memory/ (full scan — read-only except index.md)"]
outputs	["contexts/memory/index.md (registry updated if drift found)","sync_report (inline summary of changes applied and anomalies flagged)"]

Memory Index Sync

Purpose / When to Activate

Activate when:

• /gaai-status reports files on disk not registered in index.md
• After a batch of DEC files were created outside the decision-extraction skill
• As a lightweight post-delivery gate to confirm index integrity
• Before running memory-refresh or memory-compact (ensures index accuracy first)

This skill heals drift — it does NOT create new knowledge. It only registers things that already exist on disk but are missing from index.md.

---

Process

Step 1 — Decision Registry Sync

1. Read all registry files at contexts/memory/ root (index.md + any index-*.md siblings such as index-decisions.md when Decision Registry has been extracted per file-size budget) — extract all registered DEC IDs from any of them
2. Read archive/superseded-decisions.archive.md "Superseded DEC entries" table — extract all archived DEC IDs (column 1)
3. Glob decisions/DEC-*.md — list all files on disk, extract IDs from filenames
4. For each DEC file on disk:
   • Read its YAML frontmatter : id, domain, level, title, status, superseded_by, archived_to (coordinated with memory-archive-superseded skill)
   • If archived_to: field is set (e.g. archive/superseded-decisions.archive.md) AND the DEC ID is present in the archive index: SKIP active registration. The DEC's active home is the archive. Do NOT add a row to the active Decision Registry. (Prevents undo of archive operation by memory-archive-superseded skill.)
   • If archived_to: is set BUT no matching archive row: flag ⚠️ ARCHIVE INCONSISTENCY: DEC-{N} frontmatter declares archived_to but no row in archive index — escalate, do NOT auto-add either way
   • If archived_to: is NOT set AND DEC is not in any active registry: add a row to the appropriate Decision Registry — prefer index-decisions.md if it exists (Decision Registry has been extracted there) ; otherwise add to index.md Decision Registry as before. Row form is pointer-only (per memory-index-compact skill): | DEC-{N} | {domain} | {level} | {≤30-word topic from frontmatter title or essence ; never copy from DEC body §s} | {status} {YYYY-MM-DD} |. HARD CAP : ≤ 200 chars. If the frontmatter title alone exceeds 200 chars (rare), use first clause + truncate. If frontmatter status: superseded and superseded_by is set: append ⚠️ SUPERSEDED by DEC-{M} AND flag in report : "consider invoking memory-archive-superseded for DEC-{N}".
5. For each registered DEC with no file on disk: flag ⚠️ MISSING FILE in the sync report — do NOT delete registry rows (possible archive situation)

Step 2 — File Count Update

Re-count all DEC-*.md files on disk. Update the Shared Categories table file count in index.md to match.

Step 3 — Summary File Sync

1. Read index.md Summaries section — extract registered summary filenames
2. Glob summaries/*.summary.md — list all files on disk
3. For each summary on disk not registered in index.md: read its frontmatter, add entry to Summaries section
4. For each registered summary with no file on disk: flag ⚠️ MISSING FILE — update pointer or delete entry in sync report

Step 4 — Supersession Reconciliation

1. For each DEC file on disk with status: superseded in frontmatter:
   • Check if its registry row carries the ⚠️ SUPERSEDED by DEC-{M} marker
   • If not: add the marker to the registry row
2. Verify the Superseded/Retracted table in index.md is consistent with the Decision Registry (no contradictions)

Step 5 — Index Frontmatter Update

Update index.md frontmatter updated_at field:

• Format: {YYYY-MM-DD} ({N} entries synced, {M} anomalies flagged) — or (no drift — confirmed clean) if nothing changed

Step 6 — Archive Index Symmetry Check

1. For every DEC ID in archive/superseded-decisions.archive.md "Superseded DEC entries" table : verify there is exactly one matching pointer row in index.md § "Superseded (archived)" pointer table. Dangling archive row (no active pointer) = anomaly.
2. For every pointer row in index.md § "Superseded (archived)" : verify there is exactly one matching archive row. Orphan pointer (no archive backing) = anomaly.
3. Hand off to memory-index-lint for full discoverability invariant validation. If memory-index-lint is invokable (shell available), run python3 scripts/validate-memory-index.py and require CLEAN exit before declaring DRIFT_HEALED ; otherwise perform the L3 prompt-based check from memory-index-lint/SKILL.md.

---

Output: Sync Report (inline, after completion)

# Memory Index Sync — {date}

## Changes Applied
- Registered: DEC-{A}, DEC-{B}, ..., DEC-{Z} (10 entries added to registry)
- Supersession markers added: DEC-{X} (→ DEC-{Y})
- File count updated: N → M

## Anomalies Flagged (requires human review)
- ⚠️ MISSING FILE: DEC-{N} registered but no file on disk
- ⚠️ ORPHAN SUMMARY: decisions-80-89.summary.md on disk, not in index

## Result: CLEAN | DRIFT_HEALED | ANOMALIES_FOUND

---

Quality Checks

• Only registers what exists on disk — never invents registry rows
• Never deletes existing registry rows (only flags anomalies)
• Sync report is always produced, even if no changes needed (CLEAN)
• Idempotent — running twice produces no additional changes
• Does not modify any file except index.md

---

Non-Goals

This skill must NOT:

• Create new DEC files (use decision-extraction)
• Ingest new knowledge (use memory-ingest)
• Compact or archive memory (use memory-compact or memory-refresh)
• Modify DEC file content

Memory-index-sync heals the registry. It does not create or delete knowledge.