Create roadmap and README documentation

README.adoc

@@ -1,6 +1,7 @@
 = fireflag
 Jonathan D.A. Jewell <jonathan.jewell@gmail.com>
 :toc: macro
+:toclevels: 3
 :icons: font
 :source-highlighter: rouge
 :experimental:
@@ -9,7 +10,186 @@ Jonathan D.A. Jewell <jonathan.jewell@gmail.com>
 :url-bitbucket: https://bitbucket.org/hyperpolymath/fireflag
 :url-codeberg: https://codeberg.org/hyperpolymath/fireflag
 
-Feature flag management with fire-and-forget semantics
+**Feature flag management with fire-and-forget semantics**
 
 image:https://img.shields.io/badge/RSR-Certified-gold[RSR Certified,link=https://github.com/hyperpolymath/rhodium-standard-repositories]
-image:https://img.shields.io/badge/License-AGPL%20v3-blue[License]
+image:https://img.shields.io/badge/License-MIT%20OR%20AGPL--3.0-blue[License]
+image:https://img.shields.io/badge/Status-Infrastructure%20Ready-yellow[Status]
+
+toc::[]
+
+== Overview
+
+fireflag is a feature flag management system designed around **fire-and-forget semantics** - set your flags and let the system handle propagation, caching, and consistency without manual intervention.
+
+=== Current Project State
+
+[IMPORTANT]
+====
+**Infrastructure Ready - Implementation Pending**
+
+This repository contains comprehensive CI/CD infrastructure, policy enforcement, and multi-forge distribution. The actual feature flag implementation is the next phase of development. See link:ROADMAP.adoc[ROADMAP.adoc] for planned work.
+====
+
+== Vision
+
+fireflag aims to provide:
+
+* **Fire-and-Forget Flag Management** - Configure once, propagate automatically
+* **Type-Safe SDK** - Built with ReScript for compile-time guarantees
+* **Edge-Ready** - Designed for distributed, low-latency evaluation
+* **Self-Hostable** - Full control over your feature flag infrastructure
+* **FOSS-First** - No vendor lock-in, dual-licensed MIT/AGPL-3.0
+
+== Repository Infrastructure
+
+The repository is production-ready with comprehensive infrastructure:
+
+=== CI/CD Workflows (12 Active)
+
+[cols="1,2",options="header"]
+|===
+|Workflow |Purpose
+
+|`rsr-antipattern.yml`
+|Enforces language policy (blocks TypeScript, Go, non-SaltStack Python)
+
+|`npm-bun-blocker.yml`
+|Blocks npm/bun artifacts in favor of Deno
+
+|`guix-nix-policy.yml`
+|Enforces Guix (primary) / Nix (fallback) package management
+
+|`security-policy.yml`
+|Blocks weak crypto, HTTP URLs, hardcoded secrets
+
+|`wellknown-enforcement.yml`
+|RFC 9116 security.txt validation
+
+|`workflow-linter.yml`
+|Validates SPDX headers, SHA-pinned actions, permissions
+
+|`instant-sync.yml`
+|Triggers forge propagation on push/release
+
+|`mirror.yml`
+|Syncs to GitLab and Bitbucket mirrors
+
+|`quality.yml`
+|File permissions, secrets scanning, TODO tracking, EditorConfig
+
+|`jekyll-gh-pages.yml`
+|Documentation site deployment
+
+|`codeql.yml`
+|Security analysis (activates with source code)
+
+|`scorecard.yml`
+|OSSF security scorecard
+|===
+
+=== Multi-Forge Distribution
+
+fireflag is mirrored across multiple forges for resilience:
+
+[horizontal]
+GitHub (Primary):: {url-github}
+GitLab:: {url-gitlab}
+Bitbucket:: {url-bitbucket}
+Codeberg:: {url-codeberg}
+
+Automatic synchronization keeps all mirrors current via `instant-sync.yml`.
+
+== Technology Stack
+
+fireflag follows the Hyperpolymath Language Policy:
+
+=== Approved Stack
+
+[cols="1,2",options="header"]
+|===
+|Technology |Use Case
+
+|**ReScript**
+|Primary application code (type-safe, compiles to JS)
+
+|**Rust**
+|Performance-critical components, CLI tools, WASM
+
+|**Deno**
+|Runtime and package management (replaces Node/npm)
+
+|**Gleam**
+|Backend services (BEAM or JS target)
+
+|**Tauri 2.0+ / Dioxus**
+|Mobile applications (Rust-first approach)
+
+|**Bash/POSIX**
+|Build scripts and automation (minimal)
+|===
+
+=== Explicitly Banned
+
+TypeScript, Node.js, npm, Bun, Go, general Python, Java, Kotlin, Swift, React Native, Flutter
+
+See link:.claude/CLAUDE.md[.claude/CLAUDE.md] for full language policy.
+
+== Development
+
+=== Prerequisites
+
+* https://deno.land/[Deno] (runtime)
+* https://github.com/casey/just[just] (task runner)
+* https://guix.gnu.org/[GNU Guix] or https://nixos.org/[Nix] (package management)
+
+=== Task Runner
+
+[source,bash]
+----
+# List available tasks
+just
+
+# Build (when implemented)
+just build
+
+# Test (when implemented)
+just test
+
+# Format code
+just fmt
+
+# Lint code
+just lint
+----
+
+== License
+
+Dual-licensed under your choice of:
+
+* **MIT License** - Maximum flexibility for most uses
+* **AGPL-3.0-or-later** - Copyleft protection for network services
+
+Additionally encourages (non-binding) adherence to https://github.com/hyperpolymath/palimpsest-license[Palimpsest License] principles around consent-based digital interaction.
+
+See link:LICENSE.txt[LICENSE.txt] for full terms.
+
+== Contributing
+
+Contributions welcome! Please ensure:
+
+* Code follows the approved technology stack
+* All CI checks pass
+* SPDX license headers on new files
+* SHA-pinned dependencies
+
+== Citation
+
+See link:docs/CITATIONS.adoc[docs/CITATIONS.adoc] for citation formats (BibTeX, APA, MLA, Harvard, OSCOLA).
+
+== Links
+
+* link:ROADMAP.adoc[Development Roadmap]
+* link:docs/CITATIONS.adoc[Citation Guide]
+* link:.claude/CLAUDE.md[Language Policy]
+* https://github.com/hyperpolymath/rhodium-standard-repositories[RSR Framework]

ROADMAP.adoc

@@ -0,0 +1,179 @@
+= fireflag Roadmap
+:toc: macro
+:toclevels: 2
+:icons: font
+
+Development roadmap for fireflag - feature flag management with fire-and-forget semantics.
+
+toc::[]
+
+== Current Status
+
+[cols="1,3",options="header"]
+|===
+|Component |Status
+
+|**Repository Infrastructure**
+|Complete - CI/CD, multi-forge mirroring, policy enforcement
+
+|**Language Policy**
+|Complete - ReScript/Rust/Deno stack defined and enforced
+
+|**Core Implementation**
+|Not Started - Pending
+
+|**SDK**
+|Not Started - Pending
+
+|**Documentation**
+|Partial - README and ROADMAP complete, API docs pending
+|===
+
+== Phase 1: Core Library
+
+=== 1.1 Data Model (ReScript)
+
+* [ ] Flag type definitions
+** Boolean flags
+** String/enum variants
+** Percentage rollouts
+** User segment targeting
+* [ ] Targeting rules schema
+* [ ] Evaluation context types
+* [ ] Flag state serialization
+
+=== 1.2 Evaluation Engine (Rust/WASM)
+
+* [ ] High-performance flag evaluator
+* [ ] Targeting rule matcher
+* [ ] Percentage bucketing (deterministic hashing)
+* [ ] WASM compilation for edge deployment
+* [ ] ReScript bindings
+
+=== 1.3 Storage Adapters
+
+* [ ] In-memory store (default)
+* [ ] File-based persistence (JSON/TOML)
+* [ ] SQLite adapter
+* [ ] Redis adapter (optional)
+
+== Phase 2: Fire-and-Forget Runtime
+
+=== 2.1 Background Sync
+
+* [ ] Change detection and propagation
+* [ ] Conflict resolution strategy
+* [ ] Retry with exponential backoff
+* [ ] Offline queue and replay
+
+=== 2.2 Caching Layer
+
+* [ ] Multi-tier cache (memory -> disk -> remote)
+* [ ] TTL and invalidation
+* [ ] Stale-while-revalidate semantics
+* [ ] Cache warming on startup
+
+=== 2.3 Event System
+
+* [ ] Flag change events
+* [ ] Evaluation events (for analytics)
+* [ ] Audit logging
+* [ ] Webhook dispatch
+
+== Phase 3: SDK & Integrations
+
+=== 3.1 Server SDK (Gleam)
+
+* [ ] BEAM/Erlang runtime integration
+* [ ] Process-based flag caching
+* [ ] Hot flag updates without restart
+* [ ] Telemetry integration
+
+=== 3.2 Client SDK (ReScript)
+
+* [ ] Browser runtime
+* [ ] React/Dioxus hooks
+* [ ] Local evaluation mode
+* [ ] Streaming updates (SSE)
+
+=== 3.3 CLI (Rust)
+
+* [ ] `fireflag init` - Project setup
+* [ ] `fireflag set` - Set flag values
+* [ ] `fireflag get` - Query flag state
+* [ ] `fireflag sync` - Force synchronization
+* [ ] `fireflag export/import` - Bulk operations
+
+== Phase 4: Management Interface
+
+=== 4.1 Admin API (Gleam)
+
+* [ ] REST API for flag management
+* [ ] GraphQL API (optional)
+* [ ] Authentication/authorization
+* [ ] Multi-environment support
+
+=== 4.2 Web Dashboard (ReScript + Tauri)
+
+* [ ] Flag listing and search
+* [ ] Flag editor with validation
+* [ ] Targeting rule builder
+* [ ] Audit log viewer
+* [ ] Environment switcher
+
+== Phase 5: Advanced Features
+
+=== 5.1 Experimentation
+
+* [ ] A/B testing framework
+* [ ] Metric collection
+* [ ] Statistical analysis
+* [ ] Experiment scheduling
+
+=== 5.2 Governance
+
+* [ ] Change approval workflows
+* [ ] Scheduled flag changes
+* [ ] Flag lifecycle management
+* [ ] Stale flag detection
+
+=== 5.3 Observability
+
+* [ ] OpenTelemetry integration
+* [ ] Prometheus metrics
+* [ ] Distributed tracing
+* [ ] Performance dashboards
+
+== Infrastructure Complete
+
+The following infrastructure is already in place:
+
+=== CI/CD Workflows
+
+* [x] Language policy enforcement (TypeScript, Go, npm blocked)
+* [x] Security policy (no weak crypto, HTTPS only, no secrets)
+* [x] Multi-forge mirroring (GitHub, GitLab, Bitbucket, Codeberg)
+* [x] Instant sync on push/release
+* [x] OSSF Scorecard integration
+* [x] CodeQL ready (activates with source code)
+* [x] EditorConfig compliance
+* [x] SPDX header validation
+* [x] SHA-pinned dependencies enforcement
+
+=== Repository Standards
+
+* [x] Dual MIT/AGPL-3.0 licensing
+* [x] RSR (Rhodium Standard Repository) certification
+* [x] Citation documentation (BibTeX, APA, MLA, Harvard, OSCOLA)
+* [x] Development task runner (justfile)
+* [x] Palimpsest License principles (non-binding overlay)
+
+== Contributing
+
+Contributions to any phase are welcome. Priority areas:
+
+1. **Phase 1.1** - Data model design and ReScript types
+2. **Phase 1.2** - Rust evaluation engine architecture
+3. **Phase 2.1** - Fire-and-forget sync protocol design
+
+See link:README.adoc[README.adoc] for development setup and contribution guidelines.