wiki-stage-commit — Claude Code skill: approve staged wiki writes

---
name: wiki-stage-commit
description: >
  Review staged wiki writes and promote accepted pages to final locations when WIKI_STAGED_WRITES is enabled. Use for staging approval/commit; rejected pages return to _raw/ for editing.
---

# Wiki Stage Commit — Staged Write Promotion

You are reviewing LLM-written pages that are waiting in `_staging/` for human approval before they land in the live wiki. This skill is only useful when `WIKI_STAGED_WRITES=true` in the vault config.

## Before You Start

1. **Resolve config** — follow the Config Resolution Protocol in `llm-wiki/SKILL.md`. This gives `OBSIDIAN_VAULT_PATH` and `WIKI_STAGED_WRITES`.
2. If `WIKI_STAGED_WRITES` is not set or is `false`, tell the user: "Staged writes mode is not enabled. Set `WIKI_STAGED_WRITES=true` in your `.env` to use this feature." Then stop.
3. Read the `_staging/` directory inventory.

## Invocation Forms

```
/wiki-stage-commit               # interactive review: show each file and ask accept/reject
/wiki-stage-commit --all         # accept all staged files without per-file review
/wiki-stage-commit --reject-all  # reject all staged files (move to _raw/ for manual editing)
/wiki-stage-commit --list        # list staged files with summary, no changes
```

## Step 1: Inventory Staged Files

The CLI owns the inventory — don't glob `_staging/` yourself:

```bash
obsidian-wiki staging list --json
```

Each entry carries:

| Field | Meaning |
|---|---|
| `staged_path` | vault-relative path of the staged file |
| `live_path` | where it will land (a `.patch.md` targets the page it is named after) |
| `kind` | `new`, `update`, or `patch` |
| `staged_revision` | content hash of the staged file, as you are seeing it now |
| `live_revision` | content hash of the live page, or `null` if there is none yet |
| `staged_mtime` | when it was staged |

**Keep `staged_revision` and `live_revision` for every file you show the user.** They are what makes Step 3 refuse to overwrite an agent's concurrent write instead of silently clobbering it.

Report the inventory:

```
Staged files: 4 new pages, 2 updates

New pages:
  _staging/concepts/attention-mechanism.md        (staged 2026-09-08)
  _staging/entities/andrej-karpathy.md            (staged 2026-09-08)

Updates:
  _staging/concepts/transformer-architecture.md   (target: concepts/transformer-architecture.md)

Patches:
  _staging/skills/prompt-engineering.patch.md     (target: skills/prompt-engineering.md)
```

If the list is empty, report: "Nothing staged. All writes have been committed or no staged writes have been produced yet."

## Step 2: Per-File Review (interactive mode)

For each staged file (new pages first, then updates):

### For new pages:

Display a summary:

```
--- New page: concepts/attention-mechanism.md ---
Title:    Attention Mechanism
Tags:     #ml #architecture
Summary:  Core building block of transformers — computes weighted sum of values based on query-key similarity.
Tier:     supporting
Confidence: 0.72
Sources:  papers/attention.pdf

[Preview first 20 lines of body]
...

Accept [a], Reject [r], Skip [s], Preview full [p]?
```

### For patch files:

Display a structured diff:

```
--- Update: concepts/transformer-architecture.md ---
Source: _staging/concepts/transformer-architecture.patch.md

Proposed additions (+):
+ Transformers outperform RNNs on tasks requiring long-range dependencies. ^[inferred]
+ New source: papers/survey-2026.pdf

Proposed deletions (-):
- The attention mechanism was first described in [Bahdanau 2015].  (to be replaced by updated claim)

⚠️  Conflict check: live_revision no longer matches what was staged against. Review carefully.

Accept [a], Reject [r], Skip [s], Preview full diff [p]?
```

If `--all` flag is set, skip prompting and accept every file.
If `--reject-all` flag is set, skip prompting and reject every file.
If `--list` flag is set, stop after printing the inventory (Step 1).

## Step 3: Apply Decisions

The moves are mechanical and the CLI does them atomically. Pass the revisions from Step 1 so a decision made on stale information fails loudly.

### Accepting a new page

```bash
obsidian-wiki staging promote <staged_path> \
  --expect-staged <staged_revision> --expect-new
```

`--expect-new` refuses if a live page has appeared since you listed — someone else got there first.

### Accepting an update

```bash
obsidian-wiki staging promote <staged_path> \
  --expect-staged <staged_revision> --expect-live <live_revision>
```

### Rejecting a file

```bash
obsidian-wiki staging discard <staged_path>
```

It lands in `_raw/rejected-<category>-<page>.md` for manual editing. An earlier rejection of the same page is never overwritten — the second becomes `-2`.

### Accepting a patch

`promote` refuses `.patch.md` files, because merging a human-readable diff into a page whose surrounding text may have moved is judgment, not a rename. Do it yourself:

1. Read the target page and the patch.
2. Apply the `+` additions and `-` deletions **as a merge** — never overwrite the page wholesale.
3. Bump the target's `updated` frontmatter.
4. `obsidian-wiki staging discard <patch staged_path>` to clear the patch from the queue.

### When the CLI reports a conflict

Exit code **9** with `conflict: ...` on stderr means the staged or live file changed after you listed it. Nothing was moved. Do not retry with fresh revisions blindly — re-run `staging list`, show the user what changed, and ask again. The whole point of the check is that the content they approved is no longer the content that would land.

`index.md` is updated by the ingest that staged the page, so promotion does not touch it. `log.md` gets one `STAGE_COMMIT` line per invocation, written by the CLI.

## Step 4: Update Tracking Files

The CLI appends the `STAGE_COMMIT` line to `log.md` itself. After processing all staged files, reconcile the index and hot cache so the promoted pages appear:

```bash
obsidian-wiki memory sync --takeaways "Committed N staged pages; rejected M."
```

(No `--verb`: the log line was already written by `staging promote`.) Never hand-edit `index.md`, `log.md`, or `hot.md` — the command takes the lock that keeps a parallel writer from dropping your update.

## Step 5: Report

```
Stage commit complete.

✅  Accepted (N):
  concepts/attention-mechanism.md     → now live
  entities/andrej-karpathy.md         → now live
  concepts/transformer-architecture.md → updated (patch applied)

❌  Rejected (M):
  skills/fine-tuning-llms.md          → moved to _raw/rejected-skills-fine-tuning-llms.md

⏭️  Skipped (K):
  references/attention-is-all-you-need.md → still in _staging/

Staging queue: K files remaining
```

## Notes

- Staged files use the same page template as live pages — they are ready to land, just awaiting approval
- Patch files use a human-readable diff format: lines starting with `+` are additions, lines starting with `-` are deletions. `staging promote` refuses them — merge them yourself (Step 3)
- `index.md` and `log.md` are always updated immediately on ingest (they are low-risk tracking files) — only category pages go through staging
- The moves live in `obsidian_wiki/staging.py`; this skill supplies the judgment, not the file handling
- The `_staging/` directory is not tracked by Obsidian's graph view — pages only appear in the wiki after promotion