@jaybeeuu/agent-cortex 1.41.0 → 1.42.0

package/skills/style/style-tests/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: style-tests
-description: Defines this project's test-writing conventions — what to test, assertion strategy, mock discipline, the ban on static-content assertions, and how to construct test data. Use BEFORE writing or editing any test and when reviewing tests — consult it whenever you add or change test files rather than choosing an approach ad hoc. Also for a "test review", "mock strategy", "what should I test", or "is this test well-written".
+description: Defines test-writing conventions — assertion strategy, mock discipline, the content-assertion ban, and test-data construction. Use before writing or reviewing any test, or for a "test review" or "what should I test".
 ---
 
 # Test Style
@@ -22,8 +22,9 @@ description: Defines this project's test-writing conventions — what to test, a
 - **Test behaviour, not implementation.** A test must survive a refactor that does not change observable behaviour. If it fails after such a refactor, the test was wrong.
 - **Mock last, at the edges.** Mock genuine external boundaries only. Never mock within the application/domain boundary; a real collaborator is almost always cheaper than a mock that lies.
 - **Unit tests at module boundaries.** Exercise the surface of a deep module through its public API, never its internals.
-- **Integration and e2e are realistic.** Exercise real service behaviour — AWS via LocalStack or TestContainers. AWS may not be the AUT, but it must still be exercised for certainty. Use a small number of smoke tests to prove the system hangs together.
+- **Integration and e2e exercise real services.** Run the genuine collaborator — Postgres, Redis, a queue, object storage via TestContainers or LocalStack — never a fake that drifts from the real contract. Reserve e2e for a small number of smoke tests proving the system hangs together.
 - **No more tests than needed.** Every test earns its cost by pinpointing exactly where a failure lies. A test that cannot localise a fault adds maintenance weight without signal.
+- **One behaviour per test.** A test should fail for exactly one reason; several unrelated assertions turn a failure into a debugging exercise.
 - **Test code is production code.** Linted, typechecked, properly typed — no `any`, no unsafe casts, no shortcuts in constructing data. Tolerate WETness where it leaves tests more descriptive.
 - **All setup and assertion data is visible inline.** Show exactly and only the values that explain the case; a helper with sensible defaults keeps it terse.
 - **Deterministic and performant.** A failing or flaky test is investigated now. Deferring is acceptable only against a top-priority bead.
@@ -50,14 +51,17 @@ is legitimate. `readFile(config).includes("x")` is not.
 
 ## Test-data construction
 
-- **Build data inline in the test** (or in a helper called from it) so the test body shows the shape of its own input.
+- **Vital data is visible inline.** Any value that is asserted, derives the asserted state, or sets up the scenario under test appears in the test body — never hidden in a helper or a module-scope constant.
+- **Incidental data is hidden.** Everything else takes an obvious default inside a factory, so the test body reads as only the values that matter.
 - **No shared mutable top-level fixture.** If data must be reused, produce it fresh per test via a function — a factory, not a constant. Module-scope constants are acceptable only when genuinely immutable and read-only.
-- **Prefer a small configurable helper** — a factory taking partial overrides with defaults for the rest — over repeated full literals. Build the helper only when reuse justifies it; a single test's data stays a plain inline object.
-- **Name and locate the helper conventionally** so the next agent finds it — colocated with the tests, named for what it builds.
+- **Prefer a small configurable factory.** Optional partial overrides over sensible defaults beat repeated full literals. Build it when reuse justifies it; a single test's data stays a plain inline object.
+- **Name and locate the factory conventionally.** Colocate it with the tests and name it for what it builds: `createNameOfType`.
+
+Worked examples for each rule are in `EXAMPLES.md` under _Test data_.
 
 ## Workflow
 
-1. **Determine the test level.** Can you test this behaviour through the module's public API or interface? Prefer integration-level tests (the trophy's higher coverage). Reserve unit tests for complex functional logic that genuinely benefits from tight isolation, always at the module boundary. Use a small number of e2e smoke tests — with real services via LocalStack/TestContainers — to prove the system hangs together.
+1. **Determine the test level.** A unit proves logic in isolation, integration proves your code against a real collaborator across one seam, and e2e proves the assembled system on a user-visible journey. Can you test this behaviour through the module's public API or interface? Prefer integration-level tests (the trophy's higher coverage). Reserve unit tests for complex functional logic that genuinely benefits from tight isolation, always at the module boundary. Use a small number of e2e smoke tests to prove the parts are wired together — not to re-prove rules already covered below.
 
 2. **Decide what to mock.** Mock as little as possible, and only at genuine external boundaries. A useful mental model: mock what is **above** the module under test in the dependency tree, not below it. At e2e, mock almost nothing.
 
@@ -75,11 +79,18 @@ is legitimate. `readFile(config).includes("x")` is not.
 |---|---|
 | Asserting static file content — an expected config/markdown/terraform string, or a snapshot of static content | Assert the behaviour the file participates in: data inserted into a template, a header compiled correctly, a deployed service ready to serve traffic |
 | Shared mutable top-level fixture reused across tests | Build fresh data per test via a factory; a module-scope constant only when genuinely immutable and read-only |
-| Repeated full literals for the same shape | A small configurable helper taking partial overrides with sensible defaults |
+| Repeated full literals for the same shape | A small configurable factory taking partial overrides with sensible defaults |
+| A test with no assertion, or one that cannot fail (`expect(result).toBeDefined()`) | Assert the observable contract — a specific value the code must produce |
+| Computing the expected value with the implementation's own logic | Hard-code the expected value from a known-good case; the test must not share the implementation's bug |
 | Mocking implementation details or internal module structure | Mock the genuine external boundary and test through the public interface |
+| An "integration" test that mocks the collaborator it is meant to integrate with | Run the real collaborator (TestContainers/LocalStack); a fake drifts from the real contract |
+| E2E re-testing business rules already covered by unit tests | Spend e2e on wiring, migrations, and the journey — keep it to a few smoke tests |
 | Duplicating type or lint coverage | Delete the assertion — the compiler and linter already guarantee it |
-| Skipping flaky or failing tests | Fix or delete; a skipped test is a blind spot |
+| Skipping flaky or failing tests, or leaving `.only`/focus in | Fix or delete; a skipped or focused test is a blind spot |
 | Sharing state via `before`/`after` hooks | Independent tests; hooks only for expensive, non-observable infrastructure |
+| Sleeping or polling for async work to finish | Await the real completion signal; inject a clock for time-dependent logic |
+| An unawaited promise in a test | `await` every async interaction so a rejection fails the test |
+| Asserting log or console output | Assert the returned value or emitted event |
 | `any` or unsafe casts in test code | Proper types — test code is production code |
 
 ## Common Rationalizations
@@ -93,6 +104,7 @@ is legitimate. `readFile(config).includes("x")` is not.
 | "I'll skip this failing test and come back" | A skipped test is a blind spot. The failure is telling you something — listen to it. |
 | "The config file must match exactly this content" | You are cataloguing a file, not proving behaviour. Assert what the code does with it. |
 | "A shared fixture saves setup time" | It couples tests and hides which value drives the case. Build data fresh per test. |
+| "Asserting every field is more thorough" | It makes the test break for reasons the case does not care about. Assert the fields that prove the behaviour. |
 
 ## Cross-skill references
 
@@ -105,45 +117,32 @@ is legitimate. `readFile(config).includes("x")` is not.
 
 ## Examples
 
-### Behaviour over content
-
-| Instead of… | Write… |
-|---|---|
-| Reading a generated config and asserting it equals an expected string | Assert the value the code inserted into the template |
-| Snapshotting a markdown or terraform file's contents | Assert the behaviour the renderer/compiler produced |
-| Asserting a deploy artefact's static bytes | A smoke test that the deployed service is up and ready to serve traffic |
-
-### Mock boundaries
-
-| Instead of… | Write… |
-|---|---|
-| Mocking the internal database driver to verify a query was called | Testing through the repository interface with a test double at that boundary |
-| Mocking `fetch` in a unit test for an API client | Testing the client with a real HTTP stub that returns controlled responses |
-
-### Targeted assertions
+The full `❌ Instead` / `✅ Write` catalogue lives in `EXAMPLES.md`: behaviour over
+implementation, test data, mocking, integration and e2e, targeted assertions, structure and
+naming, determinism and async, isolation, and content assertions. Headline pairs:
 
 | Instead of… | Write… |
 |---|---|
+| Mocking the internal database driver to verify a query was called | Testing through the repository interface with a real in-memory implementation |
+| Snapshotting a markdown or terraform file's contents | Asserting the behaviour the renderer/compiler produced |
 | `expect(result).toEqual(fullExpectedObject)` with every field asserted | `expect(result).toMatchObject({ status: "success", id: expect.any(String) })` |
-| `expect(mockSave).toHaveBeenCalledTimes(1)` and then `expect(mockSave).toHaveBeenCalledWith(data)` | Just the call-args assertion — count is redundant |
-
-### Test data
-
-| Instead of… | Write… |
-|---|---|
 | `const user = sharedUser; user.isAdmin = true;` mutating a module-scope fixture | `const user = createUser({ isAdmin: true });` — fresh per test |
-| Spelling the full object literal in every test | `createUser({ isAdmin: true })` — a helper with defaults and explicit overrides |
 
 ## Verification checklist
 
 - [ ] Test verifies behaviour, not implementation structure
+- [ ] Integration tests exercise the real collaborator — no mocking the engine you are integrating with
+- [ ] E2E smoke tests prove wiring, migrations, and the journey — not business rules covered lower down
+- [ ] Each test fails for exactly one reason, and its name states the behaviour
 - [ ] No mocking of internal module details — only public interfaces
 - [ ] No `before`/`after` hooks for shared test state (infrastructure setup only)
-- [ ] Assertions are targeted — no over-asserting or redundant checks
+- [ ] Assertions are targeted — no over-asserting, no tautologies, no assertion-free tests
 - [ ] No test asserts static file content (config, markdown, terraform, static snapshots) — assertions prove behaviour, not inventory
 - [ ] Test data is built inline or via a fresh-per-test factory; no shared mutable top-level fixture
-- [ ] Reused test data uses a small configurable helper rather than repeated full literals
-- [ ] No skipped or commented-out tests
-- [ ] No flaky tests — all deterministic
+- [ ] Vital data is visible inline; incidental data is defaulted in a factory
+- [ ] Reused test data uses a small configurable factory rather than repeated full literals
+- [ ] No skipped, focused, or commented-out tests
+- [ ] No flaky tests — all deterministic, no sleeps or real clocks
+- [ ] Every async interaction is awaited
 - [ ] No `any` or unsafe casts in test code
 - [ ] No duplication of type or linting coverage

package/skills/workflow/plan/SKILL.md

@@ -47,6 +47,10 @@ Establish what needs to be built through investigation and collaborative design.
    - Technical constraints and trade-offs
    - How each change will be verified
 
+The epic's required sections — `## Success Criteria` for the PRD epic — are the interview's target:
+it is complete only when every required section can be filled from agreed answers. Never invent
+section content; surface assumptions and confirm them with the user.
+
 4. Sketch the major modules that will be built or modified. Look for opportunities to extract deep modules — ones that encapsulate significant behaviour behind a simple, testable interface.
 
 5. Draft a PRD using the template from `write-a-prd`. Include:
@@ -60,8 +64,9 @@ Establish what needs to be built through investigation and collaborative design.
 7. Create an epic bead from the approved PRD:
    ```bash
    bd create "<Feature Title> — PRD" --type epic \
-     --description "<rendered PRD as markdown>" --priority p2
+     --description "<rendered PRD as markdown>" --priority p2 --validate
    bd tag <epic-id> workflow:plan
+   bd lint <epic-id>
    ```
 
 #### Phase 1 gate
@@ -70,7 +75,7 @@ Establish what needs to be built through investigation and collaborative design.
 - [ ] Design decisions resolved through interview
 - [ ] Modules sketched and reviewed with the user
 - [ ] PRD drafted and approved by the user
-- [ ] Epic bead created from approved PRD
+- [ ] Epic bead created from approved PRD and lints clean (`bd lint <epic-id>`)
 
 ### Phase 2 — Break into tasks
 
@@ -82,13 +87,14 @@ Take the approved PRD and produce a set of epics and tasks using tracer-bullet v
    - **Title**: short descriptive name
    - **User stories covered**: which PRD stories this phase addresses
    - **What to build**: end-to-end behaviour description
-   - **Acceptance criteria**: verifiable outcomes
+   - **Success criteria**: verifiable outcomes — the epic's required `## Success Criteria`
 
 10. If the work is small enough for a single epic (one phase, a few tasks), skip epics and proceed directly to Phase 3. A single epic with a few tasks dispatches through ralph more efficiently than creating unnecessary epic hierarchy. If the work has multiple distinct phases, create epics:
     ```bash
     bd create "<Phase Title>" --type epic \
-      --description "<epic body with scope, criteria, dependencies>" --priority <same as parent>
+      --description "<epic body with scope, success criteria, dependencies>" --priority <same as parent> --validate
     bd tag <epic-id> workflow:plan
+    bd lint <epic-id>
     bd dep add <epic-id> <parent-epic-id> --type parent-child
     ```
 
@@ -146,8 +152,13 @@ Deliver a handoff bead and instructions for running ralph.
     - **Multiple independent epics**: create a parent meta-epic that groups them:
       ```bash
       bd create "<Feature Title> — Implementation" --type epic \
-        --description "Meta-epic grouping all phases for execution. See child epics for detail." \
-        --priority <same>
+        --description "Meta-epic grouping all phases for execution. See child epics for detail.
+
+## Success Criteria
+
+- [ ] All child epics complete and the feature verified end-to-end." \
+        --priority <same> --validate
+      bd lint <meta-epic>
       bd dep add <epic-1> <meta-epic> --type parent-child
       bd dep add <epic-2> <meta-epic> --type parent-child
       ```
@@ -187,13 +198,14 @@ Deliver a handoff bead and instructions for running ralph.
 #### Phase 4 gate
 
 - [ ] Handoff bead identified and tagged `workflow:ralph`
+- [ ] Every handoff-path bead lints clean (`bd lint`)
 - [ ] Bead state pushed with `bd dolt push`
 - [ ] Handoff summary presented with the exact instruction to give an agent
 
 ## Phase-gate checklist
 
-- [ ] Phase 1: PRD drafted and approved, epic bead created
-- [ ] Phase 2: Task breakdown approved, epics created (if needed)
+- [ ] Phase 1: PRD drafted and approved, epic bead created and validated
+- [ ] Phase 2: Task breakdown approved, epics created (if needed) and validated
 - [ ] Phase 3: All tasks created, classified, expanded, tree presented
 - [ ] Phase 4: Handoff bead prepared, state pushed, summary delivered
 

package/skills/workflow/ralph/REFERENCE.md

@@ -79,7 +79,9 @@ When a verify or review stage fails:
    ```bash
    fix_id=$(bd create "[<parent-id>] Fix (round <N>)" --type chore \
      --priority <same as parent> \
-     --description "<CHANGES_REQUESTED list or VERIFY_FAILURES list from the triggering REPORT>" -q)
+     --description "Requirements: see <parent-id> acceptance criteria (`bd show <parent-id>`).
+
+<CHANGES_REQUESTED list or VERIFY_FAILURES list from the triggering REPORT>" -q)
    bd tag $fix_id stage:fix
    bd dep add $fix_id <parent-id> --type parent-child   # fix-chore is child of parent
    ```

package/skills/workflow/run-pipeline-stage/SKILL.md

@@ -61,12 +61,17 @@ On stage failure, create a chore bead whose description carries the feedback so
 
 ```bash
 new_id=$(bd create "[<parent-id>] <title>" --type chore \
-  --description "<feedback content from REPORT>" --priority <parent-priority> -q)
+  --description "Requirements: see <parent-id> acceptance criteria (`bd show <parent-id>`).
+
+<feedback content from REPORT>" --priority <parent-priority> -q)
 bd tag $new_id stage:<next-stage>
 bd tag $new_id workflow:ralph
 bd dep add $new_id <parent-id> --type parent-child
 ```
 
+Chore beads carry no required sections, so the feedback description must point at the
+parent/requirements bead (`<parent-id>`) rather than restating its acceptance criteria.
+
 | Triggering outcome | Suggested title | Next stage tag | Description content |
 |---|---|---|---|
 | `OUTCOME: BLOCKED` from verify | `Fix: verify failures` | `stage:code` | Full BLOCKING_ISSUES list |

package/skills/workflow/using-agent-skills/SKILL.md

@@ -23,6 +23,7 @@ Task arrives
     ├── Have a rough idea? ─────────────────→ record-idea
     ├── New feature / PRD needed? ──────────→ write-a-prd
     ├── PRD approved, need tasks? ──────────→ prd-to-tasks
+    ├── Spec approved, need tickets? ───────→ spec-to-tickets
     ├── Need a single task tracked? ────────→ create-task
     ├── Need to plan a feature end-to-end? ─→ plan
     ├── Running beads / task execution? ────→ ralph

package/test/create-chores.test.mjs

@@ -0,0 +1,85 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+import { makeFakeBd } from "./helpers/fake-bd.mjs";
+
+const testDir = dirname(fileURLToPath(import.meta.url));
+const CREATE_CHORES = join(testDir, "..", "skills", "planning", "create-task", "scripts", "create-chores.ts");
+
+/** Run create-chores.ts against the fake `bd` with a parent that already
+ * carries implementation-type:afk — the label `bd create --parent` inherits.
+ * @param {string[]} parentLabels  Labels seeded on the parent bead
+ * @returns {Promise<{ ids: Record<string, string>, beads: Array<{ id: string, title: string, labels: string[] }> }>} */
+async function createChoresAgainstFakeBd(parentLabels) {
+  const dir = await mkdtemp(join(tmpdir(), "create-chores-"));
+  const { bin, state } = await makeFakeBd(dir, {
+    beads: [{ id: "parent-1", title: "Feature", labels: parentLabels }],
+  });
+
+  try {
+    const { exitCode, stdout, stderr } = await runScript(
+      ["--parent", "parent-1"],
+      { BD_PATH: bin, FAKE_BD_STATE: state },
+    );
+    assert.equal(exitCode, 0, stderr);
+
+    const ids = JSON.parse(stdout);
+    const { beads } = JSON.parse(await readFile(state, "utf8"));
+    return { ids, beads };
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+/** Run create-chores.ts with the given env overrides. */
+function runScript(args, env) {
+  return new Promise((resolve) => {
+    execFile(
+      process.execPath,
+      [CREATE_CHORES, ...args],
+      { env: { ...process.env, ...env } },
+      (error, stdout, stderr) => {
+        resolve({ exitCode: error ? error.code ?? 1 : 0, stdout, stderr });
+      },
+    );
+  });
+}
+
+describe("create-chores", () => {
+  it("gives the PR gate exactly its declared labels, without the parent's inherited implementation-type:afk", async () => {
+    const { ids, beads } = await createChoresAgainstFakeBd(["implementation-type:afk"]);
+
+    const gate = beads.find((b) => b.id === ids.featurePrReview);
+    assert.deepEqual(
+      [...gate.labels].sort(),
+      ["implementation-type:hitl", "lifecycle:feature-pr"],
+    );
+  });
+
+  it("still lets stage chores inherit implementation-type:afk from the parent", async () => {
+    const { ids, beads } = await createChoresAgainstFakeBd(["implementation-type:afk"]);
+
+    const codeChore = beads.find((b) => b.id === ids.code);
+    assert.deepEqual(
+      [...codeChore.labels].sort(),
+      ["implementation-type:afk", "stage:code"],
+    );
+  });
+
+  it("validates the PR gate task but not the stage chores", async () => {
+    const { ids, beads } = await createChoresAgainstFakeBd(["implementation-type:afk"]);
+
+    const gate = beads.find((b) => b.id === ids.featurePrReview);
+    assert.equal(gate.type, "task");
+    assert.equal(gate.validated, true);
+    assert.match(gate.description, /## Acceptance Criteria/);
+
+    const codeChore = beads.find((b) => b.id === ids.code);
+    assert.equal(codeChore.validated, false);
+  });
+});

package/test/fake-bd.test.mjs

@@ -0,0 +1,72 @@
+// Tests for the stateful fake `bd` helper's `--validate` model.
+// The fake mirrors `bd create --validate`: a substantive bead whose description lacks the
+// required section(s) for its type is rejected; chores have no requirements.
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { makeFakeBd } from "./helpers/fake-bd.mjs";
+
+/** Run the fake `bd` binary with the given args. */
+function runFake(bin, state, args) {
+  return new Promise((resolve) => {
+    execFile(bin, args, { env: { ...process.env, FAKE_BD_STATE: state } }, (error, stdout, stderr) => {
+      resolve({ exitCode: error ? error.code ?? 1 : 0, stdout, stderr });
+    });
+  });
+}
+
+/** Create a fresh fake workspace, run `fn`, then remove it. */
+async function withFake(fn) {
+  const dir = await mkdtemp(join(tmpdir(), "fake-bd-"));
+  try {
+    const { bin, state } = await makeFakeBd(dir, { beads: [] });
+    await fn(bin, state);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+describe("fake bd --validate", () => {
+  it("rejects a section-less task", async () => {
+    await withFake(async (bin, state) => {
+      const { exitCode, stderr } = await runFake(bin, state, ["create", "empty", "--type", "task", "--validate"]);
+      assert.equal(exitCode, 1);
+      assert.match(stderr, /Acceptance Criteria/);
+    });
+  });
+
+  it("accepts a task carrying ## Acceptance Criteria (case-insensitive)", async () => {
+    await withFake(async (bin, state) => {
+      const { exitCode } = await runFake(bin, state, [
+        "create", "ok", "--type", "task",
+        "--description", "## Acceptance criteria\n- [ ] done",
+        "--validate",
+      ]);
+      assert.equal(exitCode, 0);
+    });
+  });
+
+  it("requires ## Success Criteria for an epic", async () => {
+    await withFake(async (bin, state) => {
+      const { exitCode, stderr } = await runFake(bin, state, [
+        "create", "ep", "--type", "epic",
+        "--description", "## Acceptance Criteria\n- [ ] x",
+        "--validate",
+      ]);
+      assert.equal(exitCode, 1);
+      assert.match(stderr, /Success Criteria/);
+    });
+  });
+
+  it("does not require sections for a chore", async () => {
+    await withFake(async (bin, state) => {
+      const { exitCode } = await runFake(bin, state, ["create", "c", "--type", "chore", "--validate"]);
+      assert.equal(exitCode, 0);
+    });
+  });
+});

package/test/helpers/fake-bd.mjs

@@ -0,0 +1,87 @@
+// Shared test helper: a stateful fake `bd` binary for create-chores.ts.
+// `bd` is a genuine external system (its real database must never be touched
+// by tests), so the script is driven against this fake via the BD_PATH
+// override. The fake reproduces the real behaviours the tests depend on —
+// `bd create --parent` label inheritance (unless `--no-inherit-labels` is
+// passed) and `bd create --validate` section enforcement — and records every
+// created bead to a JSON state file the test can read back.
+//
+// State lives in `state.json` next to the binary; the test seeds it with the
+// parent bead and reads the children back after the script runs. Written async
+// throughout — the repo's check-no-sync lint scans test/ (including helpers).
+
+import { chmod, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const FAKE_BD_SCRIPT = [
+  "#!/usr/bin/env node",
+  "// Stateful fake for `bd create` (test/helpers/fake-bd.mjs).",
+  "const fs = require('node:fs/promises');",
+  "",
+  "const stateFile = process.env.FAKE_BD_STATE;",
+  "const VALUE_FLAGS = new Set(['--type', '--description', '--priority', '--labels', '--parent']);",
+  "const BOOL_FLAGS = new Set(['--silent', '--no-inherit-labels', '--validate']);",
+  "",
+  "(async () => {",
+  "  const argv = process.argv.slice(2);",
+  "  if (argv[0] === 'dep') process.exit(0);",
+  "  if (argv[0] !== 'create') process.exit(1);",
+  "",
+  "  const title = argv[1];",
+  "  const flags = {};",
+  "  const bools = new Set();",
+  "  for (let i = 2; i < argv.length; i++) {",
+  "    const arg = argv[i];",
+  "    if (BOOL_FLAGS.has(arg)) { bools.add(arg); continue; }",
+  "    if (VALUE_FLAGS.has(arg)) { flags[arg] = argv[++i]; continue; }",
+  "  }",
+  "",
+  "  const state = JSON.parse(await fs.readFile(stateFile, 'utf8'));",
+  "",
+  "  // Model `bd create --validate`: reject a substantive bead whose description lacks the",
+  "  // required section(s) for its type. Chores have no requirements and always pass.",
+  "  if (bools.has('--validate')) {",
+  "    const type = flags['--type'] || 'task';",
+  "    const required = {",
+  "      task: ['## Acceptance Criteria'],",
+  "      feature: ['## Acceptance Criteria'],",
+  "      bug: ['## Steps to Reproduce', '## Acceptance Criteria'],",
+  "      epic: ['## Success Criteria'],",
+  "      chore: [],",
+  "    }[type] || ['## Acceptance Criteria'];",
+  "    const description = flags['--description'] || '';",
+  "    const missing = required.filter((section) => !description.toLowerCase().includes(section.toLowerCase()));",
+  "    if (missing.length > 0) {",
+  "      console.error('missing required sections for ' + type + ': ' + missing.join(', '));",
+  "      process.exit(1);",
+  "    }",
+  "  }",
+  "",
+  "  const explicit = (flags['--labels'] || '').split(',').filter(Boolean);",
+  "  const parent = state.beads.find((b) => b.id === flags['--parent']);",
+  "  const inherited = parent && !bools.has('--no-inherit-labels') ? parent.labels : [];",
+  "  const labels = [...new Set([...inherited, ...explicit])];",
+  "",
+  "  const id = 'bd-' + state.nextId++;",
+  "  state.beads.push({ id, title, labels, parent: flags['--parent'] ?? null, type: flags['--type'] || 'task', description: flags['--description'] || '', validated: bools.has('--validate') });",
+  "  await fs.writeFile(stateFile, JSON.stringify(state));",
+  "  process.stdout.write(id + '\\n');",
+  "})().catch((err) => {",
+  "  console.error(err);",
+  "  process.exit(1);",
+  "});",
+].join("\n");
+
+/** Create a stateful fake `bd` binary in `dir`.
+ * @param {string} dir  Directory to hold the binary and its state.json
+ * @param {{ beads: Array<{ id: string, title: string, labels: string[] }> }} seed
+ *        Pre-existing beads (the parent) the fake inherits labels from
+ * @returns {Promise<{ bin: string, state: string }>} */
+export async function makeFakeBd(dir, { beads }) {
+  const bin = join(dir, "bd");
+  const state = join(dir, "state.json");
+  await writeFile(bin, FAKE_BD_SCRIPT + "\n");
+  await chmod(bin, 0o755);
+  await writeFile(state, JSON.stringify({ beads, nextId: 1 }));
+  return { bin, state };
+}

package/extensions/agent-guardrails/node_modules/.bin/pi

@@ -1,21 +0,0 @@
-#!/bin/sh
-basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
-
-case `uname` in
-    *CYGWIN*|*MINGW*|*MSYS*)
-        if command -v cygpath > /dev/null 2>&1; then
-            basedir=`cygpath -w "$basedir"`
-        fi
-    ;;
-esac
-
-if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-coding-agent@0.78.1_ws@8.21.0_zod@4.4.3/node_modules/@earendil-works/pi-coding-agent/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-coding-agent@0.78.1_ws@8.21.0_zod@4.4.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
-else
-  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-coding-agent@0.78.1_ws@8.21.0_zod@4.4.3/node_modules/@earendil-works/pi-coding-agent/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-coding-agent@0.78.1_ws@8.21.0_zod@4.4.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
-fi
-if [ -x "$basedir/node" ]; then
-  exec "$basedir/node"  "$basedir/../@earendil-works/pi-coding-agent/dist/cli.js" "$@"
-else
-  exec node  "$basedir/../@earendil-works/pi-coding-agent/dist/cli.js" "$@"
-fi

package/extensions/agent-guardrails/node_modules/.bin/tsc

@@ -1,21 +0,0 @@
-#!/bin/sh
-basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
-
-case `uname` in
-    *CYGWIN*|*MINGW*|*MSYS*)
-        if command -v cygpath > /dev/null 2>&1; then
-            basedir=`cygpath -w "$basedir"`
-        fi
-    ;;
-esac
-
-if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
-else
-  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
-fi
-if [ -x "$basedir/node" ]; then
-  exec "$basedir/node"  "$basedir/../typescript/bin/tsc" "$@"
-else
-  exec node  "$basedir/../typescript/bin/tsc" "$@"
-fi

package/extensions/agent-guardrails/node_modules/.bin/tsserver

@@ -1,21 +0,0 @@
-#!/bin/sh
-basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
-
-case `uname` in
-    *CYGWIN*|*MINGW*|*MSYS*)
-        if command -v cygpath > /dev/null 2>&1; then
-            basedir=`cygpath -w "$basedir"`
-        fi
-    ;;
-esac
-
-if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
-else
-  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
-fi
-if [ -x "$basedir/node" ]; then
-  exec "$basedir/node"  "$basedir/../typescript/bin/tsserver" "$@"
-else
-  exec node  "$basedir/../typescript/bin/tsserver" "$@"
-fi

package/extensions/agent-guardrails/node_modules/.bin/tsx

@@ -1,21 +0,0 @@
-#!/bin/sh
-basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
-
-case `uname` in
-    *CYGWIN*|*MINGW*|*MSYS*)
-        if command -v cygpath > /dev/null 2>&1; then
-            basedir=`cygpath -w "$basedir"`
-        fi
-    ;;
-esac
-
-if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules/tsx/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
-else
-  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules/tsx/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
-fi
-if [ -x "$basedir/node" ]; then
-  exec "$basedir/node"  "$basedir/../tsx/dist/cli.mjs" "$@"
-else
-  exec node  "$basedir/../tsx/dist/cli.mjs" "$@"
-fi

package/extensions/agent-modes/node_modules/.bin/pi

@@ -1,21 +0,0 @@
-#!/bin/sh
-basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
-
-case `uname` in
-    *CYGWIN*|*MINGW*|*MSYS*)
-        if command -v cygpath > /dev/null 2>&1; then
-            basedir=`cygpath -w "$basedir"`
-        fi
-    ;;
-esac
-
-if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-coding-agent@0.78.1_ws@8.21.0_zod@4.4.3/node_modules/@earendil-works/pi-coding-agent/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-coding-agent@0.78.1_ws@8.21.0_zod@4.4.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
-else
-  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-coding-agent@0.78.1_ws@8.21.0_zod@4.4.3/node_modules/@earendil-works/pi-coding-agent/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-coding-agent@0.78.1_ws@8.21.0_zod@4.4.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
-fi
-if [ -x "$basedir/node" ]; then
-  exec "$basedir/node"  "$basedir/../@earendil-works/pi-coding-agent/dist/cli.js" "$@"
-else
-  exec node  "$basedir/../@earendil-works/pi-coding-agent/dist/cli.js" "$@"
-fi

package/extensions/agent-modes/node_modules/.bin/tsc

@@ -1,21 +0,0 @@
-#!/bin/sh
-basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
-
-case `uname` in
-    *CYGWIN*|*MINGW*|*MSYS*)
-        if command -v cygpath > /dev/null 2>&1; then
-            basedir=`cygpath -w "$basedir"`
-        fi
-    ;;
-esac
-
-if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
-else
-  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
-fi
-if [ -x "$basedir/node" ]; then
-  exec "$basedir/node"  "$basedir/../typescript/bin/tsc" "$@"
-else
-  exec node  "$basedir/../typescript/bin/tsc" "$@"
-fi