@jaybeeuu/agent-cortex 2.1.0 → 2.2.0

package/agents/ralph-plan/agent.md

@@ -51,23 +51,35 @@ Update the top-level bead's `design` field with a high-level implementation plan
 ### 6. Decompose into tasks
 For large workstreams (multiple distinct areas) invoke the **prd-to-tasks** skill. For a single self-contained task invoke **create-task**. Pass the full `bd prime` output and any relevant design context from the `design` field to each skill.
 
-For each new feature bead and each new task bead, create a HITL planning gate before handoff. The feature/task bead depends on this gate and stays blocked until the user explicitly confirms planning is sufficient **for that specific feature/task**.
+**Planning gate.** Each feature carries exactly one HITL planning bead — the design gate that keeps the feature's implementation children out of `bd ready` until a human confirms planning is sufficient. It is the bead `create-task` builds on its feature path: that skill's steps 5–6 are the authority for this shape, so when you delegate the feature to `create-task` the gate already exists and you must not create a second one.
 
-Every planning gate description must be cold-start-ready so another person can pick it up without prior chat context. Include all of: (1) what is being built and why, (2) decisions already made, (3) open questions/risks, and (4) references (bead IDs, files, or docs) used during planning.
+Ownership is `--parent`; ordering is `bd dep add`. The planning bead is **owned by the feature** and **blocks every implementation child** of that feature. The feature never depends on its own gate — a container that waits on its own child is neither owner nor ordering.
+
+Every planning bead description must be cold-start-ready so another person can pick it up without prior chat context. Include all of: (1) what is being built and why, (2) decisions already made, (3) open questions/risks, and (4) references (bead IDs, files, or docs) used during planning.
+
+Both routes above create the gate for you, so this block is the shape to build by hand only when the feature already exists and `bd children <feature-id>` lists no `Plan:` child. Never run it beside a gate `create-task` already made: bead creation is not idempotent, so a second run leaves two design gates blocking the same children. The guard is check-then-act and therefore not atomic — two planners on one feature at the same instant could both pass it and create a gate each; that is acceptable because the only automated creation path goes through `create-task`, this agent runs as a single interactive HITL session, and a stray second planning bead carries no `lifecycle:feature-pr`, so ralph never pauses on it.
 
 ```bash
-gate_id=$(bd create "Plan: <feature title>" --type task --description "<planning context, decisions, open questions, and references>
+# Design gate: human-owned, owned by the feature, blocking every implementation child.
+planning_id=$(bd create "Plan: <feature title>" --type task --priority <priority> \
+  -l execution:hitl --parent <feature-id> --no-inherit-labels \
+  --description "<planning context, decisions, open questions, and references>
 
 ## Acceptance Criteria
 
-- [ ] User confirms planning is sufficient for this feature/task." --validate)
-bd tag <planning-gate-id> implementation-type:hitl
-bd dep add <feature-or-task-id> <planning-gate-id>   # feature/task depends on planning gate (gate blocks implementation)
+- [ ] The user confirms planning is sufficient for this feature." --validate --silent)
+
+# Readiness gate: every implementation child waits on the design gate.
+bd dep add <impl-task-id> <planning-bead-id>
 ```
 
-Do not close planning gates in bulk. Only close a gate after the user explicitly confirms that exact feature/task is ready to implement; leave all unconfirmed gates open and blocking.
+`--no-inherit-labels` is not optional: `bd` copies a parent's labels at create time, so without it a gate under an `execution:afk` feature picks up `execution:afk` beside its own `execution:hitl` and stops routing as human work.
+
+A planning bead is **not** a PR gate and carries no `lifecycle:` label. `create-chores.mjs` owns the `lifecycle:feature-pr` gate — owned by the implementation task, blocked by its `document` chore (the `create-task` skill's `REFERENCE.md` → PR gate bead); creating one here would put a second, differently-wired gate on the same bead. A standalone task bead needs no planning bead: `create-task` classifies it, and its human checkpoint is that PR gate.
+
+Do not close planning gates in bulk. Only close a gate after the user explicitly confirms that exact feature is ready to implement; leave all unconfirmed gates open and blocking.
 
-Before handing off, ensure every bead created in this step carries an `implementation-type` label — check `bd label list <id>` yourself. Do not spawn `classify-bead` here: planning gates were tagged inline above and `create-task` classifies its beads internally. Only invoke it for a bead that genuinely lacks both the label and a `## Type` field. Then run `bd lint <id>` for every bead created in this step and fix any missing sections before handoff.
+Before handing off, ensure every bead created in this step carries an `execution:` label — check `bd label list <id>` yourself. Do not spawn `classify-bead` here: planning gates are labelled inline above and `create-task` classifies its beads internally. Only invoke it for a bead that genuinely lacks both the label and a `## Type` field. Then run `bd lint <id>` for every bead created in this step and fix any missing sections before handoff.
 
 Tag every bead created in this step with `workflow:ralph`:
 
@@ -95,12 +107,12 @@ bead against the full backlog — a P3 feature that blocks others may need a hig
 explicit priority than a standalone P4 feature.
 
 ### 7. Agree with the user
-Present the bead list (IDs, titles, one-line rationale each) plus planning gate status for each item using `✅` (confirmed/closed) or `⏳` (awaiting confirmation/open). Ask the user to confirm or request changes before finishing.
+Present the bead list (IDs, titles, one-line rationale each) plus the planning-gate status of each feature using `✅` (confirmed/closed) or `⏳` (awaiting confirmation/open). Ask the user to confirm or request changes before finishing.
 
-If any planning gates remain open, include an explicit warning that those features/tasks are still blocked and cannot be handed off to ralph yet. Iterate until approved.
+If any planning gate remains open, include an explicit warning that its implementation children are still blocked by it and cannot be handed off to ralph yet. Iterate until approved.
 
 ### 8. Hand off to ralph
-Once approved, report: "Plan complete — `bd ready` will show the first tasks for ralph."
+Once approved, report: "Plan complete — `bd ready -l execution:afk` will show the first tasks for ralph."
 
 ## Exploration sub-agent instructions
 

package/bin/agent-cortex.mjs

@@ -2,8 +2,13 @@
 
 import { parseArgs, buildHelpText, validateHarness } from "../lib/cli.mjs";
 import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFile } from "node:fs/promises";
 import { installPi, registerPi, sweepLegacyPiUserDirs } from "./installers/pi.mjs";
 
+/** @typedef {import("./installers/pi.mjs").InstallPiResult} InstallPiResult */
+/** @typedef {import("./installers/pi.mjs").RegisterPiResult} RegisterPiResult */
+
 const argv = process.argv.slice(2);
 const parsed = parseArgs(argv);
 
@@ -12,6 +17,41 @@ if (parsed.command === "help") {
   process.exit(0);
 }
 
+/**
+ * Read the version of the package this CLI ships in: `bin/` sits one level below
+ * the package root, in the repo checkout and in the published tarball alike.
+ * Resolved from this file's own location, never from the cwd or node_modules
+ * resolution, so an installed CLI reports the version it was installed at.
+ * Throws when that manifest is missing, unreadable, malformed, or has no version
+ * string, so a broken install never prints a bogus version with a success exit.
+ * @returns {Promise<string>}
+ */
+async function readPackageVersion() {
+  const manifestPath = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+  /** @type {unknown} */
+  let manifest;
+  try {
+    manifest = JSON.parse(await readFile(manifestPath, "utf-8"));
+  } catch (err) {
+    throw new Error(`Cannot read the package version from ${manifestPath}: ${/** @type {Error} */ (err).message}`);
+  }
+  const version = /** @type {{ version?: unknown }} */ (manifest).version;
+  if (typeof version !== "string" || version === "") {
+    throw new Error(`Cannot read the package version from ${manifestPath}: the manifest has no "version" string.`);
+  }
+  return version;
+}
+
+if (parsed.command === "version") {
+  try {
+    process.stdout.write(`${await readPackageVersion()}\n`);
+  } catch (err) {
+    process.stderr.write(`${/** @type {Error} */ (err).message}\n`);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
 if (parsed.command === "unknown") {
   process.stderr.write(`Unknown command: ${parsed.name}\nRun "agent-cortex --help" for usage.\n`);
   process.exit(1);
@@ -66,7 +106,7 @@ if (parsed.command === "install") {
         process.stdout.write(`  → register it with pi: pi install ${result.output}\n`);
       }
     } catch (err) {
-      process.stderr.write(`Install failed: ${err.message}\n`);
+      process.stderr.write(`Install failed: ${/** @type {Error} */ (err).message}\n`);
       process.exit(1);
     }
     process.exit(0);
@@ -99,8 +139,11 @@ if (parsed.command === "install") {
       // keeps generating only (documented in --help).
       if (parsed.output === undefined) {
         await registerClaude({
-          root: result.marketplaceRoot,
-          manifest: result.marketplaceManifest,
+          // A default install always materialises the marketplace manifest; the
+          // generate-only form (--output) is the only path where it is null, and
+          // this branch is not that path.
+          root: /** @type {string} */ (result.marketplaceRoot),
+          manifest: /** @type {object} */ (result.marketplaceManifest),
           pluginVersion: result.pluginVersion,
           dryRun: parsed.dryRun ?? false,
           requireRegister: parsed.requireRegister ?? false,
@@ -108,12 +151,13 @@ if (parsed.command === "install") {
       }
       process.exit(0);
     } catch (err) {
-      process.stderr.write(`Install failed: ${err.message}\n`);
+      process.stderr.write(`Install failed: ${/** @type {Error} */ (err).message}\n`);
       process.exit(1);
     }
   }
 }
 
+/** @param {{ removed: string[] }} result */
 function printPiSweep({ removed }) {
   if (removed.length === 0) return;
   process.stdout.write(
@@ -124,6 +168,24 @@ function printPiSweep({ removed }) {
   }
 }
 
+if (parsed.command === "migrate") {
+  if (parsed.optionError) {
+    process.stderr.write(`${parsed.optionError}\n`);
+    process.exit(1);
+  }
+
+  // Loaded lazily: the migration registry is only needed on this path.
+  const { runMigrate } = await import("../scripts/lib/migrate.mjs");
+  try {
+    await runMigrate({ apply: parsed.apply ?? false, dir: parsed.dir });
+  } catch (err) {
+    process.stderr.write(`Migration failed: ${/** @type {Error} */ (err).message}\n`);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+/** @param {InstallPiResult} result */
 function printPiInstall(result) {
   process.stdout.write(`Installing agent-cortex for "pi" harness…\n`);
   process.stdout.write(`  ✓ Staged pi package → ${result.output}\n`);