@jaybeeuu/agent-cortex 1.40.0 → 1.41.1

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 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
@@ -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,81 @@ 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 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.
+- **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
+
+- **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 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. 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.** 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. 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 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, 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
 
@@ -54,6 +102,9 @@ 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. |
+| "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
 
@@ -61,37 +112,37 @@ 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
 
-### 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 |
-
-### Factory overrides
-
-| 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 |
 
 ## 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
-- [ ] No skipped or commented-out tests
-- [ ] No flaky tests — all deterministic
+- [ ] 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
+- [ ] Vital data is visible inline; incidental data is defaulted in a factory
+- [ ] Reused test data uses a small configurable factory rather than repeated full literals
+- [ ] No skipped, focused, or commented-out tests
+- [ ] No flaky tests — all deterministic, no sleeps or real clocks
+- [ ] Every async interaction is awaited
 - [ ] No `any` or unsafe casts in test code
 - [ ] No duplication of type or linting coverage

package/skills/workflow/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 });
     }