whetstone_RSA/docs/case_studies/whetstone_dsl_gate_inventory.md

# WhetstoneDSL Gate Inventory

## Purpose

This document grounds `whetstone_RSA` Phase 1 in the actual decision surfaces
currently present in `whetstone_DSL`.

It is intentionally narrower than a general architecture document.

The goal is to answer:

- what bounded decisions already exist in the `whetstone_DSL` taskitem and
  AST-codegen pipeline
- which of those are already deterministic
- which are immediate RSA case-study candidates
- which should become semantic skeletons first before any specialist training

This inventory is based on the current code surfaces in:

- `editor/src/TaskitemGeneratorV2.h`
- `editor/src/TaskitemConfidenceAmbiguity.h`
- `editor/src/RoutingEngine.h`
- `editor/src/mcp/RegisterArchitectIntakeTools.h`
- `editor/src/ast/ProjectionGenerator.h`
- `editor/src/CrossLanguageProjector.h`
- `editor/src/ConstrainedProjectionGate.h`
- `editor/src/mcp/RegisterCppRaisingTools.h`

## Architectural Observation

The strongest current RSA surface in `whetstone_DSL` is not the final
language-emission step.

Once the AST and target language are fixed, most current code generation is
already deterministic:

- target generator dispatch is deterministic
- AST concept dispatch is deterministic
- environment gating is deterministic
- C++ raising profile validation is deterministic

That means the immediate RSA case-study value is higher in:

- taskitem generation
- execution-contract shaping
- routing
- pre-codegen bounded profile decisions

than in raw syntax emission.

## Current Decision Surfaces

### A. Taskitem decomposition and planning

Observed decisions:

- milestone grouping
- workstream grouping
- workstream title shape
- workstream intent aggregation
- uncertainty scoring

Current implementation state:

- largely heuristic and deterministic in `ScopeMilestoneDecomposer`
- not yet expressed as explicit RSA gate contracts

Assessment:

- milestone grouping is currently deterministic and should remain so until a real
  ambiguity signal shows otherwise
- uncertainty scoring is currently formula-like and should remain deterministic
- title shaping is mixed: parts are deterministic formatting, but some grouping
  and summary choices are latent semantic decisions

RSA relevance:

- weak immediate training target
- good semantic-skeleton target

Suggested skeleton entities:

- `WorkstreamGroupingDecision`
- `MilestoneGroupingDecision`
- `WorkstreamSummaryPolicy`

### B. Taskitem worker-type assignment

Observed decision:

- `implementer | reviewer | architect | qa`

Current implementation state:

- keyword heuristic in `TaskitemGeneratorV2::inferWorkerType`
- file comment explicitly says this is a placeholder to be replaced by a
  `worker_type` specialist

Assessment:

- clear bounded enum
- direct downstream deterministic meaning
- already known from specialist experiments

RSA relevance:

- immediate case-study gate

Recommended gate class:

- bounded multiclass gate

Likely failure risks:

- label-space mismatch
- missing context gate

### C. Taskitem prerequisite-op assignment

Observed decision:

- `validate-intake`
- `architect-review`
- `resolve-dependencies`

Current implementation state:

- deterministic default plus uncertainty-based add-on in
  `TaskitemGeneratorV2::inferPrerequisiteOps`
- comments explicitly note this is a placeholder for a future
  `prereq_op_selector` specialist

Assessment:

- this is not purely one flat label
- it is closer to a bounded structured output or factorized multi-label gate

RSA relevance:

- immediate case-study gate
- especially important for factorization probes

Recommended gate shape:

- factorized or multi-label, not naive flat multiclass

Likely failure risks:

- factorizable gate
- label-space mismatch

### D. Confidence / ambiguity / escalation

Observed decisions:

- confidence score `0..100`
- ambiguity count
- escalate `true|false`

Current implementation state:

- formulaic in `TaskitemConfidenceAmbiguity`

Assessment:

- this is the strongest current example of a deterministic-disguised-as-ML gate

RSA relevance:

- important as negative evidence
- should stay deterministic unless a later richer policy surface emerges

Recommended disposition:

- deterministic layer, not RSA

### E. Routing decision

Observed decisions:

- worker type:
  `deterministic | template | slm | llm | human`
- context width:
  `local | file | project | cross-project`
- review required
- agent role:
  `linter | refactor | generator`

Current implementation state:

- deterministic rule cascade in `RoutingEngine`
- explicit override path plus heuristic fallbacks

Assessment:

- routing is already modeled as a bounded decision surface
- the current engine is a rule baseline
- this is a strong later RSA case study, but not the first one

RSA relevance:

- important second-wave case study
- especially useful for comparing deterministic baseline versus RSA gate quality

Recommended disposition:

- keep current deterministic routing as baseline
- use it later as benchmark data for RSA substitution or hybrid routing

### F. Execution-contract shaping

Observed decisions in `RegisterArchitectIntakeTools`:

- target file inference
- required tool inference
- acceptance-command inference
- cross-project target inference
- verification type inference:
  `unit | schema | docs | smoke`
- step-id inference:
  `inspect_scope`, `implement_changes`, `apply_changes`,
  `run_unit_verification`, `run_smoke_verification`, etc.
- resource-lock inference

Assessment by subtype:

- target-file inference:
  mixed, partly lexical and partly semantic
- required-tool inference:
  bounded and meaningful
- verification type:
  strong existing specialist case
- step-id inference:
  bounded structured sequence; good future structured-output RSA case
- resource locks:
  likely deterministic unless concurrency semantics become richer

RSA relevance:

- `verification_type` is immediate
- execution-contract shaping is a strong structured-output frontier

Recommended split:

- immediate RSA gates:
  - `verification_type`
- semantic skeleton first:
  - `ExecutionContractShapeDecision`
  - `TargetFileSelectionDecision`
  - `AcceptanceCommandSelectionDecision`
  - `StepSequenceDecision`

### G. AST projection / code generation

Observed decisions:

- target language selection
- AST node dispatch to language-specific visitor
- annotation-preserving cross-language projection
- environment constraint gating
- C++ raising profile:
  `safe-first | perf-first | interop-first`

Current implementation state:

- almost entirely deterministic once target language and profile are provided

Assessment:

- generator dispatch itself is not the best current RSA surface
- the richer opportunity is in bounded pre-codegen policy selection, not in
  token-level syntax generation

RSA relevance:

- immediate gate candidate:
  `cpp_raising_profile`
- skeleton-first targets:
  - `ProjectionProfileDecision`
  - `ErrorModelPolicyDecision`
  - `OwnershipMappingProfileDecision`
  - `AsyncMappingPolicyDecision`

## Inventory Table

| Decision surface | Current form | Best current layer |
| --- | --- | --- |
| `worker_type` | bounded enum | RSA immediate |
| `prereq_op_selector` | bounded structured / factorized | RSA immediate |
| `verification_type` | bounded enum | RSA immediate |
| `confidence_tier` / `escalate` | formula-like | deterministic |
| milestone grouping | heuristic grouping | semantic skeleton first |
| workstream summary/title | mixed heuristic | semantic skeleton first |
| routing layer selection | bounded enum with strong rules | deterministic baseline, later RSA |
| target-file inference | mixed bounded selection | semantic skeleton first |
| acceptance-command inference | bounded selection | semantic skeleton first |
| step-sequence inference | bounded structured sequence | semantic skeleton first |
| resource locks | bounded selection | deterministic |
| generator dispatch by language | deterministic | deterministic |
| C++ raising profile | bounded enum | RSA immediate or near-immediate |

## Recommended Implementation Order

### 1. Immediate RSA gate cases

Use the already-observed bounded gates first:

- `verification_type`
- `worker_type`
- `prereq_op_selector`
- `cpp_raising_profile`

These are the best first fit because they already have:

- small output vocabularies
- deterministic downstream meaning
- clear failure consequences
- real code paths in `whetstone_DSL`

### 2. Skeleton before specialist

Before training more specialists, define explicit semantic skeletons for:

- workstream grouping
- execution contract shaping
- target-file selection
- acceptance-command selection
- step-sequence selection

These are not yet clean enough as training targets because the semantic contract
is still implicit in heuristics.

### 3. Second-wave RSA cases

After the skeleton pass:

- routing layer selection
- routing context-width selection
- richer codegen profile selection
- backend-policy decisions in IR raising

## Implication For Sprint 002

Sprint 002 should not jump straight from the current C++ RSA scaffold into model
training.

It should first ensure the semantic model can express at least these categories:

- bounded enum gate
- factorized / structured-output gate
- deterministic baseline attached to a candidate gate
- downstream deterministic executor contract
- failure diagnosis for factorization and schema drift

That semantic coverage is required to represent the real `whetstone_DSL`
surfaces above.

## Concrete Next Step

Define Whetstone-authored semantic entities for the first four case-study gates:

- `VerificationTypeGate`
- `WorkerTypeGate`
- `PrereqOpGate`
- `CppRaisingProfileGate`

and define skeleton semantic entities for:

- `ExecutionContractShapeDecision`
- `WorkstreamGroupingDecision`
- `TargetFileSelectionDecision`

That would let `whetstone_RSA` move from generic architecture language into a
usable case-study-grounded semantic bootstrap.