--- 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 \ --expect-staged --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 \ --expect-staged --expect-live ``` ### Rejecting a file ```bash obsidian-wiki staging discard ``` It lands in `_raw/rejected--.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 ` 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