@jaybeeuu/agent-cortex 1.39.0 → 1.41.0

package/skills/planning/classify-bead/scripts/classify-bead.mjs

@@ -0,0 +1,292 @@
+// Deterministic bead classifier — resolves an AFK/HITL classification from
+// evidence already present on a bead before any model judgement is spent.
+//
+// Tier order (see skills/planning/classify-bead/SKILL.md):
+//   1. implementation-type label   — an existing decision is authoritative
+//   2. legacy ## Type field        — back-compat with pre-label beads
+//   3. conservative heuristics     — explicit natural-language signals only
+//   4. escalate                    — hand to the rubric (small/cheap model)
+//
+// Zero dependencies: run with `node classify-bead.mjs <bead-id>`.
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { pathToFileURL } from 'node:url';
+
+/** @typedef {'afk' | 'hitl'} Classification */
+/** @typedef {'label' | 'type-field' | 'heuristic'} ResolutionSource */
+
+/**
+ * @typedef {object} Resolution
+ * @property {Classification | null} classification  Resolved class, or null when the rubric must decide.
+ * @property {ResolutionSource | null} source        Which tier produced the resolution.
+ * @property {string} reason                         Human-readable justification for the resolution.
+ * @property {boolean} escalate                      True when model judgement is required (tier 4).
+ */
+
+const AFK_LABEL = 'implementation-type:afk';
+const HITL_LABEL = 'implementation-type:hitl';
+
+// Heuristic signals are deliberately conservative: they only fire on explicit
+// natural-language phrasing that maps directly onto the rubric's criteria.
+// Anything short of that escalates to the rubric rather than guessing.
+
+// Rubric: a human is required to perform or verify the work.
+const HITL_SIGNALS = [
+  /\brequires? (a )?human\b/i,
+  /\bhuman (sign-?off|approval|judgement|decision)\b/i,
+  /\bmanual (step|action|intervention)\b/i,
+  /\bvisual(ly)? (review|inspect|verify)\b/i,
+  /\bstakeholder (sign-?off|approval)\b/i,
+  /\b(credential|secret)s? (setup|rotation|provisioning)\b/i,
+  /\bprovision(ing)?\b[^.]{0,40}\b(infrastructure|infra|server|cluster)\b/i,
+];
+
+// Rubric: the bead explicitly rules out human involvement.
+const AFK_EXPLICIT_SIGNALS = [
+  /\bno human (action|input|review|intervention|judgement)\b/i,
+];
+
+// Rubric: acceptance criteria an agent can check without a human.
+const AFK_SIGNALS = [
+  /\bmachine-checkable\b/i,
+  /\bautomated (test|tests|check|checks|verification)\b/i,
+];
+
+/** @param {RegExp[]} patterns @param {string} text */
+function matchesAny(patterns, text) {
+  return patterns.some((pattern) => pattern.test(text));
+}
+
+/**
+ * @param {Classification} classification
+ * @param {ResolutionSource} source
+ * @param {string} reason
+ * @returns {Resolution}
+ */
+function resolved(classification, source, reason) {
+  return { classification, source, reason, escalate: false };
+}
+
+/** @param {string} reason @returns {Resolution} */
+function needsRubric(reason) {
+  return { classification: null, source: null, reason, escalate: true };
+}
+
+/**
+ * Read the legacy `## Type` section out of a bead description.
+ *
+ * Accepts both the block form (`## Type` then a following `AFK`/`HITL` line)
+ * and the inline form (`## Type: AFK`). Returns null when the section is absent
+ * or carries an unrelated value.
+ *
+ * @param {string} description
+ * @returns {Classification | null}
+ */
+function extractTypeField(description) {
+  const inline = description.match(/^[ \t]*#{1,6}[ \t]*Type[ \t]*:[ \t]*(AFK|HITL)\b/im);
+  if (inline) return /** @type {Classification} */ (inline[1].toLowerCase());
+
+  const block = description.match(/^[ \t]*#{1,6}[ \t]*Type[ \t]*\r?\n+[ \t]*(AFK|HITL)[ \t]*(?:\r?\n|$)/im);
+  if (block) return /** @type {Classification} */ (block[1].toLowerCase());
+
+  return null;
+}
+
+/**
+ * Resolve a bead's implementation type from the evidence it already carries,
+ * without spending a model call.
+ *
+ * @param {{ labels?: string[], description?: string }} bead
+ * @returns {Resolution}
+ */
+export function resolveClassification({ labels = [], description = '' }) {
+  if (labels.includes(AFK_LABEL)) return resolved('afk', 'label', `${AFK_LABEL} label already present`);
+  if (labels.includes(HITL_LABEL)) return resolved('hitl', 'label', `${HITL_LABEL} label already present`);
+
+  const typeField = extractTypeField(description);
+  if (typeField) return resolved(typeField, 'type-field', `legacy ## Type field declares ${typeField.toUpperCase()}`);
+
+  // Conservative heuristics: a HITL signal wins over an AFK one, mirroring the
+  // rubric's "a human is required if any criterion is true" rule.
+  if (matchesAny(HITL_SIGNALS, description)) {
+    return resolved('hitl', 'heuristic', 'description states a human-required action or verification');
+  }
+  if (matchesAny(AFK_EXPLICIT_SIGNALS, description)) {
+    return resolved('afk', 'heuristic', 'description explicitly rules out human involvement');
+  }
+  if (matchesAny(AFK_SIGNALS, description)) {
+    return resolved('afk', 'heuristic', 'description states machine-checkable acceptance criteria');
+  }
+
+  return needsRubric('no deterministic signal; rubric judgement required');
+}
+
+/** @param {Classification} classification */
+function labelFor(classification) {
+  return classification === 'afk' ? AFK_LABEL : HITL_LABEL;
+}
+
+/** @typedef {{ label: number, typeField: number, heuristic: number, rubric: number }} SourceCounts */
+
+/**
+ * @typedef {object} AuditSummary
+ * @property {number} sampled
+ * @property {SourceCounts} bySource
+ * @property {number} deterministic     Beads resolved without a model call.
+ * @property {number} needsRubric       Beads that would escalate to the rubric.
+ * @property {number} deterministicRatio deterministic / sampled (0 when empty).
+ */
+
+/**
+ * Measure what share of a bead sample the deterministic tiers resolve. This is
+ * the "measure first" number that sizes the win over spawning a subagent.
+ *
+ * @param {Array<{ labels?: string[], description?: string }>} beads
+ * @returns {AuditSummary}
+ */
+export function auditBeads(beads) {
+  /** @type {SourceCounts} */
+  const bySource = { label: 0, typeField: 0, heuristic: 0, rubric: 0 };
+
+  for (const bead of beads) {
+    const { source } = resolveClassification(bead);
+    if (source === 'label') bySource.label += 1;
+    else if (source === 'type-field') bySource.typeField += 1;
+    else if (source === 'heuristic') bySource.heuristic += 1;
+    else bySource.rubric += 1;
+  }
+
+  const deterministic = bySource.label + bySource.typeField + bySource.heuristic;
+  return {
+    sampled: beads.length,
+    bySource,
+    deterministic,
+    needsRubric: bySource.rubric,
+    deterministicRatio: beads.length === 0 ? 0 : deterministic / beads.length,
+  };
+}
+
+// ─── CLI ──────────────────────────────────────────────────────────────────────
+
+const USAGE =
+  'Usage: node classify-bead.mjs <bead-id> [--dry-run]\n' +
+  '       node classify-bead.mjs --audit [--limit <n>]';
+
+const DEFAULT_AUDIT_LIMIT = 100;
+
+// BD_PATH env override lets machines where bd is not on PATH pin a location.
+const BD_PATH = process.env.BD_PATH || 'bd';
+const execFileAsync = promisify(execFile);
+
+class UsageError extends Error {}
+
+/**
+ * @param {string[]} argv
+ * @returns {{ beadId: string | null, audit: boolean, limit: number, dryRun: boolean, help: boolean }}
+ */
+function parseArgs(argv) {
+  const options = {
+    beadId: /** @type {string | null} */ (null),
+    audit: false,
+    limit: DEFAULT_AUDIT_LIMIT,
+    dryRun: false,
+    help: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--audit') {
+      options.audit = true;
+    } else if (arg === '--dry-run') {
+      options.dryRun = true;
+    } else if (arg === '--help' || arg === '-h') {
+      options.help = true;
+    } else if (arg === '--limit') {
+      const value = Number.parseInt(argv[++i] ?? '', 10);
+      if (!Number.isInteger(value) || value <= 0) throw new UsageError('--limit requires a positive integer');
+      options.limit = value;
+    } else if (arg.startsWith('-')) {
+      throw new UsageError(`unknown option: ${arg}`);
+    } else if (options.beadId) {
+      throw new UsageError(`unexpected argument: ${arg}`);
+    } else {
+      options.beadId = arg;
+    }
+  }
+
+  return options;
+}
+
+/** @type {(args: string[]) => Promise<string>} */
+async function defaultExec(args) {
+  const { stdout } = await execFileAsync(BD_PATH, args, { encoding: 'utf-8' });
+  return stdout;
+}
+
+/**
+ * @param {object} options
+ * @param {string[]} options.argv                      CLI arguments (without node/script).
+ * @param {(args: string[]) => Promise<string>} [options.exec]  bd runner; injectable for tests.
+ * @param {(chunk: string) => void} [options.write]    stdout sink; injectable for tests.
+ * @returns {Promise<number>} process exit code.
+ */
+export async function runCli({ argv, exec = defaultExec, write = (chunk) => process.stdout.write(chunk) }) {
+  const options = parseArgs(argv);
+
+  if (options.help) {
+    write(`${USAGE}\n`);
+    return 0;
+  }
+
+  if (options.audit) {
+    const beads = JSON.parse(
+      await exec(['list', '--all', '--json', '--limit', String(options.limit), '--sort', 'created']),
+    );
+    write(`${JSON.stringify(auditBeads(beads), null, 2)}\n`);
+    return 0;
+  }
+
+  if (!options.beadId) {
+    write(`${USAGE}\n`);
+    return 2;
+  }
+
+  const [bead] = JSON.parse(await exec(['show', options.beadId, '--json']));
+  if (!bead) throw new Error(`bead not found: ${options.beadId}`);
+
+  const resolution = resolveClassification(bead);
+  const label = resolution.classification ? labelFor(resolution.classification) : null;
+  const applied = label !== null && resolution.source !== 'label' && !options.dryRun;
+
+  if (applied) await exec(['tag', options.beadId, /** @type {string} */ (label)]);
+
+  write(
+    `${JSON.stringify(
+      {
+        id: options.beadId,
+        classification: resolution.classification,
+        source: resolution.source,
+        reason: resolution.reason,
+        escalate: resolution.escalate,
+        applied,
+        label,
+      },
+      null,
+      2,
+    )}\n`,
+  );
+  return 0;
+}
+
+// Only run the CLI when invoked directly, so tests can import the pure tiers.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runCli({ argv: process.argv.slice(2) })
+    .then((code) => {
+      process.exitCode = code;
+    })
+    .catch((error) => {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+      process.exitCode = error instanceof UsageError ? 2 : 1;
+    });
+}

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

@@ -33,15 +33,23 @@ Turn a piece of work into a tracked bead, classify it for autonomous (AFK) or hu
    bd dep add <new-id> <parent> --type parent-child
    ```
 
-2. **Check for an existing classification label.** Run `bd label list <id>`. If `implementation-type` is already present, skip step 3 — re-classifying a labelled bead wastes a subagent call.
+2. **Classify deterministically.** Run the `classify-bead` classifier — it resolves an existing label, the legacy `## Type` field, and explicit heuristic signals without a model call, and applies the label itself when it resolves:
 
-3. **Classify the bead.** Delegate to the `classify-bead` skill as a subagent via {{TOOL:task}} — do not classify inline. It returns `AFK` or `HITL` and applies the `implementation-type` label.
+   ```bash
+   # Run from the TARGET project's directory — bd resolves its beads DB from cwd.
+   node <skill-scripts>/../../classify-bead/scripts/classify-bead.mjs <new-id>
+   ```
+
+   - `"classification": "afk" | "hitl"` → the label is applied; branch on that class in step 3.
+   - `"escalate": true` → delegate to the `classify-bead` skill as a subagent via {{TOOL:task}}; it applies the rubric and tags the bead.
+
+   `<skill-scripts>` is the absolute path to this skill's own `scripts/` directory, resolved from wherever this skill was loaded. Sibling skills sit alongside this skill's directory in every harness, so `../../classify-bead/scripts/` resolves to the classifier.
 
-4. **Branch on classification.**
+3. **Branch on classification.**
    - **HITL** — stop here. Report the bead ID and classification to the caller. Do not create pipeline chores: a human drives the work, so the chore tree does not apply.
-   - **AFK** — continue to step 5.
+   - **AFK** — continue to step 4.
 
-5. **Expand into pipeline stage chores.** Run the `create-chores` script, which reads this skill's `pipeline.json` and deterministically creates all stage chores plus the PR gate bead in one shot:
+4. **Expand into pipeline stage chores.** Run the `create-chores` script, which reads this skill's `pipeline.json` and deterministically creates all stage chores plus the PR gate bead in one shot:
 
    ```bash
    # Run from the TARGET project's directory — bd resolves its beads DB from cwd;
@@ -53,12 +61,13 @@ Turn a piece of work into a tracked bead, classify it for autonomous (AFK) or hu
 
    `<skill-scripts>` is the absolute path to this skill's own `scripts/` directory, resolved from wherever this skill was loaded — it varies by harness and install location, so never hardcode one harness's path.
 
-6. **Report.** Return the parent bead ID, the classification (`AFK`), and the created child bead IDs from the script output (including `featurePrReview`).
+5. **Report.** Return the parent bead ID, the classification (`AFK`), and the created child bead IDs from the script output (including `featurePrReview`).
 
 ## Red Flags
 
 - **Running the script from the wrong directory.** Chores land in whatever `.beads` tree `bd` resolves from cwd — the target project's root is the only safe cwd.
-- **Classifying inline.** The `classify-bead` rubric is a subagent's job (with a label short-circuit); inlining yours means re-reading bead content and drifting from the rubric.
+- **Spawning the `classify-bead` subagent when the classifier already resolved the bead.** The deterministic script is the short-circuit; a subagent is only for `escalate: true`.
+- **Skipping the classifier and classifying by hand.** The rubric is a subagent's job; a hand-rolled guess drifts from it.
 - **Expanding an HITL bead.** If classification is HITL, stop — creating a chore tree for human-driven work is wrong.
 - **Hardcoding `<skill-scripts>`.** The install path differs per harness (plugin cache, installed-plugins, dev checkout); resolve it at runtime.
 
@@ -66,7 +75,7 @@ Turn a piece of work into a tracked bead, classify it for autonomous (AFK) or hu
 
 | Rationalization | Rebuttal |
 |---|---|
-| "I know this task is AFK — I'll skip the classify-bead call" | Classification is a rubric check against the full bead body; assumptions masked by familiarity cause mislabelled work to hit the wrong queue. |
+| "I know this task is AFK — I'll skip the classifier" | The classifier resolves the label, `## Type`, and explicit signals in one command; skipping it leaves the bead unlabelled or forces a needless subagent. |
 | "I'll create the chores by hand instead of running the script" | The script is the single source of truth for titles, labels, dep chains, and the PR gate. Hand-created chores drift silently. |
 | "The pipeline is overkill for this small task" | If the work is worth tracking at all, the stage chore tree is what lets ralph execute and gate it. Not ready for that? Use `record-idea`. |
 
@@ -77,7 +86,7 @@ Turn a piece of work into a tracked bead, classify it for autonomous (AFK) or hu
 
 ## Cross-skill references
 
-- `classify-bead` — classify the new bead via subagent (step 3).
+- `classify-bead` — deterministic classifier first, rubric subagent only on escalation (step 2).
 
 ## Examples
 
@@ -93,7 +102,7 @@ The full bead-property contract (titles, labels, dependencies per chore and for
 
 - [ ] Parent bead exists with the correct title, description, and priority.
 - [ ] `parent-child` dependency added when a parent epic was supplied.
-- [ ] `implementation-type` label present on the parent bead (`bd label list <id>`).
+- [ ] `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.

package/skills/planning/write-a-prd/SKILL.md

@@ -25,7 +25,7 @@ description: Create a PRD through user interview, codebase exploration, and modu
 3. **Interview relentlessly.** Walk down each branch of the design tree, resolving dependencies between decisions one by one, until the user's understanding and yours are identical. Every open question at this point becomes ambiguity in the PRD.
 4. **Sketch the modules.** List the major modules to build or modify, actively looking for deep modules — ones that encapsulate rich behaviour behind a simple, stable interface testable in isolation. Confirm the list with the user, plus which modules they want tests written for.
 5. **Write the PRD.** Render the template in `FORMAT.md` (Problem Statement, Solution, User Stories, Implementation Decisions, Testing Decisions, Out of Scope, Further Notes). Make the user-story list extremely extensive so it covers all aspects of the feature.
-6. **File the bead.** Create the epic with `bd create "<title>" --type epic --priority P1 --body-file -`, piping the rendered PRD to stdin, then run `classify-bead` (as a subagent, per its invocation instructions) to label it AFK or HITL.
+6. **File the bead.** Create the epic with `bd create "<title>" --type epic --priority P1 --body-file -`, piping the rendered PRD to stdin, then run the `classify-bead` classifier (`node <this-skill-dir>/../classify-bead/scripts/classify-bead.mjs <epic-id>`, run from the target project's cwd) to label it AFK or HITL. Escalate to the `classify-bead` subagent only when the classifier reports `escalate: true`.
 
 Run the steps in order. Skip a step only when the user confirms it is unnecessary (e.g. the codebase is already explored).
 
@@ -59,7 +59,7 @@ Run the steps in order. Skip a step only when the user confirms it is unnecessar
 - Use `record-idea` when the idea is not yet ready to build.
 - Use `write-a-ticket` when the spec targets an external tracker rather than a bead.
 - Run `prd-to-tasks` on the filed epic to break the PRD into an executable backlog.
-- Run `classify-bead` on the new epic — the repo labels every new bead AFK or HITL.
+- Run the `classify-bead` classifier on the new epic — the repo labels every new bead AFK or HITL. Its `scripts/` directory sits next to this skill's directory in every harness, so `<this-skill-dir>/../classify-bead/scripts/classify-bead.mjs` resolves it. Escalate to its rubric subagent only when the classifier reports `escalate: true`.
 
 ## Examples
 

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

@@ -1,6 +1,36 @@
-# Additional Examples
+# Examples
 
-Extended before/after pairs for less common style-code patterns.
+Before/after pairs for `style-code`. The most common patterns come first; the rest are
+extended pairs for less frequent cases.
+
+## Common patterns
+
+### Types at boundaries
+
+| Instead of… | Write… |
+|---|---|
+| `function handleRequest(raw: any) { ... }` with no validation | `function handleRequest(raw: unknown): HandlerResult { ... }` validated at the ingress boundary |
+| `const user = JSON.parse(raw)` with unchecked cast | `const user = parseUser(JSON.parse(raw))` validated with `parseUser` at the deserialisation edge |
+
+### Naming
+
+| Instead of… | Write… |
+|---|---|
+| `function process(items) { ... }` | `function resolveOverdueAccounts(accounts: Account[]) { ... }` |
+| `interface Config { ... }` | `interface ExportOptions { ... }` |
+
+### Scoping
+
+| Instead of… | Write… |
+|---|---|
+| One commit fixing a bug, renaming a module, and adding an abstraction | One commit per concern, each reviewable on its own |
+
+### Stateful objects
+
+| Instead of… | Write… |
+|---|---|
+| ```ts // factory closure hiding mutable state function createStepRegistry() { const steps = new Map<string, Step>(); return { register: (name, step) => steps.set(name, step), resolve: (name) => steps.get(name), }; } ``` | ```ts // a class names the state it owns class StepRegistry { #steps = new Map<string, Step>(); register(name: string, step: Step): void { this.#steps.set(name, step); } resolve(name: string): Step \| undefined { return this.#steps.get(name); } } ``` |
+| ```ts class C { private steps = new Map<string, Step>(); } ``` (compile-time only — erases away) | ```ts class C { #steps = new Map<string, Step>(); } ``` (runtime-enforced native private field) |
 
 ## Validation and error handling
 

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

@@ -24,6 +24,7 @@ description: Defines this project's coding style, conventions, and architectural
 - **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.
 - **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.
 
 ## Workflow
@@ -62,6 +63,7 @@ description: Defines this project's coding style, conventions, and architectural
 | "The existing code already does it this way" | Existing patterns may predate this guide. Follow the guide unless changing it would inflate scope beyond the task. |
 | "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. |
 
 ## Cross-skill references
 
@@ -77,27 +79,8 @@ description: Defines this project's coding style, conventions, and architectural
 
 ## Examples
 
-See `REFERENCE.md` for the full set. The most common patterns:
-
-### Types at boundaries
-
-| Instead of… | Write… |
-|---|---|
-| `function handleRequest(raw: any) { ... }` with no validation | `function handleRequest(raw: unknown): HandlerResult { ... }` validated at the ingress boundary |
-| `const user = JSON.parse(raw)` with unchecked cast | `const user = parseUser(JSON.parse(raw))` validated with `parseUser` at the deserialisation edge |
-
-### Naming
-
-| Instead of… | Write… |
-|---|---|
-| `function process(items) { ... }` | `function resolveOverdueAccounts(accounts: Account[]) { ... }` |
-| `interface Config { ... }` | `interface ExportOptions { ... }` |
-
-### Scoping
-
-| Instead of… | Write… |
-|---|---|
-| One commit fixing a bug, renaming a module, and adding an abstraction | One commit per concern, each reviewable on its own |
+See `REFERENCE.md` for the full set — common patterns (types at boundaries, naming,
+scoping) and the stateful-object-vs-factory pair.
 
 ## Verification checklist
 
@@ -109,5 +92,6 @@ See `REFERENCE.md` for the full set. The most common patterns:
 - [ ] Types are co-located with the module that owns them
 - [ ] 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
 - [ ] Tests and docs updated where behaviour changed
 - [ ] Staged changes scanned with `review-security` before committing

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

@@ -1,6 +1,6 @@
 ---
 name: style-tests
-description: Defines this project's test-writing conventions — assertion strategy, mock discipline, and what to test. 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", or deciding "what to test".
+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".
 ---
 
 # Test Style
@@ -9,6 +9,7 @@ description: Defines this project's test-writing conventions — assertion strat
 
 - Writing new tests, reviewing existing tests, or debugging a failing test suite.
 - Deciding between unit, integration, or e2e for a given behaviour.
+- Deciding what test data to build and where.
 - Asked for a "test review", "what should I test", or "is this test well-written".
 
 ## When NOT to use
@@ -16,34 +17,70 @@ description: Defines this project's test-writing conventions — assertion strat
 - The red-green-refactor development loop — use `tdd` instead.
 - Code-level style and conventions — use `style-code`.
 
-## Philosophy / rationale
+## Principles
 
-- **Test behaviour, not implementation.** A passing test should survive a refactor that does not change observable behaviour. If a test fails after a refactor that preserved behaviour, the test was wrong.
-- **Prefer sociable tests over mockery.** Favour integration tests over unit tests. Reserve unit tests for complex functional logic that benefits from tight isolation. Use e2e smoke tests to prove the system hangs together. This is the testing trophy, not the testing pyramid.
-- **Every test has a cost.** Time to write, run, and maintain. Only write a test when its value exceeds its weight. Each behaviour should be covered at least once — ideally only once.
+- **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.
+- **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.
+- **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.
+- **Balanced test trophy.** Unit tests support the integration tests that carry the higher coverage — not a pyramid base.
+- **Tests are independent.** No shared mutable state, no order dependence; each test passes in isolation and in any order.
+- **CI is the only truth.** Locally green never counts.
+- **Don't re-test types or lint.** The compiler and linter already guarantee those; repeating them adds cost for no value.
+- **Testing is not optional.** Every behaviour is tested.
+- **Spec-by-test.** A behaviour is done when its test row is green — the plan's test rows are the spec that gates AFK implementation.
+
+## Content-assertion ban
+
+**No test may assert the static contents of a file** — config, markdown, terraform, or any
+snapshot of static content. Comparing a file against an expected string is a content inventory,
+not behaviour proof; such a test belongs to neither the suite nor the PR.
+
+Instead, assert the behaviour the file participates in: that key data was inserted into a
+template, that a compiler converted a header correctly, or run a smoke test proving deployed
+services are up and ready to serve traffic.
+
+The line is **whether the assertion proves the behaviour under test**, not whether a file is
+read. A parser's golden-output test — where the expected output is a product of the behaviour —
+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.
+- **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.
 
 ## Workflow
 
-1. **Determine the test level.** Can you test this behaviour through the module's public API or interface? Prefer integration-level tests. Reserve unit tests for complex functional logic that genuinely benefits from tight isolation. Use a small number of e2e smoke tests to prove the system hangs together.
+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.
 
-2. **Decide what to mock.** Mock as little as possible. A useful mental model: mock what is **above** the module under test in the dependency tree, not below it. At the integration level, mock only genuine external systems. At e2e, mock almost nothing.
+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.
 
 3. **Write the test structure.** Use a `describe` block per module or function; use `it` per behaviour. Name tests descriptively — the name should communicate what the system does, not how. The relationship between setup, action, and assertion should be self-evident.
 
-4. **Set up data.** Inline what matters — any value that is asserted on or establishes the test condition must appear inline in the test body. Use factory/builder helpers for complex objects with sensible defaults, but any value that changes the test condition must be an explicit override, never buried in a default. Avoid `before`/`after` hooks for shared state; they are acceptable only for expensive, non-observable infrastructure setup (e.g. starting a server or database).
+4. **Set up data.** Inline what matters — any value that is asserted on or establishes the test condition must appear inline in the test body. Reuse via a small configurable factory (partial overrides, sensible defaults) colocated with the tests and named for what it builds — never a shared mutable top-level fixture. Avoid `before`/`after` hooks for shared state; they are acceptable only for expensive, non-observable infrastructure setup (e.g. starting a server or database).
 
-5. **Write targeted assertions.** Prefer `toMatchObject` over asserting every property. Multiple assertions are fine when they all verify the same behaviour. Avoid asserting call counts when asserting call arguments already covers the behaviour.
+5. **Write targeted assertions.** Prefer `toMatchObject` over asserting every property. Multiple assertions are fine when they all verify the same behaviour. Avoid asserting call counts when asserting call arguments already covers the behaviour. Assert behaviour the file participates in, never its static contents.
 
 6. **Review against the checklist below.** Read the test as if you are seeing the codebase for the first time.
 
 ## Red Flags
 
-- **Mocking implementation details.** Hooking into internal module structure ties tests to code shape, not behaviour. Mock the module's public interface instead.
-- **Duplicating type or lint coverage.** Types and linting already provide those guarantees. Repeating them with assertions adds maintenance cost for zero value.
-- **Skipping flaky tests.** A flaky test is a broken test. Fix it or delete it. Skipping normalises unreliability across the suite.
-- **Sharing state via hooks.** Tests must be fully independent. `before`/`after` hooks that set up shared mutable state create order-dependent failures.
-- **`any` or unsafe casts in test code.** Test code is production code. Be strict with types — no `any`, no unsafe casts, no cutting corners.
-- **Skipping a failing test.** A failing test means behaviour broke. Investigate and fix it — do not paper over it.
+| Red flag | Instead |
+|---|---|
+| 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 |
+| Mocking implementation details or internal module structure | Mock the genuine external boundary and test through the public interface |
+| 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 |
+| Sharing state via `before`/`after` hooks | Independent tests; hooks only for expensive, non-observable infrastructure |
+| `any` or unsafe casts in test code | Proper types — test code is production code |
 
 ## Common Rationalizations
 
@@ -54,6 +91,8 @@ description: Defines this project's test-writing conventions — assertion strat
 | "I'll fix the flake later" | No you will not. Fix it now or delete it. |
 | "This test is too small for that pattern" | Small tests benefit from structure too. Consistency beats shortcuts. |
 | "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. |
 
 ## Cross-skill references
 
@@ -61,10 +100,19 @@ description: Defines this project's test-writing conventions — assertion strat
 |---|---|
 | Red-green-refactor development loop | `tdd` |
 | Code-level style and conventions | `style-code` |
+| Plan test rows that gate implementation | `plan` |
 | Secrets and credential scanning | `review-security` |
 
 ## 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… |
@@ -79,11 +127,12 @@ description: Defines this project's test-writing conventions — assertion strat
 | `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 |
 
-### Factory overrides
+### Test data
 
 | Instead of… | Write… |
 |---|---|
-| `const user = createUser();` where the test needs `isAdmin: true` but the default happens to set it | `const user = createUser({ isAdmin: true });` — explicit override visible in the test body |
+| `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
 
@@ -91,6 +140,9 @@ description: Defines this project's test-writing conventions — assertion strat
 - [ ] 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
+- [ ] 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
 - [ ] No `any` or unsafe casts in test code