V48 (specification-implementation): FailsafeGeneration / ThinkingsGeneration hierarchy names

Retire legacy SubStep/Meta vocabulary for Generation-within-Step:
- FailsafeMetaSubStep → FailsafeGeneration (enum + BC alias)
- GenerationSubMetaSubStep → ThinkingsGeneration (enum + BC alias)
- SubStepExecution → GenerationExecution; Failsafe/Thinkings execution subclasses
- FailsafeGenerationPrompt / ThinkingsGenerationPrompt (prompt BC aliases)
- PTRRStepGenerationArchitecture; docs (FAMILIARIZATION, TERMINOLOGY, NOTES)

Hierarchy: Generation → FailsafeGeneration | ThinkingsGeneration → PTRRAgent steps.

Author: geraldarthurdavis

BITCODE_SPEC_V48_NOTES.md

@@ -1618,6 +1618,21 @@ not provider packages.
 HostKind `local` replaces `inline` (BITCODE_PIPELINE_HOST; `inline` accepted as alias).
 Spec G3-4 tables updated to LocalHost / hostKind `local`.
 
+## Generation vocabulary: FailsafeGeneration / ThinkingsGeneration (Garrett, 2026-07-13)
+
+Legacy `FailsafeMetaSubStep` / `GenerationSubMetaSubStep` / `SubStep` naming retired
+for active vocabulary. SubStep was the old term for Generation within a PTRR step;
+Meta is not a term.
+
+```
+Generation (primitive)
+  → FailsafeGeneration   # PCC / ChunkThenSum / Stitch kinds
+  → ThinkingsGeneration  # Reason → Judge → StructuredOutput kinds
+```
+
+BC aliases remain on enums and execution classes. Prefer hierarchy names in new code.
+Architecture interface: `PTRRStepGenerationArchitecture`.
+
 ## Host vocabulary: no "Harness" for Host (Garrett, 2026-07-13)
 
 Product/runtime Host-domain identifiers no longer use the word **Harness**

FAMILIARIZATION.md

@@ -139,43 +139,53 @@ Package paths: `packages/measurement-generics/`, `packages/generic-measurements/
 Hierarchy names: `Measurement` → `AbsolutesMeasureAgent` →
 `SynthesizeAssetPacksAbsolutesMeasureAgent`.
 
-### 3.1.2 Generations (failsafes + thinkings)
+### 3.1.2 Generations (FailsafeGeneration + ThinkingsGeneration)
 
 ```
-@bitcode/generation-generics              Generation type + failsafe/thinkings enums
+Generation                                    # primitive (@bitcode/generation-generics)
         ↑
-@bitcode/generic-generations-failsafes    failsafes/ — prepared-context types + base
-@bitcode/generic-generations-thinkings    thinkings/ — Reason→Judge→StructuredOutput base
+FailsafeGeneration                            # base kinds: PCC / ChunkThenSum / Stitch
+ThinkingsGeneration                           # base kinds: Reason → Judge → StructuredOutput
         ↑
-@bitcode/agent-generics                   Agent primitive (factoryAgent, factoryQuickAgent, substeps)
+@bitcode/generic-generations-failsafes        failsafes/ — prepared-context + Failsafe surface
+@bitcode/generic-generations-thinkings        thinkings/ — Thinkings vocabulary surface
         ↑
-@bitcode/generic-agents-ptrr              PTRRAgent base (Plan→Try→Refine→Retry)
+@bitcode/agent-generics                       Agent primitive; LLM-bound generation factories
         ↑
-@bitcode/generic-agent-* / product agents specialized prompts/tools (no PTRR reimplementation)
+@bitcode/generic-agents-ptrr                  PTRRAgent steps compose Failsafe + Thinkings
+        ↑
+product agents                                specialized prompts/tools (no reimplementation)
 ```
 
 Package paths: `packages/generic-generations/{failsafes,thinkings}/`,
 `packages/generic-agents/PTRR/`.
 
 **PTRR** (Plan / Try / Refine / Retry) is the base Agent step model
-(`@bitcode/generic-agents-ptrr`). Each step runs a **Failsafes** sequence:
+(`@bitcode/generic-agents-ptrr`). Each step runs **FailsafeGeneration** kinds:
 
 1. **PrepareConciseContext** — select execution-state *keys* (not values)
 2. **ChunkThenSum** — task generation; chunk only if request too large
 3. **StitchUntilComplete** — repair schema-incomplete/truncated output
 
-Each failsafe’s generation is **Thinkings**: Reason → Judge → StructuredOutput.
+Each FailsafeGeneration runs **ThinkingsGeneration**: Reason → Judge → StructuredOutput.
+Tools run after failsafes (postprocess).
+
+**Legacy naming (BC only):** `FailsafeMetaSubStep`, `GenerationSubMetaSubStep`, `SubStep` —
+SubStep was the old term for Generation within a Step; Meta is not a term. Prefer
+`FailsafeGeneration` / `ThinkingsGeneration`.
 
 Prepared-context types (`PreparedContext`, `prepareConciseContext`, …) live with
-**failsafes** (`@bitcode/generic-generations-failsafes`), not a free-floating
-context domain. `@bitcode/context` retains only process-global `GlobalContext`
-(+ BC re-exports of failsafe prepared-context helpers).
+**failsafes** (`@bitcode/generic-generations-failsafes`). `@bitcode/context` retains
+only process-global `GlobalContext` (+ BC re-exports of failsafe helpers).
 
 LLM-bound failsafe/thinkings **factories** still execute via `AgentExecution`
 inside `agent-generics` until inverted onto pure Execution + LLM registry.
 
-| Layer | Type name | Factory |
+| Layer | Type name | Factory / kinds |
 | --- | --- | --- |
+| Primitive | `Generation` | typed Executor |
+| Base | `FailsafeGeneration` | PCC / ChunkThenSum / Stitch kinds |
+| Base | `ThinkingsGeneration` | Reason / Judge / StructuredOutput kinds |
 | Primitive | `Agent` | `factoryAgent`, `factoryQuickAgent` |
 | Base + primitive | `PTRRAgent` | `factoryPTRRAgent` (`factoryAgentWithPTRR` BC) |
 | Specific | product agents | specialized configs over `factoryPTRRAgent` |
@@ -736,8 +746,8 @@ Land the edit with the structural change (same commit or accompanying
 | Execution | Accumulating hierarchical state for a run |
 | PhaseDelegator | Pipeline phase that resolves/runs agents |
 | PTRR | Plan-Try-Refine-Retry agent steps |
-| Thinkings | Reason → Judge → StructuredOutput generations |
-| Failsafe | PCC / ChunkThenSum / Stitch context&size&schema guards |
+| ThinkingsGeneration | Reason → Judge → StructuredOutput (children of each FailsafeGeneration) |
+| FailsafeGeneration | PCC / ChunkThenSum / Stitch (parents within a PTRR step) |
 | Lens / mode | deposit vs read variance on shared SynthesizeAssetPacks |
 | Host | Decoupled pipeline host (inline or sandbox) |
 | Journal | BTD ledger rows / reconciliation |

internal-docs/TERMINOLOGY.md

@@ -8,202 +8,89 @@ This guide provides the precise terminology used in the Bitcode codebase, verifi
 
 ### PTRR Pattern (Current Implementation)
 
-**Source**: `/packages/agent-generics/src/types.ts`
+**Source**: `/packages/agent-generics/src/types.ts`, `/packages/generic-agents/PTRR`
 
 The codebase uses `AgentVariationStep` enum:
 ```typescript
 export enum AgentVariationStep {
-  PLAN = 'plan',      // Failsafe: understand and strategize
-  TRY = 'try',        // Generation: initial attempt
-  REFINE = 'refine',  // Generation: improve results
-  RETRY = 'retry'     // Failsafe: guaranteed completion
+  PLAN = 'plan',
+  TRY = 'try',
+  REFINE = 'refine',
+  RETRY = 'retry'
 }
 ```
 
-### Sub-Step Architecture
+Preferred factory: `factoryPTRRAgent` (`factoryAgentWithPTRR` is BC).
 
-**CRITICAL**: There are **EXACTLY 7 substeps per step** according to `PTRRSubStepArchitecture` interface.
+### Generation hierarchy within a PTRR step
 
-#### Failsafe Meta Sub-Steps (3)
-**Source**: `/packages/agent-generics/src/types.ts`
+**Source**: `/packages/generation-generics/src/types.ts`
+
+```
+Generation (primitive)
+  → FailsafeGeneration (base kinds — parents)
+  → ThinkingsGeneration (base kinds — children of each failsafe)
+```
+
+#### FailsafeGeneration kinds (3)
 ```typescript
-export enum FailsafeMetaSubStep {
-  PREPARE_CONCISE_CONTEXT = 'prepare_concise_context',  // CONTEXT SIGNAL/NOISE handling
-  CHUNK_THEN_SUM = 'chunk_then_sum',                    // BIG INPUT handling  
-  STITCH_UNTIL_COMPLETE = 'stitch_until_complete'       // CONVERSATIONSUTPUT handling
+export enum FailsafeGeneration {
+  PREPARE_CONCISE_CONTEXT = 'prepare_concise_context',  // CONTEXT SIGNAL/NOISE
+  CHUNK_THEN_SUM = 'chunk_then_sum',                    // BIG INPUT
+  STITCH_UNTIL_COMPLETE = 'stitch_until_complete'       // BIG OUTPUT repair
 }
 ```
 
-#### Generation Sub Meta Sub-Steps (3)
+#### ThinkingsGeneration kinds (3)
 ```typescript
-export enum GenerationSubMetaSubStep {
-  REASON = 'reason',                    // Apply reasoning and logic
-  JUDGE = 'judge',                      // Judge quality of reasoning
-  STRUCTURED_OUTPUT = 'structured_output' // Format into typed output
+export enum ThinkingsGeneration {
+  REASON = 'reason',
+  JUDGE = 'judge',
+  STRUCTURED_OUTPUT = 'structured_output'
 }
 ```
 
-#### Tool Execution (1)
-- `tools_execution` - Direct tool invocation
+#### Tools (1)
+- `tools_execution` — after all failsafes
 
-**Total**: 3 + 3 + 1 = 7 substeps per PTRR step
+**Total per PTRR step**: 3 FailsafeGenerations × Thinkings composition + tools postprocess.
+
+Architecture interface: `PTRRStepGenerationArchitecture`.
+
+### Legacy names (do not use in new code)
+
+| Legacy | Prefer |
+| --- | --- |
+| `FailsafeMetaSubStep` | `FailsafeGeneration` |
+| `GenerationSubMetaSubStep` | `ThinkingsGeneration` |
+| `SubStep` / `SubStepExecution` | `Generation` / `GenerationExecution` |
+| `FailsafeExecution` | `FailsafeGenerationExecution` |
+| `PTRRSubStepArchitecture` | `PTRRStepGenerationArchitecture` |
+| `FailsafeMetaSubStepPrompt` | `FailsafeGenerationPrompt` |
+| `AgentGenerationSubStepPrompt` | `ThinkingsGenerationPrompt` |
+
+"SubStep" was the old term for Generation within a Step. "Meta" is not a term.
 
 ## Prompt System
 
 ### PromptPart
 **Source**: `/packages/prompts/src/parts/PromptPart.ts`
 - Branded string type: `string & { readonly __brand: 'PromptPart' }`
 - Created via `createPromptPart(content: string): PromptPart`
-- Zero runtime overhead
 
 ### Prompt Class
 **Source**: `/packages/prompts/src/prompt.ts`
 - Registry-based formatting system
 - Hierarchical path organization
-- Validates required parts
-
-### Naming Conventions
-
-#### File Naming Pattern (DOCUMENTED but NOT ENFORCED)
-Documentation claims this pattern:
-```
-promptpart_[generic|specific]_[domain]_[PROMPTCLASSNAME]_[semanticcontext]_[POSITION].ts
-```
-
-**REALITY**: Multiple patterns exist in `/packages/prompts/src/raw_promptparts_promptparts/`:
-- `prompt_generic_*.ts` (e.g., `prompt_generic_and.ts`)
-- `engi_system_prompt_*.ts` (e.g., `engi_system_prompt_core_identity.ts`)
-- Simple names (e.g., `assumption_validation.ts`)
-- `patch_*.ts` files (52+ patch files)
-
-## Doc-Comment System
-
-### Current Implementation Status
-
-**✅ Implemented**:
-- Doc-comment parser exists (`/packages/doc-comment/`)
-- Plugin system with base classes
-- TypeScript transformer factory created
-- Individual plugins (doc-prompt, doc-promptpart, etc.)
-
-**❌ NOT Implemented**:
-- Transformer not integrated in build process
-- Automatic prototype injection not active
-- Runtime access functions don't exist
-- Build-time processing is aspirational
-
-### Available Annotations
-
-#### @doc-promptpart
-Version tracking for PromptParts (plugin exists)
-
-#### @doc-code-tool
-Used in MCP tools with `DocCodeToolPrompt` class pattern
-
-#### @doc-prompt
-Core prompt intelligence (plugin exists)
-
-## Tool Architecture
-
-### Tool Class Pattern
-**Source**: `@bitcode/tools-generics`
-- Abstract base class with `.use = primitiveFunction` pattern
-- MCP tools have `DocCodeToolPrompt` class with @doc-code-tool
-- No more cast patterns from 'ai' package
-- ToolUse (plans) → UsedTool (results)
-
-## Agent Architecture
-
-### Agent Interface
-**Source**: `/packages/agent-generics/src/types.ts`
-```typescript
-export interface Agent<TInput = any, TOutput = any> extends Executor<TInput, TOutput>
-```
-
-### Agent Prompts
-- **NO @doc-code-agent** - This annotation doesn't exist
-- Agents use `Prompt` class with PromptParts
-- All agents use `new Prompt()` pattern for PTRR steps
-
-## Package Structure
-
-### Execution Packages
-- `/packages/execution-generics/` - Base Execution and Executor types
-- `/packages/agent-generics/` - Agent implementation with PTRR
-- `/packages/tools-generics/` - Tool abstraction
-
-### Prompt Packages
-- `/packages/prompts/` - PromptPart and Prompt implementations
-- `/packages/doc-comment/` - Doc-comment infrastructure (no implementations)
-- `/packages/doc-code/` - Runtime injection system
-
-## Frontend and product surface terms (V48)
-
-Layout contract: `internal-docs/BITCODE_SOURCE_LAYOUT.md`.
-
-### Experiences (7)
-
-Marketing, Packs, Reads, Deposits, Docs, Conversations, Auxillaries — each with
-matching component prefixes (`Marketing*`, `Packs*`, …) under
-`uapi/components/<experience>/`.
-
-### Component layers
-
-- `Shadcn*` — root primitives (`uapi/components/shadcn/`).
-- `Bitcode*` — shared base over Shadcn (`uapi/components/bitcode/`).
-- Experience prefixes — page-specific composition over Bitcode.
-
-### Component unit
-
-Non-trivial UI lives in `ComponentName/ComponentName.tsx` (not `index.tsx`) with
-optional co-located `hooks/`, `styles/`, `__tests__/`.
-
-### Pipeline vs Execution vs Terminal
-
-| Term | Meaning |
-| --- | --- |
-| **Pipeline** | Product run surface: synthesis/read runs, master-detail tables, stream/log, selection (`BitcodePipeline*`). |
-| **Execution** (agent packages) | Low-level PTRR/agent executor primitives in packages such as `execution-generics`. Not the product UI name. |
-| **Journal / transaction** | BTD ledger journal rows and reconciliation vocabulary (`JournalEntry`, journal transaction kinds). |
-| **Terminal** | **Deleted**. No `/terminal` route or `app/terminal` tree. Do not reintroduce. |
-
-### ❌ NEVER Use These Terms:
-- "FAILSAFE GROUP" or "GENERATION GROUP" - Use the actual enum names
-- "PTRRStep" - It's `AgentVariationStep`
-- "FailsafeSubStep" - It's `FailsafeMetaSubStep`
-- "GenerationSubStep" - It's `GenerationSubMetaSubStep`
-- "@doc-code-agent" - This doesn't exist
-- "Former patterns" - Just document current state
-- New product UI named "Terminal" or product-facing "Executions page" for pipeline runs
-
-### ✅ ALWAYS Use These Terms:
-- `AgentVariationStep` for PTRR steps
-- `FailsafeMetaSubStep` for failsafe operations
-- `GenerationSubMetaSubStep` for generation operations
-- Exact class/type/enum names from source
-- File paths when referencing code
-- **Pipeline** for product run surfaces; **journal** for BTD ledger rows
-
-## Mathematical Foundation
-
-The documentation describes this unification theorem, though it's more philosophical than implemented:
-
-```
-THEOREM: Finite(Type) ∪ Infinite(Prompt) = Unified(Program)
-```
-
-This represents the aspiration that TypeScript types can carry prompt intelligence through doc-comments, though the build-time transformation is not currently active.
-
-## Key Takeaway
-
-Always verify documentation against source code. The Bitcode codebase has evolved rapidly, and documentation often describes aspirational states rather than current implementation. When in doubt:
 
-1. `grep` for the actual usage
-2. Check the exports in package index files
-3. Look at real implementations, not just interfaces
-4. Verify enum values match documentation claims
+### Generation prompt levels
+1. `AgentPrompt` — name + identity
+2. `AgentStepPrompt` — Plan/Try/Refine/Retry purpose
+3. `FailsafeGenerationPrompt` — failsafe handling instruction
+4. `ThinkingsGenerationPrompt` — Reason/Judge/Output instruction
+5. `ToolExecutionPrompt` — tool postprocess
 
----
+## Hosts
 
-*Last Updated: 2026-07-11*
-*Version: Aligned to V48 frontend component + Terminal eradication workstream*
+Use **Host** for pipeline execution boxes (LocalHost, SandboxHost). Do not use
+"Harness" for Host.

packages/agent-generics/README.md

@@ -1,23 +1,32 @@
 # Agent Generics
 
-Agent **primitives**: execution, registries, substeps, `factoryAgent` / `factoryQuickAgent`.
+Agent **primitives**: execution, registries, generation-layer factories,
+`factoryAgent` / `factoryQuickAgent`.
 
 ## Hierarchy
 
 ```
-@bitcode/agent-generics              # this package (Agent primitive)
+Generation / FailsafeGeneration / ThinkingsGeneration   # generation-generics
+        ↑
+@bitcode/agent-generics              # this package (Agent primitive + LLM-bound factories)
         ↑
 @bitcode/generic-agents-ptrr         # PTRRAgent base (Plan→Try→Refine→Retry)
         ↑
 product / generic-agent-*            # specialized agents
 ```
 
+Within each PTRR step: **FailsafeGeneration** ×3 (each runs **ThinkingsGeneration**
+Reason→Judge→StructuredOutput) + tools postprocess.
+
+Legacy `*MetaSubStep` / `SubStep` names are BC aliases only — prefer
+`FailsafeGeneration` / `ThinkingsGeneration` / `GenerationExecution`.
+
 PTRR base factories (`factoryPTRRAgent` / BC `factoryAgentWithPTRR`) live in
 `@bitcode/generic-agents-ptrr` and are re-exported here for compatibility.
 
 ## Quick vs. PTRR Agents
 
-- **PTRRAgent** (`@bitcode/generic-agents-ptrr`): sequences Plan → Try → Refine → Retry. Each generation uses the 3×3 failsafed generation pattern by default.
+- **PTRRAgent** (`@bitcode/generic-agents-ptrr`): sequences Plan → Try → Refine → Retry. Each step uses FailsafeGeneration × ThinkingsGeneration by default.
 - **QuickAgent** (this package): Minimal, single‑generation agent for setup/utility behaviors where PTRR is unnecessary.
 
 Create a QuickAgent: