@jaybeeuu/agent-cortex 1.40.0 → 1.41.0

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

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

@@ -24,7 +24,7 @@ Stage beads (`stage:code`, `stage:verify`, `stage:review`, `stage:document`, `st
 
 1. Run `bd prime` and hold the output; subagents can run it themselves if they need context.
 2. If no bead was specified, run `bd ready` and ask the user which to work on.
-3. Claim the bead with `bd update <id> --claim` — the bead, not the prompt, is the source of truth.
+3. Claim the bead with `bd update <id> --claim` — the bead, not the prompt, is the source of truth. Append a stage-start note immediately (see _Milestone Notes_).
 4. Read the bead's `stage:*` label — it names the stage to execute.
 5. Load the universal stage-runner prompt (`skills/workflow/run-pipeline-stage/prompts/stage-runner.md`), populate `<stage>`, and read the matching playbook (`skills/workflow/run-pipeline-stage/playbooks/<stage>.md`) for stage-specific rules.
 6. Tag the stage and regenerate the progress doc so pairing sessions stay current:
@@ -88,6 +88,16 @@ Log stage starts and completes, test/lint/build/security results, blockers, and
 mkdir -p .agent-cortex/ralph && echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [bead-id] [stage] message" >> .agent-cortex/ralph/ralph-bead-id.log
 ```
 
+## Milestone Notes
+
+The bead's notes are the recovery contract: if a session dies mid-stage, a fresh agent must resume from `bd show <id>` alone. Append a short checkpoint at stage start and at each milestone — never on every tool call.
+
+```bash
+bd update <id> --append-notes "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [<stage>] <what changed / what's next>"
+```
+
+`--append-notes` preserves the trail; plain `--notes` overwrites it. Record the start (stage, worktree, first action), milestones (completed chunks, tests green, files changed), decisions and rejected options, blocks, and discoveries. One or two lines per entry — a scan-friendly checkpoint trail, not a transcript. No new scratch files; beads stay the single source of truth.
+
 ## Report Format
 
 Every subagent prompt must end with the REPORT instruction:
@@ -113,6 +123,7 @@ Subagents report facts — do not ask them to suggest or predict the next step.
 - Composing a subagent prompt without the REPORT contract — the output cannot be routed.
 - Creating a feedback bead and then dispatching anyway — bypasses the fix-round accounting and parent-child dependency graph.
 - Skipping the playbook "because the stage is simple" — playbooks carry the per-stage discipline the pipeline relies on.
+- Leaving bead notes to the end of the stage — a session that dies mid-stage then loses the whole trail.
 
 ## Common Rationalizations
 
@@ -145,5 +156,6 @@ Subagents report facts — do not ask them to suggest or predict the next step.
 - [ ] Correct playbook read and followed for the stage; stage skills invoked where the playbook says.
 - [ ] Composed prompt ends with the complete REPORT contract block.
 - [ ] Progress log lines written for every stage transition and key result.
+- [ ] Milestone notes appended at stage start and each milestone with `--append-notes` (not `--notes`).
 - [ ] REPORT routed per the Dispatch Rules — next stage, feedback bead, or `bd close <id>`.
 - [ ] Feedback beads carry the full BLOCKING_ISSUES content and the parent-child dependency.

package/skills/workflow/run-pipeline-stage/prompts/stage-runner.md

@@ -14,6 +14,18 @@ Run `bd prime` if you need project-level context (conventions, tech stack, goals
 ## Progress log
 Write progress to: `.agent-cortex/ralph/ralph-<bead-id>.log`
 
+## Milestone notes
+The bead's notes are the recovery contract — a fresh session must be able to resume from
+`bd show <id>` alone. Append a short checkpoint before starting and at each milestone:
+
+```bash
+bd update <id> --append-notes "[<ISO-timestamp>] [<stage>] <what changed / what's next>"
+```
+
+Use `--append-notes` — plain `--notes` overwrites the trail. Record start, milestones, decisions
+(with rejected options), blocks, and discoveries. One or two lines per entry: a checkpoint trail,
+not a transcript. The REPORT below remains the authoritative stage outcome.
+
 ## Instructions
 1. Read and follow the playbook file listed above.
 2. Treat the bead as the source-of-truth specification (not a prompt script).

package/test/classify-bead.test.mjs

@@ -0,0 +1,277 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { access } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { resolveClassification, auditBeads, runCli } from '../skills/planning/classify-bead/scripts/classify-bead.mjs';
+
+const testDir = dirname(fileURLToPath(import.meta.url));
+
+describe('resolveClassification', () => {
+  it('resolves AFK from an existing implementation-type:afk label', () => {
+    const result = resolveClassification({
+      labels: ['implementation-type:afk'],
+      description: 'Do a thing.',
+    });
+
+    assert.equal(result.classification, 'afk');
+    assert.equal(result.source, 'label');
+    assert.equal(result.escalate, false);
+  });
+
+  it('resolves HITL from an existing implementation-type:hitl label', () => {
+    const result = resolveClassification({
+      labels: ['implementation-type:hitl'],
+      description: 'Provision the staging cluster.',
+    });
+
+    assert.equal(result.classification, 'hitl');
+    assert.equal(result.source, 'label');
+    assert.equal(result.escalate, false);
+  });
+
+  it('prefers AFK when both implementation-type labels are present', () => {
+    const result = resolveClassification({
+      labels: ['implementation-type:hitl', 'implementation-type:afk'],
+      description: 'Ambiguous bead.',
+    });
+
+    assert.equal(result.classification, 'afk');
+  });
+
+  it('resolves AFK from a legacy ## Type block when no label is present', () => {
+    const result = resolveClassification({
+      labels: [],
+      description: 'Add the export API.\n\n## Type\n\nAFK\n\n## Design\n\nSomething.',
+    });
+
+    assert.equal(result.classification, 'afk');
+    assert.equal(result.source, 'type-field');
+    assert.equal(result.escalate, false);
+  });
+
+  it('resolves HITL from a case-insensitive ## type block', () => {
+    const result = resolveClassification({
+      labels: [],
+      description: 'Rotate the signing key.\n\n## type\n\nhitl',
+    });
+
+    assert.equal(result.classification, 'hitl');
+    assert.equal(result.source, 'type-field');
+  });
+
+  it('resolves an inline ## Type: AFK field', () => {
+    const result = resolveClassification({
+      labels: [],
+      description: 'Tidy the logs.\n\n## Type: AFK\n',
+    });
+
+    assert.equal(result.classification, 'afk');
+    assert.equal(result.source, 'type-field');
+  });
+
+  it('prefers the label over a conflicting ## Type field', () => {
+    const result = resolveClassification({
+      labels: ['implementation-type:afk'],
+      description: 'Conflicting bead.\n\n## Type\n\nHITL',
+    });
+
+    assert.equal(result.classification, 'afk');
+    assert.equal(result.source, 'label');
+  });
+
+  it('escalates when the ## Type field carries no AFK/HITL value', () => {
+    const result = resolveClassification({
+      labels: [],
+      description: 'A feature.\n\n## Type\n\nFeature',
+    });
+
+    assert.equal(result.classification, null);
+    assert.equal(result.escalate, true);
+  });
+
+  it('resolves AFK from explicit no-human phrasing', () => {
+    const result = resolveClassification({
+      labels: [],
+      description: 'Rename the column; no human review required.',
+    });
+
+    assert.equal(result.classification, 'afk');
+    assert.equal(result.source, 'heuristic');
+  });
+
+  it('resolves HITL from an explicit human sign-off requirement', () => {
+    const result = resolveClassification({
+      labels: [],
+      description: 'Ship the redesign once it has stakeholder sign-off.',
+    });
+
+    assert.equal(result.classification, 'hitl');
+    assert.equal(result.source, 'heuristic');
+  });
+
+  it('lets a HITL signal outrank a generic automated-tests signal', () => {
+    const result = resolveClassification({
+      labels: [],
+      description: 'Has automated tests, but the release requires human approval.',
+    });
+
+    assert.equal(result.classification, 'hitl');
+  });
+
+  it('resolves AFK when the acceptance criteria are automated tests', () => {
+    const result = resolveClassification({
+      labels: [],
+      description: 'Cover the parser with automated tests.',
+    });
+
+    assert.equal(result.classification, 'afk');
+  });
+
+  it('escalates when no deterministic signal is present', () => {
+    const result = resolveClassification({
+      labels: [],
+      description: 'Rework the billing domain model to support proration.',
+    });
+
+    assert.equal(result.classification, null);
+    assert.equal(result.source, null);
+    assert.equal(result.escalate, true);
+  });
+
+  it('prefers the ## Type field over heuristic signals', () => {
+    const result = resolveClassification({
+      labels: [],
+      description: '## Type\n\nHITL\n\nCover it with automated tests.',
+    });
+
+    assert.equal(result.classification, 'hitl');
+    assert.equal(result.source, 'type-field');
+  });
+});
+
+describe('auditBeads', () => {
+  const sample = [
+    { labels: ['implementation-type:afk'], description: '' },
+    { labels: ['implementation-type:hitl'], description: '' },
+    { labels: [], description: '## Type\n\nAFK' },
+    { labels: [], description: 'Rework the billing domain model.' },
+  ];
+
+  it('counts each resolution source and the deterministic share', () => {
+    const summary = auditBeads(sample);
+
+    assert.deepEqual(summary.bySource, { label: 2, typeField: 1, heuristic: 0, rubric: 1 });
+    assert.equal(summary.deterministic, 3);
+    assert.equal(summary.needsRubric, 1);
+    assert.equal(summary.deterministicRatio, 0.75);
+  });
+
+  it('reports a zero ratio for an empty sample', () => {
+    assert.equal(auditBeads([]).deterministicRatio, 0);
+  });
+});
+
+describe('runCli', () => {
+  function makeExec(beads) {
+    const calls = [];
+    const exec = async (args) => {
+      calls.push(args);
+      if (args[0] === 'show') return JSON.stringify(beads);
+      if (args[0] === 'list') return JSON.stringify(beads);
+      if (args[0] === 'tag') return '';
+      throw new Error(`unexpected bd call: ${args.join(' ')}`);
+    };
+    return { exec, calls };
+  }
+
+  function capture() {
+    let output = '';
+    return { write: (chunk) => { output += chunk; }, read: () => JSON.parse(output) };
+  }
+
+  it('applies the label when the ## Type field resolves the classification', async () => {
+    const { exec, calls } = makeExec([{ id: 'proj-1', labels: [], description: '## Type\n\nAFK' }]);
+    const out = capture();
+
+    const code = await runCli({ argv: ['proj-1'], exec, write: out.write });
+
+    assert.equal(code, 0);
+    assert.deepEqual(calls, [
+      ['show', 'proj-1', '--json'],
+      ['tag', 'proj-1', 'implementation-type:afk'],
+    ]);
+    assert.deepEqual(out.read(), {
+      id: 'proj-1',
+      classification: 'afk',
+      source: 'type-field',
+      reason: 'legacy ## Type field declares AFK',
+      escalate: false,
+      applied: true,
+      label: 'implementation-type:afk',
+    });
+  });
+
+  it('does not re-apply a label that is already present', async () => {
+    const { exec, calls } = makeExec([{ id: 'proj-2', labels: ['implementation-type:hitl'], description: '' }]);
+    const out = capture();
+
+    const code = await runCli({ argv: ['proj-2'], exec, write: out.write });
+
+    assert.equal(code, 0);
+    assert.deepEqual(calls, [['show', 'proj-2', '--json']]);
+    assert.equal(out.read().applied, false);
+    assert.equal(out.read().classification, 'hitl');
+  });
+
+  it('escalates without applying a label when no deterministic signal is present', async () => {
+    const { exec, calls } = makeExec([{ id: 'proj-3', labels: [], description: 'Rework the billing model.' }]);
+    const out = capture();
+
+    const code = await runCli({ argv: ['proj-3'], exec, write: out.write });
+
+    assert.equal(code, 0);
+    assert.deepEqual(calls, [['show', 'proj-3', '--json']]);
+    assert.equal(out.read().escalate, true);
+    assert.equal(out.read().label, null);
+  });
+
+  it('resolves without applying a label under --dry-run', async () => {
+    const { exec, calls } = makeExec([{ id: 'proj-4', labels: [], description: '## Type\n\nHITL' }]);
+    const out = capture();
+
+    const code = await runCli({ argv: ['proj-4', '--dry-run'], exec, write: out.write });
+
+    assert.equal(code, 0);
+    assert.deepEqual(calls, [['show', 'proj-4', '--json']]);
+    assert.equal(out.read().classification, 'hitl');
+    assert.equal(out.read().applied, false);
+  });
+
+  it('reports the deterministic split in --audit mode', async () => {
+    const beads = [
+      { labels: ['implementation-type:afk'], description: '' },
+      { labels: [], description: 'Rework the billing model.' },
+    ];
+    const { exec, calls } = makeExec(beads);
+    const out = capture();
+
+    const code = await runCli({ argv: ['--audit', '--limit', '2'], exec, write: out.write });
+
+    assert.equal(code, 0);
+    assert.deepEqual(calls, [['list', '--all', '--json', '--limit', '2', '--sort', 'created']]);
+    assert.equal(out.read().deterministic, 1);
+    assert.equal(out.read().needsRubric, 1);
+  });
+});
+
+describe('classifier wiring', () => {
+  it('exposes the classifier at the sibling path callers are told to use', async () => {
+    // create-task/SKILL.md resolves <skill-scripts>/../../classify-bead/scripts/classify-bead.mjs.
+    const createTaskScripts = resolve(testDir, '../skills/planning/create-task/scripts');
+    const classifier = resolve(createTaskScripts, '../../classify-bead/scripts/classify-bead.mjs');
+
+    await assert.doesNotReject(access(classifier));
+  });
+});

package/test/cli.test.mjs

@@ -20,15 +20,21 @@ async function pathExists(p) {
   }
 }
 
-function runCli(args) {
+/** Run the CLI; optionally pass a custom env (e.g. a fake HOME). */
+function runCli(args, env = {}) {
   return new Promise((resolve) => {
-    execFile(process.execPath, [CLI_PATH, ...args], (error, stdout, stderr) => {
-      resolve({
-        exitCode: error ? error.code ?? 1 : 0,
-        stdout: stdout,
-        stderr: stderr,
-      });
-    });
+    execFile(
+      process.execPath,
+      [CLI_PATH, ...args],
+      { env: { ...process.env, ...env } },
+      (error, stdout, stderr) => {
+        resolve({
+          exitCode: error ? error.code ?? 1 : 0,
+          stdout: stdout,
+          stderr: stderr,
+        });
+      },
+    );
   });
 }
 
@@ -117,6 +123,11 @@ describe("parseArgs", () => {
     assert.deepStrictEqual(result, { command: "install", harness: "pi", pluginRoot: "/tmp/plugin" });
   });
 
+  it("parses --no-provision for install", async () => {
+    const result = parseArgs(["install", "pi", "--no-provision"]);
+    assert.deepStrictEqual(result, { command: "install", harness: "pi", noProvision: true });
+  });
+
   it("combines multiple install options", async () => {
     const result = parseArgs(["install", "pi", "--dry-run", "--output", "/tmp/out", "--plugin-root", "/tmp/plugin"]);
     assert.deepStrictEqual(result, {
@@ -214,8 +225,21 @@ describe("CLI integration", () => {
     assert.ok(stdout.includes("claude"));
   });
 
-  it("exits 0 for install pi", async () => {
-    const { exitCode, stdout } = await runCli(["install", "pi"]);
+  it("exits 0 for install pi (into a temp output dir)", async () => {
+    const outDir = await mkdtemp(join(tmpdir(), "cli-pi-default-"));
+    try {
+      const { exitCode, stdout } = await runCli(["install", "pi", "--output", outDir]);
+      assert.equal(exitCode, 0);
+      assert.ok(stdout.includes("pi"));
+    } finally {
+      await rm(outDir, { recursive: true, force: true });
+    }
+  });
+
+  it("exits 0 for install pi --no-provision", async () => {
+    // --no-provision keeps this hermetic: without it the CLI would install the
+    // third-party packages declared in the package manifest.
+    const { exitCode, stdout } = await runCli(["install", "pi", "--no-provision"]);
     assert.equal(exitCode, 0);
     assert.ok(stdout.includes("pi"));
   });
@@ -245,7 +269,24 @@ describe("CLI integration", () => {
     assert.ok(stdout.includes("dry-run"));
   });
 
-  it("exits 0 for install pi --output <tmp> and writes agent files", async () => {
+  it("install pi --dry-run lists the pi packages it would install", async () => {
+    // Fake HOME keeps the pi user scope hermetic: both manifest packages are
+    // missing, so the plan contains exactly the declared sources.
+    const fakeHome = await mkdtemp(join(tmpdir(), "cli-pi-home-"));
+    try {
+      const { exitCode, stdout } = await runCli(["install", "pi", "--dry-run"], { HOME: fakeHome });
+      assert.equal(exitCode, 0);
+      assert.ok(stdout.includes("Would install pi package npm:pi-questions"), "planned pi-questions shown");
+      assert.ok(
+        stdout.includes("Would install pi package npm:pi-web-access@0.10.7"),
+        "planned pi-web-access shown",
+      );
+    } finally {
+      await rm(fakeHome, { recursive: true, force: true });
+    }
+  });
+
+  it("exits 0 for install pi --output <tmp> and writes agent and config files", async () => {
     const outDir = await mkdtemp(join(tmpdir(), "cli-pi-install-"));
     try {
       const { exitCode, stdout } = await runCli(["install", "pi", "--output", outDir]);
@@ -253,6 +294,9 @@ describe("CLI integration", () => {
       assert.ok(stdout.includes("ralph.agent.md"));
       const ralph = await readFile(join(outDir, "agents", "ralph.agent.md"), "utf-8");
       assert.ok(ralph.includes("agent-cortex:ralph"));
+      const settings = JSON.parse(await readFile(join(outDir, "settings.json"), "utf-8"));
+      assert.ok(Array.isArray(settings.packages));
+      assert.ok(await readFile(join(outDir, "keybindings.json"), "utf-8"));
     } finally {
       await rm(outDir, { recursive: true, force: true });
     }