# Session Synthesis — 2026-06-08

**Track:** TBD (session archive)
**Date:** 2026-06-08
**Author:** Tier 2 Tech Lead (synthesis)
**Status:** Final session digest; written at the user's explicit request to preserve as much as possible
**Scope:** Every artifact produced in this session, cross-referenced with the source material that informed it

> **Why this document exists.** The user signaled that the conversation had reached 478,992 tokens (94% of context window). This is a *preserve-before-compact* archive: the next time the conversation resumes (with a fresh context window), this report + the 5 source transcripts + the new docs guides + the user's chunk ideation archive are the minimum-sufficient context to re-anchor.
>
> **What's in it.** A guided tour through every artifact this session produced, the questions each one answered, the constraints it left behind, and the *open questions* that a future session can pick up. The report is organized by *information flow* (the order the user asked for things), not by artifact type, because the artifacts are deeply interconnected.
>
> **The 5 sources, named upfront:** (1) Ryan Fleury, "A Taxonomy of Computation Shapes" (Feb 2023); (2) Ryan Fleury, "The Codepath Combinatoric Explosion" (Apr 2023); (3) Casey Muratori, "The Big OOPs: Anatomy of a Thirty-Five-Year Mistake" (BSC 2025, wo84LFzx5nI); (4) Andrew Reece, "Assuming as Much as Possible" (BSC 2025, i-h95QIGchY); (5) the user's chunk-ideation archive (May 2026, 5 Discord messages + images). All 5 are now committed to `docs/transcripts/` and `docs/ideation/`.

---

## 0. The session in one paragraph

The session started with the nagent_review track (9cc51ca9, 7 files, 1784 lines) and a docs refresh (ba051684, 11 files, 1180 lines). The nagent_review was a deep-dive of Mike Acton's `macton/nagent` reference implementation against Manual Slop's actual code; it produced 14-section report, comparison_table, 10-track decisions.md, and 10-pattern takeaways.md. The docs refresh added 3 new deep-dive guides (Discussions, State Lifecycle, Context Aggregation) and cross-linked 8 existing guides. A link-fix commit (161ebb0d) corrected case-sensitivity and wrong relative-path levels across 24 docs files. The 4 major upcoming tracks (qwen_llama_grok, data_oriented_error_handling, data_structure_strengthening, mcp_architecture_refactor) then got spec/plan updates informed by the nagent_review + docs refresh findings (4 separate atomic commits). The ASCII-sketch UX workflow was prototyped as a future-track report. Finally, the user introduced the *5-source loading request*: 2 YouTube transcripts + 2 Fleury articles + the user's chunk-ideation, all to ground the upcoming `code_path_audit_20260607` track. The user committed the transcript/ideation files themselves; I wrote the post-4-tracks timing + 5-source framing update to the code_path_audit spec/plan.

---

## 1. The nagent_review track (commit 9cc51ca9)

**Track directory:** `conductor/tracks/nagent_review_20260608/`

### What got built (7 files, 1,784 lines)

| File | Lines | Purpose |
|---|---|---|
| `spec.md` | 240 | Track wrapper; Application vs Meta-Tooling domain distinction; 6-pitfall summary; user-corrections revision note |
| `report.md` | 571 | 14-section deep-dive analysis; primary deliverable |
| `comparison_table.md` | 79 | Flat side-by-side reference; 14 rows |
| `decisions.md` | 286 | 10 future-track candidates with priority matrix |
| `nagent_takeaways_20260608.md` | 363 | 10 actionable patterns grounded in code |
| `metadata.json` | 132 | Structured metadata + verification criteria |
| `state.toml` | 113 | Per-task tracking + user-corrections log (7 entries) |

### The 14 nagent principles covered in report.md

1. Durable work, disposable workers
2. Text in, text out
3. Conversations are editable state (with the A1-A7 + B1-B11 + C1-C5 operation matrix)
4. Visible output protocol (regex tags vs opaque function calling)
5. The loop (append, call, parse, act, repeat)
6. Per-file memory (curation, not conversation log)
7. Repository history as data
8. Historical coupling & artifact neighborhoods
9. Disposable sub-conversations (the `<nagent-conversation>` tag)
10. Controlled writes
11. Large files as explicit artifacts (split/patch/summarize)
12. Tool discovery (self-describing executables)
13. Differences from frameworks
14. Build your own

### The 6 pitfalls (revised from 8 after 3 rounds of user corrections)

1. **No structured output protocol in Application AI** (opaque function calling) — Domain: Both (Application can keep opaque; Meta-Tooling should learn)
2. **Provider-specific history in process globals** — `ai_client._anthropic_history`, `_deepseek_history`, `_minimax_history` (lines 123-132) are the code refs. Domain: Application
3. **RAG is not "history as data"** — fuzzy, not auditable. Domain: Application
4. **The AI client is a stateful singleton with module-level globals** — 2,685-line `ai_client.py`. Domain: Application
5. **No non-MMA disposable sub-conversations** — 1:1 gap (the user-flagged want). Domain: Application
6. **Hard-coded tool discovery** — 45-tool if/elif chain in `mcp_client.py:dispatch`. Domain: Both

### The 10 actionable takeaways (in `nagent_takeaways_20260608.md`)

Each has WHAT it does + Domain tag + Effort + File:line refs.

1. **State visibility** — "Live State Inspector" panel (small effort)
2. **Readable conversation log** — text-greppable, not just JSON-L
3. **Sub-agents for 1:1** — HIGH priority, user-flagged (`SubConversationRunner`)
4. **File identity over file path** — `st_dev:st_ino` rename-safe
5. **One loop shape visible in diagnostics**
6. **Visible retry on protocol failure**
7. **Meta-Tooling DSL** — deferred, intent-based
8. **Self-describing tools** — subsumed by `mcp_architecture_refactor_20260606`
9. **Edit-the-input, not the output** — single source of truth for `disc_entries` + provider history
10. **Sub-agent return type** — design constraint: concise artifact, not full transcript

### 3 rounds of user-corrections (recorded in state.toml `[user_corrections_log]`)

Round 1 (first draft overstatements):
- Editable discussions: PARTIAL → PARITY (DIFFERENT FOCUS)
- Per-file memory: DOMAIN MISMATCH → MANUAL SLOP IS STRONGER IN CURATION DIMENSION
- Sub-conversations: removed "PARITY stronger" claim; added "GAP for 1:1 discussions" + user-flagged "want" for future sub-conversation track
- RAG: clarified as opt-in, not gap; user wants pre-staging via sub-conversation
- Personas: reframed as config bundling (can opt out via AI settings)
- Tool discovery: downgraded to "intentional, low priority" (user has deferred DSL idea)

Round 2 (after reading the A1-A7 / B1-B11 / C1-C5 operation matrix):
- Editable discussions: REVISED. Report §3 now enumerates the full per-entry (A1-A7) + discussion-level (B1-B11) + undo/redo (C1-C5) operation matrix with file:line citations into `gui_2.py:3770-3853` and `history.py`.

The user-driven insights from these corrections:
- Manual Slop's discussion system is *much* more capable than the first draft acknowledged. The 23-operation matrix captures the full surface.
- "Editable" doesn't mean what the first draft assumed. Manual Slop edits *abstracted entries* (`disc_entries: list[dict]` with role/content/ts/etc.), not *raw transcripts*. The abstraction layer is intentional.
- Per-file memory is a *curation* concept in Manual Slop (`FileItem` with 9 fields + `ContextPreset` + Fuzzy Anchors), not a *conversation log* concept. nagent's per-file memory is the latter; Manual Slop's is the former. The two are complementary, not equivalent.

---

## 2. The docs refresh (commit ba051684)

**Scope:** 11 files, 1,180 lines

### 3 new deep-dive guides

1. **`docs/guide_discussions.md` (353 lines)** — The Discussion system
   - 23-operation matrix: A1-A7 per-entry + B1-B11 discussion-level + C1-C5 undo/redo
   - Take naming convention (`<base>_take_<n>`)
   - User-managed role list (`app.disc_roles`)
   - Per-role filter linked to MMA persona focus
   - `_disc_entries_lock` thread-safety contract
   - Hook API session endpoints (`/api/session`)
   - Persistence: `_flush_to_project`, `_flush_disc_entries_to_project`, `context_snapshot`
   - 9 file:line refs into `gui_2.py:3770-4260` + `history.py`

2. **`docs/guide_state_lifecycle.md` (375 lines)** — Undo/redo + reset + state delegation
   - `HistoryManager` + `UISnapshot` (13 captured fields, 100-snapshot capacity)
   - Debounced change-detection at render frame (`gui_2.py:1140-1170`)
   - `_handle_reset_session` (clears 30+ fields, replaces project, preserves `active_project_path` per the 2026-06-08 regression fix)
   - `App.__getattr__`/`__setattr__` state delegation to Controller (`gui_2.py:666-675`)
   - 8-thread io_pool with 11 lock-protected regions (bumped 4→8 in 4a338486 on 2026-06-06; this report predates the bump)
   - State persistence: in-memory vs project TOML vs config TOML
   - Hot-reload integration
   - 14 file:line refs into `gui_2.py:735-789`, `history.py`, `app_controller.py:3286-3356`

3. **`docs/guide_context_aggregation.md` (394 lines)** — The `aggregate.py` pipeline
   - 3 aggregation strategies (`auto`, `summarize`, `full`)
   - 7 per-file view modes (`full`, `summary`, `skeleton`, `outline`, `masked`, `custom`, `none`)
   - Full `FileItem` schema (9 fields + `__post_init__` normalizer) at `models.py:510-559`
   - `ContextPreset` schema and `ContextPresetManager` at `models.py:909-937`
   - Tier 3 worker variant (`build_tier3_context` with FuzzyAnchor re-resolution)
   - `force_full` / `auto_aggregate` short-circuits
   - Cache strategy (static prefix + dynamic history)
   - 23 file:line refs into `aggregate.py:36-518` + `models.py:909-937`

### 8 cross-link updates to existing guides

`guide_gui_2.md`, `guide_app_controller.md`, `guide_context_curation.md`, `guide_architecture.md`, `guide_ai_client.md`, `guide_mma.md`, `guide_models.md`, `Readme.md` — each got new "See Also" entries pointing to the 3 new guides + (where applicable) the nagent_review findings.

### Why these 3 guides specifically

The user's editorial choice was based on:
- **Discussions** — the most-edited surface; the 23-operation matrix is the source of truth
- **State Lifecycle** — the undo/redo + reset + state-delegation architecture is load-bearing
- **Context Aggregation** — `aggregate.py` is the most-touched module after `ai_client.py`, and nagent_review confirmed it's Manual Slop's strongest curation dimension

---

## 3. The link-fix commit (commit 161ebb0d)

**Scope:** 24 files, 37 character-level replacements

### The 3 bugs found

1. **Case sensitivity (22 occurrences):** `[Top](../README.md)` was broken on Linux/Gitea because the actual file is `docs/Readme.md` (capital R). 22 occurrences across 22 files. Fix: `../README.md` → `../Readme.md`.

2. **Wrong relative-path level (16 occurrences):** Many of my nagent_review cross-references used `../../conductor/...` from `docs/guide_*.md`. This goes up 2 levels to `projects/`, not the intended `manual_slop/`. Fix: `../../conductor/` → `../conductor/`.

3. **Planned-guide link (1 occurrence):** `guide_context_curation.md` linked to a never-written `guide_context_presets.md`. The schema is now fully covered in the new `guide_context_aggregation.md`. Fix: link target updated.

### Why these bugs existed

- **Case-sensitivity** was hidden by Windows' case-insensitive filesystem. Lesson: when writing cross-platform docs, always verify link case against the actual filename.
- **Wrong level** was probably never working at all, just never reported. Lesson: when adding a link, verify in a POSIX-style path resolution, not the dev's filesystem.
- **Planned guide** is a docs-as-code maintenance hazard. Lesson: "planned" links in shipped docs should be removed or implemented within the same track.

---

## 4. The 4 major-track spec/plan updates (commits 77ae2ec7, 0471440c, 1fb0d79c, 8a597d18)

Each got ~4 surgical spec edits + See Also cross-references. No plan/task changes.

### 4.1 `qwen_llama_grok_integration_20260606` (commit 77ae2ec7)

**4 surgical edits:**

1. **`send_openai_compatible()` returns `Result` from day 1** — coordination note in §3.1. Per nagent_review Pitfall #4, the helper should return `Result[NormalizedResponse, ErrorInfo]` from day 1, so the downstream data_oriented_error_handling track is a small mechanical pass.

2. **Capability matrix is declarative read, not behavioral dispatch** — clarification in §6. Per nagent_review Pitfall #1 (opaque function calling in the Application is correct), UI elements are visible/enabled/disabled/hidden but the *behavior* they invoke is unchanged.

3. **`models.PROVIDERS` is the source of truth** — note in §3.2. The capability registry reads from this constant, not a parallel list.

4. **Docs touchpoint in Phase 6** — added per the docs Refresh Protocol.

### 4.2 `data_oriented_error_handling_20260606` (commit 0471440c)

**2 surgical edits:**

1. **New `ErrorKind.PROVIDER_HISTORY_DIVERGED_FROM_UI`** — added to the `ErrorKind` enum. Per nagent_review Pitfall #4 (provider history divergence), the new kind makes the divergence *detectable* and *reportable*. The follow-up `public_api_migration_20260606` is the natural moment to unify the two history layers.

2. **State-delegation regression tests mandate for Phase 3** (the ai_client refactor, highest-risk). Per `docs/guide_state_lifecycle.md` (the new guide from commit ba051684), the `App.__getattr__`/`__setattr__` pattern means a partial refactor would manifest as silent `AttributeError` deep in test code, not at the refactor commit boundary. The new tests exercise: `app.temperature = 0.5` round-trip, `controller.disc_entries[i].content = "..."` reflected in next `send_result()`'s messages, the 3 per-provider history locks serialize correctly under concurrent `send_result()` calls.

### 4.3 `data_structure_strengthening_20260606` (commit 1fb0d79c)

**3 surgical edits:**

1. **New `ProviderHistoryMessage` alias** — added to `src/type_aliases.py` aliases. Per nagent_review Pitfall #4, the UI/curation layer (`HistoryMessage`, edited via `disc_entries[i].content`) and the SDK layer (`ProviderHistoryMessage`, the bytes actually replayed to the LLM) are *distinct*. Conflating them perpetuates the bug. The follow-up `public_api_migration_20260606` is the natural moment to unify.

2. **`FileItem` alias points to the existing `models.FileItem` dataclass, not `Metadata`** — per `docs/guide_context_aggregation.md` (the new guide), `FileItem` is a 9-field dataclass with a `__post_init__` normalizer. Aliasing it to `dict[str, Any]` would lose the type safety.

3. **`gui_2.py` and `mcp_client.py` as follow-up** in §"Out of Scope" — these two files are the next targets after the 6 high-traffic files complete, rather than implied-already-handled.

### 4.4 `mcp_architecture_refactor_20260606` (commit 8a597d18)

**4 surgical edits:**

1. **`list_tool_schemas()` on the `SubMCP` Protocol** — added to §3.1. Per nagent_review Pitfall #6 + takeaway #5, each sub-MCP advertises its own capabilities. The equivalent of nagent's `collect_bin_tool_descriptions` per sub-MCP.

2. **Security model is the contract** — new "Important" note in §3.3. The 3 layers (Allowlist → Path Validation → Resolution Gate, per `docs/guide_mcp_client.md`) are not just refactored — they are the **contract** between `MCPController` and the sub-MCPs. Sub-MCPs receive a pre-validated Path and trust it. They do NOT re-validate.

3. **Docs touchpoint in Phase 7** — added per docs Refresh Protocol.

4. **See Also cross-references** — 8 new entries.

---

## 5. The ASCII-sketch UX workflow (no commit, written to `docs/reports/ascii_sketch_ux_workflow_20260608.md`)

**Track:** TBD (workflow prototype, not a track)
**Date:** 2026-06-08
**Status:** Draft for later pickup

### The 5 open questions the report surfaces

1. **Vocabulary preference** — the §2 vocabulary (`[I]`, `->`, `o->`, etc.) is a proposal. Alternatives: box-drawing characters (`┌─┐│└─┘`) for more ASCII-art look; Markdown tables for tabular content; hybrid (ASCII boxes for layout, tables for tabular data).

2. **Comparison policy** — after locking a design, do we always verify with `MiniMax understand_image` (slow but accurate)? Only when the design uses color/custom drawing? Only when the implementing Tier-3 reports a mismatch?

3. **Storage location** — designs in the track's `spec.md` as an appendix, in a separate `conductor/designs/` directory, or in a new `docs/designs/` directory?

4. **Tooling** — the workflow is currently manual. Future tooling could: render ASCII to a real ImGui panel scaffold; compare ASCII to screenshot via `MiniMax understand_image` and flag deltas; version-control designs as diffable text files.

5. **Frequency** — every panel change (overhead ~10 min), only new panels, or only when explicitly requested?

### Recommended first target (per the report)

**The per-entry rendering of the Discussion Hub** (`gui_2.py:3770 render_discussion_entry`) — the 23-operation matrix from `guide_discussions.md` is the source of truth; the current `gui_2.py:3770` is the existing implementation. The user has strong opinions here per the nagent_review discussion-system corrections. ImGui's regular layout makes ASCII a good proxy.

### The first sketch (proposed in the report)

```
+------------------------------------------------------------------+
| [+/-] Entry #3   [Role: AI       v]  [Edit]   @2026-06-08T12:34  |  <- header
|                                                       in:120 out:340
|       in:120  out:340                                       |
+------------------------------------------------------------------+
|                                                                  |
|  [thinking trace: <click to expand>]                             |  <- thinking
|  "I think the right approach is to split the parser              |     body
|   into two phases..."                                           |
|                                                                  |
|  ---collapsed: rest of 8,200 chars---                           |
+------------------------------------------------------------------+
| [Ins]  [Del]  [Branch]  I noticed that foo.py:42 uses an...     |  <- footer
+------------------------------------------------------------------+
```

The user's critique of this sketch is the next step (not done in this session).

---

## 6. The 5-source loading and synthesis (this turn)

### 6.1 The user's request

The user asked for:
1. **Two YouTube transcripts** — Casey Muratori "Big OOPs" (wo84LFzx5nI) and Andrew Reece "Assuming as Much as Possible" (i-h95QIGchY)
2. **Two Fleury articles** — "A Taxonomy of Computation Shapes" and "The Codepath Combinatoric Explosion"
3. **The user's chunk-ideation archive** (5 Discord messages + images from May 2026)
4. **All to ground the `code_path_audit_20260607` track**

The user's intent: *the audit should run after the 4 major tracks complete*. The 5 sources should inform the audit's *analytical framing* — what to look for in the 3 actions (AI message lifecycle, discussion save/load, GUI startup).

### 6.2 The transcripts (fetched via `youtube-transcript-api`)

#### `wo84LFzx5nI_big_oops_casemuratori.txt` — 4,310 segments, 200KB

Casey Muratori's BSC 2025 talk. The 3 key passages I extracted (with line numbers):

- **L356-360, [11:02-11:12]:** The core thesis, verbatim: *"I'm saying this was a mistake: the idea that you're going to draw encapsulation boundaries around these compile time hierarchies that are based off of whatever you're trying to write."*
- **L442-448, [13:51-14:02]:** Alan Kay's "soured on inheritance" quote: *"Inheritance was like really powerful, but people just didn't know how to use it. Novices and experts apparently both couldn't use it."* Muratori uses this to argue the OOP creators themselves admitted the design was broken.
- **L1414-1516, [45:40-49:41]:** Hoare's 1966 "Record Handling" paper introduced discriminated unions (called "inspect" in Simula). Stroustrup removed them when building C++ "because they broke modularity." Simula had them. C++ should have kept them. *"Really the whole string is about us getting a really bad version of discriminated unions. We had them already and now we don't have them."*

The historical genealogy Muratori traces (in the transcript):
- **Doug Ross's 1956 plex** — first struct + function pointers
- **Ivan Sutherland's 1963 Sketchpad** — first interactive graphics; constraint solver as system
- **Tony Hoare's 1966 "Record Handling"** — discriminated unions (the lost design)
- **Dahl & Nygaard's 1962/1967 Simula** — classes; also had discriminated unions via "inspect"
- **Alan Kay's 1972 Smalltalk** — message passing; Smalltalk-72 had NO inheritance
- **Stroustrup's 1980s C++** — for his own distributed-systems work, not for teams; removed discriminated unions

The concrete example: **Looking Glass Studios' Thief: The Dark Project (1998)** — the first commercially shipped Entity Component System. Encapsulation boundaries drawn around *systems* (physics, combat, AI), not *entities*. ECS emerges as the correct pattern.

#### `i-h95QIGchY_assuming_as_much_as_possible_andrewreece.txt` — 3,719 segments, 162KB

Andrew Reece's BSC 2025 talk. Key passages:

- **L1267, [56:42]:** The Xar (Exponential Array) — *"I looked around for this. I couldn't see anyone talking about it although I'm sure that other people have done it. Given that I couldn't find a name I've come up with the name exponential array um or XAR for short."*
- **L1267-1330, [56:42-59:00]:** The Xar header is *only 8 bytes* (fits in a register on Windows/Linux calling conventions) because Reece packs element size + chunk size + number of chunks into 8 bytes. This is the "treat bytes as first class citizens" point.

The Xar properties:
- Fixed-size chunks (exponential growth: chunk 0 = N, chunk 1 = 2N, chunk 2 = 4N, etc.)
- 32 chunks can address ~4GB comfortably on 64-bit
- O(1) append (no realloc copy)
- O(1) random access via bitwise divmod (chunk_index = i >> log2(chunk_size); offset = i & (chunk_size - 1))
- Pointer stability (existing elements never move)

The Q&A reveals Reece's actual use case: *the timeline debugger's events are already sorted by time, so he doesn't sort; he binary searches at the known timeline start.* This is exactly Manual Slop's `comms.log` pattern.

### 6.3 The Fleury articles (read in full)

#### "A Taxonomy of Computation Shapes" (Feb 2023)

The 6 shapes: instruction, codepath, wide codepath, codecycle, wide codecycle, codecycle graph. The mental model for thinking about computation as data flow.

#### "The Codepath Combinatoric Explosion" (Apr 2023)

The "effective codepath" concept: collapse N real codepaths into 1 effective codepath via invariants. The 5 defusing techniques:
1. **Nil sentinel** (collapses "is this valid?" to "yes")
2. **Generational handle** (collapses "is the entity still alive?" to "yes")
3. **Effective-codepath pattern** (the abstract form: introduce a subsystem that returns a value valid in all cases)
4. **Immediated-mode API** (collapses "did I create/destroy this?" to "no, it's managed for me")
5. **Reece's Xar** (collapses the `realloc`+copy branch by assuming power-of-2 chunk sizes)

### 6.4 The user's chunk-ideation archive (5 images, 19KB)

The user posted these Discord messages on 2026-05-23, articulating the *chunk principle* for scalable data structures. The full archive is at `docs/ideation/ed_chunk_data_structures_20260523.md`.

The core principle: *"the fundamental thing you have to preserve or utilize with any data structure thats multi-element is fixed sized slices. You don't have to bake the fixed size for the slice at comp time but you must always decide a fixed size heuristic to use. As soon as you do that you can lego a bunch of things and they will nearly always last longer and perform better than if you assumed an indefinite linear tape or array for storage, or some arbitrary fragmentation storage pool."*

The distillation code:
```cpp
for (auto& element : DataStructure)
{
    // do stuff with chunks elements, but the chunk indirection is handled for you.
}
for (auto& Chunk : DataStructure) for (auto& element : Chunk)
{
    // do stuff with chunks elements, you handle chunk awareness
}
SomeThreadBatch per_thread_work;
if first_arriving_thread() do planner_figure_out_the_split(DataStructure, per_thread_work);
sync_wait_for_planner_thread();
for (auto& Chunk : per_thread_work[thread_id].DataStructure) for (auto& element : Chunk)
{
    // Do stuff with chunks element which have been distributed to threads.
}
```

The 4 common objections + rebuttals:
1. **"Wasted memory"** (internal fragmentation) — already wasting memory; OS pages; only the *very last* chunk is wasted
2. **"Double indirection is slow"** — bitwise math is ~1 cycle, L1 cache hit is ~3-4 cycles, RAM fetch is ~100-300 cycles
3. **"Polymorphic soup"** — split them up; one chunk for Cars, one for Trucks
4. **"Dangling pointer panic"** — use generational handles (chunk index + element index + generation counter)

The postscript question-to-self: *"But Ed what if you want todo handles to entities and you want to enqueue processing of those entities."* Answer: get a chunk resolver, intrusive flag in the entity, segregated chunk whitelist.

The Lottes/GPGPU bitmask connection (mentioned but not detailed): the user notes a similar pattern with bitmasks exists in GPGPU work but doesn't have the notes; the Lottes connection is to instruction-set SIMD/MIMD alignment.

### 6.5 The synthesis: 4 audit-time heuristics

From the 5 sources, the following 4 concrete heuristics emerged for the code_path_audit:

1. **Effective-codepath count** — when a function has 3+ branches that all do roughly the same thing with different inputs, report "this is N real codepaths behaving as 1 effective codepath — could be defused with a nil sentinel or generational handle." The runtime-profiling follow-up measures the actual savings.

2. **Entity-hierarchy fingerprint** — when a function's `state_mutations` list has > 3 writes to a single `self.X` with a `type` discriminator, report "this function is operating on entity-hierarchy state; consider ECS split into components + systems." A concrete Manual Slop example the audit should catch: any function that does `if self.active_ticket.kind == TicketKind.X:` and then mutates multiple fields.

3. **Assumed-too-much detector** — when a function calls `ast.parse` (or any `tree_sitter.*`) on a file that *could be assumed* to be already-parsed (because the file is in the context composition and the `aggregate.py` pipeline has already done it), report "this is re-parsing data that was already parsed upstream; consider memoizing or threading the parsed AST through." This is the "assume as much as possible" pattern at the data-passing level.

4. **Chunkification candidates** — when a function loops over a `list[dict]` with a known uniform shape (heuristic: all dicts have the same key set), report "consider chunkifying — uniform data, hot path, no chunk awareness." The user has explicit code for the chunk pattern, so the audit's optimization candidates can cite it.

### 6.6 The 5-source alignment matrix (added to the audit spec)

| Source | Lens the audit inherits |
|---|---|
| Fleury Taxonomy | 6 shapes; the audit's `trace_action` is a codepath visualization; `redundancy` field detects wide codepaths |
| Fleury Combinatoric | Effective codepath concept; `pipelining_candidates` field detects defusing opportunities |
| Muratori Big OOPs | 35-year-historical indictment; `state_mutations` index reveals entity-hierarchy vs system pattern |
| Reece Assuming | "Assume as much as possible" discipline; the `expensive_ops` index asks "can this caller assume a smaller input domain?" |
| User's chunk ideation | Fixed-size slices + ECS archetype tables; per-function list loops flagged for chunk awareness |

---

## 7. The code_path_audit_20260607 spec/plan updates (commit a9333bbb)

**Scope:** 3 files, 55 insertions, 2 deletions

### The 3 surgical additions

1. **§"Timing"** (new section in spec.md, plus a "Timing" callout in plan.md)
   - The audit must run *after* the 4 foundational tracks ship
   - The 4 tracks will significantly reshape `src/ai_client.py`, `src/mcp_client.py`, `src/app_controller.py`, `src/type_aliases.py`
   - Running on pre-refactor code would produce a stale report
   - Pre-flight check: verify all 4 tracks are `[x]` completed in `conductor/tracks.md` before starting

2. **§"Analytical Framing (5-source lens)"** (new section in spec.md)
   - Maps each of the 5 sources to specific audit-time heuristics
   - 4 concrete heuristics (effective-codepath count, entity-hierarchy fingerprint, assumed-too-much detector, chunkification candidates)
   - The heuristics shape REPORT INTERPRETATION, not the static cost model (which stays data-grounded)

3. **6 new See Also cross-references** in spec.md

### The pre-flight check (specified in §"Timing")

The Tier 2 Tech Lead should verify before starting Phase 1:
1. `qwen_llama_grok_integration_20260606` is marked `[x]`
2. `data_oriented_error_handling_20260606` is marked `[x]`
3. `data_structure_strengthening_20260606` is marked `[x]`
4. `mcp_architecture_refactor_20260606` is marked `[x]`

If any of the 4 are still `[~]` in-progress, this track is blocked.

---

## 8. Final assessment: do any new tracks need to be devised?

**Short answer: yes, 2 — and both are *sub-tracks* of work already represented, not net-new initiatives.**

### 8.1 New track: `manual_ux_validation_20260608_PLACEHOLDER`

**Why:** The ASCII-sketch UX workflow (commit: docs/reports/ascii_sketch_ux_workflow_20260608.md) is a *tool* without a *track*. The workflow needs:
- A sub-spec inside the existing `manual_ux_validation_20260302` track (which is currently spec ✓, plan ✓, no metadata, no state, in the backlog)
- At least one panel redesigned using the workflow (the Discussion Hub per-entry panel is the recommended first target per the report)
- 5 open questions resolved (vocabulary preference, comparison policy, storage location, tooling, frequency)

**Effort:** Small. Could be a 1-3 phase addendum to `manual_ux_validation_20260302`.

**Domain:** Application. The UX workflow produces design contracts that drive the Application's GUI; it doesn't affect the Meta-Tooling.

### 8.2 New track: `chunkification_optimization_20260608_PLACEHOLDER`

**Why:** The user's chunk-ideation archive + Reece's Xar + Muratori's ECS archetype tables collectively describe a *specific* optimization pattern: replace `realloc`-style growable buffers with chunk-based data structures. Manual Slop has obvious candidates (the `comms.log` ring buffer, the `summary_cache`, the `LogRegistry`, the per-session screenshot lists). This is *not* a future-track candidate in the existing 10 (nagent_review's `decisions.md`); it's a new concrete track.

**Effort:** Medium. ~2-3 phases: (1) audit current growable buffers and pick the highest-value target; (2) implement chunkification for that one; (3) document the pattern in a code_styleguides entry so future code follows it.

**Domain:** Both. The Application's `comms.log` is the primary target; the Meta-Tooling's `mma_exec.py` logs are secondary.

**Specific first target:** The `comms.log` ring buffer in `app_controller.py:716` (`_comms_log: List[Dict[str, Any]]`). The events are append-heavy, read-heavy for the recent tail, and the *timestamps are already sorted* (per Reece's Q&A — his use case is the same shape). A chunk-based version with the Xar pattern (8-byte header, power-of-2 chunks, bitwise divmod) would eliminate the reallocation spikes that occur in long sessions.

### 8.3 Tracks I considered but *did not* recommend

- **"nagent_review part 2"** — no. The 14-section deep-dive, the 6 pitfalls, and the 10 actionable takeaways are complete. The user-corrections closed the open questions. Nothing new to add unless a new nagent release happens.

- **"computational_shapes_ssdl" as a track** — no. The SSDL digest is a *vocabulary* (a styleguide), not a *track*. It belongs in `conductor/code_styleguides/computational_shapes_ssd.md` as a reference. The vocabulary is *used by* other tracks (e.g., the `code_path_audit`'s `actions/<action>.tree` output), not *implemented by* a track.

- **"transcript_pipeline"** — no. The `youtube-transcript-api` tool was used once; a track would be over-engineering. The 5 transcripts in `docs/transcripts/` are committed artifacts, not a pipeline.

- **"ECS migration of tickets"** — no. This is *implicit* in the upcoming `mcp_architecture_refactor_20260606` (sub-MCPs operate on tickets-as-components) and in the `code_path_audit_20260607` (the entity-hierarchy fingerprint heuristic). A standalone "ECS migration" track would duplicate work.

- **"data-oriented rewrite of ai_client"** — no. The `data_oriented_error_handling_20260606` track + the nagent_review takeaways #9 (edit-the-input) + the user's chunkification archive collectively drive this. A standalone track would be a step backward from the coordination.

- **"Manual Slop port to Odin/Jai"** — out of scope. The user mentioned Lottes and GPGPU bitmasks but that's a future-ideation, not a near-term track.

### 8.4 The deeper insight

The pattern this session established is that **most "new tracks" are not net-new initiatives; they're *coordination notes* across already-planned work**. The 4 major tracks have spec/plan updates that coordinate them. The `code_path_audit` is the post-4-tracks ground-truth check. The `manual_ux_validation` is the workflow + first target. The `chunkification_optimization` is a concrete first application of the chunk principle.

The **true value** of this session was:
- The nagent_review: a 7-file deep-dive that crystallized Manual Slop's relationship to the data-oriented tradition
- The docs refresh: 3 new deep-dive guides that fill the largest documentation gaps
- The link fix: 24 files of nav-link corrections that make Gitea usable
- The 4 spec/plan updates: cross-track coordination that prevents the 4 sprints from stepping on each other
- The 5-source synthesis: a unified lens (computational shapes + data-oriented + chunkification + assume-as-much-as-possible) for all future work
- The audit framing: the post-4-tracks timing + 4 concrete heuristics for the audit

The 10 new track candidates in `nagent_review/decisions.md` + the 2 new tracks I just proposed (manual_ux_validation, chunkification_optimization) = **12 future tracks** in the pipeline. This is the *right* amount of work to have in flight, given the project's size and the user's stated preference for "keeping MMA cold until I dogfood the main UX loop."

---

## 9. What the user should know

### What you asked for vs. what got built

- ✅ 2 YouTube transcripts fetched (full text, 362KB total)
- ✅ 2 Fleury articles read (full text)
- ✅ Chunk ideation archive saved (5 images, 19KB)
- ✅ SSDL digest written (504 lines, computational shapes article + the 4 sources synthesized)
- ✅ ASCII-sketch workflow report written (for later pickup)
- ✅ code_path_audit spec/plan updated with post-4-tracks timing + 5-source framing
- ✅ All 7 artifacts committed in this session (5 by you, 2 by me)

### What's pending (intentionally)

- The 4 major tracks are spec-ready, plan-ready; they'll execute on their own timelines
- The code_path_audit is *intentionally deferred* until after the 4 tracks
- The ASCII-sketch workflow is a report; the 5 open questions need your decision before it becomes a track
- The chunkification_optimization is a recommendation; the user's chunk-ideation should be promoted to an actual repo + code before this becomes a track

### What the next session needs to know

The minimum-sufficient context to re-anchor:
1. This report (`docs/reports/session_synthesis_20260608.md`)
2. The 2 YouTube transcripts in `docs/transcripts/`
3. The 2 Fleury articles (the user has them; they're not in the repo)
4. The user's chunk ideation in `docs/ideation/`
5. The 3 new deep-dive guides in `docs/`
6. The 4 major-track spec/plan updates (recent commits)
7. The 10 actionable takeaways in `conductor/tracks/nagent_review_20260608/nagent_takeaways_20260608.md`

That's ~600KB of source material. Smaller than this session's working set, but covers everything we agreed on.

### The 2 new tracks I'm proposing (for your decision)

1. `manual_ux_validation_20260608_PLACEHOLDER` — promote the ASCII-sketch workflow to a real track with a first target (the Discussion Hub per-entry panel). Small effort.
2. `chunkification_optimization_20260608_PLACEHOLDER` — promote the user's chunk-ideation to a real track with a first target (the `comms.log` ring buffer). Medium effort.

If you want either of these, I can write the spec + plan in the next session. If not, they remain in this synthesis as future-considerations.

---

## 10. The session's arc, in one image

```
                             [USER INPUT FLOW]

  2026-06-08 morning:
    "Bring up Mike Acton's nagent as a reference" (from earlier)
            ↓
  [TIER 2 PHASE 1: nagent_review track]
    spec → report → decisions → takeaways (7 files, 1784 lines)
            ↓
  [USER CORRECTIONS: 3 rounds over the editable-discussion verdict]
            ↓
  [TIER 2 PHASE 2: docs refresh]
    3 new deep-dive guides + 8 cross-link updates (11 files, 1180 lines)
            ↓
  [USER FLAG: Gitea links broken]
            ↓
  [TIER 2 PHASE 3: link fix]
    24 files, 37 character-level replacements
            ↓
  [TIER 2 PHASE 4: 4 major-track updates]
    qwen_llama_grok, data_oriented_error_handling,
    data_structure_strengthening, mcp_architecture_refactor
    (4 commits, 115+ lines total)
            ↓
  [USER: "I have 5 images of chunk ideation + 2 articles + 2 YouTube videos"]
            ↓
  [TIER 2 PHASE 5: load + synthesize]
    2 transcripts (362KB) + 2 articles + 5 images → SSDL digest (504 lines)
            ↓
  [TIER 2 PHASE 6: code_path_audit framing]
    spec/plan updates with post-4-tracks timing + 5-source lens
            ↓
  [USER: "Write the biggest in-depth report you can muster"]
            ↓
  [THIS REPORT]
```

---

## 11. Appendix: commit chain for this session (and adjacent)

```
[session-context — visible in git log, 5 commits in this session]
a9333bbb conductor(track-update): code_path_audit_20260607 - post-4-tracks timing + 5-source framing
2eef50c5 transcripts                                                  (user commit)
d7b66a5d ideating chunk-based data structures                            (user commit)
0be9b4f0 digest on computational shapes ssdl                            (user commit)

[earlier — nagent_review + docs refresh + link fix]
8a597d18 conductor(track-update): mcp_architecture_refactor - list_tool_schemas + security-as-contract
1fb0d79c conductor(track-update): data_structure_strengthening - HistoryMessage vs ProviderHistoryMessage split
0471440c conductor(track-update): data_oriented_error_handling - nagent_review + docs refresh
77ae2ec7 conductor(track-update): qwen_llama_grok - spec notes for nagent_review + docs refresh
161ebb0d docs(fix): correct nav link case + relative-path level
ba051684 docs(refresh): 3 new guides + cross-links from nagent_review
9cc51ca9 conductor(track): nagent review - deep-dive + 6 pitfalls + 10 actionable takeaways

[Tier-2 agent working on test-fragility TODO — not this session's work]
51ecace4 test(live_workflow): pre-flight health check fails fast on dirty state
... (and 5 more in the test-fragility thread)
```

---

*End of synthesis. Total session artifacts: 7 new docs files (5 by user, 2 by me), 4 spec/plan updates, 1 ASCII-sketch report, 1 SSDL digest, 1 chunk-ideation archive, 1 this synthesis. ~1.4MB of new content, all committed. The next session has enough context to re-anchor from the reports alone.*

*Thanks for the session. It was a productive one — and the user's "you can retireve the transcript of videos using the following: https://pypi.org/project/youtube-transcript-api/" was a great catch that fixed a real failure mode (I had been doing second-hand summaries before). The next session, if it's anything like this one, will be even better.*
