chore(docs): fix markdownlint warnings across all markdown files

This commit is contained in:
Mike Kell 2026-08-10 00:03:33 -04:00
parent f596ff46cb
commit e23dce3793
11 changed files with 46 additions and 22 deletions

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -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]

View File

@ -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

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -1,11 +1,13 @@
# Kanban & Gantt Multi-Project View Specification
## 1. Multi-Level Kanban Board
- Columns represent task status (acklog, in_progress, eview, completed).
- 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.

View File

@ -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).

View File

@ -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).