@jaybeeuu/agent-cortex 1.41.0 → 1.41.1

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 1.41.1
+
+### Patch Changes
+
+- 3991199: Fix the PR gate bead created by `create-task`'s `create-chores.ts` carrying two conflicting
+  `implementation-type` labels. The gate declares `implementation-type:hitl` explicitly, but
+  `bd create --parent` also inherited the parent's `implementation-type:afk`, leaving the one
+  bead whose job is to stop automated merges labelled as autonomous work. The gate now passes
+  `--no-inherit-labels`; stage chores keep inheriting `:afk` intentionally. A regression test
+  drives the script against a stateful fake `bd` and asserts the gate's label set exactly.
+- c37b50a: Add a command/query-separation rule to `style-code`: a function either returns a value or
+  changes state — never both. Commands mutate and return nothing; queries are pure and return a
+  value. Two carve-outs: a command that can fail may return a typed result (`Result<T, E>`) rather
+  than throw, and a fluent builder may return `this` to chain. Returning data about a mutation —
+  the saved row, a count, the previous value — is no longer permitted. The existing result-object
+  guidance is unchanged.
+- c29fe79: Split the `style-tests` example catalogue into a new `EXAMPLES.md` and broaden it into
+  `❌ Instead` / `✅ Write` code pairs across eight categories: behaviour over implementation,
+  test data (vital visible / incidental hidden), mocking at boundaries, targeted assertions,
+  structure and naming, determinism and async, isolation, and content assertions. Red Flags gains
+  the recurring anti-patterns — assertion-free and tautological tests, expected values recomputed
+  with the implementation's own logic, `.only`/focus left in, sleeps and real clocks, unawaited
+  promises, and log-output assertions — and the verification checklist gains matching gates.
+  `SKILL.md` drops back to a lean 146 lines so the principles still load with the skill while the
+  deepened examples live behind progressive disclosure. The `createSomething` factory example is
+  corrected: it had a missing comma (a syntax error), asserted `prop: 0` while overriding with
+  `prop: 1`, and reached for `DeepPartial` where `Partial` reads better for a flat type.
+- c29fe79: Add integration and e2e layer conventions to `style-tests`. A new `## Integration and e2e`
+  section in `EXAMPLES.md` covers six sub-topics with `❌ Instead` / `✅ Write` pairs: what each
+  layer proves, real collaborators over fakes, isolation at the integration layer, bounded async
+  deadlines over sleeps, determinism at the edges, and what e2e should prove. `SKILL.md`
+  generalises the AWS-specific "Integration and e2e are realistic" principle to real-service
+  guidance, defines what unit, integration, and e2e each prove in workflow step 1, and adds two
+  Red Flags rows — an "integration" test that mocks the collaborator it exists to integrate with,
+  and e2e re-testing business rules already covered by unit tests — plus two matching checklist
+  items.
+
 ## 1.41.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaybeeuu/agent-cortex",
-  "version": "1.41.0",
+  "version": "1.41.1",
   "description": "Personal PI package with custom agents, skills, and extensions",
   "keywords": [
     "pi-package"

package/plugin.json

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

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

@@ -24,7 +24,7 @@ One per stage in `pipeline.json` (currently `code`, `verify`, `review`, `documen
 
 - **Type**: `task`
 - **Title**: `[<parent-id>] PR Review and Merge`
-- **Labels**: `implementation-type:hitl`, `lifecycle:feature-pr`
+- **Labels**: `implementation-type:hitl`, `lifecycle:feature-pr` — exactly one `implementation-type` label. The gate declares its own labels, so the script passes `--no-inherit-labels` and it never picks up the parent's `implementation-type:afk`. Stage chores do **not** opt out; they keep inheriting `:afk`.
 - **Dependencies**: `parent-child` to the parent bead; `blocks` on the final document stage chore (`document`, falling back to the last stage in `pipeline.json`).
 - **Purpose**: human review of the agent PR (agent branch → feature branch) before the feature closes.
 

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

@@ -105,5 +105,5 @@ The full bead-property contract (titles, labels, dependencies per chore and for
 - [ ] `implementation-type` label present on the parent bead (`bd label list <id>`) — resolved by the classifier or, on escalation, the rubric subagent.
 - [ ] HITL path: no pipeline chores created, caller told the classification. AFK path: script ran from the target project's cwd and its JSON contains every stage ID plus `featurePrReview`.
 - [ ] Chore titles/labels/dependencies match the contract (`[<parent-id>] <stage title>`, `stage:<id>`, `parent-child` to parent, `blocks` per `dependsOn`), verified against `REFERENCE.md`.
-- [ ] PR gate task exists with `implementation-type:hitl` + `lifecycle:feature-pr` labels and blocks the final document stage chore.
+- [ ] PR gate task exists and blocks the final document stage chore, carrying **exactly one** `implementation-type` label — `implementation-type:hitl` (never an inherited `implementation-type:afk` alongside it) — plus `lifecycle:feature-pr`.
 - [ ] Report returned the parent bead ID, classification, and all child bead IDs.

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

@@ -106,6 +106,10 @@ const prGateBeadId = run([
   '--priority', priority,
   '--labels', 'implementation-type:hitl,lifecycle:feature-pr',
   '--parent', parentId,
+  // The gate declares its own labels; opt out of bd's create-time parent-label
+  // inheritance so its explicit :hitl is never joined by an inherited :afk.
+  // Stage chores deliberately keep inheriting :afk -- do not add this there.
+  '--no-inherit-labels',
   '--silent',
 ]);
 run(['bd', 'dep', 'add', prGateBeadId, documentStageBeadId, '--type', 'blocks']);

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

@@ -23,6 +23,7 @@ description: Defines this project's coding style, conventions, and architectural
 - **Clarity over cleverness.** Code is read many more times than it is written. Clever code optimises for the writing moment; clear code optimises for every subsequent reading.
 - **Validate at system edges, trust the type system within.** Inbound data from API ingress, deserialisation, or inter-service communication is untrusted until validated. Within application boundaries, trust the type system to enforce correct calls — don't re-validate at every internal module boundary.
 - **Prefer result objects for domain errors; reserve exceptions for emergencies.** Expected failures — validation errors, not-found, conflict — belong in a typed result the caller can handle. Thrown `Error` should signal something genuinely broken: a programming mistake, an invariant violation, or unrecoverable state.
+- **A function either returns a value or changes state — never both.** This is command/query separation at function scale: a command mutates (writes, I/O, logging) and returns nothing — `void` or `Promise<void>`; a query is pure and returns a value. Returning data *about* a mutation — the saved row, a count, the previous value, a success boolean — makes one function two operations wearing one name. Two carve-outs: a command that can fail may return a typed result (`Result<T, E>`), which reports an outcome rather than data about the world and so composes with the result-object guidance above; and a fluent builder whose whole purpose is construction may return `this` to chain. Neither licenses a passthrough return — `arr.push()`-style returns stay banned.
 - **Deep modules beat shallow ones.** A tight public API with complexity hidden behind it is easier to use, test, and change than a flat sprawl of interdependent helpers.
 - **Be a class when you are stateful.** When a module must hold mutable state and expose methods that transform or manage it, model it as a class with public methods and real private fields (`#name`) — not a factory function returning a closure of methods. Native `#private` is enforced at runtime; TypeScript's `private` modifier is compile-time only and erases away. This is orthogonal to the functional guidance elsewhere: small components, explicit props, and hooks still govern UI and pure transforms, but a stateful object is a class, and pretending otherwise is a functional idiom wrapped around an object.
 - **Abstraction must earn its keep, but local helpers are free.** An abstraction extracted into a shared module before its shape is proven nearly always guesses wrong. But extracting a local helper to clarify domain logic is always worthwhile — even at first use. The goal is readable code, not zero duplication.
@@ -49,6 +50,7 @@ description: Defines this project's coding style, conventions, and architectural
 - **Broadening scope.** A change that fixes a bug and also renames three modules and extracts an abstraction is three changes. Split it.
 - **Skipping edge validation.** Inbound data at API ingress, deserialisation, or inter-service boundaries is untrusted until validated. Within the application, trust the type system. A missed edge validation silently poisons downstream callers.
 - **Unstructured errors.** A thrown string or `{ message }` object leaves the caller guessing what failed and why. Prefer typed result objects for expected domain failures — use thrown `Error` only when something has genuinely gone wrong (programming error, invariant violation, unrecoverable state).
+- **A mutator that returns.** A function that changes state *and* returns something about that change — a count, the mutated object, the previous value — is two operations wearing one name. Split it into a command that mutates and a query that reads.
 - **Large modules with mixed concerns.** A file doing data loading, state orchestration, and rendering is three modules waiting to be extracted.
 - **Premature cross-module abstraction.** Extracting a shared utility into a common module before the pattern has proven itself across multiple callers nearly always guesses the wrong shape. Local helpers that clarify intent are fine at first use — keep them within the module boundary until the pattern repeats.
 
@@ -64,6 +66,7 @@ description: Defines this project's coding style, conventions, and architectural
 | "I'll throw an Error for this validation failure" | Expected domain failures should be typed results the caller can handle. Reserve thrown `Error` for things that are truly broken. |
 | "I'll extract this into a shared util — it might be useful later" | Extract locally first if it clarifies the code. Promote to shared only when at least a third real caller emerges. Guessing the shape before then wastes time and creates coupling. |
 | "A factory closure is more functional/pure" | State is state — a class names it. A closure over mutable state is an object with extra steps: the state is still there, the API is less discoverable, and nothing is gained. Use `#private` fields and public methods. |
+| "It's convenient to return the saved row / new count from the write" | That return turns a command into a query mid-flight: the caller now depends on data the mutation happens to produce. Return a typed result for the outcome, and let a separate query read the state if the caller needs it. |
 
 ## Cross-skill references
 
@@ -93,5 +96,6 @@ scoping) and the stateful-object-vs-factory pair.
 - [ ] Modules are split by ownership, not just for reshuffling code
 - [ ] State transitions are explicit and encapsulated behind a clear API
 - [ ] Stateful modules with methods are classes using `#private` fields, not factory closures
+- [ ] Functions are commands (mutate, return nothing) or queries (pure, return a value) — never both
 - [ ] Tests and docs updated where behaviour changed
 - [ ] Staged changes scanned with `review-security` before committing

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

@@ -0,0 +1,548 @@
+# Examples
+
+`❌ Instead` / `✅ Write` pairs for the rules in `SKILL.md`. Each pair is a pattern seen in
+real test suites; the left column is what to replace, the right is what to replace it with.
+
+## Behaviour over implementation
+
+Assert the observable outcome. If a refactor that preserves behaviour breaks the test, the test
+was wrong.
+
+```ts
+// ❌ Instead — spies on an internal collaborator; proves only that it was wired up
+const spy = vi.spyOn(taxCalculator, "compute");
+checkout(cart);
+expect(spy).toHaveBeenCalledWith(cart);
+
+// ✅ Write — asserts what the caller observes
+expect(checkout(cart).total).toBe(90);
+```
+
+```ts
+// ❌ Instead — recomputes the expected value with the implementation's own logic,
+// so a bug in that logic passes the test
+const expected = subtotal * (1 - discountRate);
+expect(computeTotal(cart)).toBe(expected);
+
+// ✅ Write — a known-good case with a hard-coded result
+expect(computeTotal(cartOf100With10PercentDiscount)).toBe(90);
+```
+
+```ts
+// ❌ Instead — exports an internal helper so the test can reach it
+export const __testOnlyNormalise = (s: string) => s.trim().toLowerCase();
+
+// ✅ Write — drive the behaviour through the public entry point that uses it
+expect(parseEmail("  Ada@Example.COM ")).toStrictEqual({ address: "ada@example.com" });
+```
+
+## Test data: vital visible, incidental hidden
+
+The values that drive the case belong in the test body. Everything else takes an obvious
+default in a factory.
+
+```ts
+// ❌ Instead — the value under test is hidden in a top-of-file constant.
+// A reader cannot see which field makes this case "admin".
+const ADMIN_USER: User = { id: "u1", name: "Ada", isAdmin: true, locale: "en-GB" };
+
+it("grants admin access", () => {
+  expect(canEdit(ADMIN_USER)).toBe(true);
+});
+
+// ✅ Write — the driving value is on the assertion's line
+it("grants admin access", () => {
+  expect(canEdit(createUser({ isAdmin: true }))).toBe(true);
+});
+```
+
+```ts
+// ❌ Instead — one module-scope object, mutated and reused across tests.
+// These tests now depend on each other and on their order.
+const user: User = { id: "u1", name: "Ada", isAdmin: false };
+
+it("denies guest access", () => {
+  expect(canEdit(user)).toBe(false);
+});
+
+it("grants admin access", () => {
+  user.isAdmin = true;
+  expect(canEdit(user)).toBe(true);
+}); // order-dependent: the first test fails if this one runs first
+
+// ✅ Write — fresh data per test, produced by a factory
+const createUser = (overrides: Partial<User> = {}): User => ({
+  id: "u1",
+  name: "Ada",
+  isAdmin: false,
+  ...overrides,
+});
+
+it("grants admin access", () => {
+  expect(canEdit(createUser({ isAdmin: true }))).toBe(true);
+});
+
+it("denies guest access", () => {
+  expect(canEdit(createUser())).toBe(false);
+});
+```
+
+```ts
+// ❌ Instead — the full literal is re-spelled in every test, obscuring the one field that changes
+it("grants admin access", () => {
+  expect(canEdit({ id: "u1", name: "Ada", isAdmin: true, locale: "en-GB" })).toBe(true);
+});
+
+// ✅ Write — a factory defaults the incidental data, overrides carry the case
+interface SomeThing {
+  prop: number;
+  otherProp: string;
+}
+
+// Colocated with the tests, named for what it builds. Partial is enough for a flat
+// type; reach for a deep-partial only when the type nests.
+const createSomething = (overrides: Partial<SomeThing> = {}): SomeThing => ({
+  prop: 0,
+  otherProp: "{other-prop}",
+  ...overrides,
+});
+
+it("overrides only the value under test", () => {
+  const fixture = createSomething({ prop: 1 });
+
+  expect(fixture).toStrictEqual({ prop: 1, otherProp: "{other-prop}" });
+});
+```
+
+## Mocking: boundaries, not internals
+
+Mock the genuine external edge — network, clock, third-party SDK. Do not mock a collaborator
+inside the application; a real or in-memory one is usually cheaper and never lies.
+
+```ts
+// ❌ Instead — the mock replaces an internal collaborator, so the test
+// proves nothing about the real interaction
+vi.mock("../repository/userRepository");
+await saveUser(user);
+expect(userRepository.save).toHaveBeenCalledWith(user);
+
+// ✅ Write — a real in-memory implementation at the genuine boundary
+const repository = new InMemoryUserRepository();
+const service = new UserService(repository);
+
+await service.save(user);
+
+expect(await repository.get(user.id)).toStrictEqual(user);
+```
+
+```ts
+// ❌ Instead — the test asserts the stub it just configured, not the mapping
+vi.spyOn(http, "get").mockResolvedValue({ status: 200, body: apiUserResponse });
+expect(await fetchUser("u1")).toStrictEqual(apiUserResponse);
+
+// ✅ Write — stub the edge, assert the domain mapping the client performs
+vi.spyOn(http, "get").mockResolvedValue({ status: 200, body: apiUserResponse });
+expect(await fetchUser("u1")).toStrictEqual({ id: "u1", displayName: "Ada" });
+```
+
+Mock as little as possible: if a real collaborator is fast, deterministic, and side-effect free,
+use it.
+
+## Integration and e2e
+
+These layers prove what units cannot: that your code speaks correctly to a real collaborator,
+and that the assembled system works. They are the layers agents skip, and where flakiness is
+born. See `SKILL.md` for the principles that govern them.
+
+### What each layer proves
+
+A unit proves logic in isolation. An integration test proves your code against a real
+collaborator across **one seam**. An e2e test proves the assembled system on a user-visible
+journey. Pick the lowest layer that can prove the behaviour.
+
+```ts
+// ❌ Instead — an "integration" test that mocks the collaborator it exists to integrate with
+vi.mock("../db/pool");
+await saveOrder(order);
+expect(pool.query).toHaveBeenCalledWith(expect.stringContaining("INSERT INTO orders"));
+
+// ✅ Write — exercises the real collaborator across the seam
+await withPostgres(async (db) => {
+  const repository = new OrderRepository(db);
+  await repository.save(order);
+
+  expect(await repository.get(order.id)).toMatchObject({ id: order.id });
+});
+```
+
+```ts
+// ❌ Instead — a unit-tested rule re-proved at e2e: slow, and it proves nothing new
+it("applies a 10% discount to a £100 order", async () => {
+  await addToCart(page, productPricedAt(100));
+  await openCart(page);
+
+  expect(await page.textContent(".total")).toBe("£90.00");
+});
+
+// ✅ Write — e2e proves the journey and the wiring; the rule stays a unit test
+it("lets a signed-in customer complete checkout", async () => {
+  await signIn(page, customer);
+  await addToCart(page, product);
+  await checkout(page);
+
+  expect(await page.textContent(".confirmation")).toContain("Thank you");
+});
+```
+
+### Real collaborators, not fakes
+
+Run the genuine engine — Postgres, Redis, a queue, object storage — through TestContainers or
+LocalStack. A fake drifts from the real contract and reintroduces exactly the bug the
+integration test was written to catch. Fake only what you genuinely cannot run locally, and
+use a contract double when you do.
+
+```ts
+// ❌ Instead — a hand-rolled fake that does not share the real broker's contract
+const fakeQueue = { send: vi.fn() };
+await publishOrder(queueAdapter(fakeQueue));
+expect(fakeQueue.send).toHaveBeenCalled();
+
+// ✅ Write — the real broker in a container
+const queue = await startQueueContainer();
+await publishOrder(queueAdapter(queue));
+
+const [received] = await consumeOne(queue, ORDER_TOPIC);
+expect(received).toMatchObject({ id: order.id });
+```
+
+```ts
+// ❌ Instead — an ad-hoc stub invented per test; nothing pins it to the provider's API
+vi.spyOn(stripe, "charge").mockResolvedValue({ id: "ch_1" });
+
+// ✅ Write — a contract double generated from the provider's schema
+server.use(http.post("/v1/charges", () => HttpResponse.json(stripeChargeFixture)));
+
+expect(await client.charge(customer, 100)).toMatchObject({ id: "ch_1" });
+```
+
+### Isolation at the integration layer
+
+State is the enemy here. Give every test its own data and its own schema, namespace, or
+transaction; never share a seeded row or a long-lived database between tests or parallel
+workers. Starting a container is expensive and legitimately belongs in `beforeAll` — data
+does not.
+
+```ts
+// ❌ Instead — a shared seeded row mutated across tests; passes alone, fails in a parallel run
+beforeAll(async () => {
+  db = await startPostgresContainer();
+  await db.exec(seedSql);
+});
+
+it("updates the account", async () => {
+  await db.update("accounts", { id: "acc-1" }, { balance: 50 });
+});
+
+it("reads the seeded balance", async () => {
+  expect(await db.get("accounts", "acc-1")).toMatchObject({ balance: 100 });
+});
+
+// ✅ Write — container per suite, data per test
+beforeAll(async () => {
+  db = await startPostgresContainer();
+});
+
+it("updates the account", async () => {
+  const account = await createAccount(db, { balance: 100 });
+  await updateBalance(db, account.id, 50);
+
+  expect(await getAccount(db, account.id)).toMatchObject({ balance: 50 });
+});
+
+it("reads the inserted balance", async () => {
+  const account = await createAccount(db, { balance: 100 });
+
+  expect(await getAccount(db, account.id)).toMatchObject({ balance: 100 });
+});
+```
+
+### Async and eventual consistency
+
+Integration surfaces are asynchronous by nature. Await the observable signal with a bounded
+deadline; a fixed sleep is both slow and a race it may still lose.
+
+```ts
+// ❌ Instead — sleeps past the queue, then races it anyway
+await publishOrder(queue, order);
+await new Promise((resolve) => setTimeout(resolve, 500));
+
+expect(await findProjection(db, order.id)).toBeDefined();
+
+// ✅ Write — poll the observable signal with a bounded deadline
+await publishOrder(queue, order);
+await waitFor(async () => (await findProjection(db, order.id)) !== null, {
+  timeout: 5_000,
+  description: "order projection",
+});
+```
+
+```ts
+// ❌ Instead — asserts a step that has not run yet
+it("emits an audit event on save", async () => {
+  await saveUser(user);
+
+  expect(await auditLog.events()).toHaveLength(1);
+});
+
+// ✅ Write — await the event, then assert it
+it("emits an audit event on save", async () => {
+  await saveUser(user);
+  const event = await waitForEvent(auditLog, { type: "user.saved" });
+
+  expect(event).toMatchObject({ userId: user.id });
+});
+```
+
+### Determinism at the edges
+
+Pin the images, freeze the clock, and seed randomness. A test that pulls `latest` or reads the
+wall clock fails eventually for reasons that have nothing to do with the code.
+
+```ts
+// ❌ Instead — floating image tag and the real clock
+const container = await new GenericContainer("postgres:latest").start();
+const invoice = createInvoice({ issuedAt: new Date() });
+
+// ✅ Write — pinned image and an injected clock
+const container = await new GenericContainer("postgres:16.4-alpine").start();
+const clock = new FixedClock("2024-01-01T00:00:00Z");
+const invoice = createInvoice({ issuedAt: clock.now() });
+```
+
+### What e2e should prove
+
+E2E is the most expensive layer, so spend it only on what nothing else can prove: that the
+parts are wired together, migrations ran, configuration loaded, and a user can complete the
+journey. Keep the count small.
+
+```ts
+// ❌ Instead — reaches inside the system to assert call order
+it("checks out", async () => {
+  await checkout(page);
+
+  expect(spyOn(inventoryService, "reserve")).toHaveBeenCalledBefore(
+    spyOn(paymentService, "charge"),
+  );
+});
+
+// ✅ Write — asserts what the journey produced
+it("checks out", async () => {
+  await checkout(page);
+
+  expect(await page.textContent(".confirmation")).toContain("Thank you");
+  expect(await api.getOrder(orderRef)).toMatchObject({ state: "confirmed" });
+});
+```
+
+## Assertions: targeted, never tautological
+
+```ts
+// ❌ Instead — every field asserted; any unrelated field change breaks the test
+expect(created).toStrictEqual({
+  id: "u1",
+  status: "active",
+  createdAt: "2024-01-01T00:00:00.000Z",
+  updatedAt: "2024-01-01T00:00:00.000Z",
+  version: 3,
+});
+
+// ✅ Write — assert the fields that carry the behaviour; use `expect.any` for the rest
+expect(created).toMatchObject({ status: "active", id: expect.any(String) });
+```
+
+```ts
+// ❌ Instead — the count is implied by the argument assertion
+expect(mockSave).toHaveBeenCalledTimes(1);
+expect(mockSave).toHaveBeenCalledWith(user);
+
+// ✅ Write — the argument assertion already proves a single, correct call
+expect(mockSave).toHaveBeenCalledWith(user);
+```
+
+```ts
+// ❌ Instead — cannot fail; delete the implementation and this stays green
+it("handles the request", async () => {
+  const result = await handler(request);
+  expect(result).toBeDefined();
+});
+
+// ✅ Write — names the observable contract
+it("returns 200 for a valid request", async () => {
+  const response = await handler(request);
+
+  expect(response.status).toBe(200);
+});
+```
+
+```ts
+// ❌ Instead — no assertion at all; a smoke test that proves only "it did not throw"
+it("processes an order", async () => {
+  await processOrder(order);
+});
+
+// ✅ Write — assert the effect the call was supposed to have
+it("marks a processed order as fulfilled", async () => {
+  await processOrder(order);
+
+  expect(await orders.get(order.id)).toMatchObject({ state: "fulfilled" });
+});
+```
+
+## Structure and naming
+
+```ts
+// ❌ Instead — the name describes the implementation, and "works" says nothing
+it("calls send once", ...);
+it("works", ...);
+
+// ✅ Write — the name states the behaviour the test proves
+it("sends a confirmation email after a successful checkout", ...);
+it("rejects a checkout with an expired card", ...);
+```
+
+```ts
+// ❌ Instead — unrelated behaviours in one test: a failure does not localise
+it("handles users", async () => {
+  expect(await createUser(valid)).toHaveProperty("id");
+  await expect(createUser(invalid)).rejects.toThrow();
+  expect(await listUsers()).toHaveLength(1);
+});
+
+// ✅ Write — one behaviour per test, so the failure name tells you what broke
+it("assigns an id when creating a user", ...);
+it("rejects a user with no email", ...);
+it("lists every created user", ...);
+```
+
+```ts
+// ❌ Instead — loops zero times and passes when there is nothing to check
+for (const item of cart.items) {
+  expect(item.price).toBeGreaterThan(0);
+}
+
+// ✅ Write — assert the collection, so an empty cart fails
+expect(cart.items.map((item) => item.price)).toStrictEqual([10, 20, 30]);
+```
+
+## Determinism and async
+
+```ts
+// ❌ Instead — a sleep races the work and slows the suite
+await new Promise((resolve) => setTimeout(resolve, 100));
+expect(job.state).toBe("done");
+
+// ✅ Write — await the observable completion signal
+await job.completion;
+expect(job.state).toBe("done");
+```
+
+```ts
+// ❌ Instead — real wall clock and random ids make the expected value unknowable
+const invoice = { id: crypto.randomUUID(), issuedAt: new Date() };
+
+// ✅ Write — fixed values in the factory; override only what the case needs
+const createInvoice = (overrides: Partial<Invoice> = {}): Invoice => ({
+  id: "invoice-1",
+  issuedAt: new Date("2024-01-01T00:00:00Z"),
+  ...overrides,
+});
+```
+
+```ts
+// ❌ Instead — the promise is never returned or awaited, so a rejection
+// becomes an unhandled rejection and the test stays green
+it("rejects an invalid payload", () => {
+  expect(handler(bad)).rejects.toThrow();
+});
+
+// ✅ Write — await the assertion
+it("rejects an invalid payload", async () => {
+  await expect(handler(bad)).rejects.toThrow();
+});
+```
+
+## Isolation
+
+```ts
+// ❌ Instead — focus and skip markers committed; the suite silently runs less
+it.only("saves the user", ...);
+it.skip("handles a timeout", ...);
+
+// ✅ Write — remove the marker; fix the failing test or delete it
+it("saves the user", ...);
+it("handles a timeout", ...);
+```
+
+```ts
+// ❌ Instead — a shared row mutated by both tests; order now matters
+let row: Row;
+
+beforeEach(async () => {
+  row = await db.insert(makeRow());
+});
+
+it("updates the row", async () => {
+  await db.update(row.id, { name: "Ada" });
+});
+
+it("reads the row", async () => {
+  expect(await db.get(row.id)).toMatchObject({ name: "Original" });
+});
+
+// ✅ Write — each test owns its data; no cross-test coupling
+it("updates the row", async () => {
+  const row = await db.insert(makeRow());
+  await db.update(row.id, { name: "Ada" });
+
+  expect(await db.get(row.id)).toMatchObject({ name: "Ada" });
+});
+
+it("reads the row as inserted", async () => {
+  const row = await db.insert(makeRow());
+
+  expect(await db.get(row.id)).toMatchObject({ name: "Original" });
+});
+```
+
+`before`/`after` hooks are for expensive, non-observable infrastructure — starting a server,
+opening a connection — never for data a test asserts on.
+
+## Content assertions
+
+Assert the behaviour the file participates in. A comparison against an expected file is a
+content inventory; it breaks on a comment and proves nothing about the code.
+
+```ts
+// ❌ Instead — catalogues the generated file
+const config = await readFile("generated/nginx.conf", "utf8");
+expect(config).toBe("server { listen 80; }");
+
+// ✅ Write — asserts what the generator did with the input
+const config = await generateNginxConfig({ port: 8080 });
+
+expect(config).toContain("listen 8080;");
+```
+
+```ts
+// ❌ Instead — snapshots static markdown and calls it a test
+expect(await renderReadme(project)).toMatchSnapshot();
+
+// ✅ Write — asserts the renderer produced the section it was asked for
+const readme = await renderReadme({ ...project, title: "Agent Cortex" });
+
+expect(readme).toContain("# Agent Cortex");
+```
+
+A golden-output test is legitimate when the expected output is a **product of the behaviour
+under test** — a parser's AST, a compiler's emitted artifact. It is illegitimate when the file
+is static input the test simply re-reads.

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/test/create-chores.test.mjs

@@ -0,0 +1,73 @@
+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"],
+    );
+  });
+});

package/test/helpers/fake-bd.mjs

@@ -0,0 +1,67 @@
+// 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 one real behaviour the test depends on —
+// `bd create --parent` inherits the parent's labels unless
+// `--no-inherit-labels` is passed — 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']);",
+  "",
+  "(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'));",
+  "  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 });",
+  "  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 };
+}