d3ro-voice/docs/map/12-update-protocol.md

12 — Map Update Protocol (Mandatory)

This is not optional. If a change alters what the product can do, which infrastructure exists, or how developed something is, the map must be updated in the same unit of work. A feature is not "done" until the map reflects it.

The agent obligation is stated in ../../AGENTS.md.

---

1. The rule in one line

Feature change ⇒ map change, in the same commit / PR.

No feature work is complete if docs/map/10-feature-catalog.md (and, when relevant, docs/map/11-gap-backlog.md) is stale.

---

2. When to trigger an update

Trigger on any of these events:

Event	Must update
New feature added on any surface	Feature catalog row (10), surface doc (04–09) if infra changed, remove matching backlog row (11)
Feature changed (behavior, platform coverage, tier, provider)	Feature catalog status/notes, surface doc if interfaces changed
Feature deleted / de-scoped	Flip catalog row to reflect removal (delete row or mark [-] with reason), surface doc cleanup, note in 11 §4 if documentation moved
Feature deferred to backlog	Add row to 11-gap-backlog.md (§1–3) and mark catalog [ ]
Backlog item resolved	Flip 11 row to [x] with date + evidence, update catalog to [x], prune after one cycle
External blocker cleared	Flip EXT-* to [x] with evidence, update the affected catalog rows
New app / package / service / Edge Function / CI workflow	02-infrastructure.md and the relevant surface doc (04–09)
Version bump (release/product-version.json)	00-index.md header "Last full audit", 02 §9
Surface architecture change (new IPC group, new route, new provider)	Surface doc + 03-shared-packages.md if shared

---

3. The update checklist

Run this before declaring any feature task complete:

1. Locate the feature in 10-feature-catalog.md. If it has no ID, add a row with a new ID in the right domain (CAP/AI/MEM/MTG/CV/ACC/TEAM/MON/SHELL/INFRA).
2. Set status per surface (D/W/M/B) using the legend (00-index.md §2). Status is per platform, not global.
3. Add file anchors in the row notes (short path:line where useful) so the next agent can verify.
4. Update the surface doc (04–09) if you added/removed a service, route, screen, IPC channel, table, or function.
5. Update 02-infrastructure.md if you touched build, CI, Docker, deploy, scripts, or release identity.
6. Update 11-gap-backlog.md:
   • Closing an open gap → [x] + date + evidence path.
   • Creating a newly deferred item → new row with ID, gap, evidence, next step.
   • Clearing external blocker → [x] + evidence.
7. Reconcile with the mobile SSOT if the change touches mobile: docs/v3/MOBILE_APP_COMPLETION_SSOT.md remains authoritative for mobile checklist rows. If the SSOT and this map disagree, fix the SSOT first, then this map.
8. Bump the header: update 00-index.md "Last full audit" date only for a full re-audit; for incremental changes update the per-file > Last updated line if you add one.
9. Commit the docs with the code (same commit or same PR), with a clear message.

---

4. Status semantics (do not abuse)

Status	Requires
[x]	Code exists and is verified (tests/evidence in repo or an evidenced manual run recorded in the map/SSOT).
[~]	Code exists but is partial, unverified, or blocked. Say what is missing in the notes.
[ ]	Planned or absent. If planned, ensure a 11 backlog row exists.
[!]	Code is done but "done" is blocked by something outside the repo. Name the external gate.
[-]	Genuinely N/A for that surface. Add a one-line reason.

Never mark [x] to reflect "typecheck passed" alone. Typecheck ≠ runtime ≠ verified feature.

---

5. Ownership & cadence

• Every feature task updates its own rows (no batching).
• Every refactor wave / phase close triggers a reconcile pass over 10 and 11.
• Weekly or per-release do a light sweep: scan for rows whose status no longer matches code; fix drift.
• Per release (release/product-version.json bump) do a full re-audit of 02, 09, and the header dates.

---

6. Anti-drift rules

• Do not create a second feature list elsewhere. This catalog is the SSOT for "what exists and how done".
• Do not describe status in prose only. Use the tables and the legend.
• Do not leave a [~]/[!] row without a note explaining the remaining work.
• Do not add a feature to the product without adding it here.
• If you genuinely cannot determine status, mark [~] and add a backlog row "verify status of X" rather than guessing or leaving it blank.

---

7. Quick templates

New feature row (catalog):

| CAP-16 | Feature name | [x] | [ ] | [~] | [x] | short anchors; what's partial |

New gap row (backlog §1):

| GAP-<AREA>-NN | Area | What's missing | file anchors | Suggested next step |

New external blocker (backlog §3):

| EXT-<SYSTEM>-NN | Blocker | What is needed | where tracked |