docs/CODEX_LOG.md

Codex Log

This log tracks substantive Codex work on Iris. It is a human-readable companion to Git history, focused on what changed, what was tested, and whether the Iris quality gate passed.

2026-06-06

7819210 - first commit

• Initialized the public iris repository with README.md.
• Pushed main to GitHub.

Validation:

• Git remote and branch tracking confirmed.

e9f54fc - Bootstrap project structure

• Added project foundation docs and contributor workflow.
• Added AGENTS.md, CONTRIBUTING.md, repo layout docs, scripts/check_repo.sh, and source/test anchors.

Validation:

• ./scripts/check_repo.sh passed.

c788f8e - Add MiniCPM validation harness

• Added the Python Iris engine, OpenAI-compatible client, parser, prompts, and CLI validation harness.
• Added unit tests for parser and engine behavior.
• Ran MiniCPM-V 4.6 Instruct validation and documented that it did not pass the Iris quality gate.

Validation:

• python3 -m unittest discover -s tests passed.
• python3 -m compileall iris tests passed.
• ./scripts/check_repo.sh passed.
• Quality gate: failed. Outputs were too generic and repetitive.

dd9aa4c - Keep handoff docs untracked

• Removed local numbered handoff markdown files from Git tracking.
• Added ignore and check-script guardrails so future local task docs stay out of commits.

Validation:

• ./scripts/check_repo.sh passed.

601e3db - Validate local MiniCPM4.1 reasoning model

• Pulled and ran openbmb/minicpm4.1 locally through Ollama.
• Added local Ollama defaults, IRIS_ENABLE_THINKING, /think support, and a longer local timeout.
• Documented Day 1b local MiniCPM4.1-8B validation results.

Validation:

• python3 -m unittest discover -s tests passed.
• python3 -m compileall iris tests passed.
• ./scripts/check_repo.sh passed.
• Quality gate: failed. Local reasoning output still repeated generic pressures and gave implementation advice at the center.

583618e - Harden prompt retry validation

• Tightened the pressure prompt to require idea-grounded questions and removed examples that MiniCPM4.1 copied verbatim.
• Added retry feedback for generic, repeated, unrelated, and solution-shaped pressure outputs.
• Added a balanced first-JSON-object parser so multi-object model streams do not become one malformed field.
• Added stricter center-step quality checks.

Validation:

• python3 -m unittest discover -s tests passed.
• python3 -m compileall iris tests passed.
• ./scripts/check_repo.sh passed.
• Quality gate: failed. Day 1c output was grounded but still repeated the same pressure across rings and returned center steps like Interview.

776e453 - Add deterministic pressure rings

• Replaced loose depth lenses with deterministic ring profiles for Reality Contact, Real Actor, Existing Alternative, and Problem Truth.
• Added retry feedback when model pressure does not start with the required ring opening.
• Documented the Day 1d local MiniCPM4.1 validation run.

Validation:

• python3 -m unittest discover -s tests passed.
• python3 -m compileall iris tests passed.
• ./scripts/check_repo.sh passed.
• Quality gate: failed. Ring separation improved, but center outputs still collapsed to Interview and several why_it_bites fields drifted into advice.

fd0655f - Harden engine validation gate

• Added stricter advice-language validation for why_it_bites with model retry feedback instead of code rewriting.
• Changed center distillation so MiniCPM chooses actor, situation, and assumption_to_test, while Iris only validates and formats the final action.
• Added shared seed/spiral modules and ./scripts/validate_gate.py to print spirals plus automated gate scores.
• Documented the Day 1e local MiniCPM4.1 validation run.

Validation:

• python3 -m unittest discover -s tests passed.
• python3 -m compileall iris tests passed.
• ./scripts/check_repo.sh passed.
• ./scripts/validate_gate.py --all ran against local openbmb/minicpm4.1 and returned the expected gate failure code because only 2 of 3 seed spirals passed. Quality gate: failed. Medication and flashcards passed; tool rental still failed ring separation when Ring 3 repeated the safety-gear frame from Ring 1.

787293f - Harden existing alternative ring

• Added a model-chosen alternative field for the Existing Alternative ring.
• Added Ring 3 validation for missing, weak, product-shaped, copied, or failure-shaped alternatives while keeping MiniCPM responsible for the actual workaround choice.
• Added forbidden prior-frame prompt context so Ring 3 avoids copying earlier pressure scenes.
• Updated the gate with an existing_alternative_named criterion and documented the first full 3-seed automated gate pass.

Validation:

• python3 -m unittest discover -s tests passed.
• python3 -m compileall iris tests passed.
• ./scripts/check_repo.sh passed.
• ./scripts/validate_gate.py --all ran against local openbmb/minicpm4.1 and passed all 3 seed spirals. Quality gate: passed.

5241db6 - Add Gradio spiral UI shell

• Added app.py as the Hugging Face Spaces / Gradio entrypoint.
• Added iris.ui with a custom HTML/CSS concentric-ring stage, seed buttons, streaming ring reveal, and real IrisEngine wiring.
• Added UI render tests for alternative display, center display, and HTML escaping.
• Documented the Day 2a browser smoke test.

Validation:

• python3 -m unittest discover -s tests passed.
• python3 -m compileall iris tests app.py passed.
• ./scripts/check_repo.sh passed.
• Gradio app built successfully in a local virtualenv.
• Browser smoke test passed at http://127.0.0.1:7860: desktop and mobile layouts rendered without horizontal overflow, and a real UI run completed 4 rings plus center from local MiniCPM4.1.

0aef82c - Polish Gradio spiral reveal

• Added named UI ring stages, live progress pills, and pending skeleton cards for ring and center model work.
• Strengthened the center presentation as the final validation action while leaving engine judgment untouched.
• Documented the Day 2b UI smoke pass.

Validation:

• python3 -m unittest discover -s tests passed.
• python3 -m compileall iris tests app.py passed.
• ./scripts/check_repo.sh passed.
• Browser smoke test passed at http://127.0.0.1:7860: desktop and mobile layouts had no horizontal overflow, center pending appeared during a real run, the run completed with 4 rings plus center, and browser console errors were empty.

e64f5cd - Add Stitch atomic UI design export

• Added the Google Stitch atomic/infinite-zoom export under stitch_iris_atomic_infinite_zoom/.
• Preserved the Stitch HTML/CSS references, screenshots, design tokens, and UX flow notes as the source of truth for the Day 2 spatial UI.

Validation:

• Source export reviewed locally; .DS_Store stayed ignored.

9839374 - Build Stage 1 Stitch spatial canvas

• Replaced the previous Gradio form/card shell with a full-bleed static spatial canvas matching the Stitch beginning state.
• Added top navigation, left depth rail, faint orbit rings, stardust, glowing central nucleus, status/depth chips, and bottom hero copy.
• Kept the validated Iris engine unchanged; Stage 2 will wire interaction back to the existing server-side engine path.
• Added the Stage 1 screenshot and validation note.

Validation:

• python3 -m unittest discover -s tests passed.
• python3 -m compileall iris tests app.py passed.
• ./scripts/check_repo.sh passed.
• Browser smoke passed at http://127.0.0.1:7860: desktop 1440x900 and mobile 390x844 rendered full-bleed with no horizontal overflow.

ea9a3f3 - Wire Stage 2 spatial UI flow

• Added real Gradio controls over the Stitch-style nucleus and electrons so the spatial UI is clickable instead of static.
• Added the idea modal, Proceed flow, server-side MiniCPM pressure calls, latest electron descent, and R4 center distillation.
• Kept the validated engine unchanged and added a UI session/view bridge test.
• Documented the Stage 2 core-flow validation run.

Validation:

• python3 -m unittest discover -s tests passed.
• python3 -m compileall iris tests app.py passed.
• ./scripts/check_repo.sh passed.
• Browser smoke passed at http://127.0.0.1:7860: nucleus opened the modal, Proceed returned R1 from local MiniCPM, R1-R4 clicks advanced through the engine depths, R4 reached the center, and desktop/mobile layouts had no horizontal overflow.

d87b0da - Build UI v2 canvas card checkpoint

Date: 2026-06-08

• Replaced the Day 2 circle visual layer with a static FigJam-style canvas and stacking idea/AI pressure cards.
• Added the primary idea frame, three AI pressure cards, a next-iteration idea card, and a secondary frame preview.
• Updated UI tests and docs for the v2 canvas/card checkpoint while leaving the validated engine unchanged.
• Added the Stage 1 screenshot at docs/validation/day2-v2-stage1-canvas-static.png.

Validation:

• python3 -m unittest discover -s tests passed.
• python3 -m compileall iris tests app.py passed.
• git diff --check passed.
• ./scripts/check_repo.sh passed.
• Browser smoke passed at http://127.0.0.1:7860: desktop screenshot captured at 1440x900; the rendered UI had 3 AI cards, 2 idea cards, no visible circle/electron labels, and no page-level horizontal overflow. A mobile screenshot check at 390x844 confirmed the frame remains inside a scrollable canvas.
• Iris quality gate: not rerun for this visual-only checkpoint.

4cb4509 - Wire live canvas card interactions

Date: 2026-06-08

• Replaced the static v2 canvas with a live in-memory canvas app: click-to-create frames, editable idea cards, Proceed actions, iteration cards, multiple independent frames, zoom controls, wheel zoom, and drag panning.
• Added a named Gradio API bridge so browser JavaScript calls the server-side IrisEngine for live MiniCPM pressure cards and center distillation.
• Added API-contract tests for live pressure payloads, prior-card constraint formatting, center payloads, and the empty interactive shell.
• Kept the validated engine logic unchanged.
• Added the live validation screenshot at docs/validation/day2-v2-live-interactive.png.

Validation:

• python3 -m unittest discover -s tests passed.
• python3 -m compileall iris tests app.py passed.
• git diff --check passed.
• ./scripts/check_repo.sh passed.
• Browser smoke passed at http://127.0.0.1:7860 with local MiniCPM: created Frame 1, submitted a tool-rental idea, rendered a live Reality Contact card, submitted an Idea v2 refinement, rendered a live Real Actor card, created a second independent frame, used zoom controls, drag-panned, and confirmed no extra frame was created by the drag fallback.
• Final smoke metrics: 2 frames, 2 live AI pressure cards, 4 idea cards, no old circle/electron labels, no page-level horizontal overflow.
• Iris quality gate: not rerun for this visual/UI checkpoint.

b494dcc - Add live four-direction pressure cards

Date: 2026-06-08

• Changed the live canvas Proceed flow from one AI pressure card to a four-card pressure set: Constraints, Limitations, Capabilities, and Reality Contact.
• Added direction-specific prompts and engine parsing so each card is still authored by MiniCPM, with Python only enforcing format, risk-only bite language, repeat checks, and missing-field repairs through model re-prompts.
• Updated the canvas UI to render pressure sets in a two-by-two card grid, keep depth as one round per pressure set, and pass all prior pressure cards back to the engine for later iterations.
• Added tests for the four-direction payload, prior-card formatting, missing why_it_bites repair, and nested missing-pressure repair.
• Added the Fix 1 validation note and screenshot at docs/validation/day2-v2-fix1-four-pressures.md and docs/validation/day2-v2-fix1-four-pressures.png.

Validation:

• python3 -m unittest discover -s tests passed.
• python3 -m compileall iris tests app.py passed.
• git diff --check passed.
• ./scripts/check_repo.sh passed.
• Browser smoke passed at http://127.0.0.1:7860 with local MiniCPM: created Frame 1, submitted a tool-rental idea, rendered four live direction cards, and showed the next editable Idea v2 card below them.
• Iris quality gate: not rerun for this UI checkpoint.

6cb6709 - Harden MiniCPM split JSON parsing

Date: 2026-06-08

• Fixed a live MiniCPM failure where reasoning-mode output returned one JSON object with pressure_question, then a later final JSON object with why_it_bites.
• Added targeted parser support for selecting the embedded JSON object that contains the requested key without changing the default first-object parser behavior.
• Added pressure_question aliases across the direction engine and repair prompts.
• Treated build as a generic grounding stop word so placeholder ideas like build idea do not fail only because the model did not repeat build.
• Added parser and engine regression tests for split thinking/final JSON output and rough placeholder input.

Validation:

• python3 -m unittest discover -s tests passed.
• python3 -m compileall iris tests app.py passed.
• git diff --check passed.
• ./scripts/check_repo.sh passed.
• Browser smoke passed at http://127.0.0.1:7860 with local MiniCPM: submitted build idea, rendered 4 live pressure cards, and avoided the previous why_it_bites parse failure.
• Iris quality gate: not rerun for this UI parser bugfix.

b8d5c2f - Polish canvas navigation controls

Date: 2026-06-08

• Added native-feeling canvas navigation: empty-space drag pan, wheel pan, Ctrl/Cmd-wheel and Alt-wheel zoom, keyboard zoom/focus shortcuts, toolbar pan arrows, and Focus active frame.
• Made frame headers draggable handles so individual idea frames can move independently on the canvas.
• Kept textareas and buttons as normal form controls while allowing pan/zoom around frame bodies.
• Updated README, architecture notes, UI contract tests, and the validation screenshot/note at docs/validation/day2-v2-canvas-navigation.md.

Validation:

• python3 -m unittest discover -s tests passed.
• python3 -m compileall iris tests app.py passed.
• git diff --check passed.
• ./scripts/check_repo.sh passed.
• Browser smoke passed at http://127.0.0.1:7860: created one frame, dragged the frame header, panned empty canvas without creating an extra frame, Ctrl-wheel zoomed over the frame, toolbar pan moved the world, and Focus recentered the active frame.
• Iris quality gate: not rerun for this UI navigation checkpoint.

06bb36c - Add Build Small field guide

Date: 2026-06-08

• Added docs/BUILD_SMALL_FIELD_GUIDE.md to preserve Khalid's hackathon guidance: Off-the-Grid, Custom UI, optional llama.cpp, Field Notes, Open Trace, demo video, social post, and Hugging Face Space submission needs.
• Updated README, architecture notes, roadmap, and project brief so future work keeps local MiniCPM, custom canvas polish, load-bearing AI, and submission readiness in view.
• No engine or UI runtime behavior changed.

Validation:

• git diff --check passed.
• ./scripts/check_repo.sh passed.
• Iris quality gate: not rerun for this docs-only guidance update.

8e94961 - Keep canvas iterations contextual

Date: 2026-06-08

• Changed the canvas engine bridge so each Proceed call sends the current iteration, original idea, and full idea history to MiniCPM.
• Kept prior pressure cards as forbidden prior pressure context instead of idea text, reducing model copy/repeat loops while preserving model authorship.
• Made canvas pressure rounds open-ended instead of switching to a center card after depth 4.
• Added current-iteration grounding retries and a UI-only soft accept for the final model-authored card when repeat similarity is the only remaining issue.
• Added docs/validation/day2-v2-infinite-context.md.

Validation:

• python3 -m unittest discover -s tests passed.
• python3 -m compileall iris tests app.py passed.
• git diff --check passed.
• ./scripts/check_repo.sh passed.
• Browser smoke passed at http://127.0.0.1:7860: first idea returned 4 live pressure cards, a short second iteration returned 4 more, the frame reached Depth 02, and no model error card appeared.
• Iris quality gate: not rerun for this UI iteration-context checkpoint.

05da4e9 - Keep canvas moving after grounding retries

Date: 2026-06-08

• Fixed a second-iteration UI failure where the current-iteration grounding guard over-weighted weak words such as allows, amazing, and approach.
• Let the canvas soft-accept a final model-authored card when current-iteration grounding is the only remaining retry failure, while preserving hard failures for malformed JSON, advice language, and wrong direction shape.
• Added a regression test for the cheap-compute / vetted-data second-iteration case and documented the live local smoke in docs/validation/day2-v2-current-iteration-soft-pass.md.

Validation:

• python3 -m unittest discover -s tests passed.
• python3 -m compileall iris tests app.py passed.
• git diff --check passed.
• ./scripts/check_repo.sh passed.
• Live local run_canvas_engine() smoke against MiniCPM4.1 passed for the reported second-iteration wording: ok: true, 4 pressure cards, Depth 02.
• Iris quality gate: not rerun for this UI bugfix.

2026-06-10

c87d6d0 - Preserve deep canvas frame memory

• Changed the canvas engine bridge so each model call includes a structured frame-memory prompt: frame continuity, current iteration, original idea, full user iteration history, and prior AI pressure trail with depth, direction, pressure, and why_it_bites.
• Kept prior cards as separate forbidden pressure context so MiniCPM can stay synced with the idea's origin without copying earlier AI cards.
• Added deep-frame regression coverage for later-depth ideations in one frame.
• Added a UI soft-pass for broad idea-grounding retry exhaustion, while malformed JSON, advice language, and wrong direction shape still fail closed.
• Updated README, architecture notes, and docs/validation/day2-v2-deep-frame-memory.md.

Validation:

• python3 -m unittest discover -s tests passed.
• python3 -m compileall iris tests app.py passed.
• git diff --check passed.
• ./scripts/check_repo.sh passed.
• Live local run_canvas_engine() smoke against MiniCPM4.1 passed at Depth 06 with four user iterations and three prior AI pressure cards in one frame.
• Iris quality gate: not rerun for this UI memory checkpoint.

2026-06-12

784e929 - Harden Hugging Face Space readiness

• Added Docker Space frontmatter and submission-facing README notes for the Build Small track, target awards, demo link, social link, and Space URL.
• Removed Iris frontend runtime dependencies on Google Fonts and jsDelivr; the final brief now uses the browser's local Save as PDF flow.
• Added a deterministic Gradio template patch for the Docker image so Gradio's wrapper does not load Google preconnects, the iframe-resizer CDN script, or external Gradio social-card images.
• Hardened .dockerignore so .env, .env.*, and .envrc stay out of the Docker build context.
• Updated architecture and field-guide docs from the old canvas/circle language to the current pressure-studio product story.

Validation:

• python3 -m unittest discover -s tests passed.
• python3 -m compileall iris tests app.py scripts/patch_gradio_templates.py passed.
• git diff --check passed.
• ./scripts/check_repo.sh passed.
• Browser smoke passed at http://127.0.0.1:7860: pressure studio rendered, one active idea card was ready, default Gradio utility buttons were hidden, no horizontal overflow appeared, and the rendered page contained no fonts.googleapis.com, fonts.gstatic.com, cdnjs.cloudflare.com, cdn.jsdelivr.net, raw.githubusercontent.com, or html2pdf references after applying the Gradio template patch.
• Iris quality gate: not rerun; this was a Hugging Face Space readiness and submission-polish pass, not an engine-output change.

2026-06-13

56b9212 - Guard model output against template-placeholder leaks

• Added a template-leak guard so bracketed or angle-bracketed fill-in placeholders like [Constraint], [this], or <idea> trigger quality feedback instead of reaching the UI or CLI.
• Kept soft canvas mode resilient by returning a clean honest fallback card when the local model keeps leaking template placeholders after retries.
• Added regression coverage proving soft mode never surfaces placeholder cards.

Validation:

• python3 -m unittest discover -s tests passed.
• python3 -m compileall iris tests app.py passed.
• git diff --check passed.
• ./scripts/check_repo.sh passed.
• Iris quality gate: not rerun; this was a model-output validation hardening change covered by targeted regression tests.

a0a1871 - Align README tags with Build Small submission format

• Replaced freeform README frontmatter tags with the hackathon's namespaced track:, sponsor:, and achievement: tags so the submission tool can parse Iris correctly.
• Added a submission-facing explanation of what Iris is, how it is built, why MiniCPM is load-bearing, and which target awards/badges the app should claim.
• Left the demo video, social post, and Space URL TODO slots untouched for Khalid to fill after recording and posting.

Validation:

• python3 -m unittest discover -s tests passed.
• python3 -m compileall iris tests app.py passed.
• git diff --check passed.
• ./scripts/check_repo.sh passed.
• Iris quality gate: not rerun; this was README submission metadata and narrative alignment.

c6cc4ac - Speed up Hugging Face Space Docker build

• Replaced the source build of llama.cpp with a pinned prebuilt Ubuntu x64 CPU llama-server archive from the official llama.cpp releases.
• Kept the runtime path on llama.cpp while avoiding a long C++ compile on the Hugging Face Space builder.
• Updated README and deploy docs to describe the prebuilt llama-server path.

Validation:

• python3 -m unittest discover -s tests passed.
• python3 -m compileall iris tests app.py passed.
• git diff --check passed.
• ./scripts/check_repo.sh passed.
• Space deployment: built and ran at https://build-small-hackathon-iris-pressure-studio.hf.space; logs showed MiniCPM loaded through llama-server, the model server became healthy, and Gradio launched on 0.0.0.0:7860.

2026-06-14

39be7ca - Fit Space model calls within CPU timeout budget

• Raised the live UI engine-call abort window from 90 seconds to 4 minutes so CPU Basic MiniCPM rounds can complete instead of returning all-red timeout cards.
• Set the Space default IRIS_MAX_TOKENS to 320 because pressure cards are short and CPU generation speed is the live bottleneck.
• Kept README submission TODO links untouched.

Validation:

• python3 -m unittest discover -s tests passed.
• python3 -m compileall iris tests app.py passed.
• bash -n scripts/space_entrypoint.sh passed.
• git diff --check passed.
• ./scripts/check_repo.sh passed.
• Space deployment: built and ran on https://build-small-hackathon-iris-pressure-studio.hf.space, but a live CPU Basic pressure round still exceeded the new 4-minute client budget. That prompted a follow-up change to collapse the four direction requests into one bounded model generation.

0be287b - Fit live Space pressure rounds on CPU Basic

• Kept MiniCPM load-bearing while asking the live HTTP client for all four direction cards in one combined model call.
• Preserved deterministic sequential behavior for tests and fake clients.
• Raised the live browser/backend timeout budget to 10 minutes for CPU Basic cold runs while keeping IRIS_MAX_TOKENS capped.
• Capped the combined live call at one attempt and tightened the prompt against generic "the idea" cards after the live Space returned four cards in about seven minutes but with weak generic wording.
• No README submission TODO slots changed.

Validation:

• python3 -m unittest discover -s tests passed.
• python3 -m compileall iris tests app.py passed.
• bash -n scripts/space_entrypoint.sh passed.
• git diff --check passed.
• ./scripts/check_repo.sh passed.

pending - Add demo, social, and Space links to README

• Added the final Live Space, demo video, and social post links to the README submission section and top quick-links banner.
• Removed the now-satisfied README TODO items for Space, demo video, and social post links.
• Left the Build Small YAML frontmatter tags unchanged.

Validation:

• ./scripts/check_repo.sh passed.
• git diff --check passed.