Knowledge Ops

Knowledge Operations

<skill_contract> <input>Vault root, operation, scope, canonical-store rules, permissions, destination, and execution budget.</input> <output>Verified classification, retrieval, deduplication, synchronization, audit, or governed promotion changes with receipts.</output> <done>Canonical Markdown remains authoritative, provenance and immutability are preserved, and representative checks pass.</done> <non_goals>Using vectors as canonical storage, silent provenance merges, automatic semantic rewrites, or one-signal rule promotion.</non_goals>

Operate the wiki as durable disk and governance layer. Markdown pages hold understanding and provenance; indexes, memory, vectors, and dashboards are replaceable access paths.

Usage Template

Provide: vault root, operation (organize, deduplicate, retrieve, sync, audit, promote), scope, destination, permissions, and budget. Load references/storage-governance.md only when designing layers or promotion queues.

Workflow

<intake>

Resolve configured paths and identify the canonical store, immutable sources, active execution truth, optional retrieval indexes, and governance queues. Record file counts, scope, and write authority before mutation.

</intake>

<unknowns_gate>

If canonical ownership, vault identity, or merge authority is ambiguous, return NEEDS_INPUT. Treat semantic similarity as a review signal, not proof that two notes or sources are equivalent.

</unknowns_gate>

<execute>

knowledge-ops owns cross-corpus organization, identity reconciliation, retrieval/index state, promotion queues, and knowledge-debt governance. It does not replace wiki-ingest as the owner of a single source-to-candidate transaction, and it does not replace wiki-lint as the read-only health auditor.

1. Classify: assign each item to execution state, quick memory, durable wiki, optional retrieval index, or governance state.
2. Search first: exact path/title, wikilinks, canonical URL/source id, and lexical search before semantic retrieval.
3. Deduplicate: compare source identity, normalized URL, hash when available, claims, and provenance; merge compiled notes only with traceable reasons. Under concurrent writers, stage the candidate, acquire or verify one source identity key, and recheck immediately before and after promotion.
4. Store: write to the canonical Markdown layer, update indexes/maps, preserve immutable sources, and queue unresolved debt.
5. Retrieve: return paths and match reasons; load only the top evidence-bearing pages within context budget.
6. Sync: update optional indexes from canonical files and record indexed, skipped, removed, or failed items.
7. Verify: read after write, check links/source refs, rerun exact-identity search, and run representative retrieval queries. If a race produced two candidates, keep one canonical source, repoint derived locators, and emit a reconciliation receipt without rewriting prior evidence.
8. Promote: require two durable supports or one strong source plus local verification, a bounded execution contract, preserved approvals/provenance, and a cheap objective check.

Use idempotency keys for machine append operations: derive the key from operation, canonical source identity, target, and run/batch id; append only when the key is absent. Repeated schedules and retries must converge to the same canonical files and one logical receipt.

Automate deterministic counts and index refreshes only. Semantic rewrites, contradiction resolution, and rule promotion remain supervised.

</execute>

<evaluate>

Compare pre/post counts, inspect merge samples, replay retrieval queries, and verify no immutable source changed. A sync is partial if any canonical file is unindexed; retrieval quality is unproven without representative queries.

</evaluate>

<state_contract>

Persist {run_id, status, attempt, budget, evidence, unknowns, last_error, next_action} plus canonical paths, operation scope, source identity/idempotency keys, writer lease or compare-and-set evidence, file ledger, merge/reconciliation decisions, debt queues, index receipts, retrieval tests, and promotion candidates. Keep source and merge history append-only.

</state_contract>