emergent-security/docs/knowledge-maintenance.md

# Publish, load, refresh, and roll back security knowledge

Install from this trusted repository with `pip install -e '.[test]'` or a wheel
built from the reviewed revision. `emergent-knowledge list` lists cards.
`emergent-knowledge show start --audience codex --json` gives a self-contained
orientation receipt. Use `claude`, `grok`, or `generic` for other adapters.
Place `--repositories /path/to/checkouts` before the subcommand for source checks.
This command hashes only the explicitly inventoried owner files; it never emits
their contents, reads credentials, connects to an API, or requests a grant.

The explicit bundle root (`--bundle`) must come from a trusted release source.
`release.yaml` hashes detect accidental drift; they do not authenticate a
malicious bundle that brings its own hashes. Git/release provenance and owner
review establish trust. Knowledge and prompts are not enforcement boundaries.

## Loading contract

Use one of `knowledge/adapters/{codex,claude,grok,generic}.md` in the owning
session's approved entry point. This repo installs its own AGENTS.md/CLAUDE.md
pointers. No global files, permissions, model defaults, hooks, credentials, or
other repositories' instructions are changed by installation or retrieval.

Require a fresh-session proof that startup and deeper cards were actually read.
An instruction file's existence is insufficient. Record provider/client/model,
loading mode, package digest, scope resolution and source state. Reload on
resume/compaction, provider switch or repository change. Never store private
tenant context in shared receipts. Explicit bootstrap is a supported fallback:
pass the rendered receipt through the client's supported context interface and
label it accordingly; do not call it automatic discovery.

Current provider source references (checked 2026-10-03):

- [Codex AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md):
  instruction discovery is scoped to the actual session's directory hierarchy.
- [Claude memory](https://code.claude.com/docs/en/memory): CLAUDE.md and supported
  AGENTS.md discovery depend on client configuration; imports load referenced text.
- [Grok instruction compatibility](https://docs.x.ai/build/features/skills-plugins-marketplaces):
  Grok Build supports AGENTS.md and Claude instruction files. Verify installed behavior.

These are loading contracts, not promises about unattended execution. Do not
change a blocked glas-harness profile to make a knowledge test pass. Its current
README labels local profiles blocked and remote proof routes unverified. A
direct-client probe does not prove a governed harness session.

## Release checks and limits

Run `python3 -m pytest -q`, `python3 tools/seal_knowledge.py --check`, and
`emergent-knowledge --repositories /path/to/checkouts check`.
Startup content is capped at 5,500 UTF-8 bytes (measure actual provider tokens
in session evidence; bytes are not an exact token count). Deeper cards are
requested by stable ID; no free-form path or tenant query is accepted.

Only reviewed estate-general summaries are distributed. No tenant/private
cards are supported, even if a caller supplies a tenant label. The provider is
chosen from each card's allowlist. Data must be reviewed for its destination
before adding a source or card. Tests reject private cards, path escapes,
symlink escapes, duplicate YAML, tampering, and unreviewed source references.

Verified-file status proves agreement with inventoried bytes, not service health,
authorization, or owner assent. Source changes, withdrawal, supersession and
review expiry withhold the affected card. Missing checkouts/connection leave a
dated offline snapshot; it must not be used to establish current permissions.
An offline bundle cannot learn a withdrawal that happened after its last update;
its review deadline bounds that blind spot, and effects always require the
current owner's authorization path.

## Refresh ownership

From 0.2.2, each retrieval, check and public source-status call revalidates the
loaded release seal and package files. Returned cards use the exact bytes
validated against that seal. A changed seal invalidates the loaded object:
explicitly reload the reviewed bundle rather than silently following an update.
Unsealed file changes fail closed. This detects local bundle changes; an offline
bundle still cannot discover an upstream withdrawal it has not received.

Emergent Security maintains the package and tests. Every source remains owned
by its repository; gate-house/net-kingdom adoption and publication review are
tracked in EMERGENT-WP-0002-T02/T09, not presumed accepted. Review at least every
30 days and immediately on relevant owner/source, boundary, capability or scope
changes. A digest mismatch is an investigation trigger, not an auto-update job.

1. Read the changed source and its owner decision/evidence. Resolve conflicting
   claims; keep unknown or missing capabilities explicit.
2. Update the relevant cards and source revision/digests in `sources.yaml`, with
   last_verified/review_after dates and any lifecycle/supersession markers.
3. Review provider disclosure classification; never snapshot raw credentials or
   tenant documents. Bump catalog version for a changed distributed package.
4. Run tests and provider scenarios affected by the change. Then seal with
   `python3 tools/seal_knowledge.py` and inspect the manifest diff.
5. Commit, push and sync work records with Repo Manager. Publish the exact
   reviewed artifact and retain its digest and evaluation evidence.

`python3 tools/export_knowledge.py /new/directory` exports only sealed knowledge
files plus the release manifest, without overwriting a destination. The CLI can
read that bundle with `--bundle`. For rollback select the prior reviewed bundle
explicitly; recheck source freshness. Never roll back to restore withdrawn or
expired guidance. No recurring service, scheduler or fleet broadcast is installed.

## Evidence and rollout gates

`tools/probe_provider.py` creates read-only, instrumented disposable knowledge
fixtures. Per-run random markers test actual startup and deeper reading; they
are not secrets or part of the release. Raw client diagnostics remain private
under /tmp; publish only reviewed answers and minimal session metadata.
Before creating a fixture or launching a provider, the runner validates all
offered cards against sibling owner checkouts. Set `--repositories /path/to/checkouts`
to select their parent explicitly. A changed, missing, withdrawn or expired
source produces a `source-withheld` receipt and exit code 2 without a provider
launch. Repository pilots validate both `start` and their scenario card using
`--root`. A verified task card cannot bypass a withheld startup card. These
checks establish source-file freshness only; the instrumented copies still do
not establish governed-session readiness or renew old provider evidence.
Expected scenario outcomes are in `tests/fixtures/knowledge/scenarios.yaml`.
Review meanings, citations and recommendations, not string similarity alone.
Any unsafe recommendation blocks release. Missing or failed provider sessions
remain explicit gaps. Owner assent, independent adversarial review, actual
repository pilot sessions, and a verified provider matrix are rollout gates.

An acknowledgment proves reach, not understanding. Authorized standing notices
use the existing Statehub mechanism and reference the exact package; they do
not grant authority. Full rollout remains a workplan task until its evidence
exists. A non-normative local pilot is not fleet adoption.