WIP: save progress 2026-04-12
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Bill Holcombe
367
docs/case_studies/whetstone_dsl_semantic_mapping.md
Normal file
367
docs/case_studies/whetstone_dsl_semantic_mapping.md
Normal file
@@ -0,0 +1,367 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user