# Compile Procedure

The compile operation reads recent vault changes, updates affected
pages, refreshes landings and indexes, generates synthesis pages
when warranted, and commits the result.

## Pre-flight

1. Read `<vault-root>/CLAUDE.md` (the spec)
2. Read `<vault-root>/log.md` (find timestamp of last compile
   entry)
3. Confirm the vault is in a clean git state. If there are
   uncommitted changes:
   - If they are user edits in progress, stop and ask the user
     to commit or stash before proceeding
   - If they are leftovers from a failed prior run, stop and
     report — do not auto-clean

## Step 1: Identify changes since last compile

- List all files in `Sources/` with `mtime` newer than the last
  compile timestamp from `log.md`
- Read those files in full
- Categorize: new files, edited files
- For each, identify its `type:` (project-plan, session-notes)
  and domain from `path:` frontmatter (Dev, Venture, Homelab, Reference)
- Also check `Wiki/` for any manual edits to entity or synthesis pages
- If a file has no frontmatter or invalid frontmatter, flag it
  but proceed with best-effort categorization

## Step 2: Pre-compile commit

Make a single commit capturing the vault state before any
writes:

```
git add -A
git commit -m "pre-compile: <reason>"
```

Where `<reason>` is the trigger phrase or a one-line summary of
what's about to be processed (e.g., "compile run, 3 new
sessions and 2 project edits").

## Step 3: Update affected pages

For each project page touched by recent changes:

- Refresh the **Current state** section based on session notes
  added since the last update
- Add new session notes to the **Sessions** section as
  wikilinks
- Update **Decisions locked** if recent sessions captured new
  decisions
- Update **Open questions** based on recent activity
- Update the `updated:` frontmatter date

For each entity page referenced by recent changes:

- Update **Current state** if relevant
- Add new related projects/sessions to **Related projects**
  section
- Append a History entry if a significant event occurred
- Update the `updated:` frontmatter date

## Step 4: Entity promotion check

For any topic referenced in 2+ projects or 3+ sessions that
does not yet have an entity page, propose promotion:

- Add to a `promotions:` list in the compile summary
- Do not auto-create. The user reviews the proposed promotions
  and triggers a follow-up compile if any are approved.

(Exception: if the user's invocation explicitly authorized
auto-promotion for this run, proceed and create the pages.)

## Step 5: Synthesis check

Look for cross-cutting patterns warranting a synthesis page:

- Multiple sessions/projects converging on the same theme
- A pattern of decisions across projects that benefits from a
  unified statement
- A body of related entities that lacks a connecting page

If such a pattern is identified:

- Draft a synthesis page per the spec in `CLAUDE.md`
- Required: `sources:` frontmatter listing every page it pulls
  from
- Required: prose attribution for each substantive claim
- Required: explicit flag for any agent-inference claim not
  directly in a source

Do not generate synthesis pages aggressively. One per compile
run is the norm; zero is fine. Three is suspicious.

## Step 6: Refresh topic landings and indexes

For each domain with changes, update BOTH Sources and Wiki indexes:

**Sources indexes** (`Sources/<domain>/index.md`):
  - Regenerate **Active projects** list from frontmatter query
  - Regenerate **Recent sessions** list (last 10 or last 30 days)
  - Update **Completed projects** section
  - Update `updated:` date

**Wiki indexes** (`Wiki/<domain>/index.md`):
  - Update **Entities** list if entity list changed
  - Update **Synthesis pages** if any were added in this run
  - Update `updated:` date

**Layer indexes** (`Sources/index.md`, `Wiki/index.md`):
  - Refresh cross-domain catalog for each layer

**Root index** (`index.md`):
  - Refresh highlights: active projects, recent sessions, key entities
  - Update counts

## Step 7: Append to log.md

Append a single entry:

```markdown
## [YYYY-MM-DD HH:MM] compile | <one-line summary>

- Pages touched: <list>
- Pages created: <list>
- Entities promoted: <list, or "none">
- Synthesis pages written: <list, or "none">
- Tags proposed: <list, or "none">
- Contradictions flagged: <list, or "none">
- Notes: <free-text observations, if any>
```

## Step 8: Post-compile commit

```
git add -A
git commit -m "compile: <one-line summary>" -m "<body with same fields as log entry>"
```

## Step 9: Session summary

Report back to the user with:

- One-line summary of what was done
- Counts: pages touched, created, promoted, synthesized
- Anything flagged for user review (proposed promotions,
  proposed tags, suspected contradictions)
- Anything that didn't get done and why (e.g., file with
  invalid frontmatter, file the agent wasn't sure how to
  categorize)
- Next step suggestion (lint pass, or nothing)

## Stop conditions

Stop and report (do not proceed) if:

- Vault has uncommitted changes that are not from this run
- `CLAUDE.md` is missing or unreadable
- A page has malformed frontmatter that the agent cannot
  resolve confidently
- Git operations fail
- A proposed write would delete user content (always preserve;
  flag for review)

## What this procedure does not do

- Restructure folders
- Delete pages
- Rename files
- Modify pages outside the vault
- Run lint (separate operation)
- Run a second compile pass after the first