Consolidate agent-memory sprawl into archive/ and refresh stale planning docs

CHANGELOG.md

@@ -40,8 +40,9 @@ As of April 18, 2026 the user asked for roughly five files per response. Keep th
   `4/4 gates passed in 95.58s`; final source-clean check reported
   `cache_dirs=0 pyc_files=0 pytest_cache_dirs=0 ruff_cache_dirs=0`.
 * Finalized the physical root-debt boundary hardening wave. Runtime capped
-  live workers at six, so bounded write lanes were tracked through
-  `AGENT_GITLOG.md`. MOSFET, interconnect, lithography source/species, and
+  live workers at six, so bounded write lanes were tracked through a
+  pseudo-git coordination ledger (now archived at `archive/AGENT_GITLOG.md`).
+  MOSFET, interconnect, lithography source/species, and
   medium-response source surfaces gained boundary hardening; process geometry,
   SEMF/nuclear coefficients, source-plasma drive, medium intercomponent,
   root-debt, import, CLI, and boundary index/smoke-pack coverage were added or

HANDOFF.md

@@ -67,7 +67,7 @@ read `SESSION_STATE.md` and `VISIBLE_BACKLOG.md` first.
 Physical root-debt boundary hardening is now the previous verified handoff.
 
 - Runtime capped live workers at six, so the wave used bounded write lanes and
-  `AGENT_GITLOG.md` as a pseudo-git coordination ledger.
+  a pseudo-git coordination ledger (now archived in `archive/AGENT_GITLOG.md`).
 - Source changes landed in MOSFET, interconnect, lithography source/species,
   and medium-response surfaces.
 - Coverage expanded around process geometry, SEMF/nuclear coefficients,

IMPROVEMENT_MAP.md

@@ -1,9 +1,33 @@
 # gpu_stack improvement map
 
-Audit date: 2026-04-18 (original), live snapshot refreshed 2026-05-06.
+Audit date: 2026-04-18 (original), live snapshot refreshed 2026-06-10.
 
 ## Latest Verified Wave
 
+Portfolio form-and-deliverable polish is implemented, verified, and
+source-clean. Session memory files moved to `archive/`.
+
+- Scope: docs site typography and metadata, README example accuracy, ledger
+  reconciliation, and historical session-memory consolidation under `archive/`.
+- Docs site: three-font system (IBM Plex Sans / Pixelify Sans / IBM Plex Mono),
+  absolute Open Graph metadata, null-guarded panel renders, darkened eyebrow
+  labels.
+- README example fixes: dependency-cone sort by name; `evaluate_targets` uses
+  real variable name `training.tokens_per_sec`.
+- Moved `AGENT_DIARY.md`, `AGENT_WORKLOG.md`, `AGENT_GITLOG.md`,
+  `CODEX 5-5 START HERE.md`, `AGENT_REST_BREAKS/`, and `rest_breaks/` to
+  `archive/` to reduce root inventory noise.
+- Full pytest: `670 passed in 157.12s`.
+- Audit gate: PASS; systems 16, variables 1517, constants 24, equations 959,
+  root inputs 619, leaves 253, cycles 0, hard failures 0, large scope files 0,
+  large project files 0.
+- Full verifier: `4/4 gates passed in 157.32s`.
+- Read-only full verifier: `4/4 gates passed in 157.18s`.
+- Final source-clean check:
+  `cache_dirs=0 pyc_files=0 pytest_cache_dirs=0 ruff_cache_dirs=0`.
+
+## Previous Verified Wave
+
 Live next-work compass and scenario-audit missing-family ergonomics are
 implemented, verified, read-only verified, and source-clean.
 
@@ -29,7 +53,7 @@ Physical root-debt boundary hardening is implemented, verified, read-only
 verified, and source-clean.
 
 - Runtime capped live workers at six; bounded write lanes were tracked through
-  `AGENT_GITLOG.md`.
+  a pseudo-git coordination ledger (now archived at `archive/AGENT_GITLOG.md`).
 - MOSFET, interconnect, lithography source/species, and medium-response source
   surfaces gained boundary hardening.
 - Process geometry, SEMF/nuclear coefficients, source-plasma drive, medium
@@ -47,6 +71,8 @@ verified, and source-clean.
 
 ## Current snapshot
 
+Snapshot date: 2026-06-10.
+
 | Metric | Value |
 |---|---:|
 | Systems / scopes | 16 |
@@ -70,9 +96,9 @@ verified, and source-clean.
 | Variables with multiple defining relations, role-tagged | 53 |
 | Inequalities that simplify to `True` in `as_sympy()` | 0 |
 | Scope files at or above 700 lines | 0 |
-| Project Python files at or above 700 lines | 7 |
+| Project Python files at or above 700 lines | 0 |
 | Hard audit failures | 0 |
-| Collected pytest tests | 639 |
+| Collected pytest tests | 670 |
 
 ## Previous Verified Wave
 
@@ -182,7 +208,7 @@ Phase 3 modularization finished in pass 39. Every file in the original split map
 | `memory_cell.py` | 700 | DONE (pass 31) | `memory_sram.py`, `memory_dram.py`, `memory_flipflop.py` |
 | `parallelism.py` | 703 | DONE (pass 39) | `parallelism_batching.py`, `parallelism_zero_fsdp.py`, `parallelism_pipeline.py`, `parallelism_moe.py` |
 
-Phase 4 scenario resolver landed in pass 26 (`gpu_stack.core.resolver` plus `gpu_stack.resolve`). Phase 5 preset framework landed in pass 27 (`gpu_stack.core.presets` plus `gpu_stack.presets.*`). Phase 2 metadata helpers landed in pass 30 (`Registry.by_kind`, `Registry.by_extensivity`, `Registry.coverage`, and post-load `auto_classify_kinds`). Current compact metrics: 1517 variables, 959 equations, 619 roots, 639 collected tests. A CLI entry point landed in pass 32 (`gpu-stack stats`, `list-presets`, `resolve`). Scenario presets now include `dense_training_cost_fixture`, the first sourced/calibrated scenario pack, tin/EUV source scaffolding, SEMF calibration scaffolding, `scenarios.euv_tin120_lpp_source_context_assumption`, `scenario-report --missing-families`, `resolve --missing-families`, `Preset.evaluate_targets(...)`, `ScenarioReport`, `ScenarioTargetReport`, `MissingFamilySummary`, `scenario-report --json`, `scenario-audit`, `scenario-audit --missing-families`, `SCENARIO_TARGET_SETS`, `scenario_targets_for(...)`, and the `next-work` continuation compass.
+Phase 4 scenario resolver landed in pass 26 (`gpu_stack.core.resolver` plus `gpu_stack.resolve`). Phase 5 preset framework landed in pass 27 (`gpu_stack.core.presets` plus `gpu_stack.presets.*`). Phase 2 metadata helpers landed in pass 30 (`Registry.by_kind`, `Registry.by_extensivity`, `Registry.coverage`, and post-load `auto_classify_kinds`). Current compact metrics: 1517 variables, 959 equations, 619 roots, 670 collected tests. A CLI entry point landed in pass 32 (`gpu-stack stats`, `list-presets`, `resolve`). Scenario presets now include `dense_training_cost_fixture`, the first sourced/calibrated scenario pack, tin/EUV source scaffolding, SEMF calibration scaffolding, `scenarios.euv_tin120_lpp_source_context_assumption`, `scenario-report --missing-families`, `resolve --missing-families`, `Preset.evaluate_targets(...)`, `ScenarioReport`, `ScenarioTargetReport`, `MissingFamilySummary`, `scenario-report --json`, `scenario-audit`, `scenario-audit --missing-families`, `SCENARIO_TARGET_SETS`, `scenario_targets_for(...)`, and the `next-work` continuation compass.
 
 The remaining work from the original plan is:
 
@@ -206,8 +232,8 @@ Next highest-impact frontier: keep the scenario-artifact surface stable while ex
 | Constraint preservation | Current audit reports 0 inequalities that simplify to `True` in `as_sympy()`. The old SRAM margin collapses are now regression targets instead of live failures. | Constraints must stay inspectable as the graph grows, especially around branch conditions, approximation validity, and feasibility checks. | P1 |
 | Metadata coverage | The core supports references, unit checking, variable kinds, extensivity, shape, and dimensional expressions. The loaded model now uses most of it: 1324 non-constant variables have references, 1428 have `sp_units`, and 799 equations opt into dimensional checks. | Coverage is now broad across the model layer; the remaining gaps are visible and can be closed as focused slices. | P0 |
 | Calibration depth | There are still 619 root inputs across the graph, meaning variables with no value-defining identity, approximation, or selected variant. The first sourced/calibrated scenario pack is landed, full-verified, and source-clean. | The next frontier is reducing manual scenario assignments and making pack provenance/evaluation behavior reproducible. | P0 |
-| File cohesion | Current audit reports 0 scope files and 7 project Python files at or above 700 lines after lithography source-plasma, focused-beam, medium-response, and medium-density helper splits. | Reviewability, onboarding, and targeted regression testing stay tractable as scopes accumulate more subdomains. | Watch |
-| Verification surface | The bundle has timeout-protected smoke validation (`import`, `demo`, `compileall` or read-only syntax checking, graph health), package metadata, and 639 collected pytest tests behind the `verify` profiles; the fast profile now includes resolver tests plus the neutron-sensitive source-plasma trace test directly, and `--read-only` suppresses bytecode/pytest-cache artifacts where practical. | The project can keep growing symbolically, but regression risk will grow faster than coverage. | P0 |
+| File cohesion | Current audit reports 0 scope files and 0 project Python files at or above 700 lines after all helper splits including the portfolio-polish wave. | Reviewability, onboarding, and targeted regression testing stay tractable as scopes accumulate more subdomains. | Watch |
+| Verification surface | The bundle has timeout-protected smoke validation (`import`, `demo`, `compileall` or read-only syntax checking, graph health), package metadata, and 670 collected pytest tests behind the `verify` profiles; the fast profile now includes resolver tests plus the neutron-sensitive source-plasma trace test directly, and `--read-only` suppresses bytecode/pytest-cache artifacts where practical. | The project can keep growing symbolically, but regression risk will grow faster than coverage. | P0 |
 | User-facing evaluation | A conservative global resolver exists and computes targets from assignments through selected value relations, with symbolic-boundary missing reporting, constraint checks, approximation-validity checks, and optional strict CLI exits for violated feasibility. Scenario-report, root-debt, and `resolve --missing-families` diagnostics now share family/category grouping. The verified artifact surface includes `Preset.evaluate_targets(...)`, `ScenarioReport`, `ScenarioTargetReport`, `MissingFamilySummary`, `scenario-report --json`, and `scenario-audit` over sourced scenario packs with text/JSON output plus `--fail-on-issues`. It does not yet solve simultaneous systems or optimize over scenario choices. | The current API can run scenarios and emit structured artifacts; the highest-impact next step is selector control, broader pack reproducibility, and concise diagnostics. | P0 |
 | Packaging hygiene | Earlier artifacts included `__pycache__` output. A reproducible source-only build path still needs to be formalized. | Clean packaging matters once the repo starts moving between machines, agents, and CI. | P2 |
 

README.md

@@ -466,7 +466,7 @@ The README is the front door. The moving project ledger lives here:
 - [`./CHANGELOG.md`](./CHANGELOG.md)
 - [`./SESSION_STATE.md`](./SESSION_STATE.md)
 - [`./VISIBLE_BACKLOG.md`](./VISIBLE_BACKLOG.md)
-- [`./AGENT_DIARY.md`](./AGENT_DIARY.md)
-- [`./rest_breaks/README.md`](./rest_breaks/README.md)
+- [`./archive/AGENT_DIARY.md`](./archive/AGENT_DIARY.md)
+- [`./archive/rest_breaks/README.md`](./archive/rest_breaks/README.md)
 
-The diary and break-room files are not part of the package API. They are there because long-running work needs memory, and apparently so do the agents doing it.
+The diary and break-room files are not part of the package API. They are archived under `archive/` for provenance; long-running work needs memory, and apparently so do the agents doing it.

ROADMAP.md

@@ -1,9 +1,41 @@
 # gpu_stack roadmap
 
-Status timestamp: May 6, 2026, 23:00 America/Los_Angeles.
+Status timestamp: June 10, 2026, America/Los_Angeles.
 
 ## Latest Verified Wave
 
+Portfolio form-and-deliverable polish is implemented, verified, and
+source-clean. The wave was landed as PR #5 and merged to main.
+
+- Scope: docs site typography and metadata, README example accuracy, and
+  historical agent-session memory consolidation under `archive/`.
+- Docs site: three-font system (IBM Plex Sans for body copy, Pixelify Sans for
+  OS chrome and headings, IBM Plex Mono for commands); absolute Open Graph
+  metadata (`og:image`, `og:url`, `og:type`, `twitter:card`); leaked markdown
+  backticks became real `code` elements; dead `docs/styles.css` link and file
+  removed; `app.js` panel renders null-guarded; eyebrow labels darkened to
+  clear 4.5:1 contrast.
+- README example fixes: dependency-cone snippet sorts by name instead of
+  comparing `Variable` objects directly; `evaluate_targets` example uses real
+  variable name `training.tokens_per_sec`; root-debt block notes live
+  `top_roots` column.
+- Session memory files moved to `archive/` for provenance without root clutter.
+- Full pytest: `670 passed in 157.12s`.
+- Audit gate: PASS; systems 16, variables 1517, constants 24, equations 959,
+  root inputs 619, leaves 253, cycles 0, hard failures 0, large scope files 0,
+  large project files 0.
+- Full verifier: `4/4 gates passed in 157.32s`.
+- Read-only full verifier: `4/4 gates passed in 157.18s`.
+- Final source-clean check:
+  `cache_dirs=0 pyc_files=0 pytest_cache_dirs=0 ruff_cache_dirs=0`.
+- Current `next-work` evidence (live 2026-06-10):
+  Pythia `cost_per_token` has 33 missing inputs; top root-debt family is
+  `physical.lithography.medium` with weight 3014 across 15 roots; metadata
+  gaps are 65 variables without `sp_units`, 169 variables without references,
+  81 equations without references, 160 equations without unit checks.
+
+## Previous Verified Wave
+
 Live next-work compass and scenario-audit missing-family ergonomics are
 implemented, verified, read-only verified, and source-clean.
 
@@ -22,17 +54,14 @@ implemented, verified, read-only verified, and source-clean.
 - Read-only full verifier: `4/4 gates passed in 95.58s`.
 - Final source-clean check:
   `cache_dirs=0 pyc_files=0 pytest_cache_dirs=0 ruff_cache_dirs=0`.
-- Current `next-work` evidence keeps three live priorities visible:
-  close the Pythia cost-per-token missing frontier, pay down the
-  `physical.lithography.medium` root-debt family, and close the metadata tail.
 
-## Previous Verified Wave
+## Previously Verified Wave
 
 Physical root-debt boundary hardening is implemented, verified, read-only
 verified, and source-clean.
 
 - Runtime capped live workers at six; bounded write lanes were tracked through
-  `AGENT_GITLOG.md`.
+  a pseudo-git coordination ledger (now archived at `archive/AGENT_GITLOG.md`).
 - MOSFET, interconnect, lithography source/species, and medium-response source
   surfaces gained boundary hardening.
 - Process geometry, SEMF/nuclear coefficients, source-plasma drive, medium
@@ -48,7 +77,7 @@ verified, and source-clean.
 - Final source-clean check:
   `cache_dirs=0 pyc_files=0 pytest_cache_dirs=0 ruff_cache_dirs=0`.
 
-## Previous Verified Wave
+## Previously Verified Wave
 
 Scenario-audit selector/report ergonomics are implemented and verified.
 

SESSION_STATE.md

@@ -3,7 +3,7 @@
 Updated: 2026-06-10 PDT.
 
 Read this first after compaction or restart. It is intentionally shorter than
-`HANDOFF.md` and `CODEX 5-5 START HERE.md`.
+`HANDOFF.md`.
 
 ## Latest Verified Wave: Portfolio Form And Deliverable Polish
 
@@ -97,7 +97,7 @@ Status: implemented, verified, read-only verified, and source-clean.
   medium-intercomponent, root-debt, import, CLI, and index/smoke coverage were
   added around already-existing symbolic constraints.
 - Runtime capped live workers at six, so the wave used bounded write lanes and
-  `AGENT_GITLOG.md` as a pseudo-git coordination ledger.
+  a pseudo-git coordination ledger (now archived at `archive/AGENT_GITLOG.md`).
 - Focused parent pack: `125 passed in 33.75s`.
 - Full pytest: `628 passed in 71.99s`.
 - Audit gate: PASS; systems 16, variables 1517, constants 24, equations 959,

VISIBLE_BACKLOG.md

@@ -62,7 +62,7 @@ Status: implemented, verified, read-only verified, and source-clean.
 Facts to keep visible:
 
 - Runtime capped live workers at six, so the wave used bounded write lanes and
-  `AGENT_GITLOG.md` as a pseudo-git coordination ledger.
+  a pseudo-git coordination ledger (now archived at `archive/AGENT_GITLOG.md`).
 - The wave hardened physical roots where honest lower-level relations or
   obvious boundary semantics existed, without adding arbitrary calibration
   values.

archive/README.md

@@ -0,0 +1,30 @@
+# archive/
+
+This directory holds historical agent-session memory files moved from the
+repository root on 2026-06-10. The files are kept byte-identical for
+provenance. They are not operational ledgers: they record the inner thread of
+earlier agent sessions, coordination pseudo-git-log entries, break-room pauses,
+and session start-here instructions from the first large pass of the project.
+
+## What lives here
+
+| Path | Original location | What it was |
+|---|---|---|
+| `AGENT_DIARY.md` | `./AGENT_DIARY.md` | Inner thread of session work: focus, uncertainty, and non-operational texture from each agent wave. |
+| `AGENT_WORKLOG.md` | `./AGENT_WORKLOG.md` | Pseudo-git-log coordination ledger for multi-agent waves; superseded by CHANGELOG.md and HANDOFF.md. |
+| `AGENT_GITLOG.md` | `./AGENT_GITLOG.md` | Git-log-style worker progress table for bounded multi-agent write lanes. |
+| `CODEX 5-5 START HERE.md` | `./CODEX 5-5 START HERE.md` | Session start-here instructions from the physical root-debt boundary hardening wave (2026-05-05). |
+| `AGENT_REST_BREAKS/` | `./AGENT_REST_BREAKS/` | Compatibility pointer to canonical rest-break notes; see `rest_breaks/`. |
+| `rest_breaks/` | `./rest_breaks/` | Short subjective pause notes from the 2026-05-06 session. |
+
+## Why they are here and not at root
+
+The four canonical operational ledgers at root are:
+`CHANGELOG.md`, `SESSION_STATE.md`, `HANDOFF.md`, and `VISIBLE_BACKLOG.md`.
+Planning docs are `ROADMAP.md` and `IMPROVEMENT_MAP.md`. Reference docs are
+`README.md`, `PRODUCT.md`, and `DESIGN.md`.
+
+The files archived here are per-session memory artifacts. They do not serve
+day-to-day project navigation. Keeping them at root added noise to the root
+inventory without adding operational value. They are preserved here in full
+for historical reference.

docs/app.js

@@ -274,7 +274,7 @@ if (primerText && primerFacts && primerStatusTitle && primerStatusBody) {
 if (layerText && layerFacts && stack) {
   renderLayer("datacenter");
 }
-if (traceSummary && traceFacts && tracePath && traceNote && traceMeter) {
+if (traceSummary && traceFacts && tracePath && traceNote && traceMeter && traceMeterLabel && traceMeterFoot) {
   renderTrace("cost");
 }
 if (clock) {

docs/readme_fragments/readme_qa_checklist.md

@@ -53,7 +53,7 @@ Prepared 2026-05-11 18:11 America/Los_Angeles for a README rewrite into a Medium
 - Keep tables narrow enough for GitHub mobile rendering. The full scope inventory table is wide and may need splitting, collapsing into bullets, or moving to a fragment.
 - Escape or fence symbols that Markdown can mangle: `*`, `_`, `<`, `>`, `|`, `<=`, `>=`, `D <= 2U`, `(U + D) mod 3 = 0`, `x_LL > -1/2`, `gpu-stack root-debt --families`.
 - Use inline code for variable names, equation names, CLI flags, package names, and file paths.
-- Keep relative links stable from the repository root: `./IMPROVEMENT_MAP.md`, `./ROADMAP.md`, `./HANDOFF.md`, `./CHANGELOG.md`, `./AGENT_DIARY.md`, `./rest_breaks/README.md`.
+- Keep relative links stable from the repository root: `./IMPROVEMENT_MAP.md`, `./ROADMAP.md`, `./HANDOFF.md`, `./CHANGELOG.md`, `./archive/AGENT_DIARY.md`, `./archive/rest_breaks/README.md`.
 - If badges or images are added later, verify they do not depend on private state or dead external URLs.
 - Avoid raw Unicode math if the repo stays ASCII. Prefer fenced or inline code for equations unless the README already accepts richer typography.
 - Ensure headings descend cleanly. Do not jump from `##` to `####` for visual styling.