feat: make AI suggestions visibly provisional and correction-first (#13)

Suggested, confirmed, and corrected AI states are now distinct in the log
sheet, and correcting a suggested value clears the AI-confirmed state while
keeping every user-entered field. Screen-reader copy states the AI confidence
and who is in control.

- src/suggestion.js: provenance state machine (pending/confirmed/corrected/manual)
- app.js: renders provenance on the scan result and log steps, tracks corrections
- tests/suggestion.test.js: unit coverage for the state machine and a11y copy
- tests/provisional-suggestion.acceptance.mjs: browser acceptance + screenshots
- record_release_demo.mjs: demo now reviews, confirms, and corrects the suggestion
- CI, release builder, and release notes gate the new contract

scripts/build_release.py

@@ -112,6 +112,7 @@ def main() -> int:
             run(["npm", "run", "test:mobile-capture"], tree)
             run(["npm", "run", "test:sleek"], tree)
             run(["npm", "run", "test:manual-fallback"], tree)
+            run(["npm", "run", "test:provisional"], tree)
             demo_raw = release_dir / f"timmy-talking-turd-{version}-demo.raw.webm"
             demo_env = dict(server_env)
             demo_env["TIMMY_RELEASE_VERSION"] = version
@@ -135,7 +136,7 @@ def main() -> int:
         contact_sheet = release_dir / f"timmy-talking-turd-{version}-demo-contact-sheet.jpg"
         run(["ffmpeg", "-y", "-v", "error", "-i", str(demo), "-vf", "fps=1/2,scale=180:-1,tile=4x3:padding=4:margin=4", "-frames:v", "1", str(contact_sheet)], tree)
         run(["npm", "audit", "--audit-level=high"], tree)
-        for file in ("app.js", "server.mjs", "service-worker.js", "src/analysis.js", "src/domain.js", "src/draft.js", "src/vision-readiness.js", "src/hermes-agent-service.js", "src/vision-config.js", "src/vision-service.js", "tests/staging.acceptance.mjs"):
+        for file in ("app.js", "server.mjs", "service-worker.js", "src/analysis.js", "src/domain.js", "src/draft.js", "src/suggestion.js", "src/vision-readiness.js", "src/hermes-agent-service.js", "src/vision-config.js", "src/vision-service.js", "tests/staging.acceptance.mjs"):
             run(["node", "--check", file], tree)
         run(["bash", "-n", "scripts/bootstrap_selfhost_smolvlm.sh"], tree)
         run(["bash", "-n", "scripts/run_selfhost_smolvlm.sh"], tree)
@@ -163,6 +164,7 @@ def main() -> int:
             "- Smart free-text Timmy chat backed by authenticated server-side Hermes session continuity\n"
             "- Agent safety: exact-origin HttpOnly session, bounded text-only ledger context, no browser credentials or session IDs\n"
             "- Vision profiles: hosted and self-hosted SmolVLM2 bootstrap\n"
+            "- AI suggestions stay provisional: suggested, confirmed, and corrected states are distinct and screen-reader described; correcting one clears the AI-confirmed state without losing user context\n"
             "- Safety: suggestions are observable-field assistance, never diagnosis; user confirmation is required\n"
             "- Known limitation: open-weight VLM acceptance is proven, Bristol accuracy is not clinically validated\n"
             "- Package excludes model weights, medical-image corpora, raw research pages, generated screenshots, and video production assets\n"
@@ -207,7 +209,7 @@ def main() -> int:
             "codec": "h264",
             "pixel_format": "yuv420p",
             "recorded_from_working_app": True,
-            "fixture_data": "synthetic-Type-4, deterministic vision suggestion, offline vision status, and deterministic Hermes chat response",
+            "fixture_data": "synthetic-Type-4, deterministic vision suggestion reviewed, confirmed, and corrected to Type 2, offline vision status, and deterministic Hermes chat response",
         },
         "gates": {
             "unit_security": "passed",
@@ -215,6 +217,7 @@ def main() -> int:
             "photo_first_acceptance": "passed",
             "sleek_hermes_chat_acceptance": "passed",
             "manual_fallback_draft_recovery": "passed",
+            "provisional_suggestion_state": "passed",
             "dependency_audit_high": "passed",
             "syntax": "passed",
             "secret_scan": "passed",

scripts/record_release_demo.mjs

@@ -136,8 +136,18 @@ await page.locator('#ai-consent').check();
 await tap('#analyze-photo', 450);
 await page.getByText(/83% confidence/i).waitFor();
 await caption('AI may suggest visible form, broad color, and image quality — never symptoms or diagnosis', 1700);
+await indicate('.scan-result[data-provenance="pending"]');
+await caption('The suggestion stays provisional — nothing is applied or saved until you confirm it', 1700);
 await tap('#use-suggestion', 450);
-await caption('The user reviews every suggestion before saving', 1100);
+await page.locator('.ai-provenance[data-provenance="confirmed"]').waitFor();
+await caption('Confirming is explicit, and every suggested value is still yours to overrule', 1600);
+await tap('[data-type="2"]', 500);
+await page.locator('[data-provenance="corrected"]').waitFor();
+await caption('Change a suggested value and Timmy clears the AI-confirmed state', 1700);
+await indicate('.ai-provenance[data-provenance="corrected"] .provenance-note');
+await tap('#next', 450);
+await page.getByText(/You changed it to Type 2/).waitFor();
+await caption('Only visible form and color were ever suggested — urgency, discomfort, and symptoms stay yours', 1900);
 await tap('#close-sheet', 450);
 await caption('Closing the log keeps the draft in this session instead of throwing it away', 1600);
 await caption('Now the same photo flow while the vision worker is offline', 1500);
@@ -151,8 +161,8 @@ await page.getByText(/Ready for your review/i).waitFor();
 await caption('No consent prompt and no upload when analysis cannot run', 1600);
 await tap('#manual-from-scan', 500);
 const keptDraft = await page.locator('.draft-resume').innerText({ timeout: 5000 });
-if (!/Type 4/.test(keptDraft)) throw new Error('The retained draft must show exactly what the user is keeping');
-await caption('One tap still reaches manual Bristol entry', 1500);
+if (!/Type 2/.test(keptDraft)) throw new Error('The retained draft must show the value the user corrected to');
+await caption('One tap still reaches manual Bristol entry, and the draft keeps your corrected value', 1800);
 await tap('#discard-draft', 500);
 await caption('Start over clears the kept draft — nothing lingers silently', 1500);
 await tap('#close-sheet', 450);