@jaybeeuu/agent-cortex 1.43.0 → 2.1.0

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
@@ -116,7 +140,7 @@ When a verify or review stage fails:
 
 ## Log Polling
 
-Run whenever polling is triggered (timer or agent completion):
+Run whenever completion handling is triggered (an agent completion):
 
 1. **Query in-flight beads**: `bd list --status=in_progress --type=chore`. Extract each bead's ID and title.
 2. For each in-flight bead, read new lines from its **parent's** log file — logs are keyed by **parent** bead ID, so all stages of a feature share one file. Track the next unread line number per parent in memory, starting at 1:
@@ -137,7 +161,7 @@ Run whenever polling is triggered (timer or 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.
@@ -167,7 +190,7 @@ Proceed here when no chore beads are in-flight, no `stage:*` chore beads are rea
 
    When you've completed the above, prompt me to continue.
    ```
-6. **Stop completely.** Do not restart the poll timer. Do not continue the event loop. Wait for the user to re-prompt before doing any further work.
+6. **Stop completely.** Do not continue the event loop. Wait for the user to re-prompt before doing any further work.
 
 ---
 
@@ -209,7 +232,7 @@ When `bd list --status=in_progress --type=chore` returns no results AND `bd read
 | File | Purpose |
 |------|---------|
 | `.agent-cortex/ralph/progress.md` | Human-readable snapshot. Regenerate: `workspace="/abs/path"; pnpm --prefix skills/workflow/run-pipeline-stage/scripts exec tsx generate-progress.ts --workspace "$workspace" > "$workspace/.agent-cortex/ralph/progress.md"`. `workspace` must be an **absolute** path — never `.` or `$(pwd)`. **Never hand-edit.** |
-| `.agent-cortex/ralph/state.json` | Runtime bookkeeping only: the poll-timer shellId (Copilot) and the in-flight agent-ID→bead mapping. Shape: `{ "timerShellId": null, "inflight": [ { "choreId": "...", "parentId": "...", "title": "...", "agentId": "...", "logLine": 1 } ] }`. Initialise at startup with `{ "timerShellId": null, "inflight": [] }`. Update after every dispatch and every agent completion. **Never hand-edit.** |
+| `.agent-cortex/ralph/state.json` | Runtime bookkeeping only: the in-flight agent-ID→bead mapping. Shape: `{ "inflight": [ { "choreId": "...", "parentId": "...", "title": "...", "agentId": "...", "logLine": 1 } ] }`. Initialise at startup with `{ "inflight": [] }`. Update after every dispatch and every agent completion. **Never hand-edit.** |
 | `.agent-cortex/ralph/ralph-*.log` | Per-parent log files written by subagents — every stage chore of a feature appends to `.agent-cortex/ralph/ralph-<parent-id>.log` (e.g. `ralph-abc-123.log`). |
 
 All task state is derived from beads; `state.json` holds only runtime bookkeeping:
@@ -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

@@ -7,7 +7,7 @@ description: "Run all pending beads end-to-end with up to 5 concurrent pipeline-
 
 Ralph is a parallel orchestration loop. It advances AFK task beads through pipeline-stage chores (`code` → `verify` → `review` → `document`), dispatching each stage as a background subagent in the feature's worktree, then opens review-gated feature and epic PRs and pauses for human merges. Ralph never writes code itself — it dispatches, tracks, and reports.
 
-State model: task state lives in beads (ready/in_progress via `bd`); the only local file is `.agent-cortex/ralph/state.json`, holding the poll-timer shellId and the agent-ID→bead mapping. Pipeline configuration comes from `skills/planning/create-task/pipeline.json`, and stage execution belongs to the `run-pipeline-stage` skill.
+State model: task state lives in beads (ready/in_progress via `bd`); the only local file is `.agent-cortex/ralph/state.json`, holding the agent-ID→bead mapping. Pipeline configuration comes from `skills/planning/create-task/pipeline.json`, and stage execution belongs to the `run-pipeline-stage` skill.
 
 ## When to use
 
@@ -28,14 +28,14 @@ State model: task state lives in beads (ready/in_progress via `bd`); the only lo
 1. Run `bd prime` and hold the output verbatim in memory.
 2. Ensure `.agent-cortex/` and `.agent-cortex/worktrees/` are in the project's `.gitignore` (append any that are missing).
 3. Create the workspace: `mkdir -p .agent-cortex/ralph`.
-4. Initialize state: write `.agent-cortex/ralph/state.json` with `{ "timerShellId": null, "inflight": [] }`.
+4. Initialize state: write `.agent-cortex/ralph/state.json` with `{ "inflight": [] }`.
 5. Read `skills/planning/create-task/pipeline.json` and hold it in memory — you need its `maxFixRounds` for the fix loop.
 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: Copilot keeps a `sleep 120` poll timer running in the background; 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)
@@ -45,7 +45,7 @@ State model: task state lives in beads (ready/in_progress via `bd`); the only lo
 
 ### 2. Event loop
 
-On each completion notification (background agent finished, or the poll timer fired):
+On each completion notification (a background agent finished):
 
 1. Poll that parent's log for new lines — `tail -n +<nextLine> .agent-cortex/ralph/ralph-<parent-id>.log` (logs are keyed by parent bead ID, so every stage of a feature shares one file) — and post only new key events (stage transitions, test/lint results), never empty updates.
 2. Read the completed agent's output with {{TOOL:read_agent}} and parse its `---REPORT---` block for `BEAD_ID`, `STAGE_COMPLETED`, and the outcome.
@@ -62,8 +62,8 @@ On each completion notification (background agent finished, or the poll timer fi
    | `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 (background agent finished, or the poll timer fi
 
 ### 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
@@ -97,7 +97,7 @@ On each completion notification (background agent finished, or the poll timer fi
 
 ## Philosophy / rationale
 
-- Orchestration state derives from beads so a crash loses nothing but an in-memory ID mapping: `state.json` holds only the poll-timer shellId and the agent-ID→bead mapping, never task state.
+- Orchestration state derives from beads so a crash loses nothing but an in-memory ID mapping: `state.json` holds only the agent-ID→bead mapping, never task state.
 - Classification happens up-front at planning time (`create-task`), so the loop can trust `bd ready` instead of re-interpreting each bead's intent.
 - Human review gates are non-negotiable because agent-authored changes still need a person to merge them.
 
@@ -109,7 +109,7 @@ On each completion notification (background agent finished, or the poll timer fi
 ## 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/cli.test.mjs

@@ -54,11 +54,6 @@ describe("parseArgs", () => {
     assert.deepStrictEqual(result, { command: "help" });
   });
 
-  it("returns { command: 'install', harness: 'copilot' } for install copilot", async () => {
-    const result = parseArgs(["install", "copilot"]);
-    assert.deepStrictEqual(result, { command: "install", harness: "copilot" });
-  });
-
   it("returns { command: 'install', harness: 'claude' } for install claude", async () => {
     const result = parseArgs(["install", "claude"]);
     assert.deepStrictEqual(result, { command: "install", harness: "claude" });
@@ -169,11 +164,17 @@ describe("buildHelpText", () => {
 
 describe("validateHarness", () => {
   it("returns ok for supported harnesses", async () => {
-    for (const h of ["copilot", "claude", "pi"]) {
+    for (const h of ["claude", "pi"]) {
       assert.deepStrictEqual(validateHarness(h), { ok: true });
     }
   });
 
+  it("returns error for copilot, which is no longer a deploy target", async () => {
+    const result = validateHarness("copilot");
+    assert.equal(result.ok, false);
+    assert.ok(result.error.includes("Unknown harness"));
+  });
+
   it("returns error when harness is null", async () => {
     const result = validateHarness(null);
     assert.equal(result.ok, false);
@@ -207,10 +208,10 @@ describe("CLI integration", () => {
     assert.ok(stdout.includes("Usage:"));
   });
 
-  it("exits 0 for install copilot", async () => {
-    const { exitCode, stdout } = await runCli(["install", "copilot"]);
-    assert.equal(exitCode, 0);
-    assert.ok(stdout.includes("copilot"));
+  it("exits 1 for install copilot, which is no longer a deploy target", async () => {
+    const { exitCode, stderr } = await runCli(["install", "copilot"]);
+    assert.equal(exitCode, 1);
+    assert.ok(stderr.includes("Unknown harness"));
   });
 
   it("exits 0 for install claude (into a temp output dir)", async () => {

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();
+    }
+  });
+});

package/test/pending-gates.test.mjs

@@ -0,0 +1,147 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  EPIC_GATE_LABEL,
+  FEATURE_GATE_LABEL,
+  HITL_GATE_LABELS,
+  fetchGateState,
+  resolveGateState,
+  runCli,
+} from '../skills/workflow/ralph/scripts/pending-gates.mjs';
+
+function createBead({ id, title = `${id} title` }) {
+  return { id, title };
+}
+
+/**
+ * Fake `bd` for the query-contract tests: answers the three queries ralph makes
+ * and refuses anything else, so an unexpected query fails loudly.
+ */
+function makeExec({ ready = [], open = [], epics = [] } = {}) {
+  const calls = [];
+
+  const exec = async (args) => {
+    calls.push(args);
+    if (args[0] === 'ready') return JSON.stringify(ready);
+    if (args[0] === 'list' && args.includes(EPIC_GATE_LABEL)) return JSON.stringify(epics);
+    if (args[0] === 'list') return JSON.stringify(open);
+    throw new Error(`unexpected bd call: ${args.join(' ')}`);
+  };
+
+  return { exec, calls };
+}
+
+function capture() {
+  let output = '';
+  return { write: (chunk) => { output += chunk; }, read: () => JSON.parse(output) };
+}
+
+describe('resolveGateState', () => {
+  it('leaves dispatch unblocked while every gate is still parked behind its own pipeline', () => {
+    const state = resolveGateState({
+      readyGates: [],
+      openGates: [
+        createBead({ id: 'proj-1.5' }),
+        createBead({ id: 'proj-2.5' }),
+        createBead({ id: 'proj-3.5' }),
+        createBead({ id: 'proj-4.5' }),
+      ],
+      epicsAwaitingMerge: [],
+    });
+
+    assert.deepEqual(state.pendingHumanAction, []);
+    assert.deepEqual(state.parked, [
+      { id: 'proj-1.5', title: 'proj-1.5 title' },
+      { id: 'proj-2.5', title: 'proj-2.5 title' },
+      { id: 'proj-3.5', title: 'proj-3.5 title' },
+      { id: 'proj-4.5', title: 'proj-4.5 title' },
+    ]);
+  });
+
+  it('reports an unblocked gate as pending human action', () => {
+    const state = resolveGateState({
+      readyGates: [createBead({ id: 'proj-1.5', title: 'PR Review and Merge' })],
+      openGates: [createBead({ id: 'proj-1.5', title: 'PR Review and Merge' })],
+      epicsAwaitingMerge: [],
+    });
+
+    assert.deepEqual(state.pendingHumanAction, [
+      { id: 'proj-1.5', title: 'PR Review and Merge', kind: 'feature-pr' },
+    ]);
+    assert.deepEqual(state.parked, []);
+  });
+
+  it('separates an unblocked gate from gates that are still parked', () => {
+    const state = resolveGateState({
+      readyGates: [createBead({ id: 'proj-1.5' })],
+      openGates: [createBead({ id: 'proj-1.5' }), createBead({ id: 'proj-2.5' })],
+      epicsAwaitingMerge: [],
+    });
+
+    assert.deepEqual(state.pendingHumanAction.map((gate) => gate.id), ['proj-1.5']);
+    assert.deepEqual(state.parked.map((gate) => gate.id), ['proj-2.5']);
+  });
+
+  it('reports an epic awaiting merge as pending human action alongside feature gates', () => {
+    const state = resolveGateState({
+      readyGates: [],
+      openGates: [],
+      epicsAwaitingMerge: [createBead({ id: 'epic-9', title: 'Merge epic into main' })],
+    });
+
+    assert.deepEqual(state.pendingHumanAction, [
+      { id: 'epic-9', title: 'Merge epic into main', kind: 'epic-pr' },
+    ]);
+    assert.deepEqual(state.parked, []);
+  });
+});
+
+describe('fetchGateState', () => {
+  it('asks bd for unblocked gates, all gates, and epics awaiting merge on either HITL axis', async () => {
+    const { exec, calls } = makeExec();
+
+    await fetchGateState({ exec });
+
+    assert.deepEqual(calls, [
+      ['ready', '--json', '-l', FEATURE_GATE_LABEL, '--label-any', HITL_GATE_LABELS.join(',')],
+      ['list', '--json', '--limit', '0', '-l', FEATURE_GATE_LABEL, '--label-any', HITL_GATE_LABELS.join(',')],
+      ['list', '--json', '--limit', '0', '-l', EPIC_GATE_LABEL],
+    ]);
+  });
+
+  it('covers both the current and the legacy HITL label axis', () => {
+    assert.deepEqual(HITL_GATE_LABELS, ['execution:hitl', 'implementation-type:hitl']);
+  });
+
+  it('treats a gate that only the list query returns as parked', async () => {
+    const { exec } = makeExec({ ready: [], open: [createBead({ id: 'proj-1.5' })] });
+
+    const state = await fetchGateState({ exec });
+
+    assert.deepEqual(state.pendingHumanAction, []);
+    assert.deepEqual(state.parked, [{ id: 'proj-1.5', title: 'proj-1.5 title' }]);
+  });
+});
+
+describe('pending-gates CLI', () => {
+  it('prints the resolved gate state as JSON', async () => {
+    const { exec } = makeExec({
+      ready: [createBead({ id: 'proj-1.5' })],
+      open: [createBead({ id: 'proj-1.5' }), createBead({ id: 'proj-2.5' })],
+      epics: [createBead({ id: 'epic-9' })],
+    });
+    const out = capture();
+
+    const code = await runCli({ argv: [], exec, write: out.write });
+
+    assert.equal(code, 0);
+    assert.deepEqual(out.read(), {
+      pendingHumanAction: [
+        { id: 'proj-1.5', title: 'proj-1.5 title', kind: 'feature-pr' },
+        { id: 'epic-9', title: 'epic-9 title', kind: 'epic-pr' },
+      ],
+      parked: [{ id: 'proj-2.5', title: 'proj-2.5 title' }],
+    });
+  });
+});