diff --git a/PROJECT_STATUS.md b/PROJECT_STATUS.md new file mode 100644 index 00000000..d6a3bcd3 --- /dev/null +++ b/PROJECT_STATUS.md @@ -0,0 +1,104 @@ +# PROJECT_STATUS.md + +> **Bridge document for Mario (Clawdbot) ↔ Claude Code coordination** +> +> Both AIs should read this at session start. Update when priorities change. + +*Last updated: 2026-01-27 by Mario* + +--- + +## Current Focus + +**Phase**: Foundation (Phase 1) +**Sprint**: 2026-01-27 to 2026-02-03 + +### This Week's Priorities + +1. πŸ”΄ **Dashboard Pain Points** β€” Antoine to document what's broken/missing +2. πŸ”΄ **QUICK_REF.md** β€” Mario drafting simplified protocol reference +3. πŸ”΄ **CONTEXT.md** β€” Mario drafting session initialization (like Clawdbot's AGENTS.md) +4. 🟑 **LAC β†’ Git Protocol** β€” Ensure learnings are committed after sessions + +### Blocked + +- Phase 2 (Dashboard) waiting on pain point documentation + +--- + +## Active Decisions + +| Decision | Summary | Date | +|----------|---------|------| +| Full Partnership | Mario = PM, reviewer, architect. Antoine = developer, NX. | 2026-01-27 | +| Dashboard on Windows | Keep simple for now, hybrid architecture later | 2026-01-27 | +| Adopt Clawdbot Patterns | MEMORY.md, QUICK_REF.md, simplified CLAUDE.md | 2026-01-27 | + +--- + +## For Claude Code + +When starting a session: + +1. βœ… Read CLAUDE.md (system instructions) +2. βœ… Read PROJECT_STATUS.md (this file β€” current priorities) +3. βœ… Read `knowledge_base/lac/session_insights/failure.jsonl` (critical lessons) +4. πŸ”² After session: Commit any new LAC insights to Git + +### LAC Commit Protocol (NEW) + +After each significant session, commit LAC changes: + +```bash +cd Atomizer +git add knowledge_base/lac/ +git commit -m "lac: Session insights from YYYY-MM-DD" +git push origin main && git push github main +``` + +This ensures Mario can see what Claude Code learned. + +--- + +## For Mario (Clawdbot) + +When checking on Atomizer: + +1. Pull latest from Gitea: `cd /home/papa/repos/Atomizer && git pull` +2. Check `knowledge_base/lac/session_insights/` for new learnings +3. Update tracking files in `/home/papa/clawd/memory/atomizer/` +4. Update this file if priorities change + +### Heartbeat Check (Add to HEARTBEAT.md) + +```markdown +### Atomizer Check (weekly) +- git pull Atomizer repo +- Check for new LAC insights +- Review recent commits +- Update roadmap if needed +``` + +--- + +## Recent Activity + +| Date | Activity | Who | +|------|----------|-----| +| 2026-01-27 | Created master plan in PKM | Mario | +| 2026-01-27 | Created tracking files | Mario | +| 2026-01-27 | ACKed Atomizer project | Mario | +| 2026-01-27 | Canvas V3.1 improvements | Claude Code (prior) | + +--- + +## Links + +- **Master Plan**: `/home/papa/obsidian-vault/2-Projects/Atomizer-AtomasteAI/Development/ATOMIZER-NEXT-LEVEL-MASTERPLAN.md` +- **Mario's Tracking**: `/home/papa/clawd/memory/atomizer/` +- **LAC Insights**: `knowledge_base/lac/session_insights/` +- **Full Roadmap**: See Master Plan in PKM + +--- + +*This file lives in the repo. Both AIs can read it. Only update when priorities change.* diff --git a/docs/QUICK_REF.md b/docs/QUICK_REF.md new file mode 100644 index 00000000..aab90c95 --- /dev/null +++ b/docs/QUICK_REF.md @@ -0,0 +1,74 @@ +# Atomizer QUICK_REF + +> 2-page maximum intent: fastest lookup for humans + Claude Code. +> If it grows, split into WORKFLOWS/* and PROTOCOLS/*. + +_Last updated: 2026-01-29 (Mario)_ + +--- + +## 0) Non-negotiables (Safety / Correctness) + +### NX process safety +- **NEVER** kill `ugraf.exe` / user NX sessions directly. +- Only close NX using **NXSessionManager.close_nx_if_allowed()** (sessions we started). + +### Study derivation +- When creating a new study version: **COPY the working `run_optimization.py` first**. Never rewrite from scratch. + +### Relative WFE +- **NEVER** compute relative WFE as `abs(RMS_a - RMS_b)`. +- Always use `extract_relative()` (node-by-node difference β†’ Zernike fit β†’ RMS). + +### CMA-ES baseline +- `CmaEsSampler(x0=...)` does **not** evaluate baseline first. +- Always `study.enqueue_trial(x0)` when baseline must be trial 0. + +--- + +## 1) Canonical workflow order (UI + docs) + +**Create β†’ Validate β†’ Run β†’ Analyze β†’ Report β†’ Deliver** + +Canvas is a **visual validation layer**. Spec is the source of truth. + +--- + +## 2) Single source of truth: AtomizerSpec v2.0 + +- Published spec: `studies///atomizer_spec.json` +- Canvas edges are for visual validation; truth is in: + - `objective.source.*` + - `constraint.source.*` + +--- + +## 3) Save strategy (S2) + +- **Draft**: autosaved locally (browser storage) +- **Publish**: explicit action that writes to `atomizer_spec.json` + +--- + +## 4) Key folders + +- `optimization_engine/` core logic +- `atomizer-dashboard/` UI + backend +- `knowledge_base/lac/` learnings (failures/workarounds/patterns) +- `studies/` studies + +--- + +## 5) Session start (Claude Code) + +1. Read `PROJECT_STATUS.md` +2. Read `knowledge_base/lac/session_insights/failure.jsonl` +3. Read this file (`docs/QUICK_REF.md`) + +--- + +## 6) References + +- Deep protocols: `docs/protocols/` +- System instructions: `CLAUDE.md` +- Project coordination: `PROJECT_STATUS.md` diff --git a/docs/ROADMAP/2026Q1_CREATE_WIZARD.md b/docs/ROADMAP/2026Q1_CREATE_WIZARD.md new file mode 100644 index 00000000..0af81c61 --- /dev/null +++ b/docs/ROADMAP/2026Q1_CREATE_WIZARD.md @@ -0,0 +1,29 @@ +# Roadmap 2026 Q1 β€” Create Wizard + Spec/Canvas Foundation + +_Last updated: 2026-01-29 (Mario)_ + +## Milestone M1 β€” Spec/Canvas is deterministic (Foundation) +- [ ] Frontend has `lib/spec` converters (specToNodes/specToEdges) +- [ ] Objective/constraint `source` is truth +- [ ] Edges are projections of `source` +- [ ] Node positions persist + +## Milestone M2 β€” Draft + Publish (S2) +- [ ] DraftManager local autosave +- [ ] Publish writes server spec with hash check +- [ ] Conflict banner behavior defined + +## Milestone M3 β€” Create Wizard v1 (Files + Introspection + Validate + Publish) +- [ ] `/create` route + stepper +- [ ] Files step w/ dependency tree + `_i.prt` warnings +- [ ] Introspection step w/ expressions list + DV selection +- [ ] Validate step (checklist + parameters table + canvas) +- [ ] Publish step (create study folder + write README) + +## Milestone M4 β€” Create Wizard v2 (Context + Draft + Interview) +- [ ] Context scan + bundle +- [ ] Draft endpoint +- [ ] Interview engine integration + +## Notes +- Canvas stays as validation layer; spec remains the executable truth. diff --git a/docs/WORKFLOWS/ANALYZE.md b/docs/WORKFLOWS/ANALYZE.md new file mode 100644 index 00000000..1eafd727 --- /dev/null +++ b/docs/WORKFLOWS/ANALYZE.md @@ -0,0 +1,11 @@ +# Workflow: ANALYZE + +_Last updated: 2026-01-29 (Mario)_ + +## Goal +Explore results + generate insights. + +## UI +- Results overview +- Insights bank (generate HTML artifacts) +- Claude-assisted interpretation diff --git a/docs/WORKFLOWS/CREATE.md b/docs/WORKFLOWS/CREATE.md new file mode 100644 index 00000000..a0846e28 --- /dev/null +++ b/docs/WORKFLOWS/CREATE.md @@ -0,0 +1,26 @@ +# Workflow: CREATE (Study Creation) + +_Last updated: 2026-01-29 (Mario)_ + +## Goal +Create a new study via the **Create Wizard**: + +Files β†’ Introspection β†’ Context β†’ Draft β†’ Interview β†’ Validate β†’ Publish + +## Source of truth +- Draft spec (local): browser storage +- Published spec: `atomizer_spec.json` + +## Outputs required (DoD) +- `atomizer_spec.json` (published) +- `README.md` (auto-generated) +- Study folder structure created + +## Key rules +- Don’t ask user for info we can introspect. +- Ask only gap questions. +- Canvas is validation (gimmick), not the authoring source. + +## See also +- PKM: TECH-SPEC-Create-Wizard-Blueprint +- PKM: TECH-SPEC-Canvas-Study-Sync diff --git a/docs/WORKFLOWS/DELIVER.md b/docs/WORKFLOWS/DELIVER.md new file mode 100644 index 00000000..8f8c5c33 --- /dev/null +++ b/docs/WORKFLOWS/DELIVER.md @@ -0,0 +1,13 @@ +# Workflow: DELIVER + +_Last updated: 2026-01-29 (Mario)_ + +## Goal +Package everything for client delivery: +- report +- optimized model files +- optional insights html bundle +- optional DB/logs + +## Also +Archive study + capture learnings in LAC. diff --git a/docs/WORKFLOWS/REPORT.md b/docs/WORKFLOWS/REPORT.md new file mode 100644 index 00000000..16520dbf --- /dev/null +++ b/docs/WORKFLOWS/REPORT.md @@ -0,0 +1,12 @@ +# Workflow: REPORT + +_Last updated: 2026-01-29 (Mario)_ + +## Goal +Generate client-ready artifacts: +- Markdown +- HTML +- PDF (Atomizer branded template) + +## Notes +Report generation should be deterministic, with Claude optional for narrative additions. diff --git a/docs/WORKFLOWS/RUN.md b/docs/WORKFLOWS/RUN.md new file mode 100644 index 00000000..f3417cc1 --- /dev/null +++ b/docs/WORKFLOWS/RUN.md @@ -0,0 +1,16 @@ +# Workflow: RUN + +_Last updated: 2026-01-29 (Mario)_ + +## Goal +Start and reliably track long-running optimizations. + +## Requirements +- Published `atomizer_spec.json` +- Backend can start/stop processes safely + +## UI +- Live status + progress +- Convergence +- Best trial summary +- Safe stop diff --git a/docs/WORKFLOWS/VALIDATE.md b/docs/WORKFLOWS/VALIDATE.md new file mode 100644 index 00000000..8fe20868 --- /dev/null +++ b/docs/WORKFLOWS/VALIDATE.md @@ -0,0 +1,20 @@ +# Workflow: VALIDATE + +_Last updated: 2026-01-29 (Mario)_ + +## Goal +Give the user confidence that the study will run correctly: +- correct model chain +- DV bounds sane +- objectives/constraints correctly sourced +- spec is runnable + +## Primary UI +- Checklist + Parameters table + +## Secondary UI +- Canvas visualization + +## Outputs +- Validation report (errors/warnings) +- "Ready to Run" state