Skip to content

Defining a campaign

A campaign is an entry under the top-level campaigns key, keyed by its id. This page lists every field; the next pages cover each part.

Billing moving to domain-driven design, one bounded context at a time:

campaigns:
billing-ddd:
why: Untangle billing into bounded contexts behind ports.
owner: "@your-org/billing"
scope: src/**
legacy: src/services/** # unclaimed files that count as legacy
perimeter:
marker: "**/context.ts" # each context.ts marks one sector
onTouch: ratchet
phases:
- id: domain
intent: a domain module with no I/O
objectives: [no-io-in-domain]
- id: repository
intent: a repository with a migration
objectives: [has-migration]
- id: backfilled
intent: legacy rows copied and verified
attested: true # no detector sees this; `campaigns attest` leaves it
- id: cutover
intent: the flag and the legacy write path are removed
objectives: [no-legacy-write]
- id: aggregates # open: no objectives yet, so it must be last
intent: Model refunds inside the billing aggregate, or split them out.
objectives:
no-io-in-domain:
holdout: declaration
match:
all:
- path: { file: "/domain/" }
- members: { subject: calls, name: "readFileSync" }
probes: { fires: [{ path: src/billing/domain/a.ts, source: "readFileSync('x')" }] }
has-migration: # the sector is the holdout until one file matches
holdout: sector
sector: { has: { path: { file: "/migrations/.*\\.ts$" } } }
no-legacy-write:
holdout: match
match: { syntax: { pattern: "legacyBilling.write($$$)" } }
probes: { fires: [{ path: src/billing/a.ts, source: "legacyBilling.write(x)" }] }

Only objectives is required.

Field Meaning
title A display name.
why The rationale. Printed by explain and conformance.
how What to do at a holdout. Every finding carries it unless the objective sets its own.
owner Who runs the campaign. Printed in the status table.
scope Globs of the files it sees (default: every file), as graph takes. { path, extensions } also widens the walk. See Sectors.
legacy Which unclaimed files count as legacy. Default: all of them. See Sectors.
perimeter How a sector is recognized. See Sectors.
onTouch What a touched sector owes: advise, ratchet or paydown. See The nudge.
phases The ordered steps. See Phases.
endState Shorthand for the last phase, as a sector-relative node tree. See Phases.
objectives The detectors, keyed by id. See Objectives.
staleAfter How long without progress before the report calls it stalled, such as 14d or 12h. Default: never.
onComplete keep (default; stays as a guard against recurrence) or remove (check fails until you delete it).

The top-level ledger key sets where ledgers are written, relative to the manifest. Default: .architecture-campaigns.

Findings have kind campaign and rule name campaign/<campaign>/<objective>. They are judged against the objective’s ledger, never the baseline.