whetstone_DSL/docs/DETERMINIZATION_NOTES_whimptk_bootstrap.md

# Determinization Notes: `whimptk` Bootstrap

This note belongs in Whetstone because the high-entropy stages are properties of
the bootstrap and MCP workflow, not of `whimptk` itself.

The purpose is to identify places where open-ended model behavior should be
collapsed into deterministic schemas, validators, or executable transforms.

## Current Bias

If a stage can be expressed as:

- a finite schema
- a bounded classification problem
- a deterministic transformation
- a constrained verification routine

then that stage should move in that direction instead of remaining a broad
prompt.

## High-Entropy Stages Exposed By `whimptk`

### 1. Freeform sprint/spec intake

Risk:

- broad prose lets the model overfit to incidental wording
- key architectural constraints get flattened or lost

Observed constraints that need explicit structure:

- widget-first primitive order
- optional binding presentation
- separation between WHIMP policy and toolkit implementation
- non-desktop future applicability

Deterministic direction:

- define a primitive-bootstrap schema with fields such as:
  - `primitive_order`
  - `required_types`
  - `optional_types`
  - `policy_constraints`
  - `non_goals`
  - `verification_commands`

Short-term operational rule:

- restate these fields explicitly before taskitem generation

### 2. Taskitem generation from generic intake

Risk:

- broad tasks
- wrong-project paths
- invalid verification commands
- generic planning buckets instead of execution slices

Deterministic direction:

- enforce a taskitem contract:
  - one bounded objective
  - real target files
  - real acceptance commands
  - no cross-repo ambiguity
  - explicit ownership slice

Short-term operational rule:

- reject or manually correct any taskitem set that violates the contract
- preserve raw and corrected artifacts as training data

### 3. Code generation requests that are too large

Risk:

- asking for a whole subsystem invites placeholder output
- apparent success can hide missing structure

Deterministic direction:

- constrain codegen asks to one artifact at a time:
  - one type
  - one header
  - one function
  - one validator
  - one test file

Short-term operational rule:

- split cross-abstraction requests into explicit file-level contracts first

### 4. Implicit architectural assumptions

Risk:

- the model may silently reinterpret `whimptk` as a desktop-only widget library
- the model may blur toolkit and compositor responsibilities

Deterministic direction:

- add preflight acceptance checks for:
  - policy remains above implementation
  - `whimpwm` is not treated as the toolkit
  - binding presentation remains optional

Short-term operational rule:

- keep these checks in bootstrap review until Whetstone can validate them

## Candidate Whetstone Improvements

- a primitive-bootstrap JSON schema for toolkit bring-up
- a taskitem linter for wrong-project paths and invalid verification commands
- a repo-constraint injection layer for taskitem generation
- a validator for primitive dependency ordering
- a registry of approved acceptance command patterns per repo/language

## Review Rule

Whenever a Whetstone stage is corrected manually, ask:

1. Was the failure caused by underspecified input?
2. Can the missing structure be expressed as a schema or checklist?
3. Can future runs reject the bad output automatically?

If yes, this should become Whetstone product work rather than remain a local
operator habit.