breakaway 1.4.0-main.34 → 1.4.0-main.36

package/.agents/skills/pipeline/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: pipeline
+description: Use when a task asks to move a repository's CI/CD to breakaway's deploy flow or release flow (Move to breakaway's deploy flow, Deploy with breakaway, Release with breakaway), to write or change .github/breakaway-pipeline.json, to run npx breakaway pipeline init or pipeline check, or to map an old deploy or npm publish workflow onto Deploy, Promote, Roll back, and Release.
+---
+
+# Moving a repository to the deploy flow
+
+A move is one task and one pull request: you read how the repository checks, deploys, and publishes today, write `.github/breakaway-pipeline.json`, render the workflows from it with `npx breakaway pipeline init`, and account for every step of the old setup, so nothing is lost and nothing runs twice. The design is the [move's spec](../../../docs/specs/IDEA-27-move-ci-cd-to-the-deploy-flow.md) (sections 2, 2b, and 3), and the [docs](../../../docs/tasks.md#moving-a-repository-to-the-deploy-flow) say what the flows do.
+
+It is an ordinary build: claim, check in on the peloton, and hand over the way the repository's prompt and the `tasks` skill say. This skill is how to do the move itself.
+
+**You never** deploy, publish, run or re-run a workflow, touch Cloudflare, npm, or the repository's GitHub settings (environments, secrets, variables, the App's permissions), or set the repository's pipeline on the board (`repos modify --pipeline` and **Turn on deploys** are the owner's). You write files in a pull request; the owner does the rest.
+
+## 1. Read what's there
+
+Read all of it before you decide anything:
+
+- **Workflows**, `.github/workflows/*.yml`: each one's `name:` line, its triggers (`push`, `pull_request`, `workflow_run`, `release`, `workflow_dispatch`, `schedule`), and every job and step. Note which steps check (lint, test, build, typecheck), which deploy (`wrangler deploy`, `wrangler versions upload`, `cloudflare/wrangler-action`), which publish (`npm publish`, or pnpm's or yarn's, `JS-DevTools/npm-publish`, a `release` event), and which do something else (a migration, a cache purge, a notification, a manual approval through an `environment` with reviewers).
+- **Wrangler config**, `wrangler.jsonc`, `wrangler.json`, or `wrangler.toml`: the Worker's `name`, its `env` blocks (each one's name, and the Worker name it deploys as), and its bindings, above all D1 databases and their `migrations_dir`.
+- **Migrations**: the folder and how they're applied today (`wrangler d1 migrations apply`, a script).
+- **`package.json`**: `name`, `version`, `private`, `scripts` (`build`, `test`, `deploy`, `release`, `prepublishOnly`), `publishConfig`, and `workspaces`; and the lockfile, which says the install command (`npm ci` for `package-lock.json`, or pnpm's or yarn's frozen install for theirs).
+- **Versioning tools**: `.changeset/`, `release-please-config.json`, `.releaserc*` or a `release` key in `package.json` (semantic-release), and `lerna.json`.
+- **Anything already at the flow's paths**: `.github/breakaway-pipeline.json`, `.github/deploy-paths.json`, and `deploy.yml`, `promote.yml`, `rollback.yml`, or `release.yml` in `.github/workflows/`.
+- **Scripts the workflows run**, in `scripts/` or `package.json`: what each does, so you know whether `beforeDeploy` can run it.
+
+## 2. Decide what moves
+
+| The repository today | What you do |
+| --- | --- |
+| Deploys a Worker with `wrangler`, from Actions, Workers Builds, or by hand | Move it: `workers` in the config. |
+| Has checks but deploys by hand | Move it: the deploy is new, and the checks stay as they are. |
+| Publishes a package to npm, from Actions or by hand | Move it: `package` in the config. |
+| Deploys a Worker and publishes a package | Both, in one config and one pull request. |
+| Publishes to another registry (GitHub Packages, JSR, PyPI) | That publishing stays as it is. Say so in the pull request; move a Worker deploy if there is one. |
+| Deploys somewhere else (Pages, Vercel, Fly, a server, containers) | Stop (below). breakaway's deploy flow runs Cloudflare Workers only; a deploy command of the repository's own is planned, not built. |
+| `package.json` says `"private": true` and nothing deploys | Stop: there is nothing the flows can take. |
+
+The first version takes **one staging and one production Worker** and **one package** per repository. With more Workers, move the pair the task names (or that the old deploy targets on the default branch), and leave the others' deploys as they are, saying so. With several publishable packages (a monorepo), move the one the task names (or ask, below), and leave the others' publishing as it is.
+
+**Stopping** means changing nothing and opening no pull request: `comment` on the task what you found and why it doesn't move (the row above, in a sentence the owner can act on), then `release` it. When only the owner can choose (which package, which Worker pair, or what to do with a versioning tool), ask with a decision instead (the core's "Asking for a decision") and release.
+
+## 3. Write the config
+
+`.github/breakaway-pipeline.json` is the repository's own. Every value comes from what you read, never invented:
+
+```json
+{
+  "workers": { "staging": "widgets-staging", "production": "widgets" },
+  "wranglerEnv": { "staging": "staging", "production": "production" },
+  "branch": "main",
+  "checks": ["CI"],
+  "install": "npm ci",
+  "build": "npm run build",
+  "beforeDeploy": ["npx wrangler d1 migrations apply DB --remote --env $BREAKAWAY_ENV"],
+  "deployPaths": { "widgets": "^(src|public|migrations)/|^wrangler\\.jsonc$|^package(-lock)?\\.json$" },
+  "healthCheck": { "staging": "https://widgets-staging.example.workers.dev/", "production": "https://widgets.example.com/" },
+  "package": { "name": "widgets", "directory": ".", "access": "public" }
+}
+```
+
+- **`workers`**: the staging and production Worker names, as the wrangler config deploys them (with its `env` blocks, the name each environment deploys as). Two different Workers. A repository with only production today needs a staging Worker: name it `<production>-staging`, and the owner creates it (the checklist).
+- **`wranglerEnv`**: only when the wrangler config has `env` blocks; the environment name for each Worker, passed as `--env`.
+- **`branch`**: the default branch, when it isn't `main`.
+- **`checks`**: the `name:` line of each workflow that must pass before a deploy or a release, exactly as written. Every check the old deploy waited for, and the ones that run on push to the default branch. Never a workflow you're about to remove.
+- **`install`, `build`**: the repository's own one-line commands, from its old workflow or lockfile. Leave `build` out when nothing builds.
+- **`beforeDeploy`**: the old deploy's steps before `wrangler deploy` (migrations first), one command each. They read `$BREAKAWAY_ENV` (`staging` or `production`) and `$WORKER`. A step that needs more than one line goes in a script the command runs; a step that can't run there stays where it is (step 5).
+- **`deployPaths`**: per Worker, a regular expression of the paths whose change needs a deploy: its source, static assets, migrations, the wrangler config, and the package and lockfile. The board reads the same patterns to say "No deploy needed", so a path left out never ships and a path put in too many deploys for nothing. You can't prove them from reading, so the pull request lists each part and what it covers (step 6).
+- **`healthCheck`**: an address the old workflow or the README checks after a deploy, as a string (staging only) or `{ "staging", "production" }`. Leave it out when there is none; never guess one.
+- **`package`**: `name` exactly as its `package.json` says, `directory` its folder (`.` at the root), and `access` (`restricted` only when `publishConfig.access` or the old publish says so; a scoped package published `public` today stays `public`). Its `package.json` needs a plain `X.Y.Z` version: the flow counts from it. A repository that only publishes has no `workers`, `deployPaths`, `healthCheck`, `beforeDeploy`, or `wranglerEnv`.
+
+**A versioning tool with its own scheme** (changesets, semantic-release, release-please) decides versions from commits or changeset files; the release flow takes `package.json`'s version and stages `X.Y.Z-main.N` on `next` for every merge. They can't both run, and one can't be mapped onto the other. Don't replace it: ask the owner with a decision (keep the tool and move only the Worker deploy; or drop the tool for the release flow, which a later task does), and stop the package part until it's answered. Move a Worker deploy in the meantime only if the decision says to.
+
+## 4. Render the workflows
+
+In the checkout, run `npx breakaway pipeline init`. It checks the config, naming the field that's wrong and what it should be, and the rendered workflows (YAML, pinned actions, expressions, secrets only in an environment), and writes nothing if either fails. It writes `.github/workflows/deploy.yml`, `promote.yml`, `rollback.yml`, and `.github/deploy-paths.json` for `workers`, and `.github/workflows/release.yml` for `package`. Never edit what it writes: change the config and run it again.
+
+- **It refuses a file already there** that it didn't render. When that file is the old deploy or publish workflow you're replacing, delete it in this pull request (step 5) and run `pipeline init` again. When it's something else that only shares the name, stop and ask the owner with a decision: never rename or overwrite it silently.
+- **It names helper scripts the repository lacks** (`scripts/record-deployment.mjs` and the others). `repos init <slug> --update` copies them, and that is the owner's: say so under **After merging** (the workflows fail without them), unless they're already there.
+- **`npx breakaway pipeline check`** passes before you hand over: the config is sound, and the files are what it renders now.
+
+## 5. Nothing lost, nothing twice
+
+Every old job and step ends up in exactly one place: the config, a rendered workflow, kept where it was, or dropped with the reason. The rules:
+
+- **Checks are the repository's own.** Never edit or remove a workflow that checks. Deploy and Release wait for them by name.
+- **A workflow that only deploys or only publishes** comes out in the same pull request, deleted, or with its trigger on the default branch removed when it also runs for something else (a tag, by hand, a preview on pull requests, which stays). Otherwise the merge deploys or publishes twice.
+- **A workflow that checks and deploys, or checks and publishes**, is split: its checks stay as they are, and the deploy or publish job or steps come out (with the `needs:`, `if:`, permissions, and `environment` only they used). If its deploy job is all that runs on push to the default branch, drop that trigger too, so the checks still run where they did.
+- **Workers Builds** (Cloudflare's git integration) deploys from Cloudflare, not from a file: you can't turn it off. Say under **After merging** that the owner disconnects it before merging, or the merge deploys twice.
+- **A step the flow can't do** (a manual approval, a custom deploy script `beforeDeploy` can't run, a notification, a cache purge, publishing to another registry) stays exactly where it is, and the pull request lists it under **After merging** for the owner to decide. Never invent an equivalent.
+- **Publishing by hand** (a `release` or `publish` script someone runs from a laptop) stays in `package.json`; the pull request says the release flow replaces it and the owner stops running it.
+- **Never** add or change a secret, an environment, or a variable, and never put a token in a file.
+
+## 6. The pull request
+
+Open it the way the repository's prompt's **Pull requests** says, closing the task. Its description holds, besides what that asks:
+
+- **What moves**: the row from step 2, the Workers, and the package.
+- **Step by step**: a table of every old workflow, job, and step, and where each went:
+
+  | Old | Was | Now |
+  | --- | --- | --- |
+  | `deploy.yml` · deploy | `wrangler deploy` on push to `main` | Deploy (`deploy.yml`, rendered) after CI passes; the old file is removed |
+  | `ci.yml` · test | `npm test` | Kept as it is; Deploy and Release wait for CI |
+  | `ci.yml` · publish | `npm publish` on a tag | Release (`release.yml`): `next` on every merge, `latest` on the owner's Release; the step is removed |
+  | `deploy.yml` · migrate | `wrangler d1 migrations apply` | `beforeDeploy` |
+  | `deploy.yml` · notify | posts to chat | Kept where it was (After merging) |
+
+- **Deploy paths**: each pattern's parts and what they cover, so the owner can check them.
+- **After merging**: the owner's checklist below, the steps kept where they were, and anything you stopped short of.
+
+**The owner's part comes before the merge.** The merge itself runs Deploy and Release once its checks pass, so without the owner's part both fail. Add a `+owner` task for it, filled in like any task, with the checklist in its brief and only what this repository needs. It doesn't depend on the move task (it comes first), and the pull request's **After merging** repeats it under "Before you merge":
+
+- the staging and production Workers (or confirm the existing ones), and a Cloudflare API token for each;
+- the GitHub environments `staging` and `production`, each with its token as `CLOUDFLARE_API_TOKEN` and restricted to the default branch, and the repository variable `CLOUDFLARE_ACCOUNT_ID`;
+- read and write on **Actions** for the board's GitHub App on the repository (Promote, Roll back, and Release start workflows);
+- the helper scripts, with `repos init <slug> --update`, when `pipeline init` named any;
+- Workers Builds disconnected, when the repository used it;
+- for a package: the GitHub environment `npm`, restricted to the default branch; on npm, a trusted publisher for `release.yml` and the `npm` environment, or a granular `NPM_TOKEN` in that environment that can't bypass 2FA; and, after each run, approving the staged version on npm with 2FA (`npm stage approve <id>`, or Staged Packages on npmjs.com). The board shows what waits and never approves;
+- optional: the repository variable `DEPLOYS_PAUSED` (`true` stops Promote and Release), and the health-check addresses;
+- after the merge, **Turn on deploys** on the repository's GitHub page, which sets its pipeline from the files.
+
+## Before handing over
+
+- `npx breakaway pipeline check` passes.
+- The repository's own checks pass, and every workflow you changed still parses and runs the jobs it ran before, minus what moved.
+- Every old step is in the table, and no deploy or publish is left that the merge would run besides Deploy and Release.
+- No secret, token, or address you didn't read in the repository is in a file, the task, or the pull request.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakaway",
-  "version": "1.4.0-main.34",
+  "version": "1.4.0-main.36",
   "description": "The task board for you and your coding agents: a Cloudflare Worker, its web app, Taskwarrior sync, and the CLI (npx breakaway).",
   "license": "FSL-1.1-Apache-2.0",
   "type": "module",
@@ -35,6 +35,7 @@
     "prompts/*.md",
     "taskrc",
     ".agents/skills/tasks/SKILL.md",
+    ".agents/skills/pipeline/SKILL.md",
     "template"
   ],
   "engines": {
@@ -50,15 +51,16 @@
   },
   "scripts": {
     "dev": "vite",
-    "build": "vite build",
-    "test": "vitest run && vitest run --config scripts/tasks/vitest.config.js",
+    "prepare": "node scripts/board-files.mjs",
+    "build": "node scripts/board-files.mjs && vite build",
+    "test": "node scripts/board-files.mjs && vitest run && vitest run --config scripts/tasks/vitest.config.js",
     "brand": "node scripts/brand-lint.mjs",
     "format": "biome format --write .",
     "lint": "biome check .",
-    "typecheck": "wrangler types && tsc -p tsconfig.json && tsc -p scripts/tsconfig.json && tsc -p web/tsconfig.json",
+    "typecheck": "node scripts/board-files.mjs && wrangler types && tsc -p tsconfig.json && tsc -p scripts/tsconfig.json && tsc -p web/tsconfig.json",
     "site": "node site/build.mjs",
     "interop": "node interop.mjs",
-    "deploy": "vite build && wrangler deploy -c wrangler.jsonc"
+    "deploy": "node scripts/board-files.mjs && vite build && wrangler deploy -c wrangler.jsonc"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.15",

package/scripts/board-files.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 /**
  * Writes src/board-files.json (BRK-132): the board's files repos init reads (boardSources in src/init.js), by path,
- * so the Worker renders an empty repository's first commit from the same files as the CLI. scripts/tasks/init.test.js
- * fails when it's behind them; run `node scripts/board-files.mjs` after changing one.
+ * so the Worker renders an empty repository's first commit from the same files as the CLI. It's generated, never
+ * committed (BRK-148): `pnpm install`, `build`, `typecheck`, `test`, and `deploy` run this first, and the release
+ * workflow's build puts it in the bundle.
  */
 import { readFileSync, writeFileSync } from 'node:fs';
 import { boardSources } from '../src/init.js';
@@ -14,5 +15,6 @@ export const boardFiles = () => Object.fromEntries(boardSources(read).map((path)
 
 if (import.meta.url === `file://${process.argv[1]}`) {
   writeFileSync(new URL('src/board-files.json', ROOT), `${JSON.stringify(boardFiles(), null, 2)}\n`);
-  console.log('Wrote src/board-files.json.');
+  // On stderr: npm pack and npm publish run it (prepare), and their --json goes to stdout.
+  console.error('Wrote src/board-files.json.');
 }

package/scripts/tasks/cli.js

@@ -49,17 +49,18 @@ export function unknownSubcommand(command, first) {
 
 /**
  * What a CLI says about where it runs from, or null to say nothing (BRK-7). The CLI ships on npm, so `packaged` (run
- * through npx) has nothing to say. In a checkout of the board's own repository, `own` older than the board's (`board`,
- * its X-Tasks-Cli header) means pull. Anywhere else the CLI is an old copy that `repos init` used to commit: it
- * works while the API stays compatible, and on each run it says how to switch.
+ * through npx) has nothing to say. In a checkout of the board's own repository, `behind` (the board's `release`, its
+ * X-Tasks-Release header, isn't in this checkout's history: releaseBehind) means pull (BRK-148). Anywhere else the
+ * CLI is an old copy that `repos init` used to commit: it works while the API stays compatible, and on each run it says
+ * how to switch. `own` and `board` are the frozen CLI number (src/cli-version.js) such a copy carries and the board sends.
  */
-export function staleCliWarning({ own, board, boardCheckout, slug, packaged = false }) {
+export function staleCliWarning({ own, board, boardCheckout, slug, packaged = false, release = null, behind = false }) {
   if (packaged) return null;
   const theirs = Number(board);
   const older = Number.isInteger(theirs) && theirs > own;
   if (boardCheckout) {
-    if (!older) return null;
-    return `this checkout's board CLI (version ${own}) is older than the board's (${theirs}), so a command may be missing or behave differently: pull the default branch to update it.`;
+    if (!release || !behind) return null;
+    return `this checkout is behind the board's release (v${release}), so a command may be missing or behave differently: pull the default branch to update it.`;
   }
   const newer = older ? `, older than the board's (${theirs}), so a command may be missing or behave differently` : '';
   return `this checkout carries a copy of the board's CLI (version ${own}${newer}). The CLI is on npm now: run it as npx ${CLI_PACKAGE} <command> instead of node scripts/tasks.mjs, and remove the copy with npx ${CLI_PACKAGE} repos init ${slug || '<slug>'} --update, which opens a pull request here.`;
@@ -77,6 +78,22 @@ export function githubRequest(repo, { sync = false } = {}) {
   return ['GET', repo ? `github?repo=${encodeURIComponent(repo)}` : 'github', undefined];
 }
 
+/**
+ * Whether the checkout `git` runs in is behind the board's release `release` (BRK-148): it has the release's tag
+ * (`v1.4.0-main.9`, which the release workflow pushes) and that commit isn't in HEAD's history. Without the tag (tags
+ * not fetched yet), or in a `shallow` clone, whose cut history can hide an ancestor, it can't tell, and says no.
+ * `git(args)` runs git and returns its exit code.
+ * @param {string | null} release
+ * @param {(args: string[]) => number | null} git
+ * @param {{ shallow?: boolean }} [options]
+ */
+export function releaseBehind(release, git, { shallow = false } = {}) {
+  if (shallow || !release || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u.test(release)) return false;
+  const tag = `refs/tags/v${release}`;
+  if (git(['rev-parse', '-q', '--verify', `${tag}^{commit}`]) !== 0) return false;
+  return git(['merge-base', '--is-ancestor', tag, 'HEAD']) === 1;
+}
+
 /** What `github fix` accepts for --problem: the same three the pull request page offers. */
 export const FIX_PROBLEMS = ['conflicts', 'failing', 'review'];
 

package/scripts/tasks.mjs

@@ -72,6 +72,7 @@ import {
   pullAgentSummary,
   reviewRequest,
   staleCliWarning,
+  releaseBehind,
   unknownSubcommand,
 } from './tasks/cli.js';
 import { mergeViews, pelotonLines, pelotonPost, pickPeloton } from './tasks/peloton.js';
@@ -423,7 +424,7 @@ async function call(method, path, body, { soft = false } = {}) {
       `can't reach ${BASE} (${reasonOf(error)}). Cloud sessions need ${new URL(BASE).host} allowed in their network settings.`,
     );
   }
-  warnIfStale(res.headers.get('X-Tasks-Cli'));
+  warnIfStale(res.headers.get('X-Tasks-Cli'), res.headers.get('X-Tasks-Release'));
   if (res.status === 401 && !token)
     fail(
       `no token. Set BREAKAWAY_TOKEN, put it in ${ENV_FILE}, or add it as an API credential in the cloud environment (see docs/tasks.md#cloud-agents).`,
@@ -444,8 +445,11 @@ async function call(method, path, body, { soft = false } = {}) {
 }
 
 let warnedStale = false;
-/** Once a run: say so when this copy of the CLI is older than the board's (CLD-193). On stderr, so --json stays clean. */
-function warnIfStale(board) {
+/**
+ * Once a run: say so when this copy of the CLI is older than the board's (CLD-193), or this checkout of the board's own
+ * repository is behind the release the board runs (BRK-148). On stderr, so --json stays clean.
+ */
+function warnIfStale(board, release = null) {
   // An old copy says how to switch on every run, even when the board doesn't say its version.
   if (warnedStale || (board === null && PACKAGED)) return;
   warnedStale = true;
@@ -459,7 +463,22 @@ function warnIfStale(board) {
       /* no .taskrc */
     }
   }
-  const warning = staleCliWarning({ own: CLI_VERSION, board, boardCheckout, slug, packaged: PACKAGED });
+  const git = (args) => spawnSync('git', ['-C', REPO, ...args], { encoding: 'utf8', timeout: 5000 });
+  const behind =
+    boardCheckout &&
+    Boolean(release) &&
+    releaseBehind(release, (args) => git(args).status, {
+      shallow: git(['rev-parse', '--is-shallow-repository']).stdout?.trim() === 'true',
+    });
+  const warning = staleCliWarning({
+    own: CLI_VERSION,
+    board,
+    boardCheckout,
+    slug,
+    packaged: PACKAGED,
+    release,
+    behind,
+  });
   if (warning) console.error(`tasks: ${warning}`);
 }
 
@@ -2013,7 +2032,7 @@ async function initRepo(slug) {
     title,
     '-m',
     update
-      ? `The board's core, skill, release helpers, and Taskwarrior files as they are in ${board ?? 'breakaway'} now, and the session hooks run through npx, so an old copy of the CLI is removed: run it as npx ${CLI_PACKAGE} (CLI version ${CLI_VERSION}). This repository's own files are unchanged. Updated by npx ${CLI_PACKAGE} repos init ${repo.slug} --update.`
+      ? `The board's core, skill, release helpers, and Taskwarrior files as they are in ${board ?? 'breakaway'} now, and the session hooks run through npx, so an old copy of the CLI is removed: run it as npx ${CLI_PACKAGE}. This repository's own files are unchanged. Updated by npx ${CLI_PACKAGE} repos init ${repo.slug} --update.`
       : `${first.body}${starter.files.length ? ` It also adds the deploy and release flows, rendered from ${starter.files[0].path}.` : ''}`,
   );
   const pushed = spawnSync('git', ['-C', dir, 'push', '-u', 'origin', empty ? `HEAD:refs/heads/${branch}` : work], {
@@ -2039,7 +2058,7 @@ async function initRepo(slug) {
         title,
         '--body',
         update
-          ? `The task board's copied files (its CLI, version ${CLI_VERSION}, the core and stub, the tasks skill, and the Taskwarrior files) as they are on the board's repository now, updated by \`npx breakaway repos init ${repo.slug} --update\`. This repository's own files (its agent prompt, AGENTS.md, .taskrc, .envrc, package.json, .claude/settings.json) are unchanged.`
+          ? `The task board's copied files (its CLI, the core and stub, the tasks skill, and the Taskwarrior files) as they are on the board's repository now, updated by \`npx breakaway repos init ${repo.slug} --update\`. This repository's own files (its agent prompt, AGENTS.md, .taskrc, .envrc, package.json, .claude/settings.json) are unchanged.`
           : `The files the task board's agents need to claim and work a task in this repository, added by \`npx breakaway repos init ${repo.slug}\`. Nothing that was there is changed. If this repository's linter reads plain JavaScript, exclude the copied scripts (tools/tasks/ and the release helpers) from it.${plan.todo.length ? `\n\nStill to do:\n${plan.todo.map((t) => `- ${t}`).join('\n')}` : ''}`,
       ],
       { encoding: 'utf8' },

package/src/cli-version.js

@@ -1,8 +1,7 @@
 /**
- * The version of the board's CLI and the files repos init copies with it (CLD-193). The board reports it
- * (every API answer's X-Tasks-Cli header, and health), so a copy in another repository can say it's older
- * and how to update it. scripts/tasks/version.test.js fails when the copied files change and this doesn't:
- * so it lives in the board's package (CLD-135) and the CLI imports it from here.
+ * The number the board's CLI and the files repos init copies were versioned by (CLD-193), frozen by BRK-148: never
+ * change it. The board still sends it (every API answer's X-Tasks-Cli header, and `cli` in health), so an old copy of
+ * the CLI in another repository says how to switch to npx. What a checkout compares now is the board's release (the
+ * X-Tasks-Release header): pull requests no longer bump anything when a copied file changes.
  */
 export const CLI_VERSION = 73;
-export const CLI_FINGERPRINT = '2da33f9e367765c1';

package/src/init.js

@@ -7,7 +7,7 @@
  * scripts/tasks.mjs, and the board's first commit to an empty repository, through its GitHub App, is in
  * src/store-init.js, which reads the board's files from src/board-files.json (BOARD_SOURCES).
  */
-import { SKILL, areaList, routinePrompt } from './prompt.js';
+import { PIPELINE_SKILL, SKILL, areaList, routinePrompt } from './prompt.js';
 import { promptPathOf } from './repos.js';
 
 /** This machine's folder for the board, as .taskrc names it, where a caller doesn't say (scripts/tasks/settings.js). */
@@ -50,7 +50,7 @@ export const RELEASE_ENTRIES = [
 /** Copied unchanged: the board's shared core and stub, and the Taskwarrior settings the new .taskrc includes. */
 const COPIED = ['prompts/core.md', 'prompts/stub.md'];
 /** Copied with a change for the repository, or made from the board's: their source is versioned too. */
-const ADAPTED = ['taskrc', 'scripts/task', SKILL];
+const ADAPTED = ['taskrc', 'scripts/task', SKILL, PIPELINE_SKILL];
 /**
  * Where the board's files (the prompts, the shared taskrc) go in another repository. In the board's own checkout they
  * sit at the root, so the paths `read` takes are the board's; what is written keeps this folder.
@@ -68,7 +68,7 @@ const GITATTRIBUTES = ['scripts/task text eol=lf', '.envrc text eol=lf'];
 /**
  * The board's own files initPlan reads (repository paths, sorted): the prompt template, what it copies as it is or
  * adapted, and the release helpers with what they import. src/board-files.json holds them for the Worker, and
- * scripts/tasks/init.test.js fails when it falls behind (`node scripts/board-files.mjs` writes it again).
+ * `node scripts/board-files.mjs` writes it before every build and test run (it isn't committed, BRK-148).
  */
 export function boardSources(read) {
   return [...new Set(['prompts/repository.md', ...COPIED, ...ADAPTED, ...importClosure(RELEASE_ENTRIES, read)])].sort();
@@ -116,19 +116,6 @@ export function importClosure(entries, read) {
   return [...seen].sort();
 }
 
-/**
- * Every file CLI_VERSION in src/cli-version.js versions (repository paths, sorted): what repos init copies, as it is
- * or adapted, and the CLI's own files, which the npm package carries and an old copy still holds. cli-version.js
- * itself is left out, so the fingerprint can live in it.
- */
-export function copiedSources(read) {
-  return [
-    ...new Set([...importClosure(CLI_ENTRIES, read), ...importClosure(RELEASE_ENTRIES, read), ...COPIED, ...ADAPTED]),
-  ]
-    .filter((path) => path !== 'src/cli-version.js')
-    .sort();
-}
-
 /**
  * The files an old copy of the CLI holds that npx replaces (repository paths, sorted): the CLI, its hooks, and what
  * only they import. The release helpers' files stay copied, so they are not here.
@@ -201,16 +188,6 @@ export function declaredCopies(agents) {
   return [...line.split(/ come from \[/u)[0].matchAll(/`([^`]+)`/gu)].map((m) => m[1]);
 }
 
-/** A short SHA-256 of `paths` and their text: changes whenever one of them does. */
-export async function fingerprint(paths, read) {
-  const text = paths.map((path) => `${path}\0${read(path)}\0`).join('');
-  const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
-  return [...new Uint8Array(hash)]
-    .slice(0, 8)
-    .map((b) => b.toString(16).padStart(2, '0'))
-    .join('');
-}
-
 /**
  * The Taskwarrior report and context for repository `slug` (IDEA-14): `task <slug>` lists its open work, and
  * `task context <slug>` narrows everything to it and puts new tasks in it. For the shared taskrc.
@@ -340,7 +317,7 @@ export function agentsMd(repo, board, dir = DEFAULT_DIR) {
 
 - **Work lives on the task board.** This repository's tasks are in the areas ${areaList(repo)}. Use the \`tasks\` skill (\`${SKILL}\`) and the CLI, \`npx breakaway\` (the \`breakaway\` package on npm), to claim, comment, and hand over. It works in this checkout's repository, so \`list\` and \`next\` show only this repository's tasks. The skill is breakaway's, written for this repository's areas and prompt: where it names breakaway's own files or rules, the board's part applies and the rest doesn't.
 - **Agents started by the board** follow [\`${promptPathOf(repo)}\`](${promptPathOf(repo)}), which starts with the board's core, \`tools/tasks/prompts/core.md\`.
-- **Copied files.** \`tools/tasks/\`, the release helpers in \`scripts/\`, and \`${SKILL}\` come from [${board}](https://github.com/${board}). Don't edit them here: change them there. \`${MANIFEST}\` lists every file it copied, and \`repos init --update\` replaces only those: a file it doesn't list is this repository's own, even at a path breakaway copies to. \`.claude/settings.json\` holds the session hooks that show a cloud agent's output on its task, and they run through \`npx\`, so this repository carries no copy of the CLI.
+- **Copied files.** \`tools/tasks/\`, the release helpers in \`scripts/\`, \`${SKILL}\`, and \`${PIPELINE_SKILL}\` come from [${board}](https://github.com/${board}). Don't edit them here: change them there. \`${MANIFEST}\` lists every file it copied, and \`repos init --update\` replaces only those: a file it doesn't list is this repository's own, even at a path breakaway copies to. \`.claude/settings.json\` holds the session hooks that show a cloud agent's output on its task, and they run through \`npx\`, so this repository carries no copy of the CLI.
 - **Taskwarrior** (optional): \`scripts/task\`, or plain \`task\` with direnv after \`direnv allow\`, uses the board with this checkout's own \`.task/\` database, in the \`${repo.slug}\` context. \`npx breakaway setup\` connects the machine once.
 - **Changes reach \`${repo.defaultBranch || 'main'}\` through pull requests**, which the owner merges. Never merge, force-push, or rewrite \`${repo.defaultBranch || 'main'}\`.
 - **Never put a secret or token** in a file, task, comment, or pull request. The board's token lives in \`${dir}/tasks.env\` (or \`$BREAKAWAY_HOME/tasks.env\`) or the cloud environment's credentials, never in this repository.
@@ -495,6 +472,7 @@ export function initPlan({
   }
   if (readTarget('.claude/skills') === null) files.push({ path: '.claude/skills', link: '../.agents/skills' });
   copy(SKILL, skillFor(read(SKILL), board, repo));
+  copy(PIPELINE_SKILL, skillFor(read(PIPELINE_SKILL), board, repo));
   add('AGENTS.md', agentsMd(repo, board, configDir));
   if (!skipped.includes('AGENTS.md')) todo.push('AGENTS.md: add how to build in this repository');
 

package/src/prompt.js

@@ -6,6 +6,8 @@
 
 /** Where the `tasks` skill sits in a repository the board runs. */
 export const SKILL = '.agents/skills/tasks/SKILL.md';
+/** Where the `pipeline` skill sits: how an agent moves a repository's CI/CD to the deploy flow (BRK-92). */
+export const PIPELINE_SKILL = '.agents/skills/pipeline/SKILL.md';
 
 /** The repository's areas for its prompt and AGENTS.md: "product (`BWYP`), cloud (`BWYC`)". */
 export const areaList = (repo) => repo.areas.map((a) => `${a.project} (\`${a.prefix}\`)`).join(', ');