Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
174 commits
Select commit Hold shift + click to select a range
355a22a
Bumped version to 6.77.1-rc.0
github-actions[bot] Nov 11, 2026
8903ccf
Updated readdir-glob to v4 (#32804)
acburdine Nov 12, 2026
4b1bc7c
Improved machine payments test flakiness (#32805)
EvanHahn Nov 12, 2026
27d8a80
Removed unnecessary class from link replacer (#32803)
EvanHahn Nov 12, 2026
63a3aef
Update dependency knip to v6.44.2
tryghost-renovate[bot] Nov 11, 2026
25b0522
Update secretlint monorepo to v13.1.0
tryghost-renovate[bot] Nov 12, 2026
11e5029
Update dependency tsc-alias to v1.9.10
tryghost-renovate[bot] Nov 11, 2026
174bfb1
Update dependency dependency-cruiser to v18.7.2
tryghost-renovate[bot] Nov 12, 2026
bcfe5bc
Update dependency typescript-eslint to v8.72.1
tryghost-renovate[bot] Nov 11, 2026
a58caf6
Update dependency stylelint to v18
tryghost-renovate[bot] Nov 11, 2026
597644d
Removed the alpha tag from Shade's install advice
jonatansberg Nov 11, 2026
7c92aae
Removed older-Core fallbacks from Ghost Apps in Admin (#32676)
jonatansberg Nov 12, 2026
60a8a6c
Update storybook monorepo to v10.6.6
tryghost-renovate[bot] Nov 12, 2026
8da0ff9
Changed the test worker count helper to TypeScript (#32794)
ErisDS Nov 12, 2026
2c3387c
Changed phone custom fields to show calling codes in parentheses (#32…
renatoworks Nov 12, 2026
4fd8ea9
Removed the app SDK's duplicate manifest types (#32811)
jonatansberg Nov 12, 2026
49499c3
Added suggested custom field names to the checkout settings (#32819)
renatoworks Nov 12, 2026
48f1d00
Added a type check that keeps app failure codes in step across Ghost …
jonatansberg Nov 12, 2026
e211338
Added archived badges to the checkout settings pickers (#32820)
renatoworks Nov 12, 2026
b394b16
Added a span for each event Stripe sends to the webhook
rob-ghost Nov 11, 2026
da3f525
Added who the buyer is and what was saved to the checkout spans
rob-ghost Nov 11, 2026
b652471
Added a span for each change of tier a member makes
rob-ghost Nov 11, 2026
fbcfb46
Reported Stripe webhooks Ghost fails to handle to Sentry
rob-ghost Nov 11, 2026
0d0e18d
Changed CI to run the unit tests in a shuffled order (#32822)
ErisDS Nov 12, 2026
9c850e1
Added dependency boundary enforcement for all services (#32801)
ErisDS Nov 12, 2026
95213da
TypeScriptified leaf input validators (#32810)
ErisDS Nov 12, 2026
e39b667
TypeScriptified output serializer leaf mappers (#32807)
ErisDS Nov 12, 2026
11a8df0
Changed single-choice custom fields in Portal to mark the answer with…
renatoworks Nov 12, 2026
0dc9518
Added pnpm dev:multi to run two Ghosts locally (#32711)
vershwal Nov 12, 2026
b01e42c
Moved the media inliner dispatch out of the db endpoint (#32739)
vershwal Nov 12, 2026
faf6b19
Changed the last three job handlers to get their services from boot (…
vershwal Nov 12, 2026
6e02fe8
Update dependency supertest to v7.3.2
tryghost-renovate[bot] Nov 12, 2026
4fceb26
Update dependency html-validate to v11.21.0
tryghost-renovate[bot] Nov 12, 2026
2c57619
Update dependency html-minifier-next to v8.11.0
tryghost-renovate[bot] Nov 12, 2026
a2acb25
Updated eslint-plugin-react-hooks to v7.1.1 (#32826)
ErisDS Nov 12, 2026
6abc7a8
Removed stale job handler entries from the known boundary violations …
vershwal Nov 12, 2026
8c8d07c
Removed the emoji flag from the phone custom field in Portal (#32832)
renatoworks Nov 12, 2026
831731f
Added a baseline ratchet for React Compiler lint rules (#32827)
ErisDS Nov 12, 2026
123f76d
Removed test-only checks from gift, member and signing-key schedulers…
vershwal Nov 12, 2026
3106440
Removed test-only checks from the email analytics scheduler (#32740)
vershwal Nov 12, 2026
26c8839
Changed the phone custom field in Portal to start from the reader's t…
renatoworks Nov 12, 2026
5fd6fab
Added a verify command and review skill for service migrations (#32825)
ErisDS Nov 12, 2026
7294794
Changed the content CSV job to create its own progress record (#32737)
vershwal Nov 12, 2026
337f060
Fixed the commit hook failing for files in legacy services (#32840)
ErisDS Nov 12, 2026
5b3b8c4
Removed chai from Ghost's tests (#32835)
ErisDS Nov 12, 2026
997da45
Fixed flaky add-step click in the new automation trigger specs (#32833)
ErisDS Nov 12, 2026
0b924ca
Fixed assertObjectMatches accepting an object where a primitive is ex…
ErisDS Nov 12, 2026
809c596
Added reference jobs and a checklist to the jobs guide (#32734)
vershwal Nov 12, 2026
7ae8a17
TypeScriptified input serializer leaf modules (#32839)
ErisDS Nov 12, 2026
9795b5a
Added knip's dependency check to lint and CI (#32843)
ErisDS Nov 12, 2026
bc89576
Fixed a broken docs link and closed the gaps that let it land (#32844)
ErisDS Nov 12, 2026
2a051f8
Added validation of phone number characters while typing
rob-ghost Nov 12, 2026
b6bba0d
Changed phone number errors to show an example from the number's country
rob-ghost Nov 12, 2026
04edc37
Added a helper for commands to run in one transaction
rob-ghost Nov 12, 2026
c1ae188
Changed gift link commands to each run in one transaction
rob-ghost Nov 12, 2026
8f73d9d
Removed an unused way to create a custom field with a stated key
rob-ghost Nov 12, 2026
54ed74f
Changed custom field commands to each run in one transaction
rob-ghost Nov 12, 2026
e26e993
Changed tier requirement commands to each run in one transaction
rob-ghost Nov 12, 2026
e69f0f6
Changed the Stripe Checkout settings save to join a caller's transaction
rob-ghost Nov 12, 2026
b1311ee
Changed queries to read through a caller's transaction
rob-ghost Nov 12, 2026
d50d622
Added tests for how commands and queries take part in a transaction
rob-ghost Nov 12, 2026
25c0f14
Stopped logging member status when sending automation/welcome emails …
EvanHahn Nov 12, 2026
9b0b40c
Changed service checks to apply to every service that is not legacy (…
ErisDS Nov 12, 2026
f7c0484
Supported "label added" automation triggers in database schema (#32657)
EvanHahn Nov 12, 2026
1217659
Added a shared Redis connection config schema (#32847)
acburdine Nov 12, 2026
8716602
Updated TryGhost SDK deps to latest (#32852)
acburdine Nov 12, 2026
11ed642
Added a repository skill for new services (#32853)
ErisDS Nov 12, 2026
f5ec741
Updated validation schema for "label added" automation triggers (#32802)
EvanHahn Nov 12, 2026
225d054
Fixed the doc link pre-commit check failing in worktrees (#32854)
acburdine Nov 12, 2026
0e210c4
TypeScriptified Mobiledoc helper (#32849)
EvanHahn Nov 12, 2026
11b2a1c
TypeScriptified link replacer utility (#32850)
EvanHahn Nov 12, 2026
1553e35
Removed automation lifecycle trigger feature flag from backend (#32856)
EvanHahn Nov 12, 2026
a6cc862
Reduced database queries in "enqueue next automation step" action (#3…
EvanHahn Nov 12, 2026
511e3a4
Changed the staff admin-origin checks to use url-utils getAdminOrigin…
acburdine Nov 12, 2026
4bc2a98
Logged which outbox mode Ghost boots in
allouis Nov 12, 2026
d7caf48
Removed the unused Job model
allouis Nov 12, 2026
ab272fc
Made job replay after a restart opt-in
allouis Nov 12, 2026
14f5b64
TypeScriptified "max limit cap" utility (#32868)
EvanHahn Nov 12, 2026
6e96139
Fixed the automations list getting stuck on an empty Archived view (#…
zach1618 Nov 12, 2026
31c2484
TypeScriptified the session endpoint and password reset modules (#32872)
acburdine Nov 12, 2026
8137a54
TypeScriptified the Admin session auth modules (#32873)
acburdine Nov 12, 2026
0b92dff
Moved "track email delivered and opened" to new automations interface…
EvanHahn Nov 12, 2026
1fcc18c
Updated "find automation to run" query to support "label added" trigg…
EvanHahn Nov 12, 2026
ddf90a4
Changed automation canvas card errors to Shade's field error style (#…
zach1618 Nov 12, 2026
89313a9
🐛 Fixed Today's paid subscriptions showing yesterday's changes (#32294)
luissazevedo Nov 12, 2026
1de95a8
Clarified automation service event listening test (#32875)
EvanHahn Nov 12, 2026
e7ecd56
Updated type definitions for members API (#32876)
EvanHahn Nov 12, 2026
6f99cca
Fixed Compose profile forwarding in the orb Docker wrapper (#32880)
cmraible Nov 12, 2026
6955cf1
🐛 Fixed Analytics presets covering more days than their names say (#3…
luissazevedo Nov 12, 2026
995ac7f
Updated default scheduler tests: stop calling private methods (#32885)
EvanHahn Nov 12, 2026
a3b4a6a
Update dependency @tryghost/promise to v2.3.22
tryghost-renovate[bot] Nov 12, 2026
94ef073
TypeScriptified default scheduler tests (#32888)
EvanHahn Nov 13, 2026
ff594b1
Removed useless private methods from default scheduler (#32889)
EvanHahn Nov 13, 2026
fd6f4f7
Update better-auth monorepo to v1.7.19
tryghost-renovate[bot] Nov 13, 2026
c19ef28
Added the production default to the jobs guide's schedule config rule…
vershwal Nov 13, 2026
d2b4c6c
Clarified the shipping countries setting in checkout (#32894)
renatoworks Nov 13, 2026
d570318
Improved the side panel's transitions beside the page (#32896)
sagzy Nov 13, 2026
506bbe1
Update dependency jose to v6.2.17 (#32892)
tryghost-renovate[bot] Nov 13, 2026
b6fe252
Added a visibility switch option to the custom field popover (#32895)
renatoworks Nov 13, 2026
3a77f66
Added an auth:betterAuthDev flag for Better Auth's development data (…
acburdine Nov 13, 2026
ba90bc2
Added full names on hover to the checkout custom field lists (#32901)
renatoworks Nov 13, 2026
00d71bc
Removed the pnpm internal packages from tools/scripts (#32900)
acburdine Nov 13, 2026
8a92834
Moved legacy password reads and writes to user_accounts (#32870)
acburdine Nov 13, 2026
d25aadc
Moved migration utils and hooks to .ts files
acburdine Nov 13, 2026
1ee27ad
Changed migration utils and hooks to TypeScript
acburdine Nov 13, 2026
b31b1f7
Removed the unused event emitter from the members API (#32904)
ErisDS Nov 13, 2026
d0a9f13
Added start and stop hooks to defineService (#32902)
ErisDS Nov 13, 2026
fd647b4
Added dependency rules and classified every known service violation (…
ErisDS Nov 13, 2026
8e886bb
Bumped express-hbs to 4.1.0 (#32907)
acburdine Nov 13, 2026
e30976b
Added boot checks for standard services and closed gaps in the servic…
ErisDS Nov 13, 2026
dc3a4bb
Moved the custom field types and app contracts into a contracts folde…
ErisDS Nov 13, 2026
c2617d0
Update better-auth monorepo to v1.7.20
tryghost-renovate[bot] Nov 13, 2026
822f9a0
Removed old type comments from link replacer code (#32920)
EvanHahn Nov 15, 2026
6399e9d
Added E2E browser tests for automations (#32921)
EvanHahn Nov 15, 2026
dd7dd5c
Update dependency @testing-library/user-event to v14.6.10
tryghost-renovate[bot] Nov 15, 2026
9a4b57c
Update better-auth monorepo to v1.7.22
tryghost-renovate[bot] Nov 15, 2026
9fbd022
Bumped better-sqlite3 to 13.0.3 (#32910)
acburdine Nov 15, 2026
384f561
Update dependency glob to v14.0.6
tryghost-renovate[bot] Nov 15, 2026
e98ceb9
Update dependency html-validate to v11.21.1
tryghost-renovate[bot] Nov 15, 2026
6091cc5
🐛 Fixed member subscriptions on different tiers rendering flush toget…
sam-lord Nov 16, 2026
4bd60b2
Changed the outbox relay to depend only on processNext
allouis Nov 12, 2026
39f44bb
Added a way to wake the outbox relay before its next poll
allouis Nov 12, 2026
fc7e7e6
Woke the outbox relay when a dispatch commits
allouis Nov 12, 2026
7079707
Slowed the jobs outbox fallback poll to 30 seconds
allouis Nov 12, 2026
9cdf1b2
Fixed afterCommit running for savepoint work that never commits
allouis Nov 12, 2026
68025c7
Updated Admin 7 main navigation sidebar (#32845)
peterzimon Nov 16, 2026
83b7b31
Update CODEOWNERS to remove legacy service entry (#32938)
ErisDS Nov 16, 2026
9b67b7e
Let jobs backends report the jobs they hold
allouis Nov 16, 2026
f1faf37
Stopped a booting process from taking jobs another one is still running
allouis Nov 16, 2026
83ff6bf
🐛 Fixed card links being corrupted by legacy HTML entity decoding (#3…
jonatansberg Nov 16, 2026
5bee0cc
🐛 Fixed feature image captions losing their formatting on the site (#…
jonatansberg Nov 16, 2026
581fb7c
Removed automation lifecycle trigger feature flag from frontend (#32857)
EvanHahn Nov 16, 2026
cd55644
Kept renewing outbox leases until the jobs backend drains
allouis Nov 16, 2026
861cef2
Added app attribution footer to app pages (#32677)
weylandswart Nov 16, 2026
a67664b
🐛 Fixed gift redemption for new members on paid-only sites (#32352)
luissazevedo Nov 16, 2026
d85e0c9
Let jobs handlers report an interrupted run
allouis Nov 2, 2026
390d1d1
Reported a newsletter send stopped by shutdown as interrupted
allouis Nov 2, 2026
1233eaa
Simplified bulk insert code (#32878)
EvanHahn Nov 16, 2026
ebe5083
Improved bulk insert CPU and memory use (#32881)
EvanHahn Nov 16, 2026
4a9b394
Improved row locking chunk memory use (#32884)
EvanHahn Nov 16, 2026
ebb7f13
Changed Renovate to update better-auth weekly (#32927)
acburdine Nov 16, 2026
538f011
Changed the app details page to match tag and member details (#32944)
weylandswart Nov 16, 2026
82e321b
TypeScriptified search index test (#32923)
EvanHahn Nov 16, 2026
b36d347
Fixed Automations replay masking crashing when the page body is missi…
cmraible Nov 16, 2026
ba0038c
Updated automations overview and implementation guidance (#32874)
cmraible Nov 16, 2026
8db328f
Bumped @tryghost framework packages with new typings (#32949)
acburdine Nov 16, 2026
2bb2897
Removed unused "hammertime" method (#32950)
EvanHahn Nov 16, 2026
c3fb6c6
Added country flags to the files published with Portal's script
rob-ghost Nov 16, 2026
87e16d9
Added the country's flag to the phone custom field in Portal
rob-ghost Nov 16, 2026
448fb29
Bumped remaining @tryghost framework packages to latest (#32951)
acburdine Nov 16, 2026
e601bc8
Updated knex-migrator to 6.4.2 with a TypeScript MigratorConfig (#31393)
acburdine Nov 16, 2026
c924fca
Updated framework packages to their latest, typed releases (#32953)
acburdine Nov 16, 2026
e23a5b5
Handled "label added" automation notifications (#32760)
EvanHahn Nov 16, 2026
3dca1a3
Started running "label added" automations (#32761)
EvanHahn Nov 16, 2026
d02fab3
Removed last reference to automation lifecycle trigger feature flag (…
EvanHahn Nov 16, 2026
3ca4ec4
Added the "label added" automation trigger UI (#32932)
troyciesco Nov 16, 2026
3e794bd
Trigger "label added" automations (#32762)
EvanHahn Nov 16, 2026
1cd344a
Updated automation API endpoints to support "label added" automations…
EvanHahn Nov 16, 2026
9072f25
Added E2E browser test for "label added" automation (#32954)
EvanHahn Nov 16, 2026
3aa5aaa
Clarify automation analytics dependency for jobs (#32955)
EvanHahn Nov 16, 2026
66ee96c
Improved memory use by loading a single zod build (#32956)
acburdine Nov 16, 2026
b36bde2
Improved ghost_head to skip css-tree for hex accent colors (#32957)
acburdine Nov 16, 2026
5d1040c
Added runtime Zod validation to API framework (#31296)
acburdine Nov 16, 2026
bc9d80b
Improved server memory by lazy-loading libphonenumber-js (#32958)
acburdine Nov 16, 2026
933df93
Added simulated analytics events to the fake Mailgun server (#32959)
acburdine Nov 16, 2026
22d7648
Fixed revoked Stripe access flooding Sentry with webhook failures
rob-ghost Nov 16, 2026
6fb23ef
Fixed exception lines without attributes breaking Grafana's logs panels
rob-ghost Nov 16, 2026
2b8a27d
Added knownKeys to the config schema guide (#32964)
acburdine Nov 16, 2026
bf9aecf
Added a boundary rule keeping config schema files to zod imports (#32…
acburdine Nov 16, 2026
f1f970f
Logged the outbox mode on every job lifecycle line
allouis Nov 17, 2026
44c770c
Logged the outbox poll interval and lease when jobs start
allouis Nov 17, 2026
051d544
✨ Added shipping address and phone collection to Stripe Checkout
rob-ghost Nov 17, 2026
821b3d3
Updated the field type release guide to go through the released list
rob-ghost Nov 17, 2026
273faf0
v6.78.0
github-actions[bot] Nov 17, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
2 changes: 1 addition & 1 deletion .agents/bin/docker
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
#!/bin/sh
exec sudo --preserve-env=PUBLIC_URL /usr/bin/docker "$@"
exec sudo --preserve-env=PUBLIC_URL,COMPOSE_PROFILES /usr/bin/docker "$@"
145 changes: 145 additions & 0 deletions .agents/skills/add-service/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,145 @@
---
name: add-service
description: Create a new Ghost Core service with gx generate service, then finish what the generator leaves to the author - dependency wiring, boot initialization, tests and checks. Use when adding a new boot-owned capability under ghost/core/server/services. To adopt defineService in an existing service, use migrate-service instead.
---

# Add a service

The [services guide](../../../ghost/core/server/services/README.md) is the
authoring guide. This skill is the checklist that goes with it; follow the links
rather than copying a neighbouring service, which may still be legacy.

## 1. Check it is a service

Apply the guide's
[What belongs here](../../../ghost/core/server/services/README.md#what-belongs-here)
test first. A service root wires an instance that boot owns and callers share.
Name that instance, its callers and what must be ready before they use it. A
reusable constructor, an ordinary library or a helper used by one service is not
a service: put it where the guide says and stop here.

For an existing service, use [migrate-service](../migrate-service/SKILL.md).

Then read [creating a service](../../../ghost/core/server/services/README.md#creating-a-service),
[initialization](../../../ghost/core/server/services/README.md#initialization)
and the [kernel contract](../../../ghost/core/kernel/README.md#service-initialization).
[IndexNow](../../../ghost/core/server/services/indexnow-ping/index.ts) and its
[root test](../../../ghost/test/unit/server/services/indexnow-ping/index.test.ts)
are the worked example.

## 2. Generate the service

From the repository root:

```sh
pnpm gx generate service <name>
```

Use lowercase kebab-case beginning with a letter. Never write the root by hand.
The [generator](../../../tools/gx/README.md#service-generator) creates:

- `ghost/core/server/services/<name>/index.ts`, the `defineService` root
- `ghost/core/server/services/<name>/<name>-service.ts`, the implementation
- `ghost/test/unit/server/services/<name>/index.test.ts`, a starter root test

It registers nothing. A service that is not in the
[legacy service inventory](../../../ghost/core/server/services/README.md#standard-and-legacy-services)
is standard, so every service check applies from the first commit. Do not add
the service to the inventory's `services` list or to any lint configuration.

If the generator refuses a name because a path exists or the name is still
listed as legacy, read that code. Do not delete it to make generation succeed.

## 3. Implement and wire dependencies

Put behavior in the implementation and composition in the root's `create`
callback. The guide's
[dependency boundaries](../../../ghost/core/server/services/README.md#dependency-boundaries)
say what the root injects, what the implementation imports directly, and how to
handle live settings, deferred lookups and logging types. Apply them to every
implementation file, including nested helpers.

Delete the generated example comments once the real dependencies are wired.
Consumers read the instance through the root's `.service`. If a check rejects an
import, fix the wiring; do not widen the allowlist to make lint pass.

## 4. Initialize in boot

The generator leaves [boot.js](../../../ghost/core/boot.js) to you.

- **Phase.** Most roots belong in `initServices`. `initCore` and
`initServicesForFrontend` run earlier, for roots that the frontend or later
phases read. Do not initialize on the first request.
- **Order.** Initialize after everything `create` reads and before anything
reads `.service`. In `initServices`, a root that others read during their own
`create` is awaited on its own line before the `Promise.all`; independent
roots go inside it; a root that reads one of those goes after it.
- **Form.** Bind the root, then call `init()` on the binding, as the lines
around it do. Await it even when `create` is synchronous:

```js
const deliveryReceipts = require('./server/services/delivery-receipts').default;
await deliveryReceipts.init();
```

`pnpm lint:oxlint` and `gx services verify` find the call through that
binding. Lint fails until it is there, and neither recognises the inline
`await require(...).default.init()`.

- **Comments.** Replace the generated comment above `defineService` with what
`create` needs ready. Where the order matters, say why beside the call in
boot, as the existing comments there do.
- **Boot test.** `ghost/test/unit/boot/standard-services.test.ts` already
checks that boot waits for the root's `init()` and that its failure fails
boot; do not write that test again. Add a boot test only where order
matters. The `initCore` and `initServicesForFrontend` tests fail on a root
they do not list, so add a stub there for a root in those phases.
- **Resources.** Finish startup work before returning the instance. Acquire
listeners, timers and work to drain in `start` and release them in `stop`,
following
[starting and stopping](../../../ghost/core/server/services/README.md#starting-and-stopping).
Register `root.stop()` with `ghostServer.registerCleanupTask` in boot.

## 5. Test and check

Extend the generated root test and add implementation tests for behavior,
dependency timing and readiness. If startup acquires resources, cover a failed
attempt followed by a successful retry. The
[testing guide](../../../docs/contributing/testing.md#run-focused-tests)
explains the focused commands.

A new service has no inventory entry. The one exception: if the root declares
`extras`, catalogue each one in the `followUps` section of
`ghost/core/server/services/legacy-service-inventory.yaml`, as the
[standard root contract](../../../ghost/core/server/services/README.md#standard-root-contract)
describes. The inventory test compares the names.

Run from the repository root:

```sh
pnpm nx run ghost:test:unit test/unit/server/services/<name>/index.test.ts
pnpm nx run ghost:test:unit test/unit/boot/
pnpm --filter ghost exec vitest run --config vitest.config.inventory.ts
pnpm lint:oxlint
pnpm lint:boundaries
pnpm check
```

`pnpm lint:oxlint` applies `ghost/service-root-shape` to the root and
`ghost/boot-awaits-service-init` to `boot.js`.
`pnpm lint:boundaries` checks the implementation's imports. The inventory test
checks the directory has an `index.ts` root and that extras match the catalogue.

Commit with the repository commit skill, then run on the committed result:

```sh
pnpm gx services verify <name>
```

It needs a clean tree on a branch that contains the fetched `origin/main`. It
repeats the checks above, runs the full unit suite and confirms a boot test
fails when boot stops waiting for this root's `init()`. Run it again after
every rebase or fix.

Fix failures in the service rather than disabling a check. Report the commands
you ran and anything still failing.
66 changes: 43 additions & 23 deletions .agents/skills/migrate-service/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,9 @@ an execution workflow, not permission to redesign a service's lifecycle. The
[services guide](../../../ghost/core/server/services/README.md) is the authoring
guide; read it rather than copying an earlier migration blindly.

For a new service, use [add-service](../add-service/SKILL.md) to generate and
complete the root instead.

## 1. Establish the starting point

- Read the root and nearest `AGENTS.md`, the
Expand All @@ -20,9 +23,9 @@ guide; read it rather than copying an earlier migration blindly.
- Inspect status, existing branches/worktrees and related PRs. Preserve unrelated
work. Fetch `origin` and start from current `origin/main`; refresh dependencies
with `pnpm bootstrap` in a fresh checkout or after dependency changes.
- Read this service's entry in
`ghost/core/server/services/service-inventory.yaml` and any existing migration
plan. If a plan-registry skill is available, use it to find/update that plan;
- Read this service's entry under `services` in
`ghost/core/server/services/legacy-service-inventory.yaml` and any existing
migration plan. If a plan-registry skill is available, use it to find/update that plan;
do not create a competing plan in the repository.
- Verify prerequisites are merged. An open tests or enforcement PR is not main.
Preparation can proceed against a proposed policy, but record its exact head
Expand Down Expand Up @@ -66,12 +69,14 @@ Do not inject stateless utilities to evade the policy or duplicate shared helper
Inspect the source before adding a library allowance. Justify why the dependency
is a library rather than an application-owned instance, and allow only its exact
entry or file. Include the reason and a boundary regression in the migration PR
that needs the allowance. Assert each rejected target as well as its rule and
source in boundary regressions. Keep allowances out of standalone skill/tooling
PRs.
that needs the allowance. Write out each file the allowance admits in full, as
dependency-cruiser resolves it from source and from built output, in a boundary
regression; `gx services verify` looks for the literal path, not one built from
variables. Assert each rejected target as well as its rule and source. Keep
allowances out of standalone skill/tooling PRs.
Seek review when that distinction is unclear or a broader policy change is
needed; do not widen the rule merely to make lint pass. Normal inventory and
root-shape opt-ins still belong in each migration.
needed; do not widen the rule merely to make lint pass. Deleting the service's
legacy entry still belongs in each migration.

Preserve late acquisition with getters/factories when dependencies are unavailable
at boot. Inspect `pnpm gx services report <name>` and the full
Expand Down Expand Up @@ -146,23 +151,38 @@ preparation. The only new cases permitted in the migration commit are boundary
regressions for new exact dependency allowances. Never weaken assertions,
coverage gates, lint or types to make the refactor pass.

## 5. Update metadata and verify

Update this service's inventory entry: `migrated`, entry points, evidence,
contracts, extras and remaining gaps. Repair affected file references and
startup-order descriptions in other entries mechanically, without changing
their unrelated assessments.
Preserve historical audit provenance;
record the inspected base and distinguish old evidence from new validation.
Do not restore manual totals or erase unrelated backlog items.

Opt the root into `ghost/service-root-shape` in `.oxlintrc.json` as required by
the current configuration; the tooling scope check must agree with the inventory.
`migrated: true` also opts implementations into the boundary checks. Do not claim enforcement passed if that policy was
## 5. Update the inventory and verify

A migrated service is no longer legacy:

- Delete its entry under `services` in the legacy service inventory. Git
history keeps the audit record.
- Delete all its entries from `.dependency-cruiser-known-violations.json`. A
service that is not legacy cannot have any.
- If the root declares extras, move their catalogue to the service's entry in
the inventory's `followUps` section. A suggested future home, and
notes on what `defineService` does not do for the service yet, go there too.
That entry holds nothing else; leave it out when nothing is open.
- Repair affected file references and startup-order descriptions in other
legacy entries mechanically, without changing their unrelated assessments.
An audit SHA you add must be a commit on main: a branch commit disappears on
squash merge.

There is no lint list to update. Deleting the entry applies
`ghost/service-root-shape` to the root and full boundary enforcement to the
implementation. It also applies `ghost/boot-awaits-service-init` and the
standard services boot test: boot must bind the root with `.default` and await
its `init()`, as
[creating a service](../../../ghost/core/server/services/README.md#creating-a-service)
shows. Never add a legacy entry or defer a service's dependency
checks: CI rejects both. Do not claim enforcement passed if that policy was
only checked in a temporary integration or is still awaiting merge.

Run focused tests before/after, relevant real consumer/DB checks, root-shape and
inventory validation, lint/typechecks and the default `pnpm check`. Run one full
Run focused tests before/after, relevant real consumer/DB checks and the default
`pnpm check`, then `pnpm gx services verify <name>` on the committed result. Repeat
`gx services verify` after every rebase or fix: hooks do not run during a rebase.
Before a PR is opened or marked ready, an agent that did not write the change runs
the [verify-service-change skill](../verify-service-change/SKILL.md). Run one full
local validation at a time. Investigate failures from fresh output; a passing
retry or an unchanged file alone does not establish that a failure belongs to
main. Keep unrelated fixes out of the migration.
Expand Down
96 changes: 96 additions & 0 deletions .agents/skills/verify-service-change/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
---
name: verify-service-change
description: Independently verify a service characterization or defineService migration before its pull request is opened or marked ready. Use when checking tests-only characterization or a service migration that someone else wrote.
---

# Verify a service change

Check another author's work from the code and its claims. An author's own results
show what they thought to test, so they cannot show what they missed.

## Start here

Use only:

- the branch or pull request diff
- the PR description, commit messages and inventory changes
- the output of `pnpm gx services verify <service> --json`
- the unchanged service source, its consumers and existing tests in your checkout

Do not read the author's mutation list, a coordinator's summary or an earlier
review. Ignore them if the brief includes them.

Work in your own checkout of the commit, and restore every mutation. Do not commit,
push or edit the branch: report findings to whoever owns it. Run database suites
one at a time.

## Check every change

1. `gx services verify` has no `fail` result.
2. For each `review` line, read the diff and decide whether it is still true. A
stale inventory sentence is a finding.
3. Map every claim to evidence: each inventory sentence added or changed, and each
statement in the PR description and commit messages. "Unchanged" is a claim.
4. Ask whether this is the simplest way. List anything the change does not need.

## Characterization

For each test and inventory sentence, ask: does it do what it says, is it the
simplest way, and is every claim asserted?

Write your own mutations from the production code and run at least one per claim.
Each must fail the test named for that behaviour. Include these variants where
they apply:

- a module loaded at import rather than on use, checked by a test that observes
the load before the module is first required
- every instance of a repeated dependency, not only the first
- a different error with the same message
- the success path as well as each failure path
- a fake clock away from the boundary it is set to
- a chained handler where the test only inspects the first call

Say when fakes hide the risk, such as a test that fakes Express for code whose
regression would only show in a booted app.

## Migration

Fill in one row for each dependency, resource and consumer:

| Item | Old: when and how often resolved | New: when and how often resolved | Read by consumers at | On failure |
| ---- | -------------------------------- | -------------------------------- | -------------------- | ---------- |

Every difference needs a reason in the PR description. Look hardest at:

- work the old root repeated on each boot in one process, now run once
- reads at module load, including route loaders and test harnesses
- fixtures and consumer tests that still use the old shape
- failures that moved between boot and the first request
- anything left half-started when init fails and is retried
- whether order between services has a boot test; the standard services boot
test only covers that boot waits for this root and fails when it fails

Then check the shape of the change:

- A stateless utility must be imported under an exact allowance, not injected.
- Injected logging is `GhostLogger` or a `Pick` of it, and class tests use
`createLoggingFake()`.
- A root that still builds itself in two steps is not finished.

Note in the report if consumer files changed outnumber the service's own files, or
if the inventory disposition is not `migrate`. Both can mean the service should not
be migrated this way, so finish the review and raise them for the owner.

## Report

| Claim or row | Evidence | Mutation and result | Finding | Severity |
| ------------ | -------- | ------------------- | ------- | -------- |

Use three severities:

- **Blocker:** a regression, a broken consumer, or a claim that is false.
- **Should fix:** a claim the tests do not prove, or stale text.
- **Note:** a gap the change does not claim to close.

Finish with a verdict. Say "ready" when no row is a blocker or an unresolved "should
fix", and list anything you did not run.
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
## 0.2.10

### Patch Changes

- Bumped TryGhost framework dependencies to their latest versions

- Bumped TryGhost framework dependencies to their latest versions
5 changes: 5 additions & 0 deletions .changeset/changelogs/@tryghost!adapter-base-sso@0.1.9.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
## 0.1.9

### Patch Changes

- Bumped TryGhost framework dependencies to their latest versions
5 changes: 5 additions & 0 deletions .changeset/changelogs/@tryghost!kg-card-factory@5.2.10.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
## 5.2.10

### Patch Changes

- Updated dependencies
5 changes: 5 additions & 0 deletions .changeset/changelogs/@tryghost!kg-clean-basic-html@4.3.10.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
## 4.3.10

### Patch Changes

- Updated dependencies
5 changes: 5 additions & 0 deletions .changeset/changelogs/@tryghost!kg-converters@1.2.10.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
## 1.2.10

### Patch Changes

- Updated dependencies
7 changes: 7 additions & 0 deletions .changeset/changelogs/@tryghost!kg-default-cards@10.3.11.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
## 10.3.11

### Patch Changes

- Updated dependencies

- Updated TryGhost SDK dependencies
11 changes: 11 additions & 0 deletions .changeset/changelogs/@tryghost!kg-default-nodes@2.3.1.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
## 2.3.1

### Patch Changes

- Updated dependencies

- Updated dependencies

- Fixed links whose query strings look like HTML entities without a semicolon, such as `&region=` or `&para=`, being corrupted in rendered cards.

- Updated TryGhost SDK dependencies
Loading
Loading