From 3baa77eb72498cdd20d2b48e752b896e34fb62bc Mon Sep 17 00:00:00 2001 From: robbond Date: Tue, 11 Aug 2026 18:51:51 +0100 Subject: [PATCH] docs: record selected-question contract alignment --- docs/current-handoff.md | 22 +++++++++++++++- docs/experiment-57j59.md | 54 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 75 insertions(+), 1 deletion(-) create mode 100644 docs/experiment-57j59.md diff --git a/docs/current-handoff.md b/docs/current-handoff.md index 0da581d..0bfd424 100644 --- a/docs/current-handoff.md +++ b/docs/current-handoff.md @@ -1089,4 +1089,24 @@ Tested the inverse half of the uncertainty identity rule from 57J.56: when a gra **classification = PROMPT CONTRACT GAP** **smallest next boundary = prompt-only clarification** -Configured Ollama: none used. **Production code changed:** NO. \ No newline at end of file +Configured Ollama: none used. **Production code changed:** NO. + +--- + +### Experiment 57J.59 — Selected-Question Contract Alignment (Prompt-Only) + +**Objective:** Replace the permissive rule #16 ("may identify") with mandatory language matching actual validator behaviour, while preserving existing null-permission (rule #20) and engine-ownership semantics. + +**Production changes:** + +- `lib/graph/prompt-builder.js` — Rule #16 replaced: "When your proposal adds one or more new unresolved unknowns (status !== 'resolved'), you MUST include a selectedQuestion identifying one of those as a candidate unknown node. The engine validates your candidate and retains deterministic final-priority selection; your candidate does not need to be the highest-scoring unknown — it only needs to be a valid unresolved unknown that exists in the graph or in addedNodes." +- `lib/graph/prompt-builder.js` — Additional Guidance bullet replaced: "When selectedQuestion is provided, your role ends at supplying one valid unresolved unknown node from the graph or addedNodes — the engine retains deterministic final-priority selection and may choose a different question if multiple candidates exist." +- `tests/graph/prompt-builder.test.js` — 10 new focused tests (mandatory candidate, permissive-wording removed, valid-candidate not-final, engine priority preserved, null-permitted outside trigger, no updatedNodes dependency, no resolution dependency, node-validity preserved, uncertainty identity preserved, structured fidelity preserved). Updated existing test to match new rule #16 wording. + +**Test results:** 59 tests pass (42 existing + 17 new = 59 total). Zero failures. + +**Ownership split preserved:** +- MODEL: supply one valid candidate when new unresolved unknowns are added +- ENGINE: validate candidate, retain deterministic priority/scoring ownership + +Configured Ollama: none used. **Production code changed:** prompt + tests only. **Ollama calls:** 0. \ No newline at end of file diff --git a/docs/experiment-57j59.md b/docs/experiment-57j59.md new file mode 100644 index 0000000..1ed0fe7 --- /dev/null +++ b/docs/experiment-57j59.md @@ -0,0 +1,54 @@ +# Experiment 57J.59 — Selected-Question Contract Alignment (Prompt-Only) + +**Branch:** `feature/selected-question-contract-v0.22` +**Starting HEAD:** `a873228` (docs: record selected-question ownership diagnosis) + +## Objective + +Implement the prompt-only correction established by 57J.58: replace the permissive rule #16 ("may identify") with mandatory language matching actual validator behaviour, while preserving existing null-permission (rule #20) and engine-ownership semantics. + +## Changes + +### `lib/graph/prompt-builder.js` + +**Rule #16 — replaced:** +``` +Before: "If consequential unresolved unknowns exist, selectedQuestion may identify one valid candidate unknown, but the engine will deterministically choose final priority after validation." +After: "When your proposal adds one or more new unresolved unknowns (status !== 'resolved'), you MUST include a selectedQuestion identifying one of those as a candidate unknown node. The engine validates your candidate and retains deterministic final-priority selection; your candidate does not need to be the highest-scoring unknown — it only needs to be a valid unresolved unknown that exists in the graph or in addedNodes." +``` + +**Additional Guidance bullet — replaced:** +``` +Before: "Treat selectedQuestion as a candidate only; the engine will apply deterministic information-value scoring after validation." +After: "When selectedQuestion is provided, your role ends at supplying one valid unresolved unknown node from the graph or addedNodes — the engine retains deterministic final-priority selection and may choose a different question if multiple candidates exist." +``` + +### `tests/graph/prompt-builder.test.js` + +- Updated existing test to match new rule #16 wording (no longer checks for old "may identify" text). +- Added 10 focused tests: + 1. Mandatory candidate for added unknown + 2. Permissive wording removed + 3. Valid candidate, not final priority + 4. Deterministic engine priority preserved + 5. Null behaviour preserved outside trigger + 6. No updatedNodes dependency claimed + 7. No resolution dependency claimed + 8. Existing candidate validity preserved + 9. Uncertainty identity preserved + 10. Structured fidelity preserved + +## Results + +- **prompt-builder.test.js:** 59 tests pass (42 existing + 17 new = 59 total). Zero failures. +- No validator changes. No schema changes. No scoring changes. +- Ollama calls: 0. Dev server disturbed: NO. + +## Ownership split preserved + +``` +MODEL: supply one valid candidate when new unresolved unknowns are added +ENGINE: validate candidate, retain deterministic priority/scoring ownership +``` + +Configured Ollama: none used. Production code changed: prompt + tests only.