@moifort/stack 0.0.0-stage → 0.1.0

package/rules/16-routines.md

@@ -0,0 +1,69 @@
+# Scheduled routines
+
+Claude tasks that run on a schedule. Each one states its cadence, where it runs, its
+repositories, what it may do, and what it never does. A routine's push is the one exception to
+"never push unasked" ([02-commits.md](02-commits.md#push)).
+
+## Where a routine runs
+
+**In the cloud by default**, as a cloud scheduled task on the person's claude.ai account: it runs
+when the machine is off, from a fresh clone of the repositories, with the connectors and the
+environment variables the task is given, and pushes as the person's GitHub identity. Minimum
+interval one hour. What a cloud run does not have: the machine's files (no keychain, no local
+`.env`, no observer `gcloud` configuration), Xcode and the simulators, the person's browser
+sessions. So:
+
+- a cloud routine gets its credentials as environment variables of its cloud environment (the
+  Sentry token, the observer service account key, the store API key), never from a file in a
+  repository;
+- a change a cloud routine cannot verify itself (an app fix needs Xcode) is pushed as a branch
+  with a pull request, and merged by the next pass once CI built it, instead of going to
+  `main` directly;
+- a routine that needs the machine (a simulator, the keychain, a capture) is a **desktop**
+  scheduled task, which runs only while the app is open and the Mac awake, and catches up one
+  missed run on wake.
+
+Each routine's prompt names its runtime in its frontmatter (`runtime: cloud` or `desktop`); the
+install and upgrade skills create a cloud task through the `/schedule` tooling or a desktop task
+through the app, and update it on a version change.
+
+## When a routine cannot decide
+
+A routine never asks the person in its own session: nobody is there. It **opens a GitHub issue**
+in the project, labelled `decision`, with the question, the options and what it will do by
+default if nobody answers, and references it from the pull request or the report. GitHub
+notifies the person on their phone and desktop; the answer is written in the issue; the next pass
+reads the issues labelled `decision` that got an answer and acts on them. A push notification to
+the phone (`PushNotification`) is sent in addition when the session can, best effort: it needs
+Remote Control connected and is not reliable from a scheduled run.
+
+| Routine | Cadence, runtime | Does | Never |
+|---|---|---|---|
+| Sentry triage | Every six hours, cloud, every app | Reads unresolved issues, fixes the cause with a verified commit, pushes to `main`, watches CI, marks `resolvedInNextRelease` | Marks plain `resolved`; touches an issue it did not fix |
+| Daily health | Noon, cloud, per app | Through the observer account: spend from the billing export, performance, monitoring; fixes and pushes what is code; reports cold starts as a figure | Proposes a warm instance; reads errors (Sentry's job) |
+| Upgrades | Every morning after Renovate, cloud | Stack pull requests (label `stack`): the `stack-upgrade` skill, sync, migrations with their checks, merge when every migration is safe and CI is green. Major dependency pull requests: reads the changelog and migration guide, applies the code changes, deploys to staging, merges when CI and staging are green, otherwise comments and leaves open | Force-merges; edits rules; touches a pull request without one of those labels |
+| Deprecations | Monthly, cloud, per app | Runs the deprecations script, removes what is removable, raises the build floor, pushes, watches CI and Deploy | Removes anything in grace or still asked; raises the floor by hand |
+
+## Shipped by the package, installed on the machine
+
+The routines' prompts live in `routines/` of this package, with placeholders for the project's
+facts. A routine is `scope: machine` (one instance for every project: Sentry triage, stack
+upgrades) or `scope: project` (one per project: daily health). `sync` renders them into
+`~/.claude/scheduled-tasks/<id>/SKILL.md` (`<id>-<app>` for a project routine); the
+`stack-install` and `stack-upgrade` skills then create the scheduled task when it does not exist
+and update its prompt and cadence when it does, through the app's scheduled-tasks tools. A routine
+is never edited by hand on the machine: the change goes into the package and reaches every machine
+and project at the next version.
+
+## Rules
+
+- A routine verifies before committing and watches CI after pushing like any session; what it
+  cannot verify where it runs goes through a pull request and CI.
+- A routine pushes at most three commits per pass (Sentry) or one (the others), and a report
+  that says "pushed" always carries the CI result per workflow.
+- A routine never asks the person in its session; a decision becomes a `decision` issue.
+- A routine reads production through the observer account, never through the person's login.
+- The daily health routine checks the last run of every other routine and reports one that
+  missed two cadences: nothing else watches the routines.
+- The routine's prompt lives in the machine's scheduled tasks; the skills it follows are shipped
+  by this package.

package/rules/17-landing.md

@@ -0,0 +1,76 @@
+# Landing page
+
+Every product gets a page that sells it. It lives in the project's repository (`site/`), static,
+no build step, published by the Pages workflow on the project's domain
+(`<app>.polyforms.co`), next to the privacy policy and the support page the store requires.
+Shiori's page is the reference.
+
+## What it is for
+
+One job: a person who does not know the product understands in ten seconds what it does for
+them, and in two minutes wants to install it. Everything on the page serves that; nothing explains
+how the product is built.
+
+## Structure
+
+In this order, each section one screen tall at most:
+
+1. **Hero.** A title of a few words that says the benefit, not the feature ("Your library in your
+   pocket."), a subtitle of two or three short sentences, the store badge, the platform line. The
+   product's own home screen beside it.
+2. **Tour.** The product screen by screen: for each, a title that is a promise ("One photo, the
+   rest follows."), two sentences of what happens, the real screen. The essentials only, in the
+   order a new user meets them.
+3. **Features.** Everything else the product does, as cards with the app's own icons and one
+   sentence each. The section lead does not repeat the hero.
+4. **Compare.** Free against paid, as a feature table, the way the store's paywall presents it.
+   The paid plan's name and prices are the store's.
+5. **FAQ.** The questions a careful buyer asks: price, data, privacy, deletion, what happens
+   offline, what the AI does with a photo. Short answers.
+6. **Download.** The free plan set beside the paid one, the store badge again.
+
+Then a footer: privacy policy, support, the company.
+
+## Copy
+
+The tone of [08-copy.md](08-copy.md) applies in full, plus:
+
+- **Benefit first.** Every title says what the person gets; the feature is in the sentence
+  under it.
+- **Short.** A title under eight words, a paragraph under three sentences. The whole page reads
+  in two minutes.
+- **The product's name is not in the copy.** It is in the logo and the title tag; the sentences
+  talk to the reader about their life, not about the app.
+- **Concrete.** Numbers and examples over adjectives: "thirty books without pulling out a single
+  one", not "fast and powerful".
+- **Honest.** Nothing the shipped product does not do. A feature that is coming is not on the
+  page.
+
+## Screens and images
+
+- **Real screens only**, from the showcase captures ([07-appstore.md](07-appstore.md)), never a
+  mock-up drawn by hand or by a model. Each image has an `alt` that says what the screen shows.
+- **The app's own icons** (its SF Symbols) for every card, so the page and the app share a
+  visual language.
+- **Real people's data** on the screens is shown with their agreement, and reads as real (a
+  friend's actual reading), never as lorem ipsum.
+- An Open Graph image and a favicon derived from the app icon.
+
+## Languages
+
+The page is written in the source language in the HTML; `i18n.js` carries the translation for
+every element marked `data-i18n` (text), `data-i18n-alt` (image alt), `data-i18n-aria`,
+`data-i18n-src` (a screen or a cover swapped for its edition in that language), applied before the
+first paint from the browser's language. Every screen and mock is translated, down to the spines
+on a shelf: a French screen on an English page breaks the illusion. A language switch is visible
+in the nav.
+
+## Publishing and checks
+
+- `site/**` triggers the Pages workflow and nothing else; never `[skip ci]` on a site commit
+  ([04-push.md](04-push.md)).
+- Before pushing, open the page in the built-in browser in both languages, at phone and desktop
+  widths, and send a screenshot: the page is a UI change like any other
+  ([01-workflow.md](01-workflow.md#screenshot-after-every-ui-change)).
+- The privacy policy page states what is collected, by whom, for how long, and how to delete the
+  account, in the source language and in English; the store listing links to it.

package/skills/appstore/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: appstore
+description: Use when preparing an App Store or TestFlight step of a Polyforms app (listing, captures and panels, first subscription submission, release notes, signing secrets) or when App Store Connect refuses something. The long form of stack rule 07-appstore.
+---
+
+# App Store Connect
+
+## The release, in order
+
+1. `bun run deprecations`, remove what is removable, floor raised by the script's value.
+2. Notes in `CHANGELOG.md` and each `CHANGELOG.<lang>.md` (rule 06), French shown and
+   approved in the conversation.
+3. Push `main`, watch Deploy.
+4. Captures and panels only if the person asked.
+5. `git tag ios-v<version> && git push origin ios-v<version>`; watch Release to the end.
+
+## Secrets the iOS workflows read
+
+| Secret | What |
+|---|---|
+| `ASC_KEY_ID`, `ASC_ISSUER_ID`, `ASC_KEY_P8` | The team's App Store Connect API key |
+| `IOS_DIST_CERT_P12`, `IOS_DIST_CERT_PASSWORD` | The Apple Distribution certificate, base64 |
+| `IOS_PROVISION_PROFILE` | The App Store profile named `<App> App Store`, base64 |
+| `IOS_GOOGLE_SERVICE_INFO_PLIST` | The Firebase plist, base64 |
+| `IOS_SENTRY_DSN`, `SENTRY_AUTH_TOKEN` | Reporting and dSYM upload |
+
+## What has no API
+
+Done once, in the built-in browser, signed in as the person: the app record, the price
+schedule, the App Privacy answers, accepting a new agreement (account holder only).
+
+## First subscription
+
+The API refuses every direct route (`FIRST_SUBSCRIPTION_MUST_BE_SUBMITTED_ON_VERSION`,
+`SUBSCRIPTION_GROUP_SUBMISSION_NOT_ALLOWED`). The sequence that works:
+1. API: create a draft `reviewSubmission` (platform IOS), add the `appStoreVersion` as an item.
+2. Browser: the subscription group's page, "Add for review" is a dropdown, pick the draft;
+   then each subscription's page, same dropdown, same draft.
+3. The draft's "Submit for review" becomes active; submit.
+Cancelling takes a minute; a draft without items cannot be cancelled, delete its items.
+
+## Listing traps
+
+- A name held by another account in a locale answers 409: "Name: What it does".
+- Keywords: 100 characters, checked by App Store Connect.
+- A locale with release notes but no listing is created empty and the submission is refused:
+  add a locale's `infra/fastlane/metadata/<locale>/` before its notes.
+- The product page header (16:9) is dragged in by hand: there is no API for it.
+
+## TestFlight
+
+Adding a tester who belongs to another app's group answers 409: create the tester with
+`POST /v1/betaTesters` carrying the group relationship.

package/skills/domain/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: domain
+description: Use when creating or changing a backend domain (types, primitives, command, query, repository, business rules, use case, migration) in a Polyforms Nitro + Firestore project. The long form of stack rule 09-backend.
+---
+
+# Create or change a domain
+
+The `user` domain under `server/domain/user/` is the reference: copy its shape.
+
+## 1. Files
+
+```
+server/domain/<domain>/
+  types.ts            branded types and the aggregate; the file IS the spec of the model
+  primitives.ts       one Zod constructor per brand
+  command.ts          writes, bare exported functions
+  query.ts            reads, bare exported functions
+  business-rules.ts   optional: pure functions, no I/O, full coverage
+  use-case.ts         optional: orchestration across domains, no business logic of its own
+  infrastructure/
+    repository.ts     the only file that touches Firestore
+    graphql/{enums,types,inputs,queries,mutations}.ts
+```
+
+Callers import a module under the domain's name: `import * as OrderCommand from
+'~/domain/order/command'`, then `OrderCommand.place(...)`. Never a TypeScript `namespace`.
+
+## 2. Types and primitives
+
+```ts
+// types.ts
+import type { Brand } from 'ts-brand'
+import type { UserId } from '~/domain/shared/types'
+
+export type OrderId = Brand<string, 'OrderId'>
+export type Quantity = Brand<number, 'Quantity'>
+
+export type Order = {
+  id: OrderId
+  userId: UserId          // every private document names its owner
+  quantity: Quantity
+  note?: string           // absence is an optional field, never null
+  createdAt: Date
+}
+
+// primitives.ts
+export const Quantity = (value: unknown) =>
+  make<QuantityType>()(z.number().int().min(1).max(999).parse(value))
+```
+
+Never `as Quantity` on untrusted input: the constructor. Generic brands (`UserId`, `Count`,
+`Eur`, `Year`, `Day`) come from `~/domain/shared`.
+
+## 3. Repository
+
+```ts
+const orders = () => db().collection('orders').withConverter(genericDataConverter<Order>())
+
+export const findAllByUser = (userId: UserId): Promise<Order[]> =>
+  memoizedPerRequest(`order:all:${userId}`, async () =>
+    (await orders().where('userId', '==', userId).get()).docs.map((doc) => doc.data()),
+  )
+
+export const save = async (order: Order) => {
+  await orders().doc(order.id).set(withoutAbsentFields(order))
+  evictFromRequestCache(`order:all:${order.userId}`)
+  return order
+}
+```
+
+- Flat collections, `userId` on every private document, every query filters on it.
+- A memoised read is evicted or revised by every write under its key.
+- Several writes: `atomically(batch => ...)`; read-modify-write: `transactionally(tx => ...)`;
+  mass delete: `deleteInBatches`.
+- Filter, sort and page in Firestore. A new composite query adds its index to
+  `firestore.indexes.json` in the same commit.
+
+## 4. Query and command
+
+```ts
+// query.ts
+export const byId = async (userId: UserId, id: OrderId) => {
+  const order = await repository.findBy(userId, id)
+  if (!order) return 'not-found' as const
+  return order
+}
+
+// command.ts
+export const place = async (userId: UserId, quantity: Quantity) => {
+  if (await isOverLimit(userId)) return 'limit-reached' as const
+  return repository.save({ id: OrderId(randomUUID()), userId, quantity, createdAt: new Date() })
+}
+```
+
+One literal per expected failure, `as const`; `throw` only for an impossible state. A
+function's name is the business concept (`place`, not `createOrder`, never `handleX`).
+
+## 5. Account deletion
+
+A domain with private documents exports `deleteAllForUser(userId)` from its command and adds
+it to the parallel block of `server/domain/user/use-case.ts`.
+
+## 6. Tests
+
+| File | What it proves |
+|---|---|
+| `primitives.unit.test.ts`, `business-rules.unit.test.ts` | Every rule, every boundary |
+| `command.int.test.ts`, `query.int.test.ts` | Through the real repository against the fake Firestore; read budgets with `fake.docReads` and `fake.queryReads` |
+| `infrastructure/graphql/*.feat.test.ts` | The API contract: answer shape and values, error codes, read budget |
+
+```ts
+mock.module('~/system/firebase', () => ({ db: fakeDb }))
+const OrderCommand = await import('~/domain/order/command')
+```
+
+Dates are asserted with `toEqual` on the field, never inside `toMatchObject`. Run the three
+families separately.
+
+## 7. Migration
+
+Renaming, restructuring, changing enum values or removing data needs a migration:
+`server/system/migration/migrations/NNN-<what-it-does>.ts` exporting a `Migration`
+(`version`, `name`, `migrate({ db })` returning `{ ok: true, transformed }`), its
+`.int.test.ts` against the fake Firestore, and its line in `migrations/index.ts`. Idempotent:
+run twice, it changes nothing the second time. The Deploy workflow runs it; never by hand.
+
+## Checklist
+
+- [ ] Types branded, absence optional, `userId` on private documents
+- [ ] One constructor per brand, one GraphQL scalar per brand (graphql skill)
+- [ ] Repository private, memoised reads evicted on write
+- [ ] Outcomes as literals, mapped exhaustively in the resolver
+- [ ] `deleteAllForUser` wired into account deletion
+- [ ] Indexes added for new queries
+- [ ] Unit, int and feat tests, read budgets asserted
+- [ ] `bun run generate:graphql`, `bun run schema:check`, preflight green

package/skills/graphql/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: graphql
+description: Use when adding or changing a GraphQL type, field, query, mutation, input, enum or scalar in a Polyforms Pothos schema, or deprecating one. The long form of stack rules 09-backend and 11-ops (API evolution).
+---
+
+# Change the GraphQL API
+
+Domain first, schema second: the domain is the source of truth.
+
+## Where things go
+
+`server/domain/<domain>/infrastructure/graphql/` holds `enums.ts`, `types.ts`, `inputs.ts`,
+`queries.ts`, `mutations.ts`, each imported in order by `server/domain/shared/graphql/schema.ts`
+(a lender before a borrower). One endpoint, `POST /graphql`.
+
+## A scalar per brand
+
+```ts
+// builder.ts: Scalars: { Quantity: { Input: Quantity; Output: Quantity } }
+// scalars.ts
+scalar('Quantity', 'How many, 1 to 999. Example: 3.', Quantity)
+```
+
+The scalar reuses the brand's constructor: an invalid value is a `BAD_USER_INPUT` before the
+resolver runs, and resolvers never call a constructor themselves.
+
+## Types, queries, mutations
+
+```ts
+export const OrderType = builder.objectRef<Order>('Order').implement({
+  description: 'One order of the signed-in user.',
+  fields: (t) => ({
+    id: t.expose('id', { type: 'OrderId', description: 'Opaque identifier.' }),
+    note: t.exposeString('note', { nullable: true, description: 'Absent when none was written.' }),
+  }),
+})
+
+builder.mutationField('placeOrder', (t) =>
+  t.field({
+    type: OrderType,
+    description: 'Place an order. Fails with LIMIT_REACHED past the monthly limit.',
+    args: { quantity: t.arg({ type: 'Quantity', required: true, description: 'How many.' }) },
+    resolve: async (_root, { quantity }, { userId }) =>
+      match(await OrderCommand.place(userId, quantity))
+        .with('limit-reached', () => domainError('LIMIT_REACHED', 'Monthly limit reached'))
+        .with(P.not(P.string), (order) => order)
+        .exhaustive(),
+  }),
+)
+```
+
+- Every type, field, argument and enum value has a description: it is the documentation
+  the app developer reads.
+- Nullability is off by default: a field that may be absent says `nullable: true`.
+- Outcomes map with `match().exhaustive()`; `notFound`, `badUserInput`, `forbidden`,
+  `domainError(code, message)` from `shared/graphql/errors.ts`. A consultation that finds
+  nothing answers `null`.
+- Optional inputs pass through `stripNulls` before the domain.
+- A nested field that needs another document: denormalise it on the parent, or add a
+  per-request loader to the context before shipping it. Never one read per parent row.
+
+## After a change
+
+```bash
+bun run generate:graphql      # shared/schema.graphql, committed whole, never hunk-split
+bun run schema:check          # refuses a breaking change that was not deprecated
+bun run ios:codegen           # when the app uses it
+```
+
+## Deprecate, never remove
+
+When the app stops using a field or an argument, in the same commit:
+
+```ts
+oldField: t.exposeString('old', {
+  deprecationReason: 'since 1.3 (2026-10-21): use newField',
+  description: '...',
+})
+```
+
+The monthly deprecations routine removes it once a build without it has been on sale for
+fourteen days and raises the build floor. Never remove by hand, never raise the floor by hand.
+Adding a field, a query, a mutation, an optional argument or an enum value needs nothing.

package/skills/ios-feature/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: ios-feature
+description: Use when adding or changing an iOS screen or feature in a Polyforms SwiftUI app (screen, page, organism, ViewModel, client, API, fixtures, previews, tests), or taking its screenshot. The long form of stack rule 10-ios.
+---
+
+# Add an iOS feature
+
+`Features/Settings/` is the reference: copy its shape.
+
+## Files
+
+```
+Features/<Domain>/
+  <Feature>Screen.swift       connected: ViewModel, tasks, change notices, navigation, sheets
+  <Feature>ViewModel.swift    @MainActor @Observable, init(client:), state private(set)
+  <Domain>Client.swift        struct of @Sendable closures, .live and .preview
+  <Domain>API.swift           the only file that sees <App>GraphQL types; returns app models
+  <Domain>Models.swift        Sendable app models
+  <Domain>Fixtures.swift      static let preview data, shared by previews and tests
+  GraphQL/<Domain>.graphql    operations
+  components/organisms/       sections, rows, cards: may take a model, map to primitives
+  components/pages/           whole screens, pure, one onAction over an enum
+```
+
+## The page and its screen
+
+```swift
+enum OrdersAction { case open(Order.ID); case delete(Order.ID); case refresh }
+
+struct OrdersPage: View {
+    let orders: [Order]
+    let isLoading: Bool
+    let errorMessage: String?
+    let onAction: (OrdersAction) async -> Void
+    var body: some View { /* list, EmptyState, EmptyState.failure, .refreshable */ }
+}
+
+struct OrdersScreen: View {
+    @State private var viewModel = OrdersViewModel(client: .live)
+    @State private var opened: Order.ID?
+    var body: some View {
+        OrdersPage(orders: viewModel.orders, isLoading: viewModel.isLoading,
+                   errorMessage: viewModel.errorMessage) { action in
+            switch action {
+            case let .open(id): opened = id
+            case let .delete(id): await viewModel.delete(id)
+            case .refresh: await viewModel.load()
+            }
+        }
+        .task { await viewModel.load() }
+        .onReceive(NotificationCenter.default.publisher(for: .dataDidChange)) { _ in
+            Task { await viewModel.load() }
+        }
+    }
+}
+```
+
+## Loading rules in code
+
+- Nothing yet: `ProgressView()` in the body. Failure over nothing: `EmptyState.failure`.
+  Failure over rows: keep the rows, `reportError` only.
+- Every mutation through `GraphQLHelpers.perform` (it posts `.dataDidChange`); a mutation
+  that changes nothing a list shows passes `changesData: false`.
+- A button that waits: `AsyncButton` / `AsyncToolbarButton`.
+- Lists: `CursorPage`, a `LoadMoreRow`-style closer, a generation token in the ViewModel.
+
+## Patterns
+
+A list row, a detail page (fiche), a tab's main screen, a form: as described in rule 10-ios,
+"Screen patterns". The toolbar of a detail page: `xmark` left; on the right the one repeated
+action as an icon, then a `…` menu, edit first, delete last and red.
+
+## Strings
+
+Written in French in the code. After the build: `bun run ios:strings -- --write`, fill the
+English of each new key in `Localizable.xcstrings`, rerun without `--write` until it reports
+every string translated, commit the catalogue with the code.
+
+## Tests
+
+`<App>Tests/<Domain>/<Feature>ViewModelTests.swift` with Swift Testing: the client built
+inline from `.preview` with one closure overridden; `Boom`, `Flag`, `Calls` from
+`Support/TestDoubles.swift`. Never a test of a `body`.
+
+## Screenshot
+
+1. A temporary launch argument in `App.swift` that shows the page with its fixtures
+   (`if CommandLine.arguments.contains("-shot-orders") { OrdersPage(orders: Order.previews, ...) }`).
+2. Build into `/tmp/<app>-shot-<topic>` with `SWIFT_ENABLE_EXPLICIT_MODULES=NO`, install on
+   the reference simulator, launch with the argument, `xcrun simctl io <udid> screenshot`.
+3. Revert the harness before the commit; keep fixtures and previews.
+4. Check the design conventions, send the screenshot, wait for approval.
+
+Then `bun run ios:components` (pure and previewed) and `bun run ios:test`.

package/skills/stack-install/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: stack-install
+description: Use to start a new Polyforms project, or to bring an existing project onto the @moifort/stack package (init, templates, Renovate, CI check, routines).
+---
+
+# Install the stack
+
+## New project
+
+```bash
+mkdir <app> && cd <app> && git init
+bunx @moifort/stack init --stacks backend,ios --set APP_TAGLINE="..."
+bun install
+```
+
+Stacks: `backend`, `ios`, `ai`, `paid`, `admin`, `e2e`, `site`. `init` asks for every
+placeholder the chosen stacks use that it cannot derive; derived ones (name, slug, bundle id,
+repository) come from the folder name and can be overridden with `--set NAME=value`.
+
+Then, in order, verifying each:
+1. `bun run preflight` green.
+2. `bun run ios:build` and `bun run ios:test` green (ios stack).
+3. `bunx @moifort/stack bootstrap <app>` creates GitHub, Sentry, Renovate, GCP, and pushes
+   the first commit; the Deploy workflow does the first deploy. It ends with the list of
+   what needs the person.
+4. Write the deployed function URL into `ios/<App>/Shared/APIClient.swift`.
+5. Create or update the scheduled routines from `stack/routines/` (rule 16).
+6. Fill `project-context.md`.
+
+## Existing project
+
+`init` never overwrites: it writes what is missing and lists what it kept. Then write a
+batched plan, one batch per domain (CI, Terraform, Sentry, iOS shell, scripts), comparing each
+kept file with its template and bringing the project in line batch by batch, each batch
+verified and committed on its own.

package/skills/stack-upgrade/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: stack-upgrade
+description: Use when a Renovate pull request bumps @moifort/stack in a project, to sync the rules and apply the version's migrations.
+---
+
+# Upgrade the stack in a project
+
+1. Confirm the pull request bumps `@moifort/stack`. Otherwise this skill does not apply.
+2. In the pull request's branch: `bun install`, `bunx stack sync`, commit
+   `chore(stack): sync to <version>`.
+3. `bunx stack migrations <old> <new> --json`: the migrations between the two versions, for
+   this project's stacks, in order.
+4. For each migration, in order:
+   - read the rule it points to and its body (what changes, how to find it, how to fix it,
+     when it does not apply);
+   - find the affected code, fix it, run its `check` command until it exits 0;
+   - commit `refactor(<scope>): <migration id>`;
+   - when it does not apply, note why and commit nothing.
+5. `bun run preflight` (and `bun run ios:build` with the ios stack). A failure caused by a
+   migration: revert that migration's commit and mark it `needs review`.
+6. If the version changed a routine (`stack/routines/`), update the scheduled task.
+7. Comment on the pull request: one line per migration, its outcome (applied, not applicable,
+   needs review) and the files touched.
+8. Merge only when every migration is `safe`, each applied or not applicable, every `check`
+   passes and CI is green. Otherwise label `stack:review` and leave it open.
+
+Never edit `stack/` by hand, never edit a rule from a project: a wrong rule is reported.

package/src/catalogue.ts

@@ -0,0 +1,33 @@
+import type { Stack } from '~/config'
+
+/** Which stacks a shipped file needs; absent means it always applies. */
+export const RULE_STACKS: Record<string, Stack[]> = {
+  '07-appstore.md': ['ios'],
+  '09-backend.md': ['backend'],
+  '10-ios.md': ['ios'],
+  '11-ops.md': ['backend'],
+  '12-ci.md': ['backend', 'ios'],
+  '13-ai.md': ['ai'],
+  '14-infra.md': ['backend'],
+  '17-landing.md': ['site'],
+}
+
+export const ROUTINE_STACKS: Record<string, Stack[]> = {
+  'daily-health.md': ['backend'],
+  'deprecations.md': ['backend', 'ios'],
+}
+
+export const SKILL_STACKS: Record<string, Stack[]> = {
+  domain: ['backend'],
+  graphql: ['backend'],
+  'ios-feature': ['ios'],
+  appstore: ['ios'],
+}
+
+export const HOOK_STACKS: Record<string, Stack[]> = {
+  'shutdown-simulators-after-push.sh': ['ios'],
+}
+
+/** A file applies when it needs no stack, or when the project has at least one of the stacks it names. */
+export const applies = (needs: Stack[] | undefined, stacks: readonly Stack[]): boolean =>
+  needs === undefined || needs.some((stack) => stacks.includes(stack))

package/src/config.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod'
+
+export const STACKS = ['backend', 'ios', 'ai', 'paid', 'admin', 'e2e', 'site'] as const
+export type Stack = (typeof STACKS)[number]
+
+export const StackConfig = z.object({
+  stacks: z.array(z.enum(STACKS)).default([]),
+  placeholders: z.record(z.string(), z.string()).default({}),
+  exclude: z.array(z.string()).default([]),
+})
+export type StackConfig = z.infer<typeof StackConfig>
+
+export const CONFIG_FILE = 'stack.config.json'
+
+export const readConfig = async (projectDir: string): Promise<StackConfig> => {
+  const file = Bun.file(`${projectDir}/${CONFIG_FILE}`)
+  if (!(await file.exists()))
+    throw new Error(`${CONFIG_FILE} not found in ${projectDir}: run init first`)
+  return StackConfig.parse(await file.json())
+}