@jaybeeuu/agent-cortex 1.41.1 → 1.43.0

package/extensions/subagent/agents.ts

@@ -4,6 +4,7 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { fileURLToPath } from "node:url";
 import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
 
 export type AgentScope = "user" | "project" | "both";
@@ -23,6 +24,25 @@ export interface AgentDiscoveryResult {
 	projectAgentsDir: string | null;
 }
 
+/**
+ * Parse a frontmatter `tools` value into PI tool names.
+ *
+ * `parseFrontmatter` returns the scalar as a single string, and agent files are
+ * written with either a comma-separated list (`tools: read, grep`) or a
+ * whitespace-separated one. Splitting on commas alone collapses the whitespace
+ * form into one bogus name, which becomes a `--tools` allowlist matching no
+ * tool — the subagent then runs with an empty tool block. Accept both
+ * separators so neither form can zero out the tool list.
+ *
+ * @param {string | undefined} tools  Raw frontmatter `tools` scalar
+ * @returns {string[] | undefined} Tool names, or undefined when there are none
+ */
+export function parseToolList(tools: string | undefined): string[] | undefined {
+	const parsed = tools?.split(/[,\s]+/).filter(Boolean);
+
+	return parsed && parsed.length > 0 ? parsed : undefined;
+}
+
 function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig[] {
 	const agents: AgentConfig[] = [];
 
@@ -49,22 +69,17 @@ function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig
 			continue;
 		}
 
-		const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
+		const { frontmatter, body } = parseFrontmatter<Record<string, unknown>>(content);
 
-		if (!frontmatter.name || !frontmatter.description) {
+		if (typeof frontmatter.name !== "string" || typeof frontmatter.description !== "string") {
 			continue;
 		}
 
-		const tools = frontmatter.tools
-			?.split(",")
-			.map((t: string) => t.trim())
-			.filter(Boolean);
-
 		agents.push({
 			name: frontmatter.name,
 			description: frontmatter.description,
-			tools: tools && tools.length > 0 ? tools : undefined,
-			model: frontmatter.model,
+			tools: readTools(frontmatter.tools),
+			model: typeof frontmatter.model === "string" ? frontmatter.model : undefined,
 			systemPrompt: body,
 			source,
 			filePath,
@@ -74,6 +89,21 @@ function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig
 	return agents;
 }
 
+/**
+ * The tools of a frontmatter `tools` value, which is written either as a YAML
+ * scalar (one string) or as a YAML sequence (an array).
+ */
+function readTools(value: unknown): string[] | undefined {
+	if (Array.isArray(value)) {
+		const tools = value
+			.filter((tool): tool is string => typeof tool === "string")
+			.map((tool) => tool.trim())
+			.filter(Boolean);
+		return tools.length > 0 ? tools : undefined;
+	}
+	return parseToolList(typeof value === "string" ? value : undefined);
+}
+
 function isDirectory(p: string): boolean {
 	try {
 		return fs.statSync(p).isDirectory();
@@ -94,11 +124,72 @@ function findNearestProjectAgentsDir(cwd: string): string | null {
 	}
 }
 
+/**
+ * The package this extension ships inside: `<extension>/../..`, i.e. the repo
+ * checkout or the staged pi package.
+ */
+const PACKAGE_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+/**
+ * True when `agentsDir` is a rendered tree — flat `*.agent.md` files and no
+ * composable `<name>/agent.md` source directories.
+ */
+function isRenderedAgentsTree(agentsDir: string): boolean {
+	if (!isDirectory(agentsDir)) return false;
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(agentsDir, { withFileTypes: true });
+	} catch {
+		return false;
+	}
+	return !entries.some((entry) => entry.isDirectory() && fs.existsSync(path.join(agentsDir, entry.name, "agent.md")));
+}
+
+/**
+ * Directories the "user" scope discovers agents from, in precedence order.
+ *
+ * pi's own user agent dir comes first: it holds hand-written personal agents
+ * and the copies older installers made, so existing setups keep resolving what
+ * they did before. Second is the package this extension ships inside, which is
+ * what makes a staged pi package self-contained — `agent-cortex install pi`
+ * renders the flat pi agents into `<package>/agents`.
+ *
+ * A source checkout contributes nothing: its `agents/` tree is the composable
+ * source (composed at runtime by the agent-modes extension) alongside flat
+ * renders for other harnesses — Copilot's, whose tool names pi does not have.
+ */
+export function resolveUserAgentDirs(packageRoot: string = PACKAGE_ROOT): string[] {
+	const dirs: string[] = [];
+	const add = (dir: string) => {
+		const resolved = path.resolve(dir);
+		if (!dirs.includes(resolved) && isDirectory(resolved)) dirs.push(resolved);
+	};
+
+	add(path.join(getAgentDir(), "agents"));
+	const packageAgentsDir = path.join(packageRoot, "agents");
+	if (isRenderedAgentsTree(packageAgentsDir)) add(packageAgentsDir);
+
+	return dirs;
+}
+
+/**
+ * Load the user-scope agents from `dirs`, first directory wins on a name
+ * collision. Missing directories contribute nothing.
+ */
+export function loadUserAgents(dirs: string[]): AgentConfig[] {
+	const byName = new Map<string, AgentConfig>();
+	for (const dir of dirs) {
+		for (const agent of loadAgentsFromDir(dir, "user")) {
+			if (!byName.has(agent.name)) byName.set(agent.name, agent);
+		}
+	}
+	return Array.from(byName.values());
+}
+
 export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryResult {
-	const userDir = path.join(getAgentDir(), "agents");
 	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
 
-	const userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
+	const userAgents = scope === "project" ? [] : loadUserAgents(resolveUserAgentDirs());
 	const projectAgents = scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
 
 	const agentMap = new Map<string, AgentConfig>();

package/extensions/subagent/index.ts

@@ -461,7 +461,8 @@ export default function (pi: ExtensionAPI) {
 		description: [
 			"Delegate tasks to specialized subagents with isolated context.",
 			"Modes: single (agent + task), parallel (tasks array), chain (sequential with {previous} placeholder).",
-			'Default agent scope is "user" (from ~/.pi/agent/agents).',
+			'Default agent scope is "user": ~/.pi/agent/agents plus the agents/ tree of the package',
+			"this extension ships inside.",
 			'To enable project-local agents in .pi/agents, set agentScope: "both" (or "project").',
 		].join(" "),
 		parameters: SubagentParams,

package/extensions/subagent/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "test": "node --test --import tsx/esm wait.test.ts",
+    "test": "node --test --import tsx/esm wait.test.ts agents.test.ts",
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {

package/lib/cli.mjs

@@ -9,7 +9,6 @@ const INSTALL_OPTIONS = {
   "--output": { key: "output" },
   "--plugin-root": { key: "pluginRoot" },
   "--require-register": { key: "requireRegister", boolean: true },
-  "--no-provision": { key: "noProvision", boolean: true },
 };
 
 export function parseArgs(argv) {
@@ -94,16 +93,43 @@ Commands:
                                          plugin.json "agents" scans)
                         --dry-run        Print what would be generated without writing
                       Options (pi):
-                        --dry-run             Show what would be installed without writing
-                        --output <dir>        Install into <dir> — agents/, skills/,
-                                              settings.json (merged, packages managed)
-                                              and keybindings.json (default: ~/.pi/agent)
+                        (no --output)         Materialise the pi package into
+                                              ~/.agent-cortex/pi: package.json,
+                                              agents/, skills/, extensions/ and
+                                              the bundled third-party pi packages
+                                              (pi-questions, pi-web-access), then
+                                              REGISTER that directory with pi via
+                                              "pi install" (user scope, idempotent
+                                              by state: a re-run is a no-op update,
+                                              and stale raw-repo sources are
+                                              removed so one source remains).
+                                              Once registered, the artifacts the
+                                              pre-staged-model installer rendered
+                                              into ~/.pi/agent are removed in a
+                                              one-time migration: agents and
+                                              skills whose names this package
+                                              ships or once shipped. Anything
+                                              else there is left alone, including
+                                              the whole extensions/ directory.
+                                              A migration that removed every
+                                              copy it attributed is recorded in
+                                              ~/.agent-cortex/legacy-sweep.json
+                                              (keyed by the pi user directory)
+                                              and never runs there twice; one
+                                              that could not be completed warns
+                                              and is retried on the next install.
+                        --output <dir>        Stage the package into <dir> only —
+                                              no registration (default:
+                                              ~/.agent-cortex/pi)
+                        --dry-run             Show what would be staged and
+                                              registered without writing or spawning
                         --plugin-root <dir>   Override the plugin root used for {{PATH:...}}
                                               tokens (default: token-map.json's pi value)
-                        --no-provision        Skip installing the third-party pi packages
-                                              declared in the package manifest (e.g.
-                                              pi-questions, pi-web-access). They are
-                                              installed by default on a real install.
+                        --require-register
+                                              Fail the install when the pi CLI
+                                              cannot register the staged package
+                                              (missing from PATH); default warns and
+                                              prints the manual commands
   --help, -h          Show this help text`;
 }
 

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@jaybeeuu/agent-cortex",
-  "version": "1.41.1",
+  "version": "1.43.0",
   "description": "Personal PI package with custom agents, skills, and extensions",
   "keywords": [
     "pi-package"
   ],
   "license": "MIT",
-  "repository": "https://github.com/jaybeeuu/agent-cortex",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jaybeeuu/agent-cortex"
+  },
   "bin": {
     "agent-cortex": "./bin/agent-cortex.mjs"
   },
@@ -24,12 +27,12 @@
     ],
     "skills": [
       "./skills"
-    ],
-    "packages": [
-      "npm:pi-questions",
-      "npm:pi-web-access@0.10.7"
     ]
   },
+  "dependencies": {
+    "pi-questions": "^0.3.4",
+    "pi-web-access": "0.10.7"
+  },
   "scripts": {
     "build": "echo 'Build complete — no compilation needed for PI package'",
     "lint": "pnpm typecheck && pnpm check:sync",
@@ -40,6 +43,7 @@
     "changeset": "changeset",
     "version-packages": "changeset version && bash scripts/sync-plugin-version.sh && pnpm build:copilot",
     "publish-package": "TARBALL=$(pnpm pack | tail -n 1) && npm publish \"$TARBALL\" --provenance --access public",
+    "publish-noop": "echo 'No publish: the merged PR carries the no-publish label.'",
     "release": "changeset publish",
     "postinstall": "bash scripts/install-instructions.sh"
   }

package/pi/settings.json

@@ -6,15 +6,9 @@
   },
   "lastChangelogVersion": "0.87.1",
   "packages": [
-    {
-      "source": "../../src/agent-cortex",
-      "skills": []
-    },
-    "npm:pi-web-access@0.10.7",
     "npm:@getpipher/vision",
     "npm:@hypabolic/pi-hypa",
-    "npm:context-mode",
-    "npm:pi-questions"
+    "npm:context-mode"
   ],
   "defaultProvider": "opencode-go",
   "defaultModel": "deepseek-v4.1-flash",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-cortex",
   "description": "Personal Copilot CLI plugin with custom agents and skills",
-  "version": "1.41.1",
+  "version": "1.43.0",
   "author": {
     "name": "jaybeeuu"
   },

package/pnpm-workspace.yaml

@@ -5,4 +5,10 @@ packages:
 allowBuilds:
   '@google/genai': false
   esbuild: false
+  # koffi (an optionalDependency of @mariozechner/pi-tui, which pi-questions
+  # peers on) ships prebuilt build/koffi/<platform>_<arch>/*.node binaries that
+  # index.js loads directly. Its install script (cnoke --prebuild) only
+  # matters for toolchains with no shipped binary, so deny it: acknowledged
+  # explicitly to satisfy the strict allowlist, no compilation, no download.
+  koffi: false
   protobufjs: false

package/scripts/check-changeset.mjs

@@ -0,0 +1,42 @@
+// PR gate: a pull request must add a changeset (.changeset/*.md) unless it is
+// the changesets bot's Version Packages PR or carries the `no-publish` label.
+// Reads `git diff --name-status <base>...HEAD` on stdin and the PR metadata
+// from the environment (CI supplies all three).
+import { evaluateChangesetGate, parseNameStatus } from "./lib/release-gates.mjs";
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function readLabels(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    console.error("::error::PR_LABELS must be a JSON array of label names.");
+    process.exit(1);
+  }
+}
+
+const labels = readLabels(process.env.PR_LABELS ?? "[]");
+const changes = parseNameStatus(await readStdin());
+const result = evaluateChangesetGate({
+  changes,
+  labels,
+  headRef: process.env.PR_HEAD_REF ?? "",
+  actor: process.env.PR_ACTOR ?? "",
+});
+
+if (result.ok) {
+  console.log(`✓ Changeset gate passed (${result.reason}).`);
+} else {
+  console.error(
+    [
+      "::error::This PR adds no changeset (.changeset/*.md).",
+      "Publishing is the default: write a changeset file (see the style-versioning skill)",
+      "and commit it, or label the PR 'no-publish' when it genuinely ships nothing.",
+    ].join("\n"),
+  );
+  process.exitCode = 1;
+}

package/scripts/lib/release-gates.mjs

@@ -0,0 +1,61 @@
+// Decision logic for the two release gates that stop `main` re-publishing an
+// already-published version. Both gates are pure: the CLI adapters read git
+// diffs, env vars, and the GitHub API, then delegate the decision here.
+//
+// Model: publishing is the default. The only path to "no publish" is an
+// explicit `no-publish` label on the merged PR — skipping is never implicit.
+
+export const NO_PUBLISH_LABEL = "no-publish";
+export const PUBLISH_COMMAND = "pnpm publish-package";
+export const NO_PUBLISH_COMMAND = "pnpm publish-noop";
+
+// The changesets bot's Version Packages PR consumes changesets and adds none.
+const VERSION_PACKAGES_HEAD_REF = "changeset-release/";
+const GITHUB_ACTIONS_BOT = "github-actions[bot]";
+
+const CHANGESET_PATH = /^\.changeset\/[^/]+\.md$/;
+const CHANGESET_EXEMPT_PATHS = new Set([".changeset/README.md"]);
+
+/**
+ * Parse `git diff --name-status` output into `{ status, path }` entries, where
+ * `status` is the single-letter change type and `path` is the new path.
+ */
+export function parseNameStatus(output) {
+  return output
+    .split("\n")
+    .filter((line) => line.trim() !== "")
+    .map((line) => {
+      const [status, ...paths] = line.split("\t");
+      return { status: status.charAt(0), path: paths.at(-1) };
+    });
+}
+
+/**
+ * Decide whether a pull request may skip adding a changeset. Exempt only the
+ * Version Packages PR and PRs explicitly labelled `no-publish`; every other PR
+ * must add its own changeset.
+ */
+export function evaluateChangesetGate({ changes, labels, headRef, actor }) {
+  if (headRef.startsWith(VERSION_PACKAGES_HEAD_REF) || actor === GITHUB_ACTIONS_BOT) {
+    return { ok: true, reason: "version-packages-pr" };
+  }
+  if (labels.includes(NO_PUBLISH_LABEL)) {
+    return { ok: true, reason: "no-publish-label" };
+  }
+  if (changes.some((change) => change.status === "A" && isChangeset(change.path))) {
+    return { ok: true, reason: "changeset-added" };
+  }
+  return { ok: false, reason: "missing-changeset" };
+}
+
+/**
+ * Resolve the command changesets/action should exec for publishing, based on
+ * the labels of the PR merged for the pushed commit.
+ */
+export function resolvePublishCommand(labels) {
+  return labels.includes(NO_PUBLISH_LABEL) ? NO_PUBLISH_COMMAND : PUBLISH_COMMAND;
+}
+
+function isChangeset(path) {
+  return CHANGESET_PATH.test(path) && !CHANGESET_EXEMPT_PATHS.has(path);
+}

package/scripts/lib/verify-worker-tree.mjs

@@ -0,0 +1,107 @@
+// Verify that a dispatched pipeline-stage worker actually delivered.
+//
+// Why this exists: a worker's `---REPORT---` is a claim, not evidence. A stage
+// that reports `OUTCOME: SUCCESS` and leaves its work uncommitted looks
+// identical, from the report alone, to one that committed and pushed — and the
+// orchestrator opens the feature PR from the branch, so uncommitted work is
+// silently dropped. The observed failure was exactly that: workers reporting
+// success with a dirty worktree, every one of them needing a human to finish
+// the tree by hand.
+//
+// This module answers one question against the worktree itself: did this worker
+// leave a clean tree with at least one commit ahead of where it started? It
+// reads nothing the worker wrote, so it cannot be fooled by the worker's prose.
+//
+// Usage (CLI):
+//   node scripts/lib/verify-worker-tree.mjs --worktree <dir> --base <sha>
+//   node scripts/lib/verify-worker-tree.mjs --worktree <dir> --base <ref> --json
+//
+// Exit code is 0 only when the worker delivered, so a caller can gate on it.
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const execFileAsync = promisify(execFile);
+const SELF = fileURLToPath(import.meta.url);
+
+async function git(worktree, args) {
+  const { stdout } = await execFileAsync("git", args, { cwd: worktree });
+  return stdout.trim();
+}
+
+function countPaths(porcelain) {
+  return porcelain.split("\n").filter((line) => line.trim() !== "").length;
+}
+
+/**
+ * Check that a worker delivered: clean worktree and at least one commit ahead
+ * of `base`. Returns the reasons it failed, so the caller can surface them
+ * instead of guessing why a stage did not advance.
+ */
+export async function verifyWorkerTree({ worktree, base }) {
+  const reasons = [];
+
+  const dirty = await git(worktree, ["status", "--porcelain"]);
+  if (dirty !== "") {
+    reasons.push(`worktree is dirty: ${countPaths(dirty)} uncommitted path(s)`);
+  }
+
+  const ahead = Number(await git(worktree, ["rev-list", "--count", `${base}..HEAD`]));
+  if (!Number.isFinite(ahead) || ahead < 1) {
+    reasons.push(`no commit ahead of base ${base.slice(0, 7)}`);
+  }
+
+  return { ok: reasons.length === 0, reasons, commitsAhead: ahead };
+}
+
+// ─── CLI ─────────────────────────────────────────────────────────────────────
+
+function parseFlags(argv) {
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith("--")) continue;
+    const key = arg.slice(2);
+    const next = argv[i + 1];
+    if (next === undefined || next.startsWith("--")) {
+      flags[key] = true;
+    } else {
+      flags[key] = next;
+      i++;
+    }
+  }
+  return flags;
+}
+
+function required(flags, name) {
+  const value = flags[name];
+  if (typeof value !== "string" || value === "") {
+    console.error(`verify-worker-tree: --${name} <value> is required`);
+    process.exit(2);
+  }
+  return value;
+}
+
+async function main(argv) {
+  const flags = parseFlags(argv);
+  const verdict = await verifyWorkerTree({
+    worktree: required(flags, "worktree"),
+    base: required(flags, "base"),
+  });
+
+  if (flags.json) {
+    console.log(JSON.stringify(verdict, null, 2));
+  } else if (verdict.ok) {
+    console.log(`ok: ${verdict.commitsAhead} commit(s) ahead of base, tree clean`);
+  } else {
+    for (const reason of verdict.reasons) console.error(`failed: ${reason}`);
+  }
+
+  process.exit(verdict.ok ? 0 : 1);
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === SELF) {
+  await main(process.argv.slice(2));
+}

package/scripts/resolve-publish-command.mjs

@@ -0,0 +1,17 @@
+// Release gate: print the single-token publish command changesets/action
+// should exec. The merged PR's labels arrive as a JSON array in argv[2]; the
+// action splits the printed command on whitespace with no shell, so it must
+// stay a plain `pnpm <script>` token pair.
+import { resolvePublishCommand } from "./lib/release-gates.mjs";
+
+function readLabels(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    console.error("::error::labels argument must be a JSON array of label names.");
+    process.exit(1);
+  }
+}
+
+const labels = readLabels(process.argv[2] ?? "[]");
+process.stdout.write(`${resolvePublishCommand(labels)}\n`);

package/skills/engineering/grill-with-docs/SKILL.md

@@ -27,7 +27,7 @@ description: "Grilling session that challenges your plan against the existing do
 5. **Cross-reference with code.** When the user states how something works, check whether the code agrees. Surface contradictions the moment you find them.
 6. **Update `CONTEXT.md` inline.** When a term resolves, write the entry right there — do not batch. Keep it a pure glossary: no implementation details, no specs, no scratch notes. Entry format and file-discovery rules live in `REFERENCE.md`.
 7. **Offer ADRs sparingly.** Propose an ADR only when all three hold: hard to reverse, surprising without context, and the result of a real trade-off. If any is missing, skip it. ADR format lives in `REFERENCE.md`.
-8. **Close when shared understanding is reached.** Confirm every design-tree branch is resolved or explicitly deferred, and that the glossary diff captures the session's new language.
+8. **Close when shared understanding is reached.** Confirm every design-tree branch is resolved or explicitly deferred, that the glossary diff captures the session's new language, and — when the session feeds a bead — that there is enough agreed detail to fill every required section of the target bead type (see `bd-tool` → Required sections). Never invent section content; surface assumptions and confirm them.
 
 ## Red Flags
 
@@ -88,4 +88,5 @@ which voids an order before fulfilment. See cancellation.
 - [ ] Terminology conflicts and vague terms called out the moment they appeared
 - [ ] Claims cross-referenced against code; contradictions surfaced
 - [ ] ADRs offered only when all three criteria held (offering none is a valid outcome)
-- [ ] All design-tree branches resolved or explicitly deferred before closing
+- [ ] All design-tree branches resolved or explicitly deferred before closing
+- [ ] When feeding a bead, enough agreed detail to fill every required section; no fabricated answers

package/skills/engineering/improve-codebase-architecture/REFERENCE.md

@@ -43,6 +43,11 @@ Describe the architectural friction:
 - What integration risk exists in the seams between them
 - Why this makes the codebase harder to navigate and maintain
 
+## Acceptance Criteria
+
+- [ ] <verifiable outcome 1>
+- [ ] <verifiable outcome 2>
+
 ## Proposed Interface
 
 The chosen interface design:

package/skills/engineering/improve-codebase-architecture/SKILL.md

@@ -43,7 +43,7 @@ A **deep module** (John Ousterhout, "A Philosophy of Software Design") has a sma
 
 6. **User picks an interface** (or accepts the recommendation).
 
-7. **Create the refactor bead.** Run the `create-task` skill with a concise title, the description from the template in [REFERENCE.md](REFERENCE.md), and priority P2. Always use `create-task` — never `bd create` directly — because it classifies the bead and expands AFK work into pipeline stages ralph can execute. Do not ask the user to review before creating; share the bead ID.
+7. **Create the refactor bead.** Run the `create-task` skill with a concise title, the description from the template in [REFERENCE.md](REFERENCE.md), and priority P2. The template's `## Acceptance Criteria` is required (enforced by `create-task`'s `--validate`) and must reflect outcomes the user agreed, not assumptions. Always use `create-task` — never `bd create` directly — because it classifies the bead and expands AFK work into pipeline stages ralph can execute. Do not ask the user to review before creating; share the bead ID.
 
 ## Red Flags
 
@@ -95,5 +95,6 @@ Output: numbered deepening candidates (cluster, coupling, dependency category, t
 - [ ] At least two radically different designs, each with signature, usage example, hidden complexity, dependency strategy, and trade-offs
 - [ ] Recommendation given in prose, with a hybrid proposed where elements combine well
 - [ ] Refactor bead created via `create-task` at P2 using the REFERENCE.md description template
+- [ ] Description carries agreed `## Acceptance Criteria`; the bead lints clean
 - [ ] Bead ID reported and no review gate imposed before creation
 - [ ] No unrelated areas explored or refactors proposed outside the chosen candidate

package/skills/planning/create-task/SKILL.md

@@ -5,7 +5,7 @@ description: Create a task bead, classify it as AFK or HITL, and if AFK expand i
 
 # Create Task
 
-Turn a piece of work into a tracked bead, classify it for autonomous (AFK) or human-in-the-loop (HITL) execution, and — when AFK — expand it into the standard pipeline: one chore bead per stage plus a HITL PR gate task so a human always reviews the finished branch. Parameters: `title` (required), `description` (required), `priority` (0–3, default 2), `parent` (epic bead ID, optional — sets a `parent-child` dependency).
+Turn a piece of work into a tracked bead, classify it for autonomous (AFK) or human-in-the-loop (HITL) execution, and — when AFK — expand it into the standard pipeline: one chore bead per stage plus a HITL PR gate task so a human always reviews the finished branch. Parameters: `title` (required), `description` (required), `priority` (0–3, default 2), `parent` (epic bead ID, optional — sets a `parent-child` dependency). The description must carry the task's required section — `## Acceptance Criteria` — which `--validate` enforces; fill it from agreed answers, not assumptions (see `bd-tool` → Required sections).
 
 ## When to use
 
@@ -21,10 +21,13 @@ Turn a piece of work into a tracked bead, classify it for autonomous (AFK) or hu
 
 ## Workflow
 
-1. **Create the parent bead.**
+1. **Create the parent bead.** The description must contain the task's required section —
+   `## Acceptance Criteria` — or `--validate` rejects creation. Fill it from agreed answers, not
+   assumptions (see `bd-tool` → Required sections).
 
    ```bash
-   bd create "<title>" --description "<description>" --priority <priority>
+   bd create "<title>" --description "<description>" --priority <priority> --validate
+   bd lint <new-id>
    ```
 
    If a `parent` epic was provided, record the dependency:
@@ -65,6 +68,7 @@ Turn a piece of work into a tracked bead, classify it for autonomous (AFK) or hu
 
 ## Red Flags
 
+- **Filling acceptance criteria with assumptions.** Fabricated criteria pass `--validate` but mislead the pipeline. The description is the interview's output — confirm it with the human instead.
 - **Running the script from the wrong directory.** Chores land in whatever `.beads` tree `bd` resolves from cwd — the target project's root is the only safe cwd.
 - **Spawning the `classify-bead` subagent when the classifier already resolved the bead.** The deterministic script is the short-circuit; a subagent is only for `escalate: true`.
 - **Skipping the classifier and classifying by hand.** The rubric is a subagent's job; a hand-rolled guess drifts from it.
@@ -101,6 +105,7 @@ The full bead-property contract (titles, labels, dependencies per chore and for
 ## Verification checklist
 
 - [ ] Parent bead exists with the correct title, description, and priority.
+- [ ] Parent bead created with `--validate`, and `bd lint <id>` reports no missing sections.
 - [ ] `parent-child` dependency added when a parent epic was supplied.
 - [ ] `implementation-type` label present on the parent bead (`bd label list <id>`) — resolved by the classifier or, on escalation, the rubric subagent.
 - [ ] HITL path: no pipeline chores created, caller told the classification. AFK path: script ran from the target project's cwd and its JSON contains every stage ID plus `featurePrReview`.

package/skills/planning/create-task/scripts/create-chores.ts

@@ -101,8 +101,11 @@ const prGateBeadId = run([
   'bd', 'create', JSON.stringify(`[${parentId}] PR Review and Merge`),
   '--type', 'task',
   '--description', JSON.stringify(
-    'Human review gate: review and merge the agent PR into the feature branch before closing this feature.',
+    'Human review gate: review and merge the agent PR into the feature branch before closing this feature.\n\n## Acceptance Criteria\n\n- [ ] Agent PR reviewed and merged into the feature branch.',
   ),
+  // The gate is type `task`, so `--validate` enforces its `## Acceptance Criteria`
+  // section. Stage chores require no sections and deliberately omit the flag.
+  '--validate',
   '--priority', priority,
   '--labels', 'implementation-type:hitl,lifecycle:feature-pr',
   '--parent', parentId,