whetstone_RSA/docs/case_studies/whetstone_dsl_semantic_mapping.md

# WhetstoneDSL Semantic Mapping

## Purpose

This document maps the current `whetstone_DSL` implementation surfaces into the
 semantic entities being established for `whetstone_RSA`.

It exists to make Sprint 003 executable.

The goal is not to restate architecture in the abstract. The goal is to answer:

- which `whetstone_DSL` files currently embody the first RSA-relevant decisions
- which RSA semantic entities those files imply
- which parts are already deterministic baselines
- which parts should become explicit gate contracts
- which parts should remain skeletons before training

## Mapping Rule

Each `whetstone_DSL` surface should be classified into one of four roles:

- semantic source candidate
- deterministic baseline
- runtime/executor consumer
- training-data source candidate

This keeps the case study from collapsing implementation, semantics, and data
collection into one bucket.

## Surface Map

### 1. `editor/src/TaskitemGeneratorV2.h`

Current responsibility:

- generate taskitems from decomposed workstreams
- infer `workerType`
- infer `prerequisiteOps`
- mark queue readiness

RSA semantic implications:

- `worker_type` is a first-class `DecisionContract` plus `DecisionSurface`
- `prereq_op_selector` is a first-class `DecisionContract` plus structured
  `DecisionSurface`

Deterministic baseline value:

- current keyword worker heuristic is the baseline policy
- current prerequisite-op defaulting behavior is the baseline policy

Training-data value:

- high, once paired with richer context and accepted downstream contracts
- especially useful for:
  - task description -> `worker_type`
  - task description -> prerequisite-op set

Recommended semantic extraction:

- `WorkerTypeGate`
- `PrereqOpGate`

### 2. `editor/src/TaskitemConfidenceAmbiguity.h`

Current responsibility:

- compute confidence score
- count ambiguity
- derive escalation flag

RSA semantic implications:

- this is primarily a policy/baseline artifact, not a first training gate

Deterministic baseline value:

- extremely high
- should remain attached to future gate records as deterministic baseline
  evidence

Training-data value:

- low as a primary specialist target
- high as a supervision source for:
  - deterministic-baseline detection
  - guardrail-policy comparison

Recommended semantic extraction:

- `DeterministicPolicyBaseline`
- not an initial RSA gate

### 3. `editor/src/mcp/RegisterArchitectIntakeTools.h`

Current responsibility:

- intake normalization and taskitem generation orchestration
- execution-contract shaping
- verification-type inference
- target-file inference
- acceptance-command inference
- step-sequence inference
- cross-project-target inference

RSA semantic implications:

- `verification_type` is a first-class immediate gate
- execution contract shaping is a structured semantic frontier

Deterministic baseline value:

- very high for current heuristics
- should be preserved as baseline before any specialist substitution

Training-data value:

- very high if taskitem runs with context and final MCP choices still exist
- likely strongest surface for:
  - `verification_type`
  - `target_file_selection`
  - `acceptance_command_selection`
  - `execution_contract_shape`

Recommended semantic extraction:

- `VerificationTypeGate`
- `ExecutionContractShapeDecision`
- `TargetFileSelectionDecision`
- `AcceptanceCommandSelectionDecision`
- `StepSequenceDecision`

### 4. `editor/src/ScopeMilestoneDecomposer.h`

Current responsibility:

- milestone grouping
- workstream grouping
- grouped summary/title generation
- uncertainty scoring

RSA semantic implications:

- grouping decisions are real semantic decisions
- but they are not yet clean enough as direct training targets

Deterministic baseline value:

- high

Training-data value:

- medium
- useful after the grouping contract is made explicit

Recommended semantic extraction:

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

### 5. `editor/src/RoutingEngine.h`

Current responsibility:

- choose worker layer
- choose context width
- set review flag
- derive agent role

RSA semantic implications:

- future second-wave RSA surface
- useful as a meta-layer above particular gates

Deterministic baseline value:

- extremely high
- keep this baseline intact for later RSA-versus-rule comparison

Training-data value:

- medium to high once real historical routing outcomes are assembled

Recommended semantic extraction:

- `LayerSuitabilityDecision`
- `RoutingContextDecision`

Note:

- these sit one layer above RSA identity itself, so they should not be confused
  with an RSA gate contract

### 6. `editor/src/mcp/RegisterCppRaisingTools.h`

Current responsibility:

- choose and validate C++ raising profile
- run deterministic C++ raising and packaging pipeline

RSA semantic implications:

- `cpp_raising_profile` is a clean bounded gate candidate

Deterministic baseline value:

- current manual/explicit profile selection is the baseline

Training-data value:

- medium
- strongest when paired with IR traits, risk annotations, and downstream review
  outcomes

Recommended semantic extraction:

- `CppRaisingProfileGate`

### 7. `editor/src/ConstrainedProjectionGate.h`

Current responsibility:

- block generation when environment constraints are violated

RSA semantic implications:

- this is executor-side deterministic gating
- it is not currently an RSA gate candidate

Deterministic baseline value:

- extremely high

Training-data value:

- useful as supervision for invalid-output prevention
- not useful as a primary specialist target

Recommended semantic extraction:

- `DeterministicConstraintGate`

### 8. `editor/src/ast/ProjectionGenerator.h`

Current responsibility:

- dispatch AST node kinds to language-specific visitors

RSA semantic implications:

- almost none at the current stage
- this is deterministic target-language projection

Deterministic baseline value:

- total

Training-data value:

- not a primary RSA training surface

Recommended semantic extraction:

- no immediate RSA semantic entity
- leave in deterministic projection layer

### 9. `editor/src/CrossLanguageProjector.h`

Current responsibility:

- clone AST into target language
- preserve/adapt annotations

RSA semantic implications:

- good future source for bounded policy choices around adaptation profiles
- current implementation is deterministic

Deterministic baseline value:

- high

Training-data value:

- low now
- potentially higher later if multiple adaptation profiles exist

Recommended semantic extraction:

- future `ProjectionProfileDecision`
- not an immediate Sprint 003 gate

## Semantic Entity Alignment

### Immediate gate entities

| WhetstoneDSL surface | RSA entity | Status |
| --- | --- | --- |
| `TaskitemGeneratorV2::inferWorkerType` | `WorkerTypeGate` | bootstrap now |
| `TaskitemGeneratorV2::inferPrerequisiteOps` | `PrereqOpGate` | bootstrap now |
| `RegisterArchitectIntakeTools::inferVerificationType` | `VerificationTypeGate` | bootstrap now |
| `RegisterCppRaisingTools` profile enum | `CppRaisingProfileGate` | bootstrap now |

### Skeleton-first entities

| WhetstoneDSL surface | RSA entity | Status |
| --- | --- | --- |
| execution-contract heuristics | `ExecutionContractShapeDecision` | skeleton now |
| target-file inference | `TargetFileSelectionDecision` | skeleton now |
| grouping heuristics | `WorkstreamGroupingDecision` | skeleton now |
| grouped summary logic | `WorkstreamSummaryPolicy` | skeleton now |
| step-sequence inference | `StepSequenceDecision` | skeleton now |

### Deterministic baselines to preserve

| WhetstoneDSL surface | RSA role |
| --- | --- |
| `TaskitemConfidenceAmbiguity` | deterministic baseline / guardrail policy |
| `RoutingEngine` | deterministic meta-routing baseline |
| `ConstrainedProjectionGate` | deterministic constraint gate |
| `ProjectionGenerator` dispatch | deterministic projection executor |
| `CrossLanguageProjector` current adaptation | deterministic projection baseline |

## What This Means For Integration

The current integration path should be:

1. capture gate semantics first
2. preserve deterministic baselines as explicit comparison points
3. identify data sources for each gate
4. defer runtime substitution until the gate contracts are stable

The wrong integration path would be:

1. wire RSA runtime into `whetstone_DSL`
2. guess what the gates mean later

This case study is strong enough now to avoid that mistake.

## Training Data Notes

Potential high-value training data sources still likely exist in or around
`whetstone_DSL`, depending on what survived deletion:

- taskitem pipeline run logs with context and final MCP choices
- specialist training data under `whetstone_DSL/specialists`
- the `100 easy` and `25 challenging` project sets already used for examples and
  evaluation
- sprint plan corpus already used for `verification_type`

Immediate implication:

- do not block semantic bootstrap on recovering training data
- but treat recovered taskitem/MCP-choice runs as likely first-class supervision
  once the gate contracts are fixed

## Next Mapping Step

The next document after this one should define skeleton field sets for:

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

Those are the structured surfaces most likely to become later RSA gates once the
semantic contract is explicit enough to benchmark cleanly.