fullstack-agentic-flow 2.0.0

package/payload/ai-agents/canon/backend-canon.md

@@ -0,0 +1,295 @@
+# Backend Canon
+
+The one module shape every backend in this pipeline takes, whatever the
+framework. A developer who has read one module in a Laravel repo should be able
+to open a NestJS repo built by this pipeline and find the same things in the
+same places, under the same names.
+
+This file is **pipeline-owned**, not repository-owned. `architecture-context.md`
+§5.0 records *how* this repo maps the canon onto its framework, and at which
+strictness. The canon itself does not change per repo; the mapping does.
+
+Agents that read this file: 00a scaffold, 00b module scaffold, 00 bootstrap,
+02b backend contract, 03a backend sequence, 04a backend implementer.
+
+---
+
+## 1. Why a canon
+
+Framework conventions answer "where does the framework look for a controller".
+They do not answer "where does the rule that an invoice cannot be edited after
+approval live", and every team answers that differently. Readability across a
+consultancy's portfolio comes from answering it once.
+
+The canon is deliberately boring: four layers, one direction of dependency, one
+file per use case, typed data at every boundary. Nothing here is novel. The
+value is that it is the same everywhere.
+
+---
+
+## 2. The four layers
+
+```
+{modules-root}/{Module}/
+├── Domain/            what the business is
+├── Application/       what the system does
+├── Infrastructure/    how it is stored and connected
+└── Interface/         how the outside world reaches it
+    + {Module} registration (service provider, Nest module, app config)
+```
+
+| Layer | Contains | May depend on | Must never |
+|-------|----------|---------------|------------|
+| **Domain** | Entities, value objects, enums, domain errors, domain events, repository **interfaces** (ports), pure domain services | Nothing outside Domain. The language standard library. | Import the framework, the ORM (strict mode), HTTP, the queue, the clock or randomness directly (inject them) |
+| **Application** | Use cases (one per action), input Data classes (commands and queries), output Data classes (results), ports for external services, transaction boundaries | Domain | Build HTTP responses, read the request, know about the view, run raw queries |
+| **Infrastructure** | ORM models (strict mode), repository implementations, query objects, migrations, external API adapters, queue jobs, mail/notification adapters | Domain, Application | Contain business rules. A rule found here is a bug in placement |
+| **Interface** | Controllers, GraphQL resolvers, CLI commands, request-to-Data mapping, presenters/resources, view models (MVC), route definitions, policies/guards | Application (and Domain types for reading) | Call repositories or the ORM directly. Contain business rules. Open transactions |
+
+**Dependency direction is one way**: Interface → Application → Domain.
+Infrastructure implements ports declared in Domain and Application, and is wired
+in the module registration. Nothing depends on Interface.
+
+**The rule that matters most**: *a controller calls exactly one use case.* If a
+controller needs two, there is a use case missing.
+
+---
+
+## 3. Strictness: `strict` or `pragmatic`
+
+Chosen once per repository at scaffold time and recorded in
+`architecture-context.md` §5.0. Agents never mix them inside one repo.
+
+| | `strict` | `pragmatic` |
+|--|----------|-------------|
+| Domain entities | Plain classes, no ORM | ORM models live in `Domain/Models` and act as entities |
+| Repositories | Interface in Domain, implementation in Infrastructure | Interface in Domain, implementation in Infrastructure (unchanged) |
+| Mapping cost | Entity ↔ ORM model mapper per aggregate | None |
+| When to choose | Complex rules, long-lived core domain, multiple persistence targets | CRUD-heavy modules, active-record frameworks, small team speed |
+| What never relaxes | Typed Data classes at boundaries; one use case per action; controllers never touch persistence | Same |
+
+`pragmatic` is the honest default for Laravel and Rails-style frameworks. It
+relaxes exactly one thing, the purity of Domain, and nothing else. If an agent
+finds itself relaxing a second thing under the banner of "pragmatic", that is a
+finding, not a convention.
+
+---
+
+## 4. Naming — no synonyms
+
+| Thing | Name | Example |
+|-------|------|---------|
+| Use case | `{Verb}{Noun}` — imperative, business verb | `ApproveInvoice`, `ListBrands`, `ImportHsnCodes` |
+| Use case entry method | `execute` / `handle` (one, chosen per repo, recorded in §5.0) | `ApproveInvoice::execute(ApproveInvoiceData $data): InvoiceResult` |
+| Input Data (write) | `{UseCase}Data` | `CreateBrandData` |
+| Input Data (read filters) | `{Noun}FilterData` | `BrandFilterData` |
+| Output Data | `{Noun}Result` or `{Noun}View` (one, per repo) | `BrandResult` |
+| Repository port | `{Noun}Repository` | `BrandRepository` |
+| Repository implementation | `{Tech}{Noun}Repository` | `EloquentBrandRepository`, `PrismaBrandRepository` |
+| Domain error | `{Noun}{Condition}` + language suffix | `BrandNotFound` + `Exception`/`Error` |
+| Domain event | `{Noun}{PastTenseVerb}` | `InvoiceApproved` |
+| Query object | `{Noun}{Purpose}Query` | `OutstandingBalancesByAgeQuery` |
+| Enum | Singular noun | `BrandStatus` |
+
+Repository read methods are fixed across every repo:
+
+| Method | Returns | On not found |
+|--------|---------|--------------|
+| `findById(id)` | the entity | throws `{Noun}NotFound` |
+| `findByIdOrNull(id)` | entity or null | null — only when absence is a normal branch |
+| `paginate(filter: {Noun}FilterData)` | typed page of entities | empty page |
+| `listForDropdown()` | typed collection of `OptionData` | empty collection |
+| `existsBy{Field}(value)` | bool | false |
+
+A repo may extend this list in §5.3. **New repositories use these names
+exactly.** A repository bootstrapped from existing code may record an
+established spelling as its canonical one in §5.3 — for example
+`getForDropdown` in place of `listForDropdown`, or `getAll(FilterData)` in place
+of `paginate`. That spelling is then the only one allowed in that repo, and
+the canon name becomes a forbidden synonym there. What is never allowed is two
+spellings in one repository.
+
+---
+
+## 5. Typed data at every boundary
+
+See `canon/typed-data.md`. In short: **nothing crosses a layer boundary as an
+untyped array, map, dictionary, or `mixed`/`any` value.** Input arrives as a
+Data class, output leaves as a Data class, collections are typed collections of
+Data classes. This is a pipeline-wide rule, not a repo preference, and it
+outranks brevity every time.
+
+---
+
+## 6. Tests mirror the layers
+
+```
+tests/
+├── Unit/{Module}/Domain/          pure, no framework boot, no database
+├── Unit/{Module}/Application/     use cases with in-memory fakes of the ports
+├── Integration/{Module}/Infrastructure/   repositories against a real database
+└── Feature/{Module}/Interface/    HTTP / GraphQL / page tests end to end
+```
+
+(Or co-located `*.spec.ts` beside the file, when the framework's convention is
+co-location — recorded in §9. The *levels* are fixed; the *location* is mapped.)
+
+Every use case ships with an in-memory fake for each port it uses, in
+`tests/Support/Fakes/{Module}/`. Fakes are what make the Application layer
+testable in milliseconds, which is what makes TDD tolerable at scale.
+
+---
+
+## 7. Framework mappings
+
+`00a` and `00b` generate from these. `00` bootstrap verifies the repo still
+matches the mapping recorded in §5.0.
+
+### 7.1 Laravel (PHP 8.3+)
+
+```
+app/Modules/{Module}/
+├── {Module}ServiceProvider.php          binds ports → implementations, loads routes + migrations
+├── Domain/
+│   ├── Models/                          pragmatic only: Eloquent models
+│   ├── Entities/                        strict only: plain PHP classes
+│   ├── ValueObjects/
+│   ├── Enums/                           backed enums
+│   ├── Events/
+│   ├── Exceptions/
+│   └── Contracts/                       repository + service ports (interfaces)
+├── Application/
+│   ├── UseCases/                        ApproveInvoice.php — one public method
+│   ├── Data/                            Spatie Data (or readonly classes): *Data, *FilterData, *Result
+│   └── Contracts/                       ports to external services
+├── Infrastructure/
+│   ├── Persistence/
+│   │   ├── Repositories/                EloquentBrandRepository.php
+│   │   ├── Queries/                     raw/aggregate query objects
+│   │   ├── Scopes/
+│   │   └── Migrations/
+│   ├── Jobs/
+│   ├── Excel/                           import/export adapters, if any
+│   └── External/                        HTTP clients, SDK adapters
+└── Interface/
+    ├── Http/
+    │   ├── Controllers/                 thin: map request → Data → use case → response
+    │   ├── Resources/                   JSON output shaping (API topologies)
+    │   ├── ViewModels/                  Inertia/Blade page props as Data (MVC topology)
+    │   └── routes.php
+    ├── Policies/
+    └── Console/
+```
+
+- Input validation: Spatie Laravel Data (`rules()` on the Data class), injected
+  as the controller method parameter. Never `$request->validate()`, never
+  `$request->all()` past the controller.
+- Collections: `DataCollection<BrandResult>` / `Collection<int, Brand>` with
+  generics declared in docblocks; PHPStan checks them.
+- Static analysis: Larastan at the level recorded in §3, with iterable value
+  types required.
+- Tests: Pest. Unit tests extend a base that does **not** boot the app.
+
+### 7.2 NestJS (TypeScript strict)
+
+```
+src/modules/{module}/
+├── {module}.module.ts                  providers: port tokens → implementations
+├── domain/
+│   ├── entities/                       plain classes (strict) or ORM entities (pragmatic)
+│   ├── value-objects/
+│   ├── enums/
+│   ├── events/
+│   ├── errors/
+│   └── ports/                          brand.repository.ts (interface + injection token)
+├── application/
+│   ├── use-cases/                      approve-invoice.use-case.ts — one class, one execute()
+│   ├── data/                           *.data.ts, *.filter.ts, *.result.ts — classes, readonly fields
+│   └── ports/
+├── infrastructure/
+│   ├── persistence/
+│   │   ├── repositories/               prisma-brand.repository.ts / typeorm-…
+│   │   ├── queries/
+│   │   └── migrations/                 or the ORM's migration dir, mapped in §4
+│   ├── jobs/                           BullMQ processors
+│   └── external/
+└── interface/
+    ├── http/
+    │   ├── controllers/
+    │   ├── dto/                        class-validator request DTOs → mapped to application Data
+    │   └── presenters/
+    ├── graphql/                        resolvers + object types (if GraphQL)
+    └── guards/
+```
+
+- Request DTOs (class-validator) live in Interface and are **mapped** to
+  Application Data classes. Application never imports `class-validator`
+  decorators — that is a framework concern leaking inward.
+- `strict: true`, `noUncheckedIndexedAccess: true`, `exactOptionalPropertyTypes: true`.
+- ESLint: `@typescript-eslint/no-explicit-any: error`, `no-unsafe-*: error`.
+- Tests: Jest or Vitest per repo; `*.spec.ts` co-located, `test/` for e2e.
+
+### 7.3 Express / Fastify / Hono (TypeScript)
+
+Same tree as NestJS without the module file. Wiring happens in
+`src/modules/{module}/index.ts`, which exports a `register{Module}(app, deps)`
+function. Validation with Zod at Interface; `z.infer` types are **not** used as
+Application Data — map them to classes or branded readonly types so the
+Application layer does not depend on the validator.
+
+### 7.4 Django / FastAPI (Python 3.12+)
+
+```
+{project}/modules/{module}/
+├── domain/          dataclasses(frozen=True, slots=True), Enum, exceptions, Protocol ports
+├── application/     use_cases/, data/ (dataclasses or pydantic models — one choice per repo)
+├── infrastructure/  persistence/ (Django models or SQLAlchemy), repositories/, tasks/
+└── interface/       http/ (views / routers), serializers or request schemas, urls.py
+```
+
+`mypy --strict` or `pyright strict`. `dict[str, Any]` crossing a layer is the
+Python spelling of an untyped array and is forbidden the same way.
+
+### 7.5 Spring Boot (Java 21 / Kotlin)
+
+Package-by-module, then by layer: `com.acme.{module}.{domain|application|infrastructure|interface}`.
+Records for Data classes. ArchUnit test enforces the dependency direction.
+
+### 7.6 Go
+
+`internal/{module}/{domain,app,store,transport}`. Go's naming replaces
+Application/Infrastructure/Interface with `app`/`store`/`transport`; the
+mapping table in §5.0 records the equivalence. Structs for Data, no
+`map[string]any` across package boundaries.
+
+### 7.7 A framework not listed
+
+`00a` proposes a mapping using the table in §2 as the invariant and the
+framework's own conventions for everything else, records it in
+`scaffold-decisions.md` as **defaulted**, and asks the developer to confirm it
+before the first commit. `find-skills` may be used to look for an established
+skill for that framework; any skill adopted is recorded in `toolchain.md`
+§Project additions.
+
+---
+
+## 8. MVC topology specifics
+
+In an MVC repository the Interface layer also owns **view models**: one Data
+class per screen, holding exactly what the template or page component receives.
+
+- Controllers return `render(view, ViewModel)`. Never an array of props.
+- The view model is the seam between backend and UI tracks (see
+  `agents/02d-interface-seam.md`, mode `page-contract`).
+- Form error shape and flash messages are defined once in §7 and reused.
+
+---
+
+## 9. What the canon does not decide
+
+Deliberately left to the repo, recorded in the architecture context:
+
+- The ORM, the validator library, the test runner
+- Co-located vs mirrored tests
+- `execute` vs `handle`; `Result` vs `View`
+- Whether events are synchronous or queued
+- Frontend structure (see `canon/frontend-canon.md`, which is lighter by design)

package/payload/ai-agents/canon/frontend-canon.md

@@ -0,0 +1,47 @@
+# Frontend Canon
+
+Lighter than the backend canon on purpose. Frontend frameworks disagree more
+about structure than backend frameworks do, and the component inventory (§8.3)
+and design tokens (§8.4) already carry most of the consistency. This file fixes
+only the things that stay true across React, Vue, Svelte, Angular, Blade,
+Livewire, and mobile.
+
+## 1. Feature folders over type folders
+
+```
+{ui-root}/
+├── app/ or pages/        routing entry points — thin: fetch/receive data, compose a feature
+├── features/{feature}/
+│   ├── api/              typed client calls for this feature (generated or hand-written against the seam)
+│   ├── model/            types, state, derived data — named types only (typed-data T1)
+│   └── ui/               feature-local components, composed from the shared inventory
+├── shared/
+│   ├── ui/               the approved component inventory (§8.3) — nothing else lives here
+│   ├── lib/              framework-agnostic helpers
+│   └── api/              the HTTP/GraphQL client, error normalisation
+└── styles/ or theme/     design tokens (§8.4) — or the path DESIGN.md points to
+```
+
+A repo maps these names onto its framework in `architecture-context.md` §8.0.
+MVC repos with server templates map `features/{feature}/ui` onto the
+template directory for that module, and `api/` onto the view-model types.
+
+## 2. Rules that hold everywhere
+
+1. Pages/routes never call `fetch` directly — they go through `features/*/api`.
+2. Response bodies are parsed into named types at the edge (typed-data T5).
+3. `shared/ui` grows only through Gate 1 approval.
+4. Tokens, never literal values.
+5. Every data-bound region implements the required states (§8.5).
+
+## 3. Topology notes
+
+- **mvc**: the "API" is the view model the controller passes. Types for it are
+  generated or hand-mirrored from the backend ViewModel Data classes; the seam
+  document is the source of truth for both.
+- **unified-api**: types are generated from the backend's schema (OpenAPI,
+  GraphQL SDL, tRPC router) where the repo supports it; otherwise mirrored by
+  hand from the seam and checked in the integration task.
+- **split-frontend**: types come from the imported seam in
+  `contracts/{slug}/` (see `agents/02d-interface-seam.md`). The frontend repo
+  never edits an imported contract.

package/payload/ai-agents/canon/typed-data.md

@@ -0,0 +1,158 @@
+# Typed Data — pipeline-wide rule
+
+**Nothing crosses a boundary as an untyped array, map, dictionary, or
+`mixed`/`any` value. Every shape that moves between layers, modules, processes,
+or the network has a named type. Even when that means many small Data classes.**
+
+This is a pipeline rule, installed into every repository's §10 as rules
+`T1`–`T6`. A repo may tighten it. It may not relax it without a recorded Gate 1
+decision naming the exact file and reason.
+
+---
+
+## Why
+
+Arrays are the fastest way to write the first version and the slowest way to
+change the tenth. A `$filters` array accumulates keys nobody documented; a
+`Record<string, unknown>` gets a third optional field that half the callers set.
+Each iteration is individually reasonable and collectively unreadable. A Data
+class makes the shape a thing you can find, rename, and let the type checker
+chase through the codebase for you.
+
+For agents specifically: a named type is the cheapest possible context. An
+implementer that sees `paginate(BrandFilterData $filter)` knows every legal
+filter from one file. One that sees `paginate(array $filters)` has to read every
+call site and guess.
+
+---
+
+## The rules
+
+| # | Rule | Checked by |
+|---|------|------------|
+| T1 | Layer boundaries (controller→use case, use case→repository, module→module, job payloads, events) accept and return **named types only**. No `array`, `mixed`, `any`, `object`, `unknown`, `dict`, `Record<…>`, `Map<string, …>` in those signatures. | Static analysis + `scripts/check-typed-boundaries.mjs` on the diff |
+| T2 | Collections are **typed collections of named types**: `list<BrandResult>`, `DataCollection<BrandResult>`, `ReadonlyArray<BrandResult>`, `list[BrandResult]`. A bare `array` / `any[]` is never a return type. | Static analysis (iterable value types required) |
+| T3 | Fixed sets of values are **enums**, not strings. Status, type, kind, role, direction. | Review |
+| T4 | Optional is explicit: nullable types or dedicated variants — never "key may be missing". | Type checker (`exactOptionalPropertyTypes`, PHPStan) |
+| T5 | Untyped data is allowed **only at the parse edge**: the line that reads JSON, a request body, a CSV row, or an env var — and it is converted to a named type **on the next line**. | Review |
+| T6 | Money, quantities, identifiers, and dates are value objects or branded types when they carry rules (currency, precision, format). A `float` is never money. | Review |
+
+---
+
+## What "boundary" means
+
+Inside a single private method, a local array used as a scratch list is fine.
+The rule applies where one piece of code hands data to another that was written
+at a different time by a different mind:
+
+- Public and protected method signatures in Domain, Application, Infrastructure
+- Controller → use case, use case → repository, use case → port
+- Anything serialised: API responses, job payloads, events, cache entries,
+  view models, exports
+- Configuration read at runtime
+- Test fixtures shared across more than one test file
+
+---
+
+## Spelling it per language
+
+### PHP (Laravel)
+
+```php
+// Wrong
+public function getAll(array $filters): LengthAwarePaginator
+public function getForDropdown(): array
+
+// Right
+public function paginate(BrandFilterData $filter): LengthAwarePaginator  // @return LengthAwarePaginator<int, Brand>
+public function listForDropdown(): DataCollection                        // @return DataCollection<int, OptionData>
+
+final class BrandFilterData extends Data
+{
+    public function __construct(
+        public readonly ?string $search = null,
+        public readonly ?BrandStatus $status = null,
+        public readonly int $perPage = 15,
+    ) {}
+}
+
+final class OptionData extends Data
+{
+    public function __construct(
+        public readonly int $id,
+        public readonly string $label,
+    ) {}
+}
+```
+
+Analytics that previously returned `['labels' => [...], 'series' => [...]]`:
+
+```php
+final class TimeSeriesData extends Data
+{
+    /** @param list<string> $labels  @param list<float> $series */
+    public function __construct(
+        public readonly array $labels,   // typed via docblock; the class is the boundary type
+        public readonly array $series,
+    ) {}
+}
+```
+
+Note the last case: a PHP `array` property **inside** a Data class with a
+precise `list<T>` docblock is acceptable — the boundary type is `TimeSeriesData`,
+and PHPStan enforces the element type. A bare `array` in a signature is not.
+
+Tooling: Larastan/PHPStan level ≥ 6 (iterable value types required),
+`phpstan-strict-rules`, `spatie/laravel-data`.
+
+### TypeScript (NestJS, Express, any frontend)
+
+```ts
+// Wrong
+async list(filters: Record<string, unknown>): Promise<any[]>
+
+// Right
+export class BrandFilter {
+  constructor(
+    readonly search: string | null,
+    readonly status: BrandStatus | null,
+    readonly perPage: number,
+  ) {}
+}
+async paginate(filter: BrandFilter): Promise<Page<BrandResult>>
+```
+
+Frontend: every API response has a named type generated from, or checked
+against, the frozen seam. `as` casts on response bodies are a T5 violation — parse
+(Zod, Valibot, or a generated client) at the edge instead.
+
+Tooling: `strict`, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`,
+`@typescript-eslint/no-explicit-any`, `no-unsafe-assignment`,
+`no-unsafe-member-access`, `no-unsafe-return`.
+
+### Python
+
+`@dataclass(frozen=True, slots=True)` or pydantic models; `Enum`/`StrEnum`;
+`mypy --strict`. `dict[str, Any]` in a signature is the Python spelling of an
+untyped array.
+
+---
+
+## How agents apply it
+
+- **02b backend contract** names every Data class in §3 and §5, with fields and
+  types. "Accepts filters" is not a specification; `BrandFilterData { search:
+  ?string, status: ?BrandStatus, perPage: int = 15 }` is.
+- **02c UI contract** names the frontend types it consumes; **02d seam** freezes
+  them, field by field.
+- **04a / 04b implementers** create the Data classes the contract names, in the
+  task that first needs them. Creating an extra one the contract did not name is
+  fine when it removes an array from a boundary — record it in the decisions log.
+- **Gate 2** reviewers look for arrays in signatures before anything else.
+
+## Interaction with ponytail
+
+Ponytail pushes toward writing less code. That applies to **logic, abstractions,
+and dependencies** — not to type declarations. A Data class with four readonly
+fields is not over-engineering; it is the rule. When ponytail's review flags a
+Data class as unnecessary, T1 wins. See `toolchain.md` §Precedence.

package/payload/ai-agents/observations/README.md

@@ -0,0 +1,11 @@
+# Observations
+
+Written by the task-observer skill while agents work: repeated corrections,
+preferences, and gaps it notices in the agent instructions or skills.
+
+Nothing here changes the pipeline by itself. At release, agent 09b reads the
+logs written while those features were built, groups recurring ones, and writes
+`proposals-{version}.md` — specific edits to specific files — for a human to
+accept or reject. Processed logs move to `processed/`.
+
+Commit this directory. The patterns in it are team knowledge.

package/payload/ai-agents/scripts/check-test-with-change.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+// @ts-check
+/**
+ * Rule TDD-1: a commit that changes source under the configured paths must add
+ * or change a test in the same commit — or say why not with `[no-test: reason]`
+ * in its message. It cannot prove the test came first (tdd-log.md and Gate 2
+ * do that); it proves the test exists, which is the part CI can check honestly.
+ *
+ * Usage:
+ *   node .ai-agents/scripts/check-test-with-change.mjs --base origin/main   # every commit in base..HEAD
+ *   node .ai-agents/scripts/check-test-with-change.mjs --staged             # staged files, before commit
+ */
+import { execFileSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+
+import { matchesAny } from './lib/glob.mjs';
+import { loadRulesConfig } from './lib/config.mjs';
+
+/**
+ * @typedef {object} CommitFacts
+ * @property {string} sha
+ * @property {string} message
+ * @property {ReadonlyArray<string>} files
+ */
+
+/**
+ * @typedef {object} TddViolation
+ * @property {'TDD-1'} rule
+ * @property {string} sha
+ * @property {ReadonlyArray<string>} sourceFiles
+ */
+
+/**
+ * @param {CommitFacts} commit
+ * @param {import('./lib/config.mjs').TestWithChangeConfig} config
+ * @returns {TddViolation | null}
+ */
+export function evaluateCommit(commit, config) {
+  const tests = commit.files.filter((file) => matchesAny(file, config.testPaths));
+  const sources = commit.files.filter(
+    (file) => matchesAny(file, config.sourcePaths) && !matchesAny(file, config.testPaths),
+  );
+  if (sources.length === 0 || tests.length > 0) return null;
+  const exemption = new RegExp(`\\[${config.exemptionTag}:\\s*[^\\]\\s][^\\]]*\\]`);
+  if (exemption.test(commit.message)) return null;
+  return { rule: 'TDD-1', sha: commit.sha, sourceFiles: sources };
+}
+
+/**
+ * @param {ReadonlyArray<string>} args
+ * @returns {string}
+ */
+function git(args) {
+  return execFileSync('git', args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 }).trim();
+}
+
+/**
+ * @param {ReadonlyArray<string>} argv
+ * @returns {number}
+ */
+export function main(argv) {
+  const config = loadRulesConfig(process.cwd()).testWithChange;
+  if (config.sourcePaths.length === 0) {
+    console.log('TDD-1 test-with-change: not configured (testWithChange.sourcePaths is empty) — skipping.');
+    return 0;
+  }
+
+  /** @type {Array<CommitFacts>} */
+  const commits = [];
+  if (argv.includes('--staged')) {
+    const files = git(['diff', '--cached', '--name-only']).split('\n').filter(Boolean);
+    commits.push({ sha: 'staged', message: '', files });
+  } else {
+    const baseIndex = argv.indexOf('--base');
+    const base = baseIndex >= 0 ? argv[baseIndex + 1] ?? 'origin/main' : 'origin/main';
+    const shas = git(['rev-list', '--no-merges', `${base}..HEAD`]).split('\n').filter(Boolean);
+    for (const sha of shas) {
+      commits.push({
+        sha,
+        message: git(['log', '-1', '--format=%B', sha]),
+        files: git(['show', '--name-only', '--format=', sha]).split('\n').filter(Boolean),
+      });
+    }
+  }
+
+  const violations = commits
+    .map((commit) => evaluateCommit(commit, config))
+    .filter(/** @returns {v is TddViolation} */ (v) => v !== null);
+
+  for (const v of violations) {
+    console.log(
+      `${v.rule} ${v.sha.slice(0, 8)} — source changed with no test change: ${v.sourceFiles.join(', ')}. ` +
+        `Add the test, or explain with [${config.exemptionTag}: reason] in the commit message.`,
+    );
+  }
+  console.log(`TDD-1 test-with-change: ${violations.length} violation(s) in ${commits.length} commit(s).`);
+  return violations.length === 0 ? 0 : 1;
+}
+
+const invoked = process.argv[1];
+if (invoked !== undefined && import.meta.url === pathToFileURL(invoked).href) {
+  process.exit(main(process.argv.slice(2)));
+}