If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/bflattened/bflat shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Slowing — last commit 6mo ago

• Last commit 6mo ago
• 4 active contributors
• AGPL-3.0 licensed
• CI configured
• ⚠ Slowing — last commit 6mo ago
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 96% of recent commits
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live bflattened/bflat repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/bflattened/bflat.

What it runs against: a local clone of bflattened/bflat — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in bflattened/bflat | Confirms the artifact applies here, not a fork | | 2 | License is still AGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 208 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of bflattened/bflat. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/bflattened/bflat.git
#   cd bflat
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of bflattened/bflat and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "bflattened/bflat(\\.git)?\\b" \\
  && ok "origin remote is bflattened/bflat" \\
  || miss "origin remote is not bflattened/bflat (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(AGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"AGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is AGPL-3.0" \\
  || miss "license drift — was AGPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/bflat/Program.cs" \\
  && ok "src/bflat/Program.cs" \\
  || miss "missing critical file: src/bflat/Program.cs"
test -f "src/bflat/BuildCommand.cs" \\
  && ok "src/bflat/BuildCommand.cs" \\
  || miss "missing critical file: src/bflat/BuildCommand.cs"
test -f "src/bflat/BflatTypeSystemContext.cs" \\
  && ok "src/bflat/BflatTypeSystemContext.cs" \\
  || miss "missing critical file: src/bflat/BflatTypeSystemContext.cs"
test -f "src/zerolib/System/Object.cs" \\
  && ok "src/zerolib/System/Object.cs" \\
  || miss "missing critical file: src/zerolib/System/Object.cs"
test -f "src/zerolib/Internal/Startup.Windows.cs" \\
  && ok "src/zerolib/Internal/Startup.Windows.cs" \\
  || miss "missing critical file: src/zerolib/Internal/Startup.Windows.cs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 208 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~178d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/bflattened/bflat"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

bflat is an ahead-of-time (AOT) C# cross-compiler that merges Roslyn (the official C# compiler) with NativeAOT to produce small, self-contained native executables and shared libraries for Windows, Linux (glibc/musl/bionic), and UEFI platforms—without requiring .NET, MSBuild, or NuGet. It ships as a single binary that emits x64/arm64 machine code directly, combining modern C# language features with the CoreCLR garbage collector and RyuJIT code generator. Monorepo structure: src/bflat/ contains the command-line entry point (Program.cs, BuildCommand.cs) and compilation orchestration (BflatTypeSystemContext.cs, ConfigurablePInvokePolicy.cs); src/zerolib/ provides the minimal standard library with platform-specific startup shims (Startup.Windows.cs, Startup.Unix.cs, Startup.Efi.cs); samples/ holds runnable demonstrations (HelloWorld, Snake, Sokol bindings) and src/debloat/ is a utility for binary shrinking. The bflat.Tests project validates compilation and output correctness.

C# developers who want Go-like tooling simplicity (single bflat build file.cs command producing native binaries) without the .NET ecosystem overhead; systems programmers targeting embedded/UEFI platforms via the minimal --stdlib:zero mode; teams building cross-platform CLI tools and libraries who need predictable, small binary size and no runtime dependencies.

Actively developed and production-capable: the project supports multiple target platforms (Linux glibc/arm64, Windows, UEFI, Android), ships official releases via GitHub and winget, includes CI/CD workflows (.github/workflows/cicd.yml), and has a test suite (src/bflat.Tests/). However, it remains a smaller ecosystem than .NET proper and relies on a companion fork (bflattened/runtime) for runtime/compiler internals, indicating ongoing evolution rather than 1.0 stability.

Single-repository risk: core compiler logic depends on bflattened/runtime (a fork of dotnet/runtime) maintained separately, creating a two-repo dependency chain that could diverge or lag upstream. Limited public issue visibility in provided file list makes backlog assessment difficult. Musl-based Linux support is explicitly 'in the works,' signaling platform gaps. The toolchain's reliance on Roslyn and NativeAOT means breaking changes in those .NET components could require rework, and the maintainer surface area appears small.

Visible activity includes multi-platform testing via .github/workflows/cicd.yml, recent sample additions (Sokol graphics bindings, Snake game), and ongoing refinement of the minimal runtime layer (Internal/Stubs.cs for platform-specific glue). The repo structure and sample breadth suggest active feature development, though specific current sprint details are not visible in the file listing.

Clone the repo, navigate to src/, and build the compiler: git clone https://github.com/bflattened/bflat.git && cd bflat && dotnet build src/bflat/bflat.csproj (requires .NET SDK to bootstrap). Once built, test with a sample: ./bflat build samples/HelloWorld/hello.cs && ./hello. See BUILDING.md for detailed instructions. Pre-built releases are available at https://github.com/bflattened/bflat/releases.

Daily commands: Build the compiler: dotnet build src/bflat/bflat.csproj -c Release. Then use it: ./bin/Release/bflat build <file.cs> (Unix/Linux) or bin\Release\bflat.exe build <file.cs> (Windows). For samples: bflat build samples/HelloWorld/hello.cs && ./hello. Cross-compile example: bflat build hello.cs --os:windows --arch:x64 from Linux to produce Windows x64 binaries.

• src/bflat/Program.cs — Entry point for the bflat compiler toolchain; every contributor must understand the command dispatch logic and overall compilation flow.
• src/bflat/BuildCommand.cs — Core compilation orchestration that bridges Roslyn and NativeAOT; essential for understanding how C# source becomes native executables.
• src/bflat/BflatTypeSystemContext.cs — Type system configuration that integrates Roslyn's semantic analysis with NativeAOT's code generation; critical for cross-compilation logic.
• src/zerolib/System/Object.cs — Core runtime object definition and GC integration; foundational for the minimal standard library that ships with bflat binaries.
• src/zerolib/Internal/Startup.Windows.cs — Platform-specific startup sequence for Windows; demonstrates bflat's multi-OS runtime initialization strategy.
• src/bflat/ConfigurablePInvokePolicy.cs — P/Invoke interop configuration; critical for understanding how bflat manages FFI and native library linking.
• src/bflat.Tests/BflatCompilation.cs — Test harness for compilation pipeline; shows how the toolchain is validated end-to-end.

Add a new standard library type

1. Create a new public type (e.g., DateTime, Guid) in src/zerolib/System/ with required runtime methods and GC-friendly allocation (src/zerolib/System/YourType.cs)
2. If the type requires compiler-injected helpers (constructors, finalizers), add stubs in src/zerolib/Internal/Runtime/CompilerHelpers/InteropHelpers.cs (src/zerolib/Internal/Runtime/CompilerHelpers/InteropHelpers.cs)
3. Add reflection metadata attributes to src/zerolib/System/Reflection/ReflectionAttributes.cs if the type needs runtime type discovery (src/zerolib/System/Reflection/ReflectionAttributes.cs)
4. Update src/zerolib/README.md to document what .NET types are supported and any behavioral differences (src/zerolib/README.md)

Add support for a new target platform (OS/architecture pair)

1. Create platform-specific startup file src/zerolib/Internal/Startup.YourOS.cs with entry point and initialization logic (src/zerolib/Internal/Startup.YourOS.cs)
2. Implement platform console I/O in src/zerolib/System/Console.YourOS.cs using native APIs (src/zerolib/System/Console.YourOS.cs)
3. Implement platform threading in src/zerolib/System/Thread.YourOS.cs if concurrency is supported (src/zerolib/System/Thread.YourOS.cs)
4. Add architecture and instruction set detection to src/bflat/InstructionSetHelpers.cs for the new platform (src/bflat/InstructionSetHelpers.cs)
5. Update src/bflat/CommonOptions.cs to recognize the new --os:yourOS flag and validate architecture pairs (src/bflat/CommonOptions.cs)

Add a new P/Invoke binding to an external native library

1. Create a C# wrapper class in src/zerolib/System/Runtime/InteropServices/ with DllImport declarations for C functions (src/zerolib/System/Runtime/InteropServices/YourLibraryBinding.cs)
2. Define struct marshaling rules (StructLayout, CharSet, etc.) on your types using InteropAttributes.cs (src/zerolib/System/Reflection/ReflectionAttributes.cs)
3. Configure linking in src/bflat/ConfigurablePInvokePolicy.cs to specify how the native library is resolved and loaded (src/bflat/ConfigurablePInvokePolicy.cs)
4. Create a sample in samples/ folder demonstrating the binding (e.g., samples/MyLibrary/binding.cs) (samples/YourLibrary/binding.cs)

Add a new compiler optimization or code generation pass

1. Implement the optimization logic in src/bflat/BuildCommand.cs within the Roslyn AST or IL pipeline before NativeAOT codegen (src/bflat/BuildCommand.cs)
2. If the optimization requires type system awareness, extend src/bflat/BflatTypeSystemContext.cs with new analysis methods (src/bflat/BflatTypeSystemContext.cs)
3. Add corresponding unit tests in src/bflat.Tests/ to verify correctness across Windows, Linux, and UEFI targets (src/bflat.Tests/UnitTest1.cs)

bflattened/runtime dependency: you cannot build bflat without pre-built compiler/runtime binaries from https://github.com/bflattened/runtime; the source alone is insufficient. BUILDING.md likely details this. Platform-specific behavior in src/zerolib/ means minimal-stdlib binaries are not portable across OS families. Roslyn version pinning: the version of Roslyn used must match the expected semantic model; version mismatch will cause silent code generation bugs. No explicit NuGet.config visible, so feed resolution may depend on global dotnet configuration. Instruction set detection (InstructionSetHelpers.cs) may silently fall back to baseline CPU features if your host runtime doesn't expose advanced ISA flags—important for binary portability expectations.

• Ahead-of-Time (AOT) Compilation — bflat's entire value proposition depends on AOT: pre-compiling C# to native machine code at build time rather than JIT-compiling at runtime, enabling small standalone binaries and predictable startup.
• Cross-compilation — bflat can target Windows, Linux, and UEFI from any host OS (Windows→Linux, Linux→Windows) via separate target platform flags (--os, --arch); understanding target vs. host architecture is essential for correct builds.
• P/Invoke (Platform Invoke) and FFI (Foreign Function Interface) — bflat's ConfigurablePInvokePolicy.cs gatekeeper controls how C# code calls native OS functions; mishandling this is a vector for memory unsafety and crashes, especially in minimal-stdlib mode.
• Roslyn and Semantic Analysis — BflatTypeSystemContext bridges Roslyn's syntax/symbol understanding to the NativeAOT runtime; understanding how Roslyn's SyntaxTree and SemanticModel work is key to debugging compilation errors or adding new language features.
• Garbage Collection (GC) and Memory Management — bflat uses CoreCLR's GC (or a minimal manual stub in --stdlib:zero mode); understanding pause times, heap layout, and GC barriers is critical for performance tuning and avoiding latency spikes in AOT binaries.
• IL (Intermediate Language) and Code Generation — bflat takes Roslyn's IL output and feeds it to NativeAOT's RyuJIT code generator; understanding IL opcodes and the IL→native translation pipeline helps diagnose unexpected binary behavior or performance issues.
• Minimal Standard Library and Zero-Cost Abstraction — bflat's --stdlib:zero mode (src/zerolib/) strips most .NET runtime features to minimize binary size; this requires understanding what can and cannot be used, and how platform startup differs between DotNet and Zero modes.

• dotnet/runtime — Upstream source for CoreCLR GC, RyuJIT, and the runtime libraries that bflattened/runtime forks and adapts for bflat's AOT needs.
• dotnet/roslyn — The C# compiler frontend that bflat integrates; provides parsing, semantic analysis, and IL generation before NativeAOT codegen.
• bflattened/runtime — Companion repo: a maintained fork of dotnet/runtime with bflat-specific patches for AOT compiler internals, P/Invoke, and minimal stdlib support.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for ConfigurablePInvokePolicy.cs

The src/bflat/ConfigurablePInvokePolicy.cs file exists but there are minimal tests in src/bflat.Tests/UnitTest1.cs. P/Invoke policies are critical for cross-platform native interop correctness. Adding targeted tests for different platform scenarios (Windows/Unix/Efi) and edge cases would prevent regressions and improve maintainability.

• [ ] Create src/bflat.Tests/ConfigurablePInvokePolicyTests.cs
• [ ] Add test cases for platform-specific policy selection (Windows, Linux/Unix, EFI)
• [ ] Add test cases for invalid/missing P/Invoke configurations
• [ ] Add test cases for policy application across different instruction sets
• [ ] Update src/bflat.Tests/bflat.Tests.csproj if needed to include new test file

Add integration tests for zerolib platform-specific implementations

The src/zerolib/ directory contains platform-specific implementations (Startup.Windows.cs, Startup.Unix.cs, Startup.Efi.cs, Console..cs, Environment..cs) but there's no evidence of integration tests validating these platform-specific code paths work correctly. This is critical for a cross-platform tool.

• [ ] Create src/bflat.Tests/ZerolibPlatformIntegrationTests.cs
• [ ] Add tests that compile and run Hello World samples on each supported platform (or mock platform detection)
• [ ] Add tests for Console I/O on Windows, Unix, and EFI platforms
• [ ] Add tests for Environment variable access across platforms
• [ ] Document expected test results in BUILDING.md for platform-specific testing

Expand samples with platform-specific compilation examples and add sample build tests

The samples/ directory has good examples (HelloWorld, DynamicLibrary, Snake, Sokol) but lacks documentation and validation that they compile successfully on different platforms. The README.md snippet shows cross-compilation to Windows, but there are no samples demonstrating EFI or arm64 targeting, and no automated tests ensuring samples remain buildable.

• [ ] Add samples/CrossPlatformBuild/README.md documenting compilation for Windows, Linux x64, Linux arm64, and EFI targets
• [ ] Add samples/EFIHelloWorld/ demonstrating EFI-specific startup code using src/zerolib/Internal/Startup.Efi.cs
• [ ] Create src/bflat.Tests/SampleCompilationTests.cs that programmatically builds all samples and validates output
• [ ] Update .github/workflows/cicd.yml to run sample compilation tests on each CI run
• [ ] Document any platform-specific build requirements in each sample's README.md

• Add unit tests for src/bflat/InstructionSetHelpers.cs: the file detects CPU features but has no visible test coverage in src/bflat.Tests/—write tests validating x86-64 ISA detection (AVX, SSE, BMI, etc.) on various simulated CPU strings.
• Document the zerolib API surface: src/zerolib/ is a minimal stdlib with no formal API docs; create a markdown guide in samples/ or zerolib/ listing what types and methods are available, what's missing vs. DotNet stdlib, and when --stdlib:zero is safe to use.
• Add a dynamic-linking sample: samples/DynamicLibrary/ exists but is minimal; extend it with a more complex use case (e.g., a plugin loader that calls C# functions from native code), and add integration tests in src/bflat.Tests/ validating two-way FFI correctness.

The bflat codebase demonstrates a reasonable security posture for a compiler/tooling project. No critical vulnerabilities were identified from the static file structure analysis. The main concerns are medium-severity risks related to P/Invoke security and potential input validation in compiler commands. The codebase appears to follow good practices with clear separation of concerns (build, compilation, runtime). However, without access to actual code implementations, detailed security review of interop helpers, input validation routines, and IL generation logic is recommended. No obvious hardcoded credentials or secrets were detected in file names or visible structure. No Docker or infrastructure misconfiguration issues are apparent from the provided information.

• Medium · Potential P/Invoke Security Risk — src/bflat/ConfigurablePInvokePolicy.cs. The codebase contains ConfigurablePInvokePolicy.cs which handles P/Invoke invocations. P/Invoke calls to unmanaged code can be a security risk if not properly validated, especially when dealing with untrusted input or dynamically constructed library paths. Fix: Ensure all P/Invoke declarations use explicit library names rather than dynamic construction. Validate all parameters passed to P/Invoke calls. Consider implementing a whitelist of allowed P/Invoke targets.
• Medium · Limited Input Validation in Compiler Tooling — src/bflat/BuildCommand.cs, src/bflat/ILBuildCommand.cs. The BuildCommand.cs and ILBuildCommand.cs files handle user input for compilation. Without visible input validation, there's a risk of command injection or path traversal vulnerabilities when processing file paths or compilation options. Fix: Implement strict input validation for all command-line arguments and file paths. Use path canonicalization to prevent directory traversal attacks. Validate file extensions and paths against a whitelist.
• Low · Interop Helpers Security Considerations — src/zerolib/Internal/Runtime/CompilerHelpers/InteropHelpers.cs. The InteropHelpers.cs file in zerolib provides runtime interop functionality. Interop code that bridges managed and unmanaged code requires careful security review to prevent buffer overflows, format string vulnerabilities, or information disclosure. Fix: Review all interop marshaling code for unsafe patterns. Use safe marshaling practices. Validate buffer sizes and string lengths. Implement bounds checking for all interop calls.
• Low · Dynamic IL Generation Risks — src/bflat/ILBuildCommand.cs. The ILBuildCommand.cs handles IL (Intermediate Language) build operations. Dynamic IL generation or modification could potentially be exploited if input is not properly validated. Fix: Ensure IL generation only accepts sanitized input. Validate all IL instructions and metadata before generation. Consider restricting IL generation capabilities to trusted sources only.
• Low · Missing FUNDING Metadata Security — .github/FUNDING.yml. The .github/FUNDING.yml file is present but content is not visible. Ensure this file doesn't contain sensitive information like API keys or credentials. Fix: Audit FUNDING.yml to ensure it contains only public information (sponsorship links, etc.). Never commit credentials or API keys in any configuration file.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.