From ca9195588b22df4b2182e34bfc7a73c024c7bb4a Mon Sep 17 00:00:00 2001 From: alethkit Date: Wed, 13 May 2026 22:24:08 +0100 Subject: [PATCH] Add agent guidance and CBE docs scaffold --- AGENTS.md | 12 ++++++++++++ docs/architecture.md | 11 +++++++++++ docs/roadmap.md | 8 ++++++++ 3 files changed, 31 insertions(+) create mode 100644 AGENTS.md create mode 100644 docs/architecture.md create mode 100644 docs/roadmap.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..85fbbcd --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,12 @@ +# CBE Agent Instructions + +- CBE is derived from QBE. +- The project goal is categorical/proof-artifact infrastructure, not QBE's original minimal-backend goal. +- Preserve inherited QBE behavior unless a task explicitly says otherwise. +- Keep `master` as upstream/QBE baseline. +- Do CBE work on `cbe`; in Codex Cloud, the checked-out task branch may be called `work`, and that is acceptable. +- Prefer small, reviewable commits. +- Every behavior-changing patch must include either a test or a clear manual validation command. +- Do not introduce external dependencies without justification. +- Keep C code style close to existing QBE style unless a new subsystem clearly needs a different style. +- New semantic/provenance code should be isolated under clearly named files rather than tangled into backend code. diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..b68a0a6 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,11 @@ +# CBE Architecture (Planned) + +Intended transformation and artifact pipeline: + +QBE IL +→ parsed QBE AST / internal structures +→ block-argument SSA normalization +→ olog-shaped artifact graph +→ derived facts +→ proof obligations +→ provenance / invalidation diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000..035ce84 --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,8 @@ +# CBE Roadmap + +- M0: preserve baseline build +- M1: machine-readable IR dump +- M2: phi-to-block-argument normalization +- M3: olog JSON export +- M4: structural proof obligations +- M5: dependency provenance and invalidation