From 5ac729cf8964799ab310011ccce5743fb3cb6026 Mon Sep 17 00:00:00 2001 From: hyperpolymath Date: Sun, 17 May 2026 01:29:21 +0100 Subject: [PATCH] chore(Item 11): drop duplicate .md docs (RSR-canonical .adoc retained) Dedupe: keep RSR-canonical .adoc, drop verified-faithful .md duplicate. Day 10 / Item 11. Inbound links repointed to .adoc where applicable. Co-Authored-By: Claude Opus 4.7 --- CHANGELOG.md | 496 --------------------------------------------------- 1 file changed, 496 deletions(-) delete mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index b3d49a0..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,496 +0,0 @@ -# Changelog - -All notable changes to UbiCity 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). - -## [0.2.0] - 2025-01-22 - -### Added - -**Core Infrastructure** -- ESM module support (`type: "module"` in package.json) -- Zod schemas for runtime validation with detailed error messages -- Async/await API throughout (replaces blocking sync I/O) -- Dedicated storage abstraction layer (`ExperienceStorage`) -- Comprehensive test suite (14 tests, all passing) -- GitHub Actions CI/CD pipeline (tests on Node 18/20/22) - -**New Modules** -- `src/schemas.js` - Zod validation for all data types -- `src/storage.js` - Async file operations -- `src/cli.js` - Proper CLI with argument parsing -- `src/export.js` - Export to CSV, GeoJSON, DOT, Markdown -- `src/privacy.js` - Anonymization and PII removal tools - -**Export Formats** -- CSV export for spreadsheet analysis -- GeoJSON export for mapping tools (Mapbox, Leaflet, QGIS) -- Graphviz DOT format for domain network visualization -- Markdown export for readable learner journeys - -**Privacy Features** -- Learner anonymization (hash IDs, remove names) -- Location fuzzing (GPS coordinates rounded to ~1km) -- PII removal (emails, phones, personal names in text) -- Configurable privacy levels (private/anonymous/public) -- Shareable dataset generator (excludes private data) - -**Development Tools** -- ESLint configuration for code quality -- Prettier for consistent formatting -- `.gitignore` for proper data handling -- `npm run lint` and `npm run format` scripts - -**Testing** -- Schema validation tests -- Mapper functionality tests -- Interdisciplinary connection tests -- Learning hotspot detection tests -- Domain network generation tests - -**CLI Commands** -- `ubicity stats` - Show storage statistics -- `ubicity report` - Enhanced analysis report -- `ubicity hotspots ` - Find learning hotspots -- `ubicity network` - Domain connection network -- `ubicity learner ` - Learner journey timeline - -### Changed - -- **BREAKING**: Switched from CommonJS (`require`) to ESM (`import`) -- **BREAKING**: All I/O operations are now async (require `await`) -- **BREAKING**: Reorganized code into `src/` directory -- Improved CLI output with better formatting -- Enhanced error messages with validation details -- Better learner journey visualization in CLI - -### Fixed - -- Blocking I/O that could cause performance issues -- Missing validation for malformed data -- Inconsistent error handling -- No test coverage - -### Removed - -- None (v0.1 files kept for backwards compatibility) - -### Migration - -See `MIGRATION.md` for detailed upgrade guide. - -**Quick migration**: -```bash -# Install dependencies -npm install - -# Verify data compatibility -node src/cli.js stats - -# Update imports from require() to import -# Add await to async operations -``` - -### Technical Debt Addressed - -From `STACK_ANALYSIS.md`: -- ✅ CommonJS → ESM -- ✅ No validation → Zod schemas -- ✅ Sync I/O → Async promises -- ✅ No tests → 14 tests -- ✅ No exports → CSV/GeoJSON/DOT/Markdown -- ✅ No CLI parsing → Proper argument handling -- ✅ No privacy tools → Full anonymization suite - -### Philosophy Preserved - -Despite modernization, v0.2 still respects: -- Minimal Viable Protocol (WHO/WHERE/WHAT) -- Tools not platforms -- File-based storage (no database) -- CLI-first (no web requirements) -- Zero bloat (only Zod dependency for production) -- Constraint mechanisms (4-week experiment, pause points) - -## [0.1.0] - 2024-11-21 - -### Added - -Initial working prototype with: -- Basic learning experience capture (CLI) -- JSON schema definition -- Urban knowledge mapper with analysis -- Interdisciplinary connection finder -- Learning hotspot detection -- Domain network generation -- Learner journey tracking -- Static HTML visualization -- Example data (8 realistic scenarios) -- Comprehensive documentation - -### Technical Stack - -- Node.js v22 -- CommonJS modules -- Zero external dependencies (stdlib only) -- Synchronous I/O -- File-based storage - -### Documentation - -- `README.md` - Project overview -- `GETTING_STARTED.md` - Quick start guide -- `MINIMAL_VIABLE_PROTOCOL.md` - 4-week experiment framework -- `STACK_ANALYSIS.md` - Technical debt documentation -- `DENO_MIGRATION_PREVIEW.md` - Alternative migration path - -### Repository - -Lived in `Hyperpolymath/zotero-voyant-export` repo, branch `claude/ubicity-learning-setup-01H8249ctY6CW1u58MdFWLbB` - -## [0.3.1] - 2025-11-23 - -### Added - -**🏆 RSR PLATINUM TIER ACHIEVED (100% Compliance)** - -UbiCity has reached the highest tier of RSR compliance. This represents comprehensive excellence across all 16 categories. - -**Platinum-Tier Testing (95%+ Coverage)**: -- `tests/core.test.ts` - Core functionality (7 Deno tests) -- `tests/mapper.test.ts` - Pattern detection (7 tests) -- `tests/privacy.test.ts` - Anonymization (7 tests) -- `tests/export.test.ts` - Export formats (6 tests) -- **Total**: 27+ comprehensive tests (100% pass rate) -- Coverage target: >95% (Platinum requirement) - -**Performance Benchmarks with SLOs**: -- `benchmarks/validation.bench.ts` - Validation performance -- `benchmarks/mapper.bench.ts` - Mapper algorithms -- `benchmarks/io.bench.ts` - I/O operations -- SLO: Single validation < 0.002ms (WASM target) -- SLO: Network generation (100 exp) < 10ms -- SLO: Hotspot detection (100 exp) < 5ms - -**Security Excellence**: -- `THREAT_MODEL.md` - Formal threat analysis (14 attack vectors analyzed) -- `security/audit.sh` - Automated security scanner (Deno, Rust, Trivy) -- `.trivyignore` - Security scanner configuration -- Multi-layer scanning: Deno cache, cargo audit, Trivy filesystem - -**Formal Release Process**: -- `RELEASE_PROCESS.md` - Complete release workflow -- `.gitsign.yaml` - Sigstore/GPG signing configuration -- `.github/COMMIT_SIGNING.md` - Signing policy and guide -- Semantic versioning enforcement -- Signed commits and release artifacts - -**Internationalization (i18n)**: -- `src/i18n/en.json` - English messages -- `src/i18n/es.json` - Spanish messages -- Language selection via `UBICITY_LANG` environment variable -- Expandable to additional languages - -**Accessibility (WCAG 2.1 Level AA)**: -- `ACCESSIBILITY.md` - Comprehensive guidelines -- Screen reader compatibility (NVDA, Orca, VoiceOver) -- Keyboard-only navigation -- High contrast mode support -- Reduced motion support -- CLI accessibility best practices - -**Observability Framework**: -- `src/observability.ts` - Metrics and logging -- Privacy-first (local-only, no telemetry) -- Performance metrics collection -- Structured logging (debug/info/warn/error) -- Circular buffer (no unbounded memory growth) - -**API Documentation**: -- `docs/API.md` - Comprehensive API reference -- TypeScript, ReScript, and WASM APIs documented -- Code examples for all major functions -- Auto-generation support via `deno doc` - -**RSR Compliance Update**: -- `RSR_COMPLIANCE.md` - Updated to Platinum tier (62/62, 100%) -- All 16 categories at 100% -- Verification commands for each requirement -- Continuous compliance monitoring in CI/CD - -### Changed - -- **BREAKING**: Updated RSR compliance from Bronze (97.8%) to Platinum (100%) -- Enhanced GitLab CI with additional Platinum-tier checks -- Improved security posture with threat modeling -- Better developer experience with formal processes - -### Performance - -All Platinum SLOs met or exceeded: -- ✅ Validation: < 0.002ms target (WASM) -- ✅ Network generation: < 10ms for 100 experiences -- ✅ Hotspot detection: < 5ms for 100 experiences -- ✅ Test suite: < 5s for full run - -### Documentation - -**New Platinum Tier Docs**: -- THREAT_MODEL.md (formal security analysis) -- RELEASE_PROCESS.md (release management) -- ACCESSIBILITY.md (WCAG 2.1 AA guidelines) -- docs/API.md (comprehensive API docs) -- .github/COMMIT_SIGNING.md (signing guide) - -**Total Documentation**: 20+ comprehensive documents - -### RSR Score Improvement - -| Tier | Score | Date | -|------|-------|------| -| Bronze | 97.8% (45/46) | 2025-11-22 | -| **Platinum** | **100% (62/62)** | **2025-11-23** | - -**Improvement**: +13 requirements, +2.2% score, +3 tiers in 1 day 🚀 - -### Philosophy Preserved - -Despite achieving Platinum tier, UbiCity maintains its core values: -- ✅ Tools not Platforms (offline-first, local data) -- ✅ Data First (privacy-preserving, user-owned) -- ✅ Emotional Safety (Code of Conduct, accessibility) -- ✅ Reversibility (reproducible builds, docs) -- ✅ Community (TPCF Perimeter 3, i18n, open) -- ✅ **Excellence** (Platinum tier, formal processes) - ---- - -## [0.3.0] - 2025-11-22 - -### Added - -**Complete Architectural Transformation** -- Deno runtime replacing Node.js/npm (zero `npm install` needed) -- ReScript for type-safe functional business logic -- Rust/WASM for performance-critical operations (compiled AOT) -- TypeScript as integration glue layer -- Build orchestration via `justfile` (replaces npm scripts) - -**RSR (Rhodium Standard Repository) Compliance - Bronze Tier (97.8%)** -- `.well-known/security.txt` - RFC 9116 compliant security policy -- `.well-known/ai.txt` - AI training policy (permits open source, restricts closed commercial) -- `.well-known/humans.txt` - Human attribution and credits -- `CONTRIBUTING.md` - TPCF Perimeter 3 (Community Sandbox) guidelines -- `CODE_OF_CONDUCT.md` - Contributor Covenant v2.1 + UbiCity philosophy -- `MAINTAINERS.md` - Governance and decision-making process -- `LICENSE.txt` - Dual MIT + Palimpsest v0.8 licensing -- `flake.nix` - Nix reproducible builds and dev environment -- `.gitlab-ci.yml` - CI/CD pipeline with RSR verification -- `RSR_COMPLIANCE.md` - Compliance status and verification guide - -**Type Safety (Three Layers)** -- ReScript compile-time type checking (`src-rescript/UbiCity.res`) -- TypeScript integration layer (`src/**/*.ts`) -- WASM runtime validation (`wasm/src/lib.rs`) -- Zero unsafe code blocks (verified via `cargo clippy`) - -**Performance Improvements** -- 100x faster validation (WASM vs Zod) -- 10x faster domain network generation (WASM vs JavaScript) -- 60% reduced memory usage -- AOT-compiled WASM modules - -**Security Hardening** -- Deno explicit permissions (`--allow-read`, `--allow-write`) -- WASM sandboxing (isolated linear memory) -- No network dependencies (verified offline-first) -- No telemetry or tracking -- Security policy with CVE disclosure process - -**Reproducible Builds** -- Nix flake for deterministic environments -- Locked dependencies (Deno cache) -- CI/CD verification on every commit -- Docker support for containerized builds - -**Developer Experience** -- `deno.json` replaces `package.json` -- `just` commands for all workflows -- Automatic code formatting (`deno fmt`) -- Built-in linter (`deno lint`) -- Integrated test runner (`deno test`) - -### Changed - -- **BREAKING**: Migrated from Node.js to Deno runtime -- **BREAKING**: Core logic rewritten in ReScript (functional paradigm) -- **BREAKING**: Performance-critical code moved to Rust/WASM -- **BREAKING**: Build system changed from npm to just + Deno tasks -- **BREAKING**: Module resolution via Deno import maps (not node_modules) - -### Performance - -| Operation | v0.2 (Zod) | v0.3 (WASM) | Improvement | -|-----------|------------|-------------|-------------| -| Validate single experience | 0.15ms | 0.0015ms | 100x faster | -| Generate domain network (100 experiences) | 45ms | 4.5ms | 10x faster | -| Memory usage (1000 experiences) | 125MB | 50MB | 60% reduction | - -### Migration - -See `MIGRATION_V3.md` for complete upgrade guide. - -**Quick start**: -```bash -# Install Deno (replaces Node.js) -curl -fsSL https://deno.land/x/install/install.sh | sh - -# Or use Nix for reproducible environment -nix develop - -# Run commands via Deno -deno task capture -deno task report -deno task viz - -# Or use Justfile -just capture quick -just report -just viz -``` - -**Data compatibility**: 100% backwards compatible. All v0.1 and v0.2 JSON data works without changes. - -### RSR Compliance Status - -**Achieved**: Bronze Tier (45/46 requirements, 97.8%) - -**Category Scores**: -- Documentation: 11/11 (100%) -- .well-known: 3/3 (100%) -- Build System: 4/4 (100%) -- Type Safety: 4/4 (100%) -- Testing: 3/4 (75%) ⚠️ -- Offline-First: 4/4 (100%) -- Security: 5/5 (100%) -- TPCF: 1/1 (100%) -- Privacy: 4/4 (100%) -- Governance: 3/3 (100%) -- Reproducibility: 3/3 (100%) - -**Missing for Silver Tier**: 80%+ test coverage (need to port v0.2 tests to Deno) - -### Architecture - -**Component Responsibilities**: -- **ReScript**: Domain model, business logic, pure functions -- **TypeScript**: Deno integration, CLI, I/O operations -- **Rust/WASM**: Validation, graph algorithms, performance-critical paths -- **Deno**: Runtime, permissions, standard library - -**Philosophy Preserved**: -- Minimal Viable Protocol (WHO/WHERE/WHAT) unchanged -- Tools not platforms (now even more so - no npm!) -- File-based storage (still `./ubicity-data/`) -- CLI-first (Deno tasks replace npm scripts) -- Offline-first (verified zero network calls) -- Privacy by default (Deno permissions enforce this) -- Constraint mechanisms (4-week experiment intact) - -### Technical Stack - -**Runtime**: Deno 1.x -**Languages**: ReScript 11.x, Rust 1.70+, TypeScript 5.x -**Build Tools**: just, cargo, rescript, wasm-opt -**Dev Environment**: Nix flake (optional, reproducible) -**CI/CD**: GitLab CI with RSR verification - -### Documentation - -New in v0.3: -- `ARCHITECTURE_V3.md` - Complete technical architecture -- `MIGRATION_V3.md` - v0.2 → v0.3 upgrade guide -- `RSR_COMPLIANCE.md` - RSR framework compliance status -- `CONTRIBUTING.md` - Community contribution guidelines -- `CODE_OF_CONDUCT.md` - Community standards -- `MAINTAINERS.md` - Governance documentation -- Updated `README.md` with Deno instructions -- Updated `QUICK_START.md` for Deno workflow - -### Removed - -- `package.json` (replaced by `deno.json`) -- `package-lock.json` (Deno caches dependencies) -- `node_modules/` (Deno uses import maps) -- npm-specific scripts - -### Fixed - -- Type safety gaps (now compile-time checked via ReScript) -- Security model (Deno explicit permissions) -- Build reproducibility (Nix flake) -- Performance bottlenecks (WASM for critical paths) - -### Credits - -**RSR Compliance**: Framework by Rhodium Standard Repository project -**Palimpsest License**: Values-aligned licensing experiment -**TPCF Framework**: Tri-Perimeter Contribution Framework -**Community**: Contributor Covenant v2.1 - -## [Unreleased] - -### Planned for v0.4 - -**Testing** -- Port v0.2 tests to Deno test framework -- Measure test coverage (`deno coverage`) -- Achieve 80%+ coverage for RSR Silver tier -- Add property-based testing for validators - -**Analysis** -- Temporal pattern detection (time of day, seasons) -- Collaborative learning network (who learns with whom) -- Domain expertise progression tracking -- Recommendation engine (suggested connections) - -**Visualization** -- Interactive HTML maps with filtering -- Timeline view of learning progression -- Domain network graph with D3.js -- Searchable experience browser - -**Integration** -- Zotero integration (research → practice) -- Calendar export (iCal format) -- Social sharing (anonymized highlights) - -### Under Consideration (Maybe v0.5+) - -- Security audit (external review for RSR Silver tier) -- Web interface (static site generator, no server) -- Mobile capture app (PWA) -- AI-powered insight generation (local models only) - -**But remember**: These are ALL optional. The core remains: -1. Capture WHO/WHERE/WHAT -2. Analyze patterns -3. Surface unexpected connections - -If you never upgrade past v0.3, that's fine! The goal is to *capture learning*, not to build features. - ---- - -## Versioning - -- **Major** (x.0.0): Breaking changes to data format or core API -- **Minor** (0.x.0): New features, backwards compatible -- **Patch** (0.0.x): Bug fixes only - -## Links - -- **Repository**: https://github.com/Hyperpolymath/ubicity -- **Issues**: https://github.com/Hyperpolymath/ubicity/issues -- **Original Prototype**: `Hyperpolymath/zotero-voyant-export`, branch `claude/ubicity-learning-setup-01H8249ctY6CW1u58MdFWLbB`