Project Modeling

Phase 2. Builds the one model that all 23 documents are views over, and the vocabulary they all use.

Iron Law

ONE MODEL, MANY VIEWS. If a view needs a new fact, the fact goes in the model first.

The moment a document invents a component name, an owner, or a boundary that the model does not carry, the package has two models. It will not notice, and the contradiction surfaces during diligence rather than during drafting.

What the model contains

Element	Captures	Where it surfaces
Product intent vs implemented behaviour	What it is for, and what it actually does — separately	01-project/
Actors, journeys, roles, permissions	Who does what, and what they may do	01-project/, 02-architecture/
Components and deployment units	Purpose, owner, runtime, interfaces, state, criticality	02-architecture/components-and-codebase.md
Interfaces and contracts	Producers, consumers, transport, versioning	02-architecture/interfaces-and-integrations.md
Data and its lifecycle	Stores, classes, residency, retention, deletion	02-architecture/data-and-ai.md
Infrastructure and environments	Topology, promotion path, differences between environments	02-architecture/infrastructure-and-deployment.md
Boundaries	Control, data, trust, failure, tenancy	Everywhere. The most load-bearing element
Owners and decision rights	Who owns, who decides, who escalates	00-control/terminology-and-ownership.md
Lifecycle and target state	What exists now vs what is planned	Every document, kept visibly distinct
Assets, dependencies, licenses, risks	Provenance and exposure	05-due-diligence/

Every element is an evidence-backed claim. A component with no evidenced owner is unassigned — never the last committer, never the most active contributor. During an incident, a fabricated owner is worse than an admitted gap.

Classify first

Classify the project from evidence before modelling it, and record the classification with its supporting evidence IDs. The classification changes which elements carry weight — not which files exist. See references/project-type-adaptation.md.

Do not force web-service assumptions onto a library, a model, a device, or an offline tool. A library's "deployment" is a registry publish; a device's "rollback" may not exist at all.

Test the model against three flows

A model that has not been walked end to end is a diagram, not a model. Trace at least:

1. One primary user or business flow — entry point through to the effect the user cares about
2. One change-to-production flow — commit through test, review, build, deploy, and rollback
3. One credible failure, recovery, or abuse flow — a dependency outage, a partial failure, a malicious input, or an incident from alert to recovery

Where one is genuinely inapplicable, substitute a different flow and explain why — never silently drop it. A project with no deployment still has an artifact-publication flow; a project with no users still has a consumer.

Each trace either confirms the model or produces a gap. Both outcomes are valuable; only the first is comfortable. Trace failures become AQ- or CT- rows before any drafting begins, because a model corrected in Phase 2 costs one edit and a model corrected in Phase 6 costs a rewrite of everything downstream.

These same traces are what verification pass B later attempts to falsify. Record them explicitly so the pass can execute them independently rather than inventing its own.

Canonical names

Every entity gets one authoritative name in TM-####, plus its aliases. Aliases are not noise — source material genuinely uses old names, and a reader who greps for the old one must land somewhere.

Name these classes: product and project; components, services, modules, repositories, packages; user, customer, administrator, and operator roles; environments and deployment units; external systems and partners; data classes and domain entities; interfaces and events; owners and teams.

Once recorded, the canonical name is used in all documents. A document that calls the same service by two names inside one file is a Medium finding; two documents disagreeing is a High one, because a reader cannot tell whether they describe one system or two.

Projecting to views

A view selects and abstracts. It never adds.

Legitimate	Illegitimate
Omitting internal components from a partner view	Renaming a component to sound cleaner externally
Generalizing "PostgreSQL 15 on RDS" to "a managed relational database"	Describing a boundary that the model does not carry
Dropping evidence IDs from public text	Dropping a limitation that made the claim true
Summarizing five failure modes as "degrades to read-only" when that is what all five do	Summarizing them that way when one does not

The public projection has its own rules and its own gate — see disclosure-gating. This skill's obligation is narrower and absolute: the underlying model must be identical across every view.

Current versus target

Keep them visibly separate in the model itself, not just in prose. A model that merges "the planned event bus" with "the current synchronous call" produces an architecture document describing a system nobody has built.

Planned elements carry a planned marker and the evidence for the plan — an approved decision record, not a conversation. A plan with no approved record is R at best and frequently U.

Output Format

Write the model to <outputRoot>/00-control/.project-model.json and the vocabulary to 00-control/terminology-and-ownership.md.

## Canonical Entities

| ID | Canonical name | Class | Aliases | Definition | Owner | Evidence |
|---|---|---|---|---|---|---|
| TM-0001 | {name} | component / role / environment / data-class / interface / external-system | {old names} | {one sentence} | {role or `unassigned`} | [EV-####] |

## Ownership

| Area | Component owner | Decision owner | Operational owner | Documentation owner | Bus-factor concern |
|---|---|---|---|---|---|

## End-to-End Traces

### Trace {N}: {name} ({primary | change-to-production | failure})
| Step | Component | Interface | State touched | Evidence | Confirms or contradicts model |
|---|---|---|---|---|---|

The ownership table's unassigned entries and bus-factor concerns feed 05-due-diligence/ directly. Do not soften them.

Rationalization Prevention

Excuse	Response
"The partner guide needs a simpler name for this service"	Then the canonical name is wrong, or the simplification is a lie. Fix one; do not maintain two.
"I will trace the flows after drafting the architecture"	Then the architecture document is a hypothesis and everything downstream inherits its errors.
"This component has no owner in any file, but Alex touches it most"	unassigned. Commit frequency is not ownership, and paging the wrong person at 3am is a real cost.
"The diagram is clearer if I add this connection"	Every node and edge needs evidence. An inferred connection is labelled inferred, in the internal document, or it is not drawn.
"The team is migrating to the new architecture, so I will document that"	Document what exists, mark what is planned, and cite the approved decision. A target state written as current is a false statement.
"Both names appear in the code, so both are canonical"	One is canonical, the other is an alias. Pick using evidence and record the alias.
"The third trace does not apply to this project"	Then substitute one and say why. Silently running two traces is not running three.

Integration

Invoked in Phase 2 of /dossier:baseline and re-validated by /dossier:refresh when the blast radius touches components, interfaces, data, or infrastructure. Loaded by dossier-pass-b-falsification, which attempts to break the traces recorded here. Every dossier-doc-drafter dispatch receives the model as input.

References: references/project-type-adaptation.md, references/register-schemas.md, references/package-contract-02-architecture.md.