@connextar/house 0.15.0 → 0.15.1

package/README.md

@@ -584,6 +584,14 @@ runbook — is [`docs/ReleaseProcess.md`](docs/ReleaseProcess.md), shipped in th
 package. Each app's own `docs/operations/ReleaseProcess.md` links to it and adds
 only what is its own: its public API, its trigger documents, its history note.
 
+Beside it, [`docs/RoutineOperations.md`](docs/RoutineOperations.md) is the method
+for the recurring checks that keep an app ready, aligned and compliant — security
+rounds, release gates, bills, backups, the privacy policy against the code — each
+with when it last ran and when it's next due. An app copies
+[`docs/templates/RoutineOperations.md`](docs/templates/RoutineOperations.md) to its
+own `docs/operations/RoutineOperations.md`, which holds only its register and run
+log, and its `AGENTS.md` tells every agent to read the Next due column first.
+
 ### `@connextar/house/changelog`
 
 `<Changelog releases={CHANGELOG} />` — the body of a `/changelog` page. Each
@@ -2079,7 +2087,10 @@ Then, per module the app takes up:
    §7: the old entries become numbered releases once, `lib/release.test.ts` guards
    them from then on, and the app's own `docs/operations/ReleaseProcess.md` says
    only what is its own.
-5. **Gates, then the pages.** `npm run check`, `npm test`, `npm run build`, and
+5. **Routine operations** follow [`docs/RoutineOperations.md`](docs/RoutineOperations.md):
+   copy the template to `docs/operations/RoutineOperations.md`, fill the register
+   from its §5, and add its §6 pointer to `AGENTS.md`.
+6. **Gates, then the pages.** `npm run check`, `npm test`, `npm run build`, and
    grep the built CSS for a class that only the package uses — the one check that
    proves step 1.
 

package/docs/RoutineOperations.md

@@ -0,0 +1,140 @@
+# Routine Operations
+
+> The method every Connextar app uses to keep its recurring checks in one place: what each one is for, how often it runs, how to run it, when it last ran and what it found, and when it's next due. Scheduled checks get lost in day-to-day work; a register that every task starts by reading is what stops that. Shared by the cohort and shipped inside `@connextar/house`, beside [ReleaseProcess.md](ReleaseProcess.md); each app keeps a `docs/operations/RoutineOperations.md` that holds its own register and run log.
+
+_First written for AltEd on 2026-10-16 (its v0.116.0) and generalised for the cohort the same day._
+
+---
+
+## 0. What each app's own document says
+
+This document is the method. An app's `docs/operations/RoutineOperations.md` links here and holds three things nobody else can write:
+
+1. **Its register** — one row for every routine the app has (§2), manual and automated.
+2. **Its run log** — one line for every run (§3, step 5), newest first.
+3. **Its standing go-aheads** — any routine the owner has said may read or write production without asking each time, recorded on that routine's row.
+
+Start it from [templates/RoutineOperations.md](templates/RoutineOperations.md): copy it to `docs/operations/RoutineOperations.md`, put the app's name in the title, and fill the register (§5 lists the rows most apps start with). Then add the pointer in §6 to the app's `AGENTS.md`.
+
+The method is not copied into the app. If it needs to change, change it here, so every app changes with it.
+
+---
+
+## 1. What a routine is
+
+A **routine** is any check or chore that has to happen again and again, on a calendar or on a trigger, whether or not anything is broken. It belongs on the register if forgetting it would cost something: a security gap, a wrong price, a bill, a broken promise in the privacy policy, a stale document.
+
+There are two kinds:
+
+- **Manual:** a person or an agent runs it and records the result. Security rounds, a pricing or usage baseline, the month's bill check.
+- **Automated:** the app runs it by itself on a schedule. Scheduled jobs and crons. The register still lists these, because someone has to look at whether they're running.
+
+---
+
+## 2. The register
+
+Every routine has one row, with:
+
+| Field        | What it holds                                                                                               |
+| ------------ | ----------------------------------------------------------------------------------------------------------- |
+| **ID**       | `OPS-nn`. Never reused, so the run log can point at it.                                                     |
+| **Routine**  | Its name, in plain words.                                                                                   |
+| **Why**      | What goes wrong if it's skipped.                                                                            |
+| **When**     | A calendar cadence ("monthly, mid-month") or a trigger ("after every 5 feature tranches", "every release"). |
+| **How**      | The command or runbook, and anything it must never do (for example, write to production).                   |
+| **Record**   | Where the full result goes: a document, a dashboard.                                                        |
+| **Last run** | Date, version and a one-line result, or "Not recorded".                                                     |
+| **Next due** | A date, or the trigger that makes it due.                                                                   |
+| **Status**   | One of the keys below.                                                                                      |
+
+### Status keys
+
+| Status         | Meaning                                                         |
+| -------------- | --------------------------------------------------------------- |
+| ✅ On schedule | Ran when due; next run not yet due.                             |
+| 🟨 Due         | Due now, or due by the next release.                            |
+| 🟥 Overdue     | Past its date or trigger and not run.                           |
+| ⏰ Scheduled   | A run is booked, for example a scheduled task (§4).             |
+| 🤖 Automated   | The app runs it itself; the row is about watching it.           |
+| ⚪ Proposed    | Suggested, not yet agreed by the owner. Not counted as overdue. |
+| 🧊 Paused      | Deliberately off, with the date and reason recorded.            |
+
+### How the register is laid out
+
+- **Manual routines** — the full table, every field above.
+- **Automated routines** — a shorter table (ID, job, what it does, when, status), headed by a sentence saying where to watch them: the app's job-health page, its operational summary email, its host's cron dashboard. Say how often to look (at least weekly) and when to look sooner.
+- **Paused** — ID, routine, why paused, since.
+
+---
+
+## 3. Running a routine
+
+1. **Check it's due.** At the start of any piece of work, read the register's **Next due** column. A 🟨 Due or 🟥 Overdue routine runs before new feature work, or the owner says why not.
+2. **Run it exactly as its How column says.** If the How has gone stale, fix the How first.
+3. **Never write to production as part of a routine** unless its How says so and the owner has said yes for this run. Reads against production need the owner's go-ahead too, unless the row records a standing one.
+4. **Record the full result where its Record column says.**
+5. **Add a line to the run log:** date, ID, who ran it, the result in a sentence, and any follow-up.
+6. **Update the row:** Last run, Next due, Status.
+7. **Act on findings** by the rules of the routine's own record. For a security round: Critical and High get fixed before anything else.
+8. **Release if a status document changed**, following [ReleaseProcess.md](ReleaseProcess.md).
+
+---
+
+## 4. Adding, changing, retiring and booking
+
+### Adding or changing a routine
+
+- Add a row with the next free ID. A new routine starts ⚪ Proposed until the owner agrees its cadence.
+- When something new needs regular attention (a new paid service, a new scheduled job, a new legal promise), add it to the register **in the same change set that creates it**.
+- A change to a routine's cadence or How is a change to its row, with a run-log line if it follows from a run.
+
+### Retiring a routine
+
+Set it to 🧊 Paused and move it to the Paused table, with the date and the reason. Don't delete it: the run log still points at it, and IDs are never reused.
+
+### Booking runs
+
+A routine with a calendar cadence should have its next run booked, not just remembered. Book it as a scheduled task in Claude, or as a calendar reminder for a person, name the booking on the row's **Next due** ("2026-11-15 09:00, scheduled task `app-pricing-baseline`"), and set the row to ⏰ Scheduled.
+
+Whatever runs it follows this document: record, log, update the row. A booked run that touches production says so in its own instructions, and leaves its result uncommitted for review.
+
+---
+
+## 5. Rows most apps start with
+
+Copy the ones that apply into the new register, as ⚪ Proposed until the owner agrees each cadence, and make each How the app's real command. One that doesn't apply yet (no payments, no AI) is left out; one that applies but is off for now goes in the Paused table with the reason.
+
+| Routine                                  | Typical When                                                             | Typical How                                                                                                                     |
+| ---------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| Security and QA audit round              | After every 5 feature tranches (the delivery workflow's cadence).        | The delivery workflow's audit round: the full test suite, typecheck and lint, the build, `npm audit --audit-level=moderate`.    |
+| Documentation pruning round              | After every 10 feature iterations.                                       | Dedupe and restructure the status documents; never drop open work.                                                              |
+| Release gates                            | Every release.                                                           | The app's check, test, build and release-guard commands, each read by its exit status ([ReleaseProcess.md](ReleaseProcess.md)). |
+| Browser sweep, including phone width     | With each security round, and with any change to shared layout.          | The app's end-to-end and accessibility suites.                                                                                  |
+| Privacy policy against what the app does | With each security round, and with any change to analytics, email or AI. | Read the policy's promises against the code: what's recorded, where, for how long, by which providers.                          |
+| Hosting, database and provider bills     | Monthly, when the invoices arrive.                                       | Compare with last month; explain any jump before it compounds.                                                                  |
+| AI and third-party prices                | Monthly, if the app prices anything from a provider's cost.              | Compare the app's stored prices and exchange rates with the providers' published ones; change them only with the owner.         |
+| Payments, end to end                     | After any change to checkout or webhooks, and once a quarter.            | One real purchase of each kind, then a refund; check every record and message the customer should get.                          |
+| Backups and a restore drill              | Quarterly.                                                               | Restore into a branch or a scratch database and check it opens. A backup nobody has restored is a hope, not a backup.           |
+| Dependency and shared-package currency   | Monthly, or when `@connextar/house` releases.                            | `npm outdated`; take up the house package's new version by its README; note anything held back and why.                         |
+| Watching the scheduled jobs              | Weekly (automated rows).                                                 | The app's job-health page or summary email: every job ran, none is failing, none is running far more often than it should.      |
+
+If continuous integration is switched off, add it to the Paused table with the reason, and make the release gates and the browser sweep the routines that stand in for it.
+
+---
+
+## 6. The pointer in `AGENTS.md`
+
+Add this section to the app's `AGENTS.md`, so every agent reads the register before it starts:
+
+```markdown
+## Routine operations
+
+- **`docs/operations/RoutineOperations.md` is the register of recurring checks**,
+  with when each last ran and when it's next due. At the start of a task, read its
+  **Next due** column: a routine that is due or overdue runs before new feature
+  work, or the owner says why not.
+- After running one, record it as the shared method says
+  (https://github.com/Connextar/cx-house/blob/main/docs/RoutineOperations.md):
+  the full result in its record, a line in the run log, and the row's Last run / Next due / Status.
+  Add a row in the same change set as anything new that needs regular attention.
+```

package/docs/templates/RoutineOperations.md

@@ -0,0 +1,43 @@
+# App name — Routine Operations
+
+> The recurring checks that keep App name ready, aligned and compliant: what each one is for, how often it runs, how to run it, when it last ran and what it found, and when it's next due. The method — the fields, the status keys, how to run, add, retire and book a routine — is the cohort's, in `@connextar/house`: [`docs/RoutineOperations.md`](https://github.com/Connextar/cx-house/blob/main/docs/RoutineOperations.md). This file holds only App name's register and run log. Sits beside [ReleaseProcess.md](ReleaseProcess.md); [`AGENTS.md`](../../AGENTS.md) points here.
+
+_Last updated: YYYY-MM-DD — first version._
+
+**At the start of a task, read the Next due column.** A 🟨 Due or 🟥 Overdue routine runs before new feature work, or the owner says why not.
+
+Status keys: ✅ On schedule · 🟨 Due · 🟥 Overdue · ⏰ Scheduled · 🤖 Automated · ⚪ Proposed · 🧊 Paused.
+
+---
+
+## 1. Register
+
+### 1.1 Manual routines
+
+| ID     | Routine | Why | When | How | Record | Last run | Next due | Status |
+| ------ | ------- | --- | ---- | --- | ------ | -------- | -------- | ------ |
+| OPS-01 |         |     |      |     |        |          |          |        |
+
+### 1.2 Automated routines
+
+The app runs these itself. The routine here is **watching** them: say where (a job-health page, a summary email, the host's cron dashboard), how often to look, and when to look sooner.
+
+| ID  | Job | What it does | When | Status |
+| --- | --- | ------------ | ---- | ------ |
+|     |     |              |      |        |
+
+### 1.3 Paused
+
+| ID  | Routine | Why paused | Since |
+| --- | ------- | ---------- | ----- |
+|     |         |            |       |
+
+---
+
+## 2. Run log
+
+Newest first. One line a run: date · ID · who · result · follow-up.
+
+| Date | ID  | Who | Result | Follow-up |
+| ---- | --- | --- | ------ | --------- |
+|      |     |     |        |           |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@connextar/house",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "description": "The pieces every app we build needs and none of them should own a copy of.",
   "license": "MIT",
   "repository": {