V48 Gate 5 (spec-impl): Co-locate tests with owners

Move parse/PCC/measure suites to owning packages; core vs
edges layout; agent-generics keeps composition tests only.

Author: geraldarthurdavis

.docs/AGENTS.md

@@ -53,6 +53,25 @@
 - Any inline code comment that cites an accepted QA finding shorthand must always carry the fully-qualified tag `[VERSION]-Gate[N]-F[ID]` (e.g. `V48-Gate3-F26-B`), never a bare `F26-B`-style tag. The same fully-qualified tag must always be discoverable in the specification/QA ledger file(s) (e.g. the finding's own `### V48-Gate3-F26` heading in `.qa/BITCODE_V48_QA.md`), so a reader can go from either direction — code comment to spec entry, or spec entry to every citing code comment — with a single grep. This keeps finding-to-fix traceability intact without requiring the surrounding file or commit to already establish which version/gate is active.
 - Once implementation starts on a gate branch, do not stop at partial progress unless blocked by missing external input or explicit user pause. A gate branch is ready to stop only when the gate's acceptance criteria are implemented, specified, tested, documented, committed, pushed, and pull-requested for closure into the version branch.
 - Treat gate and promotion workflow health as part of gate closure. Gate pull requests into version branches must be green through the **active + draft** gate-quality / canon-quality surface (not prior-era `check-vN-*` suites). Repository-wide living product CI (uapi lint/typecheck/build/Jest) must remain greenable during draft work. Version pull requests into `main` must pass the version promotion workflow, which performs promotion-grade validations and commits the standalone `BITCODE_SPEC.txt` pointer change only after those validations pass.
+- **Test co-location with package ownership (required):** unit tests live in the package that **owns** the unit under test — never under a consumer because it imports the unit. Examples: `@bitcode/parsing` tests under `packages/parsing/`; PrepareConciseContext (PCC) under `packages/generic-generations/failsafes/` even while an LLM-bound factory is still transitional in `@bitcode/agent-generics`. **Implementer exception:** when package B *implements for itself* a base/specific class from a primitive/base in package A, B's specialization tests co-locate in B; A's base tests stay in A. Do not re-host A's base suite under B.
+- **Tests co-locate with the owning package (required):** unit tests live in the package that **owns** the unit under test — not in a consumer, re-export host, or monorepo root. Law:
+  - **Primitive package** → primitive contracts  
+  - **Generic base package** → base contracts (even if an LLM factory is *temporarily hosted* in another package for execution coupling)  
+  - **Implementing package** → only tests that *compose/specialize* the base for that package  
+  - **Product package** → product-only behavior  
+  Anti-pattern: parking `@bitcode/parsing` or MeasureAgent base tests under `@bitcode/agent-generics` because factories re-export or host them. Pilot co-location: `packages/parsing`, `packages/generic-generations/failsafes` (PCC), `packages/generic-measurements/measure-agent`.
+- **Test organization: core vs edges (required for backend packages as they migrate):** package unit tests live under two categories so suites stay readable and useful:
+  | Category | Purpose | Growth |
+  | --- | --- | --- |
+  | **Core** | Extremely clear default / happy-path behavior of the package or subsystem | Stable — grows only when core API/behavior changes |
+  | **Edges** | Exhaustive edge cases, debug flags, failures, bounds, regression pins | Grows as edges are discovered |
+  **Layout (both folder and filename required):**
+  ```text
+  src/__tests__/core/<topic>.core.test.ts
+  src/__tests__/edges/<topic>.edges.test.ts
+  src/__tests__/support/   # shared fixtures only — not a third test class
+  ```
+  Default package `test` runs **both**; `test:core` / `test:edges` are convenience only — **edges are never optional** for commit/CI green. New tests go into the correct folder immediately; do not add flat `__tests__/*.test.ts` on opted-in packages. Pilot exemplars: `@bitcode/agent-generics` (core/edges), `@bitcode/generic-generations-failsafes` (PCC + prepared-context), `@bitcode/parsing`. When reorganizing, also **elevate**: clear descriptors, drop stale/clutter tests, make core files teach the product by reading alone. Human guide: `CONTRIBUTING.md` §8.0.
 - **REQUIRED — never commit until all living CI checks are run locally and completely green.** This is absolute for every commit that may land on a shared branch, gate PR, or production path. **All commits must be green for production deployment** — a red commit is undeployable product debt, not “CI will catch it later.”
   - **Hard ban:** do **not** `git commit` (and do **not** push) while lint, typecheck, build, or required package/Jest suites are red, skipped, or only partially run for the change set.
   - **Before every commit**, the living local CI mirror must be green. It is **enforced by `.githooks/pre-commit`** (`pnpm run hooks:install` once per clone):

.docs/FAMILIARIZATION.md

@@ -514,7 +514,7 @@ Grouped by role. Names are `@bitcode/<name>` unless noted.
 | Package | Responsibility |
 | --- | --- |
 | `execution-generics` | `Execution` state tree, `Executor`, sequential/parallel/pipe |
-| `agent-generics` | Agent = Executor + PTRR composition over generations |
+| `agent-generics` | Agent = Executor + PTRR composition over generations; tests under `__tests__/core|edges` (see CONTRIBUTING §8.0) |
 | `tools-generics` | `Tool` class, factories, MCP bridges |
 | `pipelines-generics` | ExecutionPipeline primitives / stream hooks (no phases; phases are SDIVF-only) |
 | `generic-pipelines-execution-pipeline-sdivf` | SDIVF base loop (`packages/generic-pipelines/execution-pipeline-sdivf`) |

CONTRIBUTING.md

@@ -405,6 +405,52 @@ Connected-services orientation: [`.docs/BITCODE_CONNECTED_SERVICES.md`](.docs/BI
 
 ## 8. Testing, documenting, and proving
 
+### 8.0 Package co-location and core vs edges
+
+**Package co-location (required):** unit tests live in the package that **owns**
+the unit under test. Do not put package A’s suite under package B because B is a
+consumer (e.g. parsing tests belong in `packages/parsing/`, not
+`agent-generics`; PCC belongs in `packages/generic-generations/failsafes/`).
+
+**Implementer exception:** when package B *implements for itself* a base or
+specific class from a primitive/base in A, B’s specialization tests co-locate in
+B. A’s base tests stay in A. Do not re-host A’s base suite under B.
+
+Package tests (backend first; other packages migrate progressively) are also
+split so **core behavior stays obvious** while edge coverage can grow without
+burying it.
+
+| Category | Role | Growth |
+| --- | --- | --- |
+| **Core** | Default / happy-path behavior — a new reader should learn the package from these files alone | Stable unless core API/behavior changes |
+| **Edges** | Exhaustive edges: failures, bounds, debug env, odd inputs, regression pins | Grows continuously |
+
+**Physical law (folder + filename both required):**
+
+```text
+packages/<pkg>/src/__tests__/
+  core/<topic>.core.test.ts
+  edges/<topic>.edges.test.ts
+  support/                    # fixtures only
+```
+
+| Script | Meaning |
+| --- | --- |
+| `pnpm -C packages/<pkg> test` | **Both** core and edges (commit / CI bar) |
+| `test:core` / `test:edges` | Convenience filters — **not** a way to skip edges before commit |
+
+**Heuristic:** if it teaches “how this package works by default,” it is **core**.
+If it pins a corner, flag, failure, or bug, it is **edges**.
+
+When reorganizing a package, also **elevate** tests: clearer `describe`/`it`
+names, remove stale or redundant cases, keep core files short and didactic.
+
+**Pilots:** `@bitcode/agent-generics` (composition only); `@bitcode/parsing`;
+`@bitcode/generic-generations-failsafes` (PCC + prepared-context);
+`@bitcode/generic-measurements-measure-agent` / `absolutes`;
+`@bitcode/parsing`. Other packages adopt the same layout when next touched.
+Full agent law: `.docs/AGENTS.md`.
+
 ### 8.1 REQUIRED: never commit until full local CI is completely green
 
 **Never commit** (and **never push**) until the living required CI surface has

packages/agent-generics/README.md

@@ -3,6 +3,27 @@
 Agent **primitives**: execution, registries, generation-layer factories,
 `factoryAgent` / `factoryQuickAgent`.
 
+## Tests (core vs edges)
+
+| Category | Path | Role |
+| --- | --- | --- |
+| **Core** | `src/__tests__/core/*.core.test.ts` | Default / happy-path package contracts |
+| **Edges** | `src/__tests__/edges/*.edges.test.ts` | Flags, failures, bounds, telemetry corners |
+
+```bash
+pnpm test              # both (required green)
+pnpm test:core         # convenience
+pnpm test:edges        # convenience — not a commit skip
+```
+
+Law: `.docs/AGENTS.md`, `CONTRIBUTING.md` §8.0. Core should teach Thinkings +
+failsafe *composition* + PTRR step tools without reading edges.
+
+**Not here:** PrepareConciseContext (PCC) base pins live in
+`@bitcode/generic-generations-failsafes` (`packages/generic-generations/failsafes/`).
+This package may still *host* the transitional LLM-bound factory and may test how
+agents *use* PCC; it must not re-host the PCC base suite.
+
 ## Hierarchy
 
 ```

packages/agent-generics/jest.config.cjs

@@ -1,8 +1,13 @@
 const path = require('path');
 const { createJestConfig } = require('../../tests/jest.base.cjs');
 
+// Core vs edges: see .docs/AGENTS.md and CONTRIBUTING §8.0.
+// testMatch: core and edges globs only; both always required green.
 module.exports = createJestConfig(__dirname, {
-  testMatch: ['**/__tests__/**/*.test.(ts|tsx)'],
+  testMatch: [
+    '**/__tests__/core/**/*.core.test.(ts|tsx)',
+    '**/__tests__/edges/**/*.edges.test.(ts|tsx)',
+  ],
   moduleNameMapper: {
     '^@bitcode/logger$': path.join(__dirname, '../logger/src/logger.ts'),
     // Deep subpaths not covered by package root map
@@ -14,5 +19,5 @@ module.exports = createJestConfig(__dirname, {
     '^@bitcode/generic-artifacts-compose$': path.join(__dirname, '../generic-artifacts/compose/src/index.ts'),
     '^@bitcode/parsing$': path.join(__dirname, '../parsing/src/parsing.ts'),
   },
-  collectCoverageFrom: ['src/**/*.{ts,tsx}', '!src/**/*.d.ts'],
+  collectCoverageFrom: ['src/**/*.{ts,tsx}', '!src/**/*.d.ts', '!src/**/__tests__/**'],
 });

packages/agent-generics/package.json

@@ -8,6 +8,8 @@
     "build": "tsc --noEmit",
     "typecheck": "node ../../node_modules/typescript/bin/tsc -p tsconfig.typecheck.json --noEmit",
     "test": "jest",
+    "test:core": "jest --testPathPattern=__tests__/core/",
+    "test:edges": "jest --testPathPattern=__tests__/edges/",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
     "type-check": "pnpm run typecheck"

…rc/__tests__/agent-llms-registry.test.ts …__/core/agent-llms-registry.core.test.tspackages/agent-generics/src/__tests__/agent-llms-registry.test.ts renamed to packages/agent-generics/src/__tests__/core/agent-llms-registry.core.test.ts packages/agent-generics/src/__tests__/agent-llms-registry.test.ts renamed to packages/agent-generics/src/__tests__/core/agent-llms-registry.core.test.ts

@@ -47,8 +47,8 @@ jest.mock('@bitcode/generic-llms', () => {
 });
 
 import { Execution } from '@bitcode/execution-generics';
-import { AgentExecution } from '../execution/AgentExecution';
-import { AgentLLMsRegistry } from '../execution/AgentLLMsRegistry';
+import { AgentExecution } from '../../execution/AgentExecution';
+import { AgentLLMsRegistry } from '../../execution/AgentLLMsRegistry';
 
 const ENV_KEYS = [
   'BITCODE_LLM_PROVIDER',

…s__/failsafe-generation-sequence.test.ts …ailsafe-generation-sequence.core.test.tspackages/agent-generics/src/__tests__/failsafe-generation-sequence.test.ts renamed to packages/agent-generics/src/__tests__/core/failsafe-generation-sequence.core.test.ts packages/agent-generics/src/__tests__/failsafe-generation-sequence.test.ts renamed to packages/agent-generics/src/__tests__/core/failsafe-generation-sequence.core.test.ts

@@ -1,16 +1,16 @@
 // @ts-nocheck
 /**
- * Pins for createFailsafeGenerationSequence — the Failsafes sequence is
- * selection (PCC) -> task (CS, xchunks when triggered) -> repair-only (SC):
- * - PCC always runs ONE selection Thinkings (key-selection schema, keys only)
- * - CS runs ONE task Thinkings when the composed request fits
- * - SC adds ZERO generations when the task output is schema-complete
+ * CORE — FailsafeGenerationSequence default success path.
+ *
+ * Teaches: selection (PCC) → task (ChunkThenSum) → repair-only (Stitch);
+ * PCC selection Thinkings; one task Thinkings when request fits; Stitch adds
+ * zero generations when task output is schema-complete.
  */
 import { z } from 'zod';
 import { Execution } from '@bitcode/execution-generics';
-import { StepExecution } from '../execution';
-import { createFailsafeGenerationSequence } from '../steps/failsafe-sequence';
-import { factoryChunkThenSum, factoryStitchUntilComplete } from '../generations/llm-bound-factories';
+import { StepExecution } from '../../execution';
+import { createFailsafeGenerationSequence } from '../../steps/failsafe-sequence';
+import { factoryChunkThenSum, factoryStitchUntilComplete } from '../../generations/llm-bound-factories';
 
 const outputSchema = z.object({ title: z.string(), score: z.number() });
 
@@ -73,8 +73,8 @@ afterEach(() => {
   delete process.env.BITCODE_DEBUG_SKIP_THINKINGS_JUDGE_AND_STRUCTURED_OUTPUT;
 });
 
-describe('createFailsafeGenerationSequence composition', () => {
-  it('runs selection -> task -> repair-only and returns the {context, output, finalOutput} envelope', async () => {
+describe('CORE: FailsafeGenerationSequence default composition', () => {
+  it('runs selection → task → repair-only and returns {context, output, finalOutput}', async () => {
     const counter = { calls: 0 };
     const { root, step } = makeRootAndStep(makeScriptedLLM(counter));
     const sequence = createFailsafeGenerationSequence({ outputSchema });

…lsafe-sequence-order-and-failure.test.ts …ts__/core/failsafe-sequence.core.test.tspackages/agent-generics/src/__tests__/failsafe-sequence-order-and-failure.test.ts renamed to packages/agent-generics/src/__tests__/core/failsafe-sequence.core.test.ts packages/agent-generics/src/__tests__/failsafe-sequence-order-and-failure.test.ts renamed to packages/agent-generics/src/__tests__/core/failsafe-sequence.core.test.ts

@@ -1,15 +1,17 @@
 // @ts-nocheck
 /**
- * Pins for createFailsafeGenerationSequence:
- * - composition ORDER: prepare (seq-0) -> chunk (seq-1) -> stitch (seq-2)
- * - a rejecting LLM (e.g. the callLlmWithTimeout 'timed out after Nms'
- *   rejection) propagates through the whole sequence as a clean failure —
- *   no retry, no hang, no partial envelope.
+ * CORE — FailsafeGenerationSequence structure and hard failure propagation.
+ *
+ * Teaches: prepare (seq-0) → chunk (seq-1) → stitch (seq-2); a rejecting LLM
+ * fails the whole sequence cleanly (no hang / silent retry).
+ *
+ * Detailed failsafe call counts and debug filters: failsafe-generation-sequence
+ * and edges as applicable.
  */
 import { z } from 'zod';
 import { Execution } from '@bitcode/execution-generics';
-import { StepExecution } from '../execution';
-import { createFailsafeGenerationSequence } from '../steps/failsafe-sequence';
+import { StepExecution } from '../../execution';
+import { createFailsafeGenerationSequence } from '../../steps/failsafe-sequence';
 
 const outputSchema = z.object({ title: z.string(), score: z.number() });
 
@@ -43,8 +45,8 @@ function collectNodes(node: any, out: any[] = []): any[] {
   return out;
 }
 
-describe('createFailsafeGenerationSequence composition order', () => {
-  it('hosts prepare under seq-0, chunk under seq-1 and stitch under seq-2', async () => {
+describe('CORE: FailsafeGenerationSequence composition order', () => {
+  it('hosts prepare under seq-0, chunk under seq-1, and stitch under seq-2', async () => {
     const llm = async (input: any) => ({
       content: scriptedContent(input),
       usage: { totalTokens: 5 },
@@ -67,8 +69,8 @@ describe('createFailsafeGenerationSequence composition order', () => {
   });
 });
 
-describe('createFailsafeGenerationSequence failure propagation', () => {
-  it('surfaces an LLM timeout rejection from the very first call — exactly one invocation, no retry', async () => {
+describe('CORE: FailsafeGenerationSequence failure propagation', () => {
+  it('surfaces an LLM timeout from the first call — one invocation, no silent retry', async () => {
     const counter = { calls: 0 };
     const llm = async () => {
       counter.calls++;

…sts__/prepared-task-user-payload.test.ts …/prepared-task-user-payload.core.test.tspackages/agent-generics/src/__tests__/prepared-task-user-payload.test.ts renamed to packages/agent-generics/src/__tests__/core/prepared-task-user-payload.core.test.ts packages/agent-generics/src/__tests__/prepared-task-user-payload.test.ts renamed to packages/agent-generics/src/__tests__/core/prepared-task-user-payload.core.test.ts

@@ -6,15 +6,15 @@
  */
 import { z } from 'zod';
 import { Execution } from '@bitcode/execution-generics';
-import { StepExecution } from '../execution';
-import { createFailsafeGenerationSequence } from '../steps/failsafe-sequence';
+import { StepExecution } from '../../execution';
+import { createFailsafeGenerationSequence } from '../../steps/failsafe-sequence';
 import {
   factoryChunkThenSum,
   factoryPrepareConciseContext,
   factoryReason,
   isPreparedTaskInput,
   buildPreparedTaskLlmPayload,
-} from '../generations/llm-bound-factories';
+} from '../../generations/llm-bound-factories';
 
 function makeRootAndStep(llm?: (input: any) => Promise<any>) {
   const root = new Execution('agent-root') as any;