@jaybeeuu/agent-cortex 2.0.0 → 2.1.0

package/extensions/output-style/output-style.ts

@@ -0,0 +1,32 @@
+/**
+ * Output style for the PI system prompt.
+ *
+ * The second slice of docs/ideas/improve-pi-system-prompt.md: the reply shape, not
+ * the task discipline. Three concerns, in order — lead with the action, write in
+ * Simplified Technical English, restate the context the reader cannot remember.
+ *
+ * The prose lives in output-style.md so one file feeds both harnesses: this
+ * extension appends it to the PI system prompt, and the Claude installer wraps it
+ * in a managed CLAUDE.md section. It is read once at load, so the appended text is
+ * stable across turns and keeps the prompt-cache prefix intact. The marker doubles
+ * as an idempotency guard: a chained prompt that already carries the block is
+ * returned unchanged.
+ */
+
+import { readFileSync } from "node:fs";
+
+export const OUTPUT_STYLE_MARKER = "## Output style (agent-cortex)";
+
+export const OUTPUT_STYLE = readFileSync(new URL("./output-style.md", import.meta.url), "utf-8");
+
+/**
+ * Append the output-style block to a system prompt.
+ *
+ * The base prompt is preserved verbatim (minus trailing whitespace) so callers can
+ * chain this after other `before_agent_start` handlers. Idempotent: a prompt that
+ * already contains the marker is returned unchanged.
+ */
+export function appendOutputStyle(systemPrompt: string): string {
+  if (systemPrompt.includes(OUTPUT_STYLE_MARKER)) return systemPrompt;
+  return `${systemPrompt.trimEnd()}\n\n${OUTPUT_STYLE}`;
+}

package/extensions/output-style/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@agent-cortex/output-style",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "node --test --import tsx/esm output-style.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.78.1"
+  }
+}

package/extensions/output-style/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "strict": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "skipLibCheck": true
+  },
+  "include": ["*.ts"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaybeeuu/agent-cortex",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Personal PI package with custom agents, skills, and extensions",
   "keywords": [
     "pi-package"
@@ -35,8 +35,9 @@
   },
   "scripts": {
     "build": "echo 'Build complete — no compilation needed for PI package'",
-    "lint": "pnpm typecheck && pnpm check:sync",
+    "lint": "pnpm typecheck && pnpm check:sync && pnpm check:skills",
     "check:sync": "node scripts/check-no-sync.mjs",
+    "check:skills": "node scripts/check-skill-frontmatter.mjs",
     "test": "node --test test/*.test.mjs && pnpm -r test",
     "typecheck": "pnpm -r typecheck",
     "changeset": "changeset",

package/scripts/check-skill-frontmatter.mjs

@@ -0,0 +1,21 @@
+// Repo convention: every SKILL.md frontmatter must parse and declare a name and
+// description, because PI silently drops a skill whose frontmatter throws. Runs
+// via `pnpm lint` (CI) and locally. Scans the repository root, so both skills/
+// and repo-local .agents/skills/ are covered.
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { checkSkills } from "./lib/skill-frontmatter.mjs";
+
+const ROOT = join(fileURLToPath(new URL(".", import.meta.url)), "..");
+
+const { checked, failures } = await checkSkills({ root: ROOT });
+
+if (failures.length > 0) {
+  console.error("✗ Invalid SKILL.md frontmatter — PI would silently drop these skills:");
+  for (const { file, errors } of failures) {
+    for (const error of errors) console.error(`  ${file}: ${error}`);
+  }
+  process.exit(1);
+}
+
+console.log(`✓ SKILL.md frontmatter valid (${checked} files)`);

package/scripts/lib/skill-frontmatter.mjs

@@ -0,0 +1,135 @@
+// SKILL.md frontmatter validation, shared by `pnpm lint` (via
+// scripts/check-skill-frontmatter.mjs) and its tests.
+//
+// PI reads a skill's frontmatter with `parse` from the `yaml` package and
+// silently drops the skill when that parse throws — only a warning diagnostic
+// is emitted. A skill whose frontmatter is broken therefore disappears from the
+// prompt with no visible failure. This module makes that failure loud: every
+// SKILL.md must parse, declare a non-empty `name` and `description`, and keep
+// the description within PI's 1024-character limit.
+//
+// Frontmatter extraction mirrors PI's parseFrontmatter (dist/utils/frontmatter.js), so a
+// SKILL.md that PI drops — frontmatter that will not parse, or no description — fails here
+// too. The check is stricter than PI in two places PI only warns about: `name` must be a
+// non-empty frontmatter field (PI falls back to the directory name), and a description over
+// 1024 characters is an error.
+//
+// Known gaps, each verified against PI's loader and left unhandled on purpose:
+// - A symlinked SKILL.md is skipped: `entry.isFile()` is false for a symlink, while PI
+//   stats through the link and loads it. No symlinked SKILL.md exists in this repo.
+// - Duplicate `name` values across skill roots are not detected: validation is per-file
+//   with no name index, while PI drops the loser of a name collision.
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { parse } from "yaml";
+
+/** PI's maximum description length — a longer description is rejected. */
+export const MAX_DESCRIPTION_LENGTH = 1024;
+
+const SKILL_FILE = "SKILL.md";
+const SKIPPED_DIRS = new Set([".git", "node_modules"]);
+
+/**
+ * Return the YAML text between the leading `---` delimiters, or null when the
+ * document has no frontmatter block. Mirrors PI's extraction step, including
+ * newline normalisation and BOM stripping.
+ */
+function extractYaml(content) {
+  const normalized = content.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  if (!normalized.startsWith("---")) return null;
+
+  const endIndex = normalized.indexOf("\n---", 3);
+  if (endIndex === -1) return null;
+
+  return normalized.slice(4, endIndex);
+}
+
+/** True when `value` is a string with at least one non-whitespace character. */
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+
+/**
+ * Validate one SKILL.md document.
+ *
+ * @param {string} content - Raw SKILL.md contents.
+ * @returns {string[]} Human-readable problems; empty when the frontmatter is valid.
+ */
+export function validateSkillFrontmatter(content) {
+  const yamlText = extractYaml(content);
+  if (yamlText === null) {
+    return ["frontmatter block is missing (expected '---' delimiters)"];
+  }
+
+  let frontmatter;
+  try {
+    frontmatter = parse(yamlText);
+  } catch (error) {
+    const message = error instanceof Error ? error.message.split("\n")[0] : "unknown parse error";
+    return [`frontmatter is not valid YAML: ${message}`];
+  }
+
+  if (frontmatter === null || typeof frontmatter !== "object" || Array.isArray(frontmatter)) {
+    return ["frontmatter is not a YAML mapping of name/description fields"];
+  }
+
+  const errors = [];
+  if (!isNonEmptyString(frontmatter.name)) {
+    errors.push("frontmatter is missing a non-empty name");
+  }
+  if (!isNonEmptyString(frontmatter.description)) {
+    errors.push("frontmatter is missing a non-empty description");
+  } else if (frontmatter.description.length > MAX_DESCRIPTION_LENGTH) {
+    errors.push(
+      `description exceeds ${MAX_DESCRIPTION_LENGTH} characters (${frontmatter.description.length})`,
+    );
+  }
+
+  return errors;
+}
+
+/** Recursively collect every SKILL.md below `dir`, skipping vendored trees. */
+async function findSkillFiles(dir) {
+  const found = [];
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return found;
+  }
+
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIPPED_DIRS.has(entry.name)) continue;
+      found.push(...(await findSkillFiles(full)));
+    } else if (entry.isFile() && entry.name === SKILL_FILE) {
+      found.push(full);
+    }
+  }
+
+  return found;
+}
+
+/**
+ * Validate every SKILL.md under `root`.
+ *
+ * @param {{ root: string }} options
+ * @returns {Promise<{ checked: number, failures: Array<{ file: string, errors: string[] }> }>}
+ *   `checked` counts the SKILL.md files examined; `failures` holds one entry per
+ *   invalid file, with `file` relative to `root`.
+ */
+export async function checkSkills({ root }) {
+  const files = await findSkillFiles(root);
+  const failures = [];
+
+  for (const file of files) {
+    const content = await readFile(file, "utf-8");
+    const errors = validateSkillFrontmatter(content);
+    if (errors.length > 0) {
+      failures.push({ file: relative(root, file), errors });
+    }
+  }
+
+  return { checked: files.length, failures };
+}

package/skills/workflow/ralph/REFERENCE.md

@@ -74,13 +74,37 @@ When the `document` chore for a parent task completes:
 3. Report the PR URL in chat as soon as it is created.
 4. Find the child HITL task bead for this parent with label `lifecycle:feature-pr` (created by `create-task`).
 5. Update that HITL bead with the PR URL/status (comment or note) so the reviewer has the link.
-6. Do not schedule new parent features while this HITL PR gate bead remains open.
-7. Once the PR is merged, a human closes the HITL PR gate bead. After that, close the parent feature bead:
+6. Do not schedule new parent features while this gate is **unblocked** — an unblocked gate is a feature genuinely awaiting a human merge (see _Gate predicate_ below).
+7. Once the PR is merged, a human closes the HITL PR gate bead, which unblocks the scheduling brake. After that, close the parent feature bead:
    ```bash
    bd close <parent-id>
    ```
    Only then continue with next parent features.
 
+### Gate predicate — parked vs pending
+
+Ralph's only scheduling brake is a gate that is **unblocked**. `create-chores` pre-creates a `lifecycle:feature-pr` gate for *every* planned feature, blocked behind that feature's own `document` chore; such a gate is **parked** — the feature has not reached its PR stage — and must never stop dispatch. Only when the `document` chore closes does the gate unblock, and that is the state in which a human must merge.
+
+Resolve the question with one command instead of ad-hoc `bd` queries:
+
+```bash
+node skills/workflow/ralph/scripts/pending-gates.mjs
+```
+
+| Field | Meaning | Effect on ralph |
+| --- | --- | --- |
+| `pendingHumanAction` | Unblocked `lifecycle:feature-pr` gates (all blockers closed) plus epics tagged `awaiting-epic-pr-merge`, each as `{ id, title, kind }` | Non-empty → do **not** schedule new parent features; the same list is the **Pending Human Action** table |
+| `parked` | Open gates still blocked behind their own pipeline | Informational only — never stops dispatch, never appears in the table |
+
+Gate queries match the HITL axis on either `execution:hitl` (current) or `implementation-type:hitl` (legacy), so gates created on either side of the two-axis migration are counted.
+
+**Invariant — what may block a gate.** `parked` means "blocked by its own pipeline". A gate blocked by its parent **feature** bead is not parked in any harness: that bead stays open until after the merge, so the gate never reaches `bd ready`, never appears in `pendingHumanAction`, and a human merge is silently never requested. Keep the two shapes apart:
+
+- A `create-chores` gate unblocks exactly once, when its `document` chore closes. Until then it is parked and must not stop dispatch.
+- A gate must never carry a `blocks` dependency onto its own feature bead (the native-Claude shape: `bd create ... --labels ...lifecycle:feature-pr` then dep it to `<id>`). Remove it with `bd dep rm <gate> <id>` if present, so the gate is unblocked while its PR awaits merge.
+
+So the predicate is sensitive to *what* blocks a gate, not only whether something does. `agents-native/ralph.md` (the Claude harness) keeps the open-gate form for this reason: its gates stay blocked by design, and its `document` chores never close; F10 (agnt-ctx-s5xd.10) unifies the two predicates.
+
 ---
 
 ## Fix Loop
@@ -137,7 +161,7 @@ Run whenever completion handling is triggered (an agent completion):
 
 ## HITL Pause
 
-Proceed here when no chore beads are in-flight, no `stage:*` chore beads are ready, and HITL gate beads are pending (open `lifecycle:feature-pr` beads or epics tagged `awaiting-epic-pr-merge`). Ralph stops rather than burning requests on idle polls.
+Proceed here when no chore beads are in-flight, no `stage:*` chore beads are ready, and `pending-gates.mjs` reports a non-empty `pendingHumanAction` — an **unblocked** `lifecycle:feature-pr` gate or an epic tagged `awaiting-epic-pr-merge` (see _Gate predicate_). Gates still parked behind their own pipeline do not count. Ralph stops rather than burning requests on idle polls.
 
 1. Regenerate `.agent-cortex/ralph/progress.md` one final time — do not delete it.
 2. For each **multi-feature** epic whose feature beads are all closed but not yet tagged `awaiting-epic-pr-merge`, open/update an epic PR to main (skip single-feature epics — their feature branch PRs already target `main`):
@@ -149,12 +173,11 @@ Proceed here when no chore beads are in-flight, no `stage:*` chore beads are rea
    ```bash
    bd dolt push
    ```
-4. Collect pending HITL gate beads and their PR URLs:
+4. Collect the table rows from `pendingHumanAction`:
    ```bash
-   bd list -l lifecycle:feature-pr -l implementation-type:hitl
-   bd list -l awaiting-epic-pr-merge
+   node skills/workflow/ralph/scripts/pending-gates.mjs
    ```
-   For each bead, run `bd show <id>` to retrieve the PR URL from bead notes.
+   For each entry, run `bd show <id>` to retrieve the PR URL from bead notes. `kind: "feature-pr"` rows read "review and merge the feature PR"; `kind: "epic-pr"` rows read "review and merge the epic PR into main".
 5. Output the **Pending Human Action** summary:
    ```
    ⏸️  Ralph is paused — human action required before work can continue.
@@ -221,5 +244,5 @@ All task state is derived from beads; `state.json` holds only runtime bookkeepin
 | What stage is a bead in? | Read the `stage:*` label from `bd show <id>` |
 | Which agent-ID maps to which bead? | `inflight` entries in `.agent-cortex/ralph/state.json` |
 | How many fix rounds? | Count chore beads with label `stage:fix` that are children of the parent task. Read `maxFixRounds` from `skills/planning/create-task/pipeline.json`. |
-| Which features are review-gated? | Find open child task beads labelled `lifecycle:feature-pr` and `implementation-type:hitl` |
+| Which features are review-gated? | `pendingHumanAction` entries with `kind: "feature-pr"` from `pending-gates.mjs` — unblocked `lifecycle:feature-pr` gates on either HITL axis. A gate in `parked` is pre-created but not yet actionable |
 | Which epics are review-gated? | `bd list -l awaiting-epic-pr-merge` |

package/skills/workflow/ralph/SKILL.md

@@ -33,9 +33,9 @@ State model: task state lives in beads (ready/in_progress via `bd`); the only lo
 6. Run `bd ready` and classify each available bead:
    - **Chore with a `stage:*` label**: pipeline stage bead — eligible for dispatch.
    - **Task or other type without an `implementation-type:*` label**: unexpected here — classification happens at planning time via `create-task`. Do not invoke `classify-bead`; treat as needs-refinement and note it for the shutdown summary.
-   - **Task labelled `implementation-type:hitl`**: skip — record the ID for the Pending Human Action summary at shutdown.
+   - **Task labelled `execution:hitl`** (or the legacy `implementation-type:hitl`): skip — record the ID for the Pending Human Action summary at shutdown.
 7. For each ready chore bead (up to 5), dispatch it from its parent's feature worktree (see _Dispatching a chore bead_ in REFERENCE.md — create branches/worktrees first).
-8. Hand over to your harness's completion-detection mechanism: PI keeps a {{TOOL:wait_for_agents}} call outstanding over every in-flight agent ID. If no chore was dispatched and HITL gate beads are pending (`bd list -l lifecycle:feature-pr -l implementation-type:hitl` or `bd list -l awaiting-epic-pr-merge`), go straight to HITL Pause (REFERENCE.md).
+8. Hand over to your harness's completion-detection mechanism: PI keeps a {{TOOL:wait_for_agents}} call outstanding over every in-flight agent ID. If no chore was dispatched and `pending-gates.mjs` reports a non-empty `pendingHumanAction` (an unblocked `lifecycle:feature-pr` gate, or an epic tagged `awaiting-epic-pr-merge`), go straight to HITL Pause (REFERENCE.md).
 9. Regenerate `.agent-cortex/ralph/progress.md`:
    ```bash
    # workspace must be the absolute path you cd'd into — never . or $(pwd)
@@ -62,8 +62,8 @@ On each completion notification (a background agent finished):
    | `review` | `REVIEW_OUTCOME: CHANGES_REQUESTED` | Run the fix loop (REFERENCE.md) |
    | `document` | — | Open/update the feature PR now (`feature/<parent-id>` → its base branch), report the URL, and update the child HITL gate bead (`lifecycle:feature-pr`). Wait for a human to close that bead after merge, then `bd close <parent-id>` |
 
-5. Run `bd ready` and dispatch new ready `stage:*` chore beads while the in-flight count (`bd list --status=in_progress --type=chore`) is under 5. Do not schedule new parent features while any `lifecycle:feature-pr` HITL gate bead is open.
-6. If no chores are in-flight and `bd ready` returns no `stage:*` chores, proceed to HITL Pause (REFERENCE.md) when HITL gate beads are pending, otherwise to Shutdown (REFERENCE.md).
+5. Run `bd ready` and dispatch new ready `stage:*` chore beads while the in-flight count (`bd list --status=in_progress --type=chore`) is under 5. Do not schedule new parent features while `pending-gates.mjs` reports a non-empty `pendingHumanAction` — that is, while a `lifecycle:feature-pr` gate is **unblocked**. Gates still blocked behind their own pipeline (pre-created for a feature that has not reached its PR stage) are parked and never stop dispatch.
+6. If no chores are in-flight and `bd ready` returns no `stage:*` chores, proceed to HITL Pause (REFERENCE.md) when `pendingHumanAction` is non-empty, otherwise to Shutdown (REFERENCE.md).
 7. Regenerate `.agent-cortex/ralph/progress.md`.
 
 ### 3. Branching and review model
@@ -75,7 +75,7 @@ On each completion notification (a background agent finished):
 
 ### 4. HITL pause and shutdown
 
-- **HITL Pause** — when no chores are in-flight, none ready, and HITL gate beads are pending: regenerate `progress.md`, open/update epic PRs to `main` for multi-feature epics and tag each epic `awaiting-epic-pr-merge` (single-feature epics need none — their feature PRs already target `main`), run `bd dolt push`, output the Pending Human Action table, then stop completely until re-prompted.
+- **HITL Pause** — when no chores are in-flight, none ready, and `pending-gates.mjs` reports a non-empty `pendingHumanAction`: regenerate `progress.md`, open/update epic PRs to `main` for multi-feature epics and tag each epic `awaiting-epic-pr-merge` (single-feature epics need none — their feature PRs already target `main`), run `bd dolt push`, output the Pending Human Action table, then stop completely until re-prompted.
 - **Shutdown** — when all work is complete: regenerate `progress.md`, open/update epic PRs to `main` for multi-feature epics and tag them (single-feature epics need none), run `bd dolt push`, then output the Pending Human Action / Needs Refinement / cap-blocked / Pending Epic Review summaries that apply, or "All beads complete."
 
 ## Red Flags
@@ -109,7 +109,7 @@ On each completion notification (a background agent finished):
 ## Cross-skill references
 
 - The `run-pipeline-stage` skill owns the stage-runner prompt, per-stage playbooks, the `---REPORT---` format, and fix-loop feedback beads — read it before dispatching any stage.
-- The `create-task` skill owns `pipeline.json` and creates the `lifecycle:feature-pr` HITL gate beads.
+- The `create-task` skill owns `pipeline.json` and creates the `lifecycle:feature-pr` HITL gate beads. `skills/workflow/ralph/scripts/pending-gates.mjs` owns the gate predicate — parked vs pending — and is the only place the gate queries live.
 - Do not invoke `classify-bead` from this loop — classification was already applied at planning time.
 
 ## Verification checklist

package/skills/workflow/ralph/scripts/pending-gates.mjs

@@ -0,0 +1,134 @@
+// Resolves which beads are waiting on a human, and which are merely parked
+// behind their own pipeline.
+//
+// Ralph schedules new parent features only when nothing is pending human action.
+// The distinction that matters is *unblocked*, not *open*: `create-chores`
+// pre-creates a `lifecycle:feature-pr` gate for every planned feature, blocked
+// behind that feature's own document chore. Such a gate is parked — the feature
+// has not reached its PR stage — and must never stop dispatch. Only once the
+// document chore closes does the gate unblock, and that is the state in which a
+// feature genuinely awaits a human merge.
+//
+// Zero dependencies: run with `node pending-gates.mjs`.
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { pathToFileURL } from 'node:url';
+
+/** The structural label every feature PR gate carries, whatever its axis. */
+export const FEATURE_GATE_LABEL = 'lifecycle:feature-pr';
+
+/** Epics whose PR into `main` awaits a human merge. */
+export const EPIC_GATE_LABEL = 'awaiting-epic-pr-merge';
+
+// Two-axis migration: gates created before the `execution:afk/hitl` migration
+// carry `implementation-type:hitl`, gates created after carry `execution:hitl`.
+// Both mean "a human must act", so the query matches either.
+export const HITL_GATE_LABELS = ['execution:hitl', 'implementation-type:hitl'];
+
+/** @typedef {{ id: string, title?: string }} Bead */
+/** @typedef {{ id: string, title: string, kind: 'feature-pr' | 'epic-pr' }} PendingAction */
+
+/**
+ * @typedef {object} GateState
+ * @property {PendingAction[]} pendingHumanAction  Beads a human must act on now — non-empty means "do not schedule new parent features".
+ * @property {Array<{ id: string, title: string }>} parked  Open gates still blocked behind their own pipeline; informational only.
+ */
+
+/**
+ * Split open gates into those awaiting a human now and those still parked.
+ *
+ * @param {object} input
+ * @param {Bead[]} input.readyGates            Open gates with no active blockers.
+ * @param {Bead[]} input.openGates             Every open gate, blocked or not.
+ * @param {Bead[]} input.epicsAwaitingMerge    Epics tagged `awaiting-epic-pr-merge`.
+ * @returns {GateState}
+ */
+export function resolveGateState({ readyGates, openGates, epicsAwaitingMerge }) {
+  const actionable = new Set(readyGates.map((bead) => bead.id));
+
+  const pendingHumanAction = [
+    ...readyGates.map((bead) => pendingAction(bead, 'feature-pr')),
+    ...epicsAwaitingMerge.map((bead) => pendingAction(bead, 'epic-pr')),
+  ];
+
+  const parked = openGates
+    .filter((bead) => !actionable.has(bead.id))
+    .map((bead) => ({ id: bead.id, title: bead.title ?? '' }));
+
+  return { pendingHumanAction, parked };
+}
+
+/**
+ * @param {Bead} bead
+ * @param {'feature-pr' | 'epic-pr'} kind
+ * @returns {PendingAction}
+ */
+function pendingAction(bead, kind) {
+  return { id: bead.id, title: bead.title ?? '', kind };
+}
+
+// BD_PATH env override lets machines where bd is not on PATH pin a location.
+const BD_PATH = process.env.BD_PATH || 'bd';
+const execFileAsync = promisify(execFile);
+
+/** @type {(args: string[]) => Promise<string>} */
+async function defaultExec(args) {
+  const { stdout } = await execFileAsync(BD_PATH, args, { encoding: 'utf-8' });
+  return stdout;
+}
+
+/**
+ * Query bd for the current gate state.
+ *
+ * @param {object} [options]
+ * @param {(args: string[]) => Promise<string>} [options.exec]  bd runner; injectable for tests.
+ * @returns {Promise<GateState>}
+ */
+export async function fetchGateState({ exec = defaultExec } = {}) {
+  const gateFilter = ['-l', FEATURE_GATE_LABEL, '--label-any', HITL_GATE_LABELS.join(',')];
+
+  // `bd ready` is blocker-aware: it returns only gates whose document chore has
+  // closed, i.e. the ones genuinely awaiting a human merge.
+  const readyGates = JSON.parse(await exec(['ready', '--json', ...gateFilter]));
+  const openGates = JSON.parse(await exec(['list', '--json', '--limit', '0', ...gateFilter]));
+  const epicsAwaitingMerge = JSON.parse(await exec(['list', '--json', '--limit', '0', '-l', EPIC_GATE_LABEL]));
+
+  return resolveGateState({ readyGates, openGates, epicsAwaitingMerge });
+}
+
+// ─── CLI ──────────────────────────────────────────────────────────────────────
+
+const USAGE = 'Usage: node pending-gates.mjs\n\nPrints { pendingHumanAction, parked } as JSON.\n';
+
+class UsageError extends Error {}
+
+/**
+ * @param {object} options
+ * @param {string[]} options.argv                              CLI arguments (without node/script).
+ * @param {(args: string[]) => Promise<string>} [options.exec]  bd runner; injectable for tests.
+ * @param {(chunk: string) => void} [options.write]             stdout sink; injectable for tests.
+ * @returns {Promise<number>} process exit code.
+ */
+export async function runCli({ argv, exec = defaultExec, write = (chunk) => process.stdout.write(chunk) }) {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    write(USAGE);
+    return 0;
+  }
+  if (argv.length > 0) throw new UsageError(`unexpected argument: ${argv[0]}`);
+
+  write(`${JSON.stringify(await fetchGateState({ exec }), null, 2)}\n`);
+  return 0;
+}
+
+// Only run the CLI when invoked directly, so tests can import the pure resolver.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runCli({ argv: process.argv.slice(2) })
+    .then((code) => {
+      process.exitCode = code;
+    })
+    .catch((error) => {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+      process.exitCode = error instanceof UsageError ? 2 : 1;
+    });
+}

package/test/installer.test.mjs

@@ -661,4 +661,146 @@ describe("install claude — settings.json", () => {
       await fx.cleanup();
     }
   });
-});
+});
+// ─── installClaude — managed CLAUDE.md section ────────────────────────────────
+
+const MANAGED_BEGIN = "<!-- BEGIN agent-cortex:output-style -->";
+const MANAGED_END = "<!-- END agent-cortex:output-style -->";
+const OUTPUT_SOURCE = "## Output style (agent-cortex)\n\nRules for replies.\n";
+
+/** Minimal package root carrying the output-style source, enough for
+ * installClaude to materialise the managed CLAUDE.md section. */
+async function makeInstructionsFixture({ source = OUTPUT_SOURCE, memory } = {}) {
+  const root = await makeTmp();
+  await writeFile(
+    join(root, "package.json"),
+    JSON.stringify({ name: "agent-cortex", version: "1.2.3", license: "MIT" }),
+  );
+  await writeFile(
+    join(root, "token-map.json"),
+    JSON.stringify({ tools: {}, paths: { plugin_root: { claude: "PLUGIN_ROOT" } } }),
+  );
+  await mkdir(join(root, "agents"));
+  await mkdir(join(root, "skills"));
+  if (source !== null) {
+    await mkdir(join(root, "extensions", "output-style"), { recursive: true });
+    await writeFile(join(root, "extensions", "output-style", "output-style.md"), source);
+  }
+  const output = join(root, "out");
+  const instructionsPath = join(root, "claude-home", "CLAUDE.md");
+  if (memory !== undefined) {
+    await mkdir(dirname(instructionsPath), { recursive: true });
+    await writeFile(instructionsPath, memory);
+  }
+  return { root, output, instructionsPath, cleanup: () => rm(root, { recursive: true, force: true }) };
+}
+
+const MANAGED_SECTION = `${MANAGED_BEGIN}\n${OUTPUT_SOURCE.trimEnd()}\n${MANAGED_END}\n`;
+
+describe("installClaude — managed CLAUDE.md section", () => {
+  it("creates CLAUDE.md with the managed section when the file does not exist", async () => {
+    const fx = await makeInstructionsFixture();
+    try {
+      const result = await installClaude({ root: fx.root, output: fx.output, instructionsPath: fx.instructionsPath });
+
+      assert.equal(result.instructions.action, "written");
+      assert.equal(await readFile(fx.instructionsPath, "utf-8"), MANAGED_SECTION);
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("appends the section to existing memory and keeps the user's text", async () => {
+    const fx = await makeInstructionsFixture({ memory: "# My memory\n\nAlways run the tests.\n" });
+    try {
+      await installClaude({ root: fx.root, output: fx.output, instructionsPath: fx.instructionsPath });
+
+      const written = await readFile(fx.instructionsPath, "utf-8");
+      assert.ok(written.startsWith("# My memory\n\nAlways run the tests.\n\n"), "personal text kept at the top");
+      assert.ok(written.endsWith(MANAGED_SECTION), "managed section appended");
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("replaces only the managed section, keeping memory text on both sides", async () => {
+    const memory = `# Top\n\n${MANAGED_BEGIN}\n## Output style (agent-cortex)\n\nStale rules.\n${MANAGED_END}\n\n# Bottom\n\nKeep me.\n`;
+    const fx = await makeInstructionsFixture({ memory });
+    try {
+      await installClaude({ root: fx.root, output: fx.output, instructionsPath: fx.instructionsPath });
+
+      const written = await readFile(fx.instructionsPath, "utf-8");
+      assert.equal(written, `# Top\n\n${MANAGED_SECTION}\n# Bottom\n\nKeep me.\n`);
+      assert.equal(written.includes("Stale rules."), false, "stale block replaced");
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("re-running is idempotent — the second install reports unchanged", async () => {
+    const fx = await makeInstructionsFixture({ memory: "# My memory\n" });
+    try {
+      await installClaude({ root: fx.root, output: fx.output, instructionsPath: fx.instructionsPath });
+      const first = await readFile(fx.instructionsPath, "utf-8");
+
+      const second = await installClaude({ root: fx.root, output: fx.output, instructionsPath: fx.instructionsPath });
+      assert.equal(second.instructions.action, "unchanged");
+      assert.equal(await readFile(fx.instructionsPath, "utf-8"), first);
+      assert.equal(first.split(MANAGED_BEGIN).length - 1, 1, "exactly one managed section");
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("leaves a file with an unterminated section unchanged and warns", async () => {
+    const memory = `# My memory\n\n${MANAGED_BEGIN}\nHand-edited, no end marker.\n`;
+    const fx = await makeInstructionsFixture({ memory });
+    try {
+      const warnings = [];
+      const result = await installClaude({
+        root: fx.root,
+        output: fx.output,
+        instructionsPath: fx.instructionsPath,
+        warn: (m) => warnings.push(m),
+      });
+
+      assert.equal(result.instructions.action, "skipped-unmanaged");
+      assert.equal(await readFile(fx.instructionsPath, "utf-8"), memory, "file untouched");
+      assert.ok(warnings.some((w) => w.includes("unterminated")), "unmatched markers are warned about");
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("dry-run plans the CLAUDE.md write without touching the filesystem", async () => {
+    const fx = await makeInstructionsFixture();
+    try {
+      const result = await installClaude({
+        root: fx.root,
+        output: fx.output,
+        instructionsPath: fx.instructionsPath,
+        dryRun: true,
+      });
+
+      assert.equal(result.instructions.action, "would-write");
+      assert.equal(await pathExists(fx.instructionsPath), false, "nothing written in dry-run");
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("ships the real output-style source the pi extension reads", async () => {
+    const real = await readFile(join(ROOT, "extensions", "output-style", "output-style.md"), "utf-8");
+    assert.ok(real.startsWith("## Output style (agent-cortex)"), "canonical heading");
+
+    const fx = await makeInstructionsFixture({ source: real });
+    try {
+      await installClaude({ root: fx.root, output: fx.output, instructionsPath: fx.instructionsPath });
+      const written = await readFile(fx.instructionsPath, "utf-8");
+      assert.ok(written.includes("### Write Simplified Technical English (ASD-STE100)"));
+      assert.ok(written.includes("### Restate the context, never assume it"));
+    } finally {
+      await fx.cleanup();
+    }
+  });
+});