# 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`](../../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 |
```