maintain-contract
The workflow contract for any agent that ingests, retrieves from, or maintains a claude-wiki-pages vault. Documents the safe ordering — ground → judge → verify — checkpoint discipline, retrieval groun
SKILL.mdskills/maintain-contract/SKILL.md
GitHubMaintain contract — how to drive the wiki safely
This is the procedure any agent (this plugin's or a third party's) follows to
operate on a vault without corrupting it. It pairs with
/claude-wiki-pages:engine-api, which documents the tool surface this contract sequences.
The three invariants
- Ground, then judge, then verify. Compute facts with the engine (verify, fix, and the planned link-suggest/search) before reasoning. The LLM makes only judgment calls — topic placement, prose, what to synthesize — over engine-computed facts, never from memory. Close every write with
verify/heal. raw/is immutable. Never write, move, or delete anything undervault/raw/. Sources are the provenance anchor. Theprotect-rawhook enforces this; do not fight it.- Git is the safety net, not approval. Self-heal is automatic. Before structural changes, a checkpoint commit is written; rollback is
git revert <healCommit>. Do not prompt the user for permission to fix structure. Write phases that happen outside the engine (ingest writes, judgment fixes, polish) are bounded the same way:snapshot.sh prebefore the phase,snapshot.sh postafter it, and theSubagentStopcommit backstop sweeps up anything left dirty — no LLM write escapes git coverage.
Ingest (add knowledge)
snapshot.sh pre— checkpoint the pre-write state. 2. Read each source inraw/completely. 3. Write cited wiki pages (sources:as[[wikilinks]]to_sources/summaries), thensnapshot.sh post --label "ingest …". 4. Runengine.sh heal— it checkpoints, then verify→fix→re-verify, then commits. 5. Surface only what needs editorial intent (ambiguous merges, deletions).
Retrieve (answer questions)
- Use grounded retrieval (engine
search, orgrepoverwiki/untilsearchships) to fetch candidate pages. 2. Answer only from those pages. 3. Cite every claim with the[[Page Title]]it came from. 4. Never invent a citation; if the wiki cannot answer, say so.
Maintain (keep it healthy)
engine.sh verify --jsonto diagnose. 2.engine.sh heal --jsonto repair the structural-error subset under a checkpoint. 3. Apply judgment fixes (restructures, merges) automatically under the same checkpoint. 4. Re-verify; iterate within the engine's cap; surface residual editorial items.
Hard rules (never violate)
- Never create a
[[wikilink]]to a non-existent page, and never create a stub just to satisfy a broken link. - Never forge provenance — do not edit
sources:to manufacture a citation. - Never delete page content; connect orphans instead.
- Always read
vault/CLAUDE.mdfirst — it is the authoritative schema and wins any conflict.
Multi-vault operating rules
When more than one vault is registered, every engine call must be explicitly scoped. These rules
are derived from ADR-0009 and
ADR-0016; the enforcement
mechanism is the firewall twins (scripts/firewall.sh + src/core/firewall.ts) and the registry
reader (scripts/resolve-vault.sh).
Rule 1 — Always target the active vault.
Pass --target <active-vault-path> to every engine call. Never omit --target when a registry is
configured; the engine resolves the vault independently and may not agree with the hook's resolved
path if the registry has changed between calls.
Rule 2 — Pass --other-vaults from the registry for confinement.
scripts/resolve-vault.sh exports registry_other_vaults — the registered vault roots minus the
active one. Pass that set as --other-vaults to the engine's firewall command so both the bash
twin and the TS twin enforce the cross-vault deny rule with the same root set. Do not hard-code
vault paths; derive them from the registry at call time.
Rule 3 — Reads from a non-active registered vault are permitted.
An agent may read files (via Read tool or grep/Glob over a non-active vault path) when a
cross-vault comparison is needed. Read operations are not governed by the firewall write-confinement
boundary. No engine flag is required for reads.
Rule 4 — Writes to any non-active vault are firewall-BLOCKED regardless of --other-vaults.
The cross-vault deny rule fires before the allowPaths check (ADR-0009 precedence:
deny → cross-vault → vault → allowPaths → outside-vault). Passing --other-vaults does not
grant write access — it provides the root set the firewall uses to identify and block cross-vault
writes. No firewall.allowPaths entry can override a cross-vault block. To write to a
different vault, first switch the active vault via scripts/set-vault.sh switch <path>.
Rule 5 — A malformed or inconsistent registry resolves FAIL-CLOSED (zero writable roots).
If registry_other_vaults (scripts/resolve-vault.sh) exits non-zero — because the registry JSON
is malformed or current_vault_path ∉ vaults[] — the firewall maps this to zero writable roots:
neither the active vault nor any other vault is writable until the registry is repaired. This is
not an error to work around; it is the security posture mandated by ADR-0016 (PM.2/N4). The
fail-closed signal is an exit code, not a stdout sentinel; the __FAIL_CLOSED__ token lives only
inside scripts/firewall.sh. Run bash scripts/set-vault.sh list to diagnose the inconsistency.
Specification anchor
Contracts: docs/architecture.md (command & agent contracts), SECURITY.md (security model).