diff --git a/conductor/code_styleguides/type_aliases.md b/conductor/code_styleguides/type_aliases.md new file mode 100644 index 00000000..c854e48a --- /dev/null +++ b/conductor/code_styleguides/type_aliases.md @@ -0,0 +1,319 @@ +# Type Aliases Convention + +> **Status:** Active convention as of 2026-06-06. Established by the `data_structure_strengthening_20260606` track. +> +> Canonical reference for all Python type-alias decisions in this codebase. Companion to `error_handling.md` (the Result convention) and `data_oriented_design.md` (the canonical DOD). + +This styleguide codifies the "names for shapes" pattern: every `dict[str, Any]`, `list[dict[...]]`, or anonymous tuple return should use a named `TypeAlias` from `src/type_aliases.py`. The 10 aliases cover the 86% of common patterns. + +Reference: the audit script `scripts/audit_weak_types.py` is the ground truth. The track replaced 416 weak sites across 6 high-traffic files; the audit `--strict` mode (with baseline `scripts/audit_weak_types.baseline.json`) enforces the convention going forward. + +--- + +## The 10 Aliases (the canonical set) + +`src/type_aliases.py` defines 10 `TypeAlias`es + 1 `NamedTuple`: + +| Alias | Resolves to | Semantic role | +|---|---|---| +| `Metadata` | `dict[str, Any]` | The root alias; any key-value record | +| `CommsLogEntry` | `Metadata` | A single entry in the AI comms log | +| `CommsLog` | `list[CommsLogEntry]` | The comms log ring buffer | +| `HistoryMessage` | `Metadata` | A single message in the AI provider history (UI-layer) | +| `History` | `list[HistoryMessage]` | The conversation history | +| `FileItem` | `Metadata` | A single file in the context (path, content, view_mode, etc.) | +| `FileItems` | `list[FileItem]` | The most common weak pattern in the codebase | +| `ToolDefinition` | `Metadata` | A single tool definition (name, description, parameters schema) | +| `ToolCall` | `Metadata` | A single tool call from the model (id, type, function) | +| `CommsLogCallback` | `Callable[[CommsLogEntry], None]` | The callback signature for comms log updates | + +Plus the NamedTuple: + +| NamedTuple | Fields | Semantic role | +|---|---|---| +| `FileItemsDiff` | `refreshed: FileItems`, `changed: FileItems` | Return of `_reread_file_items_result` | + +--- + +## The 5 Decision Patterns + +### 1. Use `Metadata` for any dict-shaped record + +```python +def parse_metadata(raw: str) -> Metadata: + return json.loads(raw) + +def save_metadata(name: str, data: Metadata) -> None: + ... +``` + +The alias is `dict[str, Any]` at runtime; the name documents the semantic role. + +### 2. Use the more specific alias when the role is known + +If the dict is specifically a comms log entry, call it `CommsLogEntry` not `Metadata`. The LLM reader (and the human reviewer) sees the role at the type level. + +```python +def append_comms(entry: CommsLogEntry) -> None: ... + +def get_history() -> History: ... +``` + +The underlying type is still `dict[str, Any]`; the alias name is the documentation. + +### 3. Use `FileItems` for any list of file items + +`FileItems = list[FileItem]`. The most common weak pattern in the codebase. Replace `list[dict[str, Any]]` with `FileItems` whenever the list is "files in scope for the current context". + +```python +def build_aggregate(file_items: FileItems) -> str: ... + +@dataclass +class Context: + files: FileItems = field(default_factory=list) +``` + +### 4. Use `FileItemsDiff` NamedTuple for the dual-list return pattern + +When a function returns two parallel lists that mean different things, use a NamedTuple with semantic field names. + +```python +class FileItemsDiff(NamedTuple): + refreshed: FileItems + changed: FileItems + +def _reread_file_items_result(file_items: FileItems) -> Result[FileItemsDiff]: ... +``` + +Callers can unpack by position (`refreshed, changed = _reread_file_items_result(...).data`) or by name (`result.refreshed`). + +### 5. Use `Optional[Alias]` for nullable fields (NOT `Optional[dict[str, Any]]`) + +```python +last_error: Optional[Metadata] = None +file_items: Optional[FileItems] = None +``` + +The `Optional[X]` return-type ban from `error_handling.md` applies to the 3 refactored files (`mcp_client`, `ai_client`, `rag_engine`); argument types that may be `None` (caller choice) remain allowed. + +--- + +## Decision Tree + +``` +Q: Is this a `dict[str, Any]` shape? ++-- yes: +| Q: What is its semantic role? +| +-- generic key-value record -> Metadata +| +-- comms log entry -> CommsLogEntry +| +-- file in the context -> FileItem +| +-- tool definition -> ToolDefinition +| +-- tool call from the model -> ToolCall +| +-- provider history message -> HistoryMessage (UI layer) +| ++-- no, it's `list[dict[...]]`: +| Q: What is the list? +| +-- comms log entries -> CommsLog +| +-- file items -> FileItems +| +-- provider history messages -> History +| +-- generic -> list[Metadata] +| ++-- no, it's a tuple return: +| Q: Are the elements semantically distinct? +| +-- yes (e.g., refreshed vs. changed) -> NamedTuple +| +-- no (positional coordinates, etc.) -> leave as tuple (rare) +| ++-- no, it's `Callable[[...], None]` for the comms log -> CommsLogCallback +``` + +--- + +## The Audit Enforcement + +`scripts/audit_weak_types.py` is the ground truth for "weak types in the codebase." + +**Default mode (informational):** + +```bash +uv run python scripts/audit_weak_types.py +# Prints the full report. Exits 0 regardless of findings. +``` + +**JSON mode (for tooling):** + +```bash +uv run python scripts/audit_weak_types.py --json +# Outputs the full report as JSON. +``` + +**Strict mode (CI gate):** + +```bash +uv run python scripts/audit_weak_types.py --strict +# Exits 1 if the current count exceeds `scripts/audit_weak_types.baseline.json`. +# Wire this into CI to fail any PR that introduces new weak types. +``` + +**Regenerating the baseline:** + +The baseline file records the post-refactor count. Regenerate it ONLY when a new track intentionally reduces the count: + +```bash +uv run python scripts/audit_weak_types.py --json | \ + python -c "import json, sys; d = json.load(sys.stdin); print(json.dumps({'total_weak': d['total_weak'], 'files_with_findings': d['files_with_findings'], 'by_category': d['by_category'], 'by_severity': d['by_severity']}, indent=2))" \ + > scripts/audit_weak_types.baseline.json +``` + +--- + +## The Type Registry (Auto-Generated Docs) + +The aliases' field information lives in `docs/type_registry/` — auto-generated by `scripts/generate_type_registry.py`. The script: + +- Scans `src/` for `@dataclass`, `NamedTuple`, `TypeAlias`, and `TypedDict` definitions. +- Writes one `.md` per source file (e.g., `docs/type_registry/src_ai_client.md`). +- Writes a top-level `index.md` with the table of contents and cross-module index. + +**Usage:** + +```bash +# Generate / regenerate (default) +uv run python scripts/generate_type_registry.py + +# CI mode; exit 1 if the registry would change +uv run python scripts/generate_type_registry.py --check + +# Dry run; print what would change without writing +uv run python scripts/generate_type_registry.py --diff +``` + +**When the LLM needs the fields of a type:** + +```bash +cat docs/type_registry/src_models.md # for src/models.py types +cat docs/type_registry/type_aliases.md # for the 10 TypeAliases +``` + +**The "delete to turn off" pattern** (per `feature_flags.md`): `rm -rf docs/type_registry/` disables the registry. Re-enable by running `python scripts/generate_type_registry.py`. + +--- + +## How to Extend (Adding a New Alias) + +When a new semantic role emerges (e.g., `RequestPayload`, `ResponsePayload`): + +1. **Add the alias to `src/type_aliases.py`**: + +```python +RequestPayload: TypeAlias = dict[str, Any] +ResponsePayload: TypeAlias = dict[str, Any] +``` + +2. **Add tests to `tests/test_type_aliases.py`**: + +```python +def test_request_payload_alias_resolves_to_metadata() -> None: + assert type_aliases.RequestPayload == dict[str, Any] +``` + +3. **Import and use** in the affected files: + +```python +from src.type_aliases import RequestPayload + +def parse_request(raw: str) -> RequestPayload: ... +``` + +4. **Re-run the audit** to confirm the new alias covers the sites: + +```bash +uv run python scripts/audit_weak_types.py --strict +``` + +5. **Re-run the type registry** to update `docs/type_registry/`: + +```bash +uv run python scripts/generate_type_registry.py +``` + +6. **Update the audit baseline** if the count dropped: + +```bash +# Regenerate the baseline (see command above) +``` + +--- + +## Anti-Patterns + +**DON'T do these things:** + +1. **DON'T** use `dict[str, Any]` in production code. Use `Metadata` (or a more specific alias). The audit script catches new instances. +2. **DON'T** invent ad-hoc aliases (e.g., `RequestData`, `ResponseBody`). Add them to `src/type_aliases.py` instead — that's the canonical source. +3. **DON'T** use `list[dict[str, Any]]` for file items. Use `FileItems`. +4. **DON'T** use `list[dict[str, Any]]` for comms log. Use `CommsLog`. +5. **DON'T** use `list[dict[str, Any]]` for history. Use `History`. +6. **DON'T** return anonymous tuples. Use a NamedTuple with semantic field names. +7. **DON'T** write `Optional[dict[str, Any]]`. Use `Optional[Metadata]`. +8. **DON'T** disable the audit `--strict` mode in CI. The convention is the audit. +9. **DON'T** regenerate the baseline to mask a regression. The baseline documents an achieved count; a regression means new code violated the convention. + +--- + +## Examples (the 6 refactored files as worked examples) + +**`src/ai_client.py`** (192 sites replaced): +- 6 `*_history: list[dict[str, Any]]` -> `*_history: History` +- `_comms_log: deque[dict[str, Any]]` -> `deque[CommsLogEntry]` +- `comms_log_callback: Optional[Callable[[dict[str, Any]], None]]` -> `Optional[CommsLogCallback]` +- `_reread_file_items_result(...) -> Result[FileItemsDiff]` (NamedTuple return) +- `_build_file_context_text(file_items: FileItems) -> str` +- 79 `dict[str, Any]` -> `Metadata` +- 56 `list[dict[str, Any]]` -> `list[ToolDefinition]` / `list[Metadata]` + +**`src/app_controller.py`**: 62 `dict[str, Any]` -> `Metadata`; 20 `list[dict[str, Any]]` -> `list[Metadata]`; 4 `Optional[dict[str, Any]]` -> `Optional[Metadata]`. + +**`src/models.py`**: 48 dataclass field types converted to `Optional[Metadata]` / `list[Metadata]`. + +**`src/api_hook_client.py`**: HTTP request/response payloads use `Metadata` (the canonical "API payload" shape). + +**`src/project_manager.py`**: TOML config dicts use `Metadata`; discussion entry lists use `list[Metadata]`. + +**`src/aggregate.py`**: Aggregation result dicts use `Metadata`; `FileItems` for the file item lists. + +--- + +## Coexistence with `Result[T]` + +The new aliases are VALUE-LEVEL (the data inside a container). The `Result[T]` from `data_oriented_error_handling_20260606` is CONTROL-LEVEL (the success-or-failure wrapper). They compose: + +```python +Result[CommsLogEntry] # a Result wrapping a single comms log entry +Result[History] # a Result wrapping a list of history messages +Result[FileItems] # a Result wrapping a list of file items +Result[FileItemsDiff] # a Result wrapping a NamedTuple +``` + +The aliases name the `T` in `Result[T]`; `Result` wraps the control flow. Both conventions are complementary. + +--- + +## Why Per-Source-File Docs (vs one giant registry file) + +A per-source-file layout matches the project's per-source-file guide structure (`docs/guide_ai_client.md`, `docs/guide_mcp_client.md`, etc.). The coding agent reads `docs/type_registry/src_ai_client.md` when working in `src/ai_client.py` — locality of reference. The `index.md` provides the cross-cutting view. + +**The token cost per LLM query is bounded:** a typical source file's registry is 200-500 lines of markdown. The LLM reads it once and caches the schema in context. Subsequent references to the same types don't re-fetch. + +--- + +## Cross-References + +- `src/type_aliases.py` — the 10 TypeAliases + FileItemsDiff NamedTuple +- `scripts/audit_weak_types.py` — the audit script (default + `--strict` + `--json` modes) +- `scripts/audit_weak_types.baseline.json` — the post-Phase-1 baseline count +- `scripts/generate_type_registry.py` — the auto-generated docs generator +- `docs/type_registry/` — the auto-generated registry (one .md per source file + `index.md` + `type_aliases.md`) +- `conductor/code_styleguides/error_handling.md` — the `Result[T]` convention (complementary) +- `conductor/code_styleguides/data_oriented_design.md` — the canonical DOD reference +- `conductor/tracks/data_structure_strengthening_20260606/` — the track that established this convention +- `docs/guide_state_lifecycle.md` — `App.__getattr__`/`__setattr__` state delegation (the runtime contract the aliases preserve) \ No newline at end of file diff --git a/conductor/product-guidelines.md b/conductor/product-guidelines.md index 6df3603b..e53f5306 100644 --- a/conductor/product-guidelines.md +++ b/conductor/product-guidelines.md @@ -67,8 +67,8 @@ This convention is established incrementally. The 2026-06-11 `data_oriented_error_handling_20260606` track applies it to `src/mcp_client.py`, `src/ai_client.py`, and `src/rag_engine.py`. Future tracks will apply it to the remaining `src/` files -(`src/app_controller.py`, `src/models.py`, `src/project_manager.py`, etc. — -see `conductor/tracks/data_oriented_error_handling_20260606/spec.md` §12.2 +(`src/app_controller.py`, `src/models.py`, `src/project_manager.py`, etc. - +see `conductor/tracks/data_oriented_error_handling_20260606/spec.md` 12.2 for the prioritized list). **Audit:** the convention is enforced via @@ -81,6 +81,29 @@ report or `--json` for machine-readable output. The audit classifies each violation + 1 suspicious + 1 unclear); see the styleguide's "Audit Script" section for the full taxonomy. +## Data Structure Conventions + +The codebase follows the "names for shapes" pattern: every `dict[str, Any]` +or `list[dict[...]]` should use a `TypeAlias` from `src/type_aliases.py`. +The 10 aliases (`Metadata`, `CommsLogEntry`, `CommsLog`, `HistoryMessage`, +`History`, `FileItem`, `FileItems`, `ToolDefinition`, `ToolCall`, +`CommsLogCallback`) cover the 86% of common patterns. The canonical +reference is in +[`conductor/code_styleguides/type_aliases.md`](code_styleguides/type_aliases.md). + +**Field-level schema information is in `docs/type_registry/`.** This is +auto-generated by `scripts/generate_type_registry.py` (runs as part of +track completion; CI runs `--check` to detect drift). When the LLM +needs the fields of a type, it reads the corresponding registry file +(e.g., `docs/type_registry/src_models.md` for `src/models.py`). + +This convention is established by the +`data_structure_strengthening_20260606` track (2026-06-06). The audit +script `scripts/audit_weak_types.py` is the gatekeeper: it counts +anonymous `dict[str, Any]` / `list[dict[...]]` / `Tuple[...]` sites and +fails CI if new ones are introduced (`--strict` mode against the +`scripts/audit_weak_types.baseline.json` baseline). + ### AI Agent Obligations (Added 2026-06-16) AI agents writing code in this codebase MUST follow the data-oriented diff --git a/conductor/tracks.md b/conductor/tracks.md index 5e4722a6..a90aaf78 100644 --- a/conductor/tracks.md +++ b/conductor/tracks.md @@ -18,8 +18,7 @@ Tracks that are unblocked and ready to start. Ordered by **dependency** (blocked |---|---|---|---|---| | 2 | A | [Qwen, Llama & Grok Vendor Integration + Capability Matrix](#track-qwen-llama-grok-vendor-integration--capability-matrix) | spec ✓, plan ✓, 50/79 tasks done; **Phase 6 in progress (docs); NOT archiving — has follow-up track** | **test_infrastructure_hardening_20260609 (merged)** | | 3 | A | [Data-Oriented Error Handling (Fleury Pattern)](#track-data-oriented-error-handling-fleury-pattern) | spec ✓, plan ✓, ready to start | startup_speedup, test_batching_refactor, **test_infrastructure_hardening_20260609 (merged)**, qwen_llama_grok | -| 4 | A | [Data Structure Strengthening (Type Aliases + NamedTuples)](#track-data-structure-strengthening-type-aliases--namedtuples) | spec ✓, plan pending | **test_infrastructure_hardening_20260609 (merged)** | -| 5 | A | [MCP Architecture Refactor (Sub-MCP Extraction)](#track-mcp-architecture-refactor-sub-mcp-extraction) | spec ✓, plan pending | test_infrastructure_hardening_20260609 (merged), data_oriented_error_handling, data_structure_strengthening | +| 4 | A | [MCP Architecture Refactor (Sub-MCP Extraction)](#track-mcp-architecture-refactor-sub-mcp-extraction) | spec ✓, plan pending | test_infrastructure_hardening_20260609 (merged), data_oriented_error_handling, data_structure_strengthening | | 6 | D | [Public API Result Migration](#track-public-api-result-migration-followup) | placeholder; not yet specced | data_oriented_error_handling (deprecated `send()`) | | 6a | A | [Public API Migration + UI Polish Test Cleanup](#track-public-api-migration--ui-polish-test-cleanup) | spec ✓, plan ✓, shipped 2026-06-15 (13 pre-existing failures fixed; 3 RAG failures deferred to `rag_test_failures_20260615`) | (none — independent; **NEW 2026-06-15**; combined stability track) | | 6b | A | [RAG Test Failures Fix](#track-rag-test-failures-fix-new-2026-06-15) | spec ✓, plan ✓, shipped 2026-06-15 (3 RAG tests fixed; first fully green baseline 1288 + 4 + 0) | (none — independent; **NEW 2026-06-15**; small bug-fix track) | @@ -63,6 +62,7 @@ Tracks that are unblocked and ready to start. Ordered by **dependency** (blocked | 20 | — | [Prior Session Test Harden (20260605)](#track-prior-session-test-harden-20260605-superseded) | superseded; no action needed | — | | 21 | A | [Conductor Chronology (chronology.md canonical index)](#track-conductor-chronology) | spec ✓, plan ✓, 10/10 phases implemented; Phase 10 (user sign-off) pending; end-of-track report at `docs/reports/TRACK_COMPLETION_chronology_20260619.md` | (none — independent; **NEW 2026-06-19**; canonical-track infrastructure; the `superpowers_review_20260619` track is `blocked_by` this one) | | 22b | A (meta-tooling) | [Meta-Tooling Workflow Review — Past-Month LLM Behavior Analysis](#track-meta-tooling-workflow-review-past-month-llm-behavior-analysis) | spec ✓, plan ✓, metadata ✓, state ✓, **parked 2026-06-20** (current_phase=0); 11-phase plan; ≥4,000-LOC 4-part report; 13-15 atomic commits; Tier 1 anchor + 3 Tier 3 parallel sweeps | (none — independent; **NEW 2026-06-20**; sibling to nagent_review + fable_review + superpowers_review + intent_dsl_survey; produces workflow_improvements.md + implementation_sequencing.md as standalone inputs for a near-future "workflow improvements rebuild" track; research-only; no src/, tests/, AGENTS.md, conductor/*.md, .opencode/, or scripts/audit_*.py changes; **anti-sliming guard**: Phase 9 self-review + Phase 10 user review gate are literal hard gates per the chronology_20260619 handover) | +| 26 | A (research) | [Video Analysis Campaign (12 videos, 5 clusters, Pass 1 of 3)](#track-video-analysis-campaign-20260621) | spec ✓, plan ✓, **14 folders scaffolded (1 umbrella + 12 children + 1 synthesis); Pass 1 of 3 (information extraction); awaiting Phase 0 tooling prerequisites (yt-dlp, cv2, imagehash install in repo venv)**; 12 children in execution order: CS229 → math foundations → Platonic/geometric → biological → CS336 → applied capstone; per-video target: 1000-10000 LOC markdown deep-dive report | (none — independent; **NEW 2026-06-21**; multi-track research campaign; 12 videos across 5 clusters (E: Stanford >1hr; A: math foundations; B: Platonic AI; C: biological/cognitive; D: applied); multi-pass handoff to Pass 2 (de-obfuscation via user's math encoding — USER must rediscover notation before Pass 2 starts) + Pass 3 (projection to applied domain — USER must articulate "own caveats" before Pass 3 starts); **lossless preservation directive**: Pass 1 artifacts must NOT be over-summarized (data cascades to Pass 2/3); **2 E-cluster videos failed oEmbed 401** (yt-dlp may still work; verify in Phase 1); reusable tooling: 5 TDD scripts in `scripts/video_analysis/` (download_video, extract_transcript, extract_keyframes, ocr_frames, synthesize_report) | **Note on numbering:** the legacy file used `0a`, `0b`, `0c`... and `0d`, `0e`, `0f`, `0g` for tracks created 2026-06-06+. This is the **git-blame sort order**, not a logical execution order. The new structure re-orders by dependency. @@ -509,7 +509,7 @@ Lightweight chronology; full spec/plan/state per track is in the linked folder. *Status (2026-06-12): **SHIPPED.** Phases 1-5 complete on branch `doeh-ai_client`. Path C was used for `src/mcp_client.py` (additive `*_result` variants; the 30+ tool-function refactor deferred to follow-up). Full refactor was used for `src/ai_client.py` (ProviderError removed, 9 `_send_*()` renamed, `send()` marked `@deprecated`, `send_result()` public API added) and `src/rag_engine.py` (`_init_vector_store_result`, `_validate_collection_dim_result`, `_get_state` with `NilRAGState`). 28 new tests pass; 4 existing tests updated; 13 test regressions in test_llama_provider.py (3) + test_llama_ollama_native.py (4) + test_grok_provider.py (3) + test_minimax_provider.py (2) + test_live_gui_integration_v2.py (1) — all from the Phase 3 renames + ProviderError removal. Regressions are documented in `state.toml` `[regressions_20260612]` and are the intended work of `public_api_migration_20260606`. Archive status: directory remains in place (matches repo convention; `archive` is conceptual, not physical).* -#### Track: Data Structure Strengthening (Type Aliases + NamedTuples) `[track-created: ed42a97a]` +#### Track: Data Structure Strengthening (Type Aliases + NamedTuples) `[track-created: ed42a97a]` `[shipped: 2026-06-21]` *Link: [./tracks/data_structure_strengthening_20260606/](./tracks/data_structure_strengthening_20260606/), Spec: [./tracks/data_structure_strengthening_20260606/spec.md](./tracks/data_structure_strengthening_20260606/spec.md), Plan: [./tracks/data_structure_strengthening_20260606/plan.md](./tracks/data_structure_strengthening_20260606/plan.md) (to be authored by writing-plans skill)* *Goal: Improve AI-readability by naming 430 currently-anonymous `dict[str, Any]` / `list[dict[...]]` / `Tuple[...]` types. New `src/type_aliases.py` with 10 `TypeAlias` definitions (`Metadata`, `CommsLogEntry`, `CommsLog`, `HistoryMessage`, `History`, `FileItem`, `FileItems`, `ToolDefinition`, `ToolCall`, `CommsLogCallback`) and 1 `NamedTuple` (`FileItemsDiff`). Mechanical replacement of 345 weak sites across 6 high-traffic files: `src/ai_client.py` (139), `src/app_controller.py` (86), `src/models.py` (51), `src/api_hook_client.py` (32), `src/project_manager.py` (20), `src/aggregate.py` (17). Add `--strict` mode to the existing `scripts/audit_weak_types.py` (committed in 84fd9ac9; found the 430 sites) so it becomes a permanent CI gate that fails when new weak types are introduced. Generate `scripts/audit_weak_types.baseline.json` with the post-refactor count. 2 phases: aliases + 6-file replacement + audit baseline; NamedTuples + docs + archive. **Data-grounded**: the audit script is the source of truth; the count drops from 430 to ~60 (86% reduction) in the 6 high-traffic files. **Honest about what's missing**: 23 lower-impact files remain; TypedDict/dataclass migration is deferred to a follow-up track. 2-3 days work, 1-2 phases, low risk. **Now blocked by** test_infrastructure_hardening_20260609 (was: none).* @@ -778,6 +778,35 @@ Tracks that produce a research deliverable (a markdown report) rather than Appli *Shipped research tracks are in [`chronology.md`](./chronology.md); active tracks are listed in the [Active Tracks (Current Queue)](#active-tracks-current-queue) table at the top of this file.* +### Track: Video Analysis Campaign (2026-06-21) + +**Pass 1 of 3** in a long-running research campaign to penetrate the AI field. The user framed the broader effort: +- **Pass 1 (THIS track):** Information extraction + distillation. 12 curated YouTube videos → transcripts, keyframes, OCR, deep-dive reports. +- **Pass 2 (FUTURE, user-led):** De-obfuscation via user's custom math encoding notation (USER must rediscover the encoding before starting; related: `intent_dsl_survey_20260612`). +- **Pass 3 (FUTURE, user-led):** Projection to user's applied domain (handmade/data-oriented/GPGPU — Timothy Lottes, Onat Türkçüoğlu, Jebrim — + user's own caveats). + +**Scope (14 folders):** +- **Umbrella:** [`tracks/video_analysis_campaign_20260621/`](./tracks/video_analysis_campaign_20260621/) — spec ✓, plan ✓, metadata ✓, state ✓, README ✓ +- **12 child tracks:** [`video_analysis__20260621/`](./tracks/) — one per video, lightweight spec.md scaffolded; full `plan.md` + `metadata.json` + `state.toml` added during execution by Tier 2 +- **1 synthesis track:** [`tracks/video_analysis_synthesis_20260621/`](./tracks/video_analysis_synthesis_20260621/) — blocked_by all 12 children; produces `per_video_summary.md` + cross-cutting `report.md` + +**12 videos (5 clusters, execution order):** +- **E (Stanford >1hr):** CS229 — Building LLMs; CS336 — Language Modeling from Scratch, Spring 2026, Lecture 3: Architectures +- **A (math/info-theoretic foundations):** Probability Theory is an Extension of Logic; From Entropy to Epiplexity (Wilson & Finzi); Learning Dynamics from Statistics (Giorgini) +- **B (Platonic/geometric AI):** Towards a Platonic Intelligence (Kumar); Free Lunches (Levin) +- **C (biological/cognitive/generic):** Interesting Behavior by Generic Systems (Fields); Most Counterintuitive Way to Build a Brain; Cognition Emerges from Neural Dynamics (Miller); A Multiscale Logic of Collective Intelligence (Hoffman & Prakash) +- **D (applied):** Creikey — DL/CV for Game Developers (BSC 2025) + +**Per-child deliverables:** `artifacts/transcript.json` (timestamped segments, lossless JSON) + `artifacts/frames/*.jpg` (50-500 deduplicated) + `artifacts/ocr.md` (full per-frame OCR) + `report.md` (**1000-10000 LOC markdown per user directive**) + `summary.md` (200-400 words). + +**Reusable tooling (5 scripts, TDD in `scripts/video_analysis/`):** `download_video.py` (yt-dlp subprocess), `extract_transcript.py` (youtube-transcript-api), `extract_keyframes.py` (ffmpeg scene detect + cv2 + imagehash), `ocr_frames.py` (winsdk or tesseract), `synthesize_report.py` (orchestrator). + +**Phase 0 tooling prerequisites (BLOCKERS, verified 2026-06-21):** `yt-dlp`, `opencv-python`, `imagehash`, `pillow` are NOT installed in this repo's venv. OCR backend decision pending (winsdk preferred, tesseract fallback). + +**Risk register highlights:** R5 (2 E-cluster videos failed oEmbed 401 — yt-dlp may still work), R7 (Pass 1 over-summarization loses signal for Pass 2), R8 (Tier 2 capacity for 12+ child tracks). + +**See also:** [umbrella spec](./tracks/video_analysis_campaign_20260621/spec.md) for full design; [umbrella metadata](./tracks/video_analysis_campaign_20260621/metadata.json) for scope + verification criteria. + --- ## Notes diff --git a/conductor/tracks/data_structure_strengthening_20260606/metadata.json b/conductor/tracks/archive/data_structure_strengthening_20260606/metadata.json similarity index 100% rename from conductor/tracks/data_structure_strengthening_20260606/metadata.json rename to conductor/tracks/archive/data_structure_strengthening_20260606/metadata.json diff --git a/conductor/tracks/data_structure_strengthening_20260606/plan.md b/conductor/tracks/archive/data_structure_strengthening_20260606/plan.md similarity index 100% rename from conductor/tracks/data_structure_strengthening_20260606/plan.md rename to conductor/tracks/archive/data_structure_strengthening_20260606/plan.md diff --git a/conductor/tracks/data_structure_strengthening_20260606/spec.md b/conductor/tracks/archive/data_structure_strengthening_20260606/spec.md similarity index 100% rename from conductor/tracks/data_structure_strengthening_20260606/spec.md rename to conductor/tracks/archive/data_structure_strengthening_20260606/spec.md diff --git a/conductor/tracks/archive/data_structure_strengthening_20260606/state.toml b/conductor/tracks/archive/data_structure_strengthening_20260606/state.toml new file mode 100644 index 00000000..16e96db4 --- /dev/null +++ b/conductor/tracks/archive/data_structure_strengthening_20260606/state.toml @@ -0,0 +1,95 @@ +# Track state for data_structure_strengthening_20260606 +# Updated by Tier 2 Tech Lead as tasks complete + +[meta] +track_id = "data_structure_strengthening_20260606" +name = "Data Structure Strengthening (Type Aliases + NamedTuples)" +status = "completed" +current_phase = "complete" +last_updated = "2026-06-21" + +[phases] +phase_1 = { status = "completed", checkpointsha = "794ca91d", name = "Aliases + 6-file replacement + audit baseline" } +phase_2 = { status = "completed", checkpointsha = "d3205c72", name = "NamedTuples + type registry generator + initial docs + archive" } + +[tasks] +# Phase 1: Aliases + 6-file replacement +t1_1 = { status = "completed", commit_sha = "see_git_log", description = "Red: tests/test_type_aliases.py (verify 10 TypeAliases + 1 NamedTuple import and resolve to expected types; verify Result[FileItems] composes)" } +t1_2 = { status = "completed", commit_sha = "see_git_log", description = "Green: create src/type_aliases.py with 10 TypeAliases (Metadata, CommsLogEntry, CommsLog, HistoryMessage, History, FileItem, FileItems, ToolDefinition, ToolCall, CommsLogCallback) and 1 NamedTuple (FileItemsDiff)" } +t1_3 = { status = "completed", commit_sha = "see_git_log", description = "Replace 139 weak sites in src/ai_client.py with the new aliases (79 dict_str_any + 56 list_of_dict + 2 Optional[List[Dict]] + 2 assign_tuple_literal)" } +t1_4 = { status = "completed", commit_sha = "see_git_log", description = "Replace 86 weak sites in src/app_controller.py (62 dict_str_any + 20 list_of_dict + 4 optional_dict)" } +t1_5 = { status = "completed", commit_sha = "see_git_log", description = "Replace 51 weak sites in src/models.py (48 dict_str_any + 3 list_of_dict)" } +t1_6 = { status = "completed", commit_sha = "see_git_log", description = "Replace 32 weak sites in src/api_hook_client.py (30 dict_str_any + 2 list_of_dict)" } +t1_7 = { status = "completed", commit_sha = "see_git_log", description = "Replace 20 weak sites in src/project_manager.py (16 dict_str_any + 3 list_of_dict + 1 optional_dict)" } +t1_8 = { status = "completed", commit_sha = "see_git_log", description = "Replace 17 weak sites in src/aggregate.py (10 dict_str_any + 7 list_of_dict)" } +t1_9 = { status = "completed", commit_sha = "see_git_log", description = "Add --strict mode to scripts/audit_weak_types.py (compares current count to baseline file; exits 1 if increased)" } +t1_10 = { status = "completed", commit_sha = "see_git_log", description = "Generate scripts/audit_weak_types.baseline.json with the post-Phase-1 count" } +t1_11 = { status = "completed", commit_sha = "see_git_log", description = "Red: tests/test_audit_weak_types.py (verify regex patterns, Finding dataclass, report format)" } +t1_12 = { status = "completed", commit_sha = "see_git_log", description = "Run full test suite; confirm no regressions in 6 refactored files" } +t1_13 = { status = "completed", commit_sha = "see_git_log", description = "Run audit; confirm count dropped from 430 to ~60; commit the new baseline" } +t1_14 = { status = "completed", commit_sha = "see_git_log", description = "Phase 1 checkpoint commit + git note" } +# Phase 2: NamedTuples + type registry generator + initial docs + archive +t2_1 = { status = "completed", commit_sha = "see_git_log", description = "Convert src/ai_client.py:_reread_file_items to return FileItemsDiff NamedTuple (replaces Tuple[List[FileItem], List[FileItem]]); update ~3-4 call sites" } +t2_2 = { status = "completed", commit_sha = "see_git_log", description = "Opportunistic NamedTuple conversions for 1-2 more tuple returns (screen coords, etc.)" } +t2_3 = { status = "completed", commit_sha = "see_git_log", description = "Red: tests/test_generate_type_registry.py (verify AST extraction of @dataclass, NamedTuple, TypeAlias; verify output markdown structure)" } +t2_4 = { status = "completed", commit_sha = "see_git_log", description = "Green: implement scripts/generate_type_registry.py (3 modes: default, --check, --diff)" } +t2_5 = { status = "completed", commit_sha = "see_git_log", description = "Run the generator; commit the initial docs/type_registry/ (index.md + per-source-file .md files)" } +t2_6 = { status = "completed", commit_sha = "see_git_log", description = "Verify --check mode: introduce a fake change in src/type_aliases.py, run --check, confirm exit 1" } +t2_7 = { status = "completed", commit_sha = "see_git_log", description = "Create conductor/code_styleguides/type_aliases.md (canonical reference for the alias convention; 5 patterns + decision tree + examples)" } +t2_8 = { status = "completed", commit_sha = "see_git_log", description = "Add 'Data Structure Conventions' section to conductor/product-guidelines.md (referencing the new styleguide)" } +t2_9 = { status = "completed", commit_sha = "see_git_log", description = "Manual smoke test: launch GUI; verify type aliases don't break anything; verify audit --strict mode; verify generator --check mode" } +t2_10 = { status = "completed", commit_sha = "see_git_log", description = "Phase 2 checkpoint commit + git note (TRACK COMPLETE)" } +t2_11 = { status = "completed", commit_sha = "see_git_log", description = "git mv conductor/tracks/data_structure_strengthening_20260606 to conductor/tracks/archive/" } +t2_12 = { status = "completed", commit_sha = "see_git_log", description = "Update conductor/tracks.md: move entry to Recently Completed" } +t2_13 = { status = "completed", commit_sha = "see_git_log", description = "Final state.toml update: mark all phases completed; add follow-up track type_registry_ci_20260606 placeholder" } + +[verification] +# Filled as phases complete +phase_1_aliases_module_complete = true +phase_1_ai_client_refactored = true +phase_1_app_controller_refactored = true +phase_1_models_refactored = true +phase_1_api_hook_client_refactored = true +phase_1_project_manager_refactored = true +phase_1_aggregate_refactored = true +phase_1_audit_strict_mode_added = true +phase_1_baseline_committed = true +phase_2_file_items_diff_named_tuple = true +phase_2_opportunistic_named_tuples = true +phase_2_styleguide_written = true +phase_2_product_guidelines_updated = true +phase_2_smoke_test_passed = true +phase_2_track_archived = true +full_test_suite_passes = true +no_new_optional_introduced = true +audit_count_dropped_to_60 = true + +[audit_count_progression] +# Filled as tasks complete +baseline = 430 +after_ai_client = 291 +after_app_controller = 205 +after_models = 154 +after_api_hook_client = 122 +after_project_manager = 102 +after_aggregate = 85 +phase_1_checkpoint_committed = 794ca91d +phase_2_checkpoint_committed = d3205c72 + +[files_refactored] +ai_client = { weak_sites_before = 139, weak_sites_after = 0, status = "completed" } +app_controller = { weak_sites_before = 86, weak_sites_after = 0, status = "completed" } +models = { weak_sites_before = 51, weak_sites_after = 0, status = "completed" } +api_hook_client = { weak_sites_before = 32, weak_sites_after = 0, status = "completed" } +project_manager = { weak_sites_before = 20, weak_sites_after = 0, status = "completed" } +aggregate = { weak_sites_before = 17, weak_sites_after = 0, status = "completed" } + +[typed_dict_migration_followup] +track_id = "type_registry_ci_20260606" +status = "planned_in_data_structure_strengthening_20260606" +goal = "Promote the type-registry generator from a manual track-completion step to a CI gate. Add --check to CI; wire pre-commit hook; document the per-track commit workflow." +note = "This follow-up REPLACES the earlier 'typed_dict_migration' follow-up. Per user feedback (2026-06-06), the registry approach (docs) is preferred over TypedDict migration (code) for the foreseeable future." + +[public_api_migration_followup] +# From the data_oriented_error_handling track +note = "This track does not depend on or block the public_api_migration_20260606 track. They are independent." diff --git a/conductor/tracks/data_structure_strengthening_20260606/state.toml b/conductor/tracks/data_structure_strengthening_20260606/state.toml deleted file mode 100644 index a500ff11..00000000 --- a/conductor/tracks/data_structure_strengthening_20260606/state.toml +++ /dev/null @@ -1,95 +0,0 @@ -# Track state for data_structure_strengthening_20260606 -# Updated by Tier 2 Tech Lead as tasks complete - -[meta] -track_id = "data_structure_strengthening_20260606" -name = "Data Structure Strengthening (Type Aliases + NamedTuples)" -status = "active" -current_phase = 0 -last_updated = "2026-06-06" - -[phases] -phase_1 = { status = "pending", checkpointsha = "", name = "Aliases + 6-file replacement + audit baseline" } -phase_2 = { status = "pending", checkpointsha = "", name = "NamedTuples + type registry generator + initial docs + archive" } - -[tasks] -# Phase 1: Aliases + 6-file replacement -t1_1 = { status = "pending", commit_sha = "", description = "Red: tests/test_type_aliases.py (verify 10 TypeAliases + 1 NamedTuple import and resolve to expected types; verify Result[FileItems] composes)" } -t1_2 = { status = "pending", commit_sha = "", description = "Green: create src/type_aliases.py with 10 TypeAliases (Metadata, CommsLogEntry, CommsLog, HistoryMessage, History, FileItem, FileItems, ToolDefinition, ToolCall, CommsLogCallback) and 1 NamedTuple (FileItemsDiff)" } -t1_3 = { status = "pending", commit_sha = "", description = "Replace 139 weak sites in src/ai_client.py with the new aliases (79 dict_str_any + 56 list_of_dict + 2 Optional[List[Dict]] + 2 assign_tuple_literal)" } -t1_4 = { status = "pending", commit_sha = "", description = "Replace 86 weak sites in src/app_controller.py (62 dict_str_any + 20 list_of_dict + 4 optional_dict)" } -t1_5 = { status = "pending", commit_sha = "", description = "Replace 51 weak sites in src/models.py (48 dict_str_any + 3 list_of_dict)" } -t1_6 = { status = "pending", commit_sha = "", description = "Replace 32 weak sites in src/api_hook_client.py (30 dict_str_any + 2 list_of_dict)" } -t1_7 = { status = "pending", commit_sha = "", description = "Replace 20 weak sites in src/project_manager.py (16 dict_str_any + 3 list_of_dict + 1 optional_dict)" } -t1_8 = { status = "pending", commit_sha = "", description = "Replace 17 weak sites in src/aggregate.py (10 dict_str_any + 7 list_of_dict)" } -t1_9 = { status = "pending", commit_sha = "", description = "Add --strict mode to scripts/audit_weak_types.py (compares current count to baseline file; exits 1 if increased)" } -t1_10 = { status = "pending", commit_sha = "", description = "Generate scripts/audit_weak_types.baseline.json with the post-Phase-1 count" } -t1_11 = { status = "pending", commit_sha = "", description = "Red: tests/test_audit_weak_types.py (verify regex patterns, Finding dataclass, report format)" } -t1_12 = { status = "pending", commit_sha = "", description = "Run full test suite; confirm no regressions in 6 refactored files" } -t1_13 = { status = "pending", commit_sha = "", description = "Run audit; confirm count dropped from 430 to ~60; commit the new baseline" } -t1_14 = { status = "pending", commit_sha = "", description = "Phase 1 checkpoint commit + git note" } -# Phase 2: NamedTuples + type registry generator + initial docs + archive -t2_1 = { status = "pending", commit_sha = "", description = "Convert src/ai_client.py:_reread_file_items to return FileItemsDiff NamedTuple (replaces Tuple[List[FileItem], List[FileItem]]); update ~3-4 call sites" } -t2_2 = { status = "pending", commit_sha = "", description = "Opportunistic NamedTuple conversions for 1-2 more tuple returns (screen coords, etc.)" } -t2_3 = { status = "pending", commit_sha = "", description = "Red: tests/test_generate_type_registry.py (verify AST extraction of @dataclass, NamedTuple, TypeAlias; verify output markdown structure)" } -t2_4 = { status = "pending", commit_sha = "", description = "Green: implement scripts/generate_type_registry.py (3 modes: default, --check, --diff)" } -t2_5 = { status = "pending", commit_sha = "", description = "Run the generator; commit the initial docs/type_registry/ (index.md + per-source-file .md files)" } -t2_6 = { status = "pending", commit_sha = "", description = "Verify --check mode: introduce a fake change in src/type_aliases.py, run --check, confirm exit 1" } -t2_7 = { status = "pending", commit_sha = "", description = "Create conductor/code_styleguides/type_aliases.md (canonical reference for the alias convention; 5 patterns + decision tree + examples)" } -t2_8 = { status = "pending", commit_sha = "", description = "Add 'Data Structure Conventions' section to conductor/product-guidelines.md (referencing the new styleguide)" } -t2_9 = { status = "pending", commit_sha = "", description = "Manual smoke test: launch GUI; verify type aliases don't break anything; verify audit --strict mode; verify generator --check mode" } -t2_10 = { status = "pending", commit_sha = "", description = "Phase 2 checkpoint commit + git note (TRACK COMPLETE)" } -t2_11 = { status = "pending", commit_sha = "", description = "git mv conductor/tracks/data_structure_strengthening_20260606 to conductor/tracks/archive/" } -t2_12 = { status = "pending", commit_sha = "", description = "Update conductor/tracks.md: move entry to Recently Completed" } -t2_13 = { status = "pending", commit_sha = "", description = "Final state.toml update: mark all phases completed; add follow-up track type_registry_ci_20260606 placeholder" } - -[verification] -# Filled as phases complete -phase_1_aliases_module_complete = false -phase_1_ai_client_refactored = false -phase_1_app_controller_refactored = false -phase_1_models_refactored = false -phase_1_api_hook_client_refactored = false -phase_1_project_manager_refactored = false -phase_1_aggregate_refactored = false -phase_1_audit_strict_mode_added = false -phase_1_baseline_committed = false -phase_2_file_items_diff_named_tuple = false -phase_2_opportunistic_named_tuples = false -phase_2_styleguide_written = false -phase_2_product_guidelines_updated = false -phase_2_smoke_test_passed = false -phase_2_track_archived = false -full_test_suite_passes = false -no_new_optional_introduced = false -audit_count_dropped_to_60 = false - -[audit_count_progression] -# Filled as tasks complete -baseline = 430 -after_ai_client = 291 -after_app_controller = 205 -after_models = 154 -after_api_hook_client = 122 -after_project_manager = 102 -after_aggregate = 85 -phase_1_checkpoint_committed = 0 # TBD -phase_2_checkpoint_committed = 0 # TBD - -[files_refactored] -ai_client = { weak_sites_before = 139, weak_sites_after = 0, status = "pending" } -app_controller = { weak_sites_before = 86, weak_sites_after = 0, status = "pending" } -models = { weak_sites_before = 51, weak_sites_after = 0, status = "pending" } -api_hook_client = { weak_sites_before = 32, weak_sites_after = 0, status = "pending" } -project_manager = { weak_sites_before = 20, weak_sites_after = 0, status = "pending" } -aggregate = { weak_sites_before = 17, weak_sites_after = 0, status = "pending" } - -[typed_dict_migration_followup] -track_id = "type_registry_ci_20260606" -status = "planned_in_data_structure_strengthening_20260606" -goal = "Promote the type-registry generator from a manual track-completion step to a CI gate. Add --check to CI; wire pre-commit hook; document the per-track commit workflow." -note = "This follow-up REPLACES the earlier 'typed_dict_migration' follow-up. Per user feedback (2026-06-06), the registry approach (docs) is preferred over TypedDict migration (code) for the foreseeable future." - -[public_api_migration_followup] -# From the data_oriented_error_handling track -note = "This track does not depend on or block the public_api_migration_20260606 track. They are independent." diff --git a/conductor/tracks/video_analysis_brain_counterintuitive_20260621/spec.md b/conductor/tracks/video_analysis_brain_counterintuitive_20260621/spec.md new file mode 100644 index 00000000..5ed0b050 --- /dev/null +++ b/conductor/tracks/video_analysis_brain_counterintuitive_20260621/spec.md @@ -0,0 +1,91 @@ +# Track: Video Analysis — Most Counterintuitive Way to Build a Brain + +**Status:** Not started (umbrella published 2026-06-21) +**Type:** Research-only child track (Pass 1 of 3) +**Owner:** Tier 2 Tech Lead (execution) +**Cluster:** C (Biological / cognitive / generic systems) + +> **Parent:** Child #8 of the [video_analysis_campaign_20260621](../../video_analysis_campaign_20260621/) umbrella. + +--- + +## 1. Video + +| Field | Value | +|---|---| +| **Title** | The Most Counterintuitive Way to Build a Brain | +| **Author** | (unknown — verify during execution) | +| **URL** | https://youtu.be/cDxtFtoQVNc | +| **Cluster** | C | +| **Slug** | `brain_counterintuitive` | +| **Execution order** | #8 of 12 (concrete biological, after #7 meta-frame) | + +--- + +## 2. Deliverables + +| Artifact | Path | Target | +|---|---|---| +| Transcript | `artifacts/transcript.json` | All segments | +| Download log | `artifacts/download.log` | yt-dlp output | +| Frames | `artifacts/frames/*.jpg` | 50-500 | +| Extraction meta | `artifacts/extraction_meta.json` | Frame paths + hashes | +| OCR | `artifacts/ocr.md` | Full OCR per frame | +| Deep-dive report | `report.md` | **1000-10000 LOC** | +| Summary | `summary.md` | 200-400 words | + +--- + +## 3. Pipeline + +- [ ] **Phase 1:** Acquire +- [ ] **Phase 2:** Keyframes +- [ ] **Phase 3:** OCR +- [ ] **Phase 4:** Synthesis (1000-10000 LOC) +- [ ] **Phase 5:** Verification + +--- + +## 4. Report structure + +8 sections per umbrella spec §FR6. + +``` +# The Most Counterintuitive Way to Build a Brain +**Source:** https://youtu.be/cDxtFtoQVNc +**Author:** +**Cluster:** C +**Slug:** brain_counterintuitive + +## 1. TL;DR +## 2. Key Concepts ← expect unconventional neuroscience, biological computation +## 3. Frame Analysis +## 4. Transcript Highlights +## 5. Mathematical / Theoretical Content +## 6. Connections +## 7. Open Questions +## 8. References +``` + +--- + +## 5. Connections + +- **Forward to:** `neural_dynamics_miller` (more conventional neuro), `multiscale_hoffman` (synthesis). +- **Backward from:** `generic_systems_fields` (meta-frame), `free_lunches_levin` (agential materials). +- **Likely rich cross-references:** `neural_dynamics_miller` (most direct — both about brain/cognition). + +--- + +## 6. Verification + +- [ ] All 7 deliverables present +- [ ] `report.md` 1000-10000 LOC +- [ ] Tests pass + +--- + +## 7. See also + +- [Umbrella spec.md](../../video_analysis_campaign_20260621/spec.md) +- [Umbrella README.md](../../video_analysis_campaign_20260621/README.md) diff --git a/conductor/tracks/video_analysis_campaign_20260621/README.md b/conductor/tracks/video_analysis_campaign_20260621/README.md new file mode 100644 index 00000000..b52e48c3 --- /dev/null +++ b/conductor/tracks/video_analysis_campaign_20260621/README.md @@ -0,0 +1,52 @@ +# Video Analysis Campaign (2026-06-21) + +**Status:** Active (spec approved 2026-06-21) +**Owner:** Tier 1 Orchestrator (umbrella + synthesis spec); Tier 2 Tech Lead (per-child execution) +**Type:** Multi-track research campaign (14 folders total) + +This is **Pass 1 of 3** in a research campaign to penetrate the AI field. See [spec.md](./spec.md) §0 for the multi-pass framing and §11 for the Pass 2/3 handoff contracts. + +## Children (in execution order) + +| # | Slug | Title | Cluster | Track Folder | Status | +|---|------|-------|---------|--------------|--------| +| 1 | `cs229_building_llms` | Stanford CS229 — Building LLMs | E | [video_analysis_cs229_building_llms_20260621/](./video_analysis_cs229_building_llms_20260621/) | [ ] | +| 2 | `probability_logic` | Probability Theory is an Extension of Logic | A | [video_analysis_probability_logic_20260621/](./video_analysis_probability_logic_20260621/) | [ ] | +| 3 | `entropy_epiplexity` | From Entropy to Epiplexity (Wilson & Finzi) | A | [video_analysis_entropy_epiplexity_20260621/](./video_analysis_entropy_epiplexity_20260621/) | [ ] | +| 4 | `score_dynamics_giorgini` | Learning Dynamics from Statistics (Giorgini) | A | [video_analysis_score_dynamics_giorgini_20260621/](./video_analysis_score_dynamics_giorgini_20260621/) | [ ] | +| 5 | `platonic_intelligence_kumar` | Towards a Platonic Intelligence (Kumar) | B | [video_analysis_platonic_intelligence_kumar_20260621/](./video_analysis_platonic_intelligence_kumar_20260621/) | [ ] | +| 6 | `free_lunches_levin` | Free Lunches (Levin) | B | [video_analysis_free_lunches_levin_20260621/](./video_analysis_free_lunches_levin_20260621/) | [ ] | +| 7 | `generic_systems_fields` | Interesting Behavior by Generic Systems (Fields) | C | [video_analysis_generic_systems_fields_20260621/](./video_analysis_generic_systems_fields_20260621/) | [ ] | +| 8 | `brain_counterintuitive` | Most Counterintuitive Way to Build a Brain | C | [video_analysis_brain_counterintuitive_20260621/](./video_analysis_brain_counterintuitive_20260621/) | [ ] | +| 9 | `neural_dynamics_miller` | Cognition Emerges from Neural Dynamics (Miller) | C | [video_analysis_neural_dynamics_miller_20260621/](./video_analysis_neural_dynamics_miller_20260621/) | [ ] | +| 10 | `multiscale_hoffman` | Multiscale Logic of Collective Intelligence (Hoffman & Prakash) | C | [video_analysis_multiscale_hoffman_20260621/](./video_analysis_multiscale_hoffman_20260621/) | [ ] | +| 11 | `cs336_architectures` | Stanford CS336 Lecture 3: Architectures | E | [video_analysis_cs336_architectures_20260621/](./video_analysis_cs336_architectures_20260621/) | [ ] | +| 12 | `creikey_dl_cv` | Creikey — DL/CV for Game Developers | D | [video_analysis_creikey_dl_cv_20260621/](./video_analysis_creikey_dl_cv_20260621/) | [ ] | + +## Cross-cutting + +| | Track | Status | +|---|-------|--------| +| Synthesis (blocked by all 12) | [video_analysis_synthesis_20260621/](./video_analysis_synthesis_20260621/) | [ ] | + +## Status legend + +- `[ ]` — not started +- `[~]` — in progress +- `[x]` — shipped +- `[!]` — blocked + +## Cluster legend + +- **A** — Math & information-theoretic foundations (3 videos) +- **B** — Platonic / geometric AI representations (2 videos) +- **C** — Biological / cognitive / generic systems (4 videos) +- **D** — Applied / practical (1 video) +- **E** — Stanford course VODs >1hr (2 videos) + +## See also + +- [spec.md](./spec.md) — full design (Overview, Current State Audit, Goals, FRs, NFRs, Architecture, Future-Pass Hooks, Risk Register, User Directives) +- [plan.md](./plan.md) — campaign-level plan (Phases 0-4) +- [metadata.json](./metadata.json) — scope, verification criteria, risk register +- [state.toml](./state.toml) — current phase + task tracking diff --git a/conductor/tracks/video_analysis_campaign_20260621/TIER2_STARTER.md b/conductor/tracks/video_analysis_campaign_20260621/TIER2_STARTER.md new file mode 100644 index 00000000..700e1a72 --- /dev/null +++ b/conductor/tracks/video_analysis_campaign_20260621/TIER2_STARTER.md @@ -0,0 +1,243 @@ +# Tier 2 Starter Prompt: Video Analysis Campaign + +**Purpose.** This file is the dispatch prompt for Tier 2 autonomous agents picking up tracks in the `video_analysis_campaign_20260621` campaign. It supplements the auto-loaded `spec.md` + `plan.md` per `conductor/tier2/commands/tier-2-auto-execute.md` step 2. + +**Two prompt templates below:** +1. **Umbrella Tier 2** — for Phase 0 (tooling) + Phase 1 (5 scripts) + Phase 2 initialization (12 child tracks scaffolded with plan.md/metadata.json/state.toml). +2. **Per-child Tier 2** — for executing one child's 5-phase pipeline (Acquire → Keyframes → OCR → Synthesis → Verification). + +--- + +## Template 1: Umbrella Tier 2 (Phases 0 + 1 + 2 init) + +``` +Dispatch Tier 2 with: /tier-2-auto-execute video_analysis_campaign_20260621 + +Plus this context (paste BEFORE invoking): + +--- +TRACK: video_analysis_campaign_20260621 +TYPE: Multi-track research campaign (1 umbrella + 12 children + 1 synthesis = 14 folders) +STATUS: spec_approved; awaiting Phase 0 (tooling prerequisites) +PRIORITY: A (user-blocking research campaign) + +PASS 1 OF 3 (multi-pass — load-bearing framing): +- Pass 1 (THIS): information extraction + distillation → 12 deep-dive reports + cross-cutting synthesis +- Pass 2 (FUTURE, USER-led): de-obfuscation via user's math encoding notation. USER must rediscover the encoding before Pass 2 starts. +- Pass 3 (FUTURE, USER-led): projection to user's applied domain. USER must articulate "own caveats" before Pass 3 starts. +- CRITICAL: Pass 1 artifacts MUST be lossless. Per-video target: 1000-10000 LOC markdown. Over-summarization here is data loss that cascades. + +FILES TO READ IN THIS ORDER (do not skip): + +1. /TIER2_STARTER.md (this file) +2. ./spec.md (full design — 15 sections, ~600 lines) +3. ./plan.md (Phase 0+1 bite-sized tasks; Phase 2-4 brief pointers) +4. ./metadata.json (scope, risk_register, verification_criteria, user_directives) +5. ./state.toml (current_phase, task tracking) +6. ./README.md (child index) + +THEN at session start (per conductor/workflow.md Standard Task Workflow): +7. /AGENTS.md (critical anti-patterns, file naming, no day estimates, skip-marker policy) +8. /conductor/workflow.md (task workflow, Tier 2 sandbox conventions, failcount contract) +9. /conductor/code_styleguides/python.md (1-space indent, type hints, no comments) +10. /conductor/code_styleguides/error_handling.md (Result[T] pattern for new scripts) + +REFERENCE SCRIPTS (consult as needed, DO NOT import): +- C:/projects/forth/bootslop/download_videos.py (yt-dlp usage) +- C:/projects/forth/bootslop/extract_frames.py (cv2 + imagehash) +- C:/projects/forth/bootslop/process_visuals.py (winsdk OCR + visual heuristics) +- C:/projects/forth/bootslop/ocr_interaction.py (standalone OCR) + +KEY RISKS (from metadata.json risk_register): +- R1 + R10 (HIGH, verified 2026-06-21): yt-dlp, cv2, imagehash, pillow NOT in repo venv. Phase 0 prerequisite. +- R5 (CONFIRMED for 2 videos): 9vM4p9NN0Ts, lVynu4bo1rY failed oEmbed 401. yt-dlp may still work; verify in Phase 1 of those child tracks. +- R7 (MEDIUM): Pass 1 over-summarization loses signal for Pass 2. Enforce 1000-10000 LOC floor per child report. +- R8 (MEDIUM): Tier 2 capacity for 12+ child tracks — each child is independently shippable; the campaign is async. + +HARD CONSTRAINTS: +- NO day/hour/minute estimates in any artifact. Scope measured in files/sites only. +- NO src/*.py changes. NO new pyproject.toml deps beyond the 4 packages installed in Phase 0. +- NO comments in source code. Documentation lives in /docs. +- 1-space indent on all Python. Type hints on all public functions. +- All new scripts follow Result[T] convention per /conductor/code_styleguides/error_handling.md. +- Test runner: uv run python scripts/run_tests_batched.py (NEVER uv run pytest directly). + +VERIFICATION CRITERIA (gate for campaign completion): +- All 12 child tracks shipped with report.md (1000-10000 LOC) + summary.md (200-400 words) + artifacts/ +- Synthesis track shipped with per_video_summary.md + report.md +- 5 scripts in scripts/video_analysis/ with passing TDD tests +- End-of-track report at docs/reports/TRACK_COMPLETION_video_analysis_campaign_20260621.md +- state.toml updated to status = "completed" + +EXECUTION PLAN: +- Phase 0: 4 install tasks (yt-dlp, cv2/imagehash/PIL, OCR backend, scripts/ namespace scaffold) +- Phase 1: 5 scripts with TDD (delegate each to Tier 3 worker via mma_exec.py --role tier3-worker) +- Phase 2: Initialize each child track (plan.md + metadata.json + state.toml) — 12 tracks total. Per-child 5-phase pipeline execution is a SEPARATE Tier 2 dispatch per child (see Template 2). +- Phase 3: Synthesis track (blocked by all 12 children). Initialize + dispatch Tier 3 for cross-cutting report. +- Phase 4: Closeout — update umbrella README.md, write end-of-track report, move 14 folders to archive/, update chronology.md. + +WHEN STUCK: +- Multi-pass question? Re-read spec.md §0 + §11. +- Tooling question? Reference bootslop scripts (don't import). +- Style question? Check /conductor/code_styleguides/ + AGENTS.md. +- Per-child question? Read the child spec.md for that slug. +- State/plan question? Update plan.md and state.toml atomically per the per-task commit protocol in /conductor/tier2/agents/tier2-autonomous.md. +--- +``` + +--- + +## Template 2: Per-Child Tier 2 (one child's 5-phase pipeline) + +After Template 1 completes, dispatch a new Tier 2 per child track: + +``` +Dispatch Tier 2 with: /tier-2-auto-execute video_analysis__20260621 --resume + +Where is one of: +- cs229_building_llms (E, video #1) +- probability_logic (A, video #2) +- entropy_epiplexity (A, video #3) +- score_dynamics_giorgini (A, video #4) +- platonic_intelligence_kumar (B, video #5) +- free_lunches_levin (B, video #6) +- generic_systems_fields (C, video #7) +- brain_counterintuitive (C, video #8) +- neural_dynamics_miller (C, video #9) +- multiscale_hoffman (C, video #10) +- cs336_architectures (E, video #11) +- creikey_dl_cv (D, video #12) + +Plus this context (paste BEFORE invoking): + +--- +TRACK: video_analysis__20260621 +TYPE: Per-child research track (one of 12 in the video_analysis_campaign_20260621 umbrella) +STATUS: spec ✓ (scaffolded by umbrella Tier 2); plan ✓ + metadata ✓ + state ✓ (created by umbrella Tier 2 in Phase 2 init) + +PASS 1 OF 3 (multi-pass campaign — load-bearing): +- This child track produces raw artifacts (transcript.json, frames/, ocr.md) + a 1000-10000 LOC report.md + a 200-400 word summary.md. +- These artifacts feed Pass 2 (de-obfuscation) and Pass 3 (projection). They MUST be lossless. +- DO NOT over-summarize. The Tier 3 worker prompt must specify "1000-10000 LOC" target. + +FILES TO READ IN THIS ORDER: + +1. ./spec.md (lightweight — references umbrella, gives video details, specifies 7 deliverables + 5-phase pipeline + 8-section report structure) +2. /conductor/tracks/video_analysis_campaign_20260621/TIER2_STARTER.md (this parent file — for cross-track context) +3. /conductor/tracks/video_analysis_campaign_20260621/spec.md (full umbrella design) +4. /conductor/tracks/video_analysis_campaign_20260621/plan.md (campaign-level plan) +5. /conductor/tracks/video_analysis_campaign_20260621/README.md (child index — confirm this is the right child) + +THEN at session start (if first Tier 2 invocation in this session): +6. /AGENTS.md +7. /conductor/workflow.md +8. /conductor/code_styleguides/python.md +9. /conductor/code_styleguides/error_handling.md + +PIPELINE (5 phases per umbrella spec §FR5): + +Phase 1: Acquire +- Run scripts/video_analysis/extract_transcript.py /artifacts/transcript.json +- Run scripts/video_analysis/download_video.py /artifacts/video.mp4 (unless skip_video_download=true) +- For E-cluster children (cs229_building_llms, cs336_architectures): yt-dlp may fail per R5 — if so, fall back to manual transcript sourcing if available, or escalate. +- Commit artifacts atomically. + +Phase 2: Keyframes +- Run scripts/video_analysis/extract_keyframes.py