From e23dce3793e6aa153682c1829d6c2203ba8645e4 Mon Sep 17 00:00:00 2001 From: Mike Kell Date: Mon, 10 Aug 2026 00:03:33 -0400 Subject: [PATCH] chore(docs): fix markdownlint warnings across all markdown files --- DECISION_LOG.md | 1 - docs/ARCHITECTURE/02-security-and-crypto.md | 3 +++ docs/ARCHITECTURE/03-crdt-sync-protocol.md | 3 +++ docs/ARCHITECTURE/ADR/0000-adr-template.md | 4 ++++ .../ADR/0002-crypto-argon2id-keychain.md | 16 ++++++++----- docs/TASKS/phase_1_storage_and_crdt.md | 2 +- docs/UI_UX/01-eisenhower-matrix.md | 7 ++++-- docs/UI_UX/02-calendar-timeblocking.md | 4 +++- docs/UI_UX/03-kanban-gantt-views.md | 24 ++++++++++--------- docs/WORKFLOWS/01-master-user-story.md | 1 + docs/WORKFLOWS/02-ingestion-pipeline.md | 3 +++ 11 files changed, 46 insertions(+), 22 deletions(-) diff --git a/DECISION_LOG.md b/DECISION_LOG.md index ebdfaa9..7c6c13e 100644 --- a/DECISION_LOG.md +++ b/DECISION_LOG.md @@ -16,4 +16,3 @@ - OS keychain abstracted via `keyring` crate v3 (Windows Credential Manager / DPAPI, Linux SecretService / libsecret). Android keychain is excluded (`cfg(not(target_os = "android"))`) and will be handled by Flutter KeyStore bridge in Task 1.5. - Raw key material is Base64-encoded before credential-store insertion for UTF-8 backend compatibility. - Inline Base64 encode/decode helpers avoid adding an external Base64 dependency. - diff --git a/docs/ARCHITECTURE/02-security-and-crypto.md b/docs/ARCHITECTURE/02-security-and-crypto.md index 90b30ca..add7c25 100644 --- a/docs/ARCHITECTURE/02-security-and-crypto.md +++ b/docs/ARCHITECTURE/02-security-and-crypto.md @@ -1,6 +1,7 @@ # Security & Cryptography Specification ## 1. Master Key Derivation & Credential Management + - **Key Derivation Function**: Argon2id - Memory: 64 MB (65536 KiB) - Time Cost / Iterations: 3 @@ -12,12 +13,14 @@ - **Android**: Generated inside Android KeyStore backed by Hardware-backed Trusted Execution Environment (TEE) / StrongBox. ## 2. Local Database Encryption + - **Engine**: SQLCipher 4.x - **Cipher Algorithm**: AES-256-CBC - **Key Derivation**: PBKDF2-HMAC-SHA512 (256,000 iterations default for SQLCipher 4). - **Page Authentication**: HMAC-SHA512 per page. ## 3. P2P Mesh Network Encryption + - **Transport Security Protocol**: Noise Protocol Framework (Noise_XK_25519_ChaChaPoly_BLAKE2s). - **Authentication**: Pre-shared 256-bit **Swarm Key** combined with Ed25519 node identity keys. - **Peer Exchange Cipher**: Ephemeral Diffie-Hellman (X25519) key exchange + ChaCha20-Poly1305 AEAD payload ciphering. diff --git a/docs/ARCHITECTURE/03-crdt-sync-protocol.md b/docs/ARCHITECTURE/03-crdt-sync-protocol.md index ef1b81b..ac1a21e 100644 --- a/docs/ARCHITECTURE/03-crdt-sync-protocol.md +++ b/docs/ARCHITECTURE/03-crdt-sync-protocol.md @@ -1,10 +1,12 @@ # CRDT Synchronization Protocol Specification ## 1. Core Synchronization Engine + - **Framework**: Automerge (Rust Crate) - **Clock Specification**: Hybrid Logical Clocks (HLC) combining physical system time with explicit logical sequence counters to prevent clock-skew anomalies across cross-platform endpoints. ## 2. Register Models & Conflict Resolution + - **Task & Note Primitive Fields**: - Properties (Title, Status, Priority Rating, Markdown Body) utilize Last-Write-Wins Element-Set (LWW-Element-Set) registers. - Conflicts resolve deterministically based on HLC timestamps (hlc_timestamp). @@ -12,6 +14,7 @@ - Sequence Ordering uses Fractional Indexing combined with Tree-CRDT rules to eliminate circular references when moving projects offline. ## 3. Delta Exchange & Wire Protocol + - **Transport Layer**: libp2p over QUIC with direct UDP transport. - **Delta Sync Workflow**: 1. Connection established via Noise XK handshake. diff --git a/docs/ARCHITECTURE/ADR/0000-adr-template.md b/docs/ARCHITECTURE/ADR/0000-adr-template.md index 44feec7..cc41786 100644 --- a/docs/ARCHITECTURE/ADR/0000-adr-template.md +++ b/docs/ARCHITECTURE/ADR/0000-adr-template.md @@ -5,15 +5,19 @@ * **Deciders**: Michael Kell ## Context & Problem Statement + [Describe the technical context and what decision needs to be made.] ## Options Considered + 1. [Option 1] 2. [Option 2] ## Decision Outcome + Chosen Option: [Selected Option] because [justification]. ## Consequences & Trade-offs + * **Positive**: [Benefit] * **Negative**: [Drawback/Risk] diff --git a/docs/ARCHITECTURE/ADR/0002-crypto-argon2id-keychain.md b/docs/ARCHITECTURE/ADR/0002-crypto-argon2id-keychain.md index c87f9e9..61019b3 100644 --- a/docs/ARCHITECTURE/ADR/0002-crypto-argon2id-keychain.md +++ b/docs/ARCHITECTURE/ADR/0002-crypto-argon2id-keychain.md @@ -7,6 +7,7 @@ ## Context & Problem Statement Task 1.2 requires implementing a `chronogrid_crypto` crate that provides: + 1. A master-key derivation function using Argon2id with parameters mandated by `docs/ARCHITECTURE/02-security-and-crypto.md`. 2. Cross-platform OS keychain bindings for secure credential persistence (Windows, Linux). Android is deferred to the Flutter KeyStore bridge. @@ -17,20 +18,23 @@ Task 1.2 requires implementing a `chronogrid_crypto` crate that provides: 3. **Use `ring` or `sodiumoxide`** — neither provides Argon2id natively; would still need the `argon2` crate. For keychain: + 1. **Direct Win32 / libsecret FFI** — full control, but significant per-platform maintenance burden. 2. **`keyring` crate** — abstracts Windows Credential Manager, Linux SecretService, and macOS Keychain behind a single API. ## Decision Outcome **Chosen Options:** -- `argon2` crate v0.5 (RustCrypto) for KDF — spec-compliant, zero-copy output, and widely audited. -- `keyring` crate v3 for cross-platform OS keychain — minimal code, covers Windows + Linux targets. Android is excluded via `cfg(not(target_os = "android"))` and will be handled by the Flutter KeyStore bridge. + +* `argon2` crate v0.5 (RustCrypto) for KDF — spec-compliant, zero-copy output, and widely audited. +* `keyring` crate v3 for cross-platform OS keychain — minimal code, covers Windows + Linux targets. Android is excluded via `cfg(not(target_os = "android"))` and will be handled by the Flutter KeyStore bridge. **Key design choices:** -- Argon2id parameters: memory = 65 536 KiB (64 MiB), time_cost = 3, parallelism = 4, salt = 16 bytes, output = 32 bytes. -- `DerivedKey` struct wraps key + salt and implements `Zeroize + Drop` for automatic memory scrubbing. -- `Debug` impl on `DerivedKey` redacts key material to prevent accidental log leaks. -- Raw bytes are Base64-encoded before keychain insertion for UTF-8 credential backend compatibility, using inline encode/decode helpers (no extra dependency). + +* Argon2id parameters: memory = 65 536 KiB (64 MiB), time_cost = 3, parallelism = 4, salt = 16 bytes, output = 32 bytes. +* `DerivedKey` struct wraps key + salt and implements `Zeroize + Drop` for automatic memory scrubbing. +* `Debug` impl on `DerivedKey` redacts key material to prevent accidental log leaks. +* Raw bytes are Base64-encoded before keychain insertion for UTF-8 credential backend compatibility, using inline encode/decode helpers (no extra dependency). ## Consequences & Trade-offs diff --git a/docs/TASKS/phase_1_storage_and_crdt.md b/docs/TASKS/phase_1_storage_and_crdt.md index bf87387..9976c83 100644 --- a/docs/TASKS/phase_1_storage_and_crdt.md +++ b/docs/TASKS/phase_1_storage_and_crdt.md @@ -6,4 +6,4 @@ - [x] **Task 1.2**: Implement chronogrid_crypto crate with Argon2id master key derivation and OS keychain bindings. - [ ] **Task 1.3**: Implement chronogrid_core database initializers using SQLCipher 4.x matching docs/API_CONTRACTS/schema.sql. - [ ] **Task 1.4**: Integrate Automerge Rust crate into chronogrid_core for task and note CRDT register mutations. -- [ ] **Task 1.5**: Generate lutter_rust_bridge FFI bindings bridging Rust storage methods to Dart. +- [ ] **Task 1.5**: Generate lutter_rust_bridge FFI bindings bridging Rust storage methods to Dart. diff --git a/docs/UI_UX/01-eisenhower-matrix.md b/docs/UI_UX/01-eisenhower-matrix.md index 48144f8..5473633 100644 --- a/docs/UI_UX/01-eisenhower-matrix.md +++ b/docs/UI_UX/01-eisenhower-matrix.md @@ -1,16 +1,19 @@ # Eisenhower Priority Matrix View Specification ## 1. Urgency-Importance Scoring Formula + Tasks auto-calculate an Urgency-Importance Vector Score ($) executed locally inside Rust: -S = (W_i * P_user) + (W_u * f(Due_Date - t_current)) + (W_a * Age) +`S = (W_i * P_user) + (W_u * f(Due_Date - t_current)) + (W_a * Age)` Where: + - P_user: User-assigned priority coefficient (0.0 to 1.0). -- (Δt): Proximity decay function yielding exponential values as due dates approach. +- (Δt): Proximity decay function yielding exponential values as due dates approach. - W_i, W_u, W_a: Configurable weighting coefficients for importance, urgency, and age accumulation. ## 2. Quadrant Assignment Mapping + - **Quadrant I (Do First - Urgent & Important)**: Score >= Threshold_High AND Due_Date <= 48 Hours. - **Quadrant II (Schedule - Not Urgent & Important)**: Score >= Threshold_High AND (Due_Date > 48 Hours OR Due_Date IS NULL). - **Quadrant III (Delegate/Automate - Urgent & Not Important)**: Score < Threshold_High AND Due_Date <= 48 Hours. diff --git a/docs/UI_UX/02-calendar-timeblocking.md b/docs/UI_UX/02-calendar-timeblocking.md index afeb822..4e63037 100644 --- a/docs/UI_UX/02-calendar-timeblocking.md +++ b/docs/UI_UX/02-calendar-timeblocking.md @@ -1,9 +1,11 @@ # Calendar & Time-Blocking Grid Specification ## 1. Display Interface + - Multi-day, Weekly, and Monthly time-blocking grids rendered via Flutter custom painter. -- Drag-and-drop task placement: Dragging an unscheduled task onto the grid automatically updates its due_date timestamp and reserves a dedicated block based on its stimated_duration. +- Drag-and-drop task placement: Dragging an unscheduled task onto the grid automatically updates its due_date timestamp and reserves a dedicated block based on its stimated_duration. ## 2. Local CalDAV Bridge Protocol + - **Local Endpoint**: Embedded HTTPS/CalDAV service running locally on 127.0.0.1:4242. - **Interoperability**: Allows native OS calendar tools (Outlook, Thunderbird, Android DAVx⁵) to read scheduled task blocks directly as standard calendar events without sending data to external cloud servers. diff --git a/docs/UI_UX/03-kanban-gantt-views.md b/docs/UI_UX/03-kanban-gantt-views.md index d7ff3e8..0c3f91c 100644 --- a/docs/UI_UX/03-kanban-gantt-views.md +++ b/docs/UI_UX/03-kanban-gantt-views.md @@ -1,11 +1,13 @@ -# Kanban & Gantt Multi-Project View Specification - -## 1. Multi-Level Kanban Board -- Columns represent task status (acklog, in_progress, eview, completed). -- Horizontal swimlanes group tasks by -amespace_id or project_id. -- Dragging a card between columns updates its status field, triggering a CRDT state emission across active peers. - -## 2. Interactive Gantt Timeline -- Visualizes project milestones, task dependencies, and critical path progression. -- Supports fractional sub-project rendering, allowing infinite sub-task nesting. +# Kanban & Gantt Multi-Project View Specification + +## 1. Multi-Level Kanban Board + +- Columns represent task status (acklog, in_progress, eview, completed). +- Horizontal swimlanes group tasks by +amespace_id or project_id. +- Dragging a card between columns updates its status field, triggering a CRDT state emission across active peers. + +## 2. Interactive Gantt Timeline + +- Visualizes project milestones, task dependencies, and critical path progression. +- Supports fractional sub-project rendering, allowing infinite sub-task nesting. diff --git a/docs/WORKFLOWS/01-master-user-story.md b/docs/WORKFLOWS/01-master-user-story.md index 8270cce..35cdd47 100644 --- a/docs/WORKFLOWS/01-master-user-story.md +++ b/docs/WORKFLOWS/01-master-user-story.md @@ -1,6 +1,7 @@ # Master User Story: Distributed, Local-First Productivity Engine Refer to Master User Story specification for detailed acceptance criteria regarding: + 1. Multi-domain IMAP ingestion and local file watchers. 2. Serverless P2P CRDT sync across Windows, Linux, Android, and Headless nodes. 3. Multi-view display execution (Eisenhower Matrix, Time-Blocking Calendar, Kanban, Notes). diff --git a/docs/WORKFLOWS/02-ingestion-pipeline.md b/docs/WORKFLOWS/02-ingestion-pipeline.md index 14faada..ab315d2 100644 --- a/docs/WORKFLOWS/02-ingestion-pipeline.md +++ b/docs/WORKFLOWS/02-ingestion-pipeline.md @@ -1,16 +1,19 @@ # Ingestion & Local Automation Pipeline ## 1. Direct TLS IMAP Engine + - Embedded within crates/chronogrid_core (Rust native). - Connects directly over TLS to user-configured mailboxes (Personal Gmail, M365 Exchange, Custom IMAP). - Polls for flagged emails or direct forwards to internal local parse addresses. - Extracts message body to Markdown, preserves message thread headers (In-Reply-To, Message-ID), and creates linked tasks. ## 2. Native Quick Jots & Trigger Integrations + - **Windows / Linux**: System-wide global hotkey listener invokes a lightweight FFI command overlay. - **Android**: Home-screen widget and Share-Intent listener push text, links, or audio payloads directly to the local ingestion buffer. ## 3. Embedded AI Processing Architecture + - **Inference Engine**: Embedded ONNX Runtime / local LLM socket (Ollama). - **Parsing Pipelines**: 1. **Namespace Classifier**: Determines destination space (Personal, Engineering, Creations).