# Knowledge Update Protocol

Two audiences need this file: the CA using the chat (what typing `UPDATE KNOWLEDGE` actually does) and whoever builds/maintains the website backend (what has to exist for that command to be real, not just a nice sentence in the prompt).

## 1. Conversational flow (what the user experiences)

1. User types `UPDATE KNOWLEDGE`, `NEW NOTIFICATION`, `AMENDMENT`, `NEW RATE`, `NEW STANDARD`, `NEW CASE LAW`, `NEW CIRCULAR` — or pastes/uploads an official document.
2. The agent (per core prompt §7) extracts, from the supplied material:
   - Effective date
   - Applicability (entity types, jurisdiction, transaction types)
   - What it supersedes (old position + old source reference)
   - Exceptions / carve-outs
   - Transitional provisions
   - Practical implementation consequence (what changes for a user relying on the old position)
3. The agent presents this extraction back to the user as a **proposed knowledge entry** (matching the schema in `schema.md`) and explicitly asks for confirmation before it is treated as authoritative — especially if the source looks unofficial, incomplete, or ambiguous.
4. On confirmation, the entry is written to the knowledge store and a changelog row is appended (schema in `schema.md` §2).
5. The agent should **not** claim the update is "live everywhere" unless your backend actually persists it — see §2 below. If this session has no write access to the store, the agent should output the structured entry/changelog text and tell the user to have it saved into the knowledge base (i.e., don't let the model pretend a write happened when it didn't).

## 2. What the backend must actually provide

The chat model cannot maintain persistent state on its own. For `UPDATE KNOWLEDGE` to be a real capability rather than theater, the website backend needs:

- A **knowledge store** (per `schema.md`) with write access from a controlled path — ideally a human-reviewed queue (agent proposes → staff approves → entry goes live) rather than direct unreviewed writes, at least for anything above STATIC category.
- A **retrieval step** before every chat completion that pulls matching entries and assembles the `<knowledge_context>` block (see `schema.md` §4).
- A **changelog table** that's append-only, so you can always answer "what did we believe before, and when did that change."
- Optionally, a **review queue UI** for staff to approve/reject/edit agent-proposed entries before they go live — strongly recommended for anything that will drive a filing, a rate, or a deadline.

If none of this exists yet, the agent should behave exactly as instructed in core prompt §7/§14: extract and structure the update, but tell the user plainly that persistence isn't wired up yet, rather than implying it remembered something it can't actually remember past this conversation.

## 3. `CHECK FOR CHANGES` flow

- If the deployment has live web access (a search/fetch tool wired to the agent, or a scheduled backend job that periodically re-checks entries against primary sources): use it, and report exactly what was checked, against what source, and what (if anything) changed.
- If no live access exists in this session: produce a **targeted verification checklist** — the specific entries/topics that are FREQUENT or HIGHLY_TIME_SENSITIVE and are relevant to the current matter, each with the exact question that needs checking against a primary source (e.g. "confirm whether the Finance Act for AY 2027-28 changed the TDS threshold under §194J from its FY 2025-26 level"). Do not silently assume nothing changed.

## 4. Suggested automated staleness job (backend, not chat-time)

Run on a schedule (e.g. nightly or weekly):

1. Select all entries where `category IN (FREQUENT, HIGHLY_TIME_SENSITIVE)`.
2. For entries older than the staleness threshold (`schema.md` §5), either auto-fetch from a configured primary-source URL (if the entry has one and your backend has fetch capability) or flag `verification_status = stale_needs_recheck` for human review.
3. Log the sweep result as a changelog entry with `source = "automated staleness sweep"`.

This keeps the knowledge layer honest without requiring a human to remember to check every rate manually — but note the *sweep itself* should not silently rewrite a value without either a verified source fetch or human confirmation; auto-flagging stale is safe, auto-rewriting is not.

## 5. Manual entry — minimum viable version

If you're starting with no backend automation at all, the minimum viable version of this whole system is: a single JSON file (`knowledge-index.json`, following `knowledge-index.example.json`) that you edit by hand whenever a rate/rule changes, loaded in full or filtered into `<knowledge_context>` at request time. That's enough to get the currency-discipline benefit immediately; the review queue and staleness automation in §2/§4 are upgrades you can add later without changing the core prompt or the schema.
