quality-gate · git:20261029.b929ced · 2026-10-29 · sha256 523d7197f55ea987

quality-gate git:20261029.b929cedA

Immutable. This exact content never changes and is served at /api/v1/blob/523d7197f55ea987.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_erfwre27oqx7n55u/523d7197f55ea987014de5eaf227c3f9acd03504ed3dc2c8ecab32d22556a305.json

Then /plugin install quality-gate@markdownregistry-erfwre27oqx7n55u in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: quality-gate
description: >-
  Use before closing a slice or opening a pull or merge request, to merge the trunk into a
  branch, when asked whether the work is clean, done or ready, when a check, the guard or
  the pipeline reports a violation, or for a TODO(review).
allowed-tools:
  - Read
  - Edit
  - Bash(npm run verify)
  - Bash(npm run typecheck)
  - Bash(npm run lint *)
  - Bash(npm test *)
  - Bash(npm run test:coverage)
  - Bash(npm run test:e2e *)
  - Bash(npm run docs:check)
  - Bash(npm run regenerate)
  - Bash(npm run docs:generate)
  - Bash(npm run depcruise)
  - Bash(npm run deadcode)
  - Bash(npx ddd-ts-kit check *)
  - Bash(npx ddd-ts-kit verify-slice *)
  - Bash(npx ddd-ts-kit verify-merge)
  - Bash(npx ddd-ts-kit verify-merge *)
  - Bash(npx ddd-ts-kit merge-trunk)
  - Bash(npx ddd-ts-kit merge-trunk *)
  - Bash(npx ddd-ts-kit check)
  - Bash(npx ddd-ts-kit todo *)
  - Bash(npx ddd-ts-kit todo)
  - Bash(npx ddd-ts-kit status)
  - Bash(npx ddd-ts-kit story-check *)
  - Bash(npx ddd-ts-kit docs)
  - Bash(npx ddd-ts-kit explain *)
  - Bash(npx ddd-ts-kit acceptance *)
---

# Quality gate

The size and message of the commit are skill `ddd-ts-kit:commit-discipline`.

## Scope the run

| When | Run | Cost |
|---|---|---|
| after each write | nothing: the guard runs `check-file` and returns the violations | none |
| while iterating | `npx ddd-ts-kit verify-slice <context> --since <base>`: regenerate, the rules on the changed files, the specs of the context, the files near the size limit and the paths of the slice to stage (the pages of `docs/behaviour/` and the schema of the ORM the generator changed for the context included), in one run; a path it leaves out is never staged with the slice | seconds |
| before the commit that closes a slice | the two above, `npm run typecheck`, `npm run lint`, `npm run format:check` (`npm run format` settles it), `npx ddd-ts-kit todo <context>` (nothing left but `TODO(review)`), `npx ddd-ts-kit check --commit-size` | under a minute |
| to bring the trunk into the branch | `npx ddd-ts-kit merge-trunk`: one merge commit from the branch's own diff, derived files settled, `verify-merge` on the result before its commit; on a stop, resolve each hunk keeping both sides, `git add`, `merge-trunk --continue` ("Bring the trunk in" below) | seconds |
| after a merge made otherwise | `npx ddd-ts-kit verify-merge`: each line, row done or test the merge lost, to restore from its side; it exits 1 on one (the pre-push hook and `verify-slice` run it too, and only warn in this version) | a second |
| before a merge or a pull request | `npm run verify`, on the branch with the trunk merged in; each non-blocking remark of the review written as a `TODO(review)` or settled | everything |
| before the code of a story | `npx ddd-ts-kit acceptance <story> --gate written`: every slice row and criterion has a scenario, wrapped in `pending(...)`, locked and committed | seconds |
| before a story or a milestone is closed | `npx ddd-ts-kit story-check <code>` (`M1` for the rows `M1.*`): every row `done`, no marker of its own left; exits 1 with each blocker, why it is the story's, its `file:line` and its fix; then `npx ddd-ts-kit acceptance <story> --gate passing`: no scenario pending nor drifted from its lock, and each amendment it lists reported to the owner | seconds |

Layout is settled in this order: `npm run format`, then `npm run lint:fix`. Biome wraps a long
line, and the lint then asks for a blank line around the statement that now spans several lines:
that new finding is expected, never a conflict between the two. Never Prettier nor a bare
`npx biome` (without `--no`, it can fetch an unrelated package of that name); the guard refuses
both to a worker.

`npm run lint` (`ddd-ts-kit lint`) fails on a warning as on an error: fix it the same way. A rule
of the kit in transition is listed apart without failing: fix its warnings too, before the
version it names makes them errors. An
entry of `eslint-suppressions.json` is a finding the project recorded: once it is fixed the lint
fails until `npx eslint . --prune-suppressions` removes it; adding one (`--suppress-all`,
`--suppress-rule`) is a suppression.

`check --changed-since` judges the changed files, and the findings whose cause is a changed file
(a handler not registered in the module file, an adapter not wired, a use case not declared:
they sit on one file and are repaired in another, and the `subjects` of the JSON name it) only: a cycle, an unused export or a rule
broken by the combination with the trunk escapes it, which is why the last run is `verify`, on
the whole tree, after merging the trunk. `npm run verify` chains types, lint, format, every spec with the coverage thresholds
(`npm run test:coverage`), end-to-end tests, the architecture rules, the import graph
(dependency-cruiser), dead code (knip) and documentation drift. Use
`npm run typecheck`, never `npx tsc`: the project compiles with the native compiler.
`npx ddd-ts-kit status` counts the `TODO(domain)`, `TODO(platform)`, `it.todo` and
`TODO(review)` left in each context: a gate is not passed while the slice still has one of the
first three.

## Bring the trunk in

When the rows of a branch are committed, before its review and its merge: bring the trunk into
the branch with `npx ddd-ts-kit merge-trunk` (`--cwd <worktree>` from outside it), never
`git merge` alone. It computes the
merge from the newest commit of the branch the trunk holds (a first row already squash-merged, a
branch it was stacked on), settles the derived files (the `package.json` of a client at the higher
of both versions), generated regions and registries, the rows
of `slices.md`, the drizzle-kit journal and the lockfile itself, and leaves each source or test
hunk in a merge in progress with what each side did there (exit 1). Resolve each hunk keeping
both sides, never by taking one side of a source file or a test (`-X theirs`, `-X ours`,
`checkout --theirs` erase the other side without a conflict, and the guard refuses them to a
sub-agent), `git add` it, then `npx ddd-ts-kit merge-trunk --continue`: it replays the
migrations, regenerates, runs `verify-merge` on the result and commits only once no line, row
or test is lost (a removal decided on purpose: `--continue --accept-lost`; `--abort` undoes, and restores the derived files the kit regenerated). On Prisma it also runs `npm run db:client` when the merge changed a schema, so the test database is current. When the trunk moved since the merge started, `--continue` says so: it concludes the commit of the first run, so run `merge-trunk` again after it.
Under the sandbox, a trunk that changes the settings of the project (`.claude/settings.json`) or
another path the session cannot write is the owner's merge: `merge-trunk` stops with nothing
changed and exit 3, naming the paths; hand the owner the same command to run from a terminal
outside the sandbox, and do not merge by hand or reset the worktree.

## Review remarks

A review sorts its findings: a blocking one is fixed before the merge; a non-blocking one is
settled at once, or written before the merge as `TODO(review): #<row id> <remark>` at the line it is
about, by whoever fixes the branch (the `architecture-reviewer` agent gives the line and its
`file:line`, and never writes it), never left in the body of a pull request. A slice may merge with `TODO(review)` markers; a story or a
milestone is closed only when `npx ddd-ts-kit story-check <code>` exits 0: every marker of its
own handled, or dismissed by a decision record (`npx ddd-ts-kit generate adr "<title>"`,
quoting the remark without its marker) with the marker deleted in the same commit. A marker is
the story's when its text names one of its rows (the `#<row id>` above), else when the commit that
wrote its line does (its `Slice: <row id>` trailer, else its message), else, not committed, when
the worker whose worktree holds it was briefed on one of its rows. One that belongs to no row
blocks only when no other open story has a row in its context; otherwise `story-check` lists it
without blocking: settle it, or name its row in it. `--strict` blocks on every marker of the
story's contexts. The rule of two: a finding that repeats one already recorded for the project
(the same rule id, or the same remark on the same layer, in an earlier
`docs/architecture/reviews/*.md` or as a `TODO(review)` marker) is written as one line under
`## Mistakes seen here` of `AGENTS.md`, or as the config change when a rule of the kit covers
it, in the commit that settles it; the reviewer gives the line.

## Coverage

`npm run test:coverage` fails with `Coverage for <rate> (<measured>%) does not meet
"<contexts>/<context>/<layer>/**/*.ts" threshold (<floor>%)`: that layer of that context holds
code no spec runs. The thresholds are the `coverage` key of `ddd-ts-kit.config.json` (the
reference when absent: domain 90/85/90/90, application 85/80/85/85, presentation 80/70/80/80,
infrastructure 70/60/70/70, as statements/branches/functions/lines).

- Read the uncovered lines in the report, write the spec of the behaviour that reaches them
  (`/ddd-ts-kit:testing`), or delete the code when nothing can reach it.
- Never add `exclude`, `include` or `thresholds` to the runner config, a `--coverage.*` flag to a
  script, or a `v8 ignore` / `istanbul ignore` comment: `test/coverage-governed` reports them.
- Lowering a threshold is a decision of the team: change the rate in the config and record it
  with `npx ddd-ts-kit generate adr "<title>" --deviation coverage.<layer>.<rate> --reason "<why>"`.
  Raising one is free.

## Read a violation

Each carries a rule id, a `file:line`, a message and a `fix` sentence. Open that file at that
line only. `npx ddd-ts-kit explain <rule-id>` gives the reason and a good and a bad example;
`check --explain` adds the reason of every rule a run reports, once each, without a call per rule.

| Rule family | Usual root cause | Fix |
|---|---|---|
| `layer/*` | logic or a type in the wrong layer | move it, or a port in `application/ports/` and an adapter |
| `context/*` | a context reaching into another | a contract in the upstream's `published-language/`, an integration event, a declared relationship (skill `ddd-ts-kit:context-map`) |
| `tree/*`, `naming/*` | a file made by hand | `ddd-ts-kit generate`, then move the logic |
| `language/*` | a name outside the glossary | the business word, or the term added first (skill `ddd-ts-kit:glossary`) |
| `ports/*`, `declarations/*`, `composition/*` | wiring by hand | skill `ddd-ts-kit:wiring`; a stale barrel is `npx ddd-ts-kit docs` |
| `domain-events/*` | a handler or an adapter dispatching events itself; a `before-commit` handler depending on a gateway, an external port, `Cache`, `Lock`, `RateLimiter`, `JobScheduler` or `EventBus` | `await repository.save(aggregate)` and nothing else: the unit of work dispatches at its end; `phase: 'after-commit'` when the effect may be lost, an integration event when it must not |
| `authz/*` | a use case without a permission, a right decided in the wrong layer | skill `ddd-ts-kit:access-control` |
| `events/*`, `scheduling/*` | a contract outside the published language, a consumer without a name, a job doing work | skill `ddd-ts-kit:integration-event`; a job only sends a command |
| `purity/*`, `clean/*` | a hidden dependency, unclear code | skill `ddd-ts-kit:clean-code` |
| `aspects/*`, `tracing/*`, `standard/*` | a technical concern inside business code | skill `ddd-ts-kit:cross-cutting` |
| `governance/*`, `config/*` | a suppression or a config entry without its reason or record | skill `ddd-ts-kit:deviation` |
| `test/*` | behaviour without a test, or a mock | skill `ddd-ts-kit:testing` |
| documentation drift | generated files not regenerated | `npm run regenerate`, commit them with the code |
| `event-sourcing/*`, `unrecorded ...` or `formerly recorded ... in stored-events.lock.json` from `docs:check` | a state change outside an apply method, a stored shape changed in place, a stored version not recorded, or recorded by 0.82.0 or earlier | skill `ddd-ts-kit:persistence`; a changed stored shape is a new version with its upcaster, and an unrecorded or formerly recorded one is recorded by `npx ddd-ts-kit docs --stored-events` (once final), never by hand |

Five ids are held by ESLint (`domain/*`, `application/*`): `npm run lint` reports them.

## Not without the owner's explicit agreement

A suppression, a lowered severity, a wider allow-list, an extra directory, a relaxed
pipeline, `any`, a non-null assertion, a skipped or deleted test, an acceptance scenario changed
while its criterion was not: skill `ddd-ts-kit:deviation`. Getting to green is never the
reason. A baseline of the errors (`check --baseline write`) is written by the owner, in a
terminal, never by you: the guard refuses it. `check --baseline prune` needs no agreement: it only
lowers what the baseline holds, after a fix.

## Report

The commands run and their real result, in a few lines. A failing gate is reported as
failing, with what remains and why.