From cb00cba0c202604e192b3397316c3d49d08a1ebf Mon Sep 17 00:00:00 2001 From: Ed_ Date: Tue, 23 Jun 2026 20:33:42 -0400 Subject: [PATCH] conductor(deob_c11_ref): Initialize C11 reference track scaffold Pass 3 sub-track scaffolding: - spec.md: 14 sections, 4 cluster sub-reports + 1 main c11_convention.md + 1 tracks.md update - plan.md: 6 atomic tasks, per-file commits with git notes - metadata.json: scope, verification criteria, source files audited (17 primary + 5 fallback), risk register, user-directives-logged - state.toml: 3 phases, 7 tasks - README.md: track index + cross-references The 4 cluster sub-reports + main c11_convention.md + tracks.md update follow in separate atomic commits. --- .../README.md | 84 ++++++++++ .../metadata.json | 109 ++++++++++++ .../plan.md | 115 +++++++++++++ .../spec.md | 157 ++++++++++++++++++ .../state.toml | 57 +++++++ 5 files changed, 522 insertions(+) create mode 100644 conductor/tracks/video_analysis_deob_c11_reference_20260623/README.md create mode 100644 conductor/tracks/video_analysis_deob_c11_reference_20260623/metadata.json create mode 100644 conductor/tracks/video_analysis_deob_c11_reference_20260623/plan.md create mode 100644 conductor/tracks/video_analysis_deob_c11_reference_20260623/spec.md create mode 100644 conductor/tracks/video_analysis_deob_c11_reference_20260623/state.toml diff --git a/conductor/tracks/video_analysis_deob_c11_reference_20260623/README.md b/conductor/tracks/video_analysis_deob_c11_reference_20260623/README.md new file mode 100644 index 00000000..62270a54 --- /dev/null +++ b/conductor/tracks/video_analysis_deob_c11_reference_20260623/README.md @@ -0,0 +1,84 @@ +# C11 Reference — Track Index + +**Track:** `video_analysis_deob_c11_reference_20260623` +**Type:** Pass 3 sub-track (research/synthesis) +**Status:** spec DRAFT (pending user review) +**Date:** 2026-06-23 + +## What this track is + +Pass 3 will project the v2-deobfuscated outputs to C11/Python code. This sub-track produces a C11 reference document that captures the user's idiomatic C11 style — synthesized from ~25 primary source files (forth bootslop + Pikuma/duffle) with raddbg/src/base as the fallback for patterns the primary sources don't cover. + +## Track files + +| File | Purpose | +|---|---| +| `spec.md` | The design intent: 14 sections, the goals, the architecture reference, the out-of-scope items, the risk register, the verification criteria | +| `plan.md` | The TDD-ready plan: 6 atomic tasks (4 cluster sub-reports + 1 main report + 1 tracks.md update) | +| `metadata.json` | The machine-readable metadata: scope, verification criteria, source files audited, risk register, user-directives-logged | +| `state.toml` | The track state: 3 phases, 7 tasks, user-directives-logged | +| `README.md` | This file (the track index) | +| `research/cluster_0_pikuma_duffle.md` | Survey of 9 Pikuma duffle headers + 2 gte_hello files (PRIMARY) | +| `research/cluster_1_forth_bootslop_attempt_1.md` | Survey of 4 forth bootslop attempt_1 files (PRIMARY, user's own) | +| `research/cluster_2_forth_bootslop_references.md` | Survey of 2 forth reference files (PRIMARY, forth) | +| `research/cluster_3_raddbg_src_base.md` | Survey of 5 raddbg/src/base headers (FALLBACK) | +| `c11_convention.md` | The main C11 reference document (the synthesis) | + +## Source files audited + +### Primary (~25 files) + +| Source | Count | Role | +|---|---|---| +| Pikuma duffle (`C:\projects\Pikuma\ps1\code\duffle\`) | 9 headers | PRIMARY (Pikuma course-style C; the duffle library) | +| Pikuma gte_hello (`C:\projects\Pikuma\ps1\code\gte_hello\`) | 2 files | PRIMARY (single-header integration) | +| forth bootslop attempt_1 (`C:\projects\forth\bootslop\attempt_1\`) | 4 files | PRIMARY (user's own duffle integration) | +| forth bootslop references (`C:\projects\forth\bootslop\references\`) | 2 files | PRIMARY (forth references) | + +### Fallback (5 files) + +| Source | Count | Role | +|---|---|---| +| raddebugger/src/base (`C:\projects\raddebugger\src\base\`) | 5 headers | FALLBACK (raddbg is the "base" for stuff missing) | + +## What the C11 reference covers + +15 sections in `c11_convention.md`: +1. Overview (the user's idiomatic C11) +2. Naming conventions +3. Type system (TSet_, PtrSet_, Proc_, Struct_, Union_, Opt_, Ret_, Enum_) +4. Memory ordering (ooo_drift_, ooo_anchor_, ooo_drain_, ooo_weld_) +5. Inlining (I_, FI_, NI_) +6. Section / read-only placement (RO_, read_only) +7. Macro style (__VA_ARGS__, _Generic, static_assert) +8. Slice / arena allocators (Slice_, Str8, FArena) +9. Comment style (design-doc headers, the Style Notes block) +10. Build flags (INTELLISENSE_DIRECTIVES, pragma region/endregion) +11. Error handling (assert, slice_assert, StaticAssert) +12. Per-language `<<` / `>>` rendering (C11 specific) +13. The raddbg fallback (when duffle doesn't have the pattern) +14. Example program (a small C11 program using the conventions) +15. Cross-references + +## Sequence + +1. **Phase 1** (Tasks 1.1-1.4): Write the 4 cluster sub-reports (the evidence base). 4 atomic commits. +2. **Phase 2** (Task 2.1): Write the main `c11_convention.md` (the synthesis). 1 atomic commit. +3. **Phase 3** (Tasks 3.1-3.2): Manual review + tracks.md update. 1 atomic commit. + +**Total: 6 atomic commits.** + +## Next track + +After C11 reference SHIPPED + user approval: **`video_analysis_deob_pass3_20260623/`** (Pass 3 — the projection to C11/Python code). The c11_convention.md is the primary C11 style guide for Pass 3. + +## Cross-references + +- **Upstream:** `video_analysis_deob_apply_20260621/` (Pass 2, SHIPPED 2026-06-23) + `video_analysis_deob_lexicon_v2_20260623/` (v2 patch, SHIPPED 2026-06-23) +- **Downstream:** `video_analysis_deob_pass3_20260623/` (Pass 3, future, user-led) +- **Pattern precedent:** `video_analysis_deob_warmup_20260621/` (the warmup; the survey-style track structure) +- **Lexicon v2 per-language rendering:** `video_analysis_deob_lexicon_20260621/lexicon.md` §9 + +--- + +*End of `README.md`. 5 sections. The track is research/synthesis; no production code is written.* diff --git a/conductor/tracks/video_analysis_deob_c11_reference_20260623/metadata.json b/conductor/tracks/video_analysis_deob_c11_reference_20260623/metadata.json new file mode 100644 index 00000000..5d5a72c7 --- /dev/null +++ b/conductor/tracks/video_analysis_deob_c11_reference_20260623/metadata.json @@ -0,0 +1,109 @@ +{ + "track_id": "video_analysis_deob_c11_reference_20260623", + "name": "C11 Reference (Pass 3 Sub-Track - C11 Style Guide for Projection)", + "type": "research-synthesis", + "phase": "Pass 3 sub-track (between Pass 2 + v2 closeout and Pass 3 init)", + "date": "2026-06-23", + "status": "spec-pending-review", + "blocked_by": [ + "video_analysis_deob_apply_20260621 (SHIPPED 2026-06-23, commit 8f2e8a69)", + "video_analysis_deob_lexicon_v2_20260623 (SHIPPED 2026-06-23, commit b0c75992)" + ], + "blocks": [ + "video_analysis_deob_pass3_20260623 (future, user-led, the C11/Python projection)" + ], + "method": "direct-tier2-synthesis", + "rationale": "The C11 reference is a synthesis of ~25 primary source files. Tier 3 sub-agents would lose context on the duffle vs raddbg distinction. Tier 2 holds the full convention in mind.", + "scope": { + "new_files": [ + "conductor/tracks/video_analysis_deob_c11_reference_20260623/spec.md", + "conductor/tracks/video_analysis_deob_c11_reference_20260623/plan.md", + "conductor/tracks/video_analysis_deob_c11_reference_20260623/metadata.json", + "conductor/tracks/video_analysis_deob_c11_reference_20260623/state.toml", + "conductor/tracks/video_analysis_deob_c11_reference_20260623/README.md", + "conductor/tracks/video_analysis_deob_c11_reference_20260623/research/cluster_0_pikuma_duffle.md", + "conductor/tracks/video_analysis_deob_c11_reference_20260623/research/cluster_1_forth_bootslop_attempt_1.md", + "conductor/tracks/video_analysis_deob_c11_reference_20260623/research/cluster_2_forth_bootslop_references.md", + "conductor/tracks/video_analysis_deob_c11_reference_20260623/research/cluster_3_raddbg_src_base.md", + "conductor/tracks/video_analysis_deob_c11_reference_20260623/c11_convention.md" + ], + "modified_files": [ + "conductor/tracks.md" + ], + "deleted_files": [], + "new_sites": 9, + "modified_sites": 1, + "total_files": 10 + }, + "tasks_count": 6, + "commits_count": 6, + "verification_criteria": [ + "All 4 cluster sub-reports are written (FR1.1-FR1.4)", + "The main c11_convention.md is written with all 15 sections (FR2.1)", + "The per-language << / >> rendering is documented for C11 (FR2.2)", + "The track scaffold is complete (FR3.1-FR3.5)", + "tracks.md is updated with the new row (FR4.1)", + "No src/*.py changes (NFR1)", + "No pyproject.toml dependencies (NFR2)", + "No day estimates (NFR3)", + "Per-task atomic commits (NFR4)", + "Git notes attached (NFR5)", + "Lossless coverage of source conventions (NFR6)" + ], + "source_files_audited": { + "primary": [ + "C:\\projects\\Pikuma\\ps1\\code\\duffle\\dsl.h (10 KB)", + "C:\\projects\\Pikuma\\ps1\\code\\duffle\\memory.h (5 KB)", + "C:\\projects\\Pikuma\\ps1\\code\\duffle\\math.h (2 KB)", + "C:\\projects\\Pikuma\\ps1\\code\\duffle\\gp.h (4 KB)", + "C:\\projects\\Pikuma\\ps1\\code\\duffle\\gte.h (30 KB)", + "C:\\projects\\Pikuma\\ps1\\code\\duffle\\gcc_asm.h (27 KB)", + "C:\\projects\\Pikuma\\ps1\\code\\duffle\\mips.h (25 KB)", + "C:\\projects\\Pikuma\\ps1\\code\\duffle\\lottes_tape.h (17 KB)", + "C:\\projects\\Pikuma\\ps1\\code\\duffle\\strings.h (0.1 KB)", + "C:\\projects\\Pikuma\\ps1\\code\\gte_hello\\hello_gte.h (6 KB)", + "C:\\projects\\Pikuma\\ps1\\code\\gte_hello\\hello_gte.c (13 KB)", + "C:\\projects\\forth\\bootslop\\attempt_1\\duffle.amd64.win32.h (32 KB)", + "C:\\projects\\forth\\bootslop\\attempt_1\\main.c (50 KB)", + "C:\\projects\\forth\\bootslop\\attempt_1\\microui.c (38 KB)", + "C:\\projects\\forth\\bootslop\\attempt_1\\microui.h (10 KB)", + "C:\\projects\\forth\\bootslop\\references\\jombloforth\\jombloforth.asm (25 KB)", + "C:\\projects\\forth\\bootslop\\references\\jombloforth\\jombloforth.f (13 KB)" + ], + "fallback": [ + "C:\\projects\\raddebugger\\src\\base\\base_core.h (36 KB)", + "C:\\projects\\raddebugger\\src\\base\\base_arena.h (3 KB)", + "C:\\projects\\raddebugger\\src\\base\\base_math.h (20 KB)", + "C:\\projects\\raddebugger\\src\\base\\base_memory.h (0.6 KB)", + "C:\\projects\\raddebugger\\src\\base\\base_hash.h (0.8 KB)" + ] + }, + "pre_existing_failures_remaining": [], + "deferred_to_followup_tracks": [ + { + "title": "Pass 3 — projection to C11/Python code", + "description": "Apply the v2 lexicon + the c11_convention.md to produce C11 (raddbg/duffel/pikuma/forth bootslop conventions) and Python (manual_slop convention) code for each Pass 1 video + the synthesis. Hardware target: up to $10k workstation.", + "track_status": "future, user-led" + } + ], + "estimated_effort": { + "method": "scope (per workflow.md Tier 1 Track Initialization Rules). NO day estimates.", + "phase_1": "4 tasks: 4 cluster sub-reports (~400-550 LOC total)", + "phase_2": "1 task: the main c11_convention.md synthesis (~500-1000 LOC)", + "phase_3": "2 tasks: manual review + tracks.md update" + }, + "risk_register": [ + {"id": "R1", "risk": "The user's duffle style and raddbg style conflict; the reference can't unify them", "likelihood": "low", "impact": "medium", "mitigation": "Document them as separate substyles; flag where each applies (duffle = primary; raddbg = base for U64/U32/etc.)"}, + {"id": "R2", "risk": "The 4 cluster sub-reports miss key conventions in the source files", "likelihood": "low", "impact": "low", "mitigation": "Manual review of each cluster against the actual source; cross-check the main report against the cluster reports"}, + {"id": "R3", "risk": "The c11_convention.md is too long (over 1000 LOC)", "likelihood": "medium", "impact": "low", "mitigation": "Trim to the most important conventions; link to source files for details"}, + {"id": "R4", "risk": "The c11_convention.md is too short (under 500 LOC) and missing key patterns", "likelihood": "low", "impact": "medium", "mitigation": "Survey the 4 cluster sub-reports before writing the main report; ensure each convention is documented"}, + {"id": "R5", "risk": "The user disagrees with one of the documented conventions after seeing the reference", "likelihood": "low", "impact": "medium", "mitigation": "The reference is documented as 'the user's idiomatic C11 from these sources' not 'the only correct C11 style'; the user can override per video"}, + {"id": "R6", "risk": "The per-language << / >> rendering is not in scope but the v2 lexicon requires it", "likelihood": "low", "impact": "low", "mitigation": "Include a brief C11 rendering section in the main report; the full per-language rendering is in the v2 lexicon's lexicon.md 9"}, + {"id": "R7", "risk": "The git history is broken by the new track folder", "likelihood": "low", "impact": "low", "mitigation": "Standard track folder + per-task atomic commits; v1/v2 states are preserved in git history"} + ], + "user_directives_logged": [ + {"id": "c11_convention_from_existing_codebases", "date": "2026-06-23", "directive": "Per user 2026-06-23: 'use the forth bootslop and pikuma then. Use raddbg's base for stuff missing. otherwise go for jai/odin.' The C11 reference uses forth bootslop + Pikuma as PRIMARY sources and raddebugger/src/base as the FALLBACK for patterns the primary sources don't cover. Jai/Odin is not needed (the user prefers the C11 conventions from their existing codebases)."}, + {"id": "raddbg_scope_correction", "date": "2026-06-23", "directive": "Per user 2026-06-23: 'raddbg/src/base is not over 200 files..' The raddbg scope is specifically raddbg/src/base (24 .c + 24 .h = 48 files), not the full raddbg/src (492 files). This focuses the survey on the 'base' layer only."}, + {"id": "applied_domain_c11_or_python", "date": "2026-06-23", "directive": "Per user 2026-06-23: 'The applied domain is making a simple program in C11 or python that conveys what the subject video provides. If in c11 it should follow a specific covention of c11 that raddbg uses or that I use with my duffle libs in pikuma ps1 or the forth bootslop projects.' This C11 reference synthesizes the duffle/pikuma/forth bootslop/raddbg conventions into a single style guide for Pass 3."} + ] +} diff --git a/conductor/tracks/video_analysis_deob_c11_reference_20260623/plan.md b/conductor/tracks/video_analysis_deob_c11_reference_20260623/plan.md new file mode 100644 index 00000000..871ccf34 --- /dev/null +++ b/conductor/tracks/video_analysis_deob_c11_reference_20260623/plan.md @@ -0,0 +1,115 @@ +# Plan — C11 Reference (Pass 3 Sub-Track) + +**Track:** `video_analysis_deob_c11_reference_20260623` +**Method:** Direct Tier 2 synthesis (no Tier 3 delegation — the scope is focused, not cross-cluster; Tier 3 would lose context on the duffle vs raddbg distinction) +**Atomicity:** Per-file atomic commits with git notes + +--- + +## Phase 1: Read the primary source files + +Focus: Read 9 Pikuma duffle headers + 4 forth bootslop files + 2 forth references + 5-10 raddbg/src/base headers. Document per-file observations in cluster sub-reports. + +### Task 1.1: Write `cluster_0_pikuma_duffle.md` + +- **WHERE:** `conductor/tracks/video_analysis_deob_c11_reference_20260623/research/cluster_0_pikuma_duffle.md` +- **WHAT:** Survey of 9 Pikuma duffle headers (dsl.h, memory.h, math.h, gp.h, gte.h, gcc_asm.h, mips.h, lottes_tape.h, strings.h) + 2 gte_hello files. Document the duffle type system (U1/U2/U4, S1/S2/S4, B1/B2/B4), the macro style (`I_`, `FI_`, `NI_`, `LP_`, `internal`, `global`, `RO_`, `T_`), the hand-rolled DSL pattern (`enc_*`, `asm_inline`, `asm_clobber`, `clb_*`), the slice/arena allocator (`Slice_`, `Str8`, `FArena`, `farena_push`), the `INTELLISENSE_DIRECTIVES` pattern, the `pragma region`/`endregion` for code folding, the design-doc comment style, the byte-width type convention, the `TSet_`/`PtrSet_` typedef pattern, the `Proc_`/`Struct_`/`Union_`/`Enum_`/`Opt_`/`Ret_` macros. +- **HOW:** Synthesize the duffle conventions from the already-read files. ~150-200 LOC. +- **SAFETY:** This is a synthesis; cross-check the cluster report against the source files before committing. +- **COMMIT:** `conductor(deob_c11_ref): cluster_0_pikuma_duffle.md - 9 headers + 2 gte_hello files; primary convention source` +- **GIT NOTE:** "Primary C11 convention source: 9 Pikuma duffle headers + 2 gte_hello files. Documents the duffle type system (U1/U2/U4, S1/S2/S4, B1/B2/B4), the macro style (I_, FI_, NI_, LP_, internal, global, RO_, T_), the hand-rolled DSL pattern (enc_*, asm_inline, asm_clobber, clb_*), the slice/arena allocator, the INTELLISENSE_DIRECTIVES pattern, the pragma region pattern, the design-doc comment style." + +### Task 1.2: Write `cluster_1_forth_bootslop_attempt_1.md` + +- **WHERE:** `conductor/tracks/video_analysis_deob_c11_reference_20260623/research/cluster_1_forth_bootslop_attempt_1.md` +- **WHAT:** Survey of 4 forth bootslop attempt_1 files (duffle.amd64.win32.h, main.c, microui.c, microui.h). Document how the user applies duffle conventions in their own project. Note any user-specific extensions or modifications. +- **HOW:** Note the file structure; document the integration of duffle headers; note any deviations from the duffle convention. ~50-100 LOC. +- **SAFETY:** Same as Task 1.1. +- **COMMIT:** `conductor(deob_c11_ref): cluster_1_forth_bootslop_attempt_1.md - 4 files (user's own duffle integration)` +- **GIT NOTE:** "User's own project: 4 forth bootslop attempt_1 files (duffle.amd64.win32.h, main.c, microui.c, microui.h). Documents how the user applies duffle conventions in their own project; includes the microui library integration (MU_* prefix style)." + +### Task 1.3: Write `cluster_2_forth_bootslop_references.md` + +- **WHERE:** `conductor/tracks/video_analysis_deob_c11_reference_20260623/research/cluster_2_forth_bootslop_references.md` +- **WHAT:** Survey of 2 forth references (jombloforth.asm, jombloforth.f). Document the forth conventions (forth is not C11 but the user references it for C-like idioms). +- **HOW:** Note the forth-specific style; document the C-like idioms that translate to C11. ~50-100 LOC. +- **SAFETY:** Same as Task 1.1. +- **COMMIT:** `conductor(deob_c11_ref): cluster_2_forth_bootslop_references.md - 2 forth reference files` +- **GIT NOTE:** "Forth references: 2 files (jombloforth.asm, jombloforth.f). Documents forth-specific style and the C-like idioms that translate to C11 (the user's own forth conventions inform the C11 style)." + +### Task 1.4: Write `cluster_3_raddbg_src_base.md` + +- **WHERE:** `conductor/tracks/video_analysis_deob_c11_reference_20260623/research/cluster_3_raddbg_src_base.md` +- **WHAT:** Survey of 5 raddbg/src/base headers (base_core.h, base_arena.h, base_math.h, base_memory.h, base_hash.h). Document the raddbg style as the FALLBACK for patterns duffle doesn't cover (U64/U32, Vec2F32/Vec3S32, String8, push_array_aligned, the codebase keywords pattern). +- **HOW:** Note the raddbg style (CamelCase types, `internal`/`global`/`local_persist`/`read_only`/`thread_static`, `StaticAssert`, the designator-initializer macro pattern). Document where raddbg supplements duffle. ~100-150 LOC. +- **SAFETY:** Same as Task 1.1. +- **COMMIT:** `conductor(deob_c11_ref): cluster_3_raddbg_src_base.md - 5 raddbg/src/base headers (fallback base)` +- **GIT NOTE:** "Fallback base: 5 raddbg/src/base headers (base_core.h, base_arena.h, base_math.h, base_memory.h, base_hash.h). Documents the raddbg style for patterns duffle doesn't cover: U64/U32, Vec2F32/Vec3S32, String8, push_array_aligned, StaticAssert, the codebase keywords pattern." + +--- + +## Phase 2: Synthesize the main report + +Focus: Write `c11_convention.md` synthesizing the 4 cluster sub-reports into a single C11 reference document. + +### Task 2.1: Write `c11_convention.md` + +- **WHERE:** `conductor/tracks/video_analysis_deob_c11_reference_20260623/c11_convention.md` +- **WHAT:** The synthesis. ~500-1000 LOC. Sections: + 1. Overview (the user's idiomatic C11; borrowable from duffle/forth bootslop/Pikuma with raddbg fallback) + 2. Naming conventions (type modifiers, function names, variable names, struct/enum naming) + 3. Type system (TSet_, PtrSet_, Proc_, Struct_, Union_, Opt_, Ret_, Enum_) + 4. Memory ordering (ooo_drift_, ooo_anchor_, ooo_drain_, ooo_weld_) + 5. Inlining (I_, FI_, NI_) + 6. Section / read-only placement (RO_, read_only) + 7. Macro style (__VA_ARGS__, _Generic, static_assert, __builtin_offsetof, __builtin_expect) + 8. Slice / arena allocators (Slice_, Str8, FArena, farena_push, farena_reset) + 9. Comment style (design-doc headers, the Style Notes block, //- rjf: prefixes) + 10. Build flags (INTELLISENSE_DIRECTIVES, pragma region/endregion) + 11. Error handling (assert, slice_assert, StaticAssert) + 12. Per-language << / >> rendering (C11 specific; per the v2 lexicon) + 13. The raddbg fallback (when duffle doesn't have the pattern) + 14. Example program (a small C11 program using the conventions) + 15. Cross-references +- **HOW:** Write the main report from the 4 cluster sub-reports. Each section references the relevant cluster report. +- **SAFETY:** This is the synthesis; the 4 cluster sub-reports are the evidence base. Each convention should be traceable to a source file. +- **COMMIT:** `conductor(deob_c11_ref): c11_convention.md - the synthesis; 15 sections; ~600-800 LOC` +- **GIT NOTE:** "Main C11 reference: 15 sections; ~600-800 LOC. Synthesizes the duffle/forth bootslop/Pikuma conventions with the raddbg fallback. Includes the per-language << / >> rendering for C11 (per the v2 lexicon). Hands off to Pass 3 as the primary C11 style guide." + +--- + +## Phase 3: Verification + tracks.md update + +Focus: Manual review + tracks.md registration. + +### Task 3.1: Manual review + +- **WHERE:** All 5 new files (4 cluster + 1 main) +- **WHAT:** Verify each cluster sub-report is grounded in the source files; verify the main report is consistent with the cluster sub-reports. +- **HOW:** Read each section; cross-check against the cluster reports. + +### Task 3.2: Update `tracks.md` + +- **WHERE:** `conductor/tracks.md` +- **WHAT:** Add a new row for `video_analysis_deob_c11_reference_20260623` after row 29a. +- **HOW:** Find the existing 29a row; insert the new row. +- **SAFETY:** Standard registry update. +- **COMMIT:** `conductor(registry): Add C11 reference track row to tracks.md` +- **GIT NOTE:** "Project registry updated with the C11 reference sub-track of Pass 3." + +--- + +## Atomic commit summary + +- Task 1.1: cluster_0_pikuma_duffle.md (1 commit) +- Task 1.2: cluster_1_forth_bootslop_attempt_1.md (1 commit) +- Task 1.3: cluster_2_forth_bootslop_references.md (1 commit) +- Task 1.4: cluster_3_raddbg_src_base.md (1 commit) +- Task 2.1: c11_convention.md (1 commit) +- Task 3.2: tracks.md (1 commit) + +**Total: 6 atomic commits.** Per the workflow's "atomic per-task commits" rule, each commit is a safe rollback point. Each has a 1-3 sentence git note. + +--- + +*End of `plan.md`. 6 atomic commits. No Tier 3 delegation (focused scope). Verification by manual review.* diff --git a/conductor/tracks/video_analysis_deob_c11_reference_20260623/spec.md b/conductor/tracks/video_analysis_deob_c11_reference_20260623/spec.md new file mode 100644 index 00000000..601aab79 --- /dev/null +++ b/conductor/tracks/video_analysis_deob_c11_reference_20260623/spec.md @@ -0,0 +1,157 @@ +# Track Specification: C11 Reference (Pass 3 Sub-Track) + +**Track ID:** `video_analysis_deob_c11_reference_20260623` +**Type:** Pass 3 sub-track (research/synthesis, no code) +**Date:** 2026-06-23 +**Status:** spec DRAFT (pending user review) +**Blocked by:** `video_analysis_deob_apply_20260621` (SHIPPED 2026-06-23) + `video_analysis_deob_lexicon_v2_20260623` (SHIPPED 2026-06-23) +**Blocks:** Pass 3 (the projection to C11/Python code) + +--- + +## Overview + +Pass 3 will project the v2-deobfuscated outputs to C11/Python code. The user has specified the applied domain: C11 following the user's conventions (raddbg, duffle, Pikuma, forth bootslop), or Python (manual_slop). This sub-track produces a C11 reference document that captures the user's idiomatic C11 style — synthesized from ~25 primary source files (forth bootslop + Pikuma/duffle) with raddbg/src/base as the fallback for patterns the primary sources don't cover. + +**Why this exists:** the C11 videos in Pass 3 need a consistent C11 style guide. Without it, the LLM would invent its own style or copy random C conventions. With it, the LLM produces code that reads like the user's own: the same underscore-suffixed type modifiers (`R_`, `V_`, `LP_`, `I_`, `FI_`, `NI_`, `RO_`, `T_`), the same hand-rolled DSL pattern, the same memory-ordering vocabulary, the same design-doc comment style. + +**Why not skip this and use raddbg directly:** raddbg is a real codebase but its style is its own (Epic Games Tools' style: `internal`/`global`/`local_persist`, `U64`/`U32`/`B32`, `String8`/`Vec2F32`). The user's own duffle/forth bootslop style is different: `I_`/`FI_/`NI_`/`RO_`, `U1`/`U2`/`U4`/`S1`/`S2`/`S4`, `Str8`/`V2_S2`/`M3_S2`. The user's style is the one that reads like "the user" — that's what Pass 3 should produce. + +--- + +## Current State Audit (as of 2026-06-23, commit `b0c75992`) + +### Already Implemented (DO NOT re-implement) + +- **The v2 lexicon substrate** (`lexicon.md` + `terms_catalog.md` + `dedup_map.md` + `prompt_template.md` + `report.md` v2) — the canonical input for Pass 3. +- **The 6 open questions for Pass 3** (answered in the v2 track): applied domain = C11/Python; user-specific forms = annotation if not code; indefinites use placeholder scheme; template notation B as default; criteria are OK; Pass 3 = markdown docs + code files. +- **The 12 refinements + 8 gaps** documented in `apply_report.md` — for the lexicon, not the C11 reference. +- **The 33 deliverables + 2 reports** from Pass 2 — intermediate artifacts; Pass 3 will use the v2 lexicon to produce code directly. + +### Gaps to Fill (This Track's Scope) + +A C11 reference document covering: + +1. **Naming conventions** (type modifiers, function names, variable names, struct/enum naming) +2. **Type system** (the user's hand-rolled DSL — `TSet_`, `PtrSet_`, `Proc_`, `Struct_`, `Union_`, `Opt_`, `Ret_`, `Enum_`) +3. **Memory ordering** (`ooo_drift_`, `ooo_anchor_`, `ooo_drain_`, `ooo_weld_`, `latch_store`, `pulse_rfo`, `tact_acquire`, `tact_release`) +4. **Inlining** (`I_`, `FI_`, `NI_`) +5. **Section / read-only placement** (`RO_`, `read_only`) +6. **Macro style** (`__VA_ARGS__`, `_Generic`, `static_assert`, `__builtin_offsetof`, `__builtin_expect`) +7. **Slice / arena allocators** (`Slice_`, `Str8`, `FArena`, `farena_push`, `farena_reset`) +8. **Comment style** (heavy design-doc headers, the `Style Notes` block, `//- rjf:` prefixes) +9. **Build flags** (the `INTELLISENSE_DIRECTIVES` pattern, `#pragma region`/`endregion` for folding) +10. **Error handling** (`assert`, `slice_assert`, `StaticAssert`) +11. **Per-language `<<` / `>>` rendering** (C11: `much_less` / `much_greater` / `weakly_coupled` with `tolerance`) +12. **The raddbg fallback** (when duffle doesn't have the pattern: `U64`/`U32` from raddbg's `base_core.h`) + +--- + +## Goals + +1. **Synthesize the user's C11 convention** from 25 primary source files (forth bootslop + Pikuma/duffle) + 5-10 fallback files (raddbg/src/base). +2. **Document the convention** in `c11_convention.md` (~500-1000 LOC) at the track root. +3. **Document the per-language rendering** for `<<` / `>>` (C11 specific). +4. **Document the raddbg fallback** for patterns duffle doesn't cover. +5. **Hand off to Pass 3** — Pass 3 reads `c11_convention.md` as the primary C11 style guide. + +--- + +## Functional Requirements + +### FR1: Cluster sub-reports (evidence base) + +- **FR1.1:** `research/cluster_0_pikuma_duffle.md` — survey of 9 Pikuma duffle headers (dsl.h, memory.h, math.h, gp.h, gte.h, gcc_asm.h, mips.h, lottes_tape.h, strings.h) + 1 gte_hello file. ~150-200 LOC. +- **FR1.2:** `research/cluster_1_forth_bootslop_attempt_1.md` — survey of 4 files (duffle.amd64.win32.h, main.c, microui.c, microui.h). ~50-100 LOC. +- **FR1.3:** `research/cluster_2_forth_bootslop_references.md` — survey of 2 source files (jombloforth.asm, jombloforth.f). ~50-100 LOC. +- **FR1.4:** `research/cluster_3_raddbg_src_base.md` — survey of 5-10 raddbg/src/base headers (base_core.h, base_arena.h, base_math.h, base_memory.h, base_hash.h). ~100-150 LOC. + +### FR2: Main report + +- **FR2.1:** `c11_convention.md` — the synthesis. ~500-1000 LOC. Sections per the goals above. +- **FR2.2:** Per-language rendering section for C11 (per the v2 lexicon's per-language `<<` / `>>` requirement). +- **FR2.3:** Per-language rendering note for Python (brief; not the focus of this track but referenced). + +### FR3: Track scaffold + +- **FR3.1:** `spec.md` (this file) +- **FR3.2:** `plan.md` (the TDD-ready plan; markdown; verification by manual review) +- **FR3.3:** `metadata.json` (scope, verification criteria, risk register, user-directives-logged) +- **FR3.4:** `state.toml` (phases, tasks, verification) +- **FR3.5:** `README.md` (track index) + +### FR4: tracks.md update + +- **FR4.1:** Add a new row for `video_analysis_deob_c11_reference_20260623` to `conductor/tracks.md` after row 29a (v2 patch). + +--- + +## Non-Functional Requirements + +- **NFR1: No `src/*.py` changes.** Research/synthesis track; no production code. +- **NFR2: No `pyproject.toml` dependencies.** Markdown only. +- **NFR3: No day estimates.** Scope measured in files (4 cluster sub-reports + 1 main report + 1 new changelog + 1 new track scaffold = 7 new files + 1 modified file). +- **NFR4: Per-task atomic commits.** 1 commit per cluster sub-report + 1 commit for the main report + 1 commit for tracks.md = ~6 commits. +- **NFR5: Git notes per commit.** Each commit has a 1-3 sentence summary attached via `git notes add`. +- **NFR6: Lossless.** Every convention in the source files is documented. No convention is dropped. +- **NFR7: Secular sanitization preserved.** N/A for this track (no esoteric content). +- **NFR8: 1-space indent.** N/A (no code). + +--- + +## Architecture Reference + +- **`video_analysis_deob_warmup_20260621/`** — the warmup. The pattern for survey-style tracks. +- **`video_analysis_deob_lexicon_20260621/`** — the lexicon (v1). The reference for how a track is structured. +- **`video_analysis_deob_lexicon_v2_20260623/`** — the v2 patch. The most recent precedent for a focused track. +- **`C:\projects\Pikuma\ps1\code\duffle\`** — 9 .h files. PRIMARY convention source. +- **`C:\projects\Pikuma\ps1\code\gte_hello\`** — 2 files (1 .c + 1 .h). PRIMARY. +- **`C:\projects\forth\bootslop\attempt_1\`** — 4 files (2 .c + 2 .h). PRIMARY (user's own). +- **`C:\projects\forth\bootslop\references\`** — 2 source files (1 .asm + 1 .f). PRIMARY (forth references). +- **`C:\projects\raddebugger\src\base\`** — 48 files (24 .c + 24 .h). FALLBACK (raddbg is the "base" for stuff missing). + +--- + +## Out of Scope + +- **Jai/Odin sample** — the user explicitly said to use the C11 references (forth bootslop + Pikuma + raddbg fallback). Jai/Odin is not needed. +- **The Sectored Language V1** — the v2 patch noted that pseudo sectr lang is incomplete; this track does not address Sectored Language specifically. +- **The 33 Pass 2 deliverables** — they are intermediate artifacts; Pass 3 will use the v2 lexicon + this C11 reference. +- **The 12 Pass 2 refinements + 8 gaps** — already documented; the C11 reference is orthogonal. +- **The 5 DEFERRED gaps** (lexicon v3) — orthogonal to C11 reference. +- **Production code** — this is a research/synthesis track; no code is written. + +--- + +## Risk Register + +| # | Risk | Likelihood | Impact | Mitigation | +|---|---|---|---|---| +| R1 | The user's duffle style and raddbg style conflict; the reference can't unify them | low | medium | Document them as separate substyles; flag where each applies (duffle = primary; raddbg = base for U64/U32/etc.) | +| R2 | The 4 cluster sub-reports miss key conventions in the source files | low | low | Manual review of each cluster against the actual source; cross-check the main report against the cluster reports | +| R3 | The c11_convention.md is too long (over 1000 LOC) | medium | low | Trim to the most important conventions; link to source files for details | +| R4 | The c11_convention.md is too short (under 500 LOC) and missing key patterns | low | medium | Survey the 4 cluster sub-reports before writing the main report; ensure each convention is documented | +| R5 | The user disagrees with one of the documented conventions after seeing the reference | low | medium | The reference is documented as "the user's idiomatic C11 from these sources" not "the only correct C11 style"; the user can override per video | +| R6 | The per-language `<<` / `>>` rendering is not in scope but the v2 lexicon requires it | low | low | Include a brief C11 rendering section in the main report; the full per-language rendering is in the v2 lexicon's `lexicon.md` §9 | +| R7 | The git history is broken by the new track folder | low | low | Standard track folder + per-task atomic commits; v1/v2 states are preserved in git history | + +--- + +## Verification Criteria + +- [ ] All 4 cluster sub-reports are written (FR1.1-FR1.4) +- [ ] The main `c11_convention.md` is written with all 12 sections (FR2.1) +- [ ] The per-language `<<` / `>>` rendering is documented for C11 (FR2.2) +- [ ] The track scaffold is complete (FR3.1-FR3.5) +- [ ] `tracks.md` is updated with the new row (FR4.1) +- [ ] No `src/*.py` changes (NFR1) +- [ ] No `pyproject.toml` dependencies (NFR2) +- [ ] No day estimates (NFR3) +- [ ] Per-task atomic commits (NFR4) +- [ ] Git notes attached (NFR5) +- [ ] Lossless coverage of source conventions (NFR6) +- [ ] ~6 atomic commits total + +--- + +*End of `spec.md`. 14 sections. Scope: 4 cluster sub-reports + 1 main report + 1 track scaffold + 1 tracks.md update.* diff --git a/conductor/tracks/video_analysis_deob_c11_reference_20260623/state.toml b/conductor/tracks/video_analysis_deob_c11_reference_20260623/state.toml new file mode 100644 index 00000000..4e316d6e --- /dev/null +++ b/conductor/tracks/video_analysis_deob_c11_reference_20260623/state.toml @@ -0,0 +1,57 @@ +# Track state for video_analysis_deob_c11_reference_20260623 +# Updated by Tier 2 Tech Lead during execution + +[meta] +track_id = "video_analysis_deob_c11_reference_20260623" +name = "C11 Reference (Pass 3 Sub-Track - C11 Style Guide for Projection)" +status = "active" +current_phase = 1 +last_updated = "2026-06-23" + +[blocked_by] +video_analysis_deob_apply_20260621 = "shipped 2026-06-23 (8f2e8a69)" +video_analysis_deob_lexicon_v2_20260623 = "shipped 2026-06-23 (b0c75992)" + +[blocks] +# Pass 3 (projection to C11/Python code, future, user-led) is the next user-led track +video_analysis_deob_pass3_20260623 = "planned in video_analysis_deob_c11_reference_20260623" + +[phases] +phase_1 = { status = "pending", checkpointsha = "", name = "Read the primary source files (4 cluster sub-reports)" } +phase_2 = { status = "pending", checkpointsha = "", name = "Synthesize the main c11_convention.md report" } +phase_3 = { status = "pending", checkpointsha = "", name = "Verification + tracks.md update" } + +[tasks] +# Phase 1 (cluster sub-reports) +t1_1 = { status = "pending", commit_sha = "", description = "Write cluster_0_pikuma_duffle.md: 9 Pikuma duffle headers + 2 gte_hello files" } +t1_2 = { status = "pending", commit_sha = "", description = "Write cluster_1_forth_bootslop_attempt_1.md: 4 forth bootslop files" } +t1_3 = { status = "pending", commit_sha = "", description = "Write cluster_2_forth_bootslop_references.md: 2 forth reference files" } +t1_4 = { status = "pending", commit_sha = "", description = "Write cluster_3_raddbg_src_base.md: 5 raddbg/src/base headers" } + +# Phase 2 (main report) +t2_1 = { status = "pending", commit_sha = "", description = "Write c11_convention.md: the synthesis; 15 sections; ~600-800 LOC" } + +# Phase 3 (verification + tracks.md) +t3_1 = { status = "pending", commit_sha = "", description = "Manual review: verify each cluster report is grounded in source; main report is consistent with cluster reports" } +t3_2 = { status = "pending", commit_sha = "", description = "Update tracks.md: add new row for c11_reference track" } + +[verification] +all_4_cluster_reports = false +main_report_written = false +per_language_rendering = false +track_scaffold_complete = false +tracks_md_updated = false +no_src_changes = false +no_pyproject_deps = false +no_day_estimates = false +atomic_commits = false +git_notes_attached = false +lossless_coverage = false + +[user_directives_logged] +c11_convention_from_existing_codebases = "Per user 2026-06-23: 'use the forth bootslop and pikuma then. Use raddbg's base for stuff missing. otherwise go for jai/odin.' The C11 reference uses forth bootslop + Pikuma as PRIMARY sources and raddebugger/src/base as the FALLBACK for patterns the primary sources don't cover." +raddbg_scope_correction = "Per user 2026-06-23: 'raddbg/src/base is not over 200 files..' The raddbg scope is specifically raddbg/src/base (24 .c + 24 .h = 48 files), not the full raddbg/src (492 files)." +applied_domain_c11_or_python = "Per user 2026-06-23: 'The applied domain is making a simple program in C11 or python that conveys what the subject video provides. If in c11 it should follow a specific covention of c11 that raddbg uses or that I use with my duffle libs in pikuma ps1 or the forth bootslop projects. For python it should use manual slop's convention.'" + +[no_day_estimates] +"Enforced per conductor/workflow.md Tier 1 Track Initialization Rules. Scope measured in files (4 cluster sub-reports + 1 main report + 1 track scaffold = 6 new + 1 modified = 7 file changes). 6 atomic commits planned."