@next-friday/create-app 7.0.0 → 7.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@next-friday/create-app",
-  "version": "7.0.0",
+  "version": "7.1.0",
   "description": "Create a Next Friday project from a template.",
   "keywords": [
     "create",
@@ -74,6 +74,7 @@
     "format": "prettier --write --cache .",
     "format:check": "prettier --check --cache . && editorconfig-checker",
     "gates:check": "node scripts/check-agent-gates.ts",
+    "human-gates:check": "node scripts/check-human-gates.ts",
     "knip": "knip",
     "lint": "eslint . --fix --cache --max-warnings=0 --no-inline-config",
     "lint:check": "eslint . --cache --max-warnings=0 --no-inline-config",
@@ -86,6 +87,6 @@
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit -p tsconfig.json",
-    "verify": "pnpm suppressions:check && pnpm rules:check && pnpm gates:check && pnpm lint:check && pnpm format:check && pnpm sort-package-json:check && pnpm typecheck && pnpm test:coverage && pnpm knip && pnpm build && pnpm check:publint"
+    "verify": "pnpm suppressions:check && pnpm rules:check && pnpm gates:check && pnpm human-gates:check && pnpm lint:check && pnpm format:check && pnpm sort-package-json:check && pnpm typecheck && pnpm test:coverage && pnpm knip && pnpm build && pnpm check:publint"
   }
 }

package/templates/base/.agents/rules/constitution-changes.md

@@ -2,4 +2,4 @@
 
 The constitution is the set of files that agent settings deny to agents: rules, hooks, lint, format, and commit configuration, and the agent settings themselves. It is company policy.
 
-A developer changes the constitution through a dedicated issue, never inside a feature pull request. When a task needs a constitution change, propose it to the user, reference that issue, and wait for it to merge before the task depends on it.
+The constitution changes in a pull request like any other change, and a code owner approves it in review. Agent settings stop an agent from editing these files. When a task needs a constitution change, write the exact new text and the files it goes in on the pull request; a person commits it to that branch.

package/templates/base/.agents/skills/sdlc/playbooks/plan.md

@@ -7,10 +7,12 @@ This playbook writes the intent. The build plan, `intent/<change>/plan.md`, come
 3. Interview until the originator has said four things: the problem (who, how often, and a number with its source), the outcome as the user would see it, the constraints, and what is out of scope.
    - **When all four are already said, go to step 4 in the same turn.**
    - **When one is missing, ask and stop.** Write no draft in that turn. Ask in rounds: each round holds only questions that do not depend on another question in the same round, each asks one thing, numbered, each with a concrete answer you recommend, worded so "yes" accepts it. A recommended answer is a fact or a choice, such as "Recommended: only the checkout page", never an instruction to the person. When you have no answer to recommend, write "No recommendation" and ask plainly. Wait for the answers, and build the next round on them.
-4. Write `intent/<change>/intent.md` from the template below, where `<change>` is a short kebab-case name. Write the file in the language of the files already in `intent/`. Use exactly the template's five headings; what is out of scope goes under **Proposed outcome**. Anything else that is unknown, unverified, or not yet decided goes under **Open questions**; write "None" only when nothing is, and never list what the originator already answered. Show the whole draft, and name the file only as `intent/<change>/intent.md`.
-5. **Gate: the originator corrects the draft.** Ask whether it matches what they meant, and revise until they say yes. Commit nothing, push nothing, and open no pull request before that yes.
+4. Write `intent/<change>/intent.md` from the template below, where `<change>` is a short kebab-case name. Write the file in the language of the files already in `intent/`. Use exactly the template's five headings; what is out of scope goes under **Proposed outcome**. Anything else that is unknown, unverified, or not yet decided goes under **Open questions**; write "None" only when nothing is, and never list what the originator already answered. Show the whole draft, and name the file only as `intent/<change>/intent.md`. In plan mode you cannot write the file: show the draft as the plan, and write the file once it is approved.
+5. **Gate: the originator corrects the draft.** Ask whether it matches what they meant, and revise until they say yes. Commit nothing, push nothing, and open no pull request before that yes. In plan mode, the originator approving the plan is that yes.
 6. Commit `intent.md` on a new branch, push it, and open a pull request ready for review, as `AGENTS.md` says for branches and pull requests.
-7. **Gate: the product owner accepts or rejects the intent.** The product owner sets `Status: accepted.` or `Status: rejected.` and merges the pull request; you do neither. Report the pull request's URL, keep it green as `AGENTS.md` says, and wait.
+7. **Gate: the product owner accepts or rejects the intent.** The product owner accepts by setting `Status: accepted.` and merging the pull request, or rejects by closing it; you do neither. Report the pull request's URL, keep it green as `AGENTS.md` says, and wait.
+
+**Next:** `.agents/skills/write-spec/SKILL.md`; an agent; when the product owner has merged the intent's pull request and a person or a trigger asks for the spec.
 
 ## Template
 

package/templates/base/.agents/skills/sdlc/playbooks/question.md

@@ -4,3 +4,5 @@
 2. Answer, citing `path:line` or command output for each claim, as the **Write replies a person can check** convention in `AGENTS.md` says.
 3. Write no file, make no commit, push nothing, and post nothing to GitHub or another service.
 4. When the answer shows work worth doing, offer it in one line, such as "Send `/sdlc write an intent for this` to start the change", and stop.
+
+**Next:** none; the person; when they send a new message.

package/templates/base/.claude/skills/sdlc/playbooks/plan.md

@@ -7,10 +7,12 @@ This playbook writes the intent. The build plan, `intent/<change>/plan.md`, come
 3. Interview until the originator has said four things: the problem (who, how often, and a number with its source), the outcome as the user would see it, the constraints, and what is out of scope.
    - **When all four are already said, go to step 4 in the same turn.**
    - **When one is missing, ask and stop.** Write no draft in that turn. Ask in rounds: each round holds only questions that do not depend on another question in the same round, each asks one thing, numbered, each with a concrete answer you recommend, worded so "yes" accepts it. A recommended answer is a fact or a choice, such as "Recommended: only the checkout page", never an instruction to the person. When you have no answer to recommend, write "No recommendation" and ask plainly. Wait for the answers, and build the next round on them.
-4. Write `intent/<change>/intent.md` from the template below, where `<change>` is a short kebab-case name. Write the file in the language of the files already in `intent/`. Use exactly the template's five headings; what is out of scope goes under **Proposed outcome**. Anything else that is unknown, unverified, or not yet decided goes under **Open questions**; write "None" only when nothing is, and never list what the originator already answered. Show the whole draft, and name the file only as `intent/<change>/intent.md`.
-5. **Gate: the originator corrects the draft.** Ask whether it matches what they meant, and revise until they say yes. Commit nothing, push nothing, and open no pull request before that yes.
+4. Write `intent/<change>/intent.md` from the template below, where `<change>` is a short kebab-case name. Write the file in the language of the files already in `intent/`. Use exactly the template's five headings; what is out of scope goes under **Proposed outcome**. Anything else that is unknown, unverified, or not yet decided goes under **Open questions**; write "None" only when nothing is, and never list what the originator already answered. Show the whole draft, and name the file only as `intent/<change>/intent.md`. In plan mode you cannot write the file: show the draft as the plan, and write the file once it is approved.
+5. **Gate: the originator corrects the draft.** Ask whether it matches what they meant, and revise until they say yes. Commit nothing, push nothing, and open no pull request before that yes. In plan mode, the originator approving the plan is that yes.
 6. Commit `intent.md` on a new branch, push it, and open a pull request ready for review, as `AGENTS.md` says for branches and pull requests.
-7. **Gate: the product owner accepts or rejects the intent.** The product owner sets `Status: accepted.` or `Status: rejected.` and merges the pull request; you do neither. Report the pull request's URL, keep it green as `AGENTS.md` says, and wait.
+7. **Gate: the product owner accepts or rejects the intent.** The product owner accepts by setting `Status: accepted.` and merging the pull request, or rejects by closing it; you do neither. Report the pull request's URL, keep it green as `AGENTS.md` says, and wait.
+
+**Next:** `.agents/skills/write-spec/SKILL.md`; an agent; when the product owner has merged the intent's pull request and a person or a trigger asks for the spec.
 
 ## Template
 

package/templates/base/.claude/skills/sdlc/playbooks/question.md

@@ -4,3 +4,5 @@
 2. Answer, citing `path:line` or command output for each claim, as the **Write replies a person can check** convention in `AGENTS.md` says.
 3. Write no file, make no commit, push nothing, and post nothing to GitHub or another service.
 4. When the answer shows work worth doing, offer it in one line, such as "Send `/sdlc write an intent for this` to start the change", and stop.
+
+**Next:** none; the person; when they send a new message.

package/templates/base/.cursor/skills/sdlc/playbooks/plan.md

@@ -7,10 +7,12 @@ This playbook writes the intent. The build plan, `intent/<change>/plan.md`, come
 3. Interview until the originator has said four things: the problem (who, how often, and a number with its source), the outcome as the user would see it, the constraints, and what is out of scope.
    - **When all four are already said, go to step 4 in the same turn.**
    - **When one is missing, ask and stop.** Write no draft in that turn. Ask in rounds: each round holds only questions that do not depend on another question in the same round, each asks one thing, numbered, each with a concrete answer you recommend, worded so "yes" accepts it. A recommended answer is a fact or a choice, such as "Recommended: only the checkout page", never an instruction to the person. When you have no answer to recommend, write "No recommendation" and ask plainly. Wait for the answers, and build the next round on them.
-4. Write `intent/<change>/intent.md` from the template below, where `<change>` is a short kebab-case name. Write the file in the language of the files already in `intent/`. Use exactly the template's five headings; what is out of scope goes under **Proposed outcome**. Anything else that is unknown, unverified, or not yet decided goes under **Open questions**; write "None" only when nothing is, and never list what the originator already answered. Show the whole draft, and name the file only as `intent/<change>/intent.md`.
-5. **Gate: the originator corrects the draft.** Ask whether it matches what they meant, and revise until they say yes. Commit nothing, push nothing, and open no pull request before that yes.
+4. Write `intent/<change>/intent.md` from the template below, where `<change>` is a short kebab-case name. Write the file in the language of the files already in `intent/`. Use exactly the template's five headings; what is out of scope goes under **Proposed outcome**. Anything else that is unknown, unverified, or not yet decided goes under **Open questions**; write "None" only when nothing is, and never list what the originator already answered. Show the whole draft, and name the file only as `intent/<change>/intent.md`. In plan mode you cannot write the file: show the draft as the plan, and write the file once it is approved.
+5. **Gate: the originator corrects the draft.** Ask whether it matches what they meant, and revise until they say yes. Commit nothing, push nothing, and open no pull request before that yes. In plan mode, the originator approving the plan is that yes.
 6. Commit `intent.md` on a new branch, push it, and open a pull request ready for review, as `AGENTS.md` says for branches and pull requests.
-7. **Gate: the product owner accepts or rejects the intent.** The product owner sets `Status: accepted.` or `Status: rejected.` and merges the pull request; you do neither. Report the pull request's URL, keep it green as `AGENTS.md` says, and wait.
+7. **Gate: the product owner accepts or rejects the intent.** The product owner accepts by setting `Status: accepted.` and merging the pull request, or rejects by closing it; you do neither. Report the pull request's URL, keep it green as `AGENTS.md` says, and wait.
+
+**Next:** `.agents/skills/write-spec/SKILL.md`; an agent; when the product owner has merged the intent's pull request and a person or a trigger asks for the spec.
 
 ## Template
 

package/templates/base/.cursor/skills/sdlc/playbooks/question.md

@@ -4,3 +4,5 @@
 2. Answer, citing `path:line` or command output for each claim, as the **Write replies a person can check** convention in `AGENTS.md` says.
 3. Write no file, make no commit, push nothing, and post nothing to GitHub or another service.
 4. When the answer shows work worth doing, offer it in one line, such as "Send `/sdlc write an intent for this` to start the change", and stop.
+
+**Next:** none; the person; when they send a new message.

package/templates/base/SETUP.md

@@ -4,7 +4,7 @@ This project follows Anthropic's [AI-native SDLC Playbook](https://claude.com/re
 
 ## How a change flows
 
-1. **Plan:** the originator of an idea, a ticket, or an incident sends it with `/sdlc`, which interviews them and writes `intent/<change>/intent.md`. The product owner merges it with `Status: accepted.` or `Status: rejected.`
+1. **Plan:** the originator of an idea, a ticket, or an incident sends it with `/sdlc`, which interviews them and writes `intent/<change>/intent.md`. The product owner accepts it by merging it with `Status: accepted.`, or rejects it by closing its pull request.
 2. **Design:** `spec.md` is written from the accepted intent with the policy skills loaded (`write-spec` skill). The product owner resolves concerns with the policy owners.
 3. **Build:** the engineer starts in plan mode, approves the plan, and commits it as `plan.md`. A tech lead approves higher-risk plans.
 4. **Test:** the session runs **Verifying your work** in `AGENTS.md`.

package/templates/base/scripts/check-human-gates.ts

@@ -0,0 +1,383 @@
+import {existsSync, readdirSync, readFileSync, statSync} from "node:fs";
+import path from "node:path";
+
+type Problem = {
+  line: number;
+  message: string;
+  rule: string;
+};
+
+type Step = {
+  line: number;
+  text: string;
+};
+
+type SelfTestCase = {
+  expectedRule?: string;
+  name: string;
+  text: string;
+};
+
+const playbookDirectory = ".agents/skills/sdlc/playbooks";
+const agentOwnedWorkRule = ".agents/rules/agent-owned-work.md";
+const nextMarker = "**Next:**";
+
+const humanGateRoles = [
+  "originator",
+  "product owner",
+  "engineer",
+  "code owner",
+  "release manager",
+  "service owner",
+];
+
+const roleWords = new RegExp(String.raw`\b(?:${humanGateRoles.join("|")})s?\b`, "i");
+
+const waitingWordList = [
+  "wait",
+  "waits",
+  "approve",
+  "approves",
+  "approval",
+  "approved",
+  "approving",
+  "confirm",
+  "confirms",
+  "confirmation",
+  "permission",
+  "sign off",
+];
+
+const waitingWords = new RegExp(String.raw`\b(?:${waitingWordList.join("|")})\b`, "i");
+const roleList = humanGateRoles.join(", ");
+
+/**
+ * Blank every line of a fenced code block, keeping line numbers.
+ * @param text Playbook content with LF line endings.
+ * @returns The content with fenced lines emptied.
+ */
+function maskFencedBlocks(text: string): string {
+  let isFenced = false;
+
+  return text
+    .split("\n")
+    .map(line => {
+      const isFence = /^\s*(?:```|~~~)/.test(line);
+      const isMasked = isFenced || isFence;
+
+      isFenced = isFence ? !isFenced : isFenced;
+
+      return isMasked ? "" : line;
+    })
+    .join("\n");
+}
+
+/**
+ * Split a playbook into its numbered steps, each with its indented continuation lines.
+ * @param text Playbook content.
+ * @returns The steps with the line each starts on.
+ */
+function splitSteps(text: string): Step[] {
+  return Array.from(text.matchAll(/^\d+\. .*(?:\n[\t ]+\S.*)*/gm), match => ({
+    line: text.slice(0, match.index).split("\n").length,
+    text: match[0],
+  }));
+}
+
+/**
+ * Find gate lines whose bold sentence names no human gate role.
+ * @param lines Playbook lines.
+ * @returns One problem per such line.
+ */
+function findGateProblems(lines: string[]): Problem[] {
+  return lines
+    .map((text, index) => ({
+      text,
+      line: index + 1,
+    }))
+    .filter(({text}) => text.includes("**Gate:"))
+    .filter(({text}) => !roleWords.test(/\*\*Gate:(.*?)\*\*/.exec(text)?.[1] ?? ""))
+    .map(({line}) => ({
+      line,
+      rule: "A",
+      message: `a gate must name one of ${roleList} inside its bold sentence; write "**Gate: the <role> <does what>.**"`,
+    }));
+}
+
+/**
+ * Find steps that wait, approve, or confirm without naming a human gate role.
+ * @param text Playbook content.
+ * @returns One problem per such step.
+ */
+function findWaitingStepProblems(text: string): Problem[] {
+  return splitSteps(text)
+    .filter(step => waitingWords.test(step.text) && !roleWords.test(step.text))
+    .map(step => ({
+      rule: "B",
+      line: step.line,
+      message: `a step that waits, approves, or confirms must name who does it: one of ${roleList}`,
+    }));
+}
+
+/**
+ * Tell whether a path is a relative path without `..` to an existing regular file.
+ * @param targetPath Path from a `**Next:**` target.
+ * @returns True when the path is usable.
+ */
+function isProjectFile(targetPath: string): boolean {
+  const segments = targetPath.split(/[\\/]/);
+
+  return (
+    !path.isAbsolute(targetPath) &&
+    !segments.includes("..") &&
+    statSync(targetPath, {
+      throwIfNoEntry: false,
+    })?.isFile() === true
+  );
+}
+
+/**
+ * Describe what is wrong with the text after a `**Next:**` marker.
+ * @param text The text after the marker.
+ * @returns The problem, or an empty string when the line is valid.
+ */
+function describeNextProblem(text: string): string {
+  const parts = text.replace(/\.\s*$/, "").split(";");
+
+  if (parts.length !== 3 || parts.some(part => part.trim() === "")) {
+    return `"${nextMarker}" needs exactly three non-empty parts separated by ";" and no other ";": the target, who runs it, and what starts it`;
+  }
+
+  const target = parts.at(0)?.trim() ?? "";
+  const targetPath = /^`([^`\s]+)`$/.exec(target)?.[1];
+
+  return target !== "none" && (targetPath === undefined || !isProjectFile(targetPath))
+    ? `the "${nextMarker}" target must be "none" or one backticked relative path to an existing file in the project, with no ".." segment, found ${target}`
+    : "";
+}
+
+/**
+ * Find a missing, repeated, or malformed `**Next:**` line.
+ * @param lines Playbook lines.
+ * @returns The problems with the next-step line.
+ */
+function findNextProblems(lines: string[]): Problem[] {
+  const nextLines = lines
+    .map((text, index) => ({
+      text,
+      line: index + 1,
+    }))
+    .filter(({text}) => text.startsWith(nextMarker));
+
+  const next = nextLines.at(0);
+
+  if (next === undefined || nextLines.length !== 1) {
+    return [
+      {
+        rule: "C",
+        line: next?.line ?? 1,
+        message: `a playbook needs exactly one line starting with "${nextMarker}", found ${nextLines.length}; write "${nextMarker} <target>; <who runs it>; <what starts it>."`,
+      },
+    ];
+  }
+
+  const message = describeNextProblem(next.text.slice(nextMarker.length));
+
+  return message === ""
+    ? []
+    : [
+        {
+          message,
+          rule: "C",
+          line: next.line,
+        },
+      ];
+}
+
+/**
+ * Check one playbook against rules A, B, and C.
+ * @param text Playbook content.
+ * @returns Every problem found.
+ */
+function checkPlaybook(text: string): Problem[] {
+  const unfenced = maskFencedBlocks(text.replaceAll("\r\n", "\n"));
+  const lines = unfenced.split("\n");
+
+  return [
+    ...findGateProblems(lines),
+    ...findWaitingStepProblems(unfenced),
+    ...findNextProblems(lines),
+  ];
+}
+
+/**
+ * List the human gate roles a rule text does not mention.
+ * @param ruleText Content of the agent-owned work rule.
+ * @returns The missing roles.
+ */
+function findMissingRoles(ruleText: string): string[] {
+  return humanGateRoles.filter(role => !ruleText.toLowerCase().includes(role));
+}
+
+const validNext = "**Next:** none; the person; when they write.";
+
+const selfTestCases: SelfTestCase[] = [
+  {
+    name: "gate names a role",
+    text: `**Gate: the originator corrects the draft.**\n\n${validNext}`,
+  },
+  {
+    expectedRule: "A",
+    name: "gate names no role",
+    text: `**Gate: the manager corrects the draft.**\n\n${validNext}`,
+  },
+  {
+    expectedRule: "A",
+    name: "role outside the bold gate sentence",
+    text: `**Gate: the draft is corrected.** The originator does it.\n\n${validNext}`,
+  },
+  {
+    name: "waiting step names a role",
+    text: `1. Wait for the engineer.\n\n${validNext}`,
+  },
+  ...waitingWordList.map(word => ({
+    expectedRule: "B",
+    name: `waiting word "${word}" names no role`,
+    text: `1. Ask, then ${word} for the answer.\n\n${validNext}`,
+  })),
+  {
+    name: "plural role",
+    text: `1. Wait for the engineers and the code owners.\n\n${validNext}`,
+  },
+  {
+    expectedRule: "B",
+    name: "longer word that starts with a role",
+    text: `1. Wait for the engineering team.\n\n${validNext}`,
+  },
+  {
+    name: "CRLF line endings",
+    text: `1. Ask, then wait.\r\n   - The code owner answers.\r\n\r\n${validNext}\r\n`,
+  },
+  {
+    name: "gate inside a fenced block",
+    text: `\`\`\`\n**Gate: the manager corrects the draft.**\n\`\`\`\n\n${validNext}`,
+  },
+  {
+    name: "next inside a fenced block",
+    text: `\`\`\`\n**Next:** none; ; x\n\`\`\`\n\n${validNext}`,
+  },
+  {
+    expectedRule: "B",
+    name: "waiting word on a continuation line",
+    text: `1. Ask.\n   - Wait for the answer.\n\n${validNext}`,
+  },
+  {
+    name: "role on a continuation line covers the step",
+    text: `1. Ask, then wait.\n   - The code owner answers.\n\n${validNext}`,
+  },
+  {
+    name: "target is an existing path",
+    text: "**Next:** `package.json`; an agent; when asked.",
+  },
+  {
+    expectedRule: "C",
+    name: "target path does not exist",
+    text: "**Next:** `missing/file.md`; an agent; when asked.",
+  },
+  {
+    expectedRule: "C",
+    name: "target is an absolute path",
+    text: "**Next:** `/etc/hostname`; an agent; when asked.",
+  },
+  {
+    expectedRule: "C",
+    name: "target has a .. segment",
+    text: "**Next:** `.agents/../package.json`; an agent; when asked.",
+  },
+  {
+    expectedRule: "C",
+    name: "target is a directory",
+    text: "**Next:** `.agents`; an agent; when asked.",
+  },
+  {
+    expectedRule: "C",
+    name: "target is not backticked",
+    text: "**Next:** package.json; an agent; when asked.",
+  },
+  {
+    expectedRule: "C",
+    name: "next has two parts",
+    text: "**Next:** none; the person.",
+  },
+  {
+    expectedRule: "C",
+    name: "next has an empty part",
+    text: "**Next:** none; ; when they write.",
+  },
+  {
+    expectedRule: "C",
+    name: "next is missing",
+    text: "1. Answer.",
+  },
+  {
+    expectedRule: "C",
+    name: "next appears twice",
+    text: `${validNext}\n${validNext}`,
+  },
+];
+
+const selfTestFailures = selfTestCases
+  .filter(({expectedRule, text}) => {
+    const rules = checkPlaybook(text).map(problem => problem.rule);
+
+    return expectedRule === undefined ? rules.length > 0 : rules.join(",") !== expectedRule;
+  })
+  .map(({name}) => name);
+
+if (findMissingRoles(humanGateRoles.join(" ")).length > 0) {
+  selfTestFailures.push("a rule naming every role has no missing role");
+}
+
+if (findMissingRoles("no role").length !== humanGateRoles.length) {
+  selfTestFailures.push("a rule naming no role is missing every role");
+}
+
+if (existsSync(playbookDirectory) && existsSync(agentOwnedWorkRule)) {
+  if (selfTestFailures.length > 0) {
+    const failureLines = selfTestFailures.map(name => `- ${name}`);
+
+    process.stderr.write(`Human gate self-tests failed:\n${failureLines.join("\n")}\n`);
+    process.exitCode = 1;
+  } else {
+    const playbooks = readdirSync(playbookDirectory)
+      .filter(name => name.endsWith(".md"))
+      .map(name => `${playbookDirectory}/${name}`);
+
+    const problemLines = [
+      ...playbooks.flatMap(playbook =>
+        checkPlaybook(readFileSync(playbook, "utf8")).map(
+          ({line, message}) => `${playbook}:${line}: ${message}`,
+        ),
+      ),
+      ...findMissingRoles(readFileSync(agentOwnedWorkRule, "utf8")).map(
+        role =>
+          `${agentOwnedWorkRule}:1: the human gate role "${role}" is missing; name it in the rule or remove it from scripts/check-human-gates.ts`,
+      ),
+    ];
+
+    if (problemLines.length > 0) {
+      process.stderr.write(`${problemLines.join("\n")}\n`);
+      process.exitCode = 1;
+    } else {
+      process.stdout.write(
+        `Checked ${playbooks.length} playbooks against ${humanGateRoles.length} human gate roles.\n`,
+      );
+    }
+  }
+} else {
+  process.stderr.write(
+    `Run from the project root: ${playbookDirectory} and ${agentOwnedWorkRule} must exist.\n`,
+  );
+
+  process.exitCode = 1;
+}

package/templates/nestjs/.agents/rules.json

@@ -12,7 +12,7 @@
     "description": "Codebase hygiene: modify existing code instead of accumulating new code"
   },
   "constitution-changes": {
-    "description": "Constitution changes: change rules, hooks, and agent settings only through a dedicated issue",
+    "description": "Constitution changes: change rules, hooks, and agent settings in a pull request a code owner approves",
     "globs": [
       ".agents/rules/**",
       ".agents/rules.json",

package/templates/nestjs/.claude/rules/constitution-changes.md

@@ -22,4 +22,4 @@ paths:
 
 The constitution is the set of files that agent settings deny to agents: rules, hooks, lint, format, and commit configuration, and the agent settings themselves. It is company policy.
 
-A developer changes the constitution through a dedicated issue, never inside a feature pull request. When a task needs a constitution change, propose it to the user, reference that issue, and wait for it to merge before the task depends on it.
+The constitution changes in a pull request like any other change, and a code owner approves it in review. Agent settings stop an agent from editing these files. When a task needs a constitution change, write the exact new text and the files it goes in on the pull request; a person commits it to that branch.

package/templates/nestjs/.cursor/rules/constitution-changes.mdc

@@ -1,5 +1,5 @@
 ---
-description: "Constitution changes: change rules, hooks, and agent settings only through a dedicated issue"
+description: "Constitution changes: change rules, hooks, and agent settings in a pull request a code owner approves"
 globs: ".agents/rules/**,.agents/rules.json,.agents/hooks/**,.claude/settings.json,.claude/rules/**,.cursor/rules/**,.cursor/hooks/**,.cursor/hooks.json,scripts/sync-agent-rules.ts,scripts/check-agent-gates.ts,.husky/**,.commitlintrc.json,.prettierrc.json,eslint.config.ts,.lintstagedrc.json,.gitleaks.toml"
 alwaysApply: false
 ---
@@ -8,4 +8,4 @@ alwaysApply: false
 
 The constitution is the set of files that agent settings deny to agents: rules, hooks, lint, format, and commit configuration, and the agent settings themselves. It is company policy.
 
-A developer changes the constitution through a dedicated issue, never inside a feature pull request. When a task needs a constitution change, propose it to the user, reference that issue, and wait for it to merge before the task depends on it.
+The constitution changes in a pull request like any other change, and a code owner approves it in review. Agent settings stop an agent from editing these files. When a task needs a constitution change, write the exact new text and the files it goes in on the pull request; a person commits it to that branch.

package/templates/nestjs/.github/workflows/ci.yml

@@ -79,6 +79,8 @@ jobs:
         run: pnpm rules:check
       - name: Check agent gates
         run: pnpm gates:check
+      - name: Check human gates
+        run: pnpm human-gates:check
       - name: Check lint
         run: pnpm lint:check
       - name: Check formatting

package/templates/nestjs/package.json

@@ -22,6 +22,7 @@
     "format": "prettier --write --cache .",
     "format:check": "prettier --check --cache . && editorconfig-checker",
     "gates:check": "node scripts/check-agent-gates.ts",
+    "human-gates:check": "node scripts/check-human-gates.ts",
     "knip": "knip",
     "lint": "eslint . --fix --cache --max-warnings=0 --no-inline-config",
     "lint:check": "eslint . --cache --max-warnings=0 --no-inline-config",
@@ -43,7 +44,7 @@
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "verify": "pnpm verify:static && pnpm test:coverage && pnpm build",
-    "verify:static": "pnpm suppressions:check && pnpm rules:check && pnpm gates:check && pnpm lint:check && pnpm format:check && pnpm sort-package-json:check && pnpm peers:check && pnpm typecheck && pnpm knip && pnpm depcruise"
+    "verify:static": "pnpm suppressions:check && pnpm rules:check && pnpm gates:check && pnpm human-gates:check && pnpm lint:check && pnpm format:check && pnpm sort-package-json:check && pnpm peers:check && pnpm typecheck && pnpm knip && pnpm depcruise"
   },
   "dependencies": {
     "@nestjs/common": "12.3.2",

package/templates/nextjs/.agents/rules.json

@@ -12,7 +12,7 @@
     "description": "Codebase hygiene: modify existing code instead of accumulating new code"
   },
   "constitution-changes": {
-    "description": "Constitution changes: change rules, hooks, and agent settings only through a dedicated issue",
+    "description": "Constitution changes: change rules, hooks, and agent settings in a pull request a code owner approves",
     "globs": [
       ".agents/rules/**",
       ".agents/rules.json",

package/templates/nextjs/.claude/rules/constitution-changes.md

@@ -22,4 +22,4 @@ paths:
 
 The constitution is the set of files that agent settings deny to agents: rules, hooks, lint, format, and commit configuration, and the agent settings themselves. It is company policy.
 
-A developer changes the constitution through a dedicated issue, never inside a feature pull request. When a task needs a constitution change, propose it to the user, reference that issue, and wait for it to merge before the task depends on it.
+The constitution changes in a pull request like any other change, and a code owner approves it in review. Agent settings stop an agent from editing these files. When a task needs a constitution change, write the exact new text and the files it goes in on the pull request; a person commits it to that branch.

package/templates/nextjs/.cursor/rules/constitution-changes.mdc

@@ -1,5 +1,5 @@
 ---
-description: "Constitution changes: change rules, hooks, and agent settings only through a dedicated issue"
+description: "Constitution changes: change rules, hooks, and agent settings in a pull request a code owner approves"
 globs: ".agents/rules/**,.agents/rules.json,.agents/hooks/**,.claude/settings.json,.claude/rules/**,.cursor/rules/**,.cursor/hooks/**,.cursor/hooks.json,scripts/sync-agent-rules.ts,scripts/check-agent-gates.ts,.husky/**,.commitlintrc.json,prettier.config.ts,eslint.config.ts,.lintstagedrc.json,.gitleaks.toml"
 alwaysApply: false
 ---
@@ -8,4 +8,4 @@ alwaysApply: false
 
 The constitution is the set of files that agent settings deny to agents: rules, hooks, lint, format, and commit configuration, and the agent settings themselves. It is company policy.
 
-A developer changes the constitution through a dedicated issue, never inside a feature pull request. When a task needs a constitution change, propose it to the user, reference that issue, and wait for it to merge before the task depends on it.
+The constitution changes in a pull request like any other change, and a code owner approves it in review. Agent settings stop an agent from editing these files. When a task needs a constitution change, write the exact new text and the files it goes in on the pull request; a person commits it to that branch.

package/templates/nextjs/.github/workflows/ci.yml

@@ -79,6 +79,8 @@ jobs:
         run: pnpm rules:check
       - name: Check agent gates
         run: pnpm gates:check
+      - name: Check human gates
+        run: pnpm human-gates:check
       - name: Check lint
         run: pnpm lint:check
       - name: Check formatting

package/templates/nextjs/package.json

@@ -19,6 +19,7 @@
     "format": "prettier --write --cache .",
     "format:check": "prettier --check --cache . && editorconfig-checker",
     "gates:check": "node scripts/check-agent-gates.ts",
+    "human-gates:check": "node scripts/check-human-gates.ts",
     "knip": "knip",
     "lint": "eslint . --fix --cache --max-warnings=0 --no-inline-config",
     "lint:check": "eslint . --cache --max-warnings=0 --no-inline-config",
@@ -37,7 +38,7 @@
     "test:watch": "vitest",
     "typecheck": "next typegen && tsc --noEmit -p tsconfig.json",
     "verify": "pnpm verify:static && pnpm test:coverage && pnpm build",
-    "verify:static": "pnpm suppressions:check && pnpm rules:check && pnpm gates:check && pnpm lint:check && pnpm format:check && pnpm sort-package-json:check && pnpm peers:check && pnpm typecheck && pnpm knip && pnpm depcruise"
+    "verify:static": "pnpm suppressions:check && pnpm rules:check && pnpm gates:check && pnpm human-gates:check && pnpm lint:check && pnpm format:check && pnpm sort-package-json:check && pnpm peers:check && pnpm typecheck && pnpm knip && pnpm depcruise"
   },
   "dependencies": {
     "next": "16.4.3",

package/templates/nodejs/.agents/rules.json

@@ -12,7 +12,7 @@
     "description": "Codebase hygiene: modify existing code instead of accumulating new code"
   },
   "constitution-changes": {
-    "description": "Constitution changes: change rules, hooks, and agent settings only through a dedicated issue",
+    "description": "Constitution changes: change rules, hooks, and agent settings in a pull request a code owner approves",
     "globs": [
       ".agents/rules/**",
       ".agents/rules.json",

package/templates/nodejs/.claude/rules/constitution-changes.md

@@ -22,4 +22,4 @@ paths:
 
 The constitution is the set of files that agent settings deny to agents: rules, hooks, lint, format, and commit configuration, and the agent settings themselves. It is company policy.
 
-A developer changes the constitution through a dedicated issue, never inside a feature pull request. When a task needs a constitution change, propose it to the user, reference that issue, and wait for it to merge before the task depends on it.
+The constitution changes in a pull request like any other change, and a code owner approves it in review. Agent settings stop an agent from editing these files. When a task needs a constitution change, write the exact new text and the files it goes in on the pull request; a person commits it to that branch.

package/templates/nodejs/.cursor/rules/constitution-changes.mdc

@@ -1,5 +1,5 @@
 ---
-description: "Constitution changes: change rules, hooks, and agent settings only through a dedicated issue"
+description: "Constitution changes: change rules, hooks, and agent settings in a pull request a code owner approves"
 globs: ".agents/rules/**,.agents/rules.json,.agents/hooks/**,.claude/settings.json,.claude/rules/**,.cursor/rules/**,.cursor/hooks/**,.cursor/hooks.json,scripts/sync-agent-rules.ts,scripts/check-agent-gates.ts,.husky/**,.commitlintrc.json,.prettierrc.json,eslint.config.ts,.lintstagedrc.json,.gitleaks.toml"
 alwaysApply: false
 ---
@@ -8,4 +8,4 @@ alwaysApply: false
 
 The constitution is the set of files that agent settings deny to agents: rules, hooks, lint, format, and commit configuration, and the agent settings themselves. It is company policy.
 
-A developer changes the constitution through a dedicated issue, never inside a feature pull request. When a task needs a constitution change, propose it to the user, reference that issue, and wait for it to merge before the task depends on it.
+The constitution changes in a pull request like any other change, and a code owner approves it in review. Agent settings stop an agent from editing these files. When a task needs a constitution change, write the exact new text and the files it goes in on the pull request; a person commits it to that branch.

package/templates/nodejs/.github/workflows/ci.yml

@@ -79,6 +79,8 @@ jobs:
         run: pnpm rules:check
       - name: Check agent gates
         run: pnpm gates:check
+      - name: Check human gates
+        run: pnpm human-gates:check
       - name: Check lint
         run: pnpm lint:check
       - name: Check formatting

package/templates/nodejs/package.json

@@ -18,6 +18,7 @@
     "format": "prettier --write --cache .",
     "format:check": "prettier --check --cache . && editorconfig-checker",
     "gates:check": "node scripts/check-agent-gates.ts",
+    "human-gates:check": "node scripts/check-human-gates.ts",
     "knip": "knip",
     "lint": "eslint . --fix --cache --max-warnings=0 --no-inline-config",
     "lint:check": "eslint . --cache --max-warnings=0 --no-inline-config",
@@ -37,7 +38,7 @@
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "verify": "pnpm verify:static && pnpm test:coverage && pnpm build",
-    "verify:static": "pnpm suppressions:check && pnpm rules:check && pnpm gates:check && pnpm lint:check && pnpm format:check && pnpm sort-package-json:check && pnpm peers:check && pnpm typecheck && pnpm knip && pnpm depcruise"
+    "verify:static": "pnpm suppressions:check && pnpm rules:check && pnpm gates:check && pnpm human-gates:check && pnpm lint:check && pnpm format:check && pnpm sort-package-json:check && pnpm peers:check && pnpm typecheck && pnpm knip && pnpm depcruise"
   },
   "devDependencies": {
     "@commitlint/cli": "21.2.4",

package/templates/payload/.agents/rules.json

@@ -12,7 +12,7 @@
     "description": "Codebase hygiene: modify existing code instead of accumulating new code"
   },
   "constitution-changes": {
-    "description": "Constitution changes: change rules, hooks, and agent settings only through a dedicated issue",
+    "description": "Constitution changes: change rules, hooks, and agent settings in a pull request a code owner approves",
     "globs": [
       ".agents/rules/**",
       ".agents/rules.json",

package/templates/payload/.claude/rules/constitution-changes.md

@@ -22,4 +22,4 @@ paths:
 
 The constitution is the set of files that agent settings deny to agents: rules, hooks, lint, format, and commit configuration, and the agent settings themselves. It is company policy.
 
-A developer changes the constitution through a dedicated issue, never inside a feature pull request. When a task needs a constitution change, propose it to the user, reference that issue, and wait for it to merge before the task depends on it.
+The constitution changes in a pull request like any other change, and a code owner approves it in review. Agent settings stop an agent from editing these files. When a task needs a constitution change, write the exact new text and the files it goes in on the pull request; a person commits it to that branch.

package/templates/payload/.cursor/rules/constitution-changes.mdc

@@ -1,5 +1,5 @@
 ---
-description: "Constitution changes: change rules, hooks, and agent settings only through a dedicated issue"
+description: "Constitution changes: change rules, hooks, and agent settings in a pull request a code owner approves"
 globs: ".agents/rules/**,.agents/rules.json,.agents/hooks/**,.claude/settings.json,.claude/rules/**,.cursor/rules/**,.cursor/hooks/**,.cursor/hooks.json,scripts/sync-agent-rules.ts,scripts/check-agent-gates.ts,.husky/**,.commitlintrc.json,.prettierrc.json,eslint.config.ts,.lintstagedrc.json,.gitleaks.toml"
 alwaysApply: false
 ---
@@ -8,4 +8,4 @@ alwaysApply: false
 
 The constitution is the set of files that agent settings deny to agents: rules, hooks, lint, format, and commit configuration, and the agent settings themselves. It is company policy.
 
-A developer changes the constitution through a dedicated issue, never inside a feature pull request. When a task needs a constitution change, propose it to the user, reference that issue, and wait for it to merge before the task depends on it.
+The constitution changes in a pull request like any other change, and a code owner approves it in review. Agent settings stop an agent from editing these files. When a task needs a constitution change, write the exact new text and the files it goes in on the pull request; a person commits it to that branch.

package/templates/payload/.github/workflows/ci.yml

@@ -96,6 +96,8 @@ jobs:
         run: pnpm rules:check
       - name: Check agent gates
         run: pnpm gates:check
+      - name: Check human gates
+        run: pnpm human-gates:check
       - name: Check lint
         run: pnpm lint:check
       - name: Check formatting

package/templates/payload/package.json

@@ -21,6 +21,7 @@
     "gates:check": "node scripts/check-agent-gates.ts",
     "generate:importmap": "payload generate:importmap",
     "generate:types": "payload generate:types",
+    "human-gates:check": "node scripts/check-human-gates.ts",
     "knip": "node --env-file-if-exists=.env node_modules/knip/bin/knip.js",
     "lint": "eslint . --fix --cache --max-warnings=0 --no-inline-config",
     "lint:check": "eslint . --cache --max-warnings=0 --no-inline-config",
@@ -42,7 +43,7 @@
     "test:watch": "vitest",
     "typecheck": "next typegen && tsc --noEmit -p tsconfig.json",
     "verify": "pnpm verify:static && pnpm test:coverage && pnpm build",
-    "verify:static": "pnpm suppressions:check && pnpm rules:check && pnpm gates:check && pnpm lint:check && pnpm format:check && pnpm sort-package-json:check && pnpm peers:check && pnpm typecheck && pnpm knip && pnpm depcruise"
+    "verify:static": "pnpm suppressions:check && pnpm rules:check && pnpm gates:check && pnpm human-gates:check && pnpm lint:check && pnpm format:check && pnpm sort-package-json:check && pnpm peers:check && pnpm typecheck && pnpm knip && pnpm depcruise"
   },
   "dependencies": {
     "@payloadcms/db-postgres": "3.92.1",

package/templates/turborepo/.agents/rules.json

@@ -12,7 +12,7 @@
     "description": "Codebase hygiene: modify existing code instead of accumulating new code"
   },
   "constitution-changes": {
-    "description": "Constitution changes: change rules, hooks, and agent settings only through a dedicated issue",
+    "description": "Constitution changes: change rules, hooks, and agent settings in a pull request a code owner approves",
     "globs": [
       ".agents/rules/**",
       ".agents/rules.json",

package/templates/turborepo/.claude/rules/constitution-changes.md

@@ -22,4 +22,4 @@ paths:
 
 The constitution is the set of files that agent settings deny to agents: rules, hooks, lint, format, and commit configuration, and the agent settings themselves. It is company policy.
 
-A developer changes the constitution through a dedicated issue, never inside a feature pull request. When a task needs a constitution change, propose it to the user, reference that issue, and wait for it to merge before the task depends on it.
+The constitution changes in a pull request like any other change, and a code owner approves it in review. Agent settings stop an agent from editing these files. When a task needs a constitution change, write the exact new text and the files it goes in on the pull request; a person commits it to that branch.

package/templates/turborepo/.cursor/rules/constitution-changes.mdc

@@ -1,5 +1,5 @@
 ---
-description: "Constitution changes: change rules, hooks, and agent settings only through a dedicated issue"
+description: "Constitution changes: change rules, hooks, and agent settings in a pull request a code owner approves"
 globs: ".agents/rules/**,.agents/rules.json,.agents/hooks/**,.claude/settings.json,.claude/rules/**,.cursor/rules/**,.cursor/hooks/**,.cursor/hooks.json,scripts/sync-agent-rules.ts,scripts/check-agent-gates.ts,.husky/**,.commitlintrc.json,prettier.config.ts,eslint.config.ts,.lintstagedrc.json,.gitleaks.toml"
 alwaysApply: false
 ---
@@ -8,4 +8,4 @@ alwaysApply: false
 
 The constitution is the set of files that agent settings deny to agents: rules, hooks, lint, format, and commit configuration, and the agent settings themselves. It is company policy.
 
-A developer changes the constitution through a dedicated issue, never inside a feature pull request. When a task needs a constitution change, propose it to the user, reference that issue, and wait for it to merge before the task depends on it.
+The constitution changes in a pull request like any other change, and a code owner approves it in review. Agent settings stop an agent from editing these files. When a task needs a constitution change, write the exact new text and the files it goes in on the pull request; a person commits it to that branch.

package/templates/turborepo/.github/workflows/ci.yml

@@ -118,6 +118,8 @@ jobs:
         run: pnpm rules:check
       - name: Check agent gates
         run: pnpm gates:check
+      - name: Check human gates
+        run: pnpm human-gates:check
       - name: Check lint
         run: pnpm lint:check
       - name: Check formatting

package/templates/turborepo/package.json

@@ -21,6 +21,7 @@
     "gates:check": "node scripts/check-agent-gates.ts",
     "generate:importmap": "pnpm --filter ./apps/backoffice generate:importmap",
     "generate:types": "pnpm --filter ./apps/backoffice generate:types",
+    "human-gates:check": "node scripts/check-human-gates.ts",
     "knip": "knip",
     "lint": "eslint . --fix --cache --max-warnings=0 --no-inline-config",
     "lint:check": "eslint . --cache --max-warnings=0 --no-inline-config",
@@ -41,7 +42,7 @@
     "test:watch": "turbo run test:watch --filter=./apps/*",
     "typecheck": "tsc --noEmit -p tsconfig.json && turbo run typecheck ${TURBO_FILTER:-\"--filter=./apps/*\"}",
     "verify": "pnpm verify:static && pnpm test:coverage && pnpm build",
-    "verify:static": "pnpm suppressions:check && pnpm rules:check && pnpm gates:check && pnpm lint:check && pnpm format:check && pnpm sort-package-json:check && pnpm peers:check && pnpm typecheck && pnpm knip && pnpm depcruise"
+    "verify:static": "pnpm suppressions:check && pnpm rules:check && pnpm gates:check && pnpm human-gates:check && pnpm lint:check && pnpm format:check && pnpm sort-package-json:check && pnpm peers:check && pnpm typecheck && pnpm knip && pnpm depcruise"
   },
   "devDependencies": {
     "@commitlint/cli": "21.2.4",