LLM Wiki

- **Pin queued commits in bounded transactions.** Create `refs/llm-wiki/sources/<sha>` when a source is queued and delete it in the same ref transaction that writes its durable receipt. Backfill pins for pre-upgrade pending and quarantined records in batches of 64 by default (`LLM_WIKI_MAX_SOURCE_PIN_BATCH`). Reconstruct empty crash-left `.<sha>.<pid>` queue files when their source commit is available; retain unavailable records for diagnosis. Refuse to invoke or acknowledge a batch whose selected SHA is not an available commit.
- **Recover stale locks safely.** A live owner PID with the recorded process-start identity wins. Dead, PID-reused, or malformed owner blobs are replaceable only through the Git ref's compare-and-swap old-OID guard.
- **Validate before committing and publishing.** Reject any tracked, untracked, or ignored change outside `wiki/`. Compile `wiki/log.md`, force-stage only `wiki/` so intentionally ignored wikis persist, and commit with both recursion guards (`HIVE_SKIP_LLM_WIKI_POST_COMMIT=1` and `git -c core.hooksPath=/dev/null`). Fetch and merge the remote refresh branch, then push only `llm-wiki/refresh`; retain local work when fetch, merge, or push fails.
- **Failure is clean and bounded.** If agent execution, wiki-only validation, compilation, staging, or commit fails, force-remove the disposable managed worktree. After two consecutive failed batches by default, move the active batch to `<shared-git-dir>/llm-wiki/failed/` and open the repository-wide circuit. Continue queueing new sources without launching a provider. Never delete failed source data or automatically run a quarantined source again. User checkout bytes and branch refs must remain unchanged.
- **Subscription use is bounded.** Run provider overrides, Codex, Claude Code,
  Pi, QMD, and Git ref operations through `timeout` or `gtimeout`. If no bounded
  runner is available, fail closed before starting a provider and retain the

- **Pin queued commits in bounded transactions.** Create `refs/llm-wiki/sources/<sha>` when a source is queued and delete it in the same ref transaction that writes its durable receipt. Backfill pins for pre-upgrade pending and quarantined records in batches of 64 by default (`LLM_WIKI_MAX_SOURCE_PIN_BATCH`). Reconstruct empty crash-left `.<sha>.<pid>` queue files when their source commit is available; retain unavailable records for diagnosis. Refuse to invoke or acknowledge a batch whose selected SHA is not an available commit.
- **Recover stale locks safely.** A live owner PID with the recorded process-start identity wins. Dead, PID-reused, or malformed owner blobs are replaceable only through the Git ref's compare-and-swap old-OID guard.
- **Validate before committing and publishing.** Reject any tracked, untracked, or ignored change outside `wiki/`. Compile `wiki/log.md`, force-stage only `wiki/` so intentionally ignored wikis persist, and commit with both recursion guards (`HIVE_SKIP_LLM_WIKI_POST_COMMIT=1` and `git -c core.hooksPath=/dev/null`). Fetch and merge the remote refresh branch, then push only `llm-wiki/refresh`; retain local work when fetch, merge, or push fails.
- **Failure is clean and bounded.** If agent execution, wiki-only validation, compilation, staging, or commit fails, force-remove the disposable managed worktree. After two consecutive failed batches by default, move the active batch to `<shared-git-dir>/llm-wiki/failed/` and open the repository-wide circuit. Continue queueing new sources without launching a provider. Never delete failed source data or automatically run a quarantined source again. User checkout bytes and branch refs must remain unchanged.
- **Subscription use is bounded.** Run provider overrides, Codex, Claude Code,
  Pi, QMD, and Git ref operations through `timeout` or `gtimeout`. If no bounded
  runner is available, fail closed before starting a provider and retain the

- The current directory must be inside a git repository.
- QMD is optional but recommended. Use it when available; when missing, suggest installing it before falling back to `rg`.
- Merge existing agent settings and instructions. Do not overwrite existing config files blindly.
- Detect the main cross-project wiki when present. Check `~/wikis/master/wiki/`, `~/wikis/main/wiki/`, `<parent-of-project>/wikis/master/wiki/`, and `<parent-of-project>/wikis/main/wiki/`.
- Install wiki context for all supported agents. Only one agent owns headless scheduled and post-commit maintenance.

launch a direct refresh against whichever checkout happened to install it.
When automation is not approved, do not enable a timer; the upgrade path uses
`--disabled` to reconcile old units without activating maintenance. On
non-systemd platforms, leave the scripts installed, record the scheduler gap in
`wiki/gaps.md`, and report the manual drain command.

Preserve existing hooks and unrelated hook logic. The bundled runner reads the

- The current directory must be inside a git repository.
- QMD is optional but recommended. Use it when available; when missing, suggest installing it before falling back to `rg`.
- Merge existing agent settings and instructions. Do not overwrite existing config files blindly.
- Detect the main cross-project wiki when present. Check `~/wikis/master/wiki/`, `~/wikis/main/wiki/`, `<parent-of-project>/wikis/master/wiki/`, and `<parent-of-project>/wikis/main/wiki/`.
- Install wiki context for all supported agents. Only one agent owns headless scheduled and post-commit maintenance.

launch a direct refresh against whichever checkout happened to install it.
When automation is not approved, do not enable a timer; the upgrade path uses
`--disabled` to reconcile old units without activating maintenance. On
non-systemd platforms, leave the scripts installed, record the scheduler gap in
`wiki/gaps.md`, and report the manual drain command.

Preserve existing hooks and unrelated hook logic. The bundled runner reads the

- The current directory must be inside a git repository.
- QMD is optional but recommended. Use it when available; when missing, suggest installing it before falling back to `rg`.
- Merge existing agent settings and instructions. Do not overwrite existing config files blindly.
- Detect the main cross-project wiki when present. Check `~/wikis/master/wiki/`, `~/wikis/main/wiki/`, `<parent-of-project>/wikis/master/wiki/`, and `<parent-of-project>/wikis/main/wiki/`.
- Install wiki context for all supported agents. Only one agent owns headless scheduled and post-commit maintenance.

launch a direct refresh against whichever checkout happened to install it.
When automation is not approved, do not enable a timer; the upgrade path uses
`--disabled` to reconcile old units without activating maintenance. On
non-systemd platforms, leave the scripts installed, record the scheduler gap in
`wiki/gaps.md`, and report the manual drain command.

Preserve existing hooks and unrelated hook logic. The bundled runner reads the