peer-ai 1.0.0-next.1 → 1.0.0-next.2

package/README.md

@@ -81,10 +81,15 @@ It never overwrites an existing `peer-ai.config.json`, and it never assumes anyt
 
 Moves a project from v0, when Peer AI was a playbook copied into a `peer-ai/` folder, onto the package ([RFC 0008](../../rfcs/0008-moving-a-v0-project-onto-1-0.md)).
 
-```bash
-npx peer-ai migrate --dry-run
-npx peer-ai migrate
-```
+In the project's folder:
+
+1. **Commit or stash any work in progress.** `migrate` won't start with uncommitted changes, so the move is a change of its own.
+2. **Make a branch:** `git switch -c peer-ai-1.0`
+3. **See the plan, changing nothing:** `npx peer-ai migrate --dry-run`
+4. **Migrate:** `npx peer-ai migrate`. It asks the same few questions as `init`, already filled in from what it found.
+5. **Review the change, commit it, and open a pull request.** To undo it instead: `git stash --include-untracked`.
+6. **In your next session,** your AI tool brings up each decision `migrate` left in `docs/peer-ai-migration.md`. Go through them together, then delete the file.
+7. **On GitHub,** make `peer-ai check` a required check, so nothing merges without the gate.
 
 It converts what it can read with certainty:
 
@@ -101,7 +106,7 @@ Nothing is dropped silently. Whatever needs judgement, it copies word for word i
 
 It tells the files the project changed from v0's own by their fingerprints: a list of every file in every v0 version, which ships with the package.
 
-It never commits. It won't start with uncommitted changes, so the migration is a change of its own: review it, commit it on a branch, and open a pull request. `git restore . && git clean -fd` undoes it all.
+It never commits. It won't start with uncommitted changes, so the migration is a change of its own: review it, commit it on a branch, and open a pull request. `git stash --include-untracked` undoes it all. It deletes only files git can bring back, leaves files git ignores where they are, and refuses to write outside the project.
 
 ### Options
 
@@ -200,6 +205,18 @@ npx peer-ai render
 
 `AGENTS.md` gets the block whenever a tool other than Claude Code is listed, when it already exists, or when `CLAUDE.md` imports it.
 
+### The CI gate
+
+Render sets up `peer-ai check` in the project's CI, so no one has to remember to ([RFC 0009](../../rfcs/0009-the-ci-gate-set-up-by-render.md)):
+
+- **On GitHub Actions,** it writes `.github/workflows/peer-ai.yml`: one job, `peer-ai check`, that installs Node 24 and runs the exact version of Peer AI render ran as, so it works with or without a `package.json`. Its actions are pinned to commits. Render keeps the file up to date while it's as render left it, and leaves it alone once someone changes it by hand; `doctor` then checks it still runs the gate. A version bump updates it.
+- **On any other CI,** it prints the step to add.
+- **When a workflow of the project's own already runs `peer-ai check`,** it adds nothing.
+
+Make `peer-ai check` a required check in the repository's settings, so nothing merges without it. To run the gate some other way, set `"delivery": { "gate": false }`.
+
+### Instructions
+
 The instructions are short: how to work through the MCP server, the project's parts, its commands, its compliance packs and its own rules, and the project's settings for models, skills and activities when it has any: the models to use, the add-ons, checklists and notes for each skill, and the files to read and notes for each activity. The server serves the detail when it's needed, rather than every rule on every turn.
 
 ### Skills
@@ -280,6 +297,7 @@ npx peer-ai doctor
 | AI tools | A tool set up in the repository, such as a `CLAUDE.md` or `.cursor/`, that the config doesn't list |
 | What render writes | Instructions or MCP registrations that no longer match the config, or skills that are missing or out of date |
 | CI | A config that says there is no CI when the repository has a pipeline, which would lead Peer AI to add a second one |
+| The CI gate | A pipeline that doesn't run `peer-ai check`, or a gate workflow that's out of date or no longer runs it. Through `next_work`, the AI tool hears about it in every session. |
 | The project map | Missing, not valid, or out of date. It runs a fresh assessment and lists every item whose status has changed since `.peer-ai/map.json` was written. |
 | Work items | A file in `.peer-ai/work/` that isn't valid, isn't named after its id, or names a track the config doesn't have |
 | Git | A folder that isn't a git repository, or a `.gitignore` that hides Peer AI's files from the team and CI |
@@ -337,20 +355,7 @@ A review's result is worked out from its report when it is recorded, so an open
 
 ### In CI
 
-Run it after the project's own checks:
-
-```yaml
-- run: npx peer-ai check
-```
-
-That uses the version in the project's `package.json`. A project without one, such as a Python or Flutter project, needs Node 24 on the runner and the version `render` pinned:
-
-```yaml
-- uses: actions/setup-node@v4
-  with:
-    node-version: 24
-- run: npx -y peer-ai@<version> check
-```
+`render` sets it up: see [the CI gate](#the-ci-gate). By hand, it's a step after the project's own checks that runs, with Node 24, `npx -y peer-ai@<version> check`.
 
 ### Options
 

package/dist/doctor.js

@@ -10,6 +10,7 @@ import { DOMAINS } from "peer-ai-workflow";
 import { LEGACY_MARKERS, MAP_FILE, assess, loadConfig } from "./assess.js";
 import { count, fail, formatChecks, ok, plural, skip, warn } from "./checks.js";
 import { checkEnforcers, checkProfiles } from "./enforcers.js";
+import { GATE_FILE, checkGate } from "./gate.js";
 import { WORKFLOW_FILE } from "./pipeline.js";
 import { RUFF_FILE } from "./ruff.js";
 import { CONFIG_FILE, detectDelivery, detectName, detectTools, detectTracks } from "./detect.js";
@@ -105,7 +106,8 @@ function checkTools(root, config) {
     return ok("tools", `AI tools: ${listed.join(", ")}`);
 }
 /** What render writes for the AI tools still matches the config. */
-const ENFORCER_FILES = [WORKFLOW_FILE, RUFF_FILE];
+/** Files with a check of their own: the enforcers, and the CI gate. */
+const ENFORCER_FILES = [WORKFLOW_FILE, RUFF_FILE, GATE_FILE];
 function checkRendered(root, config, skills) {
     const plan = planRender(root, config);
     const withSkills = skills || config.skills?.commit === true;
@@ -259,6 +261,7 @@ export function diagnose(root, nodeVersion = process.versions.node, today = new
             ? needsConfig("render", "What render writes")
             : [checkRendered(root, config, options.skills ?? true)]),
         ...(config === undefined ? needsConfig("delivery", "CI") : [checkDelivery(root, config)]),
+        ...(config === undefined ? needsConfig("gate", "The CI gate") : checkGate(root, config)),
         ...(config === undefined
             ? needsConfig("standards", "Rules set aside")
             : checkStandards(config, today.toISOString().slice(0, 10))),

package/dist/gate.d.ts

@@ -0,0 +1,29 @@
+import type { PeerAiConfig } from "peer-ai-workflow";
+import { type Check } from "./checks.ts";
+export declare const GATE_FILE = ".github/workflows/peer-ai.yml";
+/** The gate's command, with the exact version render runs as, so CI needs no package.json. */
+export declare const gateCommand: () => string;
+/** The workflow render writes for the gate: Node 24 and the exact version, so any project can run it. */
+export declare function gateWorkflow(config: PeerAiConfig): string;
+export interface Gate {
+    /** What render does to the gate's workflow, on GitHub Actions. */
+    planned?: {
+        path: string;
+        action: "create" | "update" | "unchanged" | "kept";
+        content?: string;
+        note?: string;
+    };
+    /** The step to add by hand, for any other CI. */
+    manual?: string;
+    /** Where the gate runs already, when it does. */
+    runsIn?: string;
+}
+/** Whether the project's CI is GitHub Actions: workflows of its own, or the gate render wrote. */
+export declare function onGitHubActions(root: string): boolean;
+/** Where the gate stands, and what render does about it. */
+export declare function planGate(root: string, config: PeerAiConfig): Gate;
+/**
+ * peer-ai doctor's check: CI runs the gate, unless the config turns it off. With no CI yet there is
+ * nothing to say; the delivery check reports that already.
+ */
+export declare function checkGate(root: string, config: PeerAiConfig): Check[];

package/dist/gate.js

@@ -0,0 +1,141 @@
+// The CI gate (RFC 0009): CI runs peer-ai check on every change, so work is held to its record
+// without anyone having to remember to set that up. On GitHub Actions, render writes a workflow of
+// its own for it, owned the way the security workflow is: rewritten while it's as render left it,
+// and left alone once someone changes it by hand. For any other CI, render prints the step to add.
+// peer-ai doctor warns while nothing runs it, so the AI tool hears about it in every session.
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { ok, skip, warn } from "./checks.js";
+import { detectDelivery } from "./detect.js";
+import { VERSION } from "./package-info.js";
+import { CHECKOUT, SETUP_NODE, WORKFLOW_FILE, sameFile, unchangedSinceRender, withHash } from "./pipeline.js";
+export const GATE_FILE = ".github/workflows/peer-ai.yml";
+const WORKFLOWS = ".github/workflows";
+/** Workflows Peer AI writes for itself, which on their own aren't a project's CI. */
+const OWN = [GATE_FILE, WORKFLOW_FILE, `${WORKFLOWS}/copilot-setup-steps.yml`];
+/** A command that runs the gate: peer-ai check, with or without a version. */
+const GATE_COMMAND = /\bpeer-ai(@\S+)?\s+check\b/;
+/** Whether a CI file runs the gate: a line with the command, not a comment or a job's name. */
+const runsGate = (text) => text.split(/\r?\n/).some((line) => !/^\s*#/.test(line) && !/^\s*-?\s*name:/.test(line) && GATE_COMMAND.test(line));
+/** The gate's command, with the exact version render runs as, so CI needs no package.json. */
+export const gateCommand = () => `npx -y peer-ai@${VERSION} check`;
+const read = (root, path) => {
+    const full = join(root, path);
+    return existsSync(full) && statSync(full).isFile() ? readFileSync(full, "utf8") : undefined;
+};
+/** The files of a pipeline: a folder's YAML files, or the file itself. */
+function filesOf(root, pipeline) {
+    if (!pipeline.endsWith("/"))
+        return [pipeline];
+    const dir = join(root, pipeline);
+    if (!existsSync(dir) || !statSync(dir).isDirectory())
+        return [];
+    return readdirSync(dir)
+        .filter((name) => /\.ya?ml$/.test(name))
+        .sort()
+        .map((name) => `${pipeline}${name}`);
+}
+/** The workflow render writes for the gate: Node 24 and the exact version, so any project can run it. */
+export function gateWorkflow(config) {
+    const branch = config.repo?.defaultBranch;
+    const body = [
+        "name: Peer AI",
+        "on:",
+        "  pull_request:",
+        // With no default branch in the config, changes are checked in their pull requests.
+        ...(branch === undefined ? [] : ["  push:", `    branches: [${branch}]`]),
+        "permissions:",
+        "  contents: read",
+        "jobs:",
+        "  peer-ai-check:",
+        "    name: peer-ai check",
+        "    runs-on: ubuntu-latest",
+        "    timeout-minutes: 10",
+        "    steps:",
+        `      - uses: ${CHECKOUT}`,
+        "        with:",
+        "          persist-credentials: false",
+        `      - uses: ${SETUP_NODE}`,
+        "        with:",
+        "          node-version: 24",
+        `      - run: ${gateCommand()}`,
+        "",
+    ].join("\n");
+    return withHash([
+        "# Generated by peer-ai render from peer-ai.config.json: the gate, peer-ai check (RFC 0009).",
+        "# Change the config, not this file. Render writes it again while it's as render left it, and leaves",
+        "# it alone once someone changes it by hand. Make the job a required check: its name never changes.",
+    ], body);
+}
+/** Whether the project's CI is GitHub Actions: workflows of its own, or the gate render wrote. */
+export function onGitHubActions(root) {
+    return read(root, GATE_FILE) !== undefined || filesOf(root, `${WORKFLOWS}/`).some((path) => !OWN.includes(path));
+}
+/** Where the gate stands, and what render does about it. */
+export function planGate(root, config) {
+    if (config.delivery?.gate === false)
+        return {};
+    const existing = read(root, GATE_FILE);
+    const others = filesOf(root, `${WORKFLOWS}/`).filter((path) => path !== GATE_FILE);
+    const onActions = onGitHubActions(root) || (config.delivery?.pipeline ?? "").startsWith(WORKFLOWS);
+    if (onActions) {
+        if (existing === undefined) {
+            // A gate someone added to a workflow of their own is enough: there is never a second one.
+            const elsewhere = others.find((path) => runsGate(read(root, path) ?? ""));
+            if (elsewhere !== undefined)
+                return { runsIn: elsewhere };
+            return { planned: { path: GATE_FILE, action: "create", content: gateWorkflow(config) } };
+        }
+        if (unchangedSinceRender(existing)) {
+            const content = gateWorkflow(config);
+            const same = sameFile(existing, content);
+            return {
+                planned: { path: GATE_FILE, action: same ? "unchanged" : "update", ...(same ? {} : { content }) },
+                runsIn: GATE_FILE,
+            };
+        }
+        return {
+            planned: {
+                path: GATE_FILE,
+                action: "kept",
+                note: "It was changed by hand, so keeping it up to date is yours now; peer-ai doctor checks it still runs peer-ai check. Delete it to have render write Peer AI's again.",
+            },
+            ...(runsGate(existing) ? { runsIn: GATE_FILE } : {}),
+        };
+    }
+    const pipeline = detectDelivery(root)?.pipeline ?? (config.delivery?.ci === "existing" ? config.delivery.pipeline : undefined);
+    // A workflows folder that holds only Peer AI's own files isn't the project's CI.
+    if (pipeline === undefined || pipeline.startsWith(WORKFLOWS))
+        return {};
+    const runs = filesOf(root, pipeline).find((path) => runsGate(read(root, path) ?? ""));
+    if (runs !== undefined)
+        return { runsIn: runs };
+    return {
+        manual: `Your CI, ${pipeline}, doesn't run Peer AI's gate. Add a step that runs, with Node 24, after the project's own checks: ${gateCommand()}`,
+    };
+}
+const NOT_GATED = "No CI runs peer-ai check, so nothing holds work to its record in CI.";
+/**
+ * peer-ai doctor's check: CI runs the gate, unless the config turns it off. With no CI yet there is
+ * nothing to say; the delivery check reports that already.
+ */
+export function checkGate(root, config) {
+    if (config.delivery?.gate === false)
+        return [skip("gate", "The CI gate is off: delivery.gate is false.")];
+    const gate = planGate(root, config);
+    const action = gate.planned?.action;
+    if (action === "create")
+        return [warn("gate", NOT_GATED, `Run npx peer-ai render. It writes ${GATE_FILE}.`)];
+    if (action === "update")
+        return [warn("gate", `${GATE_FILE} is out of date.`, "Run npx peer-ai render.")];
+    if (action === "kept" && gate.runsIn === undefined) {
+        return [
+            warn("gate", `${GATE_FILE} was changed by hand, and no longer runs peer-ai check.`, `Put the step back: - run: ${gateCommand()}`),
+        ];
+    }
+    if (gate.runsIn !== undefined)
+        return [ok("gate", `CI runs peer-ai check: ${gate.runsIn}`)];
+    if (gate.manual !== undefined)
+        return [warn("gate", NOT_GATED, gate.manual)];
+    return [];
+}

package/dist/migrate.js

@@ -11,6 +11,7 @@ import { dirname, join, sep } from "node:path";
 import { validateConfig } from "peer-ai-workflow";
 import { LEGACY_MARKERS, loadConfig, runAssess } from "./assess.js";
 import { CONFIG_FILE, detect } from "./detect.js";
+import { GATE_FILE, onGitHubActions } from "./gate.js";
 import { ask, buildConfig, defaults } from "./init.js";
 import { Cancelled } from "./prompter.js";
 import { runRender } from "./render.js";
@@ -467,6 +468,14 @@ export function planMigration(root, detected, answers, fingerprints, repo) {
     if (leftAlone.length > 0) {
         decisions.push({ title: "Left as they were", body: leftAlone.map((line) => `- ${line}`) });
     }
+    if (onGitHubActions(root)) {
+        decisions.push({
+            title: "Make Peer AI's CI gate a required check",
+            body: [
+                `\`render\` added ${code(GATE_FILE)}, which runs \`peer-ai check\` on every pull request (RFC 0009). Only the repository's owner can make a check required: in GitHub, add the status check \`peer-ai check\` to the main branch's rules, so no change merges without it.`,
+            ],
+        });
+    }
     // The config: init's, plus everything converted.
     const config = buildConfig(detected, answers);
     const tracks = config.tracks.map((track) => dormantTracks.has(String(track.id)) ? { ...track, status: "dormant" } : track);

package/dist/pipeline.d.ts

@@ -1,6 +1,8 @@
 import { type PipelineJob } from "peer-ai-standards";
 import type { PeerAiConfig } from "peer-ai-workflow";
 export declare const WORKFLOW_FILE = ".github/workflows/peer-ai-security.yml";
+export declare const CHECKOUT = "actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1";
+export declare const SETUP_NODE = "actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0";
 /** A container image, pinned to its digest: Docker uses the digest, and the tag says which release it is. */
 export interface Image {
     name: string;
@@ -71,6 +73,8 @@ export declare function pipelineRules(config: PeerAiConfig): import("peer-ai-sta
 export declare function workflowBody(config: PeerAiConfig): string | undefined;
 /** The jobs the workflow render writes would run: the keys under jobs:. */
 export declare function workflowJobs(config: PeerAiConfig): string[];
+/** A file render owns: its header, a line recording the body's hash, then the body. */
+export declare const withHash: (header: string[], body: string) => string;
 /** The whole file render writes: a header recording the body's hash, then the body. */
 export declare function workflowFile(config: PeerAiConfig): string | undefined;
 /** Whether a file was written by render: it records a hash in its header. */

package/dist/pipeline.js

@@ -11,7 +11,8 @@ import { PROFILES, profileRulesFor } from "peer-ai-standards";
 export const WORKFLOW_FILE = ".github/workflows/peer-ai-security.yml";
 /** The folder the tools are installed in, on the PATH of the job's later steps. */
 const TOOLS = '"$RUNNER_TEMP/peer-ai-tools"';
-const CHECKOUT = "actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1";
+export const CHECKOUT = "actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1";
+export const SETUP_NODE = "actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0";
 const UPLOAD = "actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1";
 const GITLEAKS = {
     version: "8.30.1",
@@ -237,18 +238,18 @@ export function workflowJobs(config) {
 const normalise = (text) => text.replaceAll("\r\n", "\n");
 const hash = (body) => createHash("sha256").update(normalise(body)).digest("hex").slice(0, 16);
 const HASH_LINE = /^# peer-ai sha256: ([0-9a-f]{16})$/m;
+/** A file render owns: its header, a line recording the body's hash, then the body. */
+export const withHash = (header, body) => [...header, `# peer-ai sha256: ${hash(body)}`, body].join("\n");
 /** The whole file render writes: a header recording the body's hash, then the body. */
 export function workflowFile(config) {
     const body = workflowBody(config);
     if (body === undefined)
         return undefined;
-    return [
+    return withHash([
         "# Generated by peer-ai render from peer-ai.config.json: the checks of the github-actions stack profile.",
         "# Change the config, not this file. Render writes it again while it's as render left it, and leaves",
         "# it alone once someone changes it by hand. Make each job a required check: their names never change.",
-        `# peer-ai sha256: ${hash(body)}`,
-        body,
-    ].join("\n");
+    ], body);
 }
 /** Whether a file was written by render: it records a hash in its header. */
 export const writtenByRender = (content) => HASH_LINE.test(normalise(content));

package/dist/render.js

@@ -16,7 +16,8 @@ import { count, fail, formatChecks, ok, plural, skip } from "./checks.js";
 import { CONFIG_FILE } from "./detect.js";
 import { FEEDBACK_DIR } from "./feedback.js";
 import { VERSION } from "./package-info.js";
-import { WORKFLOW_FILE, sameFile, unchangedSinceRender, workflowFile } from "./pipeline.js";
+import { planGate } from "./gate.js";
+import { CHECKOUT, SETUP_NODE, WORKFLOW_FILE, sameFile, unchangedSinceRender, workflowFile } from "./pipeline.js";
 import { RUFF_FILE, ruffFile } from "./ruff.js";
 export const START = "<!-- peer-ai:start -->";
 export const END = "<!-- peer-ai:end -->";
@@ -325,8 +326,6 @@ function cursorEnvironment(root, command) {
         return { ...environment, start: next };
     }, `add to its "start" command: ${command}`);
 }
-const CHECKOUT = "actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1";
-const SETUP_NODE = "actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0";
 /**
  * Copilot's cloud agent runs the copilot-setup-steps job before it starts. A workflow that already
  * exists is left to its owner, with the step to add.
@@ -472,6 +471,12 @@ export function planRender(root, config) {
             });
         }
     }
+    // The CI gate, peer-ai check (RFC 0009): a workflow of its own on GitHub Actions, a step to add elsewhere.
+    const gate = planGate(root, config);
+    if (gate.planned !== undefined)
+        files.push(gate.planned);
+    if (gate.manual !== undefined)
+        manual.push(gate.manual);
     if (uses("claude-code"))
         files.push(claudeSessionHook(root, command));
     if (uses("cursor"))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peer-ai",
-  "version": "1.0.0-next.1",
+  "version": "1.0.0-next.2",
   "description": "Keeps AI coding tools to a senior team's standard: planning, testing, security and compliance, with proof of every check",
   "license": "MIT",
   "type": "module",
@@ -10,9 +10,9 @@
   "dependencies": {
     "@clack/prompts": "1.8.1",
     "@modelcontextprotocol/sdk": "1.30.1",
-    "peer-ai-skills": "1.0.0-next.1",
-    "peer-ai-standards": "1.0.0-next.1",
-    "peer-ai-workflow": "1.0.0-next.1",
+    "peer-ai-skills": "1.0.0-next.2",
+    "peer-ai-standards": "1.0.0-next.2",
+    "peer-ai-workflow": "1.0.0-next.2",
     "jsonc-parser": "3.3.1",
     "smol-toml": "1.9.0",
     "yaml": "2.9.1",