# The work hierarchy and time-log naming

How work is structured, and how that structure shows up in the time
logs we're consuming today.

## Hierarchy: Client → Project → Set → Task

All four are structural — they're real entities that will exist in the
future schema.

### Client
The end party the work is for. See [companies.md](companies.md).

### Project
An ongoing or one-time engagement for a Client, owned by an operator
agency (PlusROI, Bowden Works, …).

### Set
A distinct part of a Project with a **budget** and a **bundle of
related tasks**. Three common patterns:

- **Single-set project** — a one-time piece of work; the project has
  one set, closes when the set completes.
  - Project: **2026 Marketing Plan** · Set: same name.
- **Recurring sets** — a new set per billing period. Each month creates
  a new set with its own budget.
  - Project: **Monthly Marketing** · Sets: `May 2026`, `June 2026`,
    `July 2026`, …
- **Finite sets** — a multi-step project with a known sequence of sets.
  - Project: **2026 Website Rebuild** · Sets: `Design Phase`,
    `Build Phase`, `June Upgrade`.

> **"Phase" is not in the hierarchy.** It's a label someone might give
> a particular Set, typically when the set represents a build-phase
> ("Design Phase", "Build Phase"). The set is the structural unit;
> phase is one of several common naming patterns.

### Task
A unit of work inside a Set. Assigned to a person. Carries:

- An assignee, status, and (usually) a due date or expected timeframe.
- A comp dimension depending on the freelancer's engagement:
  - **hourly**: time entries accumulate against the task.
  - **per-unit**: the task has a value in units.
  - **fixed-price**: the task has a price.

Time entries always reference a task (and through it, the set, project,
and client).

## Other engagements on a project

A project has one operator but many engagements. See
[relationships.md](relationships.md) for the engagement types and the
roles each party plays:

- **Operator** — owns the project, full visibility.
- **Subcontractor** engagements — agencies and people doing the work
  under the operator's direction. The operator is the **Prime** on these.
- **Prime** engagement *above* this project — the operator may itself
  be a Subcontractor to another agency's Prime (McAllister hiring
  PlusROI on Copernic).
- **Referrer** engagements — parties owed a commission.
- **Direct-client** engagement — the end party paying.

Each engagement carries its own **visibility level** on this project
(see [relationships.md](relationships.md#visibility-level) and
[README.md](README.md#visibility-level-proposed)).

> Example: On Copernic, McAllister might see scope + status as Prime
> (or as a Referrer once they're no longer involved in delivery), but
> never the operator's internal cost breakdown.

## Time-log naming convention (in use today)

The current system uses **free-text** strings on each time-entry row
for client + project + description. The convention is:

```
Project field: {Client Name} : {Project Name}
Client field:  {Operator Agency} — either "Bowden Works" or "PlusROI"
```

So in the existing data we see:

| Project (raw) | Client (raw) |
|---|---|
| `The Shore Club : 10 Hour General Support Block` | `Bowden Works` |
| `DaxTech : Website` | `PlusROI` |
| `PlusROI : Admin` | `PlusROI` |
| `Tofino Resort + Marina : Monthly Services` | `PlusROI` |
| `Alcohol Professor : 10 Hour Support Block` | `Bowden Works` |

This means **the "Client" column doesn't name the end client** — it
names the **operator agency** (Bowden Works or PlusROI). The actual
end-client name is embedded in the "Project" field before the colon.
This matters for billing: Bowden Works invoices PlusROI for entries
flagged as `PlusROI` operator, and bills Bowden Works clients directly
for entries flagged as `Bowden Works`.

> Future schema note: when Project, Client (end-client), and Operator
> are all first-class entities, the time entry should reference all
> three independently. The colon-delimited Project string and the
> ambiguous "Client" field are both legacy convenience encodings.

## What this implies for a future schema

When we get past the Clockify-to-Toggl bridge and build a native time
tracker, the entities we'll likely want:

- **`parties`** — people and orgs.
- **`engagements`** — directional working relationships between parties.
  Typed (freelance / subcontract / partnership / referral / …) with
  the two-party roles (Prime + Subcontractor, Referrer + Operator,
  Partner + Partner, etc.).
- **`projects`** — owned by one operator party, references one
  end-client party.
- **`project_engagements`** — which parties touch this project, in
  what role, with what compensation model and visibility.
- **`sets`** — distinct parts of a project, each with a budget and a
  bundle of related tasks.
- **`tasks`** — units of work inside a set. Assignee, status, and
  whichever of `unit_value` / `fixed_price` / hourly-rate applies based
  on the freelancer's comp model.
- **`time_entries`** — references a task. Used for hourly tasks, and
  for transparency on per-unit / fixed-price tasks if the freelancer
  also tracks time.
- **`invoices`** — generated from the project ↔ party engagement +
  the work done in a set.
- **`commissions`** — derived from referrer engagements on revenue
  events.

That's a much richer model than the current `time_entries` table; this
file is the spec we'd work from when the time comes.