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:

obsidian-wiki staging list --json

Each entry carries:

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

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

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

Rejecting a file

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:

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