From 75e5723e308dc32f0a1ec16d68a7261a9d2b8a46 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 08:09:06 +0100 Subject: [PATCH] refactor: migrate repository documentation from Markdown to AsciiDoc --- ABI-FFI-README.md => ABI-FFI-README.adoc | 240 ++++++++------ ARCHITECTURE.adoc | 48 +++ ARCHITECTURE.md | 47 --- CHANGELOG.adoc | 168 +++++----- CHANGELOG.md | 71 ---- CODE_OF_CONDUCT.adoc | 215 ++++++++++++ CODE_OF_CONDUCT.md | 218 ------------ CONTRIBUTING.adoc | 109 ++++++ CONTRIBUTING.md | 116 ------- DEVELOPMENT.adoc | 308 +++++++++++++++++ DEVELOPMENT.md | 305 ----------------- GOVERNANCE.adoc | 60 ++++ GOVERNANCE.md | 60 ---- LICENSING.adoc | 90 +++++ LICENSING.md | 83 ----- MAINTAINERS.adoc | 201 ++++++++++-- MAINTAINERS.md | 221 ------------- PROJECT_SUMMARY.adoc | 362 ++++++++++++++++++++ PROJECT_SUMMARY.md | 401 ----------------------- PROOF-NEEDS.adoc | 12 + PROOF-NEEDS.md | 10 - QUICKSTART.adoc | 170 ++++++++++ QUICKSTART.md | 174 ---------- RSR_ACHIEVEMENT.adoc | 328 ++++++++++++++++++ RSR_ACHIEVEMENT.md | 292 ----------------- RSR_COMPLIANCE_AUDIT.adoc | 157 +++++++++ RSR_COMPLIANCE_AUDIT.md | 154 --------- SECURITY.adoc | 266 +++++++++++++++ SECURITY.md | 279 ---------------- TEST-NEEDS.adoc | 201 ++++++++++++ TEST-NEEDS.md | 216 ------------ TOPOLOGY.md => TOPOLOGY.adoc | 39 +-- docs/tech-debt-2026-05-26.adoc | 71 ++++ docs/tech-debt-2026-05-26.md | 57 ---- icons/README.adoc | 29 ++ icons/README.md | 32 -- llm-warmup-dev.adoc | 19 ++ llm-warmup-dev.md | 16 - llm-warmup-user.adoc | 19 ++ llm-warmup-user.md | 16 - 40 files changed, 2862 insertions(+), 3018 deletions(-) rename ABI-FFI-README.md => ABI-FFI-README.adoc (74%) create mode 100644 ARCHITECTURE.adoc delete mode 100644 ARCHITECTURE.md delete mode 100644 CHANGELOG.md create mode 100644 CODE_OF_CONDUCT.adoc delete mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.adoc delete mode 100644 CONTRIBUTING.md create mode 100644 DEVELOPMENT.adoc delete mode 100644 DEVELOPMENT.md create mode 100644 GOVERNANCE.adoc delete mode 100644 GOVERNANCE.md create mode 100644 LICENSING.adoc delete mode 100644 LICENSING.md delete mode 100644 MAINTAINERS.md create mode 100644 PROJECT_SUMMARY.adoc delete mode 100644 PROJECT_SUMMARY.md create mode 100644 PROOF-NEEDS.adoc delete mode 100644 PROOF-NEEDS.md create mode 100644 QUICKSTART.adoc delete mode 100644 QUICKSTART.md create mode 100644 RSR_ACHIEVEMENT.adoc delete mode 100644 RSR_ACHIEVEMENT.md create mode 100644 RSR_COMPLIANCE_AUDIT.adoc delete mode 100644 RSR_COMPLIANCE_AUDIT.md create mode 100644 SECURITY.adoc delete mode 100644 SECURITY.md create mode 100644 TEST-NEEDS.adoc delete mode 100644 TEST-NEEDS.md rename TOPOLOGY.md => TOPOLOGY.adoc (88%) create mode 100644 docs/tech-debt-2026-05-26.adoc delete mode 100644 docs/tech-debt-2026-05-26.md create mode 100644 icons/README.adoc delete mode 100644 icons/README.md create mode 100644 llm-warmup-dev.adoc delete mode 100644 llm-warmup-dev.md create mode 100644 llm-warmup-user.adoc delete mode 100644 llm-warmup-user.md diff --git a/ABI-FFI-README.md b/ABI-FFI-README.adoc similarity index 74% rename from ABI-FFI-README.md rename to ABI-FFI-README.adoc index f41a54e..04be86a 100644 --- a/ABI-FFI-README.md +++ b/ABI-FFI-README.adoc @@ -1,19 +1,22 @@ -{{~ Aditionally delete this line and fill out the template below ~}} +\{\{~ Aditionally delete this line and fill out the template below ~}} -# {{PROJECT}} ABI/FFI Documentation +== \{\{PROJECT}} ABI/FFI Documentation -## Overview +=== Overview -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI -## Architecture +=== Architecture -``` +.... ┌─────────────────────────────────────────────┐ │ ABI Definitions (Idris2) │ │ src/abi/ │ @@ -45,11 +48,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, AffineScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... {{project}}/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -77,15 +80,17 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ├── rust/ ├── affinescript/ └── julia/ -``` +.... -## Why Idris2 for ABI? +=== Why Idris2 for ABI? -### 1. **Formal Verification** +==== 1. *Formal Verification* -Idris2's dependent types allow proving properties about the ABI at compile-time: +Idris2’s dependent types allow proving properties about the ABI at +compile-time: -```idris +[source,idris] +---- -- Prove struct size is correct public export exampleStructSize : HasSize ExampleStruct 16 @@ -97,13 +102,14 @@ fieldAligned : Divides 8 (offsetOf ExampleStruct.field) -- Prove ABI is platform-compatible public export abiCompatible : Compatible (ABI 1) (ABI 2) -``` +---- -### 2. **Type Safety** +==== 2. *Type Safety* Encode invariants that C/Zig cannot express: -```idris +[source,idris] +---- -- Non-null pointer guaranteed at type level data Handle : Type where MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle @@ -111,13 +117,14 @@ data Handle : Type where -- Array with length proof data Buffer : (n : Nat) -> Type where MkBuffer : Vect n Byte -> Buffer n -``` +---- -### 3. **Platform Abstraction** +==== 3. *Platform Abstraction* Platform-specific types with compile-time selection: -```idris +[source,idris] +---- CInt : Platform -> Type CInt Linux = Bits32 CInt Windows = Bits32 @@ -125,13 +132,14 @@ CInt Windows = Bits32 CSize : Platform -> Type CSize Linux = Bits64 CSize Windows = Bits64 -``` +---- -### 4. **Safe Evolution** +==== 4. *Safe Evolution* Prove that new ABI versions are backward-compatible: -```idris +[source,idris] +---- -- Compiler enforces compatibility abiUpgrade : ABI 1 -> ABI 2 abiUpgrade old = MkABI2 { @@ -140,71 +148,78 @@ abiUpgrade old = MkABI2 { -- Can add new fields new_features = defaults } -``` +---- -## Why Zig for FFI? +=== Why Zig for FFI? -### 1. **C ABI Compatibility** +==== 1. *C ABI Compatibility* Zig exports C-compatible functions naturally: -```zig +[source,zig] +---- export fn library_function(param: i32) i32 { return param * 2; } -``` +---- -### 2. **Memory Safety** +==== 2. *Memory Safety* Compile-time safety without runtime overhead: -```zig +[source,zig] +---- // Null check enforced at compile time const handle = init() orelse return error.InitFailed; defer free(handle); -``` +---- -### 3. **Cross-Compilation** +==== 3. *Cross-Compilation* Built-in cross-compilation to any platform: -```bash +[source,bash] +---- zig build -Dtarget=x86_64-linux zig build -Dtarget=aarch64-macos zig build -Dtarget=x86_64-windows -``` +---- -### 4. **Zero Dependencies** +==== 4. *Zero Dependencies* No runtime, no libc required (unless explicitly needed): -```zig +[source,zig] +---- // Minimal binary size pub const lib = @import("std"); // Only includes what you use -``` +---- -## Building +=== Building -### Build FFI Library +==== Build FFI Library -```bash +[source,bash] +---- cd ffi/zig zig build # Build debug zig build -Doptimize=ReleaseFast # Build optimized zig build test # Run tests -``` +---- -### Generate C Header from Idris2 ABI +==== Generate C Header from Idris2 ABI -```bash +[source,bash] +---- cd src/abi idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig # Linux x86_64 @@ -215,13 +230,14 @@ zig build -Dtarget=aarch64-macos # Windows x86_64 zig build -Dtarget=x86_64-windows -``` +---- -## Usage +=== Usage -### From C +==== From C -```c +[source,c] +---- #include "{{project}}.h" int main() { @@ -237,16 +253,19 @@ int main() { {{project}}_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -l{{project}} -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import {{PROJECT}}.ABI.Foreign main : IO () @@ -259,11 +278,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "{{project}}")] extern "C" { fn {{project}}_init() -> *mut std::ffi::c_void; @@ -282,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" function init() @@ -312,27 +333,30 @@ try finally cleanup(handle) end -``` +---- -## Testing +=== Testing -### Unit Tests (Zig) +==== Unit Tests (Zig) -```bash +[source,bash] +---- cd ffi/zig zig build test -``` +---- -### Integration Tests +==== Integration Tests -```bash +[source,bash] +---- cd ffi/zig zig build test-integration -``` +---- -### ABI Verification (Idris2) +==== ABI Verification (Idris2) -```idris +[source,idris] +---- -- Compile-time verification %runElab verifyABI @@ -342,44 +366,44 @@ main = do verifyLayoutsCorrect verifyAlignmentsCorrect putStrLn "ABI verification passed" -``` +---- -## Contributing +=== Contributing When modifying the ABI/FFI: -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License MPL-2.0 -## See Also +=== See Also -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index 4cacc1e..4331977 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -1,90 +1,78 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Changelog - -All notable changes to DoubleTrack Browser will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -== [Unreleased] - -=== Added -- Initial project structure with Rust/WASM core and TypeScript shell -- Profile generation system with demographics, interests, and browsing styles -- Activity simulation engine with realistic URL and timing generation -- Browser extension with popup UI and options page -- Background service worker for automated activity simulation -- Storage management for profiles, activities, and statistics -- Configurable noise levels and privacy modes -- Schedule-aware activity generation based on profile occupation -- Activity history tracking and viewing -- Statistics dashboard showing activity metrics -- Content script for future page-level integration -- Comprehensive documentation (README, CLAUDE, DEVELOPMENT, CONTRIBUTING) -- Full test infrastructure for Rust and TypeScript -- Build pipeline with webpack and wasm-pack - -=== Features -- **Profile Generation**: Creates consistent, believable fictional personas - - Demographics: age, gender, location, occupation, education - - 20+ interest categories from technology to hobbies - - 4 browsing styles: Focused, Explorer, Researcher, Casual - - 4 activity levels: Low, Medium, High, VeryHigh - -- **Activity Simulation**: Generates realistic browsing patterns - - 7 activity types: Search, PageVisit, VideoWatch, Shopping, SocialMedia, News, Research - - Interest-correlated URL generation for major sites - - Realistic duration distributions based on activity type - - Schedule-based timing aligned with profile occupation - -- **Privacy Controls**: - - 4 privacy modes: Full, Moderate, Minimal, Disabled - - Adjustable noise level (0-100%) - - Optional schedule adherence - - Separate storage for real vs. simulated data - -- **User Interface**: - - Modern, gradient-based design - - Popup for quick status and controls - - Full options page for detailed configuration - - Activity history viewer with filtering - - Real-time statistics display - - Profile export functionality - -=== Technical -- Rust core compiled to WebAssembly for performance -- TypeScript with strict mode for type safety -- Manifest V3 for modern browser compatibility -- Alarm-based scheduling for efficient background operation -- IndexedDB via chrome.storage for data persistence -- Modular architecture for easy extension - -== [0.1.0] - 2025-11-22 - -=== Initial Release -- First working version of DoubleTrack Browser -- Experimental software for privacy exploration -- Full documentation and contribution guidelines - ---- - -== Version History - -- **0.1.0** - Initial release with core functionality -- **Unreleased** - Active development - -== Migration Guide - -No migrations needed yet. This is the initial release. - -== Deprecation Warnings - -None yet. - -== Security - -If you discover a security vulnerability, please email [security@example.com] rather than using the issue tracker. - ---- - -*For detailed changes, see the [commit history](https://github.com/yourusername/double-track-browser/commits).* +== Changelog + +All notable changes to `+double-track-browser+` will be documented in +this file. + +This file is generated from conventional commits by the +https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`+changelog-reusable.yml+`] +workflow (`+hyperpolymath/standards#206+`). Adopt the workflow in this +repo’s CI to keep this file in sync automatically — see +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+templates/cliff.toml+`] +for the canonical config. + +The format follows https://keepachangelog.com/en/1.1.0/[Keep a +Changelog]; this project aims to follow +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Added + +* feat(crg): add crg-grade and crg-badge justfile recipes +* feat: add wokelangiser accessibility+consent manifest +* feat: add stapeln.toml container definition +* feat: deploy UX Manifesto infrastructure +* feat: add CLADE.a2ml — clade taxonomy declaration +* feat: implement data poisoning engine with real tab orchestration +* feat(ci): enable Hypatia scanning + +==== Fixed + +* fix(affine): migrate record literals to #\{ } (affinescript#218) (#28) +* fix(ci): bump a2ml/k9-validate-action pins to canonical (#25) +* fix(ci): sync hypatia-scan.yml to canonical (#24) +* fix(ci): adopt canonical hypatia-scan.yml (#22) +* fix(ci): hypatia-scan workdir ($\{\{ env.HOME }} resolves empty) (#21) +* fix(ci): rsr-antipattern duplicate heredoc + setup-beam ubuntu24 (#17) +* fix(ci): repair YAML block-scalar in workflow-linter Check Permissions +step (#18) +* fix(ci): move secret-scanner Cargo.toml gate from job-level if: to +step-level (#19) +* fix(scorecard): enforce granular permissions and add fuzzing +placeholder +* fix(ci): Resolve workflow-linter self-matching and metadata issues + +==== Changed + +* refactor(rust_core): migrate rand 0.8 -> 0.9 API (44 build errors -> +0) +* refactor(rust_core): close .expect("`TODO: handle error`") +anti-pattern +* refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) + +==== Documentation + +* docs(governance): CRG v2.0 STRICT audit — C (declared) -> E (honest) +* docs: substantive CRG C annotation (EXPLAINME.adoc) +* docs: add EXPLAINME.adoc — prove-it file backing README claims +* docs: add checkpoint files for state tracking + +==== CI + +* ci: redistribute concurrency-cancel guard to read-only check workflows +(#27) +* ci: bump actions/upload-artifact SHA to current v4 (#16) +* ci(dependabot): restore cargo PR limit so security PRs flow (#15) +* ci(secret-scanner): drop duplicate –fail from trufflehog extra_args +(#14) +* ci: SHA-pin hyperpolymath validate-actions in dogfood-gate + +=== Pre-history + +Prior commits to this file’s introduction are recorded in git history +but not formally classified into Keep-a-Changelog sections. To backfill, +run `+git cliff -o CHANGELOG.md+` locally using the canonical +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+cliff.toml+`] +— this is one-shot mechanical work. + +''''' diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 9a28cf8..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,71 +0,0 @@ - - -# Changelog - -All notable changes to `double-track-browser` will be documented in this file. - -This file is generated from conventional commits by the -[`changelog-reusable.yml`](https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml) -workflow (`hyperpolymath/standards#206`). Adopt the workflow in this repo's CI to keep this file in sync automatically — see -[`templates/cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) -for the canonical config. - -The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); -this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Added - -- feat(crg): add crg-grade and crg-badge justfile recipes -- feat: add wokelangiser accessibility+consent manifest -- feat: add stapeln.toml container definition -- feat: deploy UX Manifesto infrastructure -- feat: add CLADE.a2ml — clade taxonomy declaration -- feat: implement data poisoning engine with real tab orchestration -- feat(ci): enable Hypatia scanning - -### Fixed - -- fix(affine): migrate record literals to #{ } (affinescript#218) (#28) -- fix(ci): bump a2ml/k9-validate-action pins to canonical (#25) -- fix(ci): sync hypatia-scan.yml to canonical (#24) -- fix(ci): adopt canonical hypatia-scan.yml (#22) -- fix(ci): hypatia-scan workdir (${{ env.HOME }} resolves empty) (#21) -- fix(ci): rsr-antipattern duplicate heredoc + setup-beam ubuntu24 (#17) -- fix(ci): repair YAML block-scalar in workflow-linter Check Permissions step (#18) -- fix(ci): move secret-scanner Cargo.toml gate from job-level if: to step-level (#19) -- fix(scorecard): enforce granular permissions and add fuzzing placeholder -- fix(ci): Resolve workflow-linter self-matching and metadata issues - -### Changed - -- refactor(rust_core): migrate rand 0.8 -> 0.9 API (44 build errors -> 0) -- refactor(rust_core): close .expect("TODO: handle error") anti-pattern -- refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) - -### Documentation - -- docs(governance): CRG v2.0 STRICT audit — C (declared) -> E (honest) -- docs: substantive CRG C annotation (EXPLAINME.adoc) -- docs: add EXPLAINME.adoc — prove-it file backing README claims -- docs: add checkpoint files for state tracking - -### CI - -- ci: redistribute concurrency-cancel guard to read-only check workflows (#27) -- ci: bump actions/upload-artifact SHA to current v4 (#16) -- ci(dependabot): restore cargo PR limit so security PRs flow (#15) -- ci(secret-scanner): drop duplicate --fail from trufflehog extra_args (#14) -- ci: SHA-pin hyperpolymath validate-actions in dogfood-gate - -## Pre-history - -Prior commits to this file's introduction are recorded in git history but not formally classified into Keep-a-Changelog sections. To backfill, run `git cliff -o CHANGELOG.md` locally using the canonical [`cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) — this is one-shot mechanical work. - ---- - - diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..d041ef1 --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,215 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +our community a harassment-free experience for everyone, regardless of +age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, color, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +=== Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our +mistakes, and learning from the experience +* Focusing on what is best not just for us as individuals, but for the +overall community +* *Supporting reversibility*: Encouraging experimentation and safe +failure +* *Respecting emotional safety*: Being mindful of anxiety and cognitive +load +* *Valuing diverse expertise*: Recognizing contributions from all skill +levels + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or +advances of any kind +* Trolling, insulting or derogatory comments, and personal or political +attacks +* Public or private harassment +* Publishing others’ private information, such as a physical or email +address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a +professional setting +* *Dismissing emotional concerns* as "`just feelings`" or "`being too +sensitive`" +* *Gatekeeping*: Excluding contributors based on experience level +* *Demanding unpaid labor*: Expecting maintainers to fix your issues +immediately + +=== Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our +standards of acceptable behavior and will take appropriate and fair +corrective action in response to any behavior that they deem +inappropriate, threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other +contributions that are not aligned to this Code of Conduct, and will +communicate reasons for moderation decisions when appropriate. + +=== Scope + +This Code of Conduct applies within all community spaces, and also +applies when an individual is officially representing the community in +public spaces. Examples of representing our community include using an +official email address, posting via an official social media account, or +acting as an appointed representative at an online or offline event. + +=== Tri-Perimeter Contribution Framework (TPCF) + +This project uses the *Tri-Perimeter Contribution Framework* to manage +trust and access control. Different perimeters have different behavioral +expectations: + +==== Perimeter 3: Community Sandbox (Current) + +*Access*: Open to all *Expectations*: - Follow this Code of Conduct - +Respect the review process - Accept that PRs may be rejected - +Understand maintainers have final say + +*Enforcement*: Community standards apply, violations result in removal +from Perimeter 3 and potential blocking. + +==== Perimeter 2: Trusted Contributors (Future) + +*Access*: Granted after sustained contributions *Expectations*: - All +Perimeter 3 expectations - Higher quality bar for contributions - Active +participation in discussions - Mentoring newcomers + +*Enforcement*: Higher trust means higher accountability. Violations may +result in demotion to Perimeter 3. + +==== Perimeter 1: Core Stewards (Future) + +*Access*: Invitation-only *Expectations*: - All Perimeter 2 expectations +- Project governance responsibilities - Conflict resolution - Strategic +direction + +*Enforcement*: Stewards hold themselves to the highest standard. + +=== Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may +be reported to the community leaders responsible for enforcement at: + +*Email*: conduct@example.com *Response SLA*: 72 hours + +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security +of the reporter of any incident. + +=== Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in +determining the consequences for any action they deem in violation of +this Code of Conduct: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behavior +deemed unprofessional or unwelcome in the community. + +*Consequence*: A private, written warning from community leaders, +providing clarity around the nature of the violation and an explanation +of why the behavior was inappropriate. A public apology may be +requested. + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period of +time. This includes avoiding interactions in community spaces as well as +external channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behavior. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No +public or private interaction with the people involved, including +unsolicited interaction with those enforcing the Code of Conduct, is +allowed during this period. Violating these terms may lead to a +permanent ban. + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +=== Emotional Safety + +This project prioritizes *emotional safety* alongside technical +excellence: + +==== Anxiety-Reducing Practices + +* *Reversibility*: All changes can be reverted easily +* *No Blame*: Focus on fixing problems, not finding fault +* *Ask Questions*: "`Stupid questions`" don’t exist +* *Experiment Freely*: Mistakes are learning opportunities +* *Take Breaks*: It’s okay to step away + +==== Burnout Prevention + +* *Sustainable Pace*: No crunch time culture +* *Say No*: Maintainers can decline features +* *Life Happens*: Family/health come first +* *No Guilt*: Disappearing for months is fine + +==== Communication Norms + +* *Assume Good Intent*: Start with charity +* *Request, Don’t Demand*: "`Could you…`" not "`You need to…`" +* *Praise in Public, Critique in Private*: Be generous with recognition +* *Emoji Encouraged*: 🎉 Make interactions warmer + +=== Attribution + +This Code of Conduct is adapted from the +https://www.contributor-covenant.org[Contributor Covenant], version 2.1, +available at +https://www.contributor-covenant.org/version/2/1/code_of_conduct.html. + +Community Impact Guidelines were inspired by +https://github.com/mozilla/diversity[Mozilla’s code of conduct +enforcement ladder]. + +Emotional safety sections inspired by: - +https://www.rust-lang.org/policies/code-of-conduct[Rust Code of Conduct] +- https://ethicalsource.dev/principles/[Ethical Source Principles] - +DoubleTrack’s focus on reversibility and experimentation + +For answers to common questions about this code of conduct, see the FAQ +at https://www.contributor-covenant.org/faq. Translations are available +at https://www.contributor-covenant.org/translations. + +''''' + +*Version*: 2.1 (DoubleTrack Extended) *Last Updated*: 2025-11-22 *Next +Review*: 2026-11-22 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index f8d4491..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,218 +0,0 @@ -# Code of Conduct - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in our -community a harassment-free experience for everyone, regardless of age, body -size, visible or invisible disability, ethnicity, sex characteristics, gender -identity and expression, level of experience, education, socio-economic status, -nationality, personal appearance, race, caste, color, religion, or sexual -identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, -diverse, inclusive, and healthy community. - -## Our Standards - -Examples of behavior that contributes to a positive environment for our -community include: - -* Demonstrating empathy and kindness toward other people -* Being respectful of differing opinions, viewpoints, and experiences -* Giving and gracefully accepting constructive feedback -* Accepting responsibility and apologizing to those affected by our mistakes, - and learning from the experience -* Focusing on what is best not just for us as individuals, but for the overall - community -* **Supporting reversibility**: Encouraging experimentation and safe failure -* **Respecting emotional safety**: Being mindful of anxiety and cognitive load -* **Valuing diverse expertise**: Recognizing contributions from all skill levels - -Examples of unacceptable behavior include: - -* The use of sexualized language or imagery, and sexual attention or advances of - any kind -* Trolling, insulting or derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or email address, - without their explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting -* **Dismissing emotional concerns** as "just feelings" or "being too sensitive" -* **Gatekeeping**: Excluding contributors based on experience level -* **Demanding unpaid labor**: Expecting maintainers to fix your issues immediately - -## Enforcement Responsibilities - -Community leaders are responsible for clarifying and enforcing our standards of -acceptable behavior and will take appropriate and fair corrective action in -response to any behavior that they deem inappropriate, threatening, offensive, -or harmful. - -Community leaders have the right and responsibility to remove, edit, or reject -comments, commits, code, wiki edits, issues, and other contributions that are -not aligned to this Code of Conduct, and will communicate reasons for moderation -decisions when appropriate. - -## Scope - -This Code of Conduct applies within all community spaces, and also applies when -an individual is officially representing the community in public spaces. -Examples of representing our community include using an official email address, -posting via an official social media account, or acting as an appointed -representative at an online or offline event. - -## Tri-Perimeter Contribution Framework (TPCF) - -This project uses the **Tri-Perimeter Contribution Framework** to manage trust -and access control. Different perimeters have different behavioral expectations: - -### Perimeter 3: Community Sandbox (Current) - -**Access**: Open to all -**Expectations**: -- Follow this Code of Conduct -- Respect the review process -- Accept that PRs may be rejected -- Understand maintainers have final say - -**Enforcement**: Community standards apply, violations result in removal from -Perimeter 3 and potential blocking. - -### Perimeter 2: Trusted Contributors (Future) - -**Access**: Granted after sustained contributions -**Expectations**: -- All Perimeter 3 expectations -- Higher quality bar for contributions -- Active participation in discussions -- Mentoring newcomers - -**Enforcement**: Higher trust means higher accountability. Violations may result -in demotion to Perimeter 3. - -### Perimeter 1: Core Stewards (Future) - -**Access**: Invitation-only -**Expectations**: -- All Perimeter 2 expectations -- Project governance responsibilities -- Conflict resolution -- Strategic direction - -**Enforcement**: Stewards hold themselves to the highest standard. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported to the community leaders responsible for enforcement at: - -**Email**: conduct@example.com -**Response SLA**: 72 hours - -All complaints will be reviewed and investigated promptly and fairly. - -All community leaders are obligated to respect the privacy and security of the -reporter of any incident. - -## Enforcement Guidelines - -Community leaders will follow these Community Impact Guidelines in determining -the consequences for any action they deem in violation of this Code of Conduct: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behavior deemed -unprofessional or unwelcome in the community. - -**Consequence**: A private, written warning from community leaders, providing -clarity around the nature of the violation and an explanation of why the -behavior was inappropriate. A public apology may be requested. - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of -actions. - -**Consequence**: A warning with consequences for continued behavior. No -interaction with the people involved, including unsolicited interaction with -those enforcing the Code of Conduct, for a specified period of time. This -includes avoiding interactions in community spaces as well as external channels -like social media. Violating these terms may lead to a temporary or permanent -ban. - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including -sustained inappropriate behavior. - -**Consequence**: A temporary ban from any sort of interaction or public -communication with the community for a specified period of time. No public or -private interaction with the people involved, including unsolicited interaction -with those enforcing the Code of Conduct, is allowed during this period. -Violating these terms may lead to a permanent ban. - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community -standards, including sustained inappropriate behavior, harassment of an -individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the -community. - -## Emotional Safety - -This project prioritizes **emotional safety** alongside technical excellence: - -### Anxiety-Reducing Practices - -- **Reversibility**: All changes can be reverted easily -- **No Blame**: Focus on fixing problems, not finding fault -- **Ask Questions**: "Stupid questions" don't exist -- **Experiment Freely**: Mistakes are learning opportunities -- **Take Breaks**: It's okay to step away - -### Burnout Prevention - -- **Sustainable Pace**: No crunch time culture -- **Say No**: Maintainers can decline features -- **Life Happens**: Family/health come first -- **No Guilt**: Disappearing for months is fine - -### Communication Norms - -- **Assume Good Intent**: Start with charity -- **Request, Don't Demand**: "Could you..." not "You need to..." -- **Praise in Public, Critique in Private**: Be generous with recognition -- **Emoji Encouraged**: 🎉 Make interactions warmer - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], -version 2.1, available at -[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. - -Community Impact Guidelines were inspired by -[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. - -Emotional safety sections inspired by: -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Ethical Source Principles](https://ethicalsource.dev/principles/) -- DoubleTrack's focus on reversibility and experimentation - -For answers to common questions about this code of conduct, see the FAQ at -[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at -[https://www.contributor-covenant.org/translations][translations]. - -[homepage]: https://www.contributor-covenant.org -[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html -[Mozilla CoC]: https://github.com/mozilla/diversity -[FAQ]: https://www.contributor-covenant.org/faq -[translations]: https://www.contributor-covenant.org/translations - ---- - -**Version**: 2.1 (DoubleTrack Extended) -**Last Updated**: 2025-11-22 -**Next Review**: 2026-11-22 diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..3759d7f --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,109 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/double-track-browser.git cd +double-track-browser + +== Using Guix (recommended for reproducibility) + +guix develop + +== Or using toolbox/distrobox + +toolbox create double-track-browser-dev toolbox enter +double-track-browser-dev # Install dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +double-track-browser/ ├── src/ # Source code (Perimeter 1-2) ├── lib/ # +Library code (Perimeter 1-2) ├── extensions/ # Extensions (Perimeter 2) +├── plugins/ # Plugins (Perimeter 2) ├── tools/ # Tooling (Perimeter 2) +├── docs/ # Documentation (Perimeter 3) │ ├── architecture/ # ADRs, +specs (Perimeter 2) │ └── proposals/ # RFCs (Perimeter 3) ├── examples/ +# Examples (Perimeter 3) ├── spec/ # Spec tests (Perimeter 3) ├── tests/ +# Test suite (Perimeter 2-3) ├── .well-known/ # Protocol files +(Perimeter 1-3) ├── .github/ # GitHub config (Perimeter 1) │ ├── +ISSUE_TEMPLATE/ │ └── workflows/ ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md +├── CONTRIBUTING.md # This file ├── GOVERNANCE.md ├── LICENSE ├── +MAINTAINERS.md ├── README.adoc ├── SECURITY.md ├── flake.guix # Guix +flake (Perimeter 1) └── Justfile # Task runner (Perimeter 1) + +.... + +--- + +## How to Contribute + +### Reporting Bugs + +**Before reporting**: +1. Search existing issues +2. Check if it's already fixed in `main` +3. Determine which perimeter the bug affects + +**When reporting**: + +Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: + +- Clear, descriptive title +- Environment details (OS, versions, toolchain) +- Steps to reproduce +- Expected vs actual behaviour +- Logs, screenshots, or minimal reproduction + +### Suggesting Features + +**Before suggesting**: +1. Check the [roadmap](ROADMAP.md) if available +2. Search existing issues and discussions +3. Consider which perimeter the feature belongs to + +**When suggesting**: + +Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: + +- Problem statement (what pain point does this solve?) +- Proposed solution +- Alternatives considered +- Which perimeter this affects + +### Your First Contribution + +Look for issues labelled: + +- [`good first issue`](https://github.com/hyperpolymath/double-track-browser/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/double-track-browser/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/double-track-browser/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/double-track-browser/labels/perimeter-3) — Community sandbox scope + +--- + +## Development Workflow + +### Branch Naming +.... + +docs/short-description # Documentation (P3) test/what-added # Test +additions (P3) feat/short-description # New features (P2) +fix/issue-number-description # Bug fixes (P2) refactor/what-changed # +Code improvements (P2) security/what-fixed # Security fixes (P1-2) + +.... + +### Commit Messages + +We follow [Conventional Commits](https://www.conventionalcommits.org/): +.... + +(): + +{empty}[optional body] + +{empty}[optional footer] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 2c007da..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://github.com/hyperpolymath/double-track-browser.git -cd double-track-browser - -# Using Guix (recommended for reproducibility) -guix develop - -# Or using toolbox/distrobox -toolbox create double-track-browser-dev -toolbox enter double-track-browser-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -double-track-browser/ -├── src/ # Source code (Perimeter 1-2) -├── lib/ # Library code (Perimeter 1-2) -├── extensions/ # Extensions (Perimeter 2) -├── plugins/ # Plugins (Perimeter 2) -├── tools/ # Tooling (Perimeter 2) -├── docs/ # Documentation (Perimeter 3) -│ ├── architecture/ # ADRs, specs (Perimeter 2) -│ └── proposals/ # RFCs (Perimeter 3) -├── examples/ # Examples (Perimeter 3) -├── spec/ # Spec tests (Perimeter 3) -├── tests/ # Test suite (Perimeter 2-3) -├── .well-known/ # Protocol files (Perimeter 1-3) -├── .github/ # GitHub config (Perimeter 1) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── GOVERNANCE.md -├── LICENSE -├── MAINTAINERS.md -├── README.adoc -├── SECURITY.md -├── flake.guix # Guix flake (Perimeter 1) -└── Justfile # Task runner (Perimeter 1) -``` - ---- - -## How to Contribute - -### Reporting Bugs - -**Before reporting**: -1. Search existing issues -2. Check if it's already fixed in `main` -3. Determine which perimeter the bug affects - -**When reporting**: - -Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: - -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour -- Logs, screenshots, or minimal reproduction - -### Suggesting Features - -**Before suggesting**: -1. Check the [roadmap](ROADMAP.md) if available -2. Search existing issues and discussions -3. Consider which perimeter the feature belongs to - -**When suggesting**: - -Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: - -- Problem statement (what pain point does this solve?) -- Proposed solution -- Alternatives considered -- Which perimeter this affects - -### Your First Contribution - -Look for issues labelled: - -- [`good first issue`](https://github.com/hyperpolymath/double-track-browser/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/double-track-browser/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/double-track-browser/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/double-track-browser/labels/perimeter-3) — Community sandbox scope - ---- - -## Development Workflow - -### Branch Naming -``` -docs/short-description # Documentation (P3) -test/what-added # Test additions (P3) -feat/short-description # New features (P2) -fix/issue-number-description # Bug fixes (P2) -refactor/what-changed # Code improvements (P2) -security/what-fixed # Security fixes (P1-2) -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): -``` -(): - -[optional body] - -[optional footer] diff --git a/DEVELOPMENT.adoc b/DEVELOPMENT.adoc new file mode 100644 index 0000000..bbc2f08 --- /dev/null +++ b/DEVELOPMENT.adoc @@ -0,0 +1,308 @@ +== Development Guide + +This guide covers setting up and developing DoubleTrack Browser. + +=== Prerequisites + +* *Node.js* (v18 or higher) +* *npm* or *yarn* +* *Rust* (latest stable) +* *wasm-pack* for compiling Rust to WebAssembly + +==== Installing Rust and wasm-pack + +[source,bash] +---- +# Install Rust +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + +# Install wasm-pack +curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh +---- + +=== Project Structure + +.... +double-track-browser/ +├── rust_core/ # Rust/WASM core logic +│ ├── src/ +│ │ ├── lib.rs # Main WASM bindings +│ │ ├── profile.rs # Profile generation +│ │ ├── activity.rs # Activity simulation +│ │ ├── interests.rs # URL generation +│ │ └── schedule.rs # Scheduling logic +│ └── Cargo.toml +├── src/ # TypeScript extension +│ ├── background/ # Service worker +│ ├── popup/ # Popup UI +│ ├── options/ # Options page +│ ├── content/ # Content scripts +│ ├── types/ # Type definitions +│ ├── utils/ # Utility functions +│ └── manifest.json +├── dist/ # Build output (gitignored) +├── icons/ # Extension icons +└── package.json +.... + +=== Initial Setup + +[source,bash] +---- +# 1. Clone the repository +git clone https://github.com/yourusername/double-track-browser.git +cd double-track-browser + +# 2. Install Node dependencies +npm install + +# 3. Build the Rust core +cd rust_core +wasm-pack build --target web +cd .. + +# 4. Build the extension +npm run build +---- + +=== Development Workflow + +==== Building + +[source,bash] +---- +# Full build (Rust + TypeScript) +npm run build + +# Build Rust core only +npm run build:rust + +# Build extension only (assumes Rust already built) +npm run build:extension + +# Development mode with watch +npm run dev +---- + +==== Testing + +[source,bash] +---- +# Run Rust tests +npm run test:rust + +# Run TypeScript tests +npm run test:ts + +# Run all tests +npm test + +# Type checking +npm run type-check + +# Linting +npm run lint +---- + +==== Loading the Extension + +===== Chrome/Chromium + +[arabic] +. Open `+chrome://extensions/+` +. Enable "`Developer mode`" (top right) +. Click "`Load unpacked`" +. Select the `+dist/+` directory + +===== Firefox + +[arabic] +. Open `+about:debugging#/runtime/this-firefox+` +. Click "`Load Temporary Add-on`" +. Select any file in the `+dist/+` directory (e.g., `+manifest.json+`) + +=== Development Tips + +==== Debugging + +*Background Service Worker:* - Chrome: `+chrome://extensions/+` → Click +"`service worker`" link - Firefox: `+about:debugging+` → Inspect +extension + +*Popup:* - Right-click popup → "`Inspect`" + +*Options Page:* - Open options, right-click → "`Inspect`" + +*Content Scripts:* - Use browser DevTools console on any page - Filter +console by "`DoubleTrack`" + +==== Hot Reloading + +The `+npm run dev+` command watches for file changes, but you’ll need +to: 1. Reload the extension in `+chrome://extensions/+` 2. Or use an +auto-reload extension like "`Extension Reloader`" + +==== Rust Development + +When modifying Rust code: + +[source,bash] +---- +cd rust_core + +# Check code without building +cargo check + +# Run tests +cargo test + +# Build and check wasm output +wasm-pack build --target web + +# Optimize for size (production) +wasm-pack build --target web --release +---- + +==== TypeScript Development + +TypeScript files are in `+src/+`. Key files: + +* `+background/index.ts+` - Main service worker logic +* `+utils/storage.ts+` - Data persistence +* `+utils/wasm.ts+` - Rust/WASM interface +* `+types/index.ts+` - Type definitions + +==== Working with WASM + +The Rust core is compiled to WASM and loaded by TypeScript: + +[arabic] +. Rust exports functions via `+#[wasm_bindgen]+` +. TypeScript imports via `+utils/wasm.ts+` +. Data is serialized/deserialized with `+serde-wasm-bindgen+` + +Currently using mock implementations in `+wasm.ts+` - replace with +actual WASM calls once compiled. + +=== Common Issues + +==== WASM Module Not Found + +*Problem:* Extension can’t find WASM files + +*Solution:* - Ensure `+npm run build:rust+` completed successfully - +Check `+dist/+` contains `+.wasm+` files - Verify webpack copied files +correctly + +==== Service Worker Not Updating + +*Problem:* Changes not reflected after reload + +*Solution:* - Chrome: Click "`service worker`" link to open DevTools - +Use "`Update`" button in extensions page - Clear storage: DevTools → +Application → Clear storage + +==== Type Errors + +*Problem:* TypeScript errors in editor + +*Solution:* + +[source,bash] +---- +npm run type-check +npm install # Ensure all types are installed +---- + +==== Build Failures + +*Problem:* Webpack or Rust build fails + +*Solution:* - Check Node.js version: `+node --version+` (should be v18+) +- Check Rust version: `+rustc --version+` - Clear builds: +`+npm run clean && npm run build+` - Delete `+node_modules+` and +reinstall: `+rm -rf node_modules && npm install+` + +=== Performance Optimization + +==== Rust + +* Use `+--release+` flag for production builds +* Profile with `+cargo flamegraph+` (install with +`+cargo install flamegraph+`) +* Minimize allocations in hot paths +* Use `+SmallRng+` instead of full RNG for speed + +==== TypeScript + +* Lazy load WASM module +* Debounce frequent operations +* Use `+chrome.alarms+` instead of `+setInterval+` +* Batch storage operations + +==== Extension Size + +Current optimizations: - Rust compiled with `+opt-level = "z"+` +(optimize for size) - LTO enabled for smaller binaries - Dead code +elimination via tree-shaking + +=== Architecture Decisions + +==== Why Rust + TypeScript? + +* *Rust*: Memory safety, performance, complex logic +* *TypeScript*: Browser API integration, UI, async operations +* *WASM*: Bridge between them + +==== Storage Design + +* Uses `+chrome.storage.local+` for persistence +* Profile data stored separately from activity history +* Statistics updated incrementally +* Activity history capped at 1000 entries + +==== Activity Simulation + +* Poisson distribution for realistic timing +* Profile-based URL generation +* Schedule-aware execution +* Configurable noise levels + +=== Contributing + +See `+CONTRIBUTING.md+` for contribution guidelines. + +==== Code Style + +*Rust:* - Follow Rust standard style (`+rustfmt+`) - Document public +APIs - Write tests for new features + +*TypeScript:* - Use ESLint configuration - Prefer `+async/await+` over +callbacks - Type everything (no `+any+`) + +=== Release Process + +[arabic] +. Update version in `+package.json+` and `+Cargo.toml+` +. Update `+CHANGELOG.md+` +. Run full test suite +. Build production version +. Test loaded extension thoroughly +. Create git tag +. Build distribution package +. Submit to Chrome Web Store / Firefox Add-ons + +=== Resources + +* https://developer.chrome.com/docs/extensions/mv3/[Manifest V3 +Documentation] +* https://rustwasm.github.io/docs/book/[WebAssembly Guide] +* https://rustwasm.github.io/wasm-pack/[wasm-pack Documentation] +* https://github.com/rustwasm/wasm-bindgen[Rust WebExtensions Example] + +=== Getting Help + +* Check existing issues on GitHub +* Read CLAUDE.md for AI assistant context +* Review inline code comments +* Consult browser extension documentation diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md deleted file mode 100644 index 52d374d..0000000 --- a/DEVELOPMENT.md +++ /dev/null @@ -1,305 +0,0 @@ -# Development Guide - -This guide covers setting up and developing DoubleTrack Browser. - -## Prerequisites - -- **Node.js** (v18 or higher) -- **npm** or **yarn** -- **Rust** (latest stable) -- **wasm-pack** for compiling Rust to WebAssembly - -### Installing Rust and wasm-pack - -```bash -# Install Rust -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh - -# Install wasm-pack -curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh -``` - -## Project Structure - -``` -double-track-browser/ -├── rust_core/ # Rust/WASM core logic -│ ├── src/ -│ │ ├── lib.rs # Main WASM bindings -│ │ ├── profile.rs # Profile generation -│ │ ├── activity.rs # Activity simulation -│ │ ├── interests.rs # URL generation -│ │ └── schedule.rs # Scheduling logic -│ └── Cargo.toml -├── src/ # TypeScript extension -│ ├── background/ # Service worker -│ ├── popup/ # Popup UI -│ ├── options/ # Options page -│ ├── content/ # Content scripts -│ ├── types/ # Type definitions -│ ├── utils/ # Utility functions -│ └── manifest.json -├── dist/ # Build output (gitignored) -├── icons/ # Extension icons -└── package.json -``` - -## Initial Setup - -```bash -# 1. Clone the repository -git clone https://github.com/yourusername/double-track-browser.git -cd double-track-browser - -# 2. Install Node dependencies -npm install - -# 3. Build the Rust core -cd rust_core -wasm-pack build --target web -cd .. - -# 4. Build the extension -npm run build -``` - -## Development Workflow - -### Building - -```bash -# Full build (Rust + TypeScript) -npm run build - -# Build Rust core only -npm run build:rust - -# Build extension only (assumes Rust already built) -npm run build:extension - -# Development mode with watch -npm run dev -``` - -### Testing - -```bash -# Run Rust tests -npm run test:rust - -# Run TypeScript tests -npm run test:ts - -# Run all tests -npm test - -# Type checking -npm run type-check - -# Linting -npm run lint -``` - -### Loading the Extension - -#### Chrome/Chromium - -1. Open `chrome://extensions/` -2. Enable "Developer mode" (top right) -3. Click "Load unpacked" -4. Select the `dist/` directory - -#### Firefox - -1. Open `about:debugging#/runtime/this-firefox` -2. Click "Load Temporary Add-on" -3. Select any file in the `dist/` directory (e.g., `manifest.json`) - -## Development Tips - -### Debugging - -**Background Service Worker:** -- Chrome: `chrome://extensions/` → Click "service worker" link -- Firefox: `about:debugging` → Inspect extension - -**Popup:** -- Right-click popup → "Inspect" - -**Options Page:** -- Open options, right-click → "Inspect" - -**Content Scripts:** -- Use browser DevTools console on any page -- Filter console by "DoubleTrack" - -### Hot Reloading - -The `npm run dev` command watches for file changes, but you'll need to: -1. Reload the extension in `chrome://extensions/` -2. Or use an auto-reload extension like "Extension Reloader" - -### Rust Development - -When modifying Rust code: - -```bash -cd rust_core - -# Check code without building -cargo check - -# Run tests -cargo test - -# Build and check wasm output -wasm-pack build --target web - -# Optimize for size (production) -wasm-pack build --target web --release -``` - -### TypeScript Development - -TypeScript files are in `src/`. Key files: - -- `background/index.ts` - Main service worker logic -- `utils/storage.ts` - Data persistence -- `utils/wasm.ts` - Rust/WASM interface -- `types/index.ts` - Type definitions - -### Working with WASM - -The Rust core is compiled to WASM and loaded by TypeScript: - -1. Rust exports functions via `#[wasm_bindgen]` -2. TypeScript imports via `utils/wasm.ts` -3. Data is serialized/deserialized with `serde-wasm-bindgen` - -Currently using mock implementations in `wasm.ts` - replace with actual WASM calls once compiled. - -## Common Issues - -### WASM Module Not Found - -**Problem:** Extension can't find WASM files - -**Solution:** -- Ensure `npm run build:rust` completed successfully -- Check `dist/` contains `.wasm` files -- Verify webpack copied files correctly - -### Service Worker Not Updating - -**Problem:** Changes not reflected after reload - -**Solution:** -- Chrome: Click "service worker" link to open DevTools -- Use "Update" button in extensions page -- Clear storage: DevTools → Application → Clear storage - -### Type Errors - -**Problem:** TypeScript errors in editor - -**Solution:** -```bash -npm run type-check -npm install # Ensure all types are installed -``` - -### Build Failures - -**Problem:** Webpack or Rust build fails - -**Solution:** -- Check Node.js version: `node --version` (should be v18+) -- Check Rust version: `rustc --version` -- Clear builds: `npm run clean && npm run build` -- Delete `node_modules` and reinstall: `rm -rf node_modules && npm install` - -## Performance Optimization - -### Rust - -- Use `--release` flag for production builds -- Profile with `cargo flamegraph` (install with `cargo install flamegraph`) -- Minimize allocations in hot paths -- Use `SmallRng` instead of full RNG for speed - -### TypeScript - -- Lazy load WASM module -- Debounce frequent operations -- Use `chrome.alarms` instead of `setInterval` -- Batch storage operations - -### Extension Size - -Current optimizations: -- Rust compiled with `opt-level = "z"` (optimize for size) -- LTO enabled for smaller binaries -- Dead code elimination via tree-shaking - -## Architecture Decisions - -### Why Rust + TypeScript? - -- **Rust**: Memory safety, performance, complex logic -- **TypeScript**: Browser API integration, UI, async operations -- **WASM**: Bridge between them - -### Storage Design - -- Uses `chrome.storage.local` for persistence -- Profile data stored separately from activity history -- Statistics updated incrementally -- Activity history capped at 1000 entries - -### Activity Simulation - -- Poisson distribution for realistic timing -- Profile-based URL generation -- Schedule-aware execution -- Configurable noise levels - -## Contributing - -See `CONTRIBUTING.md` for contribution guidelines. - -### Code Style - -**Rust:** -- Follow Rust standard style (`rustfmt`) -- Document public APIs -- Write tests for new features - -**TypeScript:** -- Use ESLint configuration -- Prefer `async/await` over callbacks -- Type everything (no `any`) - -## Release Process - -1. Update version in `package.json` and `Cargo.toml` -2. Update `CHANGELOG.md` -3. Run full test suite -4. Build production version -5. Test loaded extension thoroughly -6. Create git tag -7. Build distribution package -8. Submit to Chrome Web Store / Firefox Add-ons - -## Resources - -- [Manifest V3 Documentation](https://developer.chrome.com/docs/extensions/mv3/) -- [WebAssembly Guide](https://rustwasm.github.io/docs/book/) -- [wasm-pack Documentation](https://rustwasm.github.io/wasm-pack/) -- [Rust WebExtensions Example](https://github.com/rustwasm/wasm-bindgen) - -## Getting Help - -- Check existing issues on GitHub -- Read CLAUDE.md for AI assistant context -- Review inline code comments -- Consult browser extension documentation diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc new file mode 100644 index 0000000..9b836fb --- /dev/null +++ b/GOVERNANCE.adoc @@ -0,0 +1,60 @@ +== Governance + +=== Overview + +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. + +=== Roles and Responsibilities + +==== Maintainers + +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support + +==== Contributors + +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed + +=== Decision Making + +==== Minor Changes + +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates + +==== Major Changes + +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers + +==== Breaking Changes + +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide + +=== Code of Conduct + +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. + +=== Communication + +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions + +=== Licensing + +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. + +''''' + +_Last updated: 2026-07-18_ diff --git a/GOVERNANCE.md b/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/LICENSING.adoc b/LICENSING.adoc new file mode 100644 index 0000000..6896254 --- /dev/null +++ b/LICENSING.adoc @@ -0,0 +1,90 @@ +== Licensing Information + +=== Dual License + +DoubleTrack Browser is dual-licensed under: + +[arabic] +. *MIT License* (primary, for maximum compatibility) +. *Palimpsest License v0.8* (alternative, for RSR compliance) + +You may choose either license when using, modifying, or distributing +this software. + +=== Why Dual License? + +* *MIT*: Permissive, widely understood, maximum compatibility with other +projects +* *Palimpsest v0.8*: Supports reversibility principles and RSR Framework +goals + +=== License Texts + +* MIT License: See LICENSE-MIT +* Palimpsest License v0.8: See LICENSE-PALIMPSEST +* Historical GPL-3.0: See LICENSE (retained for historical purposes) + +=== How to Choose + +==== Use MIT if you want: + +* Maximum compatibility +* Simple, well-understood terms +* No additional obligations +* Commercial use without restrictions + +==== Use Palimpsest v0.8 if you want: + +* Support for reversibility principles +* Alignment with RSR Framework values +* Recognition of emotional safety in software development + +=== For Contributors + +By contributing to this project, you agree that your contributions will +be licensed under the same dual license (MIT + Palimpsest v0.8). + +=== For Users + +When using this software: 1. Choose which license you prefer (MIT or +Palimpsest v0.8) 2. Include the appropriate LICENSE file with your +distribution 3. Provide attribution as specified in your chosen license + +=== Clarifications + +*Q: Can I mix and match terms from both licenses?* A: No. Choose one +license and follow its terms entirely. + +*Q: What if I’m unsure which to use?* A: MIT is the simpler, more widely +understood option. Use MIT unless you specifically need Palimpsest v0.8. + +*Q: Can I relicense under just one license?* A: If you redistribute our +code, you must offer the same dual license. Derivative works may choose +stricter terms compatible with your chosen license. + +*Q: What about the GPL-3.0 LICENSE file?* A: That was the original +license. As of v0.1.1, the project has transitioned to MIT + Palimpsest +v0.8 dual licensing. The GPL-3.0 file is retained for historical +reference but is no longer the active license. + +=== SPDX License Identifiers + +When adding headers to source files, use: + +.... +// SPDX-License-Identifier: CC-BY-SA-4.0 +.... + +Or for individual file choice: + +.... +// SPDX-License-Identifier: CC-BY-SA-4.0 +.... + +=== Questions? + +Contact: legal@example.com + +''''' + +*Effective Date*: 2025-11-22 *Version*: 1.0 *Last Updated*: 2025-11-22 diff --git a/LICENSING.md b/LICENSING.md deleted file mode 100644 index 5cebb35..0000000 --- a/LICENSING.md +++ /dev/null @@ -1,83 +0,0 @@ -# Licensing Information - -## Dual License - -DoubleTrack Browser is dual-licensed under: - -1. **MIT License** (primary, for maximum compatibility) -2. **Palimpsest License v0.8** (alternative, for RSR compliance) - -You may choose either license when using, modifying, or distributing this software. - -## Why Dual License? - -- **MIT**: Permissive, widely understood, maximum compatibility with other projects -- **Palimpsest v0.8**: Supports reversibility principles and RSR Framework goals - -## License Texts - -- MIT License: See [LICENSE-MIT](LICENSE-MIT) -- Palimpsest License v0.8: See [LICENSE-PALIMPSEST](LICENSE-PALIMPSEST) -- Historical GPL-3.0: See [LICENSE](LICENSE) (retained for historical purposes) - -## How to Choose - -### Use MIT if you want: -- Maximum compatibility -- Simple, well-understood terms -- No additional obligations -- Commercial use without restrictions - -### Use Palimpsest v0.8 if you want: -- Support for reversibility principles -- Alignment with RSR Framework values -- Recognition of emotional safety in software development - -## For Contributors - -By contributing to this project, you agree that your contributions will be licensed under the same dual license (MIT + Palimpsest v0.8). - -## For Users - -When using this software: -1. Choose which license you prefer (MIT or Palimpsest v0.8) -2. Include the appropriate LICENSE file with your distribution -3. Provide attribution as specified in your chosen license - -## Clarifications - -**Q: Can I mix and match terms from both licenses?** -A: No. Choose one license and follow its terms entirely. - -**Q: What if I'm unsure which to use?** -A: MIT is the simpler, more widely understood option. Use MIT unless you specifically need Palimpsest v0.8. - -**Q: Can I relicense under just one license?** -A: If you redistribute our code, you must offer the same dual license. Derivative works may choose stricter terms compatible with your chosen license. - -**Q: What about the GPL-3.0 LICENSE file?** -A: That was the original license. As of v0.1.1, the project has transitioned to MIT + Palimpsest v0.8 dual licensing. The GPL-3.0 file is retained for historical reference but is no longer the active license. - -## SPDX License Identifiers - -When adding headers to source files, use: - -``` -// SPDX-License-Identifier: CC-BY-SA-4.0 -``` - -Or for individual file choice: - -``` -// SPDX-License-Identifier: CC-BY-SA-4.0 -``` - -## Questions? - -Contact: legal@example.com - ---- - -**Effective Date**: 2025-11-22 -**Version**: 1.0 -**Last Updated**: 2025-11-22 diff --git a/MAINTAINERS.adoc b/MAINTAINERS.adoc index 48d9781..f8f8ae9 100644 --- a/MAINTAINERS.adoc +++ b/MAINTAINERS.adoc @@ -1,47 +1,186 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Maintainers -:toc: preamble +== Maintainers -This document lists the maintainers of this project and their responsibilities. +This document lists the individuals responsible for the DoubleTrack +Browser project and defines the governance structure. -== Current Maintainers +=== Current Maintainers -[cols="2,3,2",options="header"] -|=== -| Name | Role | Contact +==== Core Stewards (Perimeter 1) -| Jonathan D.A. Jewell -| Lead Maintainer -| https://github.com/hyperpolymath[@hyperpolymath] +[width="100%",cols="16%,14%,19%,17%,17%,17%",options="header",] +|=== +|Name |Role |GitHub |Email |Areas |Since +|[Your Name] |Lead Maintainer |@yourusername |you@example.com |All +|2025-11 |=== -== Responsibilities +*Responsibilities*: - Final decision authority on project direction - +Security incident response - Release management - Community moderation - +TPCF perimeter management + +==== Trusted Contributors (Perimeter 2) + +_None currently - perimeter not yet activated_ + +*Path to Perimeter 2*: 1. Sustained contributions over 3+ months 2. 10+ +merged PRs of substance 3. Active participation in discussions 4. +Demonstrated understanding of project goals 5. Nomination by existing P1 +steward 6. Unanimous approval by all P1 stewards + +*Responsibilities* (when activated): - Code review privileges - Triage +issues and PRs - Mentor newcomers - Shape project roadmap + +=== Governance Model + +==== Decision-Making Process + +*Type A: Routine Decisions* (bugs, docs, refactoring) - Any maintainer +can merge after review - 24-hour minimum for review window - LGTM from +one P1 steward required + +*Type B: Feature Decisions* (new capabilities, API changes) - Discussion +in GitHub issue first - 72-hour minimum discussion period - LGTM from +majority of P1 stewards - Lead maintainer has veto power + +*Type C: Governance Decisions* (CoC, license, TPCF changes) - Public RFC +process required - 2-week minimum discussion period - Unanimous approval +by all P1 stewards - Community input strongly considered + +==== Conflict Resolution + +[arabic] +. *Direct Communication*: Parties attempt to resolve privately +. *Mediation*: Neutral P1 steward mediates if needed +. *Lead Decision*: Lead maintainer makes final call if unresolved +. *Fork Option*: Dissenting parties may fork under MIT terms + +==== Succession Planning + +*If Lead Maintainer Steps Down*: 1. 30-day notice preferred (not +required) 2. Existing P1 stewards elect new lead 3. If no P1 stewards +remain, most senior P2 contributor promoted 4. If project abandoned, MIT +license permits forking + +*Adding New Core Stewards*: - Requires unanimous approval of existing P1 +stewards - Minimum 12 months as P2 contributor - Demonstrated commitment +to project values - Invitation-only, not requested + +=== Perimeter Management + +==== Current Status: Perimeter 3 Only + +*Rationale*: Project is in initial development phase. TPCF Perimeters 1 +and 2 are designed but not yet activated. All contributors currently +operate in Perimeter 3 (Community Sandbox). + +==== Activation Criteria + +*Perimeter 2 Activation Triggers*: - Project has 50+ stars on GitHub - +10+ external contributors - 100+ merged PRs - First stable release +(v1.0.0) + +*Perimeter 1 Expansion Triggers*: - Project has 500+ stars on GitHub - +3+ sustained P2 contributors (12+ months) - Security audit completed - +Lead maintainer needs delegation + +=== Time Commitments + +==== Expected Availability + +*P1 Stewards*: - Check GitHub 2-3x per week minimum - Respond to +security issues within 48 hours - Review PRs within 1 week - Participate +in monthly sync (when P2 activated) + +*P2 Contributors* (when activated): - Check GitHub 1x per week - Review +assigned PRs within 2 weeks - Optional participation in discussions + +==== Stepping Down + +Maintainers may step down at any time by: 1. Notifying other maintainers +(private or public) 2. Opening a PR to remove themselves from this file +3. No justification required + +*Emeritus Status*: Former maintainers are honored in CONTRIBUTORS.md +(when created) and retain community respect. + +=== Contact Information + +==== Public Channels + +* *GitHub Issues*: +https://github.com/yourusername/double-track-browser/issues +* *Discussions*: +https://github.com/yourusername/double-track-browser/discussions +* *Email*: maintainers@example.com (public list) + +==== Private Channels + +* *Security*: security@example.com (see SECURITY.md) +* *Code of Conduct*: conduct@example.com (see CODE_OF_CONDUCT.md) +* *Governance*: governance@example.com (for TPCF perimeter requests) + +=== Responsibilities + +==== What Maintainers Do + +✅ *Do*: - Review and merge pull requests - Triage and respond to issues +- Maintain project infrastructure - Coordinate releases - Enforce Code +of Conduct - Protect user privacy - Foster welcoming community + +❌ *Don’t*: - Guarantee response times (best effort only) - Provide free +consulting - Owe anyone explanations for decisions - Sacrifice mental +health for the project + +==== What Contributors Should Expect + +*You Can Expect*: - Respectful, professional communication - Fair review +of contributions - Transparency in decision-making - Adherence to Code +of Conduct - Acknowledgment in release notes + +*You Should Not Expect*: - Immediate responses - Acceptance of all PRs - +Custom features on demand - Detailed justifications for every decision - +Unpaid labor from maintainers + +=== Maintainer Onboarding (Future) -Maintainers are responsible for: +When promoting to P2 or P1: -* Reviewing and merging pull requests -* Triaging issues and feature requests -* Ensuring code quality and security standards -* Managing releases and versioning -* Upholding the project's code of conduct +[arabic] +. *Access Grants*: +* GitHub team membership +* NPM publish rights (P1 only) +* Signing keys for releases (P1 only) +* Email list access +. *Knowledge Transfer*: +* Read all documentation +* Shadow current maintainer for 1 month +* Pair on 3+ PR reviews +* Learn release process +. *First Tasks*: +* Update MAINTAINERS.md (this file) +* Introduce yourself in Discussions +* Set up GPG signing key +* Review CONTRIBUTING.md -== Becoming a Maintainer +=== Recognition -Contributors who demonstrate: +Maintainers volunteer their time and expertise. The community thanks +them by: - Being respectful and patient - Following contribution +guidelines - Helping other users - Spreading the word about the project +- Sending encouraging messages - Buying them coffee ☕ (optional): +[TODO: Sponsor link] -* Consistent, high-quality contributions -* Understanding of the project's goals and standards -* Constructive participation in discussions -* Commitment to the project's long-term health +=== Amendment Process -May be invited to become maintainers at the discretion of existing maintainers. +This document is a living guide and may be updated by: 1. Opening a PR +with proposed changes 2. Discussion period of 1 week minimum 3. Approval +by majority of P1 stewards 4. Merge and announce in release notes -== Decision Making +''''' -* Routine decisions (bug fixes, minor improvements) can be made by any maintainer -* Significant changes require discussion and consensus among maintainers -* Breaking changes or major features should be discussed in issues before implementation +*Version*: 1.0 *Last Updated*: 2025-11-22 *Next Review*: 2026-05-22 (6 +months) -== Contact +''''' -For questions about project governance, open an issue or contact the maintainers listed above. +Thank you to all current and future maintainers for your stewardship! 🙏 diff --git a/MAINTAINERS.md b/MAINTAINERS.md deleted file mode 100644 index 5c9663f..0000000 --- a/MAINTAINERS.md +++ /dev/null @@ -1,221 +0,0 @@ -# Maintainers - -This document lists the individuals responsible for the DoubleTrack Browser project and defines the governance structure. - -## Current Maintainers - -### Core Stewards (Perimeter 1) - -| Name | Role | GitHub | Email | Areas | Since | -|------|------|--------|-------|-------|-------| -| [Your Name] | Lead Maintainer | @yourusername | you@example.com | All | 2025-11 | - -**Responsibilities**: -- Final decision authority on project direction -- Security incident response -- Release management -- Community moderation -- TPCF perimeter management - -### Trusted Contributors (Perimeter 2) - -*None currently - perimeter not yet activated* - -**Path to Perimeter 2**: -1. Sustained contributions over 3+ months -2. 10+ merged PRs of substance -3. Active participation in discussions -4. Demonstrated understanding of project goals -5. Nomination by existing P1 steward -6. Unanimous approval by all P1 stewards - -**Responsibilities** (when activated): -- Code review privileges -- Triage issues and PRs -- Mentor newcomers -- Shape project roadmap - -## Governance Model - -### Decision-Making Process - -**Type A: Routine Decisions** (bugs, docs, refactoring) -- Any maintainer can merge after review -- 24-hour minimum for review window -- LGTM from one P1 steward required - -**Type B: Feature Decisions** (new capabilities, API changes) -- Discussion in GitHub issue first -- 72-hour minimum discussion period -- LGTM from majority of P1 stewards -- Lead maintainer has veto power - -**Type C: Governance Decisions** (CoC, license, TPCF changes) -- Public RFC process required -- 2-week minimum discussion period -- Unanimous approval by all P1 stewards -- Community input strongly considered - -### Conflict Resolution - -1. **Direct Communication**: Parties attempt to resolve privately -2. **Mediation**: Neutral P1 steward mediates if needed -3. **Lead Decision**: Lead maintainer makes final call if unresolved -4. **Fork Option**: Dissenting parties may fork under MIT terms - -### Succession Planning - -**If Lead Maintainer Steps Down**: -1. 30-day notice preferred (not required) -2. Existing P1 stewards elect new lead -3. If no P1 stewards remain, most senior P2 contributor promoted -4. If project abandoned, MIT license permits forking - -**Adding New Core Stewards**: -- Requires unanimous approval of existing P1 stewards -- Minimum 12 months as P2 contributor -- Demonstrated commitment to project values -- Invitation-only, not requested - -## Perimeter Management - -### Current Status: Perimeter 3 Only - -**Rationale**: Project is in initial development phase. TPCF Perimeters 1 and 2 are designed but not yet activated. All contributors currently operate in Perimeter 3 (Community Sandbox). - -### Activation Criteria - -**Perimeter 2 Activation Triggers**: -- Project has 50+ stars on GitHub -- 10+ external contributors -- 100+ merged PRs -- First stable release (v1.0.0) - -**Perimeter 1 Expansion Triggers**: -- Project has 500+ stars on GitHub -- 3+ sustained P2 contributors (12+ months) -- Security audit completed -- Lead maintainer needs delegation - -## Time Commitments - -### Expected Availability - -**P1 Stewards**: -- Check GitHub 2-3x per week minimum -- Respond to security issues within 48 hours -- Review PRs within 1 week -- Participate in monthly sync (when P2 activated) - -**P2 Contributors** (when activated): -- Check GitHub 1x per week -- Review assigned PRs within 2 weeks -- Optional participation in discussions - -### Stepping Down - -Maintainers may step down at any time by: -1. Notifying other maintainers (private or public) -2. Opening a PR to remove themselves from this file -3. No justification required - -**Emeritus Status**: Former maintainers are honored in CONTRIBUTORS.md (when created) and retain community respect. - -## Contact Information - -### Public Channels - -- **GitHub Issues**: https://github.com/yourusername/double-track-browser/issues -- **Discussions**: https://github.com/yourusername/double-track-browser/discussions -- **Email**: maintainers@example.com (public list) - -### Private Channels - -- **Security**: security@example.com (see SECURITY.md) -- **Code of Conduct**: conduct@example.com (see CODE_OF_CONDUCT.md) -- **Governance**: governance@example.com (for TPCF perimeter requests) - -## Responsibilities - -### What Maintainers Do - -✅ **Do**: -- Review and merge pull requests -- Triage and respond to issues -- Maintain project infrastructure -- Coordinate releases -- Enforce Code of Conduct -- Protect user privacy -- Foster welcoming community - -❌ **Don't**: -- Guarantee response times (best effort only) -- Provide free consulting -- Owe anyone explanations for decisions -- Sacrifice mental health for the project - -### What Contributors Should Expect - -**You Can Expect**: -- Respectful, professional communication -- Fair review of contributions -- Transparency in decision-making -- Adherence to Code of Conduct -- Acknowledgment in release notes - -**You Should Not Expect**: -- Immediate responses -- Acceptance of all PRs -- Custom features on demand -- Detailed justifications for every decision -- Unpaid labor from maintainers - -## Maintainer Onboarding (Future) - -When promoting to P2 or P1: - -1. **Access Grants**: - - GitHub team membership - - NPM publish rights (P1 only) - - Signing keys for releases (P1 only) - - Email list access - -2. **Knowledge Transfer**: - - Read all documentation - - Shadow current maintainer for 1 month - - Pair on 3+ PR reviews - - Learn release process - -3. **First Tasks**: - - Update MAINTAINERS.md (this file) - - Introduce yourself in Discussions - - Set up GPG signing key - - Review CONTRIBUTING.md - -## Recognition - -Maintainers volunteer their time and expertise. The community thanks them by: -- Being respectful and patient -- Following contribution guidelines -- Helping other users -- Spreading the word about the project -- Sending encouraging messages -- Buying them coffee ☕ (optional): [TODO: Sponsor link] - -## Amendment Process - -This document is a living guide and may be updated by: -1. Opening a PR with proposed changes -2. Discussion period of 1 week minimum -3. Approval by majority of P1 stewards -4. Merge and announce in release notes - ---- - -**Version**: 1.0 -**Last Updated**: 2025-11-22 -**Next Review**: 2026-05-22 (6 months) - ---- - -Thank you to all current and future maintainers for your stewardship! 🙏 diff --git a/PROJECT_SUMMARY.adoc b/PROJECT_SUMMARY.adoc new file mode 100644 index 0000000..edea269 --- /dev/null +++ b/PROJECT_SUMMARY.adoc @@ -0,0 +1,362 @@ +== DoubleTrack Browser - Project Summary + +=== Overview + +DoubleTrack Browser is a fully-functional browser extension that +explores unconventional privacy protection through deliberate noise +generation. Instead of hiding user data, it creates believable fictional +browsing patterns to obscure real activity from tracking systems. + +*Status*: Complete, functional prototype ready for testing and further +development + +=== What Was Built + +==== Core Architecture + +===== 1. Rust/WebAssembly Core (`+rust_core/+`) + +*Files*: 6 Rust modules, 1 Cargo configuration *Lines of Code*: ~1,200 +lines + +*Modules*: - `+lib.rs+` - WASM bindings and public API (80 lines) - +`+profile.rs+` - Profile generation with demographics and interests (400 +lines) - `+activity.rs+` - Activity simulation engine (200 lines) - +`+interests.rs+` - URL and content generation (300 lines) - +`+schedule.rs+` - Time-based activity scheduling (150 lines) - +`+tests/integration_tests.rs+` - Comprehensive test suite (450 lines) + +*Features*: - Deterministic profile generation with optional seeding - 9 +occupation categories, 5 education levels - 20+ interest categories - 4 +browsing styles (Focused, Explorer, Researcher, Casual) - 4 activity +levels (Low to VeryHigh) - 7 activity types with realistic URL +generation - Schedule generation based on occupation and lifestyle - +Compiled to WebAssembly for browser integration + +===== 2. TypeScript Browser Extension (`+src/+`) + +*Files*: 15 TypeScript modules, 6 HTML pages, 6 CSS stylesheets *Lines +of Code*: ~3,500 lines + +*Structure*: + +.... +src/ +├── background/ # Service worker for activity simulation +├── popup/ # Quick-access UI +├── options/ # Full settings page +├── dashboard/ # Analytics and visualization +├── content/ # Content script for page integration +├── types/ # TypeScript type definitions +├── utils/ # Storage and WASM utilities +└── manifest.json # Extension configuration +.... + +*Components*: + +[arabic] +. *Background Service Worker* (300 lines) +* Activity simulation orchestration +* Alarm-based scheduling +* Message handling for UI communication +* Profile and statistics management +. *Popup UI* (HTML + CSS + TS: 500 lines) +* Extension enable/disable toggle +* Profile information display +* Quick statistics overview +* Noise level and schedule controls +. *Options Page* (HTML + CSS + TS: 700 lines) +* Comprehensive settings interface +* Profile generation and export +* Activity history viewer +* Privacy mode selection +* Statistics dashboard access +. *Analytics Dashboard* (HTML + CSS + TS: 1,100 lines) +* Canvas-based visualizations (no external charting libraries) +* 7-day activity timeline (bar chart) +* Activity type distribution (pie chart) +* Hourly pattern analysis (line chart) +* Interest category bars +* Weekly heatmap (GitHub-style) +* Recent activities list +* Profile insights generation +. *Utilities* (400 lines) +* `+storage.ts+` - Chrome storage API wrapper +* `+wasm.ts+` - Rust/WASM interface layer +* Type-safe data management +* Activity history trimming (1000-item limit) +. *Content Script* (50 lines) +* Page-level integration stub +* Future privacy safeguards +* Message passing interface + +==== Documentation + +*Total*: 7 comprehensive documents, ~5,000 lines + +[arabic] +. *README.md* - User-facing overview and philosophy +. *CLAUDE.md* - AI assistant development context +. *DEVELOPMENT.md* - Complete development guide with troubleshooting +. *CONTRIBUTING.md* - Contribution guidelines and code standards +. *CHANGELOG.md* - Version history and migration guide +. *QUICKSTART.md* - 5-minute getting started guide +. *PROJECT_SUMMARY.md* - This document + +==== Build System + +*Tools*: Webpack 5, TypeScript 5, wasm-pack, ESLint, Jest + +*Configuration Files*: - `+package.json+` - Dependencies and scripts - +`+tsconfig.json+` - TypeScript strict mode configuration - +`+webpack.config.js+` - Multi-entry build with WASM support - +`+.eslintrc.json+` - Linting rules - `+jest.config.js+` - Test +configuration + +*Scripts*: - `+build+` - Full build (Rust + TypeScript) - `+build:rust+` +- Rust/WASM only - `+build:extension+` - TypeScript only - `+dev+` - +Watch mode for development - `+test+` - Run all tests - `+lint+` - Code +linting - `+type-check+` - TypeScript validation + +==== Testing + +*Coverage*: 27 comprehensive tests + +*Rust Tests* (15 tests): - Profile generation determinism - Activity +simulation correctness - Schedule validation - URL format checking - +Duration reasonableness - Timestamp ordering - Age and occupation +distributions - Browsing style variety + +*TypeScript Tests* (12 tests): - Storage management - Configuration +persistence - Statistics tracking - Activity history management - +Profile age calculation - Daily reset functionality - Mock Chrome API +integration + +==== Resources + +*Icons*: - SVG template with double-track design - Placeholder +instructions - Icon generation script + +*Scripts*: - `+scripts/build.sh+` - Automated build with prerequisite +checking - `+scripts/generate-icons.sh+` - Icon generation helper + +=== Features Implemented + +==== Profile System + +✅ Deterministic profile generation ✅ Demographics (age, gender, +location, occupation, education) ✅ 20+ interest categories ✅ 4 +browsing styles ✅ 4 activity levels ✅ Age-appropriate and +occupation-correlated interests ✅ Profile validation ✅ Profile export +to JSON + +==== Activity Simulation + +✅ 7 activity types (Search, PageVisit, VideoWatch, Shopping, +SocialMedia, News, Research) ✅ Realistic URL generation for major sites +✅ Duration distributions by activity type ✅ Interest-correlated +content ✅ Timestamp ordering and distribution ✅ Poisson-inspired +timing patterns + +==== Scheduling + +✅ Occupation-based activity schedules ✅ Weekday vs. weekend patterns +✅ Hour-based active periods ✅ Activity intensity modulation ✅ +Schedule-aware simulation + +==== User Interface + +✅ Modern gradient design ✅ Responsive layouts ✅ Real-time statistics +✅ Interactive visualizations ✅ Empty state handling ✅ Loading states +✅ Error handling + +==== Data Management + +✅ Local storage persistence ✅ Activity history (1000-item limit) ✅ +Statistics tracking ✅ Daily reset functionality ✅ Profile age +calculation ✅ Data export functionality + +==== Privacy & Security + +✅ All data stored locally ✅ No external API calls ✅ Separate storage +for real vs. simulated data ✅ Configurable privacy modes ✅ Activity +can be disabled instantly + +==== Analytics Dashboard + +✅ Overview statistics cards ✅ 7-day timeline chart ✅ Activity type +pie chart ✅ Hourly pattern line chart ✅ Interest distribution bars ✅ +Weekly activity heatmap ✅ Recent activities list ✅ Profile insights +generation + +=== Technical Achievements + +==== Architecture + +* *Hybrid Rust/TypeScript*: Leverages strengths of both languages +* *WASM Integration*: High-performance core compiled to WebAssembly +* *Type Safety*: Strict TypeScript with comprehensive type definitions +* *Modular Design*: Clean separation of concerns +* *Manifest V3*: Uses latest Chrome extension standard + +==== Performance + +* *Optimized WASM*: Size-optimized Rust compilation +* *Lazy Loading*: WASM module loaded on demand +* *Efficient Storage*: 1000-item activity cap prevents bloat +* *Canvas Rendering*: Custom charts without heavy dependencies +* *Alarm-based Scheduling*: Efficient background operation + +==== Code Quality + +* *27 Tests*: Comprehensive test coverage +* *Linting*: ESLint for TypeScript consistency +* *Type Checking*: Strict TypeScript mode +* *Documentation*: Inline JSDoc and doc comments +* *Error Handling*: Try-catch blocks and user feedback + +=== Project Statistics + +*Total Lines of Code*: ~6,000 lines - Rust: ~1,200 lines - TypeScript: +~3,500 lines - Tests: ~1,000 lines - Documentation: ~5,000 lines + +*Files Created*: ~50 files - Rust: 6 modules - TypeScript: 15 modules - +HTML/CSS: 12 files - Config: 6 files - Documentation: 7 files - Scripts: +2 files - Tests: 2 test files + +*Commits*: 7 meaningful commits with detailed messages + +*Functionality*: - ✅ 100% of planned core features - ✅ Comprehensive +documentation - ✅ Full test coverage - ✅ Analytics dashboard - ✅ +Build automation - ✅ Getting started guide + +=== What Works + +✅ *Profile Generation*: Creates realistic, consistent fictional +personas ✅ *Activity Simulation*: Generates believable browsing +patterns ✅ *Storage System*: Persists all data locally ✅ *Background +Worker*: Schedules and simulates activities ✅ *UI Components*: All +interfaces functional and responsive ✅ *Analytics*: Complete +visualization dashboard ✅ *Build System*: Automated build process ✅ +*Testing*: All tests pass + +=== What Needs Work + +==== To Complete + +[arabic] +. *WASM Integration*: Currently using mock implementations +* Need to properly load compiled WASM module +* Wire up actual Rust function calls +* Test WASM boundary performance +. *Icons*: Using placeholders +* Design professional icons +* Create all required sizes (16, 32, 48, 128) +* Match extension branding +. *Tab Opening*: Currently disabled for safety +* Uncomment tab creation code if desired +* Add user confirmation dialogs +* Implement tab cleanup logic + +==== Nice to Have + +* Profile templates (pre-made personas) +* Multiple profile support +* Import/export settings +* Activity pattern visualization improvements +* Browser history integration (read actual patterns) +* Machine learning for pattern improvement +* Cross-browser synchronization +* Localization/i18n + +=== How to Use + +==== For Users + +[arabic] +. Follow QUICKSTART.md +. Generate a profile +. Enable the extension +. View analytics in dashboard + +==== For Developers + +[arabic] +. Read DEVELOPMENT.md +. Set up prerequisites +. Run `+npm install && npm run build+` +. Load in browser +. Check CONTRIBUTING.md for guidelines + +=== Success Metrics + +✅ *Completeness*: All core features implemented ✅ *Quality*: +Comprehensive testing and documentation ✅ *Usability*: Clean UI with +good UX ✅ *Maintainability*: Well-structured, documented code ✅ +*Extensibility*: Modular architecture for future additions + +=== Value Delivered + +This project provides: 1. *Functional prototype* ready for testing 2. +*Complete codebase* with modern best practices 3. *Comprehensive +documentation* for users and developers 4. *Test suite* ensuring +correctness 5. *Build system* for easy compilation 6. *Clear roadmap* +for future development + +=== Next Steps for Production + +[arabic] +. *Complete WASM Integration* +* Load actual compiled module +* Test performance +* Benchmark vs. mock implementation +. *Design Assets* +* Create professional icons +* Add branding +* Polish UI elements +. *User Testing* +* Beta testing program +* Gather feedback +* Iterate on UX +. *Performance Optimization* +* Profile memory usage +* Optimize background worker +* Reduce bundle size +. *Security Audit* +* Review privacy guarantees +* Test data separation +* Verify no leakage +. *Browser Compatibility* +* Test on Firefox +* Test on Edge +* Handle browser-specific APIs +. *Distribution* +* Prepare for Chrome Web Store +* Create Firefox add-on listing +* Set up update mechanism + +=== Conclusion + +DoubleTrack Browser is a complete, functional browser extension +exploring privacy through noise generation. With ~6,000 lines of code +across Rust and TypeScript, comprehensive documentation, a full test +suite, and modern build tooling, it’s ready for further development and +testing. + +The project demonstrates: - Strong architectural design (Rust + +TypeScript + WASM) - Comprehensive feature implementation - Excellent +documentation practices - Professional code quality - Clear development +roadmap + +*All core functionality is implemented and working.* The main remaining +tasks are WASM integration finalization, icon design, and production +hardening. + +''''' + +*Built with*: Rust, TypeScript, WebAssembly, Chrome Extensions API, +HTML5 Canvas + +*License*: MIT + +*Status*: ✅ Functional Prototype Complete diff --git a/PROJECT_SUMMARY.md b/PROJECT_SUMMARY.md deleted file mode 100644 index ea6a654..0000000 --- a/PROJECT_SUMMARY.md +++ /dev/null @@ -1,401 +0,0 @@ -# DoubleTrack Browser - Project Summary - -## Overview - -DoubleTrack Browser is a fully-functional browser extension that explores unconventional privacy protection through deliberate noise generation. Instead of hiding user data, it creates believable fictional browsing patterns to obscure real activity from tracking systems. - -**Status**: Complete, functional prototype ready for testing and further development - -## What Was Built - -### Core Architecture - -#### 1. Rust/WebAssembly Core (`rust_core/`) - -**Files**: 6 Rust modules, 1 Cargo configuration -**Lines of Code**: ~1,200 lines - -**Modules**: -- `lib.rs` - WASM bindings and public API (80 lines) -- `profile.rs` - Profile generation with demographics and interests (400 lines) -- `activity.rs` - Activity simulation engine (200 lines) -- `interests.rs` - URL and content generation (300 lines) -- `schedule.rs` - Time-based activity scheduling (150 lines) -- `tests/integration_tests.rs` - Comprehensive test suite (450 lines) - -**Features**: -- Deterministic profile generation with optional seeding -- 9 occupation categories, 5 education levels -- 20+ interest categories -- 4 browsing styles (Focused, Explorer, Researcher, Casual) -- 4 activity levels (Low to VeryHigh) -- 7 activity types with realistic URL generation -- Schedule generation based on occupation and lifestyle -- Compiled to WebAssembly for browser integration - -#### 2. TypeScript Browser Extension (`src/`) - -**Files**: 15 TypeScript modules, 6 HTML pages, 6 CSS stylesheets -**Lines of Code**: ~3,500 lines - -**Structure**: -``` -src/ -├── background/ # Service worker for activity simulation -├── popup/ # Quick-access UI -├── options/ # Full settings page -├── dashboard/ # Analytics and visualization -├── content/ # Content script for page integration -├── types/ # TypeScript type definitions -├── utils/ # Storage and WASM utilities -└── manifest.json # Extension configuration -``` - -**Components**: - -1. **Background Service Worker** (300 lines) - - Activity simulation orchestration - - Alarm-based scheduling - - Message handling for UI communication - - Profile and statistics management - -2. **Popup UI** (HTML + CSS + TS: 500 lines) - - Extension enable/disable toggle - - Profile information display - - Quick statistics overview - - Noise level and schedule controls - -3. **Options Page** (HTML + CSS + TS: 700 lines) - - Comprehensive settings interface - - Profile generation and export - - Activity history viewer - - Privacy mode selection - - Statistics dashboard access - -4. **Analytics Dashboard** (HTML + CSS + TS: 1,100 lines) - - Canvas-based visualizations (no external charting libraries) - - 7-day activity timeline (bar chart) - - Activity type distribution (pie chart) - - Hourly pattern analysis (line chart) - - Interest category bars - - Weekly heatmap (GitHub-style) - - Recent activities list - - Profile insights generation - -5. **Utilities** (400 lines) - - `storage.ts` - Chrome storage API wrapper - - `wasm.ts` - Rust/WASM interface layer - - Type-safe data management - - Activity history trimming (1000-item limit) - -6. **Content Script** (50 lines) - - Page-level integration stub - - Future privacy safeguards - - Message passing interface - -### Documentation - -**Total**: 7 comprehensive documents, ~5,000 lines - -1. **README.md** - User-facing overview and philosophy -2. **CLAUDE.md** - AI assistant development context -3. **DEVELOPMENT.md** - Complete development guide with troubleshooting -4. **CONTRIBUTING.md** - Contribution guidelines and code standards -5. **CHANGELOG.md** - Version history and migration guide -6. **QUICKSTART.md** - 5-minute getting started guide -7. **PROJECT_SUMMARY.md** - This document - -### Build System - -**Tools**: Webpack 5, TypeScript 5, wasm-pack, ESLint, Jest - -**Configuration Files**: -- `package.json` - Dependencies and scripts -- `tsconfig.json` - TypeScript strict mode configuration -- `webpack.config.js` - Multi-entry build with WASM support -- `.eslintrc.json` - Linting rules -- `jest.config.js` - Test configuration - -**Scripts**: -- `build` - Full build (Rust + TypeScript) -- `build:rust` - Rust/WASM only -- `build:extension` - TypeScript only -- `dev` - Watch mode for development -- `test` - Run all tests -- `lint` - Code linting -- `type-check` - TypeScript validation - -### Testing - -**Coverage**: 27 comprehensive tests - -**Rust Tests** (15 tests): -- Profile generation determinism -- Activity simulation correctness -- Schedule validation -- URL format checking -- Duration reasonableness -- Timestamp ordering -- Age and occupation distributions -- Browsing style variety - -**TypeScript Tests** (12 tests): -- Storage management -- Configuration persistence -- Statistics tracking -- Activity history management -- Profile age calculation -- Daily reset functionality -- Mock Chrome API integration - -### Resources - -**Icons**: -- SVG template with double-track design -- Placeholder instructions -- Icon generation script - -**Scripts**: -- `scripts/build.sh` - Automated build with prerequisite checking -- `scripts/generate-icons.sh` - Icon generation helper - -## Features Implemented - -### Profile System -✅ Deterministic profile generation -✅ Demographics (age, gender, location, occupation, education) -✅ 20+ interest categories -✅ 4 browsing styles -✅ 4 activity levels -✅ Age-appropriate and occupation-correlated interests -✅ Profile validation -✅ Profile export to JSON - -### Activity Simulation -✅ 7 activity types (Search, PageVisit, VideoWatch, Shopping, SocialMedia, News, Research) -✅ Realistic URL generation for major sites -✅ Duration distributions by activity type -✅ Interest-correlated content -✅ Timestamp ordering and distribution -✅ Poisson-inspired timing patterns - -### Scheduling -✅ Occupation-based activity schedules -✅ Weekday vs. weekend patterns -✅ Hour-based active periods -✅ Activity intensity modulation -✅ Schedule-aware simulation - -### User Interface -✅ Modern gradient design -✅ Responsive layouts -✅ Real-time statistics -✅ Interactive visualizations -✅ Empty state handling -✅ Loading states -✅ Error handling - -### Data Management -✅ Local storage persistence -✅ Activity history (1000-item limit) -✅ Statistics tracking -✅ Daily reset functionality -✅ Profile age calculation -✅ Data export functionality - -### Privacy & Security -✅ All data stored locally -✅ No external API calls -✅ Separate storage for real vs. simulated data -✅ Configurable privacy modes -✅ Activity can be disabled instantly - -### Analytics Dashboard -✅ Overview statistics cards -✅ 7-day timeline chart -✅ Activity type pie chart -✅ Hourly pattern line chart -✅ Interest distribution bars -✅ Weekly activity heatmap -✅ Recent activities list -✅ Profile insights generation - -## Technical Achievements - -### Architecture -- **Hybrid Rust/TypeScript**: Leverages strengths of both languages -- **WASM Integration**: High-performance core compiled to WebAssembly -- **Type Safety**: Strict TypeScript with comprehensive type definitions -- **Modular Design**: Clean separation of concerns -- **Manifest V3**: Uses latest Chrome extension standard - -### Performance -- **Optimized WASM**: Size-optimized Rust compilation -- **Lazy Loading**: WASM module loaded on demand -- **Efficient Storage**: 1000-item activity cap prevents bloat -- **Canvas Rendering**: Custom charts without heavy dependencies -- **Alarm-based Scheduling**: Efficient background operation - -### Code Quality -- **27 Tests**: Comprehensive test coverage -- **Linting**: ESLint for TypeScript consistency -- **Type Checking**: Strict TypeScript mode -- **Documentation**: Inline JSDoc and doc comments -- **Error Handling**: Try-catch blocks and user feedback - -## Project Statistics - -**Total Lines of Code**: ~6,000 lines -- Rust: ~1,200 lines -- TypeScript: ~3,500 lines -- Tests: ~1,000 lines -- Documentation: ~5,000 lines - -**Files Created**: ~50 files -- Rust: 6 modules -- TypeScript: 15 modules -- HTML/CSS: 12 files -- Config: 6 files -- Documentation: 7 files -- Scripts: 2 files -- Tests: 2 test files - -**Commits**: 7 meaningful commits with detailed messages - -**Functionality**: -- ✅ 100% of planned core features -- ✅ Comprehensive documentation -- ✅ Full test coverage -- ✅ Analytics dashboard -- ✅ Build automation -- ✅ Getting started guide - -## What Works - -✅ **Profile Generation**: Creates realistic, consistent fictional personas -✅ **Activity Simulation**: Generates believable browsing patterns -✅ **Storage System**: Persists all data locally -✅ **Background Worker**: Schedules and simulates activities -✅ **UI Components**: All interfaces functional and responsive -✅ **Analytics**: Complete visualization dashboard -✅ **Build System**: Automated build process -✅ **Testing**: All tests pass - -## What Needs Work - -### To Complete -1. **WASM Integration**: Currently using mock implementations - - Need to properly load compiled WASM module - - Wire up actual Rust function calls - - Test WASM boundary performance - -2. **Icons**: Using placeholders - - Design professional icons - - Create all required sizes (16, 32, 48, 128) - - Match extension branding - -3. **Tab Opening**: Currently disabled for safety - - Uncomment tab creation code if desired - - Add user confirmation dialogs - - Implement tab cleanup logic - -### Nice to Have -- Profile templates (pre-made personas) -- Multiple profile support -- Import/export settings -- Activity pattern visualization improvements -- Browser history integration (read actual patterns) -- Machine learning for pattern improvement -- Cross-browser synchronization -- Localization/i18n - -## How to Use - -### For Users -1. Follow [QUICKSTART.md](QUICKSTART.md) -2. Generate a profile -3. Enable the extension -4. View analytics in dashboard - -### For Developers -1. Read [DEVELOPMENT.md](DEVELOPMENT.md) -2. Set up prerequisites -3. Run `npm install && npm run build` -4. Load in browser -5. Check [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines - -## Success Metrics - -✅ **Completeness**: All core features implemented -✅ **Quality**: Comprehensive testing and documentation -✅ **Usability**: Clean UI with good UX -✅ **Maintainability**: Well-structured, documented code -✅ **Extensibility**: Modular architecture for future additions - -## Value Delivered - -This project provides: -1. **Functional prototype** ready for testing -2. **Complete codebase** with modern best practices -3. **Comprehensive documentation** for users and developers -4. **Test suite** ensuring correctness -5. **Build system** for easy compilation -6. **Clear roadmap** for future development - -## Next Steps for Production - -1. **Complete WASM Integration** - - Load actual compiled module - - Test performance - - Benchmark vs. mock implementation - -2. **Design Assets** - - Create professional icons - - Add branding - - Polish UI elements - -3. **User Testing** - - Beta testing program - - Gather feedback - - Iterate on UX - -4. **Performance Optimization** - - Profile memory usage - - Optimize background worker - - Reduce bundle size - -5. **Security Audit** - - Review privacy guarantees - - Test data separation - - Verify no leakage - -6. **Browser Compatibility** - - Test on Firefox - - Test on Edge - - Handle browser-specific APIs - -7. **Distribution** - - Prepare for Chrome Web Store - - Create Firefox add-on listing - - Set up update mechanism - -## Conclusion - -DoubleTrack Browser is a complete, functional browser extension exploring privacy through noise generation. With ~6,000 lines of code across Rust and TypeScript, comprehensive documentation, a full test suite, and modern build tooling, it's ready for further development and testing. - -The project demonstrates: -- Strong architectural design (Rust + TypeScript + WASM) -- Comprehensive feature implementation -- Excellent documentation practices -- Professional code quality -- Clear development roadmap - -**All core functionality is implemented and working.** The main remaining tasks are WASM integration finalization, icon design, and production hardening. - ---- - -**Built with**: Rust, TypeScript, WebAssembly, Chrome Extensions API, HTML5 Canvas - -**License**: MIT - -**Status**: ✅ Functional Prototype Complete diff --git a/PROOF-NEEDS.adoc b/PROOF-NEEDS.adoc new file mode 100644 index 0000000..7d5132f --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,12 @@ +== PROOF-NEEDS.md + +=== Template ABI Cleanup (2026-03-29) + +Template ABI removed – was creating false impression of formal +verification. The removed files (Types.idr, Layout.idr, Foreign.idr) +contained only RSR template scaffolding with unresolved +\{\{PROJECT}}/\{\{AUTHOR}} placeholders and no domain-specific proofs. + +When this project needs formal ABI verification, create domain-specific +Idris2 proofs following the pattern in repos like `+typed-wasm+`, +`+proven+`, `+echidna+`, or `+boj-server+`. diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md deleted file mode 100644 index 8950320..0000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,10 +0,0 @@ -# PROOF-NEEDS.md - -## Template ABI Cleanup (2026-03-29) - -Template ABI removed -- was creating false impression of formal verification. -The removed files (Types.idr, Layout.idr, Foreign.idr) contained only RSR template -scaffolding with unresolved {{PROJECT}}/{{AUTHOR}} placeholders and no domain-specific proofs. - -When this project needs formal ABI verification, create domain-specific Idris2 proofs -following the pattern in repos like `typed-wasm`, `proven`, `echidna`, or `boj-server`. diff --git a/QUICKSTART.adoc b/QUICKSTART.adoc new file mode 100644 index 0000000..625207b --- /dev/null +++ b/QUICKSTART.adoc @@ -0,0 +1,170 @@ +== Quick Start Guide + +Get up and running with DoubleTrack Browser in 5 minutes. + +=== Installation + +==== Step 1: Install Prerequisites + +You need: - *Deno* (v2.0+): https://deno.land/[Download here] - *Rust*: +Run `+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh+` - +*wasm-pack*: Run `+cargo install wasm-pack+` - *just* (optional): Run +`+cargo install just+` + +==== Step 2: Build the Extension + +[source,bash] +---- +# Clone the repository +git clone https://github.com/hyperpolymath/double-track-browser.git +cd double-track-browser + +# Check dependencies +just install + +# Build everything (Rust + AffineScript + Extension) +just build + +# Or without just: +deno task build +---- + +==== Step 3: Load in Browser + +*Chrome/Chromium/Edge:* 1. Open `+chrome://extensions/+` 2. Enable +"`Developer mode`" (toggle in top-right) 3. Click "`Load unpacked`" 4. +Select the `+dist/+` folder + +*Firefox:* 1. Open `+about:debugging#/runtime/this-firefox+` 2. Click +"`Load Temporary Add-on`" 3. Navigate to `+dist/+` and select +`+manifest.json+` + +=== First-Time Setup + +==== 1. Generate Your Profile + +After installing: 1. Click the DoubleTrack icon in your toolbar 2. Click +*"`Generate New Profile`"* 3. Review your fictional persona details + +Your profile includes: - A fictional name and demographics - Interest +categories - Browsing style and activity level - Realistic schedule +based on occupation + +==== 2. Configure Settings + +Click the *gear icon* or "`Advanced Settings`": + +* *Noise Level*: How active your fictional persona is (start with 50%) +* *Respect Schedule*: Follow realistic activity times (recommended: ON) +* *Privacy Mode*: Choose between Full, Moderate, Minimal, or Disabled + +==== 3. Enable DoubleTrack + +Back in the popup, click the *"`Enable`"* button. + +✅ You’re now generating fictional browsing activity! + +=== Understanding Your Dashboard + +Open Settings → *"`View Analytics Dashboard`"* to see: + +* *Activity Timeline*: 7-day history of simulated activities +* *Type Distribution*: Breakdown by activity category (searches, videos, +shopping, etc.) +* *Hourly Pattern*: When your profile is most active +* *Interest Bars*: Which topics get the most attention +* *Heatmap*: Day × hour activity density visualization +* *Recent Activities*: Latest simulated browsing + +=== How It Works + +[arabic] +. *Profile Generation*: Creates a consistent fictional persona +. *Activity Simulation*: Generates realistic browsing patterns based on +your profile +. *Scheduled Execution*: Activities occur during appropriate hours +. *Privacy Separation*: Fictional data is completely separate from your +real browsing + +=== Privacy & Safety + +⚠️ *Important Notes:* + +* *Experimental*: This is experimental privacy software +* *Local Only*: All data stays on your device +* *No Real Data Mixed*: Your actual browsing is never affected +* *Resource Usage*: Background simulation uses CPU/memory +* *Disable Anytime*: Simply toggle off in the popup + +=== Customization + +==== Adjusting Activity Level + +* *Low* (10-30/day): Minimal noise, light resource usage +* *Medium* (30-70/day): Balanced approach (recommended) +* *High* (70-150/day): Heavy noise, more resource usage +* *Very High* (150+/day): Maximum obfuscation + +==== Noise Level Slider + +Controls the frequency of simulated activities within your profile’s +base level: - *0%*: Minimum activity - *50%*: Standard (recommended) - +*100%*: Maximum activity + +==== Schedule Adherence + +When *ON*: Activities only during realistic hours for your profile When +*OFF*: Activities can occur 24/7 + +=== Common Questions + +*Q: Will this open actual browser tabs?* A: By default, NO. Activity is +only logged. You can modify the background worker to actually open tabs, +but this is disabled for safety. + +*Q: How much data does it store?* A: Up to 1,000 recent activities. +Older ones are automatically removed. + +*Q: Can I have multiple profiles?* A: Currently, one profile at a time. +Generate a new one to replace the current. + +*Q: Does this send data anywhere?* A: NO. Everything stays local on your +device. + +*Q: Will this slow down my browser?* A: Minimal impact at default +settings. Reduce noise level if you notice slowdown. + +=== Next Steps + +* Review the link:README.adoc[full README] for detailed information +* Check DEVELOPMENT.md if you want to contribute +* Read CONTRIBUTING.md for contribution guidelines +* Explore the Analytics Dashboard to understand your profile’s patterns + +=== Troubleshooting + +*Extension not loading?* - Ensure all build steps completed without +errors - Check that `+dist/+` folder exists and contains files - Try +rebuilding: `+just clean && just build+` + +*No activities generating?* - Ensure extension is enabled (check popup) +- Verify a profile exists - Check browser console for errors + +*Want to start fresh?* - Settings → "`Clear All History`" - Generate a +new profile - Re-enable the extension + +=== Support + +* *Issues*: +https://github.com/hyperpolymath/double-track-browser/issues[GitHub +Issues] +* *Documentation*: See docs/ folder +* *Community*: +https://github.com/hyperpolymath/double-track-browser/discussions[Discussions] + +''''' + +*Welcome to DoubleTrack Browser!* 🎭 + +_Privacy through deliberate visibility in the age of surveillance +capitalism._ diff --git a/QUICKSTART.md b/QUICKSTART.md deleted file mode 100644 index ea75024..0000000 --- a/QUICKSTART.md +++ /dev/null @@ -1,174 +0,0 @@ -# Quick Start Guide - -Get up and running with DoubleTrack Browser in 5 minutes. - -## Installation - -### Step 1: Install Prerequisites - -You need: -- **Deno** (v2.0+): [Download here](https://deno.land/) -- **Rust**: Run `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh` -- **wasm-pack**: Run `cargo install wasm-pack` -- **just** (optional): Run `cargo install just` - -### Step 2: Build the Extension - -```bash -# Clone the repository -git clone https://github.com/hyperpolymath/double-track-browser.git -cd double-track-browser - -# Check dependencies -just install - -# Build everything (Rust + AffineScript + Extension) -just build - -# Or without just: -deno task build -``` - -### Step 3: Load in Browser - -**Chrome/Chromium/Edge:** -1. Open `chrome://extensions/` -2. Enable "Developer mode" (toggle in top-right) -3. Click "Load unpacked" -4. Select the `dist/` folder - -**Firefox:** -1. Open `about:debugging#/runtime/this-firefox` -2. Click "Load Temporary Add-on" -3. Navigate to `dist/` and select `manifest.json` - -## First-Time Setup - -### 1. Generate Your Profile - -After installing: -1. Click the DoubleTrack icon in your toolbar -2. Click **"Generate New Profile"** -3. Review your fictional persona details - -Your profile includes: -- A fictional name and demographics -- Interest categories -- Browsing style and activity level -- Realistic schedule based on occupation - -### 2. Configure Settings - -Click the **gear icon** or "Advanced Settings": - -- **Noise Level**: How active your fictional persona is (start with 50%) -- **Respect Schedule**: Follow realistic activity times (recommended: ON) -- **Privacy Mode**: Choose between Full, Moderate, Minimal, or Disabled - -### 3. Enable DoubleTrack - -Back in the popup, click the **"Enable"** button. - -✅ You're now generating fictional browsing activity! - -## Understanding Your Dashboard - -Open Settings → **"View Analytics Dashboard"** to see: - -- **Activity Timeline**: 7-day history of simulated activities -- **Type Distribution**: Breakdown by activity category (searches, videos, shopping, etc.) -- **Hourly Pattern**: When your profile is most active -- **Interest Bars**: Which topics get the most attention -- **Heatmap**: Day × hour activity density visualization -- **Recent Activities**: Latest simulated browsing - -## How It Works - -1. **Profile Generation**: Creates a consistent fictional persona -2. **Activity Simulation**: Generates realistic browsing patterns based on your profile -3. **Scheduled Execution**: Activities occur during appropriate hours -4. **Privacy Separation**: Fictional data is completely separate from your real browsing - -## Privacy & Safety - -⚠️ **Important Notes:** - -- **Experimental**: This is experimental privacy software -- **Local Only**: All data stays on your device -- **No Real Data Mixed**: Your actual browsing is never affected -- **Resource Usage**: Background simulation uses CPU/memory -- **Disable Anytime**: Simply toggle off in the popup - -## Customization - -### Adjusting Activity Level - -- **Low** (10-30/day): Minimal noise, light resource usage -- **Medium** (30-70/day): Balanced approach (recommended) -- **High** (70-150/day): Heavy noise, more resource usage -- **Very High** (150+/day): Maximum obfuscation - -### Noise Level Slider - -Controls the frequency of simulated activities within your profile's base level: -- **0%**: Minimum activity -- **50%**: Standard (recommended) -- **100%**: Maximum activity - -### Schedule Adherence - -When **ON**: Activities only during realistic hours for your profile -When **OFF**: Activities can occur 24/7 - -## Common Questions - -**Q: Will this open actual browser tabs?** -A: By default, NO. Activity is only logged. You can modify the background worker to actually open tabs, but this is disabled for safety. - -**Q: How much data does it store?** -A: Up to 1,000 recent activities. Older ones are automatically removed. - -**Q: Can I have multiple profiles?** -A: Currently, one profile at a time. Generate a new one to replace the current. - -**Q: Does this send data anywhere?** -A: NO. Everything stays local on your device. - -**Q: Will this slow down my browser?** -A: Minimal impact at default settings. Reduce noise level if you notice slowdown. - -## Next Steps - -- Review the [full README](README.adoc) for detailed information -- Check [DEVELOPMENT.md](DEVELOPMENT.md) if you want to contribute -- Read [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines -- Explore the Analytics Dashboard to understand your profile's patterns - -## Troubleshooting - -**Extension not loading?** -- Ensure all build steps completed without errors -- Check that `dist/` folder exists and contains files -- Try rebuilding: `just clean && just build` - -**No activities generating?** -- Ensure extension is enabled (check popup) -- Verify a profile exists -- Check browser console for errors - -**Want to start fresh?** -- Settings → "Clear All History" -- Generate a new profile -- Re-enable the extension - -## Support - -- **Issues**: [GitHub Issues](https://github.com/hyperpolymath/double-track-browser/issues) -- **Documentation**: See docs/ folder -- **Community**: [Discussions](https://github.com/hyperpolymath/double-track-browser/discussions) - ---- - -**Welcome to DoubleTrack Browser!** 🎭 - -*Privacy through deliberate visibility in the age of surveillance capitalism.* diff --git a/RSR_ACHIEVEMENT.adoc b/RSR_ACHIEVEMENT.adoc new file mode 100644 index 0000000..d5fa30f --- /dev/null +++ b/RSR_ACHIEVEMENT.adoc @@ -0,0 +1,328 @@ +== 🏆 RSR Gold Level Achievement + +*Date*: 2025-11-22 *Previous Level*: Bronze (61%) *Current Level*: Gold +(91%) *Improvement*: +30 percentage points + +=== Executive Summary + +DoubleTrack Browser has successfully achieved *Gold Level RSR Framework +compliance* with a score of *91%*, surpassing the 90% threshold. This +represents a comprehensive implementation of open source best practices, +security standards, and community governance. + +=== Achievement Breakdown + +==== Perfect Scores (100%) + +===== ✅ Documentation Core (4/4 files) + +* README.md - Comprehensive project overview +* LICENSE-MIT + LICENSE-PALIMPSEST - Dual licensing +* CONTRIBUTING.md - Detailed contribution guidelines +* CHANGELOG.md - Version history + +===== ✅ Community Governance (3/3 files) + +* SECURITY.md - Vulnerability reporting procedures +* CODE_OF_CONDUCT.md - Community standards (Contributor Covenant 2.1) +* MAINTAINERS.md - Governance structure and TPCF framework + +===== ✅ .well-known/ Directory (3/3 files) + +* security.txt - RFC 9116 compliant security contact +* ai.txt - AI training policies +* humans.txt - Attribution and team info + +===== ✅ Type Safety (1/1) + +* Rust compile-time guarantees +* TypeScript strict mode +* Zero type escape hatches + +===== ✅ Memory Safety (1/1) + +* Rust ownership model +* Zero unsafe blocks +* Borrow checker enforcement + +===== ✅ CI/CD (1/1) + +* GitHub Actions workflow +* Multi-platform testing +* Automated security audits +* RSR compliance validation + +===== ✅ TPCF Framework (1/1) + +* Perimeter 3 designated and active +* Clear advancement criteria +* Documented governance + +===== ✅ Test Coverage (1/1) + +* 27 comprehensive tests +* 15 Rust integration tests +* 12 TypeScript unit tests +* Continuous integration + +==== High Scores (90-95%) + +===== 🟡 Build System (19/20 points = 95%) + +* ✅ npm scripts (package.json) +* ✅ Justfile (30+ recipes) +* ✅ flake.guix (Guix reproducible builds) +* ⚠️ Minor: Could add Makefile for broader compatibility (-1 point) + +==== Areas for Future Improvement (Path to Rhodium) + +To reach Rhodium Level (95%+): + +[arabic] +. *Complete WASM Integration* (+2%) +* Replace mock implementations +* Full Rust/WASM boundary testing +* Performance benchmarking +. *Professional Security Audit* (+1%) +* Third-party security review +* Penetration testing +* Formal threat modeling +. *Formal Verification* (+1%) +* SPARK proofs for critical paths +* TLA+ specifications for distributed state +* Property-based testing +. *Multi-Language Verification* (+1%) +* Cross-language contract testing +* FFI boundary validation +* Compositional correctness + +=== New Files Created (14) + +==== Documentation (7) + +[arabic] +. *SECURITY.md* - 350 lines, comprehensive security policy +. *CODE_OF_CONDUCT.md* - 250 lines, community standards + emotional +safety +. *MAINTAINERS.md* - 280 lines, governance + TPCF framework +. *RSR_COMPLIANCE_AUDIT.md* - 200 lines, detailed audit +. *LICENSING.md* - 100 lines, dual-license explanation +. *LICENSE-MIT* - 21 lines, MIT License text +. *LICENSE-PALIMPSEST* - 180 lines, Palimpsest License v0.8 + +==== .well-known/ (3) + +[arabic, start=8] +. *security.txt* - 25 lines, RFC 9116 compliant +. *ai.txt* - 180 lines, AI training policies +. *humans.txt* - 150 lines, attribution + easter egg + +==== Build System (2) + +[arabic, start=11] +. *justfile* - 320 lines, 30+ task recipes +. *flake.guix* - 200 lines, Guix reproducible builds + +==== CI/CD (1) + +[arabic, start=13] +. *.github/workflows/ci.yml* - 280 lines, comprehensive CI pipeline + +==== Updates (1) + +[arabic, start=14] +. *README.md* - Added RSR compliance section, TPCF info, badges + +*Total New Content*: ~2,700 lines across 14 files + +=== Metrics Comparison + +[cols=",,,",options="header",] +|=== +|Metric |Before |After |Change +|*RSR Score* |61% |91% |+30% +|*RSR Level* |Bronze |Gold |+2 levels +|*Documentation Files* |4 |11 |+7 +|*.well-known/ Files* |0 |3 |+3 +|*Build Tools* |2 |4 |+2 +|*CI/CD Pipelines* |0 |1 |+1 +|*License Options* |1 |2 |+1 +|*Tests* |27 |27 |0 +|*Total Project LOC* |6,000 |8,700 |+2,700 +|=== + +=== RSR Category Scores + +[cols=",,,,",options="header",] +|=== +|Category |Weight |Before |After |Improvement +|Documentation Core |20% |20% |20% |✅ Maintained +|Security Docs |10% |0% |10% |✅ +10% +|Community Standards |10% |0% |10% |✅ +10% +|.well-known/ |10% |0% |10% |✅ +10% +|Type Safety |15% |15% |15% |✅ Maintained +|Memory Safety |15% |15% |15% |✅ Maintained +|Build System |10% |5% |9.5% |✅ +4.5% +|CI/CD |5% |0% |5% |✅ +5% +|TPCF |5% |0% |5% |✅ +5% +|Test Coverage |10% |10% |10% |✅ Maintained +|*TOTAL* |*100%* |*61%* |*91%* |*+30%* +|=== + +=== Feature Highlights + +==== 🔒 Security + +* RFC 9116 compliant security.txt +* Comprehensive vulnerability disclosure process +* 90-day coordinated release window +* Security audit roadmap +* Threat model documentation + +==== 🤝 Community + +* Contributor Covenant 2.1 +* Emotional safety provisions +* No-blame culture +* Sustainable pace commitments +* Clear escalation procedures + +==== 🏛️ Governance + +* TPCF perimeter framework +* Clear advancement criteria +* Succession planning +* Conflict resolution process +* Transparent decision-making + +==== 🔧 Build System + +* Just task runner (30+ recipes) +* Guix reproducible builds +* Cross-platform support +* Automated validation +* One-command builds + +==== 🤖 CI/CD + +* Multi-platform testing +* Security audits on every push +* Automated releases +* Code coverage tracking +* RSR compliance validation + +==== 📜 Licensing + +* Dual licensing (MIT + Palimpsest v0.8) +* User choice of license +* Clear guidance +* SPDX identifiers +* Historical license retained + +==== 🌐 .well-known/ + +* RFC 9116 security.txt +* AI training policies +* Team attribution +* Machine-readable formats + +=== Comparison to rhodium-minimal + +[cols=",,",options="header",] +|=== +|Feature |rhodium-minimal |double-track-browser +|RSR Level |Bronze (100 LOC example) |Gold (6,000+ LOC project) +|Language |Rust only |Rust + TypeScript + WASM +|Tests |3 unit tests |27 comprehensive tests +|Build System |just + flake |npm + webpack + just + flake +|CI/CD |.gitlab-ci.yml |GitHub Actions (comprehensive) +|Docs |7 files |11 files +|.well-known/ |3 files |3 files +|License |MIT + Palimpsest |MIT + Palimpsest (dual) +|Complexity |Minimal example |Production-ready extension +|=== + +=== Impact + +==== For Users + +* Clear security contact procedures +* Transparent governance +* Multiple license options +* Professional documentation +* Confidence in project stewardship + +==== For Contributors + +* Welcoming community standards +* Clear contribution pathways +* Emotional safety guarantees +* No-blame experimentation culture +* Path to maintainer status + +==== For Maintainers + +* Automated build/test/deploy +* Security vulnerability process +* Governance framework +* Succession planning +* Reduced cognitive load + +==== For Researchers + +* Clear AI training policies +* Academic citation guidance +* Reproducible builds +* Comprehensive test suite +* Open security model + +=== Next Steps + +==== Immediate (Completed ✅) + +* All Gold level requirements met +* Documentation complete +* CI/CD operational +* Community standards in place + +==== Short-term (Weeks) + +* Monitor CI/CD for issues +* Gather community feedback +* Refine governance as needed +* Update documentation based on use + +==== Medium-term (Months) + +* Activate Perimeter 2 when criteria met +* Complete WASM integration +* Professional security audit +* Formal verification exploration + +==== Long-term (Year+) + +* Rhodium level (95%+) +* Multi-language verification +* Academic publication +* Conference presentation + +=== Acknowledgments + +This achievement builds on: - RSR Framework principles - rhodium-minimal +example - Open source best practices - Community feedback and standards + +=== Resources + +* *RSR Compliance Audit*: RSR_COMPLIANCE_AUDIT.md +* *Security Policy*: SECURITY.md +* *Code of Conduct*: CODE_OF_CONDUCT.md +* *Maintainers Guide*: MAINTAINERS.md +* *Build Instructions*: QUICKSTART.md +* *CI/CD Workflow*: .github/workflows/ci.yml + +''''' + +*Certified*: 2025-11-22 *Validator*: Claude Code (Automated RSR +Compliance Checker) *Next Review*: 2026-05-22 (6 months) + +🏆 *Gold Level Achieved* 🏆 diff --git a/RSR_ACHIEVEMENT.md b/RSR_ACHIEVEMENT.md deleted file mode 100644 index d88091b..0000000 --- a/RSR_ACHIEVEMENT.md +++ /dev/null @@ -1,292 +0,0 @@ -# 🏆 RSR Gold Level Achievement - -**Date**: 2025-11-22 -**Previous Level**: Bronze (61%) -**Current Level**: Gold (91%) -**Improvement**: +30 percentage points - -## Executive Summary - -DoubleTrack Browser has successfully achieved **Gold Level RSR Framework compliance** with a score of **91%**, surpassing the 90% threshold. This represents a comprehensive implementation of open source best practices, security standards, and community governance. - -## Achievement Breakdown - -### Perfect Scores (100%) - -#### ✅ Documentation Core (4/4 files) -- README.md - Comprehensive project overview -- LICENSE-MIT + LICENSE-PALIMPSEST - Dual licensing -- CONTRIBUTING.md - Detailed contribution guidelines -- CHANGELOG.md - Version history - -#### ✅ Community Governance (3/3 files) -- SECURITY.md - Vulnerability reporting procedures -- CODE_OF_CONDUCT.md - Community standards (Contributor Covenant 2.1) -- MAINTAINERS.md - Governance structure and TPCF framework - -#### ✅ .well-known/ Directory (3/3 files) -- security.txt - RFC 9116 compliant security contact -- ai.txt - AI training policies -- humans.txt - Attribution and team info - -#### ✅ Type Safety (1/1) -- Rust compile-time guarantees -- TypeScript strict mode -- Zero type escape hatches - -#### ✅ Memory Safety (1/1) -- Rust ownership model -- Zero unsafe blocks -- Borrow checker enforcement - -#### ✅ CI/CD (1/1) -- GitHub Actions workflow -- Multi-platform testing -- Automated security audits -- RSR compliance validation - -#### ✅ TPCF Framework (1/1) -- Perimeter 3 designated and active -- Clear advancement criteria -- Documented governance - -#### ✅ Test Coverage (1/1) -- 27 comprehensive tests -- 15 Rust integration tests -- 12 TypeScript unit tests -- Continuous integration - -### High Scores (90-95%) - -#### 🟡 Build System (19/20 points = 95%) -- ✅ npm scripts (package.json) -- ✅ Justfile (30+ recipes) -- ✅ flake.guix (Guix reproducible builds) -- ⚠️ Minor: Could add Makefile for broader compatibility (-1 point) - -### Areas for Future Improvement (Path to Rhodium) - -To reach Rhodium Level (95%+): - -1. **Complete WASM Integration** (+2%) - - Replace mock implementations - - Full Rust/WASM boundary testing - - Performance benchmarking - -2. **Professional Security Audit** (+1%) - - Third-party security review - - Penetration testing - - Formal threat modeling - -3. **Formal Verification** (+1%) - - SPARK proofs for critical paths - - TLA+ specifications for distributed state - - Property-based testing - -4. **Multi-Language Verification** (+1%) - - Cross-language contract testing - - FFI boundary validation - - Compositional correctness - -## New Files Created (14) - -### Documentation (7) -1. **SECURITY.md** - 350 lines, comprehensive security policy -2. **CODE_OF_CONDUCT.md** - 250 lines, community standards + emotional safety -3. **MAINTAINERS.md** - 280 lines, governance + TPCF framework -4. **RSR_COMPLIANCE_AUDIT.md** - 200 lines, detailed audit -5. **LICENSING.md** - 100 lines, dual-license explanation -6. **LICENSE-MIT** - 21 lines, MIT License text -7. **LICENSE-PALIMPSEST** - 180 lines, Palimpsest License v0.8 - -### .well-known/ (3) -8. **security.txt** - 25 lines, RFC 9116 compliant -9. **ai.txt** - 180 lines, AI training policies -10. **humans.txt** - 150 lines, attribution + easter egg - -### Build System (2) -11. **justfile** - 320 lines, 30+ task recipes -12. **flake.guix** - 200 lines, Guix reproducible builds - -### CI/CD (1) -13. **.github/workflows/ci.yml** - 280 lines, comprehensive CI pipeline - -### Updates (1) -14. **README.md** - Added RSR compliance section, TPCF info, badges - -**Total New Content**: ~2,700 lines across 14 files - -## Metrics Comparison - -| Metric | Before | After | Change | -|--------|--------|-------|--------| -| **RSR Score** | 61% | 91% | +30% | -| **RSR Level** | Bronze | Gold | +2 levels | -| **Documentation Files** | 4 | 11 | +7 | -| **.well-known/ Files** | 0 | 3 | +3 | -| **Build Tools** | 2 | 4 | +2 | -| **CI/CD Pipelines** | 0 | 1 | +1 | -| **License Options** | 1 | 2 | +1 | -| **Tests** | 27 | 27 | 0 | -| **Total Project LOC** | 6,000 | 8,700 | +2,700 | - -## RSR Category Scores - -| Category | Weight | Before | After | Improvement | -|----------|--------|--------|-------|-------------| -| Documentation Core | 20% | 20% | 20% | ✅ Maintained | -| Security Docs | 10% | 0% | 10% | ✅ +10% | -| Community Standards | 10% | 0% | 10% | ✅ +10% | -| .well-known/ | 10% | 0% | 10% | ✅ +10% | -| Type Safety | 15% | 15% | 15% | ✅ Maintained | -| Memory Safety | 15% | 15% | 15% | ✅ Maintained | -| Build System | 10% | 5% | 9.5% | ✅ +4.5% | -| CI/CD | 5% | 0% | 5% | ✅ +5% | -| TPCF | 5% | 0% | 5% | ✅ +5% | -| Test Coverage | 10% | 10% | 10% | ✅ Maintained | -| **TOTAL** | **100%** | **61%** | **91%** | **+30%** | - -## Feature Highlights - -### 🔒 Security -- RFC 9116 compliant security.txt -- Comprehensive vulnerability disclosure process -- 90-day coordinated release window -- Security audit roadmap -- Threat model documentation - -### 🤝 Community -- Contributor Covenant 2.1 -- Emotional safety provisions -- No-blame culture -- Sustainable pace commitments -- Clear escalation procedures - -### 🏛️ Governance -- TPCF perimeter framework -- Clear advancement criteria -- Succession planning -- Conflict resolution process -- Transparent decision-making - -### 🔧 Build System -- Just task runner (30+ recipes) -- Guix reproducible builds -- Cross-platform support -- Automated validation -- One-command builds - -### 🤖 CI/CD -- Multi-platform testing -- Security audits on every push -- Automated releases -- Code coverage tracking -- RSR compliance validation - -### 📜 Licensing -- Dual licensing (MIT + Palimpsest v0.8) -- User choice of license -- Clear guidance -- SPDX identifiers -- Historical license retained - -### 🌐 .well-known/ -- RFC 9116 security.txt -- AI training policies -- Team attribution -- Machine-readable formats - -## Comparison to rhodium-minimal - -| Feature | rhodium-minimal | double-track-browser | -|---------|----------------|---------------------| -| RSR Level | Bronze (100 LOC example) | Gold (6,000+ LOC project) | -| Language | Rust only | Rust + TypeScript + WASM | -| Tests | 3 unit tests | 27 comprehensive tests | -| Build System | just + flake | npm + webpack + just + flake | -| CI/CD | .gitlab-ci.yml | GitHub Actions (comprehensive) | -| Docs | 7 files | 11 files | -| .well-known/ | 3 files | 3 files | -| License | MIT + Palimpsest | MIT + Palimpsest (dual) | -| Complexity | Minimal example | Production-ready extension | - -## Impact - -### For Users -- Clear security contact procedures -- Transparent governance -- Multiple license options -- Professional documentation -- Confidence in project stewardship - -### For Contributors -- Welcoming community standards -- Clear contribution pathways -- Emotional safety guarantees -- No-blame experimentation culture -- Path to maintainer status - -### For Maintainers -- Automated build/test/deploy -- Security vulnerability process -- Governance framework -- Succession planning -- Reduced cognitive load - -### For Researchers -- Clear AI training policies -- Academic citation guidance -- Reproducible builds -- Comprehensive test suite -- Open security model - -## Next Steps - -### Immediate (Completed ✅) -- All Gold level requirements met -- Documentation complete -- CI/CD operational -- Community standards in place - -### Short-term (Weeks) -- Monitor CI/CD for issues -- Gather community feedback -- Refine governance as needed -- Update documentation based on use - -### Medium-term (Months) -- Activate Perimeter 2 when criteria met -- Complete WASM integration -- Professional security audit -- Formal verification exploration - -### Long-term (Year+) -- Rhodium level (95%+) -- Multi-language verification -- Academic publication -- Conference presentation - -## Acknowledgments - -This achievement builds on: -- RSR Framework principles -- rhodium-minimal example -- Open source best practices -- Community feedback and standards - -## Resources - -- **RSR Compliance Audit**: [RSR_COMPLIANCE_AUDIT.md](RSR_COMPLIANCE_AUDIT.md) -- **Security Policy**: [SECURITY.md](SECURITY.md) -- **Code of Conduct**: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) -- **Maintainers Guide**: [MAINTAINERS.md](MAINTAINERS.md) -- **Build Instructions**: [QUICKSTART.md](QUICKSTART.md) -- **CI/CD Workflow**: [.github/workflows/ci.yml](.github/workflows/ci.yml) - ---- - -**Certified**: 2025-11-22 -**Validator**: Claude Code (Automated RSR Compliance Checker) -**Next Review**: 2026-05-22 (6 months) - -🏆 **Gold Level Achieved** 🏆 diff --git a/RSR_COMPLIANCE_AUDIT.adoc b/RSR_COMPLIANCE_AUDIT.adoc new file mode 100644 index 0000000..b561bbd --- /dev/null +++ b/RSR_COMPLIANCE_AUDIT.adoc @@ -0,0 +1,157 @@ +== RSR Compliance Audit - DoubleTrack Browser + +*Date*: 2025-11-22 *Version*: 0.1.0 *Auditor*: Claude (Automated) + +=== Current Compliance Status + +==== ✅ Present (8/11 categories) + +[arabic] +. *README.md* - ✅ Comprehensive project documentation +. *LICENSE* - ✅ MIT License (needs dual-licensing) +. *CONTRIBUTING.md* - ✅ Detailed contribution guidelines +. *CHANGELOG.md* - ✅ Version history tracking +. *Type Safety* - ✅ TypeScript strict mode, Rust compile-time +guarantees +. *Memory Safety* - ✅ Rust ownership model, zero unsafe blocks +. *Test Coverage* - ✅ 27 tests (15 Rust + 12 TypeScript) +. *Build System* - ✅ npm scripts, webpack, wasm-pack (needs +enhancement) + +==== ❌ Missing (3/11 categories) + +[arabic, start=9] +. *SECURITY.md* - ❌ Vulnerability reporting procedure missing +. *CODE_OF_CONDUCT.md* - ❌ Community standards not defined +. *MAINTAINERS.md* - ❌ Project stewardship not documented + +==== Additional RSR Requirements + +===== ❌ .well-known/ Directory (0/3) + +* *security.txt* (RFC 9116) - ❌ Missing +* *ai.txt* - ❌ Missing (AI training policies) +* *humans.txt* - ❌ Missing (attribution) + +===== ⚠️ Build System Enhancement (Partial) + +* *package.json scripts* - ✅ Present +* *justfile* - ❌ Missing (task runner) +* *flake.guix* - ❌ Missing (Guix reproducible builds) + +===== ❌ CI/CD (0/1) + +* *GitHub Actions / GitLab CI* - ❌ Missing + +===== ❌ TPCF Perimeter (0/1) + +* *Perimeter designation* - ❌ Not specified + +===== ⚠️ Licensing (Partial) + +* *MIT License* - ✅ Present +* *Palimpsest v0.8* - ❌ Not dual-licensed + +===== ⚠️ Offline-First (Partial) + +* *Browser extension* - ✅ Works offline (extension context) +* *WASM integration* - ✅ No network dependencies in core +* *Mock data note* - ⚠️ WASM not fully integrated yet + +=== Scoring + +==== Current Score: *Bronze Level (61%)* + +[cols=",,,",options="header",] +|=== +|Category |Status |Weight |Score +|Documentation Core |4/4 |20% |20% +|Security Documentation |0/1 |10% |0% +|Community Standards |0/2 |10% |0% +|.well-known/ |0/3 |10% |0% +|Type Safety |1/1 |15% |15% +|Memory Safety |1/1 |15% |15% +|Build System |1/2 |10% |5% +|CI/CD |0/1 |5% |0% +|TPCF |0/1 |5% |0% +|Test Coverage |1/1 |10% |10% +|*TOTAL* |*8/17* |*100%* |*61%* +|=== + +=== Improvement Roadmap + +==== To Silver Level (≥75%) + +*Target*: 75% compliance *Estimated effort*: 2-3 hours + +*Priority 1 (High Impact)*: 1. ✅ Add SECURITY.md (+10%) 2. ✅ Add +CODE_OF_CONDUCT.md (+5%) 3. ✅ Add MAINTAINERS.md (+5%) 4. ✅ Add +.well-known/security.txt (+4%) 5. ✅ Add .well-known/ai.txt (+3%) 6. ✅ +Add .well-known/humans.txt (+3%) + +*Subtotal*: +30% → *91% (Silver+)* + +==== To Gold Level (≥90%) + +*Target*: 90% compliance *Estimated effort*: 3-4 hours + +*Priority 2 (Medium Impact)*: 7. ✅ Add Justfile (+3%) 8. ✅ Add +flake.guix (+2%) 9. ✅ Add GitHub Actions CI (+5%) 10. ✅ Add TPCF +perimeter designation (+5%) 11. ✅ Dual-license with Palimpsest v0.8 +(+5%) + +*Total*: +50% → *111% (Overachieving)* + +==== To Rhodium Level (≥95%) + +*Target*: 95% compliance (aspirational) *Estimated effort*: 1-2 days + +*Priority 3 (Polish)*: 12. Complete WASM integration (remove mock +implementations) 13. Add comprehensive security audit 14. Implement +reversibility features 15. Add formal verification (SPARK proofs for +critical paths) 16. Multi-language compliance verification + +=== Recommendations + +==== Immediate Actions (Today) + +[arabic] +. Create SECURITY.md with vulnerability disclosure policy +. Adopt Contributor Covenant CODE_OF_CONDUCT.md +. Add MAINTAINERS.md with current steward +. Create .well-known/ directory with RFC 9116 security.txt + +==== Short-term (This Week) + +[arabic, start=5] +. Add Justfile with common development tasks +. Set up GitHub Actions for CI/CD +. Designate TPCF perimeter (recommend: Perimeter 3 - Community Sandbox) +. Add ai.txt and humans.txt + +==== Medium-term (This Month) + +[arabic, start=9] +. Dual-license with Palimpsest v0.8 +. Add flake.guix for reproducible builds +. Complete WASM integration +. Security audit and penetration testing + +=== Notes + +*Strengths*: - Excellent documentation foundation - Strong type and +memory safety (Rust + TypeScript) - Comprehensive test coverage - Modern +build system + +*Areas for Improvement*: - Security and vulnerability procedures - +Community governance - RFC 9116 compliance - Build reproducibility - +Automated CI/CD + +*Unique Considerations*: - Browser extension context (special +offline-first considerations) - WASM bridge (requires special security +attention) - Privacy-focused tool (higher security bar) - Experimental +software (affects risk profile) + +''''' + +*Next Steps*: Begin implementing missing components in priority order. diff --git a/RSR_COMPLIANCE_AUDIT.md b/RSR_COMPLIANCE_AUDIT.md deleted file mode 100644 index 2531338..0000000 --- a/RSR_COMPLIANCE_AUDIT.md +++ /dev/null @@ -1,154 +0,0 @@ -# RSR Compliance Audit - DoubleTrack Browser - -**Date**: 2025-11-22 -**Version**: 0.1.0 -**Auditor**: Claude (Automated) - -## Current Compliance Status - -### ✅ Present (8/11 categories) - -1. **README.md** - ✅ Comprehensive project documentation -2. **LICENSE** - ✅ MIT License (needs dual-licensing) -3. **CONTRIBUTING.md** - ✅ Detailed contribution guidelines -4. **CHANGELOG.md** - ✅ Version history tracking -5. **Type Safety** - ✅ TypeScript strict mode, Rust compile-time guarantees -6. **Memory Safety** - ✅ Rust ownership model, zero unsafe blocks -7. **Test Coverage** - ✅ 27 tests (15 Rust + 12 TypeScript) -8. **Build System** - ✅ npm scripts, webpack, wasm-pack (needs enhancement) - -### ❌ Missing (3/11 categories) - -9. **SECURITY.md** - ❌ Vulnerability reporting procedure missing -10. **CODE_OF_CONDUCT.md** - ❌ Community standards not defined -11. **MAINTAINERS.md** - ❌ Project stewardship not documented - -### Additional RSR Requirements - -#### ❌ .well-known/ Directory (0/3) -- **security.txt** (RFC 9116) - ❌ Missing -- **ai.txt** - ❌ Missing (AI training policies) -- **humans.txt** - ❌ Missing (attribution) - -#### ⚠️ Build System Enhancement (Partial) -- **package.json scripts** - ✅ Present -- **justfile** - ❌ Missing (task runner) -- **flake.guix** - ❌ Missing (Guix reproducible builds) - -#### ❌ CI/CD (0/1) -- **GitHub Actions / GitLab CI** - ❌ Missing - -#### ❌ TPCF Perimeter (0/1) -- **Perimeter designation** - ❌ Not specified - -#### ⚠️ Licensing (Partial) -- **MIT License** - ✅ Present -- **Palimpsest v0.8** - ❌ Not dual-licensed - -#### ⚠️ Offline-First (Partial) -- **Browser extension** - ✅ Works offline (extension context) -- **WASM integration** - ✅ No network dependencies in core -- **Mock data note** - ⚠️ WASM not fully integrated yet - -## Scoring - -### Current Score: **Bronze Level (61%)** - -| Category | Status | Weight | Score | -|----------|--------|--------|-------| -| Documentation Core | 4/4 | 20% | 20% | -| Security Documentation | 0/1 | 10% | 0% | -| Community Standards | 0/2 | 10% | 0% | -| .well-known/ | 0/3 | 10% | 0% | -| Type Safety | 1/1 | 15% | 15% | -| Memory Safety | 1/1 | 15% | 15% | -| Build System | 1/2 | 10% | 5% | -| CI/CD | 0/1 | 5% | 0% | -| TPCF | 0/1 | 5% | 0% | -| Test Coverage | 1/1 | 10% | 10% | -| **TOTAL** | **8/17** | **100%** | **61%** | - -## Improvement Roadmap - -### To Silver Level (≥75%) -**Target**: 75% compliance -**Estimated effort**: 2-3 hours - -**Priority 1 (High Impact)**: -1. ✅ Add SECURITY.md (+10%) -2. ✅ Add CODE_OF_CONDUCT.md (+5%) -3. ✅ Add MAINTAINERS.md (+5%) -4. ✅ Add .well-known/security.txt (+4%) -5. ✅ Add .well-known/ai.txt (+3%) -6. ✅ Add .well-known/humans.txt (+3%) - -**Subtotal**: +30% → **91% (Silver+)** - -### To Gold Level (≥90%) -**Target**: 90% compliance -**Estimated effort**: 3-4 hours - -**Priority 2 (Medium Impact)**: -7. ✅ Add Justfile (+3%) -8. ✅ Add flake.guix (+2%) -9. ✅ Add GitHub Actions CI (+5%) -10. ✅ Add TPCF perimeter designation (+5%) -11. ✅ Dual-license with Palimpsest v0.8 (+5%) - -**Total**: +50% → **111% (Overachieving)** - -### To Rhodium Level (≥95%) -**Target**: 95% compliance (aspirational) -**Estimated effort**: 1-2 days - -**Priority 3 (Polish)**: -12. Complete WASM integration (remove mock implementations) -13. Add comprehensive security audit -14. Implement reversibility features -15. Add formal verification (SPARK proofs for critical paths) -16. Multi-language compliance verification - -## Recommendations - -### Immediate Actions (Today) -1. Create SECURITY.md with vulnerability disclosure policy -2. Adopt Contributor Covenant CODE_OF_CONDUCT.md -3. Add MAINTAINERS.md with current steward -4. Create .well-known/ directory with RFC 9116 security.txt - -### Short-term (This Week) -5. Add Justfile with common development tasks -6. Set up GitHub Actions for CI/CD -7. Designate TPCF perimeter (recommend: Perimeter 3 - Community Sandbox) -8. Add ai.txt and humans.txt - -### Medium-term (This Month) -9. Dual-license with Palimpsest v0.8 -10. Add flake.guix for reproducible builds -11. Complete WASM integration -12. Security audit and penetration testing - -## Notes - -**Strengths**: -- Excellent documentation foundation -- Strong type and memory safety (Rust + TypeScript) -- Comprehensive test coverage -- Modern build system - -**Areas for Improvement**: -- Security and vulnerability procedures -- Community governance -- RFC 9116 compliance -- Build reproducibility -- Automated CI/CD - -**Unique Considerations**: -- Browser extension context (special offline-first considerations) -- WASM bridge (requires special security attention) -- Privacy-focused tool (higher security bar) -- Experimental software (affects risk profile) - ---- - -**Next Steps**: Begin implementing missing components in priority order. diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..2a46cae --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,266 @@ +== Security Policy + +=== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Supported |Status +|0.1.x |:white_check_mark: |Active development +|< 0.1 |:x: |Pre-release, unsupported +|=== + +=== Security Model + +DoubleTrack Browser is *experimental privacy software* with specific +security considerations: + +==== Threat Model + +*In Scope*: - Privacy data leakage (real browsing data mixed with +simulated) - Storage injection attacks (malicious data in +chrome.storage) - WASM sandbox escapes - Content script injection +vulnerabilities - Extension permission abuse - Timing side-channels +revealing real vs. simulated activity + +*Out of Scope*: - Physical access attacks - Browser zero-days (rely on +browser vendor patches) - Social engineering of users - Cryptographic +attacks (we don’t use cryptography) + +==== Security Principles + +[arabic] +. *Data Separation*: Real and simulated browsing must NEVER mix +. *Local-Only*: No network calls, all data stays on device +. *Minimal Permissions*: Only request necessary browser APIs +. *Type Safety*: Rust + TypeScript strict mode prevent classes of bugs +. *Memory Safety*: Rust ownership model prevents memory corruption +. *Reversibility*: User can disable and clear all data instantly + +=== Reporting a Vulnerability + +==== Critical Vulnerabilities + +If you discover a vulnerability that could: - Leak real user browsing +data - Enable remote code execution - Bypass browser sandboxing - +Compromise user privacy + +*Please report IMMEDIATELY via*: + +*Email*: security@example.com (PGP key below) *Response Time*: Within 48 +hours *Coordinated Disclosure*: 90 days + +==== Non-Critical Issues + +For lower-severity issues: - Open a *private* GitHub Security Advisory - +Or email: security@example.com + +==== What to Include + +Please provide: 1. *Description*: What is the vulnerability? 2. +*Impact*: What can an attacker do? 3. *Reproduction*: Step-by-step PoC +4. *Environment*: Browser, OS, extension version 5. *Suggested Fix* +(optional): How to remediate + +==== Example Report Template + +.... +## Vulnerability Report + +**Title**: [Brief description] + +**Severity**: [Critical/High/Medium/Low] + +**Description**: +[Detailed explanation of the vulnerability] + +**Impact**: +- Privacy: [Yes/No - describe] +- Availability: [Yes/No - describe] +- Integrity: [Yes/No - describe] + +**Reproduction Steps**: +1. Install extension version X +2. Enable simulation with profile Y +3. Open developer console +4. Execute: [code/actions] +5. Observe: [vulnerability manifestation] + +**Environment**: +- Extension Version: 0.1.0 +- Browser: Chrome 120.0.6099.109 +- OS: Ubuntu 22.04 LTS + +**Suggested Fix** (optional): +[Your recommendation] + +**Disclosure Preference**: +- Public credit: [Yes/No] +- Name/handle: [If yes to credit] +.... + +=== Vulnerability Disclosure Process + +==== Timeline + +[arabic] +. *T+0 hours*: Report received, acknowledge within 48 hours +. *T+7 days*: Initial assessment and severity classification +. *T+14 days*: Patch development begins (or explanation if won’t fix) +. *T+30 days*: Patch testing and validation +. *T+60 days*: Coordinated release (or earlier if urgent) +. *T+90 days*: Public disclosure (or earlier if exploited in wild) + +==== Severity Classification + +[cols=",,",options="header",] +|=== +|Severity |SLA |Criteria +|*Critical* |7 days patch |RCE, data exfiltration, sandbox escape +|*High* |30 days patch |Privacy leak, privilege escalation +|*Medium* |60 days patch |DoS, logic errors, minor data exposure +|*Low* |90 days patch |UI spoofing, minor issues +|=== + +==== Remediation + +Depending on severity: - *Critical/High*: Emergency release + blog post ++ CVE - *Medium*: Regular release + changelog entry - *Low*: Bundled in +next release + +=== Security Testing + +==== Automated Testing + +We run: - *Cargo audit* for Rust dependency vulnerabilities - *npm +audit* for JavaScript dependency vulnerabilities - *TypeScript strict +mode* for type safety - *Rust borrow checker* for memory safety - +*ESLint security rules* for common JS vulnerabilities + +==== Manual Testing + +We encourage: - Code review of all changes - WASM sandbox boundary +audits - Storage injection testing - Permission escalation attempts + +==== Fuzzing (Future) + +Planned: - cargo-fuzz for Rust core - WASM boundary fuzzing - Storage +API fuzzing + +=== Known Issues & Limitations + +==== Current Limitations (v0.1.0) + +[arabic] +. *WASM Integration Incomplete*: Mock implementations in use +* *Risk*: Type mismatches could cause runtime errors +* *Mitigation*: TypeScript strict mode, extensive testing +* *Timeline*: Full integration by v0.2.0 +. *No Rate Limiting*: Simulated activities could be excessive +* *Risk*: Resource exhaustion, browser slowdown +* *Mitigation*: User-configurable noise levels, activity caps +* *Timeline*: Rate limiting in v0.3.0 +. *Experimental Software*: Not security-audited by third party +* *Risk*: Unknown vulnerabilities may exist +* *Mitigation*: Open source for community review +* *Timeline*: Professional audit planned for v1.0.0 + +==== Design Decisions + +*Why no encryption?* - All data is local-only - Browser already provides +storage encryption - Adding crypto increases attack surface - KISS +principle + +*Why TypeScript instead of Rust for extension?* - Browser APIs are +JavaScript-native - WASM has limitations with async Chrome APIs - +TypeScript provides sufficient type safety - Performance not critical +for UI + +*Why allow activity simulation at all?* - Core feature of the extension +- User explicitly enables it - Activities are sandboxed (no actual tab +opening by default) - Reversible (can clear all data) + +=== Security Features + +==== Data Protection + +* *Storage Isolation*: chrome.storage.local (per-extension isolation) +* *No External Calls*: Zero network requests, fully offline +* *Type Safety*: Rust + TypeScript prevent injection +* *Memory Safety*: Rust ownership prevents corruption + +==== Runtime Protection + +* *Content Security Policy*: Restrictive CSP in manifest +* *Sandboxed WASM*: No direct system access +* *Permission Minimization*: Only required APIs +* *User Consent*: Explicit enable required + +==== Auditability + +* *Open Source*: All code public on GitHub +* *Reproducible Builds*: Deterministic compilation (planned) +* *Signed Releases*: GPG signatures (planned) +* *Build Provenance*: SLSA attestation (planned) + +=== Security Resources + +==== For Users + +* link:docs/PRIVACY.md[Privacy Policy] (TODO) +* link:docs/USER_SECURITY.md[User Security Guide] (TODO) +* link:README.md#faq[FAQ] + +==== For Developers + +* link:CONTRIBUTING.md#security[Secure Coding Guidelines] +* link:docs/THREAT_MODEL.md[Threat Model] (TODO) +* link:docs/ARCHITECTURE.md[Security Architecture] (TODO) + +==== External Resources + +* https://cheatsheetseries.owasp.org/cheatsheets/Browser_Extension_Security_Cheat_Sheet.html[OWASP +Browser Extension Security] +* https://developer.chrome.com/docs/extensions/mv3/security/[Chrome +Extension Security Best Practices] +* https://webassembly.org/docs/security/[WebAssembly Security] + +=== PGP Key + +.... +-----BEGIN PGP PUBLIC KEY BLOCK----- +Comment: DoubleTrack Browser Security Team +Comment: security@example.com + +[TODO: Add actual PGP public key] + +-----END PGP PUBLIC KEY BLOCK----- +.... + +=== Hall of Fame + +We gratefully acknowledge security researchers who responsibly disclose +vulnerabilities: + +[cols=",,,,",options="header",] +|=== +|Researcher |Vulnerability |Severity |Date |Bounty +|_None yet_ |- |- |- |- +|=== + +*Note*: We currently do not offer monetary bounties but will provide: - +Public credit (if desired) - Acknowledgment in release notes - +Co-authorship credit for significant findings - Eternal gratitude and +good karma + +=== Contact + +* *Security Email*: security@example.com +* *GPG Fingerprint*: [TODO] +* *Security Advisory*: +https://github.com/yourusername/double-track-browser/security/advisories +* *Response SLA*: 48 hours + +''''' + +*Last Updated*: 2025-11-22 *Version*: 1.0 *Next Review*: 2026-05-22 (6 +months) diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 8994dcd..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,279 +0,0 @@ -# Security Policy - -## Supported Versions - -| Version | Supported | Status | -| ------- | ------------------ | ------ | -| 0.1.x | :white_check_mark: | Active development | -| < 0.1 | :x: | Pre-release, unsupported | - -## Security Model - -DoubleTrack Browser is **experimental privacy software** with specific security considerations: - -### Threat Model - -**In Scope**: -- Privacy data leakage (real browsing data mixed with simulated) -- Storage injection attacks (malicious data in chrome.storage) -- WASM sandbox escapes -- Content script injection vulnerabilities -- Extension permission abuse -- Timing side-channels revealing real vs. simulated activity - -**Out of Scope**: -- Physical access attacks -- Browser zero-days (rely on browser vendor patches) -- Social engineering of users -- Cryptographic attacks (we don't use cryptography) - -### Security Principles - -1. **Data Separation**: Real and simulated browsing must NEVER mix -2. **Local-Only**: No network calls, all data stays on device -3. **Minimal Permissions**: Only request necessary browser APIs -4. **Type Safety**: Rust + TypeScript strict mode prevent classes of bugs -5. **Memory Safety**: Rust ownership model prevents memory corruption -6. **Reversibility**: User can disable and clear all data instantly - -## Reporting a Vulnerability - -### Critical Vulnerabilities - -If you discover a vulnerability that could: -- Leak real user browsing data -- Enable remote code execution -- Bypass browser sandboxing -- Compromise user privacy - -**Please report IMMEDIATELY via**: - -**Email**: security@example.com (PGP key below) -**Response Time**: Within 48 hours -**Coordinated Disclosure**: 90 days - -### Non-Critical Issues - -For lower-severity issues: -- Open a **private** GitHub Security Advisory -- Or email: security@example.com - -### What to Include - -Please provide: -1. **Description**: What is the vulnerability? -2. **Impact**: What can an attacker do? -3. **Reproduction**: Step-by-step PoC -4. **Environment**: Browser, OS, extension version -5. **Suggested Fix** (optional): How to remediate - -### Example Report Template - -``` -## Vulnerability Report - -**Title**: [Brief description] - -**Severity**: [Critical/High/Medium/Low] - -**Description**: -[Detailed explanation of the vulnerability] - -**Impact**: -- Privacy: [Yes/No - describe] -- Availability: [Yes/No - describe] -- Integrity: [Yes/No - describe] - -**Reproduction Steps**: -1. Install extension version X -2. Enable simulation with profile Y -3. Open developer console -4. Execute: [code/actions] -5. Observe: [vulnerability manifestation] - -**Environment**: -- Extension Version: 0.1.0 -- Browser: Chrome 120.0.6099.109 -- OS: Ubuntu 22.04 LTS - -**Suggested Fix** (optional): -[Your recommendation] - -**Disclosure Preference**: -- Public credit: [Yes/No] -- Name/handle: [If yes to credit] -``` - -## Vulnerability Disclosure Process - -### Timeline - -1. **T+0 hours**: Report received, acknowledge within 48 hours -2. **T+7 days**: Initial assessment and severity classification -3. **T+14 days**: Patch development begins (or explanation if won't fix) -4. **T+30 days**: Patch testing and validation -5. **T+60 days**: Coordinated release (or earlier if urgent) -6. **T+90 days**: Public disclosure (or earlier if exploited in wild) - -### Severity Classification - -| Severity | SLA | Criteria | -|----------|-----|----------| -| **Critical** | 7 days patch | RCE, data exfiltration, sandbox escape | -| **High** | 30 days patch | Privacy leak, privilege escalation | -| **Medium** | 60 days patch | DoS, logic errors, minor data exposure | -| **Low** | 90 days patch | UI spoofing, minor issues | - -### Remediation - -Depending on severity: -- **Critical/High**: Emergency release + blog post + CVE -- **Medium**: Regular release + changelog entry -- **Low**: Bundled in next release - -## Security Testing - -### Automated Testing - -We run: -- **Cargo audit** for Rust dependency vulnerabilities -- **npm audit** for JavaScript dependency vulnerabilities -- **TypeScript strict mode** for type safety -- **Rust borrow checker** for memory safety -- **ESLint security rules** for common JS vulnerabilities - -### Manual Testing - -We encourage: -- Code review of all changes -- WASM sandbox boundary audits -- Storage injection testing -- Permission escalation attempts - -### Fuzzing (Future) - -Planned: -- cargo-fuzz for Rust core -- WASM boundary fuzzing -- Storage API fuzzing - -## Known Issues & Limitations - -### Current Limitations (v0.1.0) - -1. **WASM Integration Incomplete**: Mock implementations in use - - **Risk**: Type mismatches could cause runtime errors - - **Mitigation**: TypeScript strict mode, extensive testing - - **Timeline**: Full integration by v0.2.0 - -2. **No Rate Limiting**: Simulated activities could be excessive - - **Risk**: Resource exhaustion, browser slowdown - - **Mitigation**: User-configurable noise levels, activity caps - - **Timeline**: Rate limiting in v0.3.0 - -3. **Experimental Software**: Not security-audited by third party - - **Risk**: Unknown vulnerabilities may exist - - **Mitigation**: Open source for community review - - **Timeline**: Professional audit planned for v1.0.0 - -### Design Decisions - -**Why no encryption?** -- All data is local-only -- Browser already provides storage encryption -- Adding crypto increases attack surface -- KISS principle - -**Why TypeScript instead of Rust for extension?** -- Browser APIs are JavaScript-native -- WASM has limitations with async Chrome APIs -- TypeScript provides sufficient type safety -- Performance not critical for UI - -**Why allow activity simulation at all?** -- Core feature of the extension -- User explicitly enables it -- Activities are sandboxed (no actual tab opening by default) -- Reversible (can clear all data) - -## Security Features - -### Data Protection - -- **Storage Isolation**: chrome.storage.local (per-extension isolation) -- **No External Calls**: Zero network requests, fully offline -- **Type Safety**: Rust + TypeScript prevent injection -- **Memory Safety**: Rust ownership prevents corruption - -### Runtime Protection - -- **Content Security Policy**: Restrictive CSP in manifest -- **Sandboxed WASM**: No direct system access -- **Permission Minimization**: Only required APIs -- **User Consent**: Explicit enable required - -### Auditability - -- **Open Source**: All code public on GitHub -- **Reproducible Builds**: Deterministic compilation (planned) -- **Signed Releases**: GPG signatures (planned) -- **Build Provenance**: SLSA attestation (planned) - -## Security Resources - -### For Users - -- [Privacy Policy](docs/PRIVACY.md) (TODO) -- [User Security Guide](docs/USER_SECURITY.md) (TODO) -- [FAQ](README.md#faq) - -### For Developers - -- [Secure Coding Guidelines](CONTRIBUTING.md#security) -- [Threat Model](docs/THREAT_MODEL.md) (TODO) -- [Security Architecture](docs/ARCHITECTURE.md) (TODO) - -### External Resources - -- [OWASP Browser Extension Security](https://cheatsheetseries.owasp.org/cheatsheets/Browser_Extension_Security_Cheat_Sheet.html) -- [Chrome Extension Security Best Practices](https://developer.chrome.com/docs/extensions/mv3/security/) -- [WebAssembly Security](https://webassembly.org/docs/security/) - -## PGP Key - -``` ------BEGIN PGP PUBLIC KEY BLOCK----- -Comment: DoubleTrack Browser Security Team -Comment: security@example.com - -[TODO: Add actual PGP public key] - ------END PGP PUBLIC KEY BLOCK----- -``` - -## Hall of Fame - -We gratefully acknowledge security researchers who responsibly disclose vulnerabilities: - -| Researcher | Vulnerability | Severity | Date | Bounty | -|------------|---------------|----------|------|--------| -| *None yet* | - | - | - | - | - -**Note**: We currently do not offer monetary bounties but will provide: -- Public credit (if desired) -- Acknowledgment in release notes -- Co-authorship credit for significant findings -- Eternal gratitude and good karma - -## Contact - -- **Security Email**: security@example.com -- **GPG Fingerprint**: [TODO] -- **Security Advisory**: https://github.com/yourusername/double-track-browser/security/advisories -- **Response SLA**: 48 hours - ---- - -**Last Updated**: 2025-11-22 -**Version**: 1.0 -**Next Review**: 2026-05-22 (6 months) diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..29f0f71 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,201 @@ +== CRG C - Comprehensive Test Coverage + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Status: ACHIEVED + +This document tracks the completion of CRG C grade requirements for +`+double-track-browser+`. + +=== CRG C Requirements + +CRG C requires: - Unit tests (12 existing + inline tests) - Smoke tests +(property-based) - Build tests (cargo test) - P2P (property-based) tests +- E2E (end-to-end) tests - Reflexive tests (not applicable for this +project type) - Contract tests (type contracts in TypeScript) - Aspect +tests (security) - Benchmarks with baselines + +=== Test Coverage Summary + +==== Rust Core (rust_core/) + +===== Unit Tests (12 existing) + +* ✅ `+src/lib.rs::tests+` - Profile generation (1 test) +* ✅ `+src/lib.rs::tests+` - Activity generation (1 test) +* ✅ `+src/activity.rs::tests+` - Activity generation (1 test) +* ✅ `+src/activity.rs::tests+` - Duration generation (1 test) +* ✅ `+src/form_data.rs::tests+` - FormData generation (1 test) +* ✅ `+src/form_data.rs::tests+` - Email format (1 test) +* ✅ `+src/form_data.rs::tests+` - Preferences matching (1 test) +* ✅ `+src/schedule.rs::tests+` - Schedule generation (1 test) +* ✅ `+src/schedule.rs::tests+` - Hour in range (1 test) +* ✅ `+src/interests.rs::tests+` - Search query diversity (1 test) +* ✅ `+src/interests.rs::tests+` - URL generation all types (1 test) + +*Pass rate: 11/11 ✅* + +===== Property-Based Tests (proptest) + +File: `+tests/property_test.rs+` (11 tests) - ✅ Profile names never +empty - ✅ Profile ages in valid range [18, 100] - ✅ Interests list +bounds [1, 20] - ✅ Activity log chronologically ordered - ✅ Activity +durations positive and bounded - ✅ FormData emails always valid format +- ✅ FormData display names never empty - ✅ Generated profiles always +valid - ✅ Schedule has exactly 7 days - ✅ No null bytes in FormData +fields - ✅ Profile IDs valid and unique + +*Pass rate: 11/11 ✅* + +===== End-to-End Tests + +File: `+tests/e2e_test.rs+` (8 tests) - ✅ Full profile lifecycle +(create → serialize → deserialize → validate) - ✅ Profile → Activities +→ FormData pipeline - ✅ Profile schedule consistency - ✅ Activity +stream properties (HTTPS, titles, durations, span) - ✅ FormData email +uniqueness across profiles - ✅ FormData serialization round-trip - ✅ +Activity type distribution - ✅ Large activity generation (1 week, 100+ +activities) + +*Pass rate: 8/8 ✅* + +===== Security/Aspect Tests + +File: `+tests/aspect_test.rs+` (12 tests) - ✅ Oversized input handling +(100KB strings) - ✅ Unicode in profile fields (Spanish, Chinese, Greek, +Emoji) - ✅ XSS payload handling in URLs - ✅ SQL injection patterns in +FormData - ✅ Empty input handling - ✅ Timestamp validity (within 1 +minute) - ✅ Activity timestamp validity (within 2 days) - ✅ Integer +overflow protection - ✅ Activity list consistency - ✅ FormData field +lengths < 255 chars - ✅ No unsafe patterns (null bytes, control chars) +- ✅ Boundary values for activity duration + +*Pass rate: 12/12 ✅* + +==== Browser Extension (TypeScript/Deno) + +===== Unit Type Tests + +File: `+tests/unit/types_test.ts+` (4 tests) - ✅ Extension message +types - ✅ Storage schema validation - ✅ Form data contract - ✅ +Activity log schema + +*Pass rate: 4/4 ✅* + +===== Property-Based Tests + +File: `+tests/property/extension_properties_test.ts+` (9 tests) - ✅ +Profiles never have empty names - ✅ Activities always have HTTPS URLs - +✅ Timestamps are monotonic - ✅ Email format is valid - ✅ No null +bytes in strings - ✅ Message type always defined - ✅ Duration is +always positive - ✅ Interests array never empty - ✅ Activity type is +known + +*Pass rate: 9/9 ✅* + +===== End-to-End Extension Lifecycle + +File: `+tests/e2e/extension_lifecycle_test.ts+` (9 tests) - ✅ Extension +initialization - ✅ Profile creation - ✅ Activity generation - ✅ +Activity accumulation - ✅ Pause and resume - ✅ Configuration +persistence - ✅ Cleanup on uninstall - ✅ State serialization - ✅ +Profile switching + +*Pass rate: 9/9 ✅* + +===== Security Aspect Tests + +File: `+tests/aspect/security_test.ts+` (10 tests) - ✅ XSS prevention +in URL display - ✅ Content isolation (sandboxing) - ✅ HTTPS +enforcement - ✅ Message validation - ✅ Origin verification - ✅ No +plain HTTP for sensitive operations - ✅ No sensitive data in logs - ✅ +CSP headers enforcement - ✅ Timestamp validation - ✅ Permission +boundaries + +*Pass rate: 10/10 ✅* + +=== Test Summary + +[width="100%",cols="36%,24%,20%,20%",options="header",] +|=== +|Category |Tests |Pass |File +|Rust Unit |11 |11 |src/**/*.rs +|Rust Property |11 |11 |tests/property_test.rs +|Rust E2E |8 |8 |tests/e2e_test.rs +|Rust Aspect |12 |12 |tests/aspect_test.rs +|TypeScript Unit |4 |4 |tests/unit/types_test.ts +|TypeScript Property |9 |9 |tests/property/extension_properties_test.ts +|TypeScript E2E |9 |9 |tests/e2e/extension_lifecycle_test.ts +|TypeScript Aspect |10 |10 |tests/aspect/security_test.ts +|*TOTAL* |*74* |*74* |— +|=== + +*Overall Pass Rate: 100% (74/74 ✅)* + +=== Benchmarks + +==== Criterion Benchmarks (rust_core/benches/core_bench.rs) + +The following benchmark suites have been configured and are ready to +run: + +* `+profile_generation_with_seed+` - Profile generation performance with +deterministic seed +* `+profile_generation_random+` - Profile generation with random entropy +* `+profile_to_json+` - Serialization throughput +* `+json_to_profile+` - Deserialization throughput +* `+activity_generation+` - Activity generation for 1h, 24h, 72h +durations +* `+activity_scaling+` - Scaling benchmark for 100, 1000, 10000 activity +targets +* `+formdata_generation+` - Form data generation performance +* `+schedule_generation+` - Schedule creation performance +* `+profile_validation+` - Profile validation throughput +* `+activity_type_variety+` - Activity diversity generation (1h, 12h, +24h) +* `+full_pipeline+` - End-to-end pipeline (profile + activities + form + +schedule + serialize) + +*Run with:* `+cargo bench --manifest-path rust_core/Cargo.toml+` + +=== Code Quality + +==== Language Policy Compliance + +* ✅ Rust for core (WASM-compiled) +* ✅ AffineScript for browser (type-safe, compiles to JS) +* ✅ Deno for testing (no npm) +* ✅ MPL-2.0 license headers on all files +* ✅ No TypeScript (uses AffineScript) +* ✅ No Node.js (uses Deno) + +==== Test Characteristics + +* ✅ No panics or unwraps without context +* ✅ Property-based invariant testing +* ✅ End-to-end pipeline validation +* ✅ Security aspect coverage (XSS, SQL injection, overflow, etc.) +* ✅ Type contract enforcement +* ✅ Serialization round-trip validation +* ✅ Deterministic seeding for reproducibility + +=== Smoke Tests Passing + +Run with: `+deno task test+` (TypeScript) + `+cargo test+` (Rust) + +All tests pass without warnings (except one unused variable warning +which is acceptable). + +=== CRG Grade: C + +✅ *All CRG C requirements satisfied:* - Unit tests: 15 (11 existing + 4 +new) - Smoke tests: 24 property-based tests - Build tests: Cargo build +integration - P2P tests: 11 proptest + 9 TypeScript property tests - E2E +tests: 8 Rust + 9 TypeScript (17 total) - Contract tests: 4 TypeScript +unit + 9 property tests - Aspect tests: 12 Rust security + 10 TypeScript +security (22 total) - Benchmarks: 11 criterion benchmarks configured and +ready + +*Next Steps for Higher Grades:* - *CRG B*: Add fuzzing harness +(fuzz/fuzzer.rs), stress tests, mutation testing - *CRG A*: Add formal +proofs (Idris2 ABI verification), adversarial testing, security audit diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 8a103ce..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,216 +0,0 @@ -# CRG C - Comprehensive Test Coverage - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Status: ACHIEVED - -This document tracks the completion of CRG C grade requirements for `double-track-browser`. - -## CRG C Requirements - -CRG C requires: -- Unit tests (12 existing + inline tests) -- Smoke tests (property-based) -- Build tests (cargo test) -- P2P (property-based) tests -- E2E (end-to-end) tests -- Reflexive tests (not applicable for this project type) -- Contract tests (type contracts in TypeScript) -- Aspect tests (security) -- Benchmarks with baselines - -## Test Coverage Summary - -### Rust Core (rust_core/) - -#### Unit Tests (12 existing) -- ✅ `src/lib.rs::tests` - Profile generation (1 test) -- ✅ `src/lib.rs::tests` - Activity generation (1 test) -- ✅ `src/activity.rs::tests` - Activity generation (1 test) -- ✅ `src/activity.rs::tests` - Duration generation (1 test) -- ✅ `src/form_data.rs::tests` - FormData generation (1 test) -- ✅ `src/form_data.rs::tests` - Email format (1 test) -- ✅ `src/form_data.rs::tests` - Preferences matching (1 test) -- ✅ `src/schedule.rs::tests` - Schedule generation (1 test) -- ✅ `src/schedule.rs::tests` - Hour in range (1 test) -- ✅ `src/interests.rs::tests` - Search query diversity (1 test) -- ✅ `src/interests.rs::tests` - URL generation all types (1 test) - -**Pass rate: 11/11 ✅** - -#### Property-Based Tests (proptest) -File: `tests/property_test.rs` (11 tests) -- ✅ Profile names never empty -- ✅ Profile ages in valid range [18, 100] -- ✅ Interests list bounds [1, 20] -- ✅ Activity log chronologically ordered -- ✅ Activity durations positive and bounded -- ✅ FormData emails always valid format -- ✅ FormData display names never empty -- ✅ Generated profiles always valid -- ✅ Schedule has exactly 7 days -- ✅ No null bytes in FormData fields -- ✅ Profile IDs valid and unique - -**Pass rate: 11/11 ✅** - -#### End-to-End Tests -File: `tests/e2e_test.rs` (8 tests) -- ✅ Full profile lifecycle (create → serialize → deserialize → validate) -- ✅ Profile → Activities → FormData pipeline -- ✅ Profile schedule consistency -- ✅ Activity stream properties (HTTPS, titles, durations, span) -- ✅ FormData email uniqueness across profiles -- ✅ FormData serialization round-trip -- ✅ Activity type distribution -- ✅ Large activity generation (1 week, 100+ activities) - -**Pass rate: 8/8 ✅** - -#### Security/Aspect Tests -File: `tests/aspect_test.rs` (12 tests) -- ✅ Oversized input handling (100KB strings) -- ✅ Unicode in profile fields (Spanish, Chinese, Greek, Emoji) -- ✅ XSS payload handling in URLs -- ✅ SQL injection patterns in FormData -- ✅ Empty input handling -- ✅ Timestamp validity (within 1 minute) -- ✅ Activity timestamp validity (within 2 days) -- ✅ Integer overflow protection -- ✅ Activity list consistency -- ✅ FormData field lengths < 255 chars -- ✅ No unsafe patterns (null bytes, control chars) -- ✅ Boundary values for activity duration - -**Pass rate: 12/12 ✅** - -### Browser Extension (TypeScript/Deno) - -#### Unit Type Tests -File: `tests/unit/types_test.ts` (4 tests) -- ✅ Extension message types -- ✅ Storage schema validation -- ✅ Form data contract -- ✅ Activity log schema - -**Pass rate: 4/4 ✅** - -#### Property-Based Tests -File: `tests/property/extension_properties_test.ts` (9 tests) -- ✅ Profiles never have empty names -- ✅ Activities always have HTTPS URLs -- ✅ Timestamps are monotonic -- ✅ Email format is valid -- ✅ No null bytes in strings -- ✅ Message type always defined -- ✅ Duration is always positive -- ✅ Interests array never empty -- ✅ Activity type is known - -**Pass rate: 9/9 ✅** - -#### End-to-End Extension Lifecycle -File: `tests/e2e/extension_lifecycle_test.ts` (9 tests) -- ✅ Extension initialization -- ✅ Profile creation -- ✅ Activity generation -- ✅ Activity accumulation -- ✅ Pause and resume -- ✅ Configuration persistence -- ✅ Cleanup on uninstall -- ✅ State serialization -- ✅ Profile switching - -**Pass rate: 9/9 ✅** - -#### Security Aspect Tests -File: `tests/aspect/security_test.ts` (10 tests) -- ✅ XSS prevention in URL display -- ✅ Content isolation (sandboxing) -- ✅ HTTPS enforcement -- ✅ Message validation -- ✅ Origin verification -- ✅ No plain HTTP for sensitive operations -- ✅ No sensitive data in logs -- ✅ CSP headers enforcement -- ✅ Timestamp validation -- ✅ Permission boundaries - -**Pass rate: 10/10 ✅** - -## Test Summary - -| Category | Tests | Pass | File | -|----------|-------|------|------| -| Rust Unit | 11 | 11 | src/**/*.rs | -| Rust Property | 11 | 11 | tests/property_test.rs | -| Rust E2E | 8 | 8 | tests/e2e_test.rs | -| Rust Aspect | 12 | 12 | tests/aspect_test.rs | -| TypeScript Unit | 4 | 4 | tests/unit/types_test.ts | -| TypeScript Property | 9 | 9 | tests/property/extension_properties_test.ts | -| TypeScript E2E | 9 | 9 | tests/e2e/extension_lifecycle_test.ts | -| TypeScript Aspect | 10 | 10 | tests/aspect/security_test.ts | -| **TOTAL** | **74** | **74** | — | - -**Overall Pass Rate: 100% (74/74 ✅)** - -## Benchmarks - -### Criterion Benchmarks (rust_core/benches/core_bench.rs) - -The following benchmark suites have been configured and are ready to run: - -- `profile_generation_with_seed` - Profile generation performance with deterministic seed -- `profile_generation_random` - Profile generation with random entropy -- `profile_to_json` - Serialization throughput -- `json_to_profile` - Deserialization throughput -- `activity_generation` - Activity generation for 1h, 24h, 72h durations -- `activity_scaling` - Scaling benchmark for 100, 1000, 10000 activity targets -- `formdata_generation` - Form data generation performance -- `schedule_generation` - Schedule creation performance -- `profile_validation` - Profile validation throughput -- `activity_type_variety` - Activity diversity generation (1h, 12h, 24h) -- `full_pipeline` - End-to-end pipeline (profile + activities + form + schedule + serialize) - -**Run with:** `cargo bench --manifest-path rust_core/Cargo.toml` - -## Code Quality - -### Language Policy Compliance -- ✅ Rust for core (WASM-compiled) -- ✅ AffineScript for browser (type-safe, compiles to JS) -- ✅ Deno for testing (no npm) -- ✅ MPL-2.0 license headers on all files -- ✅ No TypeScript (uses AffineScript) -- ✅ No Node.js (uses Deno) - -### Test Characteristics -- ✅ No panics or unwraps without context -- ✅ Property-based invariant testing -- ✅ End-to-end pipeline validation -- ✅ Security aspect coverage (XSS, SQL injection, overflow, etc.) -- ✅ Type contract enforcement -- ✅ Serialization round-trip validation -- ✅ Deterministic seeding for reproducibility - -## Smoke Tests Passing - -Run with: `deno task test` (TypeScript) + `cargo test` (Rust) - -All tests pass without warnings (except one unused variable warning which is acceptable). - -## CRG Grade: C - -✅ **All CRG C requirements satisfied:** -- Unit tests: 15 (11 existing + 4 new) -- Smoke tests: 24 property-based tests -- Build tests: Cargo build integration -- P2P tests: 11 proptest + 9 TypeScript property tests -- E2E tests: 8 Rust + 9 TypeScript (17 total) -- Contract tests: 4 TypeScript unit + 9 property tests -- Aspect tests: 12 Rust security + 10 TypeScript security (22 total) -- Benchmarks: 11 criterion benchmarks configured and ready - -**Next Steps for Higher Grades:** -- **CRG B**: Add fuzzing harness (fuzz/fuzzer.rs), stress tests, mutation testing -- **CRG A**: Add formal proofs (Idris2 ABI verification), adversarial testing, security audit diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 88% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index c7f009c..9140904 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== DoubleTrack Browser — Project Topology -# DoubleTrack Browser — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ USER / BROWSER │ │ (Real & Fictional Personas) │ @@ -42,11 +38,11 @@ │ Deno Tooling .machine_readable/ │ │ wasm-pack RSR Gold (91%) │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── IDENTITY ENGINE (RUST) @@ -66,25 +62,26 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: █████████░ ~90% v0.1.0 RSR Gold Compliant -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Profile Gen ──────► Simulator ──────► Background Script ──────► Browser API │ │ │ │ ▼ ▼ ▼ ▼ Rust Core ──────► WASM Bridge ──────► AffineScript UI ─────────► User Dashboard -``` +.... -## Update Protocol +=== Update Protocol This file is maintained by both humans and AI agents. When updating: -1. **After completing a component**: Change its bar and percentage -2. **After adding a component**: Add a new row in the appropriate section -3. **After architectural changes**: Update the ASCII diagram -4. **Date**: Update the `Last updated` comment at the top of this file +[arabic] +. *After completing a component*: Change its bar and percentage +. *After adding a component*: Add a new row in the appropriate section +. *After architectural changes*: Update the ASCII diagram +. *Date*: Update the `+Last updated+` comment at the top of this file -Progress bars use: `█` (filled) and `░` (empty), 10 characters wide. -Percentages: 0%, 10%, 20%, ... 100% (in 10% increments). +Progress bars use: `+█+` (filled) and `+░+` (empty), 10 characters wide. +Percentages: 0%, 10%, 20%, … 100% (in 10% increments). diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..a6d1d30 --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,71 @@ +== Tech-Debt Audit — double-track-browser — 2026-05-26 + +*Source:* estate-wide automated scan 2026-05-26. *Companion:* +https://github.com/hyperpolymath/standards/tree/main/docs/audits[`+hyperpolymath/standards+` +2026-05-26-estate-*-debt audits]. *Combined severity:* `+MEDIUM+`. + +This file records the _raw findings_ — it does not by itself fix the +debt. Each section ends with a '`Recommended next move`' line; closing +the debt is follow-up work. + +=== 1. Proof debt + +No proof-bearing files (`+*.v+`, `+*.lean+`, `+*.agda+`, `+*.idr+`, +`+*.idr2+`, `+*.fst+`, `+*.dfy+`, `+*.tla+`, `+*.ads+`, `+*.adb+`) found +in this repo. + +*Recommended next move:* none. + +=== 2. Licence debt + +[cols=",",options="header",] +|=== +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+MPL-2.0+` +|Manifest licence |`+NONE+` +|Body classifier |`+Palimp-MPL-2.0+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |233 +|`+docs/+` files |2 +|`+docs/+` LoC |627 +|CHANGELOG.md |N +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+MEDIUM+` +|=== + +*Recommended next move:* introduce a `+docs/+` directory. The README at +233 lines has likely grown to do the work of `+docs/+` — split it into a +thin README + `+docs/architecture.md+`, `+docs/usage.md+`, etc. +Heavy-wiki exemplars to copy from: `+affinescript+`, `+boj-server+`, +`+echidna+`, `+hypatia+`. + +Additionally: *CHANGELOG.md is missing.* 65% of estate repos lack one — +adopting a CHANGELOG (or auto-generating via `+git-cliff+`) is a +recommended estate-wide follow-up. + +=== Cross-references + +* Estate proof-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md+` +* Estate licence-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md+` +* Estate documentation-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md+` + +''''' + +🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). +This file is informational — closing the debt is follow-up work owned by +the maintainer. diff --git a/docs/tech-debt-2026-05-26.md b/docs/tech-debt-2026-05-26.md deleted file mode 100644 index 00ea160..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Tech-Debt Audit — double-track-browser — 2026-05-26 - -**Source:** estate-wide automated scan 2026-05-26. -**Companion:** [`hyperpolymath/standards` 2026-05-26-estate-*-debt audits](https://github.com/hyperpolymath/standards/tree/main/docs/audits). -**Combined severity:** `MEDIUM`. - -This file records the *raw findings* — it does not by itself fix the debt. Each section ends with a 'Recommended next move' line; closing the debt is follow-up work. - -## 1. Proof debt - -No proof-bearing files (`*.v`, `*.lean`, `*.agda`, `*.idr`, `*.idr2`, `*.fst`, `*.dfy`, `*.tla`, `*.ads`, `*.adb`) found in this repo. - -**Recommended next move:** none. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `MPL-2.0` | -| Manifest licence | `NONE` | -| Body classifier | `Palimp-MPL-2.0` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 233 | -| `docs/` files | 2 | -| `docs/` LoC | 627 | -| CHANGELOG.md | N | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `MEDIUM` | - -**Recommended next move:** introduce a `docs/` directory. The README at 233 lines has likely grown to do the work of `docs/` — split it into a thin README + `docs/architecture.md`, `docs/usage.md`, etc. Heavy-wiki exemplars to copy from: `affinescript`, `boj-server`, `echidna`, `hypatia`. - -Additionally: **CHANGELOG.md is missing.** 65% of estate repos lack one — adopting a CHANGELOG (or auto-generating via `git-cliff`) is a recommended estate-wide follow-up. - -## Cross-references - -- Estate proof-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md` -- Estate licence-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md` -- Estate documentation-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md` - ---- - -🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). This file is informational — closing the debt is follow-up work owned by the maintainer. diff --git a/icons/README.adoc b/icons/README.adoc new file mode 100644 index 0000000..d131efb --- /dev/null +++ b/icons/README.adoc @@ -0,0 +1,29 @@ +== Extension Icons + +This directory contains the icon assets for DoubleTrack Browser. + +=== Required Sizes + +The extension requires icons in the following sizes: - 16x16 - Toolbar +icon - 32x32 - Toolbar icon (retina) - 48x48 - Extension management page +- 128x128 - Chrome Web Store + +=== Creating Icons + +To create proper icons, use a tool like: - Figma - Adobe Illustrator - +Inkscape (free) + +Design guidelines: - Use a simple, recognizable symbol - Consider a +"`double track`" or "`parallel lines`" motif - Colors should work well +on light and dark backgrounds - Maintain good contrast for visibility + +=== Placeholder Icons + +Currently using placeholder icons. Replace these with proper designed +icons before release. + +=== Icon Theme + +Suggested theme: Two parallel paths or tracks, representing the dual +nature of browsing (real + fictional). Colors could include blues and +purples matching the extension’s UI theme. diff --git a/icons/README.md b/icons/README.md deleted file mode 100644 index 98e57e7..0000000 --- a/icons/README.md +++ /dev/null @@ -1,32 +0,0 @@ -# Extension Icons - -This directory contains the icon assets for DoubleTrack Browser. - -## Required Sizes - -The extension requires icons in the following sizes: -- 16x16 - Toolbar icon -- 32x32 - Toolbar icon (retina) -- 48x48 - Extension management page -- 128x128 - Chrome Web Store - -## Creating Icons - -To create proper icons, use a tool like: -- Figma -- Adobe Illustrator -- Inkscape (free) - -Design guidelines: -- Use a simple, recognizable symbol -- Consider a "double track" or "parallel lines" motif -- Colors should work well on light and dark backgrounds -- Maintain good contrast for visibility - -## Placeholder Icons - -Currently using placeholder icons. Replace these with proper designed icons before release. - -## Icon Theme - -Suggested theme: Two parallel paths or tracks, representing the dual nature of browsing (real + fictional). Colors could include blues and purples matching the extension's UI theme. diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..c875065 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — double-track-browser (Developer) + +=== What is double-track-browser? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-dev.md b/llm-warmup-dev.md deleted file mode 100644 index e0084f1..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — double-track-browser (Developer) - -## What is double-track-browser? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.adoc b/llm-warmup-user.adoc new file mode 100644 index 0000000..0f87eab --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — double-track-browser (User) + +=== What is double-track-browser? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.md b/llm-warmup-user.md deleted file mode 100644 index fac9ab9..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — double-track-browser (User) - -## What is double-track-browser? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture