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.
This commit is contained in:
@@ -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.*
|
||||
@@ -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."}
|
||||
]
|
||||
}
|
||||
@@ -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.*
|
||||
@@ -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.*
|
||||
@@ -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."
|
||||
Reference in New Issue
Block a user