# Ownership, review and keeping it current

A context file that was right in March and wrong in October is worse than a missing one: the agent trusts it. Maintenance is the main cost of the kit, so plan it before the first draft.

## Who owns what

- The people who own a business definition approve its meaning. Operations or data teams maintain packaging, versioning and retrieval. An engineer can encode a rule; an engineer cannot decide what the company means by a qualified opportunity.
- Typical split (one person can hold several roles in a small team, but each role is named):
  - `stack.md`: marketing operations or the martech lead owns; each tool's owner confirms their own entry.
  - `naming-rules.md`: marketing operations owns; the analytics lead approves event and property rules.
  - `metrics.md`: one business owner and one technical owner per metric; the file owner keeps the format.
  - `data-dictionary.md`: data or analytics engineering owns; source system owners confirm their entities.
  - `tracking-plan/`: the analytics lead owns the index; each contract carries its own owners.
  - `decisions.md`: whoever made the decision writes the entry; the file owner checks format.
- A conflict between revenue pressure and customer commitments, or between two departments' definitions, goes to the person named in the index as tie-breaker.

## Review cadence (defaults)

Adjust to how fast each area changes; write the chosen cadence into each file header.

- `stack.md`: monthly drift check, plus every trigger below.
- `naming-rules.md`: quarterly, and when a new channel, agency or ad platform is added.
- `metrics.md`: each metric block carries its own `last_reviewed` and `review_by`. Quarterly by default, and on any trigger. A metric used in board reporting is reviewed before each board cycle.
- `data-dictionary.md`: on schema or property changes, otherwise quarterly.
- `tracking-plan/README.md`: on each tracking release.
- `decisions.md`: no review; append on each decision, release and incident.
- `README.md`: whenever a file is added, renamed in meaning, or changes owner.

## Stale files: decision rules

- Reporting and investigation, `review_by` passed by up to 30 days: use the file, and say in the answer that the source is due for review.
- Reporting and investigation, more than 30 days past, or the owner role no longer exists: use the file only for drafts and investigations; for numbers that will be reported, ask the owner to confirm the definition first.
- Actions (a send, an audience sync, a bid or budget change, a lifecycle update): any rule past `review_by`, or with `status: draft`, blocks the action until the owner confirms it. The 30-day grace period never applies to actions.
- `status: draft` or a fact marked inferred: never present it as the approved definition.
- Two current definitions found (in the folder, or the folder against a dashboard or semantic layer): stop and ask the owner. Do not choose by recency.

## Change triggers

Any of these starts a targeted update, regardless of cadence:

- A tool is added, replaced, migrated or removed, or a contract ends.
- A new property, container, stream, ad account, workspace or warehouse dataset is created, or one is retired.
- A consent model, CMP or region scope changes.
- Pricing, plans, packaging or lifecycle stage definitions change.
- A reporting setting changes that applies only going forward. The GA4 property `timeZone` is one: a change splits the series, so it needs a dated decision entry.
- An agency or internal owner changes. This also starts an access review: for each account the agency touched, record who owns it and which company roles hold admin (see "Account ownership" below), and log the review in `decisions.md`.
- A data incident is found, or a metric dispute is settled.
- A vendor renames or retires a product or API version. Example checked on 2026-10-17: Fivetran's migration FAQ says Census workspaces and Activations API V1 retire on 15 January 2027, Census is now Fivetran Activations, and syncs are now activation syncs. A stack that names Census needs a dated entry, new names in `stack.md`, and the API version in use recorded.

## Update routes

- Targeted update: all files exist and one trigger above is named ("we replaced Segment with RudderStack", "the CAC dispute is settled"). Scope the evidence collection to the affected tool or metric, apply the tool change procedure below, scan, propose, get approval, record a `decisions.md` entry, and rerun the context tests that touch the changed files. Do not re-read or re-check the rest of the stack.
- Refresh: a `review_by` date has passed or the monthly check is due. Re-collect evidence, run both drift checks below, scan, propose, get approval, record, rerun the tests.
- Both routes end with a `decisions.md` entry naming the approver and the new version of each changed file. A change without that entry is not active.

## Drift check: stack

Run monthly for `stack.md` and on every tool trigger.

1. Re-run the repo scan and re-read the latest exports (`references/repo-and-export-signals.md`).
2. Compare with `stack.md`. Classify each difference:
   - in code or export, missing from `stack.md`: new or undocumented tool;
   - in `stack.md`, no longer in code or export: removed, moved to another loader, or only in a non-scanned surface;
   - identifier changed: new container, property or account;
   - same tool, second sender found: potential double counting.
3. For each difference, propose the edit and the decision or release entry, with evidence. Do not edit on inference alone.
4. Set `last_verified` on each confirmed entry.

## Drift check: definitions

The stack check finds new and removed tools. Wrong agent answers more often come from definitions that changed under the same name. Compare the deployed state, not a branch: a `dbt_project.yml` on a feature branch is not production, and a GTM workspace is not the live container.

Per source:

- HubSpot: the property export, or the properties read (the MCP `get_properties` tool or the CRM properties API, path checked live). Compare internal name, type, options and archived state with `data-dictionary.md`. A label-only change is reviewed separately, because it changes what people see but not joins. A new property with usages and no dictionary entry becomes an open item.
- GTM: the published version, from the container export or `versions.live` under the read-only scope. Diff event names against `tracking-plan/` and tag and trigger names against `naming-rules.md`. Write the version number into the `decisions.md` release log.
- dbt: `manifest.json` and `semantic_manifest.json` from the last successful production job run, not a local compile. Compare metric and semantic model names with each `metrics.md` implementation pointer. A changed expression goes to the metric's business owner as a question; never edit the contract to match the code.
- Mixpanel Lexicon or Segment Protocols export: events with no contract go to "Events observed but not in the plan" in `tracking-plan/README.md`.
- UTMs: re-measure naming compliance (distinct and traffic-weighted, as in the naming rules template).

Baseline:

- Keep the accepted baseline as a dated, definitions-only snapshot: the export file name and version, or a hash of it, referenced from `stack.md` under the tool's `Last verified` line. No customer rows.
- Classify each difference: missing reference (the code names something the context does not), structural change (type, options, expression, grain), or meaning question (same structure, the business owner must confirm the meaning still holds).

Scheduled runs:

- A drift check that runs on a schedule gets read-only source credentials and pull-request-only repository rights behind branch protection. It opens a proposal; it never merges.
- After a merged change, rerun the affected context tests before the change counts as active.

## Tool change procedure

- Adding a tool: entry in `stack.md` with status `active` from the go-live date, decision entry with the reason, release log entry, data flows, and the owner. If it creates new metrics or properties, update `metrics.md` or `data-dictionary.md` in the same change.
- Replacing a tool: both entries exist during the overlap with dates; record which one is authoritative for each metric from which date; metrics that change source get a new version or a documented bridge.
- Removing a tool: status `retired` with the date; keep the entry so historical questions still resolve; list dashboards, syncs and skills that depended on it.
- Migration between vendors: record identifier mappings (old property to new, old event names to new) in `naming-rules.md` with cutover dates; never let one metric count both sides of the overlap.

## Account ownership

At an agency or owner change, the usual production failure is that the tag manager account, analytics account, ad account or ad business portfolio belongs to the agency's organisation, or no company role holds admin. History and access then leave with the agency.

- Each tool block in `stack.md` records who owns the account (company or agency), how many company roles hold admin, what it is linked under (a Google Ads manager account, a Meta business portfolio, called Business Manager in the API docs) and who owns that, and when access was last reviewed.
- Detect: an ad account linked only under the agency's manager account, or an analytics or tag manager account where no company role is an administrator. Record it as an open item for the business owner.
- Fewer than two company-held admin roles on any account is an open item.

## Versioning and superseding

- A metric ID carries its version as a suffix: `cac_new_paid_v1`. The base name (`cac_new_paid`) never changes.
- A correction that restores the agreed meaning keeps the ID and gets a changelog line.
- A change in meaning gets a new suffix (`cac_new_paid_v2`), an effective date and a stated historical treatment (restate, keep both series, or bridge). The ID change is deliberate: every dashboard, contract and agent that cites the old ID now visibly points at an archived definition.
- Move superseded definitions to an `## Archive` section at the bottom of the same file with `effective_to`. Keep them out of the active section so retrieval does not find two current definitions.
- An exception for one account or campaign gets a scope and an expiry date. It never quietly becomes the default rule.

## Vendor AI context copies

Several tools now hold their own business context for their agents. Treat each as a derived copy of the folder, listed in `stack.md` with its source file, version and date copied.

- Mixpanel Business Context (checked 2026-10-17): organization level under Settings, Org, AI Settings, Company Context, and project level under Settings, Project, AI Settings, Project Context; project context wins on conflict; 50,000 characters each. The MCP tools are `Get-Business-Context` and `Update-Business-Context`, and an update is a full replace. Always read the current text first, merge, show the diff, and get approval before writing.
- Amplitude AI Context (checked 2026-10-17): Project Settings, AI Controls; organization and project text, 10,000 characters each, project wins on conflict. `get_amplitude_context` returns the text instructions but not uploaded files, so rules that MCP clients need go in the text.
- HubSpot Context Home, Fivetran Context Layer (Public Preview on 2026-10-17, with plan, destination and region prerequisites) and dbt Labs' Agents Schema (an `AGENTS` schema in the warehouse) are other delivery routes. Check current availability live before planning around them.

Building a copy:

1. Start with the line: "Source: martech-context metrics.md <metric IDs>, file version <n>, copied <YYYY-MM-DD>. The canonical copy in the repository wins on conflict." Staleness is then visible from inside the vendor tool.
2. Add content in this priority until the vendor's limit is reached: approved metric definitions from `metrics.md` that the tool can compute; misleading fields and join hazards from `data-dictionary.md` that apply to the tool's data; naming rules relevant to that tool.
3. Leave out credential locations, owners' personal names, open items and anything from the exclusion list.
4. Show the full text and, for an existing copy, the diff. The owner applies it or approves the write.
5. After any change to a canonical file, list the copies derived from it and propose updates. A vendor copy older than the canonical version is a known failure: the vendor's agent answers with last quarter's definition.

## Maintenance budget

A planning estimate, not a benchmark: about ten hours to agree, map, test and assign ownership for one workflow's context, then about three hours a month (30 minutes a week on disputed answers, one hour a month on definitions and dependencies). If the team cannot give one workflow that time, narrow the scope until ownership is credible.