diff --git a/.cursor/rules/principles.mdc b/.cursor/rules/principles.mdc index 5b7a4593..991f7895 100644 --- a/.cursor/rules/principles.mdc +++ b/.cursor/rules/principles.mdc @@ -19,29 +19,12 @@ alwaysApply: true • HOW ▸ Abbreviated bullets; see docs/system_principles.md --> -# Principles Snapshot +## Behavioural Principles (micro-summary) -Human Flow & Dignity -- Human-first agency: auto-apply within band; no accept gesture; no expansion. -- Flow & rhythm: micro-corrections; defer heavy work during bursts. -- Low cognitive load: no suggestion lists; subtle underline/highlight; debug opt-in. -- Accessibility: respect reduced motion; SR announces; keyboard-first. +- Human: preserve authorship and momentum; keep the surface calm; accessible by default. +- Safety & trust: caret‑safe; private by default; explain choices simply; fail soft. +- Logic: smallest context; plain outputs; one thing at a time; validate a small band. +- Performance: match the device; ship only what we can test. -Safety, Trust & Integrity -- Caret-safe, non-undoing: never edit at/after caret; band-only; no undo entries. -- Local-first privacy: prefer local; remote off unless opted in; degrade gracefully; no text persistence. -- Explainability: show reasons, tiers, and truncations; toggleable explainers. -- Fail-soft: LM errors → rules-only; single-flight + abort; drop stale. - -Adaptive Intelligence & Execution -- Context-minimal: smallest window; allow control JSON; outputs sanitized & clamped. -- Single-flight orchestration: one active gen per band; abort on input. -- Device-tier progressive: detect capabilities → tune cadence/tokens. -- Testable/observable: gates must pass; logs for merges/aborts/tiers. - -Collaboration & Delivery -- Plan order & Questions: execute tasks in plan order; capture clarifications in `docs/questions.md`. -- Green gates: typecheck/lint/format/test must pass before merge. - -See `docs/system_principles.md` for behaviours and examples. +See `docs/system_principles.md` for links to deeper docs. diff --git a/docs/system_principles.md b/docs/system_principles.md index 66a67ac6..ed9abea0 100644 --- a/docs/system_principles.md +++ b/docs/system_principles.md @@ -22,9 +22,131 @@ Elevate human nature and human–machine input. The system amplifies clarity, rhythm, and agency while remaining safe, private, and explainable. -## Subcategories and Principles +## Behavioural Principles (high-level) -### A) Human Flow & Dignity +These are the agent’s ground rules for how to behave in any task. Each +principle links to deeper docs that hold the technical details. + +### Human + +1. Preserve authorship and momentum + +- Guidance: Keep the person in flow. Apply small, safe fixes without + asking; never change what they’re actively typing. +- Examples: + - While the person types, hold back; when they pause, tidy what was + written without moving the caret. + - If they resume typing, drop any pending idea silently. +- See also: [PRD](../PRD.md), [Caret-safe diff (ADR)](../adr/0002-caret-safe-diff.md), [Band policy](guide/reference/band-policy.md), [Acceptance: caret safety](qa/acceptance/caret_safety.feature) + +2. Keep the surface calm + +- Guidance: No suggestion lists. Use subtle underline/highlight to show + what changed; keep UI quiet. +- Examples: + - Fix a comma and briefly underline it; no popups. + - Show debug only when explicitly opened. +- See also: [PRD](../PRD.md), [Voice & tone](../brand/specs/voice-tone.md), [Config flags](guide/reference/config-flags.md), [Web demo details](guide/how-to/web-demo-details.md) + +3. Accessible by default + +- Guidance: Respect reduced motion and assistive tech; never rely on + color or animation alone. +- Examples: + - Replace animations with static highlights if the system asks for + less motion. + - Announce state changes using OS-standard phrasing. +- See also: [A11y checklist](a11y/wcag-checklist.md), [PRD](../PRD.md) + +### Safety & Trust + +4. Caret-safe, never risky + +- Guidance: Only touch a small neighborhood behind the caret; never + write at/after the caret. +- Examples: + - Correct a misspelling a few words back; do not extend text forward. + - If a change would cross the caret, skip it. +- See also: [Caret-safe diff (ADR)](../adr/0002-caret-safe-diff.md), [Band policy](guide/reference/band-policy.md), [Acceptance: caret safety](qa/acceptance/caret_safety.feature) + +5. Private by default + +- Guidance: Prefer local. Remote is opt‑in per session. Do not persist + user text. +- Examples: + - If local assets are missing, operate in safe rules‑only mode and + nudge setup, not cloud fallback. + - Clear the opt‑in when the session ends. +- See also: [PRD](../PRD.md), [LM behavior](guide/reference/lm-behavior.md), [Config flags](guide/reference/config-flags.md), [Acceptance: local LM](qa/acceptance/local_lm_integration.feature) + +6. Explain choices simply + +- Guidance: When asked, say what changed and why, without exposing user + content. +- Examples: + - “Shortened to fit the safe band.” + - “Dropped result because you kept typing.” +- See also: [Web demo details](guide/how-to/web-demo-details.md), [Implementation](../implementation.md) + +7. Fail soft, never block + +- Guidance: On any error, step down to a safe mode and keep the person + typing. +- Examples: + - Timeouts cancel work and defer until the next pause. + - No GPU? Use a simpler path, just slower—not broken. +- See also: [Architecture constraints (ADR)](../adr/0003-architecture-constraints.md), [Acceptance: streamed diffusion](qa/acceptance/streamed_diffusion.feature) + +### Logic & Clarity + +8. Smallest context; plain outputs + +- Guidance: Use only what’s needed; return clear text, no boilerplate. +- Examples: + - Consider nearby text rather than the whole document. + - Strip any labels or wrappers from model output. +- See also: [LM behavior](guide/reference/lm-behavior.md), [Injector](guide/reference/injector.md) + +9. One thing at a time + +- Guidance: Don’t juggle. If new input arrives, stop what you were + doing. +- Examples: + - Abort a running idea as soon as a new key is pressed. + - Ignore late results from an older state. +- See also: [Architecture: containers](architecture/C2-containers.md), [Implementation](../implementation.md) + +10. Check a small neighborhood (validation band) + +- Guidance: Validate and correct a short span around the cursor—not the + world. +- Examples: + - Fix “teh quick” to “the quick,” but don’t rewrite the sentence. + - Leave longer rephrasing to deliberate user actions. +- See also: [Band policy](guide/reference/band-policy.md), [Caret-safe diff (ADR)](../adr/0002-caret-safe-diff.md) + +### Performance & Reliability + +11. Meet the device where it is + +- Guidance: Use effort that suits the hardware; prioritize responsiveness. +- Examples: + - On fast devices, respond more quickly; on slower ones, take lighter + steps. + - Warm up once; avoid stutter during typing. +- See also: [Config flags](guide/reference/config-flags.md), [Web demo details](guide/how-to/web-demo-details.md) + +12. Ship only what we can test + +- Guidance: Behaviour must be observable and verifiable. +- Examples: + - Add or update tests when rules change. + - Keep acceptance criteria green before merging. +- See also: [QA index](qa/README.md), [Acceptance suite](qa/acceptance), [Implementation](../implementation.md) + +## Appendix: Technical mapping + +### A) Human Flow & Dignity (detailed) 1. Human-first agency @@ -76,7 +198,7 @@ explainable. - Use OS-standard phrasing in screen reader announcements via `liveRegion`; ensure all actions are reachable by keyboard. -### B) Safety, Trust & Integrity +### B) Safety, Trust & Integrity (detailed) 5. Caret-safe, non-undoing edits @@ -104,7 +226,7 @@ explainable. - Behaviour: Make decisions legible. Log what was proposed, why it was accepted/rejected, and the current device tier. Capture uncertainties - in `docs/questions.md` and proceed on safe defaults. + in `docs/questionnaire/questions.md` and proceed on safe defaults. - Examples: - In DebugPanel, show: model tier, tokens requested, band size, and reason codes (e.g., "caret-entered", "stale-result"); avoid showing raw user text. @@ -121,7 +243,7 @@ explainable. - If WebGPU is unavailable, switch to WASM SIMD/threads and reduce max tokens per call. -### C) Adaptive Intelligence & Execution +### C) Adaptive Intelligence & Execution (detailed) 9. Context-grounded minimality