# Change Management

> Safe-change governance for this project.

_Governance layer. Verified 2026-07-23. See [`ai-workflow.md`](ai-workflow.md) and [`decision-process.md`](decision-process.md)._

---

## Documentation rules
- **Business-rule changes require KB updates** — update the affected [`../02-business/*`](../02-business/) file and record the decision.
- **Architecture decisions require decision records** — follow [`decision-process.md`](decision-process.md); append to [`../06-history/decisions-log.md`](../06-history/decisions-log.md).
- **New AI actions require permission review** — before adding an agent action or MCP tool, review both gates in [`../03-ai-agents/permissions.md`](../03-ai-agents/permissions.md) and update [`../03-ai-agents/actions.md`](../03-ai-agents/actions.md) / [`tools.md`](../03-ai-agents/tools.md). Note the agent `allowed_actions` enums are **`Unknown - requires confirmation`** against the live spec.
- Docs follow **verified** code — never updated before Review; only affected files change.

## Code rules
- **Do not bypass the service layer.** Pipeline transitions go through the canonical `Startup/InvestorLabelActionService` ([`../02-business/investors.md`](../02-business/investors.md), [`startups.md`](../02-business/startups.md)). Never set `group_id`/status/action directly to fake a transition.
- **Do not bypass policies.** Honor `ActionPolicyService`, `McpAuth` tiers, and Spatie permissions ([`../03-ai-agents/permissions.md`](../03-ai-agents/permissions.md)). Respect the `ai.enabled` flag and `ai.cb` circuit breaker.
- **Understand the existing flow before changing behavior** — read [`../01-architecture/data-flow.md`](../01-architecture/data-flow.md) and reuse existing REST controllers (MCP/agents delegate to them; no duplicated logic).

## Database rules
- **Respect the no-delete rule on the AI/API/MCP surface** — those channels expose no deletion ([`../05-development/database-rules.md`](../05-development/database-rules.md), DR-005). Notes are create/edit-only there; the **admin dashboard** may delete notes (DR-010). Tags are no-delete/no-detach.
- **Preserve audit history** — `ai_activity_logs` is append-only; do not weaken its constraints. Keep `ActivityContext` source tagging.
- **Follow migration conventions** — additive/soft where possible; keep merge-on-insert dedup, dual label keys, and monthly-uniqueness patterns intact ([`../06-history/migrations.md`](../06-history/migrations.md)).

## Shared invariants
- **A business/validation rule enforced on more than one write path must have a single authoritative source.** The same field can be written from the dashboard, the REST API, MCP tool handlers, jobs, and imports — these must not each carry their own copy of the limit/rule.
- Before changing such a rule, **inspect all write paths** and reconcile them to one source (a shared `FormRequest`, rule object, or model constant). **Divergence between paths is a bug**, not a feature (see [`task-classification.md`](task-classification.md)).
- New code must **consume** the single source rather than re-declaring the rule inline.

## Locked decisions (do not silently change)
DR-001 (Numu is the executor; Make = orchestration/AI only) and the other entries in [`../06-history/decisions-log.md`](../06-history/decisions-log.md). Changing one requires a new superseding decision record.